.Dd March 11, 2013
.Dt JAILDAEMON 1 USD
.Os FreeBSD
.Sh NAME
.Nm jaildaemon
.Nd A fixed command-line interface for FreeBSD jails to their host system
.Sh SYNOPSIS
.Nm
.Cm Fl D
.Op Fl p Ar pidfile
.Op Fl f Ar ipcsockpath
.Nm
.Cm Fl c Ar command Fl j Ar jid
.Op Fl rR
.Op Fl u Ar uid
.Op Fl g Ar gid
.Op Fl t Ar proctitle
.Op Fl f Ar ipcsockpath
.Sh DESCRIPTION
The
.Nm
daemon awaits commands from the
.Nm
utility to spawn a probe process in a jail, optionally giving it a talking
proctitle. It assigns a single command to this process which is executed once
the associated probe receives the HUP signal, optionally respawning the probe.
.Pp
This is useful to allow scripts or users in a
.Xr jail 8
environment to trigger some predefined actions in the host system, like
rebooting a jailed host, manipulating devices or taking file system snapshots.
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl D
Start the
.Nm
in daemon mode. It will check for other instances of jaildaemon by sending a
test command to the ipc socket.
.It Fl p Ar pidfile
When run in daemon mode, write the ID of the daemon process into the
.Ar pidfile
using the
.Xr pidfile 3
functionality. Ignored in utility mode.
.It Fl f Ar ipcsockpath
.Nm
in utility mode passes commands to the
.Nm
daemon via unix domain socket, which defaults to
.Pa /var/run/jaildaemon.pipe .
You can pass an alternative with this option.
.It Fl c Ar command
Start the
.Nm
in utility mode and pass the
.Ar command ,
together with the jid and an optional proctitle to the
.Nm
daemon. When the utility detects no running
.Nm
daemon, an error is reported.
.It Fl j Ar jid
The jail id of the jail
.Nm
daemon shall attach the probe process to.
.It Fl t Ar proctitle
Setting a proctitle on the probe process is useful to provide some information
to scripts or users in the jail, what action sending the HUP signal triggers.
The proctitle is visible via the
.Xr ps 1
utility and signals can be sent to all processes matching the string with the
.Xr pkill 1
utility when invoked with the
.Ar -f
option. (See
.Sx EXAMPLES
for more details.)
.It Fl r
Tell the
.Nm
daemon to respawn the probe process once the triggered command in the host
system has completed.
.Pp
By default all commands start single shot processes; to avoid race conditions
and multiple invocations of possibly non-reentrant scripts, probe processes
kill themselves after receiving the HUP signal. Respawning is meant as an
option for commands that do not shut down the jail.
.It Fl R
Just like the
.Fl r
option, only the
.Nm
daemon does not wait for the
.Ar command
to complete before re-spawning the probe process.
.Pp
Use this option only if you know, what you're doing. Most shell scripts are
not re-entrant, even if their authors think so and most programs that run
long enough should not be started twice with identical parameters.
.It Fl u Ar uid
Probes normally run as user root and thus can only be signalled by root
inside the jail. For some use cases it is desirable to allow non-privileged
processes inside the jail to signal the probe. You can use this switch to
tell
.Nm
what uid to drop to after being jailed away. (Note that uids inside and
outside the jail are never guaranteed to match.)
.Pp
Use this option only if you know, what you're doing. For most occasions it
is a good idea to restrict signalling probes to the root user.
.Pp
.It Fl g Ar gid
Set the group ID of the probe process. Useful together with the -u switch on
hosts where security.bsd.see_other_gids=0.
.El
.Pp
Exactly one of the
.Fl D
or
.Fl c
options must be specified, in daemon mode all options for the utility mode are
ignored. In utility mode the
.Fl j
parameter is mandatory.
.Sh EXAMPLES
.Ss Starting the daemon
The
.Nm
daemon normally is run from its
.Xr rc 8
script on boot time. Invoke the daemon by hand using this command:
.Bl -tag -width indent
.It Nm Fl D Fl p Ar /var/run/jaildaemon.pid
Start the daemon and write the daemon's pid to the file
.Ar /var/run/jaildaemon.pid .
(This is the default pid file location.)
.El
.Ss Running the utility
When the
.Nm
daemon is alive, you can start attaching probe commands to running jails.
.Pp
While the first examples show you what is possible, the most simple way of
scripting an action is to write a small wrapper script as shown in the third
example.
.Bl -tag -width indent
.It Nm Fl c Ar 'ezjail-admin restart example.com' Fl j Ar 23 Fl t Ar EZJAIL_REBOOT
Start a probe in jail with jid 23 (presumably a jail with the name
.Dq example.com )
and assign it the command
.Bd -literal -offset indent
ezjail-admin restart example.com
.Ed
.Pp
The proctitle
.Dq EZJAIL_REBOOT
will be visible from within the jail, and a reboot can be triggered from a
script inside the jail with the command
.Bd -literal -offset indent
pkill -HUP -f EZJAIL_REBOOT
.Ed
.It Nm Fl c Ar 'zfs snapshot jails/example.com@`date +%s`' Fl j Ar 42 Fl r Fl t Ar ZFS_SNAPSHOT
Start a probe in jail with jid 42 (presumably a jail with the name
.Dq example.com )
and assign it the command
.Bd -literal -offset indent
zfs snapshot jails/example.com@`date +%s`
.Ed
.Pp
The proctitle
.Dq ZFS_SNAPSHOT
will be visible from within the jail and taking a zfs snapshot of the jail's
file system can be triggered from a script inside the jail with the command
.Bd -literal -offset indent
pkill -HUP -f ZFS_SNAPSHOT
.Ed
.Pp
After the zfs snapshot command finished, a new probe with identical parameters is
spawned and attached to the jail.
.It Nm Fl c Ar 'reload_routing_table.sh example.com' Fl j Ar 1 Fl r Fl t Ar UPDATE_ROUTING
.El
.Sh FILES
.Pa /var/run/jaildaemon.pipe
.Sh SEE ALSO
.Xr jail 8 ,
.Xr signal 3 ,
.Xr ps 1 ,
.Xr pgrep 1 ,
.Xr pkill 1
.Sh AUTHOR
.An Dirk Engling
.Aq erdgeist@erdgeist.org .