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.

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.