civodul pushed a commit to branch devel
in repository shepherd.
commit f63e2d2e5e80cb6342e03028469ae8993bf61b2c
Author: Ludovic Courtès <[email protected]>
AuthorDate: Sun Nov 3 12:16:04 2024 +0100
doc: Rewrite “Jump Start”.
The goal is to give a shorter, clearer, and more up-to-date overview of
the commands one needs to know as a user or system administrator.
* doc/shepherd.texi (Jump Start): Rewrite.
(Invoking shepherd): Add bit about the configuration file.
---
doc/shepherd.texi | 280 +++++++++++++++++++-----------------------------------
1 file changed, 97 insertions(+), 183 deletions(-)
diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index 0e627b3..bc3d80e 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -122,231 +122,126 @@ Shepherd's more advanced features.
@node Jump Start
@chapter Jump Start
-@cindex prefix
-This chapter gives a short overview of the Shepherd. It is enough if you just
-need the basic features of it. As it is not assumed that readers are
-familiar with all the involved issues, a very experienced user might
-be annoyed by the often very detailed descriptions in this
-introduction. Those users are encouraged to just skip to the
-reference section.
-
-Note that all the full file names in the following text are based on
-the assumption that you have installed the Shepherd with an empty prefix. If
-your Shepherd installation for example resides in @code{/usr/local}
-instead, add this directory name in front of the absolute file names
-mentioned below.
-
-@cindex Configuration file
-When @command{shepherd} gets started, it reads and evaluates a
-configuration file. When it is started with superuser privileges, it
-tries to use @code{/etc/shepherd.scm}. When started as normal user, it
-looks for a file called @code{$XDG_CONFIG_HOME/shepherd/init.scm}. If
-the @code{XDG_CONFIG_HOME} environment variable is not defined,
-@code{$HOME/.config/shepherd/init.scm} is used instead (@pxref{Managing
-User Services }). With the option @code{--config} (or, for short,
-@code{-c}), you can specify where to look instead. So if you want to
-start @command{shepherd} with an alternative file, use one of the
-following commands:
-
-@example
-shepherd --config=/etc/shepherd.scm.old
-shepherd -c /etc/shepherd.scm.old
-@end example
-
-@cindex Starting a service
-As the final ``d'' suggests, @command{shepherd} is just
-a daemon that (usually) runs in the
-background, so you will not interact with it directly. After it is
-started, @command{shepherd} will listen on a socket special file, usually
-@code{/var/run/shepherd/socket}, for further commands. You use the tool
-@dfn{herd} to send these commands to @command{shepherd}. Usage of herd is
simple and
-straightforward: To start a service called @code{apache}, you use:
-
-@example
-herd start apache
-@end example
-
-@cindex Status (of services)
-@cindex Service status
-When you do this, all its dependencies will get resolved. For
-example, a webserver is quite likely to depend on working networking,
-thus it will depend on a service called @code{networking}. So if you
-want to start @code{apache}, and @code{networking} is not yet running, it
-will automatically be started as well. The current status of all the
-services defined in the configuration file can be queried like this:
+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
-Or, to get additional details about each service, run:
+... to get detailed information about a specific service, including
+recently-logged messages:
@example
-herd detailed-status
+herd status sshd
@end example
@noindent
-In this example, this would show the @code{networking} and @code{apache}
-services as started. If you just want to know the status of the
-@code{apache} service, run:
+... and to start, stop, restart, enable, or disable services, among
+other possible actions:
@example
-herd status apache
+herd start nginx
+herd stop tor
+herd disable tor
+herd restart guix-daemon
@end example
-You may also view a log of service events, including the time at which
-each service was started or stopped, by running:
+@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 log
+herd graph | xdot -
@end example
-Likewise, you can read messages recently logged by @command{shepherd}
-itself by querying the @dfn{root service} (@pxref{The root Service}):
+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.
-@example
-herd status root
-@end example
-
-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:
+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 graph | xdot -
+herd files log-rotation
@end example
-@cindex Stopping a service
-You can stop
-a service and all the services that depend on it will be stopped.
-Using the example above, if you stop @code{networking}, the service
-@code{apache} will be stopped as well---which makes perfect sense,
-as it cannot work without the network being up. To actually stop a
-service, you use the following, probably not very surprising, command:
+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 stop networking
+herd status root
@end example
-There are two more actions you can perform on every service: the
-actions @code{enable} and @code{disable} are used to prevent and allow
-starting of the particular service. If a service is intended to be
-restarted whenever it terminates (how this can be done will not be
-covered in this introduction), but it is respawning too often in a
-short period of time (by default 5 times in 5 seconds), it will
-automatically be disabled. After you have fixed the problem that
-caused it from being respawned too fast, you can start it again with
-the commands:
+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 enable foo
-herd start foo
+herd load root ~/additional-services.scm
@end example
-@cindex virtual services
-@cindex fallback services
-But there is far more you can do than just that. Services can not
-only simply depend on other services, they can also depend on
-@emph{virtual} services. A virtual service is a service that is
-provided by one or more services additionally. For instance, a service
-called @code{exim} might provide the virtual service
-@code{mailer-daemon}. That could as well be provided by a service
-called @code{smail}, as both are mailer-daemons. If a service needs
-any mailer-daemon, no matter which one, it can just depend on
-@code{mailer-daemon}, and one of those who provide it gets started (if
-none is running yet) when resolving dependencies. The nice thing is
-that, if trying to start one of them fails, @command{shepherd} will go on and
try to
-start the next one, so you can also use virtual services for
-specifying @emph{fallbacks}.
-
-Additionally to all that, you can perform service-specific actions.
-Coming back to our original example, @code{apache} is able to
-reload its modules, therefore the action @code{reload-modules} might
-be available:
+To view a log of service events, including the time at which each
+service was started or stopped, run:
@example
-herd reload-modules apache
+herd log
@end example
-Service-specific actions can only be used when the service is
-started, i.e. the only thing you can do to a stopped service is
-starting it. An exception exists, see below.
+Last, you can view documentation about services and their actions:
-There are two actions which are special, because even if services
-can implement them on their own, a default implementation is provided
-by @command{shepherd} (another reason why they are special is that the default
-implementations can be called even when the service is not running;
-this inconsistency is just to make it more intuitive to get
-information about the status of a service, see below).
-
-These actions are @code{restart} and @code{status}. The default
-implementation of @code{restart} calls @code{stop} and @code{start} on the
-affected service, taking care to also restart any dependent services. The
-default implementation of @code{status} displays some general information
-about the service, like what it provides, and what it depends on.
-
-A special service is @code{root}, which is used for controlling the
-Shepherd itself. You can also reference to this service as
-@code{shepherd}. It implements various actions. For example, the
-@code{status} action displays which services are started and which ones
-are stopped, whereas @code{detailed-status} has the effect of applying
-the default implementation of @code{status} to all services one after
-another. The @code{load} action is unusual insofar as it shows a
-feature that is actually available to all services, but which we have
-not seen yet: It takes an additional argument. You can use @code{load}
-to load arbitrary code into the Shepherd at runtime, like this:
-
-@example
-herd load shepherd ~/additional-services.scm
-@end example
-
-In the same vein the special action @code{doc} describes its service
-when called without an argument or describes a service-specific action
-when called with the action as the additional arguments. You can even
-get the list of the service-specific actions a service provides when
-using with the additional argument @code{list-actions}.
@example
$ herd doc root
The root service is used to operate on shepherd itself.
-$ herd doc root list-actions
-root (help status halt power-off load eval unload reload daemonize cd restart)
$ herd doc root action power-off
power-off: Halt the system and turn it off.
@end example
-This is enough now about the @command{herd} and @command{shepherd} programs, we
-will now take a look at how to configure the Shepherd. In the configuration
-file, we need mainly the definition of services. We can also do
-various other things there, like starting a few services already.
-
-FIXME: Finish. For now, look at the @code{doc/examples/} subdirectory.
-
-@example
-...
-@end example
-
-Ok, to summarize:
-
-@itemize @bullet
-@item
-@command{shepherd} is a daemon, @command{herd} the program that controls it.
-@item
-You can start, stop, restart, enable and disable every service, as
-well as display its status.
-@item
-You can perform additional service-specific actions, which you can
-also list.
-@item
-Actions can have arguments.
-@item
-You can display the status of a service, even if the service does not
-provide a specific implementation for this action. The same is true
-for restarting.
-@item
-The @code{root}/@code{shepherd} service is used to control
-@command{shepherd} itself.
-@end itemize
+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 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@@ -398,13 +293,32 @@ The @code{shepherd} program has the following synopsis:
shepherd [@var{option}@dots{}]
@end example
-It accepts the following options:
+@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}; 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 script on startup.
+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,
