summaryrefslogtreecommitdiff
path: root/man1/jaildaemon.1
diff options
context:
space:
mode:
Diffstat (limited to 'man1/jaildaemon.1')
-rw-r--r--man1/jaildaemon.1163
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 @@
1.Dd March 11, 2013
2.Dt JAILDAEMON 1 USD
3.Os FreeBSD
4.Sh NAME
5.Nm jaildaemon
6.Nd A fixed commandline interface for FreeBSD jails to their host system
7.Sh SYNOPSIS
8.Nm
9.Cm Fl D
10.Op Fl p Ar pidfile
11.Op Fl f Ar ipcsockpath
12.Nm
13.Cm Fl c Ar command Fl j Ar jid
14.Op Fl r
15.Op Fl t Ar proctitle
16.Op Fl f Ar ipcsockpath
17.Sh DESCRIPTION
18The
19.Nm
20daemon awaits commands from the
21.Nm
22utility to spawn a probe process in a jail, optionally giving it a talking
23proctitle. It assigns a single command to this process which is executed once
24the associated probe receives the HUP signal, optionally respawning the probe.
25.Pp
26This is useful to allow scripts or users in a
27.Xr jail 8
28environment to trigger some predefined actions in the host system, like
29rebooting a jailed host, manipulating devices or taking file system snapshots.
30.Pp
31The options are as follows:
32.Bl -tag -width indent
33.It Fl D
34Start the
35.Nm
36in daemon mode. It will check for other instances of jaildaemon by sending a
37test command to the ipc socket.
38.It Fl p Ar pidfile
39When run in daemon mode, write the ID of the daemon process into the
40.Ar pidfile
41using the
42.Xr pidfile 3
43functionality. Ignored in client mode.
44.It Fl f Ar ipcsockpath
45.Nm
46in utility mode passes commands to the
47.Nm
48daemon via unix domain socket, which defaults to
49.Pa /var/run/jaildaemon.pipe .
50You can pass an alternative with this option.
51.It Fl c Ar command
52Start the
53.Nm
54in utility mode and pass the
55.Ar command
56, together with the jid and an optional proctitle to the
57.Nm
58daemon. When the client detects no running
59.Nm
60daemons, an error is reported.
61.It Fl j Ar jid
62The jail id of the jail
63.Nm
64daemon shall attach the probe process to.
65.It Fl t Ar proctitle
66Setting a proctitle on the probe process is useful to provide some information
67to scripts or users in the jail, what action sending the HUP signal triggers.
68The proctitle is visible via the
69.Xr ps 1
70utility and signals can be sent to all processes matching the string with the
71.Xr pkill 1
72utility when invoked with the
73.Ar -f
74option. (See
75.Sx EXAMPLES
76for more details.)
77.It Fl r
78Tell the
79.Nm
80daemon to respawn the probe process once the triggered command in the host
81system has finished.
82.Pp
83By default all commands start single shot processes; to avoid race conditions
84and multiple invocations of possibly non-reentrant scripts, probe processes
85kill themselves after receiving the HUP signal. Respawning is meant as an
86option for commands that do not shut down the jail.
87.El
88.Pp
89Exactly one of the
90.Fl D
91or
92.Fl c
93options must be specified, in daemon mode all options for the utility mode are
94ignored. In utility mode the
95.Fl j
96parameter is mandatory.
97.Sh EXAMPLES
98.Ss Starting the daemon
99The
100.Nm
101daemon normally is run from it's
102.Xr rc 8
103script on boot time. Invoke the daemon by hand using this command.
104.Bl -tag -width indent
105.It Nm Fl D Fl p Ar /var/run/jaildaemon.pid
106Start the daemon and write the daemon's pid to the file
107.Ar /var/run/jaildaemon.pid .
108.El
109.Ss Running the utility
110When the
111.Nm
112daemon is alive, you can start attaching probe commands to running jails.
113.Pp
114While the first examples show you what is possible, the most simple way of
115scripting an action is to write a small wrapper script as shown in the third
116example.
117.Bl -tag -width indent
118.It Nm Fl c Ar 'ezjail-admin restart foo.com' Fl j Ar 23 Fl t Ar EZJAIL_REBOOT
119Start a probe in jail with jid 23 (presumably a jail with the name
120.Dq foo.com )
121and assign it the command
122.Bd -literal -offset indent
123ezjail-admin restart foo.com
124.Ed
125.Pp
126The proctitle
127.Dq EZJAIL_REBOOT
128will be visible from within the jail, and a reboot can be triggered from a
129script inside the jail with the command
130.Bd -literal -offset indent
131pkill -HUP -f EZJAIL_REBOOT
132.Ed
133.It Nm Fl c Ar 'zfs snapshot jails/foo.com@`date +%s`' Fl j Ar 42 Fl r Fl t Ar ZFS_SNAPSHOT
134Start a probe in jail with jid 42 (presumably a jail with the name
135.Dq foo.com )
136and assign it the command
137.Bd -literal -offset indent
138zfs snapshot jails/foo.com@`date +%s`
139.Ed
140.Pp
141The proctitle
142.Dq ZFS_SNAPSHOT
143will be visible from within the jail and taking a zfs snapshot of the jail's
144file system can be triggered from a script inside the jail with the command
145.Bd -literal -offset indent
146pkill -HUP -f ZFS_SNAPSHOT
147.Ed
148.Pp
149After the zfs snapshot command finished, a new probe with identical paramters is
150spawned and attached to the jail.
151.It Nm Fl c Ar 'reload_routing_table.sh foo.com' Fl j Ar 1 Fl r Fl t Ar UPDATE_ROUTING
152.El
153.Sh FILES
154.Pa /var/run/jaildaemon.pipe
155.Sh SEE ALSO
156.Xr jail 8 ,
157.Xr signal 3 ,
158.Xr ps 1 ,
159.Xr pgrep 1 ,
160.Xr pkill 1
161.Sh AUTHOR
162.An Dirk Engling
163.Aq erdgeist@erdgeist.org .