vsrun(8)

Name

vsrun - Start a server process

Synopsis

vsrun [-u user] [-p pidfile] [-r root] [-w directory] [-m monitor-pidfile termination-handler] [-s syslog-prefix] [-d directory keep-duration] -- command

In the most common usage, at least the user and pidfile options are used.

Contents

Description

When starting a server process in the background it is often necessary to take care of several details first, including:

It is often also desirable to take action if such a process dies, such as sending e-mail and/or restarting the server.

Many server programs will take some or all of these steps themselves. However, several of these steps require super-user priviledges. It's best to limit the size of code executed as the super-user. For programs written in languages where control over initialization code may be limited (C++, scripting languages) it may be preferable to instead use a small C program to take care of these issues. This is what vsrun does.

While it's distributed with Vesta for use with its servers, it can be used with other programs as well.

Flags

-u | --user user
User to execute the server process as.
-p | --pidfile pidfile
File to write the server process ID into. If the file exists, it will be overwritten.
-r | --root root
A directory to chroot to.
-w | --work-dir directory
A directory to be set as the working directory before starting the server. Not that if the -r flag is also given, the working directory is changed after the chroot, so directory should be relative to the new root.
-m | --manager monitor-pidfile termination-handler
Specifies that vsrun should stay resident and monitor the server process to see whether it terminates. The process ID of the monitor will be written to monitor-pidfile . If the server dies, termination-handler will be invoked.
-b | --background
Fork and run in the background. If this option is not given, the server process (or the vsrun manager process) will remain in the foreground.
-s | --syslog syslog-prefix
Redirect all standard output/error from vsrun and the server to syslog. This works by executing a separate process with the command "logger -t syslog-prefix". It's assumed that the logger(1) command exists on your system and is on the $PATH environment variable when vsrun is started. (It's normally in /usr/bin.) Note that this option is mutually exclusive with --logdir.
-d | --logdir directory keep-duration
Redirect all standard output/error from vsrun and the server to files in directory. If the directory doesn't exist, it will be created. Output from vsrun (errors or information from the manager) will be written to "vsrun.log", output from the server will be written to "logfile". Older files with these names will be renamed to "vsrun.log.N" and "logfile.N" where N is an integer. Any such files older than the keep-duration will be deleted. The keep duration must be an integer followed by one of the following units: h (hours), d (days), w (weeks), m (months). If no unit is given, defaults to days. Note that this option is mutually exclusive with --syslog.
--
Denotes the end of the options to vsrun. Everything after this option will be taken as the server command to run. (Note that this option is mandatory.)

Manager Behavior

When managing a server process, vsrun will restart the server unless it exits voluntarily. If the server does exit voluntarily, the manager process will simply exit.

If the manager process is sent the SIGHUP signal, it will terminate (with SIGTERM) and restart the server process. This makes it possible to explicitly request that the manager restart the server.

If the manager process is sent the SIGTERM signal, it will terminate the server process (also with SIGTERM) and then exit. This makes it possible to explicitly request that the manager shut down the server.

Note that in the event of either an intentional kill or an intentional restart, the termination handler is not invoked. (The termination handler is really only for an unexpected termination of the server process.)

Termination Handler

The second argument to the -m flag is a command to be invoked in the even that the server process terminates unexpectedly. This should be a single path to an executable file. If you need to do something requiring arguments, create a small shell script for your termination handler.

The following environment variables will be defined when the termination handler is invoked:

VSRUN_SERVER_COMMAND
The command used to start the server.
VSRUN_SERVER_UPTIME
The number of seconds between when the server was started and when it exited
VSRUN_SERVER_EXITED
Set to 1 if the server exited volutarily, 0 otherwise
VSRUN_SERVER_EXITSTATUS
Set to the exit status of the server process if it exited volutarily.
VSRUN_SERVER_TERMSIG
Set of the number of the signal (e.g. 11 for segfault, 6 for abort) that caused the child process to terminate, if any. (See signal(7) for a listing of numeric signal values.)
VSRUN_SERVER_COREDUMP
Set to 1 if the server created a core file when it exited, 0 otherwise
VSRUN_SERVER_EXPLAIN
A text string which summarizes the reason why the server exited (e.g. "exited with status 1" or "dumped core with signal 11").
VSRUN_SERVER_PID
The process ID of the server process. (Obviously since the process has already terminated, this is most useful for informational messages or for locating core files whose name includes the process ID.)
If the termination handler exits with status 0 (indicating success), the server process will be restarted by vsrun. Otherwise, the server will not be restarted and the vsrun monitor process will exit.

If the -u flag is given, the termination handler will be executed as the same user as the server.

A typical termination handler might include:

Examples

Start a server as a particular user writing a file containing its process ID: 

vsrun -p /var/run/foo.pid -u foouser -- fooserver
Same as above, but also Monitor the server and, if it crashes, run a script and restart it: 
vsrun -p /var/run/foo.pid -u foouser -m /var/run/foo-manager.pid /home/foouser/foo-died -- fooserver
Same as above, but send the server's output to syslog: 
vsrun -p /var/run/foo.pid -u foouser -m /var/run/foo-manager.pid /home/foouser/foo-died -s foo -- fooserver
Rather than sending the server's output to syslog, send it to files in a directory, keeping log files for 2 months: 
vsrun -p /var/run/foo.pid -u foouser -m /var/run/foo-manager.pid /home/foouser/foo-died -d /var/log/foo 2m -- fooserver
Run the server in the background as particular user with restricted filesystem access (i.e. in a chroot): 
vsrun -b -r /var/lib/foo -w / -u foouser -- fooserver

Limitations

vsrun always redirects the standard input of the server to /dev/null.

vsrun does not redirect standard output/error unless you use the -s flag or the the -d flag.

Bugs

If the -d flag is used and the the -w flag is not used, the working directory of the server process will be the directory argument to the -d flag rather than the current working directory where vsrun is invoked.

See Also

chroot(1), chroot(2), signal(7), logger(1)

Similar tools include:

Author

Ken Schalk <ken@xorian.net>

Based on smgr written by Ted Wobber, Copyright 1988 Digital Equipment Corporation.

This page was generated automatically by mtex software.