module Baal::OptionalOptions

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

Constants

OPTIONAL_OPTS

All optional options

VALID_POLICIES
VALID_SCHEDULE_CLASSES

Public Instance Methods

background() click to toggle source
# File lib/baal/optional_options.rb, line 177
def background
  @commands_and_opts.push OPTIONAL_OPTS[:background]
  self
end
Also aliased as: in_background
change_to_gid(group_name_or_gid)
Alias for: group
change_to_group(group_name_or_gid)
Alias for: group
change_to_group_name(group_name_or_gid)
Alias for: group
change_to_uid(username_or_uid, group_or_gid = nil)
Alias for: chuid
change_to_user(username_or_uid, group_or_gid = nil)
Alias for: chuid
chdir(path) click to toggle source

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.

# 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) click to toggle source

Change directories and chroot to root before starting the process.

@param new_root_dir [String] path to chroot to

NOTE: the pid_file is written after the chroot

# 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) click to toggle source

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

@param username_or_uid [String, Integer, Symbol] username or uid to change

to.

@param group_or_gid [String, Integer, Symbol] group name or group id to

change to.

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.
# 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
Also aliased as: change_to_user, change_to_uid
gid(group_name_or_gid)
Alias for: group
group(group_name_or_gid) click to toggle source

Change to a group or group id before starting the process

@param group_name_or_gid [String, Integer, Symbol] the group name or group

id to be changed to
# 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
group_name(group_name_or_gid)
Alias for: group
in_background()
Alias for: background
incr_nice_level(incr)
Alias for: nice_level
io_sched(sched_class, priority = nil) click to toggle source

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.

@param sched_class [String, Symbol] the io scheduler class.

Supported values: :idle, :best-effort, :real-time

@param priority [String, Integer] the process priority.

# 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
Also aliased as: iosched, io_schedule
io_schedule(sched_class, priority = nil)
Alias for: io_sched
iosched(sched_class, priority = nil)
Alias for: io_sched
make_pid_file() click to toggle source

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.
# File lib/baal/optional_options.rb, line 271
def make_pid_file
  @commands_and_opts.push OPTIONAL_OPTS[:make_pid_file]
  self
end
Also aliased as: make_pidfile
make_pidfile()
Alias for: make_pid_file
nice_level(incr) click to toggle source

Alters the priority of the process before starting it.

@param incr [String, Integer] amount to alter the priority level, can be

positive or negative
# File lib/baal/optional_options.rb, line 194
def nice_level(incr)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:nice_level]}=#{incr}"
  self
end
Also aliased as: incr_nice_level
no_close() click to toggle source

Only relevant when using –background

# File lib/baal/optional_options.rb, line 184
def no_close
  @commands_and_opts.push OPTIONAL_OPTS[:no_close]
  self
end
oknodo() click to toggle source

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

# File lib/baal/optional_options.rb, line 120
def oknodo
  @commands_and_opts.push OPTIONAL_OPTS[:oknodo]
  self
end
proc_sched(policy, priority = nil) click to toggle source

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

Default priority is 0 when executed.

@param policy [String, Symbol] the process scheduler policy.

Supported values: :other, :fifo, :rr

@param priority [String, Integer] the process priority

# 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
Also aliased as: procshed, process_schedule
process_schedule(policy, priority = nil)
Alias for: proc_sched
procshed(policy, priority = nil)
Alias for: proc_sched
quiet() click to toggle source

Do not print informational messages; only display error messages

# File lib/baal/optional_options.rb, line 127
def quiet
  @commands_and_opts.push OPTIONAL_OPTS[:quiet]
  self
end
remove_pid_file() click to toggle source

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.

# File lib/baal/optional_options.rb, line 285
def remove_pid_file
  @commands_and_opts.push OPTIONAL_OPTS[:remove_pid_file]
  self
end
Also aliased as: remove_pidfile
remove_pidfile()
Alias for: remove_pid_file
retry(timeout_or_schedule) click to toggle source

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.

@param 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.

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

# 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
Also aliased as: retry_timeout, retry_schedule
retry_schedule(timeout_or_schedule)
Alias for: retry
retry_timeout(timeout_or_schedule)
Alias for: retry
signal(signal = 'TERM') click to toggle source

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

@param signal[String, Symbol] the signal to send

# File lib/baal/optional_options.rb, line 53
def signal(signal = 'TERM')
  @commands_and_opts.push "#{OPTIONAL_OPTS[:signal]}=#{signal}"
  self
end
Also aliased as: with_signal
start_as(path) click to toggle source

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.

@param path [String] path to process to attempt to start as

# File lib/baal/optional_options.rb, line 103
def start_as(path)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:start_as]}=#{path}"
  self
end
Also aliased as: startas
startas(path)
Alias for: start_as
test() click to toggle source

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

# File lib/baal/optional_options.rb, line 112
def test
  @commands_and_opts.push OPTIONAL_OPTS[:test]
  self
end
umask(mask) click to toggle source

Sets the umask of the process before starting it

@param mask [String, Integer] umask value

# File lib/baal/optional_options.rb, line 250
def umask(mask)
  @commands_and_opts.push "#{OPTIONAL_OPTS[:umask]}=#{mask}"
  self
end
verbose() click to toggle source

Print verbose informational messages when executing the script

# File lib/baal/optional_options.rb, line 292
def verbose
  @commands_and_opts.push OPTIONAL_OPTS[:verbose]
  self
end
with_signal(signal = 'TERM')
Alias for: signal