STARTPROC(8)

📦 version 3.14, in opensuse-leap 16.0

✨ STARTPROC(8) ✨

ok so this is the STARTPROC(8) page from The SuSE boot concept — and it's literally the whole "is it running? no? then start it" pipeline bestie 💅

🌸 NAME 🌸

  • Startproc — start processes identified by path name
  • Start_daemon — start processes identified by path name

(yes they're the same thing, start_daemon is just the LSB-flavored twin 🫶)

⭐ SYNOPSIS ⭐

startproc [-fLves] [-x] [[-n ]-<prio>] [-o c<class>,n<data>]
       [-(t|T) <sec>] [-u user] [-g group] [-l log_file|-q|-d]
       [-p pid_file] [-i ignore_file] [-c root] [-(w|W <file list>)]
       /path/to/executable [arguments for executable]

start_daemon [-fLve] [-x] [-n +/-<prio>] [-o c<class>,n<data>] [-u user]
       [-g group] [-l log_file|-q|-d] [-p pid_file] [-i ignore_file]
       [-c root] /path/to/executable [arguments for executable]

🦋 SYNOPSIS LSB 3.1 🦋

start_daemon [-f] [-n +/-<prio>] /path/to/executable [arguments for
       executable]

💜 DESCRIPTION 💜

ok so here's the whole vibe: startproc and the LSB variant start_daemon go check for all the processes of the executable you named, and if they find none, they start it. periodt. 🎀

⚠️ real talk though: startproc is designed to start a daemon — not a kernel thread, and not a program that enables a kernel thread. it's giving "wrong tool for that job" energy, and you don't wanna find out the hard way 💀

With no options at all, startproc hunts for a process using the full path of the corresponding program plus a default pid file (/var/run/<basename>.pid) — those two together identify the executable out from the /proc file system (see proc(5)). And it only falls back to the base name (/proc/<pid>/stat) to identify the running program if the inode number (/proc/<pid>/exe) and the full name are unavailable (/proc/<pid>/cmdline), or if the executable straight up changes its zeroth argument 😭

The extra-sparkle functionality comes from -p (this used to be option -f, but it changed due to the LSB specification, iykyk). If you pass it, startproc tries to check against the pid read from that file instead of the default pid file (/var/run/<basename>.pid). The pid read from the file gets compared against the pids of possible running processes that use the specified executable. And to avoid confusion with stale pid files, a not-up-to-date pid is just… ignored 🙈

So you can have two different sessions of one binary program? yeah — option -i ignore_file lets you specify a pid file whose pid number is used to ignore all processes of the corresponding process session. iconic behavior honestly 👑

And option -v makes startproc print out verbose diagnostics, because sometimes you just need the tea ☕

Now the thing about start_daemon: it does not support -(t|T) <sec> or -(w|W <file list>) for waiting for success, and it doesn't do -s for a new session — because this variant doesn't fork to start the executable. no fork, no drama, no those flags 💅

🔥 REQUIRED 🔥

  • /path/to/executable — specifies the executable by its full path name, and this argument is always required, no exceptions bestie. Everything that follows this path is considered options for the executable being launched. Want more info? hit up the respective manpage(s) 🌈

✨ OPTIONS ✨

  • [-n ]+/-<prio> — set the nice level for the process. If you use it, this option should always be the first in the command line, don't fight it. The nice level <prio> may be specified in the range between -20 and +20. And heads up: only root is allowed to set negative nice values 🔐
  • -o c<class>,n<data> — set the io scheduling class and priority. If used, this option requires the class identifier c and the class number to use: 0 for none, 1 for realtime, 2 for best-effort, 3 for idle. The scheduling class data can be appended with the identifier n. This only has an effect if the chosen class accepts an argument. For the classes realtime and best-effort, 0 upto 7 are valid data numbers — lower number = higher priority, so don't come for the small numbers ⚡
  • -e — bequeath only a minimal set of environment variables to the new process: HOME, PATH, SHELL, LISTEN_PID, LISTEN_FDS, RUNLEVEL, and PREVLEVEL. travel light 🎒
  • -p pid_file — (former option -f, changed due to the LSB specification.) Use an alternate pid file instead of the default (/var/run/<basename>.pid). The pid read from this file is being matched against the pid of running processes that have an executable with the specified path. In order to avoid confusion with stale pid files, a not up-to-date pid will be ignored. Obviously this option does not work if option -f is specified 🚫
  • -i ignore_file — the pid found in this file is used as session id of the same binary program, which should be ignored by startproc. Obviously this option does not work if option -f is specified 🚫
  • -f — this option is required by the Linux Standard Base Specification (LSB). With this option the start of a process is forced. no thoughts, just force 😤
  • -g group — sets the group ID of the process to gid.
  • -l log_file — redirect the process standard output and standard error to the file log_file. bye bye terminal spam 🫶
  • -L — this option causes symlinks to be followed, as the like-named option in ls(1). Note: for the file name the original name of the program is used instead of the name of the symbolic link 🔗
  • -c root — change root directory to root. Services which have been started with this option can only be checked by checkproc(8) and signaled by killproc(8) if checkproc(8) and killproc(8) are called with the same option argument for the option -c. consistency is key bestie 🗝️
  • -q — equals to -l /dev/null (supresses output). shhh 🤫
  • -d — let startproc expect that the started service will do a dialog by prompting for, e.g. a passphrase. This option implies a timeout of 15 seconds (-t 15) ⏳
  • -s — starts the process in a new session. The new task is a process group leader and has no controlling tty 👑
  • -t <sec> — the number of seconds to wait after the successful start of a service. This option accepts the number of seconds to wait. You can specify some units after a given number: s for seconds, m for minutes, and h for hours to wait ⏱️
  • -T <sec> — the same as for option -t but wait only on the started process, not on childs forked by the process 👶
  • -w — wait the first started process to terminate before returning. If the parent process of the daemon does not finish, also startproc(8) does not finish. clingy but make it sysadmin 😭
  • -W <file list> — wait on the provided file or list of files separated with colons. If the files will not be created, startproc(8) does not finish 🕰️
  • -u user — sets the user ID of the process to user.
  • -v — verbose output. tell me everything 💬
  • -x — tells startproc as well as start_daemon to use the upto 15 byte long filename name found in /proc/<pid>/stat to be able to identify scripts overwriting their command line 📜

🎀 EXAMPLE 🎀

startproc /usr/sbin/sendmail

starts /usr/sbin/sendmail if no sendmail process is found. If a pid file sendmail.pid exists in /var/run/, then the pid found in this file is used to search the process table for a process with an executable that matches the specified pathname, /usr/sbin/sendmail. If no matching process is found, /usr/sbin/sendmail is launched 🚀

startproc -p /var/myrun/lpd.pid /usr/sbin/lpd

starts /usr/sbin/lpd if there is no process with the pid found in /var/myrun/lpd.pid and no process in the actual process table exists that uses the specified binary. double-checked, double-slay 💅✨

👑 EXIT CODES 👑

The exit codes have the following LSB conform conditions:

  • 0 — Success 🎉
  • 1 — Generic or unspecified error
  • 2 — Invalid or excess argument(s)
  • 4 — Insufficient privilege(s)
  • 5 — Program is not installed
  • 7 — Program is not running

In some error cases, diagnostic output is sent to standard error, or, if standard error is not available, syslogd(8) is being used 📨

💡 NOTE 💡

startproc is a replacement for the Bourne shell function daemon found in the widely used SysVinit package of Miquel van Smoorenburg, <miquels@cistron.nl>. And repeat after me: startproc is not useful to start kernel threads 🙅‍♀️ That should be done by service utilities designed for the purpose to accomplish this task. use the right tool, bestie.

💀 BUGS 💀

ok so the caveats, and there are a few, ngl:

  • Identifying a process based on the executable file and the corresponding inode number only works if the process stays alive during startproc's execution. Processes rewriting their zeroth argument, or shell scripts (the inode number of the shell executable file is not identical to that of the script file), may not be identified by a filename path 😬
  • Startproc does not start a process if there already exists one being in the zombie state. Zombies are processes which arn't alive but listed in the process table to have the exit status ready for the corresponding parent processes. Therefore the parent processes should be check out 🧟
  • Start_daemon is not able to check for exit status of an executable daemon, because after the final execve(3) the start_daemon as an own process does not exit anymore 🫥

🗂️ FILES 🗂️

  • /proc/ — path to the proc file system (see proc(5)).
  • /etc/init.d/ — path to the SuSE boot concept script base directory as required by the Linux Standard Base Specification (LSB) (see init.d(7)).

🌈 SEE ALSO 🌈

checkproc(8), killproc(8), insserv(8), init.d(7), kill(1), skill(1), killall(8), killall5(8), signal(7), proc(5).

go read those too, they're the friend group 🫶

1994-2007 Werner Fink, 1996-2000 SuSE GmbH Nuernberg, Germany. 2007 SuSE LINUX Products GmbH, Nuernberg, Germany.

🧚 AUTHOR 🧚

Werner Fink <werner@suse.de>

and that's the whole page bestie 🎀 this one came from the 3rd Berkeley Distribution, dated Nov 30, 2007, and it's filed under STARTPROC(8) — now go start some daemons, responsibly 💜✨

📦 where this page comes from