\input texinfo @c -*- texinfo -*-
@c shepherd.texi -- The documentation in Texinfo format.
@documentencoding UTF-8
@setfilename shepherd.info
@settitle The GNU Shepherd Manual

@include version.texi
@set OLD-YEARS 2002, 2003
@set NEW-YEARS 2013, 2016, 2018--2020, 2022--2025

@copying
Copyright @copyright{} @value{OLD-YEARS} Wolfgang J@"ahrling@*
Copyright @copyright{} @value{NEW-YEARS} Ludovic Courtès@*
Copyright @copyright{} 2020 Brice Waegeneire@*
Copyright @copyright{} 2020 Oleg Pykhalov@*
Copyright @copyright{} 2020, 2023 Jan (janneke) Nieuwenhuizen@*
Copyright @copyright{} 2024 Jakob Kirsch@*

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying

@dircategory System software
@direntry
* shepherd: (shepherd). The Shepherd service manager.
* herd: (shepherd)Invoking herd
                        Controlling the Shepherd service manager.
* reboot: (shepherd)Invoking reboot
                        Rebooting a Shepherd-controlled system.
* halt: (shepherd)Invoking halt
                        Turning off a Shepherd-controlled system.
@end direntry

@titlepage
@title The GNU Shepherd Manual
@subtitle For use with the GNU Shepherd @value{VERSION}
@subtitle Last updated @value{UPDATED}

@author Wolfgang J@"ahrling
@author Ludovic Courtès

@insertcopying
@end titlepage

@contents


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@ifnottex
@node Top
@top The GNU Shepherd Manual

This manual documents the GNU@tie{}Shepherd version @value{VERSION}, a
service manager for the GNU system.

@menu
* Introduction::                Introduction to the Shepherd service manager.
* Jump Start::                  How to do simple things with the Shepherd.
* herd and shepherd::           User interface to service management.
* Services::                    Details on services.
* Service Collection::          Services that come with the Shepherd.
* Misc Facilities::             Generally useful things provided by the Shepherd.
* Internals::                   Hacking shepherd.

* GNU Free Documentation License::  The license of this manual.
* Concept Index::
* Procedure and Macro Index::
* Variable Index::
* Type Index::
@end menu
@end ifnottex

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Introduction
@chapter Introduction

@cindex service manager
This manual documents the GNU@tie{}Daemon Shepherd, or GNU@tie{}Shepherd
for short.  The Shepherd looks after system services, typically @dfn{daemons}.
It is used to start and stop them in a reliable
fashion.  For instance, it will dynamically determine and start any
other services that our desired service depends upon.

The Shepherd is the @dfn{init system} of the GNU operating system---it is the
first user process that gets started, typically with PID 1, and runs
as @code{root}.  Normally the purpose of init systems is to manage all
system-wide services, but the Shepherd can also be a useful tool assisting
unprivileged users in the management of their own daemons.

Flexible software requires some time to master and
the Shepherd is no different.  But don't worry: this manual should allow you to
get started quickly.  Its first chapter is designed as a practical
introduction to the Shepherd and should be all you need for everyday use
(@pxref{Jump Start}).  In chapter two we will describe the
@command{herd} and @command{shepherd} programs, and their relationship, in
more detail (@ref{herd and shepherd}).  Subsequent chapters provide a full
reference manual and plenty of examples, covering all of Shepherd's
capabilities.  Finally, the last chapter provides information for
those souls brave enough to hack the Shepherd itself.

@cindex dmd
The Shepherd was formerly known as ``dmd'', which stands for @dfn{Daemon
Managing Daemons} (or @dfn{Daemons-Managing Daemon}?).

@cindex Guile
@cindex Scheme
This program is written in Guile Scheme.  Guile is also the Shepherd's
configuration language.  @xref{Introduction,,, guile, GNU Guile
Reference Manual}, for an introduction to Guile.  We have tried to make
the Shepherd's basic features as accessible as possible---you should be
able to use these even if you do not know how to program in Scheme.  A
basic grasp of Guile is required only if you wish to make use of the
Shepherd's more advanced features.

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Jump Start
@chapter Jump Start

The Shepherd comes with two main commands: @command{shepherd}, which is
the daemon that manages services (@pxref{Invoking shepherd}), and
@command{herd}, the command to monitor and control @command{shepherd}
(@pxref{Invoking herd}).  The @command{shepherd} command itself may run
as an ``init system'', also known as PID@tie{}1@footnote{In that case it
is the first process started by the system, hence the process identifier
(PID) 1.}, where it manages system services, or as a user, where it
manages user services.

As a user and system administrator, the @command{herd} command is your
main entry point; it allows you to get an overview of the services and
their status:

@example
herd status
@end example

@noindent
... to get detailed information about a specific service, including
recently-logged messages:

@example
herd status sshd
@end example

@noindent
... and to start, stop, restart, enable, or disable services, among
other possible actions:

@example
herd start nginx
herd stop tor
herd disable tor
herd restart guix-daemon
@end example

@cindex service graph
@cindex graph of services
Each service may depend on other services.  Services and their
dependencies form a @dfn{graph}, which you can view, for instance with
the help of @uref{https://github.com/jrfonseca/xdot.py, xdot}, by
running:

@example
herd graph | xdot -
@end example

Since @command{shepherd} knows about these dependencies, the
@command{herd start nginx} command above starts not just the
@code{nginx} service, but also every service it depends on.  Likewise,
@command{herd stop tor} stops not just @code{tor} but also everything
that depends on it.

Services may define @dfn{custom actions} in addition to @code{start},
@code{stop}, and the other actions mentioned above.  For example, the
@code{log-rotation} service has a custom @code{files} action to list log
files subject to rotation (@pxref{Log Rotation Service}):

@example
herd files log-rotation
@end example

A special service is @code{root}, which is used for controlling the
Shepherd itself (@pxref{The root Service}).  Its @code{status} action
displays info about the @command{shepherd} process, including messages
it recently logged, possibly on behalf of other services:

@example
herd status root
@end example

The @code{load} action of @code{root} lets you dynamically load new
service definitions from a configuration file, which we'll discuss
later; note that this action takes the file name as an extra argument:

@example
herd load root ~/additional-services.scm
@end example

To view a log of service events, including the time at which each
service was started or stopped, run:

@example
herd log
@end example

Last, you can view documentation about services and their actions:

@example
$ herd doc root
The root service is used to operate on shepherd itself.
$ herd doc root action power-off
power-off: Halt the system and turn it off.
@end example

That's pretty much all there is to know from the user and system
administrator viewpoint.

Packagers, distro developers, and advanced system administrator,
certainly noticed that we haven't talked about a crucial aspect for
them: the configuration file for @command{shepherd}.  That's certainly
the most interesting and unique bit of the Shepherd: @emph{configuration
is a Scheme program}.  You do not need to be an expert in the Scheme
programming language to write it though: for common uses, configuration
is entirely declarative and contains the same information you would find
in a systemd @file{.service} file or anything similar.  You can define
services that spawn a process, others that wait for incoming connections
and pass it on to a daemon (inetd-style or systemd-style @dfn{socket
activation}), as well as timed services that run a program periodically.
@xref{Service Examples}, to get started.

@cindex extensibility
What's interesting is that you can go beyond the kind of services
Shepherd offers you: You need a service that mounts/unmounts file
systems? A service that sets up networking?  One that runs a daemon in a
container?  This is where extensibility shines: you can write services
that do this---and more.  @xref{Defining Services}, for a reference of
the programming interface to define services.  And, whether or not you
use Guix System, check out the variety of services it provides
(@pxref{Services,,, guix, GNU Guix Reference Manual}).

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node herd and shepherd
@chapter @command{herd} and @command{shepherd}

@cindex herd
@cindex shepherd
@cindex daemon
@cindex daemon controller
@cindex relative file names
@cindex herding, of daemons
The daemon that runs in the background and is responsible for
controlling the services is @command{shepherd}, while the user interface
tool is called @command{herd}: it's the command that allows you to
actually @emph{herd} your daemons@footnote{
@cindex deco, daemon controller
In the past, when the
GNU@tie{}Shepherd was known as GNU@tie{}dmd, the @command{herd} command
was called @code{deco}, for @dfn{DaEmon COntroller}.}.  To perform an
action, like stopping a service or calling an action of a service, you
use the herd program.  It will communicate with shepherd over a Unix
Domain Socket.

Thus, you start @command{shepherd} once, and then always use
@command{herd} whenever you want to do something service-related.  Both
@command{shepherd} and @command{herd} understand the standard arguments
@code{--help}, @code{--version} and @code{--usage}.


@menu
* Invoking shepherd::           How to start the service damon.
* Invoking herd::               Controlling daemons.
* Invoking reboot::             Rebooting a shepherd-controlled system.
* Invoking halt::               Turning off a shepherd-controlled system.
@end menu

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Invoking shepherd
@section Invoking @command{shepherd}

@cindex @command{shepherd} Invocation
@cindex invoking @command{shepherd}
The @code{shepherd} program has the following synopsis:

@example
shepherd [@var{option}@dots{}]
@end example

@cindex configuration file
When @command{shepherd} starts, it reads and evaluates a configuration
file---actually a Scheme program that uses the Shepherd's programming
interface to define, register, and start services (@pxref{Defining
Services}).  When it is started with superuser privileges, it tries to
read @code{/etc/shepherd.scm}; when started as a unprivileged user, it
looks for a file called @code{$XDG_CONFIG_HOME/shepherd/init.scm}.  If
the @env{XDG_CONFIG_HOME} environment variable is undefined,
@code{$HOME/.config/shepherd/init.scm} is used instead (@pxref{Managing
User Services}).  The @option{--config} option described below lets you
choose a different file.

@cindex socket file, for @command{shepherd}
As the final ``d'' suggests, @command{shepherd} is a daemon that runs in
the background, so you will not interact with it directly.  After it is
started, @command{shepherd} listens on a socket, usually
@file{/var/run/shepherd/socket} (this can be changed with the
@option{--socket} option or the @env{SHEPHERD_SOCKET} environment
variable).  The @dfn{herd} tool sends commands to @command{shepherd}
using this socket (@pxref{Invoking herd}).

The @command{shepherd} command accepts the following options:

@cindex configuration file
@table @samp
@item -c @var{file}
@itemx --config=@var{file}
Read and evaluate @var{file} as the configuration file on startup.

Scheme code in @var{file} is evaluated in the context of a fresh module
where bindings from the @code{(shepherd service)} module are available,
in addition to the default set of Guile bindings.  It may typically
perform three actions:

@enumerate
@item
defining services using the @code{service} procedure (@pxref{Defining
Services});
@item
registering those services with @code{register-services} (@pxref{Service
Registry});
@item
starting some or all of those services with
@code{start-in-the-background} (@pxref{Interacting with Services}).
@end enumerate

@xref{Service Examples}, for examples of what @var{file} might look
like.

Note that @var{file} is evaluated @emph{asynchronously}:
@command{shepherd} may start listening for client connections (with the
@command{herd} command) before @var{file} has been fully loaded.  Errors
in @var{file} such as service startup failures or uncaught exceptions do
@emph{not} cause @command{shepherd} to stop.  Instead the error is
reported, leaving users the opportunity to inspect service state and,
for example, to load an updated config file with:

@example
herd load root @var{file}
@end example

@item -I
@itemx --insecure
@cindex security
@cindex insecure
Do not check if the directory where the socket---our communication
rendez-vous with @command{herd}---is located has permissions @code{700}.
If this option is not specified, @command{shepherd} will abort if the
permissions are not as expected.

@item -l [@var{file}]
@itemx --logfile[=@var{file}]
@cindex logging
@cindex log file
Log output into @var{file}.

For unprivileged users, the default log file is
@file{$XDG_STATE_HOME/shepherd/shepherd.log} with @file{$XDG_STATE_HOME}
defaulting to @file{$HOME/.local/state}.

@item --syslog[=@var{file}]
@cindex syslog
Force logging to @var{file} (@file{/dev/log} by default), a @dfn{syslog}
socket (@pxref{Overview of Syslog,,, libc, The GNU C Library Reference
Manual}).

When running as root, the default behavior is to connect to
@file{/dev/log}.  A syslog daemon,
@command{syslogd}, is expected to read messages from there
(@pxref{syslogd invocation, syslogd,, inetutils, GNU Inetutils}).

When @file{/dev/log} is unavailable, for instance because
@command{syslogd} is not running, as is the case during system startup
and shutdown, @command{shepherd} falls back to the Linux kernel
@dfn{ring buffer}, @file{/dev/kmsg}.  If @file{/dev/kmsg} is missing, as
is the case on other operating systems, it falls back to
@file{/dev/console}.

@item --pid[=@var{file}]
When @command{shepherd} is ready to accept connections, write its PID to @var{file} or
to the standard output if @var{file} is omitted.

@item -s @var{file}
@itemx --socket=@var{file}
@cindex socket special file
Receive further commands on the socket special file @var{file}.

@vindex XDG_RUNTIME_DIR
If this
option is not specified, @file{@var{localstatedir}/run/shepherd/socket} is
taken when running as @code{root}; when running as an unprivileged
user, @command{shepherd} listens to @file{/run/user/@var{uid}/shepherd/socket},
where @var{uid} is the user's numerical ID@footnote{On GNU/Linux, the
@file{/run/user/@var{uid}} directory is typically created by elogind or by
systemd, which are available in most distributions.}, or to
@file{$XDG_RUNTIME_DIR/shepherd} when the @code{XDG_RUNTIME_DIR}
environment variable is defined.

@quotation Note
If the listening socket is deleted, it becomes impossible to control
@command{shepherd}.  Thus, upon deletion, @command{shepherd} tries to
reopen the socket (when running as PID@tie{}1) or shuts down (when
running as an unprivileged user).

The latter behavior is useful when the listening socket is under
@file{/run/user/@var{uid}} (the default) since that directory is usually
deleted as soon as the user session terminates.
@end quotation

@item -S
@itemx --silent
Don't do output to stdout.

@item --quiet
Synonym for @code{--silent}.

@end table

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Invoking herd
@section Invoking @command{herd}

@cindex herd
The @command{herd} command is a generic client program to control a
running instance of @command{shepherd} (@pxref{Invoking shepherd}).
When running as root, it communicates with the @dfn{system
instance}---the process with PID@tie{}1; when running as a normal user,
it communicates with the @dfn{user's instance}, which is a regular,
unprivileged process managing the user's own services (this can be
changed by passing the @option{--socket} option or by setting the
@env{SHEPHERD_SOCKET} environment variable).  For example, the following
command displays the status of all the @dfn{system services}:

@example
sudo herd status
@end example

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

@example
herd status
@end example

The command has the following synopsis:

@example
herd [@var{option}@dots{}] @var{action} [@var{service} [@var{arg}@dots{}]]
@end example

It causes the @var{action} of the @var{service} to be invoked.  When
@var{service} is omitted and @var{action} is @code{status} or
@code{detailed-status}, the @code{root} service is used@footnote{This
shorthand does not work for other actions such as @code{stop}, because
inadvertently typing @code{herd stop} would stop all the services, which
could be pretty annoying.} (@pxref{The root Service}, for
more information on the @code{root} service.)

For each action, you should pass the appropriate @var{arg}s.  Actions
that are available for every service are @code{start}, @code{stop},
@code{restart}, @code{status}, @code{enable}, @code{disable}, and
@code{doc}.

If you pass a file name as an @var{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 @command{shepherd}, not to that of @command{herd}.

The @code{herd} command understands the following option:

@table @samp

@item -s @var{file}
@itemx --socket=@var{file}
Send commands to the socket special file @var{file}. If this option is
not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.

@item -n @var{number}
@itemx --log-history=@var{number}
Display up to @var{number} lines of the of @var{service} when running:

@example
herd status @var{service} -n @var{number}
@end example

By default up to ten lines are printed.
@end table

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

@table @samp

@item --user=@var{user}
@itemx --group=@var{group}
Run the process under the specified @var{user} and @var{group}.

@item -d @var{directory}
@itemx --working-directory=@var{directory}
Run the process or service from @var{directory}.

@item -E @var{environment}
@itemx --environment-variable=@var{environment}
Add @var{environment} to the environment variables of the service, where
@var{environment} has the form @code{@var{variable}=@var{value}}.

@item -N @var{name}
@itemx --service-name=@var{name}
Register the service under @var{name}.

@item --log-file=@var{file}
Log service output to @var{file}.

@end table

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


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Invoking reboot
@section Invoking @command{reboot}

@cindex herd
The @command{reboot} command is a convenience client program to instruct
the Shepherd (when used as an init system) to stop all running services and
reboot the system.  It has the following synopsis:

@example
reboot [@var{option}@dots{}]
@end example

It is equivalent to running @command{herd stop shepherd}.  The
@code{reboot} command understands the following option:

@table @samp

@item -s @var{file}
@itemx --socket=@var{file}
Send commands to the socket special file @var{file}. If this option is
not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.

@cindex kexec, rebooting into a new Linux kernel
@cindex rebooting into a new Linux kernel with kexec
@item -k
@itemx --kexec
Reboot the system using Linux's kexec (this is equivalent to running
@command{herd kexec root}).  The kernel that was previously loaded using
the @command{kexec -l @var{file}} command is executed directly instead
of rebooting into the BIOS, keeping the downtime to a minimum.  See the
@uref{https://linux.die.net/man/8/kexec, @command{kexec} command
documentation} for more information.

This feature is only available on Linux-based systems.  It has no effect
on systems where kexec is unsupported or when no system was loaded for
eventual kexec reboot.  Last, if kexec reboot fails at run time,
@command{shepherd} falls back to normal reboot.

@end table

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Invoking halt
@section Invoking @command{halt}

@cindex herd
The @command{halt} command is a convenience client program to instruct
the Shepherd (when used as an init system) to stop all running services and turn
off the system.  It has the following synopsis:

@example
halt [@var{option}@dots{}]
@end example

It is equivalent to running @command{herd power-off shepherd}.  As
usual, the @code{halt} command understands the following option:

@table @samp

@item -s @var{file}
@itemx --socket=@var{file}
Send commands to the socket special file @var{file}. If this option is
not specified, @file{@var{localstatedir}/run/shepherd/socket} is taken.

@end table


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Services
@chapter Services

@cindex service
@tindex <service>
The @dfn{service} is obviously a very important concept of the Shepherd.
On the Guile level, a service is represented as a record of type
@code{<service>}.  Each service has a number of properties that you
specify when you create it: how to start it, how to stop it, whether to
respawn it when it stops prematurely, and so on.  At run time, each
service has associated @dfn{state}: whether it is running or stopped,
what PID or other value is associated with it, and so on.

This section explains how to define services and how to query their
configuration and state using the Shepherd's programming interfaces.

@quotation Note
The programming interface defined in this section may only be used
within a @command{shepherd} process.  Examples where you may use it
include:

@itemize
@item
the @command{shepherd} configuration file (@pxref{Service Examples});
@item
as an argument to @command{herd eval root @dots{}} (@pxref{The root
Service});
@item
at the REPL (@pxref{REPL Service}).
@end itemize

These procedures may not be used in Guile processes other than
@command{shepherd} itself.
@end quotation

@menu
* Defining Services::           Defining services.
* Service Registry::            Mapping service names to records.
* Interacting with Services::   Accessing service state.
* Service De- and Constructors::  Commonly used ways of starting and
                                   stopping services.
* Timers::                      Timed services.
* The root Service::            The service that comes first.
* Legacy GOOPS Interface::      Former interface and how to migrate.
* Service Examples::            Examples that show how services are used.
* Managing User Services::      Running the Shepherd as a user.
@end menu

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Defining Services
@section Defining Services

A service is created by calling the @code{service} procedure, from the
@code{(shepherd service)} module (automatically visible from your
configuration file), as in this example:

@lisp
(service
  '(sshd ssh-daemon)  ;for convenience, give it two names
  #:start (make-forkexec-constructor
           '("/usr/sbin/sshd" "-D")
           #:pid-file "/etc/ssh/sshd.pid")
  #:stop (make-kill-destructor)
  #:respawn? #t)
@end lisp

The example above creates a service with two names, @code{sshd} and
@code{ssh-daemon}.  It is started by invoking @command{/usr/sbin/sshd},
and it is considered up and running as soon as its PID file
@file{/etc/ssh/sshd.pid} is available.  It is stopped by terminating the
@command{sshd} process.  Finally, should @command{sshd} terminate
prematurely, it is automatically respawned.  We will look at
@code{#:start} and @code{#:stop} later (@pxref{Service De- and
Constructors}), but first, here is the reference of the @code{service}
procedure and its optional keyword arguments.

@deffn {Procedure} service @var{provision} @
  [#:requirement '()] [#:one-shot? #f] [#:transient? #f] @
  [#:respawn? #f] [#:start (const #t)] [#:stop (const #f)] @
  [#:actions (actions)] @
  [#:termination-handler default-service-termination-handler] @
  [#:documentation #f]
@cindex canonical name of services
Return a new service with the given @var{provision}, a list of symbols
denoting what the service provides.  The first symbol in the list is the
@dfn{canonical name} of the service, thus it must be unique.

The meaning of keyword arguments is as follows:

@table @code
@item #:requirement
@code{#:requirement} is, like @var{provision}, a list of symbols that
specify services.  In this case, they name what this service depends on:
before the service can be started, services that provide those symbols
must be started.

Note that every name listed in @code{#:requirement} must be registered
so it can be resolved (@pxref{Service Registry}).

@item #:respawn?
@cindex respawning services
Specify whether the service should be respawned by @command{shepherd}.
If this slot has the value @code{#t}, then, assuming the service has an
associated process (its ``running value'' is a PID), restart the service
if that process terminates.

There is a limit to avoid endless respawning: when the service gets
respawned ``too fast'', it is @dfn{disabled}---see
@code{#:respawn-limit} below.

@cindex respawn delay
@item #:respawn-delay
Specify the delay before a service is respawned, in seconds (including a
fraction), for services marked with @code{#:respawn? #t}.  Its default
value is @code{(default-respawn-delay)} (@pxref{Service De- and
Constructors}).

@cindex respawn limit
@item #:respawn-limit
Specify the limit that prevents @command{shepherd} from respawning too
quickly the service marked with @code{#:respawn? #t}.  Its default value
is @code{(default-respawn-limit)} (@pxref{Service De- and
Constructors}).

The limit is expressed as a pair of integers: the first integer,
@var{n}, specifies a number of consecutive respawns and the second
integer, @var{t}, specifies a number of seconds.  If the service gets
respawned more than @var{n} times over a period of @var{t} seconds, it
is automatically @dfn{disabled} (@pxref{Interacting with Services,
@code{service-enabled?}}).  Once it is disabled, the service must be
explicitly re-enabled using @command{herd enable @var{service}} before
it can be started again.

Consider the service below:

@lisp
(service '(xyz)
         #:start (make-forkexec-constructor @dots{})
         #:stop (make-kill-destructor)
         #:respawn? #t
         #:respawn-limit '(3 . 5))
@end lisp

The effect is that this service will be respawned at most 3 times over a
period of 5 seconds; if its associated process terminates a fourth time
during that period, the service will be marked as disabled.

@item #:one-shot?
@cindex one-shot services
Whether the service is a @dfn{one-shot service}.  A one-shot service is
a service that, as soon as it has been successfully started, is marked
as ``stopped.''  Other services can nonetheless require one-shot
services.  One-shot services are useful to trigger an action before
other services are started, such as a cleanup or an initialization
action.

As for other services, the @code{start} method of a one-shot service must
return a truth value to indicate success, and false to indicate failure.

@item #:transient?
@cindex transient services
Whether the service is a @dfn{transient service}.  A transient service
is automatically unregistered when it terminates, be it because its
@code{stop} method is called or because its associated process
terminates.

This is useful in the uncommon case of synthesized services that may not
be restarted once they have completed.

@item #:start
@cindex constructor of a service
@cindex starting a service
Specify the @dfn{constructor} of the service, which will be called to
start the service.  This must be a procedure that accepts any number of
arguments; those arguments will be those supplied by the user, for
instance by passing them to @command{herd start}.  If the starting
attempt failed, it must return @code{#f} or throw an exception;
otherwise, the return value is stored as the @dfn{running value} of the
service.

@quotation Note
Constructors must terminate, successfully or not, in a timely fashion,
typically less than a minute.  Failing to do that, the service would
remain in ``starting'' state and users would be unable to stop it.
@end quotation

@xref{Service De- and Constructors}, for info on common service constructors.

@item #:stop
@cindex stopping a service
@cindex destructor of a service
This is the service @dfn{destructor}: a procedure of one or more
arguments that should stop the service.  It is called whenever the user
explicitly stops the service; its first argument is the running value of
the service, subsequent arguments are user-supplied.  Its return value
will again be stored as the running value, so it should
return @code{#f} if it is now possible again to start the service at a
later point.

@quotation Note
Destructors must also terminate in a timely fashion, typically less than
a minute.  Failing to do that, the service would remain in ``stopping''
state and users would be unable to stop it.
@end quotation

@xref{Service De- and Constructors}, for info on common service
destructors.

@item #:termination-handler
@cindex termination of a service's process
The procedure to call when the process associated with the service
terminates.  It is passed the service, the PID of the terminating
process, and its exit status, an integer as returned by @code{waitpid}
(@pxref{Processes, @code{waitpid},, guile, GNU Guile Reference Manual}).

The default handler is the @code{default-service-termination-handler}
procedure, which respawns the service if applicable.

@item #:actions
@cindex actions of services
@cindex service actions
The additional actions that can be performed on the service when it is
running.  A typical example for this is the @code{restart} action.  The
@code{actions} macro can be used to defined actions (see below).
@end table
@end deffn

A special service that every other service implicitly depends on is the
@code{root} (also known as @code{shepherd}) service.  @xref{The root
Service}, for more information.

@cindex graph of services
Services and their dependencies form a @dfn{graph}.  At the
command-line, you can view that export a representation of that graph
that can be consumed by any application that understands the Graphviz
format, such as @uref{https://github.com/jrfonseca/xdot.py, xdot}:

@example
herd graph | xdot -
@end example

Service actions are defined using the @code{action} procedure or the
@code{actions} (plural) macro, as shown below.

@deffn {Procedure} action @var{name} @var{proc} [@var{doc}]
Return a new action with the given @var{name}, a symbol, that executes
@var{proc}, a one-argument procedure that is passed the service's running
value.  Use @var{doc} as the documentation of that action.
@end deffn

@defmac actions (name proc) @dots{}
Create a value for the @code{#:actions} parameter of @code{service}.
Each @var{name} is a symbol and each @var{proc} the corresponding
procedure that will be called to perform the action.  A @var{proc} has
one argument, which will be the running value of the service.
@end defmac

Naturally, the @code{(shepherd service)} provides procedures to access
this information for a given service object:

@deffn {Procedure} service-provision @var{service}
Return the symbols provided by @var{service}.
@end deffn

@deffn {Procedure} service-canonical-name @var{service}
Return the @dfn{canonical name} of @var{service}, which is the first
element of the list returned by @code{service-provision}.
@end deffn

@deffn {Procedure} service-requirement @var{service}
Return the list of services required by @var{service} as a list of
symbols.
@end deffn

@deffn {Procedure} one-shot-service? @var{service}
@deffnx {Procedure} transient-service? @var{service}
Return true if @var{service} is a one-shot/transient service.
@end deffn

@deffn {Procedure} respawn-service? @var{service}
Return true if @var{service} is meant to be respawned if its associated
process terminates prematurely.
@end deffn

@deffn {Procedure} service-respawn-delay @var{service}
Return the respawn delay of @var{service}, in seconds (an integer or a
fraction or inexact number).  See @code{#:respawn-delay} above.
@end deffn

@deffn {Procedure} service-respawn-limit @var{service}
Return the respawn limit of @var{service}, expressed as a pair---see
@code{#:respawn-limit} above.
@end deffn

@deffn {Procedure} service-documentation @var{service}
Return the documentation (a string) of @var{service}.
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Service Registry
@section Service Registry

@cindex service registry
At run time, @command{shepherd} maintains a @dfn{service registry} that
maps service names to service records.  Service dependencies are
expressed as a list of names passed as @code{#:requirement} to the
@code{service} procedure (@pxref{Defining Services}); these names are
looked up in the registry.  Likewise, when running @code{herd start
sshd} or similar commands (@pxref{Jump Start}), the service name is
looked up in the registry.

Consequently, every service must be appear in the registry before it can
be used.  A typical configuration file thus includes a call to the
@code{register-services} procedure (@pxref{Service Examples}).  The
following procedures let you interact with the registry.

@deffn {Procedure} register-services @var{services}
Register @var{services} so that they can be looked up by name, for instance
when resolving dependencies.

Each name uniquely identifies one service.  If a service with a given name has
already been registered, arrange to have it replaced when it is next stopped.
If it is currently stopped, replace it immediately.
@end deffn

@deffn {Procedure} unregister-services @var{services}
Remove all of @var{services} from the registry, stopping them if they are not
already stopped.
@end deffn

@deffn {Procedure} lookup-service @var{name}
Return the service that provides @var{name}, @code{#f} if there is none.
@end deffn

@deffn {Procedure} for-each-service @var{proc}
Call @var{proc}, a procedure taking one argument, once for each
registered service.
@end deffn

@deffn {Procedure} lookup-running @var{name}
Return the running service that provides @var{name}, or false if none.
@end deffn


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Interacting with Services
@section Interacting with Services

What we have seen so far is the interface to @emph{define} a service and
to access it (@pxref{Defining Services}).  The procedures below, also
exported by the @code{(shepherd service)} module, let you modify and
access the state of a service.  You may use them in your configuration
file, for instance to start some or all of the services you defined
(@pxref{Service Examples}).

Under the hood, each service record has an associated @dfn{fiber}
(really: an actor) that encapsulates its state and serves user
requests---a fiber is a lightweight execution thread (@pxref{Service
Internals}).

The procedures below let you change the state of a service.

@deffn {Procedure} start-service @var{service} . @var{args}
Start @var{service} and its dependencies, passing @var{args} to its
@code{start} method.  Return its running value, @code{#f} on failure.
@end deffn

@deffn {Procedure} stop-service @var{service} . @var{args}
Stop @var{service} and any service that depends on it.  Return the list of
services that have been stopped (including transitive dependent services).

If @var{service} is not running, print a warning and return its canonical name
in a list.
@end deffn

@deffn {Procedure} perform-service-action @var{service} @var{the-action} . @var{args}
Perform @var{the-action} (a symbol such as @code{'restart} or @code{'status})
on @var{service}, passing it @var{args}.  The meaning of @var{args} depends on
the action.
@end deffn

The @code{start-in-the-background} procedure, described below, is
provided for your convenience: it makes it easy to start a set of
services right from your configuration file, while letting
@command{shepherd} run in the background.

@deffn {Procedure} start-in-the-background @var{services}
Start the services named by @var{services}, a list of symbols, in the
background.  In other words, this procedure returns immediately without
waiting until all of @var{services} have been started.

This procedure can be useful in a configuration file because it lets you
interact right away with shepherd using the @command{herd} command.
@end deffn

The following procedures let you query the current state of a service.

@deffn {Procedure} service-running? @var{service}
@deffnx {Procedure} service-stopped? @var{service}
@deffnx {Procedure} service-enabled? @var{service}
Return true if @var{service} is currently running/stopped/enabled, false
otherwise.
@end deffn

@deffn {Procedure} service-status @var{service}
Return the status of @var{service} as a symbol, one of: @code{'stopped},
@code{'starting}, @code{'running}, or @code{'stopping}.
@end deffn

@deffn {Procedure} service-running-value @var{service}
Return the current ``running value'' of @var{service}---a Scheme value
associated with it.  It is @code{#f} when the service is stopped;
otherwise, it is a truth value, such as an integer denoting a PID
(@pxref{Service De- and Constructors}).
@end deffn

@deffn {Procedure} service-status-changes @var{service}
Return the list of symbol/timestamp pairs representing recent state
changes for @var{service}.
@end deffn

@deffn {Procedure} service-startup-failures @var{service}
@deffnx {Procedure} service-respawn-times @var{service}
Return the list of startup failure times or respawn times of
@var{service}.
@end deffn

@deffn {Procedure} service-process-exit-statuses @var{services}
Return the list of last exit statuses of @var{service}'s main process
(most recent first).
@end deffn

@cindex replacement, or a service
@deffn {Procedure} service-replacement @var{service}
Return the @dfn{replacement} of @var{service}, or @code{#f} if there is
none.

The replacement is the service that will replace @var{service} when it
is eventually stopped.
@end deffn

@deffn {Procedure} service-recent-messages @var{service}
Return a list of messages recently logged by @var{service}---typically
lines written by a daemon on standard output.  Each element of the list
is a timestamp/string pair where the timestamp is the number of seconds
since January 1st, 1970 (an integer).
@end deffn

@deffn {Procedure} service-log-file @var{service}
Return the file where messages by @var{service} are logged, or @code{#f}
if there is no such file, for instance because @var{service}'s output is
logged by some mechanism not under shepherd's control.
@end deffn

@xref{Service Internals}, if you're curious about the nitty-gritty
details!


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Service De- and Constructors
@section Service De- and Constructors

@cindex generating constructors
@cindex generating destructors
@cindex constructors, generation of
@cindex destructors, generation of
Each service has a @code{start} procedure and a @code{stop} procedure,
also referred to as its @dfn{constructor} and @dfn{destructor}
(@pxref{Services}).  The procedures listed below return procedures that
may be used as service constructors and destructors.  They are flexible
enough to cover most use cases and carefully written to complete in a
timely fashion.

@deffn {Procedure} make-forkexec-constructor @var{command} @
  [#:user #f] @
  [#:group #f] @
  [#:supplementary-groups '()] @
  [#:pid-file #f] [#:pid-file-timeout (default-pid-file-timeout)] @
  [#:input-port #f] @
  [#:log-file #f] @
  [#:directory (default-service-directory)] @
  [#:file-creation-mask #f] [#:create-session? #t] @
  [#:resource-limits '()] @
  [#:environment-variables (default-environment-variables)]
Return a procedure that forks a child process, closes all file
descriptors except the standard output and standard error descriptors,
sets the current directory to @var{directory}, sets the umask to
@var{file-creation-mask} unless it is @code{#f}, changes the environment
to @var{environment-variables} (using the @code{environ} procedure),
sets the current user to @var{user} the current group to @var{group}
unless they are @code{#f} and supplementary groups to
@var{supplementary-groups} unless they are @code{'()}, and executes
@var{command} (a list of strings.)  When
@var{input-port} is set, it refers to a port that is used as the standard input
of the created child process (@file{/dev/null} is used by default).  When
@var{create-session?} is true, the child process creates a new session with
@code{setsid} and becomes its leader.  The result of the procedure will be the
@code{<process>} record representing the child process.

@quotation Note
This will not work as expected if the process ``daemonizes'' (forks); in
that case, you will need to pass @code{#:pid-file}, as explained below.
@end quotation

When @var{pid-file} is true, it must be the name of a PID file
associated with the process being launched; the return value is the PID
once that file has been created.  If @var{pid-file} does not show up in less
than @var{pid-file-timeout} seconds, the service is considered as failing to
start.

When @var{log-file} is true, it names the file to which the service's
standard output and standard error are redirected.  @var{log-file} is
created if it does not exist, otherwise it is appended to.

@quotation Note
@xref{Log Rotation Service}, for a service to rotate log files specified
via the @code{#:log-file} parameter.
@end quotation

Guile's @code{setrlimit} procedure is applied on the entries in
@var{resource-limits}.  For example, a valid value would be:

@lisp
'((nproc 10 100)         ;number of processes
  (nofile 4096 4096))    ;number of open file descriptors
@end lisp
@end deffn

@deffn {Procedure} make-kill-destructor [@var{signal}] @
  [#:grace-period (default-process-termination-grace-period)]
Return a procedure that sends @var{signal} to the process group of the PID
given as argument, where @var{signal} defaults to @code{SIGTERM}.  If the
process is still running after @var{grace-period} seconds, send it
@code{SIGKILL}.  The procedure returns once the process has terminated.

This @emph{does} work together with respawning services,
because in that case the @code{stop} method of the @code{<service>}
arranges so that the service is not respawned.
@end deffn

@anchor{exec-command}
The @code{make-forkexec-constructor} procedure builds upon the following
procedures.

@deffn {Procedure} exec-command @var{command} @
  [#:user #f] @
  [#:group #f] @
  [#:supplementary-groups '()] @
  [#:log-file #f] [#:log-port #f] [#:input-port #f] @
  [#:directory (default-service-directory)] @
  [#:file-creation-mask #f] [#:create-session? #t] @
  [#:resource-limits '()] @
  [#:environment-variables (default-environment-variables)]
@deffnx {Procedure} fork+exec-command @var{command} @
  [#:user #f] @
  [#:group #f] @
  [#:supplementary-groups '()] @
  [#:input-port #f] @
  [#:log-file #f] [#:log-encoding "UTF-8"] @
  [#:directory (default-service-directory)] @
  [#:file-creation-mask #f] [#:create-session? #t] @
  [#:resource-limits '()] @
  [#:environment-variables (default-environment-variables)]
Run @var{command} as the current process from @var{directory}, with
@var{file-creation-mask} if it's true, with @var{rlimits}, and with
@var{environment-variables} (a list of strings like @code{"PATH=/bin"}.)
File descriptors 1 and 2 are kept as is or redirected to
either @var{log-port} or @var{log-file}
if it's true, whereas file descriptor 0
(standard input) points to @var{input-port} or @file{/dev/null}; all other file descriptors
are closed prior to yielding control to @var{command}.  When
@var{create-session?} is true, call @code{setsid} first
(@pxref{Processes, @code{setsid},, guile, GNU Guile Reference Manual}).

By default, @var{command} is run as the current user.  If the @var{user}
keyword argument is present and not false, change to @var{user}
immediately before invoking @var{command}.  @var{user} may be a string,
indicating a user name, or a number, indicating a user ID.  Likewise,
@var{command} will be run under the current group, unless the
@var{group} keyword argument is present and not false, and
@var{supplementary-groups} is not @code{'()}.

@code{fork+exec-command} does the same as @code{exec-command}, but in
a separate process whose PID it returns.

@quotation Warning
The @command{shepherd}'s main even loop is responsible for calling
@code{waitpid} to reap processes that have completed.  User code
@emph{must not} call @code{waitpid} as that would compete with
@code{waitpid} calls made by the main event loop, possibly leading to
deadlocks.

Use @code{system*} or @code{spawn-command} when you need to spawn a
command and wait for its exit status.  @ref{Process Utilities}.
@end quotation
@end deffn

@defvar default-environment-variables
This parameter (@pxref{Parameters,,, guile, GNU Guile Reference Manual})
specifies the default list of environment variables to be defined when
the procedures above create a new process.

It must be a list of strings where each string has the format
@code{@var{name}=@var{value}}.  It defaults to what @code{environ}
returns when the program starts (@pxref{Runtime Environment,
@code{environ},, guile, GNU Guile Reference Manual}).
@end defvar

@deffn {Procedure} user-environment-variables @
  [name-or-id (getuid)] @
  [environment-variables (default-environment-variables)]

Take the list @var{environment-variables}, replace @env{HOME} with home
directory of the user and @env{USER} with the name of the user and
return the result.
@end deffn

@defvar default-pid-file-timeout
This parameter (@pxref{Parameters,,, guile, GNU Guile Reference Manual})
specifies the default PID file timeout in seconds, when
@code{#:pid-file} is used (see above).  It defaults to 5 seconds.
@end defvar

@defvar default-process-termination-grace-period
This parameter (@pxref{Parameters,,, guile, GNU Guile Reference Manual})
specifies the ``grace period'' (in seconds) after which a process that
has been sent @code{SIGTERM} or some other signal to gracefully exit is
sent @code{SIGKILL} for immediate termination.  It defaults to 5
seconds.
@end defvar

@cindex respawn delay
@defvar default-respawn-delay
This parameter specifies the default value of the @code{#:respawn-delay}
parameter of @code{service} (@pxref{Defining Services}).  It defaults to
@code{0.1}, meaning a 100ms delay before respawning a service.
@end defvar

@cindex respawn limit
@cindex disabled service
@defvar default-respawn-limit
This parameter specifies the default value of the @code{#:respawn-limit}
parameter of @code{service} (@pxref{Defining Services}).

As an example, suppose you add this line to your configuration file:

@lisp
(default-respawn-limit '(3 . 10))
@end lisp

The effect is that services will be respawned at most 3 times over a
period of 10 seconds before being disabled.
@end defvar

@cindex on-demand, starting services
@cindex inetd-style services
One may also define services meant to be started @emph{on demand}.  In
that case, shepherd listens for incoming connections on behalf of the
program that handles them; when it accepts an incoming connection, it
starts the program to handle them.  The main benefit is that such
services do not consume resources until they are actually used, and they
do not slow down startup.

These services are implemented following the protocol of the venerable
inetd ``super server'' (@pxref{inetd invocation, inetd,, inetutils, GNU
Inetutils}).  Many network daemons can be invoked in ``inetd mode'';
this is the case, for instance, of @command{sshd}, the secure shell
server of the OpenSSH project.  The Shepherd lets you define inetd-style
services, specifically those in @code{nowait} mode where the daemon is
passed the newly-accepted socket connection while @command{shepherd} is
in charge of listening.

@anchor{endpoints}
@cindex endpoints, for inetd services
@cindex endpoints, for systemd services
Listening endpoints for such services are described as records built
using the @code{endpoint} procedure provided by the @code{(shepherd
endpoints)} module:

@deffn {Procedure} endpoint @var{address} [#:name "unknown"] @
  [#:style SOCK_STREAM] [#:backlog 128] @
  [#:socket-owner (getuid)] [#:socket-group (getgid)] @
  [#:socket-directory-permissions #o755] @
  [#:bind-attempts (default-bind-attempts)]
Return a new endpoint called @var{name} of @var{address}, an address as
return by @code{make-socket-address}, with the given @var{style} and
@var{backlog}.

When @var{address} is of type @code{AF_INET6}, the endpoint is
@emph{IPv6-only}.  Thus, if you want a service available both on IPv4
and IPv6, you need two endpoints.  For example, below is a list of
endpoints to listen on port 4444 on all the network interfaces, both in
IPv4 and IPv6 (``0.0.0.0'' for IPv4 and ``::0'' for IPv6):

@lisp
(list (endpoint (make-socket-address AF_INET INADDR_ANY 4444))
      (endpoint (make-socket-address AF_INET6 IN6ADDR_ANY 4444)))
@end lisp

This is the list you would pass to @code{make-inetd-constructor} or
@code{make-systemd-constructor}---see below.

When @var{address} is of type @code{AF_UNIX}, @var{socket-owner} and
@var{socket-group} are strings or integers that specify its ownership and that
of its parent directory; @var{socket-directory-permissions} specifies the
permissions for its parent directory.

Upon @samp{EADDRINUSE} (``Address already in use''), up to @var{bind-attempts}
attempts will be made to @code{bind} on @var{address}, one every second.
@end deffn

@defvar default-bind-attempts
This parameter specifies the number of times, by default, that
@command{shepherd} will try to bind an endpoint address if it happens to
be already in use.
@end defvar

The inetd service constructor takes a command and a list of such
endpoints:

@deffn {Procedure} make-inetd-constructor @var{command} @var{endpoints} @
  [#:service-name-stem _] [#:requirements '()] @
  [#:max-connections (default-inetd-max-connections)] @
  [#:user #f] @
  [#:group #f] @
  [#:supplementary-groups '()] @
  [#:directory (default-service-directory)] @
  [#:file-creation-mask #f] [#:create-session? #t] @
  [#:resource-limits '()] @
  [#:environment-variables (default-environment-variables)]
Return a procedure that opens sockets listening to @var{endpoints}, a list
of objects as returned by @code{endpoint}, and accepting connections in the
background.

Upon a client connection, a transient service running @var{command} is
spawned.  Only up to @var{max-connections} simultaneous connections are
accepted; when that threshold is reached, new connections are immediately
closed.

The remaining arguments are as for @code{make-forkexec-constructor}.
@end deffn

@deffn {Procedure} make-inetd-destructor
Return a procedure that terminates an inetd service.
@end deffn

@cindex systemd-style services
@cindex on-demand, starting services
@cindex socket activation, starting services
@cindex starting services, via socket activation
The last type is @dfn{systemd-style services}.  Like inetd-style
services, those are started on demand when an incoming connection
arrives, but using the protocol devised by the systemd service manager
and referred to as
@uref{https://www.freedesktop.org/software/systemd/man/daemon.html#Socket-Based%20Activation,
@dfn{socket activation}}.  The main difference with inetd-style services
is that shepherd hands over the listening socket(s) to the daemon; the
daemon is then responsible for accepting incoming connections.  A
handful of environment variables are set in the daemon's execution
environment (see below), which usually checks them using the libsystemd
or libelogind
@uref{https://www.freedesktop.org/software/systemd/man/sd_listen_fds.html,
client library helper functions}.
The constructor and destructor for systemd-style daemons are described
below.

@deffn {Procedure} make-systemd-constructor @var{command} @var{endpoints} @
  [#:lazy-start? #t] @
  [#:user #f] @
  [#:group #f] @
  [#:supplementary-groups '()] @
  [#:log-file #f] @
  [#:directory (default-service-directory)] @
  [#:file-creation-mask #f] [#:create-session? #t] @
  [#:resource-limits '()] @
  [#:environment-variables (default-environment-variables)]
Return a procedure that starts @var{command}, a program and list of
argument, as a systemd-style service listening on @var{endpoints}, a list of
@code{<endpoint>} objects.

@var{command} is started on demand on the first connection attempt on one of
@var{endpoints} when @var{lazy-start?} is true; otherwise it is started as
soon as possible.  It is passed the listening sockets for @var{endpoints} in
file descriptors 3 and above; as such, it is equivalent to an @code{Accept=no}
@uref{https://www.freedesktop.org/software/systemd/man/systemd.socket.html,systemd
socket unit}.  The following environment variables are set in its environment:

@table @env
@item LISTEN_PID
It is set to the PID of the newly spawned process.

@item LISTEN_FDS
It contains the number of sockets available starting from file descriptor
3---i.e., the length of @var{endpoints}.

@item LISTEN_FDNAMES
The colon-separated list of endpoint names.
@end table

This must be paired with @code{make-systemd-destructor}.
@end deffn

@deffn {Procedure} make-systemd-destructor
Return a procedure that terminates a systemd-style service as created by
@code{make-systemd-constructor}.
@end deffn

The following constructor/destructor pair is also available for your
convenience, but we recommend using @code{make-forkexec-constructor} and
@code{make-kill-destructor} instead (this is typically more robust than
going through the shell):

@deffn {Procedure} make-system-constructor @var{command}@dots{}
The returned procedure will execute @var{command} in a shell and
return @code{#t} if execution was successful, otherwise @code{#f}.
For convenience, it takes multiple arguments which will be
concatenated first.
@end deffn

@deffn {Procedure} make-system-destructor @var{command}@dots{}
Similar to @code{make-system-constructor}, but returns @code{#f} if
execution of the @var{command} was successful, @code{#t} if not.
@end deffn

@xref{Timers}, for other service constructors and destructors: those for
timers.

@node Timers
@section Timers

@cindex timers (timed services)
@cindex timed services (timers)
@cindex periodic services
In addition to process, inetd-style, and systemd-style services
discussed before, another type of service is available: @dfn{timers}.

Timers, you guessed it, execute a command or call a procedure
periodically.  They work like other services: they can be started,
stopped, unloaded, and so on.  The constructor and destructor shown
below let you define a timer; they are exported by @code{(shepherd
service timer)}, so make sure to add a line like this to your
configuration file if you'd like to use them:

@lisp
(use-modules (shepherd service timer))
@end lisp

@cindex calendar events, for timers
@cindex timer periodicity
Timers fire on calendar events: ``every Sunday at noon'', ``everyday at
11AM and 8PM'', ``on the first of each month'', etc@.  If you ever used
cron, mcron, or systemd timers, this is similar.  Calendar events are
specified using the @code{calendar-event} procedure, which defines
@emph{constraints} on each calendar component: months, days of week,
hours, minutes, and so on.  Here are a few examples:

@lisp
;; Every Sunday and every Wednesday, at noon.
(calendar-event #:hours '(12) #:minutes '(0)
                #:days-of-week '(sunday wednesday))

;; Everyday at 11AM and 8PM.
(calendar-event #:hours '(11 20) #:minutes '(0))

;; At 9:10AM on the first and fifteenth of each month.
(calendar-event #:days-of-month '(1 15)
                #:hours '(9) #:minutes '(10))
@end lisp

@deffn {Procedure} calendar-event [#:months any-month] @
  [#:days-of-month any-day] [#:days-of-week any-day-of-week] @
  [#:hours any-hour] [#:minutes any-minute] @
  [#:seconds '(0)]
Return a calendar event that obeys the given constraints.  Raise an
error if one of the values is out of range.

All the arguments are lists of integers as commonly used in the
Gregorian calendar, except for @code{days-of-week} which is a list of
symbols denoting weekdays: @code{'monday}, @code{'tuesday}, etc.

@quotation Note
@cindex daylight saving time (DST), for timers
All calendar events are understood in the timezone they occur in, should
daylight saving time (DST) changes occur between consecutive events.

For example, in Western and Central Europe, the waiting time between two
consecutive daily events is 24 hours except on two occasions: it is 23
hours when switching from ``normal'' time (CET, or UTC+1) to summer time
(CEST, or UTC+2), and it is 25 hours when switching from summer time
to ``normal'' time.
@end quotation
@end deffn

@cindex Vixie cron, converting date specifications
@cindex cron, converting date specifications
Users familiar with the venerable Vixie cron can instead convert
cron-style date specifications to a calendar event data structure using
the @code{cron-string->calendar-event} procedure described below.

@deffn {Procedure} cron-string->calendar-event @var{str}
Convert @var{str}, which contains a Vixie cron date line, into the
corresponding @code{calendar-event}.  Raise an error if @var{str} is invalid.

A valid cron date line consists of 5 space-separated fields: minute, hour, day
of month, month, and day of week.  Each field can be an integer, or a
comma-separate list of integers, or a range.  Ranges are represented by two
integers separated by a hyphen, optionally followed by slash and a number of
repetitions.  Here are examples:

@table @code
@item 30 4 1,15 * *
4:30AM on the 1st and 15th of each month;
@item 5 0 * * *
five minutes after midnight, every day;
@item 23 0-23/2 * * 1-5
23 minutes after the hour every two hour, on weekdays.
@end table
@end deffn

To create a timer, you create a service with the procedures described
below as its @code{start} and @code{stop} methods (@pxref{Defining
Services}).

@deffn {Procedure} make-timer-constructor @var{event} @var{action} @
  [#:occurrences +inf.0] [#:log-file #f] [#:max-duration #f] @
  [#:wait-for-termination? #f]
Return a procedure for use as the @code{start} method of a service.  The
procedure will perform @var{action} for @var{occurrences} iterations of
@code{event}, a calendar event as returned by @code{calendar-event}.
@var{action} may be either a command (returned by @code{command}) or a thunk;
in the latter case, the thunk must be suspendable or it could block the whole
shepherd process.

When @var{log-file} is true, log the output of @var{action} to that file
rather than in the global shepherd log.

When @var{wait-for-termination?} is true, wait until @var{action} has finished
before considering executing it again; otherwise, perform @var{action}
strictly on every occurrence of @var{event}, at the risk of having multiple
instances running concurrently.

When @var{max-duration} is true, it is the maximum duration in seconds that a
run may last, provided @var{action} is a command.  Past @var{max-duration}
seconds, the timer's process is forcefully terminated with signal
@var{termination-signal}.
@end deffn

@deffn {Procedure} make-timer-destructor
Return a procedure for the @code{stop} method of a service whose
constructor was given by @code{make-timer-constructor}.
@end deffn

As we have seen above, @code{make-timer-constructor} can be passed a
command to execute.  Those are specified using the @code{command}
procedure below.

@deffn {Procedure} command @var{line} @
  [#:user #f] [#:group #f] [#:supplementary-groups '()] @
  [#:environment-variables (default-environment-variables)] @
  [#:directory (default-service-directory)] @
  [#:resource-limits '()]
Return a new command for @var{line}, a program name and argument list, to be
executed as @var{user} and @var{group}, with the given
@var{environment-variables}, in @var{directory}, and with the given
@var{resource-limits}.

These arguments are the same as for @code{fork+exec-command} and related
procedures (@pxref{exec-command, @code{fork+exec-command}}).
@end deffn

It's also possible to add a @code{trigger} action to timer
services, such that one can trigger it with:

@example
herd trigger @var{service}
@end example

To do that, you would add the predefined @code{timer-trigger-action} to
the service's @code{actions} field (@pxref{Defining Services}).

@defvar timer-trigger-action
This is the @code{trigger} service action.  When invoked, its effect is
to invoke the action passed to @code{make-timer-constructor}.
@end defvar

@xref{timer-example, timer example}, to see how to put it all together.

Last, this module also provides @code{timer-service}, a sort of ``meta''
timer service that lets you dynamically create timed services from the
command line.  @xref{Timer Service}.

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node The root Service
@section The @code{root} Service

@cindex root service
@cindex special services
The service @code{root} is special, because it is used to control the
Shepherd itself.  It has an alias @code{shepherd}.  It provides the
following actions (in addition to @code{enable}, @code{disable} and
@code{restart} which do not make sense here).

@table @code
@item status
Displays which services are started and which ones are not.

@item detailed-status
Displays detailed information about every registered service.

@cindex evaluating code in shepherd
@item load @var{file}
Evaluate in the @command{shepherd} process the Scheme code in
@var{file}, in a fresh module that uses the @code{(shepherd services)}
module---as with the @code{--config} option of @command{shepherd}
(@pxref{Invoking shepherd}).

@item eval @var{exp}
Likewise, evaluate Scheme expression @var{exp} in a fresh module with
all the necessary bindings.  Here is a couple of examples:

@example
# herd eval root "(+ 2 2)"
4
# herd eval root "(getpid)"
1
# herd eval root "(lookup-running 'xorg-server)"
(service (version 0) (provides (xorg-server)) @dots{})
@end example

@item unload @var{service-name}
Attempt to remove the service identified by @var{service-name}.
@command{shepherd} will first stop the service, if necessary, and then
remove it from the list of registered services.  Any services
depending upon @var{service-name} will be stopped as part of this
process.

If @var{service-name} simply does not exist, output a warning and do
nothing.  If it exists, but is provided by several services, output a
warning and do nothing.  This latter case might occur for instance with
the fictional service @code{web-server}, which might be provided by both
@code{apache} and @code{nginx}.  If @var{service-name} is the special
string and @code{all}, attempt to remove all services except for the Shepherd
itself.

@item reload @var{file-name}
Unload all known optional services using unload's @code{all} option,
then load @var{file-name} using @code{load} functionality.  If
file-name does not exist or @code{load} encounters an error, you may
end up with no defined services.  As these can be reloaded at a later
stage this is not considered a problem.  If the @code{unload} stage
fails, @code{reload} will not attempt to load @var{file-name}.

@item daemonize
Fork and go into the background.  This should be called before
respawnable services are started, as otherwise we would not get the
@code{SIGCHLD} signals when they terminate.

@item kexec
On GNU/Linux, reboot straight into a new Linux kernel previously loaded
with the @command{kexec -l @var{file}} command.  This is the action
invoked by the @command{reboot -k} command.  @xref{Invoking reboot}.

@end table

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Legacy GOOPS Interface
@section Legacy GOOPS Interface

@cindex GOOPS, former interface
From its inception in 2002 with negative version numbers (really!)@: up
to version 0.9.x included, the Shepherd's service interface used GOOPS,
Guile's object-oriented programming system (@pxref{GOOPS,,, guile, GNU
Guile Reference Manual}).  This interface was deprecated in 0.10.0 and
removed in 1.0.0.  The remainder of this section describes that
interface and how to migrate from it.

The GOOPSy interface provided
a @code{<service>} class whose instances you could access
directly with @code{slot-ref}; generic functions such as @code{start}
and @code{stop} had one method accepting a service object and another
method accepting the name of a service as a symbol, which it would
transparently resolve.

Fortunately, common idioms are easily converted to the current
interface.  For example, you would previously create a service like so:

@tindex <service>
@lisp
(make <service>       ;former GOOPS interface
  #:provides '(something)
  #:requires '(another thing)
  #:start @dots{}
  #:stop @dots{}
  #:respawn? #t)
@end lisp

With the new interface (@pxref{Defining Services}), you would write
something very similar:

@lisp
(service '(something)
  #:requirement '(another thing)
  #:start @dots{}
  #:stop @dots{}
  #:respawn? #t)
@end lisp

@findex start
@findex stop
Likewise, instead of writing:

@lisp
(start 'whatever)
@end lisp

@noindent
... you would write:

@lisp
(start-service (lookup-service 'whatever))
@end lisp

If in doubt, please get in touch with us at @email{help-guix@@gnu.org}.

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Service Examples
@section Service Examples

@cindex configuration file, examples
The configuration file of the @command{shepherd} command
(@pxref{Invoking shepherd}) defines, registers, and possibly starts
@dfn{services}.  Each service specifies other services it depends on and
how it is started and stopped.  The configuration file contains Scheme
code that uses the programming interface of the @code{(shepherd
service)} module (@pxref{Services}).

Let's assume you want to define and register a service to start mcron,
the daemon that periodically executes jobs in the background
(@pxref{Introduction,,, mcron, GNU mcron Manual}).  That service is
started by invoking the @command{mcron} command, after which
@command{shepherd} should monitor the running process, possibly
re-spawning it if it stops unexpectedly.  Here's the configuration file
for this one service:

@lisp
(define mcron
  (service
    '(mcron)
    ;; Run /usr/bin/mcron without any command-line arguments.
    #:start (make-forkexec-constructor '("/usr/bin/mcron"))
    #:stop (make-kill-destructor)
    #:respawn? #t))

(register-services (list mcron))
@end lisp

You can write the snippet above in the default configuration
file---@file{~/.config/shepherd/init.scm} if you run @command{shepherd}
as an unprivileged user.  When you launch it, @command{shepherd} will
evaluate that configuration; thus it will define and register the
@code{mcron} service, but it will @emph{not} start it.  To start the
service, run:

@example
herd start mcron
@end example

Alternatively, if you want @code{mcron} to be started automatically when
@command{shepherd} starts, you can add this snippet at the end of the
configuration file:

@lisp
(start-in-the-background '(mcron))
@end lisp

Now let's take another example: @command{sshd}, the secure shell daemon
of @uref{https://www.openssh.com,the OpenSSH project}.  We will pass
@command{sshd} the @option{-D} option so that it does not ``detach'',
making it easy for @command{shepherd} to monitor its process; we also
tell @command{shepherd} to check its @dfn{PID file} to determine once it
has started and is ready to accept connections:

@lisp
(define sshd
  (service
    '(sshd ssh-daemon)  ;for convenience, give it two names
    #:start (make-forkexec-constructor
             '("/usr/sbin/sshd" "-D")
             #:pid-file "/etc/ssh/sshd.pid")
    #:stop (make-kill-destructor)
    #:respawn? #t))

(register-services (list sshd))
(start-in-the-background '(sshd))
@end lisp

@cindex inetd mode, example
Alternatively, we can start @command{sshd} in @dfn{inetd mode}: in that
case, @command{shepherd} listens for connection and spawns
@command{sshd} only upon incoming connections.  The inetd mode is
enabled by passing the @option{-i} command-line option:

@lisp
(define sshd
  (service
    '(sshd ssh-daemon)
    #:start (make-inetd-constructor
             '("/usr/sbin/sshd" "-D" "-i")
             (list (endpoint
                    (make-socket-address AF_INET INADDR_ANY 22))
                   (endpoint
                    (make-socket-address AF_INET6 IN6ADDR_ANY 22)))
             #:max-connections 10)
    #:stop (make-inetd-destructor)
    #:respawn? #t))

(register-services (list sshd))
(start-in-the-background '(sshd))
@end lisp

The @code{make-socket-address} procedure calls above return the
@dfn{listening addresses} (@pxref{Network Socket Address,,, guile, GNU
Guile Reference Manual}).  In this case, it specifies that
@command{shepherd} will accept connections coming from any network
interface (``0.0.0.0'' in IPv4 notation and ``::0'' for IPv6) on port
22.  The @code{endpoint} calls wrap these addresses in endpoint records
(@pxref{endpoints}).  When a client connects, @command{shepherd} accepts
it and spawns @command{sshd -D -i} as a new @dfn{transient service},
passing it the client connection.  The @code{#:max-connections}
parameter instructs @command{shepherd} to accept at most 10 simultaneous
client connections.

@anchor{system-star-example}
@cindex nginx, service example
The example below---a service for the @url{https://nginx.org,nginx} web
server---illustrates a situation where a service constructor and
destructor work by invoking a program with @code{system*} instead of the
usual @code{make-forkexec-constructor} and @code{make-kill-destructor}.

@lisp
(service
  '(nginx)
  #:start (lambda ()
            ;; The 'nginx' command daemonizes and returns immediately;
            ;; it eventually writes a PID file once successfully started.
            (and (zero? (system* "/usr/sbin/nginx"))
                 (read-pid-file "/var/run/nginx/pid")))
  #:stop (lambda _
           ;; Stop the nginx daemon by running this command.
           (unless (zero? (system* "/usr/sbin/nginx" "-s" "stop"))
             (error "failed to stop nginx"))
           #f))
@end lisp

@xref{Process Utilities}, for more on @code{system*} and related process
helpers.

@anchor{timer-example}
@cindex timer, example
Let's now look at @dfn{timers}---services that run periodically, on
chosen calendar events (@pxref{Timers}).  If you ever used systemd
timers or the venerable cron, this is similar.  The example below
defines a timer that fires twice a day and runs the @command{updatedb}
command as root (@pxref{Invoking updatedb,,, find, Finding Files}):

@lisp
;; Import the module for 'make-timer-constructor' & co.
(use-modules (shepherd service timer))

(define updatedb
  (service
    '(updatedb)
    #:start (make-timer-constructor
              ;; Fire at midnight and noon everyday.
              (calendar-event #:hours '(0 12) #:minutes '(0))
              (command '("/usr/bin/updatedb"
                         "--prunepaths=/tmp")))
    #:stop (make-timer-destructor)
    #:actions (list timer-trigger-action)))

(register-services (list updatedb))
(start-in-the-background '(updatedb))
@end lisp

Thanks to the @code{#:actions} bit above, you can also run @code{herd
trigger updatedb} to trigger that job.

In these examples, we haven't discussed dependencies among
services---the @code{#:requires} keyword of @code{<service>}---nor did
we discuss systemd-style services.  These are extensions of what we've
seen so far.  @xref{Services}, for details.

If you use Guix System, you will see that it contains a wealth of
Shepherd service definitions.  The nice thing is that those give you a
@emph{complete view} of what goes into the service---not just how the
service is started and stopped, but also what software package is used
and what configuration file is provided.  @xref{Shepherd Services,,,
guix, GNU Guix Reference Manual}, for more info.

@node Managing User Services
@section Managing User Services

The Shepherd can be used to manage services for an unprivileged user.
First, you may want to ensure it is up and running every time you log
in.  One way to accomplish that is by adding the following lines to
@file{~/.bash_profile} (@pxref{Bash Startup Files,,, bash, The GNU Bash
Reference Manual}):

@verbatim
if [[ ! -S ${XDG_RUNTIME_DIR-$HOME/.cache}/shepherd/socket ]]; then
    shepherd
fi
@end verbatim

Then, we suggest the following top-level
@file{$XDG_CONFIG_HOME/shepherd/init.scm} file, which will automatically
load individual service definitions from
@file{~/.config/shepherd/init.d}:

@lisp
(use-modules (shepherd service)
             ((ice-9 ftw) #:select (scandir)))

;; Send shepherd into the background
(perform-service-action root-service 'daemonize)

;; Load all the files in the directory 'init.d' with a suffix '.scm'.
(for-each
  (lambda (file)
    (load (string-append "init.d/" file)))
  (scandir (string-append (dirname (current-filename)) "/init.d")
           (lambda (file)
             (string-suffix? ".scm" file))))

@end lisp

Then, individual user services can be put in
@code{$XDG_CONFIG_HOME/shepherd/init.d/}, e.g., for @command{ssh-agent}.

@lisp
;; Add to your ~/.bash_profile:
;;
;; SSH_AUTH_SOCK=$@{XDG_RUNTIME_DIR-$HOME/.cache@}/ssh-agent/socket
;; export SSH_AUTH_SOCK

(use-modules (shepherd support))

(define ssh-agent
  (service
    '(ssh-agent)
    #:documentation "Run `ssh-agent'"
    #:start (lambda ()
              (let ((socket-dir (string-append %user-runtime-dir "/ssh-agent")))
                (unless (file-exists? socket-dir)
                  (mkdir-p socket-dir)
                  (chmod socket-dir #o700))
                (fork+exec-command
                 `("ssh-agent" "-D" "-a" ,(string-append socket-dir "/socket"))
                 #:log-file (string-append %user-log-dir "/ssh-agent.log"))))
    #:stop (make-kill-destructor)
    #:respawn? #t))

(register-services (list ssh-agent))
(start-service ssh-agent)
@end lisp

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Service Collection
@chapter Service Collection

The Shepherd comes with a collection of services that let you control it
or otherwise extend its functionality.  This chapter documents them.

@menu
* System Log Service::          Good ol' syslog.
* Log Rotation Service::        Tidying up log files.
* Transient Service Maker::     Running commands in the background.
* Timer Service::               Scheduling command execution.
* Monitoring Service::          Monitoring shepherd resource usage.
* REPL Service::                Interacting with a running shepherd.
@end menu

@node System Log Service
@section System Log Service

@cindex system log (syslogd)
@cindex syslogd (system log)
Traditionally, GNU and Unix-like systems come with a system-wide logging
mechanism called @dfn{syslog} that applications and services can use.
This mechanism usually relies on a standalone process, the
@command{syslogd} daemon, that listens for incoming messages, typically
on the @file{/dev/log} Unix-domain socket, and writes them to files or
terminals according to user settings (@pxref{syslogd invocation,
syslogd,, inetutils, GNU Inetutils}).  Each message sent to
@command{syslogd} specifies its @dfn{priority} and originating
@dfn{facility} along with the actual message (@pxref{Overview of
Syslog,,, libc, The GNU C Library Reference Manual}).

The Shepherd provides an optional in-process service that can be used as
a substitute for the traditional @command{syslogd} program.  The
configuration snippet below instantiates and registers that service for
@command{shepherd} running as PID@tie{}1:

@lisp
(use-modules (shepherd service system-log))

(register-services
  ;; Create a system log with the default settings.
  (list (system-log-service)))

;; Start it.
(start-service (lookup-service 'system-log))
@end lisp

The configuration above starts the service under the names
@code{system-log} and @code{syslogd}.  Messages are logged in files
under @file{/var/log}, on @file{/dev/tty12} (the twelfth console
terminal on Linux), and on the console for emergency messages.  The
@code{system-log} service is integrated with the log rotation service:
log files it creates are subject to log rotation, in a ``race-free''
fashion (@pxref{Log Rotation Service}).

The destination of syslog messages---the files, terminals, etc.@: where
they are written---can be configured by passing a procedure as the
@code{#:message-destination} argument of @code{system-log-service}:

@lisp
(define (message-destination message)
  ;; Return the list of files where MESSAGE is to be written.
  (cond ((member (system-log-message-priority message)
                 (list (system-log-priority emergency)
                       (system-log-priority alert)))
         ;; Important messages go both to a file and to the console.
         '("/dev/console" "/var/log/messages))
        ((string-prefix? "sudo" (system-log-message-content message))
         ;; Messages coming from sudo go to a dedicated file.
         '("/var/log/sudo"))
        ((member (system-log-message-facility message)
                 (list (system-log-facility authorization)
                       (system-log-facility authorization/private)))
         ;; Security-sensitive messages are written only to this
         ;; one file.
         '("/var/log/secure"))
        (else
         ;; Everything else goes to /var/log/messages.
         '("/var/log/messages"))))

(define my-syslogd
  ;; Customized system log instance.
  (system-log-service #:message-destination message-destination))
@end lisp

The example above shows how to assign different destinations based on
message priority, facility, and content.  Note that each message can be
written to zero, one, or more files.

The interface to the system log service is provided by the
@code{(shepherd service system-log)} module and described thereafter.

@deffn {Procedure} system-log-message? @var{obj}
Return true if @var{obj} is a system log message.
@end deffn

@deffn {Procedure} system-log-message-facility @var{message}
@deffnx {Procedure} system-log-message-priority @var{message}
@deffnx {Procedure} system-log-message-content @var{message}
@deffnx {Procedure} system-log-message-sender @var{message}
Return the given attribute of @var{message}, a system log message:

@itemize
@item
Its facility, an integer as constructed by @code{system-log-facility}.
For example, the expression @code{(system-log-facility mail)} evaluates
to the value of the ``mail'' facility.

@item
Its priority, an integer as constructed by @code{system-log-priority}.
For example, @code{(system-log-priority debug)} returns the ``debug''
priority.

@item
Its content, a string.

@item
Its sender, either @code{#f}, in which case the message originates from
the local host, or a socket address as constructed by
@code{make-socket-address} if the message originates from a different
host (see below).
@end itemize
@end deffn

@deffn {Procedure} system-log-service [@var{sources}] @
         [#:provision '(system-log syslogd)] @
         [#:requirement '()] @
         [#:kernel-log-file (kernel-log-file)] @
         [#:message-destination (default-message-destination-procedure)] @
         [#:date-format default-logfile-date-format] @
         [#:history-size (default-log-history-size)] @
         [#:max-silent-time (default-max-silent-time)]
Return the system log service (@dfn{syslogd}) with the given
@var{provision} and @var{requirement} (lists of symbols).  The service accepts
connections on @var{sources}, a list of @code{<endpoint>} objects; optionally
it also reads messages from @code{#:kernel-log-file}, which defaults to
@file{/proc/kmsg} (Linux) or @file{/dev/klog} (the Hurd) when running as root.

Log messages are passed to @var{message-destination}, a one-argument procedure
that must return the list of files to write it to.  Write a mark to log files
when no message has been logged for more than @var{max-silent-time} seconds
(this feature is disabled by setting @var{max-silent-time} to @code{#f}).
Timestamps in log files are formatted according to @var{date-format}, a format
string for @code{strftime}, including delimiting space---e.g., @code{\"%c \"}
for a format identical to that of traditional syslogd implementations.

Keep up to @var{history-size} messages in memory for the purposes of allowing
users to view recent messages without opening various files.
@end deffn

@deffn {Procedure} default-message-destination-procedure
Return a procedure that, given a system log message, returns a ``good''
default destination to log it to.
@end deffn

@defvar kernel-log-file
This SRFI-39 parameter denotes the location of the kernel log file,
by default @file{/proc/kmsg} on Linux and @file{/dev/klog} on the Hurd.
@end defvar

@defvar default-max-silent-time
This SRFI-39 parameter denotes the maximum number of seconds after which
syslogd prints a ``mark'' in its files if it has not printed anything
for this long.
@end defvar


@node Log Rotation Service
@section Log Rotation Service

@cindex log rotation
@cindex rotating log files of services
All these services produce many log files; they're useful, for sure, but
wouldn't it be nice to archive them or even delete them periodically?
The @dfn{log rotation} service does exactly that.  Once you've enabled
it, it periodically @dfn{rotates} the log files of services---those
specified via the @code{#:log-file} argument of service constructors
(@pxref{Service De- and Constructors})---those of the system log
(@pxref{System Log Service}), and also, optionally,
``external'' log files produced by some other mechanism.

By ``rotating'' we mean this: if a service produces
@file{/var/log/my-service.log}, then rotating it consists in
periodically renaming it and compressing it to obtain, say,
@file{/var/log/my-service.log.1.gz}---after renaming the @emph{previous}
@file{my-service.1.log.gz} to @file{my-service.log.2.gz}, and so
on@footnote{This is comparable to what the venerable logrotate tool
would do.}.  Files older than some configured threshold are deleted
instead of being renamed.  The process is race-free: if the service is
running, not a single line that it logs is lost during rotation.

To enable the log rotation service, you can add the following lines to
your configuration file (@pxref{Service Examples}):

@lisp
(use-modules (shepherd service log-rotation))

(register-services
  ;; Create a service that rotates log files once a week.
  (list (log-rotation-service)))

;; Start it.
(start-service (lookup-service 'log-rotation))
@end lisp

This creates a @code{log-rotation} service, which is in fact a timed
service (@pxref{Timers}).  By default it rotates logs once a week and
you can see past and upcoming runs in the usual way:

@example
herd status log-rotation
@end example

You can also trigger it explicitly at any time, like so:

@example
herd trigger log-rotation
@end example

Last, you can list log files subject to rotation:

@example
herd files log-rotation
@end example

The default settings should be good for most use cases, but you can
change them by passing the @code{log-rotation-service} procedure a
number of arguments---see the reference documentation below.

@deffn {Procedure} log-rotation-service [@var{event}] @
          [#:provision '(log-rotation)] [#:requirement '()] @
          [#:external-log-files '()] @
          [#:compression (%default-log-compression)] @
          [#:expiry (%default-log-expiry)] @
          [#:rotation-size-threshold (%default-rotation-size-threshold)]
Return a timed service that rotates service logs along with
@var{external-log-files} (a list of file names such as
@file{/var/log/nginx/access.log} corresponding to ``external'' log files
not passed as @code{#:log-file} to any service) on every occurrence of
@var{event}, a calendar event.

Compress log files according to @var{method}, which can be one of
@code{'gzip}, @code{'zstd}, @code{'none}, or a one-argument procedure that
is passed the file name.  Log files smaller than @var{rotation-size-threshold}
are not rotated; copies older than @var{expiry} seconds are deleted.

Last, @var{provision} and @var{requirement} are lists of symbols specifying
what the service provides and requires, respectively.  Specifying
@var{requirement} is useful to ensure, for example, that log rotation runs
only if the service that mounts the file system that hosts log files is up.
@end deffn

@node Transient Service Maker
@section Transient Service Maker

@cindex transient service maker
@cindex background, running commands
The @dfn{transient service maker} lets you run commands in the
background, and it does so by wrapping those commands in transient
services (@pxref{Defining Services}).  It is similar to the
@uref{https://www.freedesktop.org/software/systemd/man/latest/systemd-run.html,
@command{systemd-run}} command, which you might have encountered before.

A simple configuration file that uses this service looks like this:

@lisp
(use-modules (shepherd service transient))

(register-services (list (transient-service)))
@end lisp

This creates a service called @code{transient} that has a @code{spawn}
action, which you can use like this:

@example shell
# Run 'make' from the current directory.
herd spawn transient -d "$PWD" -- make -j4

# Run 'rsync' from the home directory, inheriting
# the 'SSH_AUTH_SOCK' environment variable.
herd spawn transient \
  --log-file=backup.log \
  -E SSH_AUTH_SOCK=$SSH_AUTH_SOCK -- \
  rsync -e ssh -vur . backup.example.org:
@end example

@c copied from 'herd schedule timer'
Each of these @command{herd spawn transient} commands creates a new
transient service.  Like any other service, they can be inspected and
stopped.  Running @command{herd stop transient} stops all the currently
running transients.

The command runs from the directory specified by
@code{default-service-directory} or from that specified by the
@option{--working-directory} option of @command{herd}; it starts with the
environment variables in @code{default-environment-variables}, augmented
with @env{HOME} when running as a different user, with the addition of
variables passed with @code{--environment-variable}.  @xref{Invoking
herd}, for more info on influential command-line options.

@deffn {Procedure} transient-service [@var{provision}] @
         [#:requirement '()]
Return a service with the given @var{provision} and
@var{requirement}.  The service has a @code{spawn} action that lets users run
commands in the background.
@end deffn

@node Timer Service
@section Timer Service

@anchor{timer-schedule-command}
@cindex timer service, like @command{at}
@cindex @command{at} command, with timer service
The @code{(shepherd service timer)} provides the @code{timer} service,
which lets you dynamically create timed services (@pxref{Timers}), from
the command line, in a way similar to the traditional @command{at}
command:

@example shell
# Run the 'mail' command, as root, as 12PM.
herd schedule timer at 12:00 -- \
  mail --to=charlie -s "Lunch time!"

# Run the 'mpg123' command as user 'charlie' at 7AM, from charlie's
# home directory.
herd schedule timer at 07:00 --user=charlie -- \
  mpg123 Music/alarm.mp3

# Run 'rsync' from the ~/doc directory, inheriting the 'SSH_AUTH_SOCK'
# environment variable.  Log the output in 'backup.log'.
herd schedule timer at 13:00 \
  --log-file=backup.log \
  -d ~/doc -E SSH_AUTH_SOCK=$SSH_AUTH_SOCK -- \
  rsync -e ssh -vur . backup.example.org:
@end example

Each of these @command{herd schedule timer} commands creates a new timed
service, which, like any other service, can be inspected and stopped;
those services are transient and vanish after they have executed their
command (@pxref{Defining Services}).

The command runs from the directory specified by
@code{default-service-directory} or from that specified by the
@option{--working-directory} option of @command{herd}; it has with the
environment variables in @code{default-environment-variables}, augmented
with @env{HOME} when running as a different user, with the addition of
variables passed with @code{--environment-variable}.  @xref{Invoking
herd}, for more info on influential command-line options.

This @code{timer} service can be added to your configuration like so:

@lisp
(use-modules (shepherd service timer))

(register-services (list (timer-service)))
@end lisp

The reference follows.

@deffn {Procedure} timer-service [@var{provision}] @
         [#:requirement '()]
Return a timer service with the given @var{provision} and
@var{requirement}.  The service has a @code{schedule} action that lets users
schedule command execution similar to the venerable @command{at} command.
@end deffn

@node Monitoring Service
@section Monitoring Service

The @dfn{monitoring service}, as its name suggests, monitors resource
usage of the shepherd daemon.  It does so by periodically logging
information about key resources: heap size (memory usage), open file
descriptors, and so on.  It is a simple and useful way to check whether
resource usage remains under control.

To use it, a simple configuration file that uses this service and
nothing else would look like this:

@lisp
(use-modules (shepherd service monitoring))

(register-services
  ;; Create a monitoring service that logs every 15 minutes.
  (list (monitoring-service #:period (* 15 60))))

;; Start it!
(start-service (lookup-service 'monitoring))
@end lisp

Using the @code{herd} command, you can get immediate resource usage
logging:

@example
$ herd log monitoring
service names: 3; heap: 8.77 MiB; file descriptors: 20
@end example

You can also change the logging period; for instance, here is how you'd
change it to 30 minutes:

@example
$ herd period monitoring 30
@end example

The @code{(shepherd service monitoring)} module exports the following
bindings:

@deffn {Procedure} monitoring-service @
          [#:period (default-monitoring-period)]
Return a service that will monitor shepherd resource usage by printing it
every @var{period} seconds.
@end deffn

@defvar default-monitoring-period
This parameter specifies the default monitoring period, in seconds.
@end defvar

@node REPL Service
@section Read-Eval-Print Loop Service

@cindex REPL, read-eval-print loop
@cindex read-eval-print loop, REPL
Scheme wouldn't be Scheme without support for @dfn{live hacking}, and
your favorite service manager had to support it too!  The @dfn{REPL
service} provides a read-eval-print loop (REPL) that lets you interact
with it from the comfort of the Guile REPL (@pxref{Running Guile
Interactively,,, guile, GNU Guile Reference Manual}).

The service listens for connections on a Unix-domain socket---by default
@file{/var/run/shepherd/repl} when running as root and
@file{/run/user/@var{uid}/shepherd/repl} otherwise---and spawns a new
service for each client connection.  Clients can use the REPL as they
would do with a ``normal'' REPL, except that it lets them inspect and
modify the state of the @command{shepherd} process itself.

@quotation Caveat
The live REPL is a powerful tool in support of live hacking and
debugging, but it's also a dangerous one: depending on the code you
execute, you could lock the @command{shepherd} process, make it crash,
or who knows what.

One particular aspect to keep in mind is that @command{shepherd}
currently uses Fibers in such a way that scheduling among fibers is
cooperative and non-preemptive.  Beware!
@end quotation

A configuration file that enables the REPL service looks like this:

@lisp
(use-modules (shepherd service repl))

(register-services (list (repl-service)))
@end lisp

With that in place, you can later start the REPL:

@example
herd start repl
@end example

From there you can connect to the REPL socket.  If you use Emacs, you
might fancy doing it with Geiser's @code{geiser-connect-local} function
(@pxref{Top,,, geiser, Geiser User Manual}).

The @code{(shepherd service repl)} module exports the following
bindings.

@deffn {Procedure} repl-service [@var{socket-file}]
Return a REPL service that listens to @var{socket-file}.
@end deffn

@defvar default-repl-socket-file
This parameter specifies the socket file name @code{repl-service} uses
by default.
@end defvar

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Misc Facilities
@chapter Misc Facilities

This is a list of facilities which are available to code running
inside of the Shepherd and is considered generally useful, but is not directly
related to one of the other topic covered in this manual.

@menu
* Process Utilities::           Helpers to deal with processes
* Errors::                      Signalling, handling and ignoring errors.
* Communication::               Input/Output in various ways.
@end menu

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Process Utilities
@section Process Utilities

@cindex spawning a program, from within shepherd
When writing custom service actions, you may find it useful to spawn
helper processes.  The @code{(shepherd service)} module provides helpers
that are safe to use within the @command{shepherd} process.
@xref{system-star-example, the nginx example}, for a typical use case.

@deffn {Procedure} system @var{command}
@deffnx {Procedure} system* @var{command} @var{arguments} @dots{}
Run @var{command} and return its exit status, which can be examined with
@code{status:exit-val} and related procedures (@pxref{Processes,,,
guile, GNU Guile Reference Manual}).

This works exactly like the @code{system} and @code{system*} procedures
provided by Guile but the @command{shepherd} process redefines them so
they cooperate with its own even loop and child process termination
handling.
@end deffn

@deffn {Procedure} spawn-command @var{command} @
  [#:user #f] [#:group #f] @
  [#:environment-variables (default-environment-variables)] @
  [#:directory (default-service-directory)] @
  [#:resource-limits '()] @
  [#:log-file #f]
Like @code{system*}, spawn @var{command} (a list of strings) and return
its exit status.  Additionally accept the same keyword arguments as
@code{fork+exec-command}: @code{#:user}, @code{#:directory}, and so on.
@ref{exec-command, @code{fork+exec-command}}.
@end deffn

@node Errors
@section Errors

@cindex assertions
@deffn {macro} assert expr
If @var{expr} yields @code{#f}, display an appropriate error
message and throw an @code{assertion-failed} exception.
@end deffn

@cindex system errors
@deffn {macro} without-system-error expr@dots{}
Evaluates the @var{expr}s, not going further if a system error occurs,
but also doing nothing about it.
@end deffn

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Communication
@section Communication

The @code{(shepherd comm)} module provides primitives that allow clients such
as @command{herd} to connect to @command{shepherd} and send it commands to
control or change its behavior (@pxref{Defining Services, actions of
services}).

@tindex <shepherd-command>
Currently, clients may only send @dfn{commands}, represented by the
@code{<shepherd-command>} type.  Each command specifies a service it
applies to, an action name, a list of strings to be used as arguments,
and a working directory.  Commands are instantiated with
@code{shepherd-command}:

@deffn {Procedure} shepherd-command @var{action} @var{service} @
         [#:@var{arguments} '()] [#:@var{directory} (getcwd)]
Return a new command (a @code{<shepherd-command>}) object for
@var{action} on @var{service}.
@end deffn

@noindent
Commands may then be written to or read from a communication channel
with the following procedures:

@deffn {Procedure} write-command @var{command} @var{port}
Write @var{command} to @var{port}.
@end deffn

@deffn {Procedure} read-command @var{port}
Receive a command from @var{port} and return it.
@end deffn

In practice, communication with @command{shepherd} takes place over a
Unix-domain socket, as discussed earlier (@pxref{Invoking shepherd}).
Clients may open a connection with the procedure below.

@deffn {Procedure} open-connection [@var{file}]
Open a connection to the daemon, using the Unix-domain socket at
@var{file}, and return the socket.

When @var{file} is omitted, the default socket is used.
@end deffn

@cindex output
The daemon writes output to be logged or passed to the
currently-connected client using @code{local-output}:

@deffn {Procedure} local-output format-string . args
This procedure should be used for all output operations in the Shepherd.  It
outputs the @var{args} according to the @var{format-string}, then
inserts a newline.  It writes to whatever is the main output target of
the Shepherd, which might be multiple at the same time in future versions.
@end deffn

@cindex protocol, between @command{shepherd} and its clients
Under the hood, @code{write-command} and @code{read-command} write/read
commands as s-expressions (sexps).  Each sexp is intelligible and
specifies a protocol version.  The idea is that users can write their
own clients rather than having to invoke @command{herd}.  For instance,
when you type @command{herd status}, what is sent over the wire is the
following sexp:

@lisp
(shepherd-command
  (version 0)
  (action status) (service root)
  (arguments ()) (directory "/data/src/dmd"))
@end lisp

The reply is also an sexp, along these lines:

@lisp
(reply (version 0)
       (result (((service @dots{}) @dots{})))
       (error #f) (messages ()))
@end lisp

This reply indicates that the @code{status} action was successful,
because @code{error} is @code{#f}, and gives a list of sexps denoting
the status of services as its @code{result}.  The @code{messages} field
is a possibly-empty list of strings meant to be displayed as is to the
user.


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Internals
@chapter Internals

This chapter contains information about the design and the
implementation details of the Shepherd for people who want to hack it.

The GNU@tie{}Shepherd is developed by a group of people in connection
with @uref{https://www.gnu.org/software/guix/, Guix System}, GNU's
advanced distribution, but it can be used on other distros as well.
You're very much welcome to join us!  You can report bugs to
@email{bug-guix@@gnu.org} and send patches or suggestions to
@email{guix-devel@@gnu.org}.

@menu
* Coding Standards::            How to properly hack the Shepherd.
* Service Internals::           How services actually work.
* Design Decisions::            Why the Shepherd is what it is.
@end menu

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Coding Standards
@section Coding Standards

About formatting: Use common sense and GNU Emacs (which actually is
the same, of course), and you almost can't get the formatting wrong.
Formatting should be as in Guile and Guix, basically.  @xref{Coding
Style,,, guix, GNU Guix Reference Manual}, for more info.

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Service Internals
@section Service Internals

@cindex CSP, concurrent sequential processes
@cindex concurrent sequential processes, CSP
Under the hood, each service record has an associated @dfn{fiber}, a
lightweight execution thread and @command{shepherd} as a whole follows
the @acronym{CSP, Concurrent Sequential Processes} model
(@pxref{Introduction,,, fibers, Fibers}).
A service's fiber encapsulates all the @emph{state} of its corresponding
service: its status (whether it's running, stopped, etc.), its ``running
value'' (such as the PID of its associated process), the time at which
its status changed, and so on.  Procedures that access the state of a
service, such as @code{service-status}, or that modify it, such as
@code{start-service} (@pxref{Interacting with Services}), merely send a
message to the service's associated fiber.

@cindex actor model, for services
This pattern follows the @dfn{actor model}: each of these per-service
fibers is an @dfn{actor}@footnote{There is one noteworthy difference
compared to the actor model.  In the ``real'' actor model, messaging
among actors is asynchronous; in the CSP model, messaging is
synchronous, which means that the sender and receiver must always
@emph{rendezvous} and their send/receive operation blocks until the
other end is here to receive/send the message.  @xref{Context,,, fibers,
Fibers}, for more info.}.  There are several benefits:

@itemize
@item
each actor has a linear control flow that is easy to reason about;
@item
access and modification of the service state are race-free since they
are all handled sequentially by its actor;
@item
the actor's code is purely functional, which again makes it easier to
reason about it.
@end itemize

There are other actors in the code, such as the service registry
(@pxref{Service Registry}).  Fibers are used pervasively throughout the
code to achieve concurrency.

Note that Fibers is set up such that the @code{shepherd} process has
only one POSIX thread (this is mandated by POSIX for processes that call
@code{fork}, with all its warts), and fibers are scheduled in a
cooperative fashion.  This means that it is possible to block the
@code{shepherd} process for instance by running a long computation or by
waiting on a socket that is not marked as @code{SOCK_NONBLOCK}.  Be
careful!

We think this programming model makes the code base not only more
robust, but also very fun to work with---we hope you'll enjoy it too!

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Design Decisions
@section Design Decisions

@quotation Note
This section was written by Wolfgang Jährling back in 2003 and documents
the original design of what was then known as GNU@tie{}dmd.  The main
ideas remain valid but some implementation details and goals have
changed.
@end quotation

The general idea of a service manager that uses dependencies, similar
to those of a Makefile, came from the developers of the GNU Hurd, but
as few people are satisfied with System V Init, many other people had
the same idea independently.  Nevertheless, the Shepherd was written with the
goal of becoming a replacement for System V Init on GNU/Hurd, which
was one of the reasons for choosing the extension language of the GNU
project, Guile, for implementation (another reason being that it makes
it just so much easier).

The runlevel concept (i.e. thinking in @emph{groups} of services) is
sometimes useful, but often one also wants to operate on single
services.  System V Init makes this hard: While you can start and stop
a service, @code{init} will not know about it, and use the runlevel
configuration as its source of information, opening the door for
inconsistencies (which fortunately are not a practical problem
usually).  In the Shepherd, this was avoided by having a central entity that is
responsible for starting and stopping the services, which therefore
knows which services are actually started (if not completely
improperly used, but that is a requirement which is impossible to
avoid anyway).  While runlevels are not implemented yet, it is clear
that they will sit on top of the service concept, i.e. runlevels will
merely be an optional extension that the service concept does not rely
on.  This also makes changes in the runlevel design easier when it may
become necessary.

The consequence of having a daemon running that controls the services
is that we need another program as user interface which communicates
with the daemon.  Fortunately, this makes the commands necessary for
controlling services pretty short and intuitive, and gives the
additional bonus of adding some more flexibility.  For example, it is
easiely possible to grant password-protected control over certain
services to unprivileged users, if desired.

An essential aspect of the design of the Shepherd (which was already mentioned
above) is that it should always know exactly what is happening,
i.e. which services are started and stopped.  The alternative would
have been to not use a daemon, but to save the state on the file
system, again opening the door for inconsistencies of all sorts.
Also, we would have to use a separate program for respawning a service
(which just starts the services, waits until it terminates and then
starts it again).  Killing the program that does the respawning (but
not the service that is supposed to be respawned) would cause horrible
confusion.  My understanding of ``The Right Thing'' is that this
conceptionally limited strategy is exactly what we do not want.

The way dependencies work in the Shepherd took a while to mature, as it was not
easy to figure out what is appropriate.  I decided to not make it too
sophisticated by trying to guess what the user might want just to
theoretically fulfill the request we are processing.  If something
goes wrong, it is usually better to tell the user about the problem
and let her fix it, taking care to make finding solutions or
workarounds for problems (like a misconfigured service) easy.  This
way, the user is in control of what happens and we can keep the
implementation simple.  To make a long story short, @emph{we don't try
to be too clever}, which is usually a good idea in developing
software.

If you wonder why I was giving a ``misconfigured service'' as an
example above, consider the following situation, which actually is a
wonderful example for what was said in the previous paragraph: Service
X depends on symbol S, which is provided by both A and B.  A depends
on AA, B depends on BB.  AA and BB conflict with each other.  The
configuration of A contains an error, which will prevent it from
starting; no service is running, but we want to start X now.  In
resolving its dependencies, we first try to start A, which will cause
AA to be started.  After this is done, the attempt of starting A
fails, so we go on to B, but its dependency BB will fail to start
because it conflicts with the running service AA.  So we fail to
provide S, thus X cannot be started.  There are several possibilities
to deal with this:

@itemize @bullet
@item
When starting A fails, terminate those services which have been
started in order to fulfill its dependencies (directly and
indirectly).  In case AA was running already, we would not want to
terminate it.  Well, maybe we would, to avoid the conflict with BB.
But even if we would find out somehow that we need to terminate AA to
eventually start X, is the user aware of this and wants this to happen
(assuming AA was running already)?  Probably not, she very likely has
assumed that starting A succeeds and thus terminating AA is not
necessary.  Remember, unrelated (running) services might depend in AA.
Even if we ignore this issue, this strategy is not only complicated,
but also far from being perfect: Let's assume starting A succeeds, but
X also depends on a service Z, which requires BB.  In that case, we
would need to detect in the first place that we should not even try to
start A, but directly satisfy X's dependency on S with B.

@item
We could do it like stated above, but stop AA only if we know we won't
need it anymore (for resolving further dependencies), and start it
only when it does not conflict with anything that needs to get
started.  But should we stop it if it conflicts with something that
@emph{might} get started?  (We do not always know for sure what we
will start, as starting a service might fail and we want to fall back
to a service that also provides the particular required symbol in that
case.)  I think that either decision will be bad in one case or
another, even if this solution is already horribly complicated.

@item
When we are at it, we could just calculate a desired end-position, and
try to get there by starting (and stopping!) services, recalculating
what needs to be done whenever starting a service fails, also marking
that particular service as unstartable, except if it fails to start
because a dependency could not be resolved (or maybe even then?).
This is even more complicated.  Instead of implementing this and
thereby producing code that (a) nobody understands, (b) certainly has
a lot of bugs, (c) will be unmaintainable and (d) causes users to
panic because they won't understand what will happen, I decided to do
the following instead:

@item
Just report the error, and let the user fix it (in this case, fix the
configuration of A) or work around it (in this case, disable A so that
we won't start AA but directly go on to starting B).
@end itemize

I hope you can agree that the latter solution after all is the best
one, because we can be sure to not do something that the user does not
want us to do.  Software should not run amok.  This explanation was
very long, but I think it was necessary to justify why the Shepherd uses a very
primitive algorithm to resolve dependencies, despite the fact that it
could theoretically be a bit more clever in certain situations.

One might argue that it is possible to ask the user if the planned
actions are ok with her, and if the plan changes ask again, but
especially given that services are supposed to usually work, I see few
reasons to make the source code of the Shepherd more complicated than
necessary.  If you volunteer to write @emph{and} maintain a more
clever strategy (and volunteer to explain it to everyone who wants to
understand it), you are welcome to do so, of course@dots{}


@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl-1.3.texi

@c @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

@node Concept Index
@unnumbered Concept Index

@printindex cp

@node Procedure and Macro Index
@unnumbered Procedure and Macro Index

@printindex fn

@node Variable Index
@unnumbered Variable Index

@printindex vr

@node Type Index
@unnumbered Type Index

@printindex tp

@bye