diff --git a/README.md b/README.md index bac178f6..b2a93fb0 100644 --- a/README.md +++ b/README.md @@ -162,20 +162,27 @@ Syntax: N is the runlevel number 1-9, where 6 is reserved for reboot. Default is 2. -* `run [LVLS] /path/to/cmd ARGS -- Optional description` +* `run [LVLS] /path/to/cmd ARGS -- Optional description` One-shot command to run in sequence when entering a runlevel, with optional arguments and description. This command is guaranteed to be completed before running the next command. -* `task [LVLS] /path/to/cmd ARGS -- Optional description` +* `task [LVLS] /path/to/cmd ARGS -- Optional description` One-shot like 'run', but starts in parallel with the next command -* `service [LVLS] /path/to/daemon ARGS -- Optional description` +* `service [LVLS] /path/to/daemon ARGS -- Optional description` Service, or daemon, to be monitored and automatically restarted if it exits prematurely. Please note that you often need to provide a `--foreground` or `--no-background` argument to most daemons to prevent them from forking off a sub-process in the background. +```shell + service [2345] /sbin/ospfd -- OSPF daemon +``` + + For a detailed description of conditions, and how to debug them, + see the [Finit Conditions](doc/conditions.md) document. + * `inetd service/proto[@iflist] [LVLS] /path/to/daemon args` Launch a daemon when a client initiates a connection on an Internet port. Available services are listed in the UNIX `/etc/services` file. @@ -227,7 +234,7 @@ Syntax: sure to call the configure script with `--enable-embedded` if this is what you want. -* `console ` +* `console ) in -the service stanza. Multiple conditions may be specified separated by -comma. Conditions are AND'ed during evaluation, i.e. all conditions -must be satisfied in order for a service to run. +In addition to declaring allowed runlevels per service, it is also +possible to declare user-defined conditions as dependencies. Conditions +are specified within angle brackets (<>) in the service stanza. +Multiple conditions may be specified separated by comma. Conditions are +AND'ed during evaluation, i.e. all conditions must be satisfied in order +for a service to run. **Example:** @@ -39,8 +40,8 @@ service's pidfile being created. Triggering ---------- -Conditions are triggered by using the `emit` command of the `initctl` -control tool. +Conditions are triggered either by plugins or by using the `emit` +command of the `initctl` control tool. * `initctl emit +your/cond/here` @@ -61,20 +62,38 @@ new (or possibly unchanged) state of it. Built-in Conditions ------------------- -Finit is distributed with the `pidfile`-plugin. If enabled, it will -watch `/var/run/` for pidfiles created by services that it controls -and set a corresponding condition in the `svc/` namespace. +Finit is distributed with a `pidfile` and `netlink` plugin. If enabled, +the `pidfile` plugin watches `/var/run/` for PID files created by +monitored services, and sets a corresponding condition in the `svc/` +namespace. Similarily, the `netlink` plugin provides basic conditions +for when an interface is brought up/down and when a default route +(gateway) is set. -For example, if Finit starts the `/sbin/netd` daemon and it creates the -file `/var/run/netd.pid`, the condition `svc/sbin/netd` is satisfied. -If the file is removed, the condition is cleared. +With the example listed above, finit does not start the `/sbin/netd` +daemon until `setupd` and `zebra` has started *and* created their PID +files. Which they do when they completed their main tasks of setting up +VLANs, bridge, interfaces, etc. When `netd` in turn starts up it +creates the file `/var/run/netd.pid`, and the condition `svc/sbin/netd` +is satisfied. When the file is removed, the condition is cleared. + +The full path to the dependency is needed by finit to match the PID file +to a monitored process. + +Built-in conditions: + +- `svc/` +- `net/route/default` +- `net//exist` +- `net//up` + +Note: `up` is administratively up, `IFF_UP`, not link up, `IFF_RUNNING`. Debugging --------- If a service is not being started as it should, the problem might be -that one of its conditions are not in the expected state. Use the +that one of its conditions is not in the expected state. Use the command `initctl status` to inspect service status. Services in the `ready` state are pending a condition. @@ -102,9 +121,9 @@ Internals A condition is always in one of three states: -* `on`: The condition is asserted. -* `off`: The condition is deasserted. -* `flux`: The conditions state is unknown. +* `on` (+): The condition is asserted. +* `off` (-): The condition is deasserted. +* `flux` (~): The conditions state is unknown. All conditions that have not explicitly been set are interpreted as being in the `off` state. diff --git a/doc/service.md b/doc/service.md index edea5369..5c57ab50 100644 --- a/doc/service.md +++ b/doc/service.md @@ -1,29 +1,34 @@ -# Services +Finit Services +============== -## State Machine +![The service state machine](svc-machine.png "The service state machine") -![A service's state machine](svc-machine.png "A service's state machine") +State Machine +------------- -A service is bound to a state machine that is in one of six (6) -states. For `run`s and `task`s there is an additional end state called -`DONE`, not shown in the diagram for brevity. All services start in -the `HALTED` state. +A service is bound to a state machine that is in one of six (6) states. +For `run`s and `task`s there is an additional end state called `DONE`, +not shown in the diagram for brevity. Services start in the `HALTED` +state. The current state depends on the two following conditions: * `E`: Service enabled. In order for `E` to be satisfied, the service must be allowed to run in the current runlevel and must not be - blocked. A service may be blocked for several reasons: - - - The user has manually stopped the service using `initctl stop - JOB`. - - - The binary repeatedly dies after being started. I.e. keeps - crashing. + blocked. A service may be blocked for several reasons: + - The user has manually stopped the service using `initctl stop JOB` + - The binary repeatedly dies after being started. I.e. keeps crashing. - The binary is missing in the filesystem. -* `C`: Service conditions are satisfied. +* `C`: Service conditions are satisfied: + + - `on` (+): The condition is asserted. + - `off` (-): The condition is deasserted. + - `flux` (~): The conditions state is unknown. + +For a detailed description of conditions, and how to debug them, +see the [Finit Conditions](conditions.md) document.