Man page

1 files changed, 163 insertions, 0 deletions

diff --git a/man1/jaildaemon.1 b/man1/jaildaemon.1
new file mode 100644
index 0000000..69ad632
--- /dev/null
+++ b/man1/jaildaemon.1
@@ -0,0 +1,163 @@
+.Dd March 11, 2013
+.Dt JAILDAEMON 1 USD
+.Os FreeBSD
+.Sh NAME
+.Nm jaildaemon
+.Nd A fixed commandline 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 r
+.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 client 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 client detects no running
+.Nm
+daemons, 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 finished.
+.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.
+.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 it's
+.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 .
+.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 foo.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 foo.com )
+and assign it the command
+.Bd -literal -offset indent
+ezjail-admin restart foo.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/foo.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 foo.com )
+and assign it the command
+.Bd -literal -offset indent
+zfs snapshot jails/foo.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 paramters is
+spawned and attached to the jail.
+.It Nm Fl c Ar 'reload_routing_table.sh foo.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 .