Services and targets

Services and targets are defined by bundle directories. Although there is no constraint enforced, and system-control simply follows symbolic links, by convention service bundle directories generally live under /etc/service-bundles/services, /run/service-bundles/services, or /var/sv; and target bundle directories generally live under /etc/service-bundles/targets.

A service is generally a dæmon process that runs. A target is generally a collection of services that are started/stopped together.

Jobs and actions

The start and stop subcommands construct jobs, which comprise a set of actions. Each action is a start or a stop command to the control API of a service/target. Jobs are composed by starting with an action on a named service, and then following information in the service bundles to related services and targets. The service bundles also determine the order in which the actions are taken.

A start action simply requests that the service manager bring the service/target to the "running" state, if it isn't already there. A stop action, however, is more complex. Initially it requests that the service manager bring the service/target to the "stopped" state (if it isn't already there). However, if that does not happen within 60 seconds, it requests that the service manager send the SIGKILL signal to the service/target.

Bundle directories

A bundle directory contains the command information, dependency information, relationship information, and control/status API for a service. It contains various subdirectories (which can be symbolic links to directories elsewhere):

Relationships are not the same as dependencies. A service can "want" another service without having any ordering against it with respect to start/stop actions. Indeed, this is a common case for system targets. The normal target, for example, "wants" the server, workstation, multi-user, static-networking , and users targets (and by extension everything that they in their turn "want"), but all of the wanted services are started in parallel with the normal target itself.

Similarly, a service can be ordered with respect to another service without having a dependency from it. For example, both "log" and "main" services are "wanted" by the server and workstation targets, explicitly. The individual "main" services, therefore, only need to be ordered after their corresponding "log" services, and do not "want" them. ("log" services are first-class citizens in this respect.)

There are no implicit relationships or dependencies in a bundle. The relationships and dependencies are exactly what is explicitly in the filesystem. system-control will fail if the recorded relationships and dependencies are self-contradictory or impossible (such as a service that conflicts with itself, for example).

Bundle search paths and conventional locations

Several subcommands take a list of bundle names... . Each name can be the full absolute pathname of a bundle directory or a relative pathname with a directory prefix, in which case it is used as-is, or a bundle directory name without any directory prefix, in which case a set of standard locations is searched for a bundle directory by that name. The search algorithm is as follows:

If the path search fails, the name is simply assumed to name a bundle directory in the current directory.

System information subcommands

For compatibility with uses of initctl, the version subcommand displays the (compiled-in) version of the toolset. It does not contain the string "upstart".

System control subcommands

Those subcommands communicate with the system manager to change system state. system-control sends a signal to process #1 using the kill(2) system call. It will fail if it does not have the necessary privileges for sending a signal to that process.

Exactly how the system power cycles, powers off, halts, reboots, switches to normal, emergency, or rescue modes, and so forth is entirely up to whatever is running as process #1, which is expected to be in charge of system state. These subcommands do nothing except send the signals to command the system manager. They do not directly enact any system state change themselves. In part this is because that would open up the possibility of the service manager killing the process that was (partway through) enacting the state changes, if a state change happened to affect the service running the system-control command.

The [--force] command line argument is used within the various targets and is intended to cause the system manager to proceed directly to the finalization action.

The init subcommand is spawned by system-manager(8) and per-user-manager(8) as their initial action. They pass it the command line arguments that they themselves were invoked with. As such, its command line syntax is modelled on what boot loaders and kernels tend to supply to process #1, which is a largely undocumented and non-standardized mixture of old-style runlevels and options.

In normal and rescue modes it sends two signals to process #1, instituting a two-phase initialization sequence similar to the FILESYSTEMS milestone mechanism in BSD operating systems. The first phase, the sysinit target, is expected to initialize as much of the system as necessary so that the second phase, the normal or rescue target, can find all service and target bundles, including those that are not on the root filesystem.

There is no q runlevel. This is deliberate. Its use case is running telinit q after updating /etc/ttys or /etc/inittab. Any script that is updating those files and then expecting the system manager to re-read them is not targetting the correct configuration mechanisms, and is in error.

LILO, the FreeBSD loader(8), GRUB, and others may cause -a or -f options to be passed. Their meanings are non-standard, largely or even wholly undocumented, inconsistent across platforms and toolsets, considered obsolete in their original forms, and without application here. The -z option is a dummy space-taker that is also used by such systems. All three options are ignored. The --update command line option is reserved for future use.

job subcommands

These subcommands process one or more jobs, sending messages to the service manager to start or to stop one or more services. Jobs may also involve invoking any number of configurable actions. Jobs processing tries to ensure that service dependencies are correctly maintained and processed. To control services directly and individually without regard for dependencies, use service-control(8).

The --verbose command line option cause information about actions taken and blocked/unblocked services to be written to standard error as jobs are processed. If the standard error is a terminal, system-control uses whatever it can find via the terminfo library to display various parts of the output in different colours, highlighting different events in different colours. The --colour command line option tells it to do this unconditionally, even if its standard error is not a terminal. The --pretend command line option tells it to only pretend that it is taking actions, and not actually take them.

The reset command is intended to be used by package installer programs. It is translated into either start or stop according to whether the service is enabled or disabled; and can be thought of, if one likes, as "reset to however the service is configured to be at bootstrap". This allows package installers to remain in blissful ignorance of whether a service should be started or stopped after installing the package for it. Instead, the package installer simply executes the preset command and then the reset command and the service is started or stopped according to whatever the administrator has chosen.

The isolate subcommand exists for compatibility, and is equivalent to start.

service autoboot configuration subcommands

These subcommands enable or disable one or more services or targets, so that they do or do not automatically start when one of the standard targets is started and automatically stop when the shutdown standard target is started.

Each service bundle specifies a (symbolically linked) list of target bundles in its wanted-by/ directory. Usually these will be the workstation, server, users, or multi-user standard targets. For each bundle, enabling the service involves symbolically linking its bundle directory into the target bundle's wants/ list, and disabling the service involves removing that link.

Each service bundle also specifies a (symbolically linked) list of target bundles in its stopped-by/ directory. Usually these will be the shutdown standard target. For each bundle, enabling the service involves symbolically linking its bundle directory into the target bundle's conflicts/ and after/ lists, and disabling the service involves removing those links.

The preset command is intended to be used by package installer programs. It is translated into either enable or disable according to a system/administrator-supplied preset flag (unless the --dry-run command line argument is used, causing it to take no actual action). This allows package installers to remain in blissful ignorance of whether a service should be enabled or disabled after installing the package for it. Instead, the package installer simply executes the preset command and the service is set to whatever enabled or disabled status the administrator has chosen.

The service/socket/target that is preset is prefixname, with prefix specifiable via the --prefix command line argument. Preset information can be taken from one of several sources:

service status/control subcommands

system-control takes each of the [names...], searches for the corresponding service bundle directory, constructs a list of directory names, and chains to other commands with those directory names as arguments:

script conversion subcommand

This subcommand takes some systemd unit files and generates from them a service bundle in the current directory (or in the root directory) that contains scripts, dependencies, and autoboot dependency configuration information. The bundle is not enabled by the conversion process, but can be started and enabled as it stands, with the start and preset subcommands, just like any other service bundle.

fstab conversion subcommand

The convert-fstab-services subcommand takes the entries in /etc/fstab and generates from them a set of service bundles.

The write-volume-service-bundles subcommand writes service bundles that contain scripts, dependencies, and autoboot dependency configuration information appropriate for mounting, unmounting, and checking a volume.

The bundles generated by these subcommands are written in the current directory (or in the root directory). They are not enabled by the conversion process, but can be started and enabled as they stand, with the start and preset subcommands, just like any other service bundle. With preset the --fstab option is appropriate of course. (It is preset that handles the noauto option.)

The assumption is that all service bundles are under one common root and all target bundles under another; so service-to-service dependencies and orderings can be relative pathnames whilst service-to-target and target-to-service dependencies and orderings have to be absolute pathnames. The --etc-bundle option changes this assumption, such that target bundles are now assumed to be reachable with relative pathnames from the converted service bundle; as is the case for special early bootstrap service bundles that live in /etc/service-bundles/services/. It also forces the bundle to be marked as an EarlySupervise bundle whose supervise/ directory lives in a tmpfs.

conversion utility subcommand

The escape subcommand takes each name and converts it using the escaping rules used in the convert-systemd-units subcommand. Each escaped name is written to standard output, separated from its predecessor (if any) by a space and prefixed with prefix (which is not escaped).

The --alt-escape option causes the same selection of an alternative escaping algorithm as with the command line option of the same name for the convert-systemd-units subcommand.

Nagios plug-in subcommand

This subcommand is intended for use as a Nagios plug-in. It queries the status API in the bundle directory for service/target name .

Kernel module management subcommands

These subcommands provide a minimal operating-system-neutral kernel module loading and unloading mechanism, for use in cross-platform service bundles. They devolve to the appropriate operating system commands, which are kldload(8) and kldunload(8) on BSD and modprobe(8) (without or with the --remove option) on Linux.

service program dump subcommands

system-control takes each of the [names...], searches for the corresponding service bundle directory, changes to the corresponding service directory, and runs grep(1) to dump the contents of the start, stop, run, and restart files.

service environment manipulation subcommands

If the name service has an environment template subdirectory named env/ (in the format understood by envdir(1)), these subcommands can be used to manipulate that template.

The --full command-line option switches to an alternative format for the environment template subdirectory, as understood by envdir(1) when its option of the same name is used.

filesystem table query subcommands

These subcommands query the /etc/fstab database. They fill a gap left by the getent(1) command, which has no subcommand for reading the filesystem table. Like that command, they query the on-disc administrative database of what is configured to be mounted; not the kernel's list of currently active mounts.

startup

These standard targets are (indirectly) started by the init subcommand.

shutdown

The poweroff, powercycle, halt, and reboot subcommands invoke several standard targets indirectly.

For example: When system-manager(8) is process #1, system halt operates as follows:

Other standard targets are started by telinit(1).

service collections

User-supplied services and targets that are auto-started at system bootstrap should list themselves in the wants/ and conflicts/ lists of subordinate targets (via the enable and disable subcommands). These targets are usually not started explicitly.

core subordinate targets

Core services and targets are incorporated into a set of further subordinate targets.