| DAEMON(1) | User Commands | DAEMON(1) |
daemon - turns other processes into daemons
usage: daemon [options] [--] [cmd arg...]
options:
-h, --help - Print a help message then exit
-V, --version - Print a version message then exit
-v, --verbose[=level] - Set the verbosity level
-d, --debug[=level] - Set the debugging level
-C, --config=path - Specify the system configuration file
-N, --noconfig - Bypass the system configuration file
-n, --name=name - Guarantee a single named instance
-X, --command="cmd" - Specify the client command as an option
-P, --pidfiles=/dir - Override standard pidfile location
-F, --pidfile=/path - Override standard pidfile name and location
-u, --user=user[:[group]] - Run the client as user[:group]
-R, --chroot=path - Run the client with path as root
-D, --chdir=path - Run the client in directory path
-m, --umask=umask - Run the client with the given umask
-e, --env="var=val" - Set a client environment variable
-i, --inherit - Inherit environment variables
-U, --unsafe - Allow execution of unsafe executable
-S, --safe - Disallow execution of unsafe executable
-c, --core - Allow core file generation
--nocore - Disallow core file generation (default)
-r, --respawn - Respawn the client when it terminates
-a, --acceptable=# - Minimum acceptable client duration (seconds)
-A, --attempts=# - Respawn # times on error before delay
-L, --delay=# - Delay between respawn attempt bursts (seconds)
-M, --limit=# - Maximum number of respawn attempt bursts
--idiot - Idiot mode (trust root with the above)
-f, --foreground - Run the client in the foreground
-p, --pty[=noecho] - Allocate a pseudo terminal for the client
-B, --bind - Stop when the user's last logind session ends
-l, --errlog=spec - Send daemon's error output to syslog or file
-b, --dbglog=spec - Send daemon's debug output to syslog or file
-o, --output=spec - Send client's output to syslog or file
-O, --stdout=spec - Send client's stdout to syslog or file
-E, --stderr=spec - Send client's stderr to syslog or file
--ignore-eof - After SIGCHLD ignore any client output
--read-eof - After SIGCHLD read any client output (default)
--running - Check if a named daemon is running
--restart - Restart a named daemon client
--stop - Terminate a named daemon process
--signal=signame - Send a signal to a named daemon
--list - Print a list of named daemons
daemon(1) turns other processes into daemons. There are many tasks that need to be performed to correctly set up a daemon process. This can be tedious. daemon performs these tasks for other processes.
The preparatory tasks that daemon performs for other processes are:
On BSD systems (except macOS), the system configuration file(s) are /usr/local/etc/daemon.conf and /usr/local/etc/daemon.conf.d/* by default.
On macOS, when installed via macports, the system configuration file(s) are /opt/local/etc/daemon.conf and /opt/local/etc/daemon.conf.d/*.
This can happen when daemon was invoked interactively via the shell builtin exec. When this initial process terminates below, the terminal emulator that invoked the shell also terminates, so daemon need to protect itself from that.
When the client terminates, and the --respawn option wasn't supplied, daemon terminates as well.
As well as the system configuration file, additional configuration files will be read from the directory whose path matches the system configuration file with ".d" appended to it (e.g. /etc/daemon.conf.d). Any file in that directory whose name starts with a dot character (".") is ignored. The same checks as described above apply to these files as well.
On BSD systems (except macOS), the system configuration file(s) are /usr/local/etc/daemon.conf and /usr/local/etc/daemon.conf.d/* by default.
On macOS, when installed via macports, the system configuration file(s) are /opt/local/etc/daemon.conf and /opt/local/etc/daemon.conf.d/*.
The name may only consist of the following characters:
-._abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789
While a named daemon's client process is running, there will also be a separate pidfile to record the process id of the client process. Its filename will be the same as the daemon pidfile's, except that the filename extension will be .clientpid rather than .pid. The only reason that there should be a .pid file, with no .clientpid file, is during the delay between respawn attempts bursts.
daemon --name ftumch
Note: If the client command is specified with the --command option, either in the configuration file, or on the command line, then any additional command line arguments on the daemon command line are appended to the client command that is specified with the --command option.
This option only affects the --name and --list options. Use this option if these standard locations are unacceptable, but make sure that you don't forget where you put your pidfiles. This option is best used in configuration files, or in shell scripts, rather than on an interactive command line.
The pidfile location will be created automatically only if it is within the user's home directory.
The pidfile location will be created automatically only if it is within the user's home directory.
Idiot mode also allows the root user to expand environment variable notation (e.g. $VAR and ${VAR}) in command line option arguments, and in configuration files. By default, internal environment variable expansion is only performed for normal users. Note that this doesn't apply to any such expansion performed earlier by the shell that invokes daemon(1). See the EXPANSION section below for more details.
If the noecho argument is supplied with this option, the client's side of the pseudo terminal will be set to noecho mode. Use this only if there really is a terminal involved and input is being echoed twice.
This option is only available on Linux systems that have either systemd(1) (e.g. Debian) or elogind(8) (e.g. Slackware). On systems with systemd(1), you could instead use a systemd user service, particularly if your user account is not allowed to have user services that linger.
If the --verbose option is supplied, print a message before exiting. If both the named daemon and its client process are running, the output will look like this, showing both process IDs:
daemon: name is running (pid 7455) (clientpid 7457)
If the named daemon is running but its client process is not (there might be a delay between respawn attempt bursts), the output will look like this, showing only the daemon process's ID:
daemon: name is running (pid 7455) (client is not running)
If the named daemon is not running at all, the output will look like this:
daemon: name is not running
This option can only be used with the --name option. Note that the --chroot, --user, --name, --pidfiles and --pidfile (and possibly --config) options must be the same as for the target daemon.
This option can only be used with the --name option. Note that the --chroot, --user, --name, --pidfiles and --pidfile (and possibly --config) options must be the same as for the target daemon.
This option can only be used with the --name option. Note that the --chroot, --user, --name, --pidfiles and --pidfile (and possibly --config) options must be the same as for the target daemon.
The known list of signals are: hup, int, quit, ill, trap, abrt, iot, bus, fpe, kill, usr1, segv, usr2, pipe, alrm, term, stkflt, cld, chld, cont, stop, tstp, ttin, ttou, urg, xcpu, xfsz, vtalrm, prof, winch, poll, io, pwr, sys, emt and info. Not all of them are available on all platforms.
Without the --verbose option, this will only list the names of daemons whose pidfiles are locked, as this implies that the corresponding daemon must still be running. Note that pidfiles for daemons that were not started by daemon(1) might not be locked. An unlocked pidfile might indicate that daemon(1) has died unexpectedly, or it might just be a pidfile for a daemon that was not started by daemon(1). If this might lead to confusion, you might want to consider using a dedicated pidfiles directory for named daemons started by daemon(1), and leave the default pidfiles directories for other daemons that were started independently of daemon(1).
With the --verbose option, the items in the list will look like the output of the --running option with --verbose, but with more detail.
If there are no pidfiles at all, the output will look like this:
No named daemons are running
If a pidfile is locked, and there is a corresponding client pidfile, that indicates that the named daemon and its client are both running, and the output will look like this, showing both process IDs:
name is running (pid ####) (client pid ####)
If a pidfile is locked, but there is no client pidfile, that indicates that the named daemon is running, but its client is not (e.g. during a delay between respawn attempt bursts when the client is failing to start successfully), and the output will look like one of the following three options:
When we can tell that the pidfile is for a process whose executable name is daemon:
name is running (pid ####) (client is not running)
When we can tell that the pidfile is for a process whose executable name is something other than daemon (i.e. is independent of daemon(1)):
name is running (pid ####) (independent)
When it's not possible to determine the name of the executable associated with the pidfile (i.e. On systems other than Linux without a /proc file system):
name is running (pid ####) (client is not running or is independent)
If a pidfile is not locked, and the applicable pidfiles directory is the default, that indicates either that the daemon has unexpectedly terminated, or just that the pidfile is for a daemon that was not started by daemon(1), and the output will look like this:
name is not running (or is independent)
If a pidfile is not locked, and the applicable pidfiles directory is not the default, then it is assumed that all pidfiles are for daemons that were started by daemon(1), and the output will look like this:
name is not running
As with all other programs, a -- argument signifies the end of options. Any options that appear on the command line after -- are part of the client command.
Some simple shell-like expansion is performed internally on the arguments of the command line options with a text argument (but not the options with a numeric argument).
Environment variable notation, such as $VAR or ${VAR}, is expanded. Then user home directory notation, such as ~ or ~user, is expanded. File name expansion (i.e. globbing) is NOT performed internally. Neither are any of your login shell's other wonderful expansions. This is very basic.
This might not be of much use on the command line, since daemon is normally invoked via a shell, which will first perform all of its usual expansions. It might even be undesirable to perform expansion internally after the shell has already done so (e.g. if you refer to any directory names that actually contain the '$' character, or if you use any environment variables whose values contain the '$' character, which is unlikely).
But it can be useful in configuration files. See the FILES section below for more details. It can also be useful when daemon is invoked directly by another program without the use of a shell.
By default, environment variable expansion is not performed for the root user, even if the environment variable was defined in the configuration files. The --idiot option can be used to change this behaviour, and allow the expansion of environment variables for the root user. Home directory notation expansion is performed for all users.
/etc/daemon.conf, /etc/daemon.conf.d/* - system-wide default options
/usr/local/etc/daemon.conf, /usr/local/etc/daemon.conf.d/* - system-wide default options on BSD systems (except macOS).
/opt/local/etc/daemon.conf, /opt/local/etc/daemon.conf.d/* - system-wide default options on macOS when installed via macports.
~/.daemonrc, ~/.daemonrc.d/* - user-specific default options
Each line of the configuration file is either an environment variable definition, or a configuration directive.
Environment variable definitions consist of the variable name, followed immediately by '=' and the value of the variable. They look like they do in shell, except that there is no quoting or other shell syntax. Environment variable values can include simple environment variable notation (e.g. $VAR or ${VAR}), and user home directory notation (e.g. ~ or ~user). These will be expanded internally by daemon. See the EXPANSION section above for more details.
Note that any environment variables that are defined in the configuration file, which are subsequently used explicitly in another environment variable definition or in an option argument, will have these expansions performed multiple times. Avoid environment variables whose values can change again if expansion is performed multiple times.
Example:
PATH=/usr/bin:/usr/sbin:$HOME/bin:~app/bin
PIDFILES=~/.run
Configuration directives consist of a client name (for options that apply to a single client), or '*' (for generic options that apply to all clients), followed by spaces and/or tabs, followed by a comma-separated list of options. Any option arguments must not contain any commas. The commas that separate options can have spaces and tabs before and after them. Option arguments that are text (but not numbers) can include simple environment variable notation (e.g. $VAR or ${VAR}), and user home directory notation (e.g. ~ or ~user). These will be expanded internally by daemon. See the EXPANSION section above for more details.
Blank lines and comments ('#' to end of the line) are ignored. Lines can be continued with a '\' character at the end of the line.
Example:
* errlog=daemon.err,output=local0.err,core
test1 syslog=local0.debug,debug=9,verbose=9,respawn
test2 syslog=local0.debug,debug=9, \
verbose=9,respawn, \
pidfiles=$PIDFILES
The command line options are processed first, to look for a --config option. If no --config option was supplied, the default configuration files, /etc/daemon.conf and /etc/daemon.conf.d/*, are used. On BSD systems (except macOS), the default configuration files are /usr/local/etc/daemon.conf and /usr/local/etc/daemon.conf.d/*. On macOS when installed via macports, the default configuration files are /opt/local/etc/daemon.conf and /opt/local/etc/daemon.conf.d/*. If the user has their own configuration files, ~/.daemonrc and ~/.daemonrc.d/*, they are also used.
If the configuration files contain any generic ('*') entries, their options are applied in order of appearance. If the --name option was supplied, and the configuration files contain any entries for the given name, those options are then applied in order of appearance.
Finally, the command line options are applied again. This ensures that any generic options apply to all clients by default. Client-specific options override generic options. User options override system-wide options. Command line options override everything else.
Note that the configuration files are not opened and read until after any --chroot and/or --user command line options are processed. This means that the configuration file paths and the client's file path must be relative to the --chroot argument. It also means that the configuration files and the client executable must be readable/executable by the user specified by the --user argument. It also means that the --chroot and --user options must not appear in the configuration file. Also note that the --name option must not appear on the right hand side in the configuration file either.
The --errlog, --dbglog, --output, --stdout and --stderr options all take an argument that can be either a syslog destination of the form "facility.priority" or the path to a file. Here are the lists of syslog facilities and priorities:
Facilities: kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, local0, local1, local2, local3, local4, local5, local6, local7. Priorities: emerg, alert, crit, err, warning, notice (on some systems), info, debug.
If the path to a file is supplied instead, bear in mind the fact that daemon(1) changes to the root directory by default, and so the file path should be an absolute path (or relative to the --chroot and/or --chdir option argument). Otherwise, daemon(1) will attempt to create the file relative to its current directory. You might not have permissions to do that, or want to even if you do.
Clients can only be restarted if they were started with the --respawn option. Using --restart on a non-respawning daemon client is equivalent to using --stop. If you try to restart a named daemon, and it stops instead, then it probably wasn't started with the --respawn option.
Clients that are run in the foreground with a pseudo terminal don't respond to job control (i.e. suspending with Control-Z doesn't work). This is because the client belongs to an orphaned process group (it starts in its own process session), so the kernel won't send it SIGSTOP signals. However, if the client is a shell that supports job control, then its subprocesses can be suspended.
In KDE, if you use "exec daemon" (or just "exec" without daemon) in a shell, to run a KDE application, you might find that the KDE application sometimes doesn't run. This problem has only been seen with konsole(1), but it might happen with other KDE applications as well. Capturing the standard error of the KDE application might show something like:
unnamed app(9697): KUniqueApplication: Registering failed! unnamed app(9697): Communication problem with "konsole" , it probably crashed. Error message was: "org.freedesktop.DBus.Error.ServiceUnknown" : " "The name org.kde.konsole was not provided by any .service files"
A workaround seems to be to delay the termination of the initial daemon(1) process by at least 0.4 seconds. To make this happen, set the environment variable DAEMON_INIT_EXIT_DELAY_MSEC to the number of milliseconds by which to delay. For example: DAEMON_INIT_EXIT_DELAY_MSEC=400. Or you could just avoid using exec when starting KDE applications.
On Linux systems that have systemd(1) or elogind(8), you might find that your daemon processes and their client processes are terminated when you logout, even though they are in a different process session, and so should be unaffected. This is because systemd has the ability to terminate all of your processes when you logout. Luckily, this feature is turned off by default in some Linux distributions. However, if it is on, you can turn it off by adding the following line to /etc/systemd/logind.conf (or /etc/elogind/logind.conf):
KillUserProcesses=no
libslack(3), daemon(3), coproc(3), pseudo(3), init(8), inetd(8), fork(2), umask(2), setsid(2), chdir(2), chroot(2), setrlimit(2), setgid(2), setuid(2), setgroups(2), initgroups(3), syslog(3), kill(2), wait(2), systemd-logind(8), elogind(8)
20210304 raf <raf@raf.org>
| 20210304 | daemon-0.8 |