3.2 Invoking herd ¶

The herd command is a generic client program to control a running instance of shepherd (see Invoking shepherd). When running as root, it communicates with the system instance—the process with PID 1; when running as a normal user, it communicates with the user’s instance, which is a regular, unprivileged process managing the user’s own services. For example, the following command displays the status of all the system services:

sudo herd status

Conversely, the command below displays the status of user services, assuming a user shepherd is running:

herd status

The command has the following synopsis:

herd [option...] action [service [arg...]]

It causes the action of the service to be invoked. When service is omitted and action is status or detailed-status, the root service is used⁴ (see The root Service, for more information on the root service.)

For each action, you should pass the appropriate args. Actions that are available for every service are start, stop, restart, status, enable, disable, and doc.

If you pass a file name as an arg, it will be passed as-is to the Shepherd, thus if it is not an absolute name, it is local to the current working directory of shepherd, not to herd.

The herd command understands the following option:

‘-s file’

‘--socket=file’

Send commands to the socket special file file. If this option is not specified, localstatedir/run/shepherd/socket is taken.

‘-n number’

‘--log-history=number’

Display up to number lines of the of service when running:

herd status service -n number

By default up to ten lines are printed.

In addition, the options below are understood by service actions that spawn other processes or services, such as herd schedule timer (see timer-service) and herd spawn transient (see Transient Service Maker).

‘--user=user’

‘--group=group’

Run the process under the specified user and group.

‘-d directory’

‘--working-directory=directory’

Run the process or service from directory.

‘-E environment’

‘--environment-variable=environment’

Add environment to the environment variables of the service, where environment has the form variable=value.

‘-N name’

‘--service-name=name’

Register the service under name.

‘--log-file=file’

Log service output to file.

The herd command returns zero on success, and a non-zero exit code on failure. In particular, it returns a non-zero exit code when action or service does not exist and when the given action failed.