doc: update section on pidfile.so plugin
@@ -31,7 +31,7 @@ service to run.
### Example
```shell
- service [2345] <pid/sbin/setupd,pid/sbin/zebra> /sbin/netd -- Network monitor
+service [2345] <pid/setupd,pid/zebra> /sbin/netd -- Network monitor
```
In this example the Network monitor daemon `netd` is not started until
@@ -95,20 +95,34 @@ Built-in conditions:
Composition
-----------
-The `pid/` conditions can be quite tricky to understand. They are
-generated by the Finit `pidfile.so` plugin and are composed from the
-daemon's path and the pidfile name (and path).
-
-| **service** | **pid:** | **pidfile path** | **svc condition** |
-|--------------------------------------|-----------------|------------------|-------------------|
-| /sbin/foo | | /run/foo.pid | pid/sbin/foo |
-| /sbin/bar -p /run/baz.pid | pid:baz | /run/bas.pid | pid/sbin/baz |
-| lxc-start -n foo -p /run/lxc/foo.pid | pid:lxc/foo.pid | /run/lxc/foo.pid | pid/lxc/foo |
-| /usr/bin/dbus-daemon | pid:dbus/pid | /run/dbus/pid | pid/usr/bin/dbus |
-
-Omitting the `pid:` to run/task/service/sysv stanza means Finit will
-guess the pidfile path based on `/run/` and the basename(1) of the
-program.
+The `pid/` conditions are generated by the Finit `pidfile.so` plugin and
+composed from a service's `name:` and `:id`. By default the basename of
+the daemon and the empty string.
+
+| **service** | **condition** |
+|----------------------------------------------------|------------------|
+| /sbin/foo | pid/foo |
+| /sbin/bar -p /run/baz.pid | pid/bar |
+| name:lxc :foo lxc-start -n foo -p /run/lxc/foo.pid | pid/lxc:foo |
+| /usr/bin/dbus-daemon | pid/dbus-daemon |
+| :222 dropbear -p 222 | pid/dropbear:222 |
+
+The condition is asserted when `pidfile.so` receives an inotify event for a file
+matching `/run/*.pid`, `/run/**/*.pid`, or `/run/**/pid`, which contains the
+PID of the service Finit has started.
+
+When Finit configuration files are changed and the `initctl reload`
+command is called, it is expected of services to touch their PID files
+for Finit to reassert their conditions.
+
+Daemons that don't create PID files, or fail to touch them on reload,
+can be worked around by using the `pid:/path/to/file.pid` syntax in
+the service stanza for the daemon. It is far from optimal since any
+synchronization of depending services may fail due to the daemon not
+having reinitialized/created their IPC sockets, or similar.
+
+> **Note:** in versions of Finit prior to v4, the PID conditions were
+> called 'svc' conditions, and they were far more complex.
Debugging
