From 3ba18b4fc7acfd3f375f9e5123b9cecb20f8c221 Mon Sep 17 00:00:00 2001 From: erdgeist <> Date: Mon, 11 Mar 2013 18:13:06 +0000 Subject: Man page --- man1/jaildaemon.1 | 163 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 man1/jaildaemon.1 (limited to 'man1') 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 . -- cgit v1.2.3