Module: Baal::OptionalOptions

Included in:
Daemon
Defined in:
lib/baal/optional_options.rb

Overview

Optional Options is a container for all methods relating to options that can be added to your start-stop-daemon script, but are not required

Defined Under Namespace

Classes: InvalidPolicyError, InvalidScheduleClassError

Constant Summary collapse

OPTIONAL_OPTS =

All optional options

{
  group: '--group',
  signal: '--signal',
  retry: '--retry',
  start_as: '--startas',
  test: '--test',
  oknodo: '--oknodo',
  quiet: '--quiet',
  chuid: '--chuid',
  chroot: '--chroot',
  chdir: '--chdir',
  background: '--background',
  no_close: '--no-close',
  nice_level: '--nicelevel',
  proc_sched: '--procsched',
  io_sched: '--iosched',
  umask: '--umask',
  make_pid_file: '--make-pidfile',
  remove_pid_file: '--remove-pidfile',
  verbose: '--verbose'
}.freeze
VALID_POLICIES = 
%w(other fifo rr).freeze
VALID_SCHEDULE_CLASSES = 
%w(idle best-effort real-time).freeze

Instance Method Summary collapse

Instance Method Details

#background ⇒ Object Also known as: in_background 



177
178
179
180
 
# File 'lib/baal/optional_options.rb', line 177

def background
  @commands_and_opts.push OPTIONAL_OPTS[:background]
  self
end

#chdir(path) ⇒ Object

Change directories to @path before starting the process.

Chdir is done AFTER the chroot if the OptionalOptions#chroot option is set. When no OptionalOptions#chroot is set, start-stop-daemon will chdir to the root directory before starting the process.



172
173
174
175
 
# File 'lib/baal/optional_options.rb', line 172

def chdir(path)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:chdir]}=#{path}"
  self
end

#chroot(new_root_dir) ⇒ Object

Change directories and chroot to root before starting the process.

NOTE: the pid_file is written after the chroot

Parameters:

  • new_root_dir (String) —

    path to chroot to



161
162
163
164
 
# File 'lib/baal/optional_options.rb', line 161

def chroot(new_root_dir)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:chroot]}=#{new_root_dir}"
  self
end

#chuid(username_or_uid, group_or_gid = nil) ⇒ Object Also known as: change_to_user, change_to_uid

Change to the specified username or uid before starting the process.

NOTE: If a user is specified without a group, the primary GID for that

user is used.

NOTE: Primary and supplemental groups are set as well, even if the

OptionalOptions#group option is not specified. The
OptionalOptions#group option is only groups that the user isn't
normally a member of.

Parameters:

  • username_or_uid (String, Integer, Symbol) —

    username or uid to change to.

  • group_or_gid (String, Integer, Symbol) (defaults to: nil) —

    group name or group id to change to.



147
148
149
150
151
 
# File 'lib/baal/optional_options.rb', line 147

def chuid(username_or_uid, group_or_gid = nil)
  group_or_gid = group_or_gid.nil? ? '' : ":#{group_or_gid}"
  @commands_and_opts.push "#{OPTIONAL_OPTS[:chuid]}=#{username_or_uid}#{group_or_gid}"
  self
end

#group(group_name_or_gid) ⇒ Object Also known as: group_name, gid, change_to_group, change_to_group_name, change_to_gid

Change to a group or group id before starting the process

Parameters:

  • group_name_or_gid (String, Integer, Symbol) —

    the group name or group id to be changed to



38
39
40
41
 
# File 'lib/baal/optional_options.rb', line 38

def group(group_name_or_gid)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:group]}=#{group_name_or_gid}"
  self
end

#io_sched(sched_class, priority = nil) ⇒ Object Also known as: iosched, io_schedule

Alters the io IO scheduler class and priority of the process before starting it.

Default priority is 4, unless the sched_class is :idle, then it’s 7.

Parameters:

  • sched_class (String, Symbol) —

    the io scheduler class. Supported values: :idle, :best-effort, :real-time

  • priority (String, Integer) (defaults to: nil) —

    the process priority.



233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/baal/optional_options.rb', line 233

def io_sched(sched_class, priority = nil)
  puts sched_class
  unless VALID_SCHEDULE_CLASSES.include? sched_class.to_s
    raise InvalidScheduleClassError,
          'Invalid schedule class. Expected: idle, best-effort, real-time'
  end

  priority = priority.nil? ? ' ' : ":#{priority}"
  @commands_and_opts.push "#{OPTIONAL_OPTS[:io_sched]}=#{sched_class}#{priority}"
  self
end

#make_pid_file ⇒ Object Also known as: make_pidfile

Used when starting a program that does not create its own pid file.

Used together with the file specified by the MatchingOptions#pidfile option.

This will place the pid into the file specified by the MatchingOptions#pidfile option, just before executing the process.

NOTE: The file will only be removed if the OptionalOptions#remove_pid_file option is used.

WARNING: Will not work in all cases, such as when the program being

executed  forks from its main process. Because of this, it is
usually only useful when combined with the
OptionalOptions#background option.



271
272
273
274
 
# File 'lib/baal/optional_options.rb', line 271

def make_pid_file
  @commands_and_opts.push OPTIONAL_OPTS[:make_pid_file]
  self
end

#nice_level(incr) ⇒ Object Also known as: incr_nice_level

Alters the priority of the process before starting it.

Parameters:

  • incr (String, Integer) —

    amount to alter the priority level, can be positive or negative



194
195
196
197
 
# File 'lib/baal/optional_options.rb', line 194

def nice_level(incr)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:nice_level]}=#{incr}"
  self
end

#no_close ⇒ Object

Only relevant when using –background



184
185
186
187
 
# File 'lib/baal/optional_options.rb', line 184

def no_close
  @commands_and_opts.push OPTIONAL_OPTS[:no_close]
  self
end

#oknodo ⇒ Object

Return an exit status of 0 instead of 1 if no actions are, or would not be, taken



120
121
122
123
 
# File 'lib/baal/optional_options.rb', line 120

def oknodo
  @commands_and_opts.push OPTIONAL_OPTS[:oknodo]
  self
end

#proc_sched(policy, priority = nil) ⇒ Object Also known as: procshed, process_schedule

Alters the process scheduler class and priority of the process before starting it.

Default priority is 0 when executed.

Parameters:

  • policy (String, Symbol) —

    the process scheduler policy. Supported values: :other, :fifo, :rr

  • priority (String, Integer) (defaults to: nil) —

    the process priority



210
211
212
213
214
215
216
217
218
 
# File 'lib/baal/optional_options.rb', line 210

def proc_sched(policy, priority = nil)
  unless VALID_POLICIES.include? policy.to_s
    raise InvalidPolicyError, 'Invalid policy. Expected: other, fifo, rr'
  end

  priority = priority.nil? ? ' ' : ":#{priority}"
  @commands_and_opts.push "#{OPTIONAL_OPTS[:proc_sched]}=#{policy}#{priority}"
  self
end

#quiet ⇒ Object

Do not print informational messages; only display error messages



127
128
129
130
 
# File 'lib/baal/optional_options.rb', line 127

def quiet
  @commands_and_opts.push OPTIONAL_OPTS[:quiet]
  self
end

#remove_pid_file ⇒ Object Also known as: remove_pidfile

Used when stopping a program that will NOT remove its own pid file.

Used together with the file specified by the MatchingOptions#pidfile option.

This will remove the file specified by the MatchingOptions#pidfile option.



285
286
287
288
 
# File 'lib/baal/optional_options.rb', line 285

def remove_pid_file
  @commands_and_opts.push OPTIONAL_OPTS[:remove_pid_file]
  self
end

#retry(timeout_or_schedule) ⇒ Object Also known as: retry_timeout, retry_schedule

Used with Commands#stop. Specifies that start-stop-daemon is to check whether the process(es) do finish. It will check repeatedly whether any matching processes are running, until none are. If the processes do not exit it will then take futher action as defined by the schedule.

To specify a schedule: a schedule is a list of at least two items
separated by slashes; each item may be any of the following:

  1. signal number or signal name, which means to send that signal
  2. timeout, which means to wait that many seconds for processes to
    exit
  3. forever, which means to repeat the rest of the schedule forever if
    necessary

If the end of the schedule is reached and forever is not specified, then
start-stop-daemon exits with the error status of 2.

WARNING: If a schedule is specified, then any signal specified with
         OptionalOptions#signal is ignored.

TODO: Add better arguments for constructing a schedule

Parameters:

  • timeout_or_schedule (String, Integer) —

    If a timeout (in seconds) is specified, then the following schedule is used:

    signal/timeout/KILL/timeout, where signal is specified with
OptionalOptions#signal.



88
89
90
91
 
# File 'lib/baal/optional_options.rb', line 88

def retry(timeout_or_schedule)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:retry]}=#{timeout_or_schedule}"
  self
end

#signal(signal = 'TERM') ⇒ Object Also known as: with_signal

Used with Commands#stop. Specifies the signal to send to the processes attempting to be stopped.

Parameters:

  • signal (String, Symbol) (defaults to: 'TERM') —

    the signal to send



53
54
55
56
 
# File 'lib/baal/optional_options.rb', line 53

def signal(signal = 'TERM')
  @commands_and_opts.push "#{OPTIONAL_OPTS[:signal]}=#{signal}"
  self
end

#start_as(path) ⇒ Object Also known as: startas

Used with Commands#start.

Starts the process at the specified path. If not added as an option to Commands#start, the path will default to the one provided to MatchhingOptions#exec.

Parameters:

  • path (String) —

    path to process to attempt to start as



103
104
105
106
 
# File 'lib/baal/optional_options.rb', line 103

def start_as(path)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:start_as]}=#{path}"
  self
end

#test ⇒ Object

Print actions that would be taken and set an appropriate return value, but take no action



112
113
114
115
 
# File 'lib/baal/optional_options.rb', line 112

def test
  @commands_and_opts.push OPTIONAL_OPTS[:test]
  self
end

#umask(mask) ⇒ Object

Sets the umask of the process before starting it

Parameters:

  • mask (String, Integer) —

    umask value



250
251
252
253
 
# File 'lib/baal/optional_options.rb', line 250

def umask(mask)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:umask]}=#{mask}"
  self
end

#verbose ⇒ Object

Print verbose informational messages when executing the script



292
293
294
295
 
# File 'lib/baal/optional_options.rb', line 292

def verbose
  @commands_and_opts.push OPTIONAL_OPTS[:verbose]
  self
end