2
2
Fork
You've already forked dbus-controller-script
0
A generic non-systemd controller for dbus-broker
  • C 62.4%
  • Python 22.8%
  • Shell 11.5%
  • Meson 3.3%
capezotte 1d4d89bf9f dinit-turnstile-session: change ready type 
POSIX does not guarantee the shell will be able to handle file
descriptors with more than one digit:
"The largest possible value is implementation-defined; however, all
implementations shall support at least 0 to 9, inclusive, for use by the
application." (POSIX.1-2024, Shell Command Language, Section 2.7).
mksh (since R53) and dash happily refuse to support fds >=10, and dinit
seems to like using these for `pipevar`. Let's just use 9 and call it a
day. Plus being sure we can close it is a nice bonus.
2026年03月09日 21:01:03 -03:00
contrib/tools.orig move policy_xml out of contrib 2026年02月20日 22:45:08 -03:00
init-samples dinit-turnstile-session: change ready type 2026年03月09日 21:01:03 -03:00
pkg make policy no longer optional; install dbcs-policy-xml 2026年02月20日 22:45:08 -03:00
pysrc move policy_xml out of contrib 2026年02月20日 22:45:08 -03:00
socktools --print-address for dbcs-socketbinder 2026年02月20日 22:45:08 -03:00
src waitid oops, again 2026年02月22日 15:45:30 -03:00
subprojects here's tree 2024年07月05日 14:32:26 -03:00
.gitignore update samples 2026年02月14日 15:41:21 -03:00
meson.build make policy no longer optional; install dbcs-policy-xml 2026年02月20日 22:45:08 -03:00
meson_options.txt make policy no longer optional; install dbcs-policy-xml 2026年02月20日 22:45:08 -03:00
POLICY.md move policy_xml out of contrib 2026年02月20日 22:45:08 -03:00
README.md --print-address for dbcs-socketbinder 2026年02月20日 22:45:08 -03:00

dbus-controller-script

A non-systemd controller for dbus-broker with scriptable hooks (last tested with v37).

A fork of dbus-controller-s6 that replaces its suggested policy for s6 with entrypoints for scripts.

dbus-controller-script is configured through the command line and files in its working directory.

Options

It expects to have a bound and listening socket as its stdin, which is given to the broker over the D-Bus protocol.

There are three options:

  • -3: write a newline to a preopened file descriptor 3 after sending the first batch of commands to dbus-broker. This is compatible with s6's notification-fd and dinit's ready-notification = pipefd.
  • -C: change working directory after starting dbus-broker (see Files below).
  • -v: number representing logging verbosity. 0 unrecoverable failures; 1 major, but recoverable, errors (default); 2 minor errors and warnings; 3 informational messages on program state; 4 debug.

After the options, a command line is expected. It is spawned with file descriptor 3 pointing to the reading end of the controller's IPC endpoint. The most obvious option is dbus-broker --controller=3 --machineid=..., but if additional setup is needed, you can prepend utilities that change process state, or give the path to a script that ultimately execs the broker.

Files

Whenever a the controller receives a relevant D-Bus signal from the broker, it runs scripts in its working directory:

  • populate-services (executable)/services (static): An executable that provides a list of bus-activable names on stdout, one per line (first), or a static list of services in the same format. If neither of these files is absent, bus activation is disabled, and the next file is a no-op.
  • service-start: whenever dbus-controller-script gets an activation request for a dbus-name populate-services told it about, it spawns ./service-start $name (one argument).
  • service-export: whenever a request to add some "key=value" to the D-Bus activation environment comes, it spawns ./service-export $key $value (two arguments). If this file is absent, such requests are ignored.
  • populate-policy (executable)/policy (static): The representation of the policy that shall govern connections, message passing and name ownership. This file has an ad-hoc format described in POLICY.md. Similarly to populate-services and services, populate-policy is an executable, while policy is a ready-made list. Only this file is mandatory.

These files are exec'd as-is; you can write them in any programming language, all it takes is a suitable shebang. They also inherit the controller's working directory, so using relative paths is predictable.

Note that the files are assumed to respond correctly to SIGTERM, and to have proper timeouts in place. Otherwise, the process table and other system resources may be exhausted.

Signals

dbus-controller-script accepts two signals to reload configuration, SIGHUP and SIGALRM. The former causes it to reload its service list, while the latter causes it to reload the policy.

To reload both items, send both signals, or use the D-Bus method call, busctl --system call org.freedesktop.DBus / org.freedesktop.DBus ReloadConfig.

Socket Tools

Socket preopening is usually a better pattern than programs binding sockets themselves. That's why the options for connecting to syslog and choosing socket path were removed. As a fallback, the original code for the options was factored out as separate tools:

  • dbcs-socketbinder path ...: binds a Unix domain socket at path, enables listening on it and makes it the program's stdin. This can be used in the command line for the controller itself.
  • dbcs-streamclient syslog-sock ... and dbcs-journalclient syslog-sock ...: establish a SOCK_STREAM/SOCK_DGRAM (respectively) connection at fd 7. This can be used in the command-line that spawns dbus-broker. See docs/dbus-broker.rst on the broker's repository on the differences between the logging formats.

They support an -@ option, meaning path will be found in the abstract namespace for Unix sockets instead of the filesystem. Additionally, dbcs-socketbinder takes a -a option (set up octal permissions for the socket it binds) and a -p option (print address, like dbus-daemon --print-address, after binding).

Rosetta stone:

  • dbus-controller-* -d /path/to/dbus-sock dbus-broker = dbcs-socketbinder /path/to/dbus-sock dbus-controller-script -- dbus-broker ...
  • dbus-controller-* -s = dbus-controller-script -- dbcs-journalclient /dev/log dbus-broker --log=7 ...
  • dbus-controller-s6 -e ... = don't provide a ./service-export file.

They are extremely bare-bones, and perform very little validation of their input. If your init system supports socket preopening, it is far better to rely on it than on these tools. Do not use dbcs-socketbinder -p to supply readiness notification for your init system; use dbus-controller-script -3.

Examples

See the init-samples folder.