Tree


.gitignorecommits | blame
LICENSE.mdcommits | blame
Makefilecommits | blame
README.mdcommits | blame
newctl/
newd/

README.md

newd for OpenBSD
================

newd is a base daemon to start new OpenBSD daemons from. It carries the
privilege separated process layout, the imsg pipes between the processes,
the newctl control socket, a yacc configuration parser with macro and
include support, logging, and the rc.d and man page scaffolding, and
nothing else.

Processes
---------

* `newd` (parent): runs as root, parses `newd.conf`, forks the children,
  pushes configuration to them and answers `newctl show parent`.
* `control`: chrooted and unprivileged, owns `/var/run/newd.sock` and
  routes `newctl` requests to the parent and replies back to `newctl`.
* `engine`: chrooted and unprivileged, where the work of the new daemon
  belongs. Receives configuration from the parent and answers
  `newctl show engine`.

Startup is: the parent sends `IMSG_CFG_DONE` to both children, the engine
acknowledges with `IMSG_CFG_DONE`, and the parent then sends
`IMSG_CTL_START` to both, at which point the engine calls `engine_launch()`.

Building a new daemon
---------------------

1. Rename `newd`/`newctl`/`NEWD_*`/`_newd` throughout.
2. Add configuration keywords to `parse.y` (the `%token` line, the sorted
   table in `lookup()` and a `conf_main` rule) and fields to `struct newd`.
3. Add `IMSG_*` types to `newd.h`, handle them in the `*_dispatch_*`
   functions, and send any state the engine needs from `newd_configure()`.
4. Add `newctl` commands to `parser.c` and handlers to `newctl.c`.
5. Widen the `pledge` and `unveil` calls as needed.

Prerequisites
-------------

* OpenBSD 7.7 or higher

Files
-----

* `/usr/local/sbin/newd`
* `/usr/local/man/man8/newd.8`
* `/etc/examples/newd.conf`
* `/usr/local/man/man5/newd.conf.5`
* `/etc/rc.d/newd`
* `/usr/local/sbin/newctl`
* `/usr/local/man/man8/newctl.8`

Usage
-----

Compile and install.

		make
		doas make install
		doas groupadd _newd
		doas useradd -d /var/empty -L daemon -g _newd -s /sbin/nologin _newd
		doas cp newd/examples/etc/rc.d/newd /etc/rc.d/
		doas cp newd/examples/etc/newd.conf /etc/

Once newd.conf is in place, run `rcctl enable newd` and `rcctl start newd`.
The daemon can also be run manually from the command line. To keep newd
from daemonizing, run `newd -d`.

To check it is alive:

		newctl show parent
		newctl show control
		newctl show engine

Author
------

[Tracey Emery](https://github.com/basepr1me/)

See the [License](LICENSE.md) file for more information.