summaryrefslogtreecommitdiff
path: root/man1/jaildaemon.1
blob: cdbcb996ec83930d4e4342f969d13f111fdd2051 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
.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 .