view vspawn.8 @ 0:76247b09b625

misc: initial import
author David Demelier <markand@malikania.fr>
date Thu, 29 Jul 2021 09:23:42 +0200
parents
children 7916dd39a513
line wrap: on
line source

.\"
.\" vspawn.8 -- start and stop daemons
.\"
.\" Copyright (c) 2021 David Demelier <markand@malikania.fr>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd July 28, 2021
.Dt VSPAWN 8
.Os
.Sh NAME
.Nm vspawn
.Nd start and stop daemons
.Sh SYNOPSIS
.Nm
.Op Fl fm
.Op Fl c Ar chroot
.Op Fl g Ar gid
.Op Fl p Ar pidfile
.Op Fl u Ar uid
.Ar start|status|stop
.Ar exec
.Op Ar arguments...
.Sh DESCRIPTION
.Nm
is an utility to start, check and stop daemons with specified UID, GID and
optional chrooting.
.Pp
It is designed to start daemons and system services which don't go to
background by themselves.
.Pp
If the option
.Fl f
isn't specified, all file descriptors are closed (stdin, stdout and stderr)
prior to running the program.
.Pp
The following options are available:
.Bl -tag
.It Fl f
Stays in foreground.
.It Fl c
Chroot into the
.Ar chroot
directory before spawning the command. The path to the program
.Ar exec
needs to be relative to that chroot.
.It Fl g
Use
.Ar gid
as group id to run the program as.
.It Fl m
Creates a pidfile when using the
.Ar start
command.
.It Fl p
Specifies the path to the pidfile. The default is located in
.Pa /run/name.pid
where name is the actual base name component from
.Ar exec
program path.
.It Fl u
Use
.Ar uid
as user id to run the program as.
.El
.Pp
The following commands are available:
.Bl -tag
.\" start
.It Cm start
Starts the program specified by
.Ar exec
and its optional
.Ar arguments .
If the program is already running by checking its pidfile (see
.Fl m
and
.Fl p
options),
.Nm
will throw an error.
.\" status
.It Cm status
Check if the program seems to be running. Be careful because services that may
crash can still be reported as running if the pidfile is still present.
.\" stop
.It Cm stop
Stop the process by sending
.Em SIGTERM
signal to its process id.
.El
.\" EXAMPLES
.Sh EXAMPLES
.Ss Start a daemon which does not go into the background
This command will effectively start
.Em blockapp
into the background and create a pidfile
.Pa /run/blockapp.pid .
.Bd -literal
# vspawn start -m /bin/blockapp
.Ed
.Ss Check its status
We still need to specify the path to the executable as it is used to determine
the default pid path.
.Bd -literal
# vspawn status /bin/blockapp
running with pid 34019
.Ed
.Ss Change UID/GID
Sets user and group to change program permissions. This will also affect the
pidfile creation so make sure /run is writable or use a different directory.
.Bd -literal
# vspawn -u www -g www /bin/httpd
.Ed
.\" SEE ALSO
.Sh SEE ALSO
.Xr vinit 8
.\" AUTHORS
.Sh AUTHORS
.Nm
was written by David Demelier <markand@malikania.fr>