summaryrefslogtreecommitdiff
path: root/stories/projects/jaildaemon.rst
diff options
context:
space:
mode:
Diffstat (limited to 'stories/projects/jaildaemon.rst')
-rw-r--r--stories/projects/jaildaemon.rst77
1 files changed, 77 insertions, 0 deletions
diff --git a/stories/projects/jaildaemon.rst b/stories/projects/jaildaemon.rst
new file mode 100644
index 0000000..cc818e3
--- /dev/null
+++ b/stories/projects/jaildaemon.rst
@@ -0,0 +1,77 @@
1.. description: is a tool for the FreeBSD operating system to allow flexible and secure communication from jail environments to the host system.
2.. tags: project
3.. date: 2015/02/18 19:10:08
4.. title: jaildaemon
5.. subtitle: A fixed command-line interface for FreeBSD jails to their host system
6.. slug: ../arts/software/jaildaemon/index
7.. prio: 850
8
9.. contents::
10 :depth: 1
11 :class: ezjail-toc
12
13----
14
15Overview
16========
17
18.. image:: http://www.freebsd.org/gifs/daemon_hammer-tn25.jpg
19 :align: right
20
21Virtual FreeBSD jail based server environments can not easily trigger actions in the host system, most prominently restarting themselves (if they ``kill -1`` everything, they usually stay shut down) and trigger actions like routing table updates, triggering zfs snapshots or rollbacks and configuring ``tun/tap``-Devices (as an openvpnd would).
22
23There are several less-than-optimal solutions for that problem: granting forced-command ssh access to jails, polling some Jail-state from within the host system or dig some proprietary socket holes through the Jail's barrier, exposing a root-shell attack vector to the outside world.
24
25*jaildaemon* aims to solve the problem in a simple and straight forward way while trying to minimize the attack surface for adversaries from the Jail and the network. It is a tiny daemon running in the host system that forks a probe process with a single associated command on demand, attaches it to a single jail and (optionally) assigns it a verbose proctitle. When the Jail's root user sends a SIGHUP to this probe process, it dies with a magic exit code, signalling the daemon to execute the associated command (in host context). You can chose to have the daemon restart the probe process after the command is executed (e.g. when it triggers updating routing tables) or just wait for it to be restarted by the Jail management tool (e.g. when using ``/usr/local/etc/rc.d/ezjail restart shell.foo.com`` as a reboot helper).
26
27----
28
29Code
30====
31
32You can always get the latest version of *jaildaemon*, use ``git clone git://erdgeist.org/jaildaemon`` or the legacy view ``cvs -d :pserver:anoncvs@cvs.erdgeist.org:/home/cvsroot co jaildaemon`` with an empty password to check it out. There is a *jaildaemon* tarball, but no versioning yet. You can scroll through the source at `jaildaemon gitweb </gitweb/jaildaemon>`_ or `jaildaemon cvsweb (deprecated) </cvsweb/jaildaemon>`_. Typing ``make install`` installs the binary in your ``${PREFIX}/bin`` (or ``/usr/local``, if none is set) and the rc-script to ``${PREFIX}/etc/rc.d/``.
33
34A tight integration with `ezjail </arts/software/ezjail/>`_ is, of course, following soon.
35
36----
37
38Examples
39========
40
41Start the daemon as root with ``jaildaemon -D``, with optional parameters ``p`` and ``f`` to request the pidfile being written or to specify a different controlling command unix domain socket location (that is used by *jaildaemon* when run in client mode to communicate with the server, and defaults to ``/var/run/jaildaemon.pipe``), respectively.
42
43If you installed the package, you can just enable *jaildaemon* in your ``/etc/rc.conf``, by adding ``jaildaemon_enable=YES``. It should then start at reboot, or when you run ``/usr/local/etc/rc.d/jaildaemon start``.
44
45Start a new probe process in a Jail (in this example jid 23) to trigger the execution of the script::
46
47 /usr/local/bin/parse_route_config -s /usr/jails/shell.foo.com/
48
49while identifying as 'route config update' in the jail and respawn::
50
51 jaildaemon -j 23 -c '/usr/local/bin/parse_route_config -s /usr/jails/shell.foo.com/' -t 'route config update' -r
52
53From within the jail (``ezjail-admin console shell.foo.com``) trigger the command by ``pkill -HUP -f 'route config update'``.
54
55Start a (non-spawning) Jail reboot trigger::
56
57 jaildaemon -j 23 -c '/usr/local/etc/rc.d/ezjail restart shell.foo.com' -t REBOOT
58
59Now, from within that Jail, reboot via ``pkill -HUP -f REBOOT``.
60
61----
62
63Version history
64===============
65
66* Version 0.2:
67
68 * Fixed a bug where *jaildaemon* when run from /etc/rc would ignore SIGHUP by default.
69 * You can now make the probe drop into another uid, so that non-root-processes can trigger actions, as well.
70 * Allow *jaildaemon* to accept the jailname for the -j parameter, as well.
71
72----
73
74License
75=======
76
77*jaildaemon* was written by `Dirk Engling <mailto:erdgeist@erdgeist.org>`_ with lots of help from sg and is considered `beer ware </beerware.html>`_.