service-manager 1 user commands nosh
service-manager service manager
`service-manager`

## Description

`service-manager` manages a set of services, allowing their service processes to be programmatically brought up and down, and providing automatic restart upon failure.

It expects file descriptor 3 to be a (datagram) socket that has been set up to listen for incoming datagrams. This is its main control socket, through which it receives requests to load, unload, and pipe together services from utilities such as service-dt-scanner 1 and system-control 8. It creates individual control FIFOs for each service, through which it receives requests to send signals the service and bring it up or down, from utilities such as service-control 1.

system-manager 8 invokes `service-manager` with the appropriate socket (which it sets up itself) and output directed to a logging dæmon. So also does per-user-manager 1. Alternatively, `service-manager` can be started by local-datagram-socket-listen 1, which will set up the appropriate socket. (`service-manager` can even be started as a "socket-activated" dæmon by systemd 1 with the systemd-recommended `Accept=false`.)

## Services

Each service comprises several files in the filesystem, contained in two directories. The service manager neither knows nor cares where in the filesystem these directories are. That is the province of the utilities that feed control requests to it. See service-bundle 5 for the details of these files and directories.

system-control 1 builds upon these two with further directories, to construct a service bundle, and likewise service-dt-scanner 1 has its compatibility convention. But the all of this is entirely unknown to `service-manager`, which only deals with the core two directories, and places no restrictions on their locations in the filesystem, absolute or relative to each other.

The initial states of service processes – the user and group IDs, session, controlling terminal, session login name, process group, environment variables, open file descriptors, current root directory, and current working directory – are uniformly inherited from `service-manager` itself, not from the utilities such as service-dt-scanner 1 and system-control 8; with the exceptions that no file descriptors for service bundles or control sockets are available, and the current working directory is set to the `service` directory of the service bundle being invoked. (`service-manager` marks all such file descriptors as close-upon-exec 2, and the operating system kernel thus ensures that they are closed in the service process at the point that it tries to execute the designated `start`, `run`, `restart`, or `stop` program.) `service-manager` in turn inherits its state from (conventionally) the system-manager 8 or per-user-manager 1 that invoked it, and does not change it.

The control utilities can direct `service-manager` to plumb the standard input of one service to a pipe that is connected to the standard output and standard error of another service. In this case, `service-manager` retains open file descriptors to both ends of the pipe, only inherited by the relevant services. If not plumbed, the standard error of a service process in particular goes to the same place as the standard error of `service-manager`. Conventionally, system-manager 8 or per-user-manager 1 will have set up a cyclog 1 process to capture this to a fall-back global log.

The upshot of this is that all service processes start in their `service` directory; with the global root directory; with the service manager's credentials, session, and process group; with no controlling terminal or session login name; with the global environment that system-manager 8 or per-user-manager 1 either set up from the likes of `/etc/default/locale` and the like (c.f. those tools's respective manuals) or itself inherited from the kernel's own command-line/environment set by the operating system boot loader; with no open file descriptors other than standard input+output+error (unless the kernel or an "initial RAM disc" system, if one is in use, left some file descriptors open in error); and with standard error either going to the same place as the `service-manager`'s or to another service.

The `start`, `run`, `restart`, and `stop` programs have the responsibility for (as appropriate) dropping privileges, changing working or root directory, creating separate sessions and process groups, assigning login names to those sessions, opening controlling terminals, and clearing or changing the environment.

## Author

Jonathan de Boyne Pollard