Ruby Daemons Documentation

If you want to run a specific block of Ruby code in the background rather than an external file, use Daemons.run_proc('name.rb'). This allows you to include the logic directly within your control script while still providing the same start/stop/restart/run/status CLI interface as the file-based wrapper.

# myproc_control.rb
require 'daemons'

Daemons.run_proc('myproc.rb') do
  loop do
    sleep(5)
  end
end

A Pid-File stores the process identification number (PID) of a running daemon, allowing other programs to send signals (like TERM to stop the process).

Naming Convention

• If only one instance is allowed: <scriptname>.pid
• If multiple instances are allowed: <scriptname>_num<number>.pid (where <number> is an integer).
• The default delimiter used is _num.

Storage Modes

When configuring Daemons, you can choose where these files reside using the :dir_mode option:

1. :script: A directory relative to the script being daemonized.
2. :normal: A directory specified by the :dir option.
3. :system: The preconfigured /var/run directory.

When a process is daemonized by the Daemons library, the following technical steps occur:

1. Forking: Forks a child process and exits the parent.
2. Session Leadership: Becomes a session leader to detach from the controlling terminal.
3. Double Fork: Forks a second child and exits the first child to prevent re-acquiring a controlling terminal.
4. Working Directory: Changes the current working directory to /.
5. Umask: Clears the file creation mask (sets umask to 0000).
6. File Descriptors: Closes file descriptors and reopens $stdout and $stderr to point to a logfile if possible.

Consequences for your code:

• The current directory is always /.
• You cannot receive input from the console (e.g., gets will not work).
• You cannot output to the console via puts or print unless you have configured log redirection.

The Daemons::Application#start method behaves differently depending on the :mode option provided in the configuration:

• :none: Used to daemonize the currently running process (via Daemons.daemonize).
• :exec: Uses Kernel.exec to replace the current process with the configured script. Environment variable DAEMONS_ARGV is set to the controller arguments.
• :load: Loads the configured script into the current Ruby process. Environment variables DAEMONS_ARGV and ARGV are adjusted to match the application's arguments.
• :proc: Runs a specific Ruby proc (provided via the :proc option) as a daemon. This is useful for running in-memory logic without a separate script file.

Note: If the :ontop option is set, the application runs in the foreground (simulated mode) instead of daemonizing.

Daemons::SyslogIO supports two buffering modes controlled by the sync attribute:

• Line Buffered (Default): When sync is false, output is buffered and flushed whenever a newline (\n) is encountered. This is generally optimal for syslog to ensure complete log lines.
• Synchronous IO: When sync is true, output is written immediately via syswrite, bypassing the internal buffer.

You can manually trigger a flush of any buffered data using the flush method.

syslog_io = Daemons::SyslogIO.new("myapp")

# Enable synchronous mode
syslog_io.sync = true

# Or use line buffering (default)
syslog_io.sync = false

# Manually flush buffer
syslog_io.flush

By default, ruby control_script.rb status shows if the daemon is running and its PID. You can provide a custom status message by passing a :show_status_callback key in the options hash to Daemons.run. The callback receives an app object which provides access to the PID and other metadata.

def custom_show_status(app)
  # Display the default status information
  app.default_show_status

  puts "PS information"
  system("ps -p #{app.pid.pid.to_s}")
end

Daemons.run('myserver.rb', { show_status_callback: :custom_show_status })

To turn the currently executing Ruby process into a daemon (without the ability to be controlled via start/stop CLI commands), call Daemons.daemonize. This is typically used after performing initial application setup/initialization while still in the foreground.

require 'daemons'

# Perform foreground initialization
init()

# Become a daemon
Daemons.daemonize

# Enter the main loop
loop do
  # server logic
end

You can spawn and manage multiple daemon tasks directly from within a running Ruby application using Daemons.call.

• Use Daemons.call for a single daemon task. It returns a task object that can be used to control the process (e.g., task.stop).
• Use Daemons.call(:multiple => true) to spawn multiple daemon tasks.

require 'daemons'

task1 = Daemons.call(:multiple => true) do
  loop do
    # task logic
    sleep(5)
  end
end

task2 = Daemons.call do
  loop do
    # task logic
    sleep(5)
  end
end

# Control the tasks
task1.stop
task2.stop

You can control how Daemons::Application handles process termination and signal sequences.

Signal Sequences

The :signals_and_waits option accepts a string formatted as SIGNAL:WAIT|SIGNAL:WAIT. This defines the sequence of signals sent during a stop operation and how long to wait after each.

Example format: TERM:10|KILL:5 (Send TERM, wait 10s, then send KILL, wait 5s).

Exit Behavior

• :hard_exit: If set to true, the application will use exit! to terminate, preventing at_exit handlers from running. Use this carefully as it may prevent PID file cleanup.
• :backtrace: If set to true, the application will attempt to write an exception log if it exits due to an error (provided it is not in :ontop mode and didn't exit via SIGTERM).

The Daemons::Reporter accepts an options hash in its constructor. To silence all status and system messages, use the :shush option.

• options[:shush] = true: Disables all output via output_message and prevents $stdout.sync = true from being set.

# To suppress all output:
reporter = Daemons::Reporter.new(shush: true)