Initial.HEADv0.1trunk

A  AUTHORS
A  COPYING
A  ChangeLog
A  INSTALL
A  Makefile.am
A  Makefile.in
A  NEWS
A  README
A  aclocal.m4
A  configure
A  configure.ac
A  doc/Makefile.am
A  doc/Makefile.in
A  doc/fdl-1.3.texi
A  doc/texinfo.tex
A  doc/whispers.texi
A  install-sh
A  missing

1 files changed, 1312 insertions, 0 deletions

diff --git a/doc/whispers.texi b/doc/whispers.texi
new file mode 100644
index 0000000..8e44f2a
--- /dev/null
+++ b/doc/whispers.texi
@@ -0,0 +1,1312 @@
+\input texinfo
+@c -*-texinfo-*-
+
+@c %**start of header
+@setfilename whispers.info
+@documentencoding UTF-8
+@settitle Whispers Reference Manual
+@c %**end of header
+
+@set UPDATED 10 October 2024
+@set UPDATED-MONTH October 2024
+@set EDITION 0.1.0
+@set VERSION 0.1.0
+
+@copying
+Copyright @copyright{} 2024 Runciter <runciter@@whispers-vpn.org>@*
+
+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 administration
+@direntry
+* Whispers: (whispers).         Tree of shepherd processes
+@end direntry
+
+@titlepage
+@title Whispers Reference Manual
+@subtitle Shepherd process tree for GNU Guix
+@author Runciter
+
+@page
+@vskip 0pt plus 1filll
+Edition @value{EDITION} @*
+@value{UPDATED} @*
+
+@insertcopying
+@end titlepage
+
+@contents
+
+@node Top, Definitions, (dir), (dir)
+@top Whispers
+
+This manual documents Whispers version @value{VERSION}.
+
+@insertcopying
+
+@menu
+* Definitions::
+* Purpose::
+* The whispers service::
+* Service extensions::
+* Whispers services::
+* The whispers command::
+* Caveats::
+* Bugs::
+* GNU Free Documentation License::
+* Concept Index::
+* Programming Index::
+@end menu
+
+@node Definitions, Purpose, Top, Top
+@chapter Definitions
+
+Whispers is a multi-user process tree of shepherd processes and their
+services, @xref{Top,,,shepherd,The GNU Shepherd Manual}.
+
+Within this manual, shepherd processes run by whispers and their
+relationships between themselves and with their services are referred to
+using the following terminology:
+
+@table @code
+
+@cindex hierarchy
+@item Hierarchy
+The part of the whispers process tree constituted of shepherd processes
+proper is referred to as the whispers @code{hierarchy}. Non-shepherd
+processes of the whispers process tree are also shepherd services
+provided by whispers through its hierarchy, although they are not
+themselves part of the hierarchy.
+
+@cindex superior
+@item Superior
+The parent process of a process running inside the whispers process tree
+is called its @code{superior}, unless that parent is just the PID 1
+shepherd, in which case the child is the shepherd process which lies at
+the top of the hierarchy.
+
+@cindex lieutenant
+@item Lieutenant
+A child process and service of a shepherd running inside the hierarchy
+is called a @code{lieutenant} of that shepherd process. While
+non-shepherd processes of the whispers tree are also lieutenants, they
+cannot have lieutenants themselves.
+
+@end table
+
+@node Purpose, The whispers service, Definitions, Top
+@chapter Purpose
+
+Whispers provides a sandboxing facility, since all processes controlled
+as shepherd services by the hierarchy can be stopped or started as an
+action of their service in their superior or the PID 1 shepherd. They
+can also be given actions independently from each other. The command
+@command{whispers} is a simple wrapper around @command{herd} providing a
+convenience switch to control all services in the hierarchy, @xref{The
+whispers command}.
+
+As a Guix service, whispers provides configuration handles so that
+actions can be performed by any controlling shepherd before starting
+shepherd lieutenants of the hierarchy, or after stopping them. While
+this facility is mostly intended for developers adding easily
+configurable extensions to whispers, they can also be employed by users
+should they decide to expand the hierarchy by using the low-level
+configuration of the whispers Guix service itself, @xref{The whispers
+service}.
+
+Additionally, the whispers hierarchy can be configured to operate
+daemons run by unprivileged users of the system, including when those
+have to make use of unprivileged sockets. An important difference
+between unprivileged lieutenants of the whispers hierarchy and Guix home
+shepherd services is that the latter are typically (always?) running
+only when their controlling user has a login session on the machine,
+while the former are running permanently and restarted automatically
+according to the configuration of their controlling lieutenant
+shepherd. Incidentally, services of unprivileged whispers lieutenants do
+not depend on @command{elogind}, its dependencies or the facilities it
+provides.
+
+A directory tree of imbricated tmpfs file systems is also deployed
+on-demand under @code{/run/whispers} whenever processes are started
+inside the hierarchy proper. These directories hold UNIX sockets and PID
+files necessary to the operation of the hierarchy and the other services
+it provides. When a hierarchy process is stopped by its superior or by
+PID 1, its dedicated tmpfs file system is unmounted after lieutenant
+tmpfs file systems are recursively unmounted within the hierarchy,
+leaving a ``clean slate'' with no leftover PID or socket files.
+
+Whispers itself can be fully stopped in this way by using @command{herd}
+to trigger the stop action of its service in PID 1, namely by using the
+command @command{herd stop whispers}. In a similar fashion, this will
+recursively unmount all tmpfs files systems created by whispers,
+hopefully and normally leaving behind an empty @code{/run/whispers}
+directory.
+
+Log files of the whispers hierarchy and its shepherd services are all
+stored under the path @code{/var/log/whispers}, with a sub-directory
+tree mimicking the hierarchy in its current and past states.
+
+Various Scheme sub-modules of @code{(whispers packages whispers)}
+provide Guix services that deploy daemons running inside the whispers
+hierarchy. Those modules also export configuration records for their
+services; they can be configured through semi-digestible Guix service
+instanciations in a machine's system configuration, @xref{Whispers
+services}. This is in any case simpler than deploying all the system's
+whispers lieutenants and their services ``by hand'' using the low-level
+whispers service configuration record, @ref{The whispers service}.
+
+@node The whispers service, Service extensions, Purpose, Top
+@chapter The whispers service
+
+The @code{(whispers services whispers)} scheme module provides a Guix
+shepherd service which extends a multi-user process tree of shepherd
+services.
+
+@defvar whispers-service-type
+This is the type for the service extending the shepherd with a whispers
+process tree. Its value must be an @code{whispers-configuration} record.
+
+@end defvar
+
+@deftp {Data Type} whispers-configuration
+
+@table @asis
+
+@item @code{coreutils-package} (default @code{coreutils})
+A file-like-object. The coreutils package to use.
+
+@item @code{util-linux-package} (default @code{util-linux})
+A file-like-object. the util-linux package to use.
+
+@item @code{whispers-package} (default @code{whispers})
+A file-like-object. the whispers package to use, @xref{The whispers
+command}.
+
+@item @code{name} (default @code{'whispers})
+A symbol. The shepherd provision of this whispers service in its
+superior or PID 1.
+
+@item @code{lieutenants} (default @code{'()})
+A list of Guix service objects. The lieutenants of this whispers
+service.
+
+@item @code{requires} (default @code{'()})
+A list of symbols. The list of shepherd provisions that this service
+requires in its superior or PID 1, a.k.a its dependencies.
+
+@item @code{user} (default @code{"root"})
+A string. The name of the user running this whispers service.
+
+@item @code{extend-user?} (default @code{#f})
+A boolean value. Whether @code{user} should be extended by Guix system
+when the system is reconfigured. Set this switch when and only when the
+group will not be explicitly declared in the system configuration Scheme
+file.
+
+@item @code{group} (default @code{"root"})
+A string. The name of the group this whispers service is run as.
+
+@item @code{extend-group?} (default @code{#f})
+A boolean value. Whether @code{group} should be extended by Guix system
+when the system is reconfigured. Set this switch when and only when the
+group will not be explicitly declared in the system configuration Scheme
+file.
+
+@item @code{timeout} (default @code{'(default-pid-file-timeout)})
+A string. The PID file timeout when starting this service. Its default
+value is defined in the shepherd's program Scheme code.
+
+@item @code{extra-packages} (default @code{(list)})
+A list of Guix records of type @code{package}. A list of extra packages
+to include in the profile that this service extends the Guix service of
+type @code{guix-profile-service-type} with.
+
+@item @code{extra-actions} (default @code{(list)})
+A list of shepherd-action records. Extra actions that are provided for
+this service in its superior or PID 1.
+
+@item @code{pre-start-action?} (default @code{#f})
+A boolean value. Whether this service performs a shepherd action named
+@code{pre-start} in its superior of PID 1, as part of its @code{start}
+action, immediately before its shepherd process is run by its superior
+or PID 1. If this flag is set, the @code{pre-start} action must be
+defined within the @code{extra-actions} field of this record.
+
+@item @code{post-stop-action?} (default @code{#f})
+A boolean value. Whether this service performs a shepherd action named
+@code{post-stop} in its superior of PID 1, as part of its @code{stop}
+action, immediately after its shepherd process is terminated by its
+superior or PID 1. If this flag is set, the @code{pre-start} action must
+be defined within the @code{extra-actions} field of this record.
+
+@item @code{%auto-start?} (default @code{#t})
+A boolean value. Whether this service's superior or PID 1 should
+automatically start this service when it is started itself.
+
+@end table
+
+@end deftp
+
+@node Service extensions, Whispers services, The whispers service, Top
+@chapter Service extension relationships
+
+The service of type @code{whispers-service-type} (@xref{The whispers
+service}) extends multiple other services (@xref{Service Types and
+Services,,,Guix,GNU guix}):
+
+@table @code
+
+@item rottlog-service-type
+@xref{Log Rotation,,,Guix,GNU guix}.
+
+@item account-service-type
+
+@item shepherd-root-service-type
+@xref{Shepherd Services,,,Guix,GNU guix}.
+
+@item mcron-service-type
+@xref{Scheduled Job Execution,,,Guix,GNU guix}.
+
+@item profile-service-type
+@xref{Service Reference,,,Guix,GNU guix}.
+
+@end table
+
+Only the shepherd at the top of the hierarchy extends the root
+shepherd. Hierarchy shepherd services themselves can be pseudo-extended
+by other services which have a @code{service-extension} targeting the
+service of type @code{shepherd-root-service-type}. That is to say,
+Whispers hijacks the shepherd extensions of services within its service
+tree so that those services ``extend'' their superior shepherd's
+pseudo-Guix service instead of extending the root shepherd Guix service.
+
+Services of the service tree which have a @code{service-extension}
+targeting the services of type @code{profile-service-type},
+@code{mcron-service-type} and/or @code{account-service-type} simply have
+their declared extensions recursively collected by whispers and passed
+down the extension graph by whisper's own extensions of other Guix
+services at system-reconfiguration time, as if they were direct Guix
+service extensions.
+
+The same functionality is intended and included in the code for services
+of the service tree which have a @code{service-extension} targeting the
+service of type @code{rottlog-service-type}. At the time of writing, it
+does not seems to be working, no log rotation happens inside the path
+@code{/var/log/whispers}.
+
+Other service extensions of services within the whispers service tree
+should be silently ignored.
+
+On the hand, the service of type @code{whispers-service-type} can be
+extended, in the strict sense of the word, by other services extending
+it with a nested list of lieutenants to be added one level below the top
+of the hierarchy. Sub-modules of the @code{whispers services whispers}
+module make use of this mechanism, @xref{Whispers services}.
+
+@node Whispers services, The whispers command, Service extensions, Top
+@chapter Whispers services
+
+This section documents whispers service types for various applications,
+for which service types and configuration bindings are offered by the
+whispers channel in scheme sub-modules of @code{whispers services
+whispers}. The facilities offered make configuration simpler than if
+they were done by hand using general whispers records (@xref{The
+whispers service} about those).
+
+Most of the services described in this section can be run either as root
+or as an unprivileged user, independently from @command{elogind} and
+from the existence of an interactive login session, as it is often
+desired and sometimes completely necessary. The services can however
+only be configured with root permissions, because they are deployed by
+system reconfiguration, @xref{System Configuration,,,Guix,GNU guix}.
+
+For the services documented here, typically, a hierarchy is extended
+below the whispers service of PID 1 for a service type or a themed group
+of service types. Each of these first-level hierarchies is documented by
+a sub-section of the present section. Those first level lieutenants
+extend in turn one lieutenant for each individual user which will make
+use of the services under their umbrella. Those per-user lieutenants are
+the superiors of individual (non-shepherd process) shepherd services.
+
+The resulting hierarchies are of the form:
+``/<hierarchy-theme>/<user>/<service>''. The ``<user>'' lieutenant(s) of
+``<hierarchy-type>'' each extend a shepherd process running as the user,
+so that the sockets and PID files of ``<service>'' and their parent
+directories hopefully exhibit correct permissions.
+
+For unprivileged users, the ``<user>'' lieutenant name is the same as
+their UNIX handle, and their service within their superior provisions a
+symbol converted from this name. For root, the lieutenant name is
+``root-user'' and the shepherd provision is the symbol
+@code{root-user}. This is done to avoid conflicts, because every
+shepherd daemon has a built-in service which provisions the symbol
+@code{root}.
+
+@menu
+* The finance hierarchy::
+* The gps hierarchy::
+* The mail hierarchy::
+* The ssh hierarchy::
+* The vpn hierarchy::
+* The xdg hierarchy::
+* Unprivileged services::
+@end menu
+
+@node The finance hierarchy, The gps hierarchy, Whispers services, Whispers services
+@section The finance hierarchy
+
+A bitcoin (BTC) node and/or a monero (XMR) can be deployed as shepherd
+services run by an unprivileged user within the @code{finance}
+hierarchy. Those features are provided by the @code{whispers services
+whispers finance} module.
+
+@menu
+* Configuring the finance hierarchy and services::
+* Configuration examples (whispers finance)::
+@end menu
+
+@node Configuring the finance hierarchy and services, Configuration examples (whispers finance), The finance hierarchy, The finance hierarchy
+@subsection Configuring the finance hierachy and services
+
+@defvar whispers-finance-service-type
+This is the type for the service extending whispers with a finance
+hierarchy and its associated services. Its value must be a
+@code{whispers-finance-configuration} record.
+
+@end defvar
+
+@deftp {Data Type} whispers-finance-configuration
+
+@table @asis
+
+@item @code{users-groups-nodes} (default @code{()})
+A list of @code{crypto-user-group-nodes} records configuring the finance
+hierarchy and its services, containing one member for each user making
+use of the hierarchy, be they root or unprivileged users.
+
+@end table
+
+@end deftp
+
+A record of type @code{crypto-user-group-nodes} configures the
+hierarchy and its services for a single user of the system.
+
+@deftp {Data Type} crypto-user-group-nodes
+
+@table @asis
+
+@item @code{user-and-group} (default @code{(whispers-user-group)})
+A record of the @code{whispers-user-group} type, @xref{Unprivileged
+services}. Its default is the record type's default record.
+
+@item @code{nodes} (default @code{(nodes-configuration})
+A record of the @code{nodes-configuration} type. Its default is the
+record type's default record.
+
+@end table
+
+@end deftp
+
+A record of type @code{nodes-configuration} type configures whether
+individual crypto services are wanted for a single user at the tip of
+the finance hierarchy, and stores their configuration for this user.
+
+@deftp {Data Type} nodes-configuration
+
+@table @asis
+
+@item @code{(bitcoin?} (default @code{#f})
+A boolean value, whether to extend a bitcoin node as a service.
+
+@item @code{(btc-node} (default @code{(bitcoin-node-configuration)})
+A record of the @code{bitcoin-node-configuration} type. Its default is
+the record type's default record.
+
+@item @code{(monero?} (default @code{#f})
+A boolean value
+
+@item @code{(xmr-node} (default @code{(monero-node-configuration)})
+A record of the @code{monero-node-configuration} type. Its default is
+the record type's default record.
+
+@end table
+
+@end deftp
+
+When the finance hierarchy extends a bitcoin node, the node is
+configured by a record of type @code{bitcoin-node-configuration} .
+
+@deftp {Data Type} bitcoin-node-configuration
+
+@table @asis
+
+@item @code{bitcoin-package} (default @code{bitcoin-core})
+A file-like object. The bitcoin package to use.
+
+@item @code{walletdir-opt?} (default @code{#f})
+A boolean value. Whether to set the @command{-walletdir} option
+explicitly for the service.
+
+@item @code{walletdir} (default @code{""})
+A string. The value for the @command{-walletdir} option when it is
+explicitly set.
+
+@item @code{proxy-opt?} (default @code{#f})
+A boolean value. Whether to set the @command{-proxy} option explicitly
+for the service.
+
+@item @code{proxy} (default @code{""})
+A string. The value for the @command{-proxy} option when it is
+explicitly set.
+
+@item @code{%auto-start?} (default @code{#t})
+A boolean value. Whether the service should be started automatically
+when its superior starts.
+
+@end table
+
+@end deftp
+
+When the finance hierarchy extends a monero node, the node is
+configured by a record of type @code{monero-node-configuration} .
+
+@deftp {Data Type} monero-node-configuration
+
+@table @asis
+
+@item @code{bitcoin-package} (default @code{bitcoin-core})
+A file-like object. The bitcoin package to use.
+
+@item @code{proxy-opt?} (default @code{#f})
+A boolean value. Whether to set the @command{--proxy} option explicitly
+for the service.
+
+@item @code{proxy} (default @code{""})
+A string. The value for the @command{--proxy} option when it is
+explicitly set.
+
+@item @code{proxy-opt?} (default @code{#f})
+A boolean value. Whether to set the @command{--tx-proxy} option explicitly
+for the service.
+
+@item @code{proxy} (default @code{""})
+A string. The value for the @command{--tx-proxy} option when it is
+explicitly set.
+
+@item @code{prune-blockchain-opt?} (default @code{#f})
+A boolean value. Whether to use the @command{--prune-blockchain} option
+for the service.
+
+@item @code{%auto-start?} (default @code{#t})
+A boolean value. Whether the service should be started automatically
+when its superior starts.
+
+@end table
+
+@end deftp
+
+@node Configuration examples (whispers finance),  , Configuring the finance hierarchy and services, The finance hierarchy
+@subsection Configuration examples (whispers finance)
+
+This example extends a hierarchy with both a BTC and an XMR node.
+
+The nodes contact initiate contacts with other nodes through a SOCKSv5
+proxy exposed on localhost port 7777. The
+@code{whispers-finance-service-type} does not take care of extending
+this proxy automatically; it can be done for example using a service of
+type @code{whispers-ssh-service-type}, @pxref{The ssh hierarchy}.
+Incidentally, should it be desirable or necessary, a service of type
+@code{whispers-ssh-service-type} can also take care of extending
+persistent reverse forwardings to open ports as necessary to be
+accessible for other nodes on the network; by default, port 8333 for
+bitcoin, and port 18080 for monero.
+
+@cindex ssh forwarding, example
+@lisp
+(service whispers-finance-service-type
+ (whispers-finance-configuration
+  (users-groups-nodes
+   (list
+    (crypto-user-group-nodes
+     (nodes
+      (nodes-configuration
+       (bitcoin? #t)
+       (btc-node
+        (bitcoin-node-configuration (proxy-opt? #t)
+                                    (proxy "localhost:7777")))
+       (monero? #t)
+       (xmr-node
+        (monero-node-configuration (proxy-opt? #t)
+                                   (proxy "127.0.0.1:7777")
+                                   (tx-proxy-opt? #f)
+                                   (tx-proxy "127.0.0.1:7777")
+                                   (prune-blockchain-opt? #t)))))
+       (user-and-group
+        (whispers-user-group (user "joe-chip")
+                             (group "joe-chip"))))))))
+@end lisp
+
+@node The gps hierarchy, The mail hierarchy, The finance hierarchy, Whispers services
+@section The gps hierarchy
+
+A @command{gpsd} service can be deployed as shepherd services run by an
+unprivileged user within the @code{gps} hierarchy. Those features are
+provided by the @code{whispers services whispers gps} module.
+
+@menu
+* Configuring the gps hierarchy and services::
+* Configuration examples (whispers gps)::
+@end menu
+
+@node Configuring the gps hierarchy and services, Configuration examples (whispers gps), The gps hierarchy, The gps hierarchy
+@subsection Configuring the gps hierarchy and services
+
+@defvar whispers-gps-service-type
+This is the type for the service extending whispers with a gps hierarchy
+and its associated services. Its value must be a list of
+@code{gps-user-group-configs} records.
+
+@end defvar
+
+@deftp {Data Type} gps-user-group-configs
+
+@table @asis
+
+@item @code{user-and-group} (default @code{(whispers-user-group)})
+A record of the @code{whispers-user-group} type, @xref{Unprivileged
+services}. Its default is the record type's default record.
+
+@item @code{gpsd?} (default @code{#t})
+A boolean value. Whether to extend gpsd(s) as service(s) for this
+user in the hierarchy.
+
+@item @code{gpsd-configs} (default @code{(list (gpsd-configuration))})
+A list of records of the @code{gpsd-configuration} type. The default is
+a list whose single member is the default value of a
+@code{gpsd-configuration} record.
+
+@end table
+
+@end deftp
+
+The @code{whispers services gps} module exports the
+@code{gpsd-configuration} record type which is used to configure a
+single gpsd service for a user in the hierarchy.
+
+@deftp {Data Type} gpsd-configuration
+
+@table @asis
+
+@item @code{gpsd-package} (default @code{gpsd})
+A file-like object. The gpsd package to use.
+
+@item @code{provision} (default special, see text)
+A symbol. The shepherd provision of the service within its superior. The
+default is computed at system-reconfiguration time as the concatenation
+of @code{gpsd-} and the value of @code{port} field of this record.
+
+@item @code{source} (default @code{"/dev/ttyUSB0})
+A string. The source from which gpsd receives gps data input.
+
+@item @code{port} (default @code{2947})
+An integer. The port on which gpsd serves GPS data for other programs.
+
+@item @code{listen-any?} (default @code{#f})
+A boolean value. Whether gpsd should listen on any interface, as opposed
+to just listening on loopback.
+
+@item @code{%auto-start?} (default @code{#t})
+A boolean value. Whether the service should be started automatically
+when its superior starts.
+
+@end table
+
+@end deftp
+
+@node Configuration examples (whispers gps),  , Configuring the gps hierarchy and services, The gps hierarchy
+@subsection Configuration examples (whispers gps)
+
+In this example, a gpsd service is extended which retrieves location
+information from another gpsd at IP 1.2.3.4 and makes it available on
+gpsd's default port 2947 on localhost. The gpsd process belongs to user
+named joe-chip.
+
+@cindex gpsd, example
+@lisp
+(service whispers-gps-service-type
+ (list
+  (gps-user-group-configs
+   (user-and-group
+    (whispers-user-group
+     (user "joe-chip")
+     (group "users")))
+   (gpsd-configs
+    (list
+     (gpsd-configuration (source "tcp://1.2.3.4:2947")))))))
+@end lisp
+
+@node The mail hierarchy, The ssh hierarchy, The gps hierarchy, Whispers services
+@section The mail hierarchy
+
+An @command{hydroxide} service allowing the local handling of emails
+from proton mail server can be deployed as shepherd services run of an
+unprivileged user are provided by the @code{whispers services whispers
+mail} module.
+
+@menu
+* Configuring the mail hierarchy and services::
+* Configuration examples (whispers mail)::
+@end menu
+
+@node Configuring the mail hierarchy and services, Configuration examples (whispers mail), The mail hierarchy, The mail hierarchy
+@subsection Configuring the mail hierarchy and services
+
+@defvar whispers-mail-service-type
+This is the type for the service extending whispers with a mail hierarchy
+and its associated services. Its value must be a
+@code{whispers-mail-configuration} record.
+
+@end defvar
+
+@deftp {Data Type} whispers-mail-configuration
+
+@table @asis
+
+@item @code{users-groups-services} (default @code{()})
+A list of @code{user-group-services} records configuring the
+mail hierarchy and its services, containing one member for each user
+making use of the hierarchy, be they root or unprivileged users.
+
+@end table
+
+@end deftp
+
+@deftp {Data Type} user-group-services
+
+@table @asis
+
+@item @code{user-and-group} (default @code{(whispers-user-group)})
+A record of the @code{whispers-user-group} type, @xref{Unprivileged
+services}. Its default is the record type's default record.
+
+@item @code{services} (default @code{(mail-services-configuration)})
+A record of the @code{mail-services-configuration} type. The default is
+the default value of a @code{mail-services-configuration} record.
+
+@end table
+
+@end deftp
+
+A record of type @code{mail-services-configuration} configures mail
+services for a single user in the hierarchy.
+
+@deftp {Data Type} mail-services-configuration
+
+@table @asis
+
+@item @code{user-and-group} (default @code{#f})
+A boolean value, whether an hydroxide service should be deployed for
+this user in the hierarchy.
+
+@item @code{hydroxide-service} (default @code{(hydroxide-service-configuration)})
+A record of the @code{hydroxide-configuration} type. The default is the
+default value of a @code{hydroxide-service-configuration} record.
+
+@end table
+
+@end deftp
+
+A record of type @code{hydroxide-service-configuration} configures the
+hydroxide service for a single user in the hierarchy.
+
+@deftp {Data Type} hydroxide-service-configuration
+
+@table @asis
+
+@item @code{hydroxide-package} (default @code{hydroxide})
+A file-like object. The hydroxide package to use.
+
+@item @code{https-proxy?} (default @code{#f})
+A boolean value. Whether hydroxide should connect to the proton mail
+servers behind a proxy.
+
+@item @code{https-proxy} (default @code{"socks5://localhost:8971"})
+A string specifying the proxy that hydroxide will use, when applicable
+per the provision of the @code{https-proxy?} field. The proxy is set
+using this string by exporting it as the value of an @code{https_proxy}
+variable into @command{hydroxide}'s environment.
+
+@item @code{imap?} (default @code{#t})
+A boolean value. Whether hydroxide should listen to IMAP protocol
+requests from the loopback interface.
+
+@item @code{smtp?} (default @code{#t})
+A boolean value. Whether hydroxide should listen to IMAP protocol
+requests from the loopback interface.
+
+@item @code{carddav?} (default @code{#t})
+A boolean value. Whether hydroxide should listen to IMAP protocol
+requests from the loopback interface.
+
+@item @code{%auto-start?} (default @code{#t})
+A boolean value. Whether the service should be started automatically
+when its superior starts.
+
+@end table
+
+@end deftp
+
+@node Configuration examples (whispers mail),  , Configuring the mail hierarchy and services, The mail hierarchy
+@subsection Configuration examples (whispers mail)
+
+With this example hierarchy, an hydroxide service is extended for the
+user named joe-chip, allowing the programs on localhost to access the
+Proton mail servers on localhost through the SMTP and IMAP protocols,
+but not carddav.
+
+Hydroxide contacts the Proton mail servers through a SOCKSv5 proxy
+exposed on localhost port 7777. The @code{whispers-mail-service-type}
+does not take care of extending this proxy automatically, it can be done
+for example using a service of type @code{whispers-ssh-service-type},
+@pxref{The ssh hierarchy}.
+
+The hierarchy cannot take care of initially authenticating hydroxide to
+the Proton mail servers, and provides no facility to authenticate the
+user to the hydroxide servers on localhost.
+
+@cindex mail, example
+@lisp
+(service whispers-mail-service-type
+ (whispers-mail-configuration
+  (users-groups-services
+   (list
+    (mail-user-group-services
+     (services
+      (mail-services-configuration (hydroxide? #t)
+                                   (hydroxide-service
+                                    (hydroxide-service-configuration
+                                     (https-proxy? #t)
+                                     (https-proxy "socks5://localhost:7777")
+                                     (carddav? #f)))))
+     (user-and-group
+      (whispers-user-group (user "joe-chip")
+                           (group "users"))))))))
+@end lisp
+
+@node The ssh hierarchy, The vpn hierarchy, The mail hierarchy, Whispers services
+@section The ssh hierarchy
+
+The facilities in the @code{whispers services whispers ssh} module
+provide ssh-related features to a system and its users:
+
+@table @code
+
+@item ssh forwarding
+A wrapper around the @code{whispers services ssh-tunneler} module,
+providing services for permanent ssh dynamic, tunnel, port and reverse
+port forwardings, including proxying them and re-enabling and restarting
+them through cron jobs in case their connection drops,
+@xref{Top,,,ssh-tunneler,SSH Tunneler Reference Manual}. While not as
+general as the baseline ssh tunneler Guix service, configuration through
+whispers is probably simpler in some aspects.
+
+@item ssh agent
+Run any of the system's users ssh agent as a permanent service in
+whispers, including automatically adding user-configured keys into the
+agent.
+
+@end table
+
+@menu
+* Configuring the ssh hierarchy and services::
+* Configuration example (whispers ssh)::
+@end menu
+
+@node Configuring the ssh hierarchy and services, Configuration example (whispers ssh), The ssh hierarchy, The ssh hierarchy
+@subsection Configuring the ssh hierarchy and services
+
+@defvar whispers-ssh-service-type
+This is the type for the service extending whispers with a ssh hierarchy
+and its associated services. Its value must be a
+@code{whispers-ssh-configuration} record.
+
+@end defvar
+
+@deftp {Data Type} whispers-ssh-configuration
+
+@table @asis
+
+@item @code{ssh-package} (default @code{openssh})
+A file-like object. The ssh package to use.
+
+@item @code{users-groups-keys-forwards} (default @code{()})
+A list of @code{ssh-user-group-keys-forwards} records configuring the
+ssh hierarchy and its services, containing one member for each user
+making use of the hierarchy, be they root or unprivileged users.
+
+@end table
+
+@end deftp
+
+A record of type @code{ssh-user-group-keys-forwards} configures the
+hierarchy and its services for a single user of the system.
+
+@deftp {Data Type} ssh-user-group-keys-forwards
+
+@table @asis
+
+@item @code{user-and-group} (default @code{(whispers-user-group)})
+A record of the @code{whispers-user-group} type, @xref{Unprivileged
+services}. Its default is the record type's default record.
+
+@item @code{agent?} (default @code{#t})
+A boolean value. Whether to extend an ssh agent as a service for this
+user in the hierarchy.
+
+@item @code{keys} (default @code{()})
+A list of strings. Paths to ssh keys to load into the agent
+automatically.
+
+@item @code{tunneler?} (default @code{#f})
+A boolean value. Whether to extend ssh tunneling/forwarding as a service
+for this user in the hierarchy.
+
+@item @code{forwardings} (default @code{()})
+A list of of records of the @code{whispers-forwarding} type. Each member
+of the list configures one ssh connection with forwarding(s).
+
+@end table
+
+@end deftp
+
+A record of type @code{whispers-forwarding} configures a service which
+daemonizes a single ssh connection.
+
+@deftp {Data Type} whispers-forwarding
+
+@table @asis
+
+@item @code{forwards} (default @code{()})
+A list of records of type @code{ssh-forward-configuration}, @xref{Client
+system configuration,,,ssh-tunneler,SSH Tunneler Reference Manual}. Each
+member of this list configures one forwarding of the connection.
+
+@item @code{name-prefix} (default @code{"ssh-forwards"})
+A string used to name the service. This gets cast into a symbol forming
+part or all of the shepherd provision for the service.
+
+@item @code{suffix-name?} (default @code{#t})
+A boolean value. Whether to add a computed suffix that describes the
+forwardings to @code{stealth-name-prefix}.
+
+@item @code{use-agent?} (default @code{#t})
+A boolean value. Whether the connection should use the keys loaded into
+a running ssh agent.
+
+@item @code{clear-password?} (default @code{#f})
+A boolean value. Whether to wrap the connection in
+@command{sshpass}. This is strictly discouraged for security and privacy
+in general, and this should probably @emph{never} be used on a
+multi-user computer. Toggling this field in a system configuration is
+even worse than using @command{sshpass} directly from command-line, see
+the @code{clear-password} field documentation for why.
+
+@item @code{clear-password} (default @code{""})
+A string. The password that @command{sshpass} will use, when configured
+to do so. Be advised that this password goes into the Guix store in
+clear-text.
+
+@item @code{sshd-user} (default @code{"root"})
+A string. The user for ssh to connect as on the @code{sshd-host}.
+
+@item @code{sshd-host} (default @code{"127.0.0.1"})
+A string. The sshd host to connect to.
+
+@item @code{sshd-port} (default @code{22})
+An integer. The port used to connect to the sshd on @code{sshd-host}.
+
+@item @code{strict-check} (default @code{"yes"})
+A string. Whether ssh will perform strict key checking of the presented
+host keys when connecting.
+
+@item @code{known-hosts-files} (default @code{("~/.ssh/known_hosts" "~/.ssh/known_hosts2")})
+A list of strings. Files where ssh will look for known hosts in order to
+perform its host key checking.
+
+@item @code{server-alive-interval} (default @code{30})
+An integer, which is passed as the value for the corresponding options
+of @command{ssh}.
+
+@item @code{server-alive-count-max} (default @code{6})
+An integer, which is passed as the value for the corresponding options
+of @command{ssh}.
+
+@item @code{resurrect?} (default @code{#t})
+A boolean value. Whether the superior shepherd of the connection service
+should perform a @code{resurrect} action on the service through an
+extended @command{mcron} job, @pxref{Shepherd actions,,,ssh-tunneler,SSH
+Tunneler Reference Manual}.
+
+@item @code{resurrect-time-spec} (default @code{''(next-minute '(47))})
+A quoted cron time job specification, @pxref{Guile
+Syntax,,,mcron,mcron}, defining the time at which the service and, when
+applicable, its proxy service are resurrected if stopped or disabled,
+when configured to do so through the @code{resurrect?} field of this
+record.
+
+@item @code{force-resurrect?} (default @code{#t})
+A boolean value. Whether the superior shepherd of the connection service
+should perform a @code{force-resurrect} action on the service through an
+extended @command{mcron} job, @pxref{Shepherd actions,,,ssh-tunneler,SSH
+Tunneler Reference Manual}.
+
+@item @code{force-resurrect-time-spec} (default @code{''(next-hour '(3))})
+A quoted cron time job specification, @pxref{Guile
+Syntax,,,mcron,mcron}, defining the time at which the service and, when
+applicable, its proxy service are force-resurrected, when configured to
+do so through the @code{force-resurrect?} field of this record.
+
+@item @code{timeout} (default @code{5})
+An integer. The timeout in seconds for starting the service.
+
+@item @code{stealth?} (default @code{#t})
+A boolean value. Whether to extend a second ssh connection as a proxy,
+for stealth and/or to avoid detection of tunnel forwardings by packet
+scanning from hostile firewalls. This connection used for proxying opens
+a dynamic forward to a proxy of your choice, through a dedicated
+lieutenant service of type @code{persistent-ssh-service-type}
+(@pxref{Client system configuration,,,ssh-tunneler,SSH Tunneler
+Reference Manual}) and is also configured by fields of this record (see
+below).
+
+@item @code{stealth-name-prefix} (default @code{"ssh-forwards"})
+A string used to name the stealth service. This gets cast into a symbol
+forming part or all of the shepherd provision for this service.
+
+@item @code{stealth-suffix-name?} (default @code{#t})
+A boolean value. Whether to add a computed suffix that describes the
+forwarding used for proxying to @code{stealth-name-prefix}.
+
+@item @code{stealth-use-agent?} (default @code{#t})
+A boolean value. Whether the proxy connection should use the keys loaded
+into a running ssh agent, when the @code{stealth?}
+field of this record is toggled.
+
+@item @code{stealth-clear-password?} (default @code{#f})
+A boolean value. Whether to wrap the proxy connection in
+@command{sshpass}. This is strictly discouraged for security and privacy
+in general, and this should probably @emph{never} be used on a
+multi-user computer. Toggling this field in a system configuration is
+even worse than using @command{sshpass} directly from command-line, see
+the @code{stealth-clear-password} field documentation for why.
+
+@item @code{stealth-clear-password} (default @code{""})
+A string. The password that @command{sshpass} will use, when the
+@code{stealth?} field of this record is toggled and configured to do
+so. Be advised that this password goes into the Guix store in
+clear-text.
+
+@item @code{stealth-sshd-user} (default @code{"root"})
+A string. The user for ssh to connect as on the @code{stealth
+sshd-host}, when the @code{stealth?} field of this record is toggled.
+
+@item @code{stealth-sshd-host} (default @code{"127.0.0.1"})
+A string. The sshd host to connect to for the proxy connection, when the
+@code{stealth?} field of this record is toggled.
+
+@item @code{stealth-sshd-port} (default @code{22})
+An integer. The port used to connect to the sshd on @code{sshd-host},
+when the @code{stealth?} field of this record is toggled.
+
+@item @code{stealth-strict-check} (default @code{"yes"})
+A string. Whether ssh will perform strict key checking of the presented
+host keys when connecting the proxy connection, when the @code{stealth?}
+field of this record is toggled.
+
+@item @code{stealth-known-hosts-files} (default @code{("~/.ssh/known_hosts" "~/.ssh/known_hosts2")})
+A list of strings. Files where ssh will look for known hosts in order to
+perform its host key checking when establishing the proxy connection,
+when the @code{stealth?} field of this record is toggled.
+
+@item @code{stealth-server-alive-interval} (default @code{30})
+An integer, which is passed as the value for the corresponding options
+of @command{ssh} for the proxy connection, when the @code{stealth?}
+field of this record is toggled.
+
+@item @code{stealth-server-alive-count-max} (default @code{6})
+An integer, which is passed as the value for the corresponding options
+of @command{ssh} for the proxy connection, when the @code{stealth?}
+field of this record is toggled.
+
+@item @code{stealth-timeout} (default @code{5})
+An integer. The timeout in seconds for starting the proxy connection
+service, when the @code{stealth?} field of this record is toggled.
+
+@item @code{stealth-proxy-port} (default @code{8585})
+An integer. The port that the proxy connection exposes on localhost as
+part of the dynamic forward to @code{stealth-sshd-host}, when the
+@code{stealth?} field of this record is toggled. In this case, The
+baseline connection service's command is extended in such a way that it
+auto-magically uses this port of localhost to proxy its own connection.
+
+@item @code{%auto-start?} (default @code{#t)})
+A boolean value. Whether the service and, when the @code{stealth?}
+field of this record is toggled, its proxying service should be
+automatically started by their superior shepherd when it starts.
+
+@end table
+
+@end deftp
+
+@node Configuration example (whispers ssh),  , Configuring the ssh hierarchy and services, The ssh hierarchy
+@subsection Configuration examples (whispers ssh)
+
+The hierarchy configured below extends and uses an ssh agent which loads
+a rsa key in a default location, extends and uses a persistent ssh
+connection exposing the host at ip "5.6.7.8" as a socks5 proxy available
+on localhost port 3333, and extends a persistent ssh connection to host
+at ip "1.2.3.4" through the aforementioned proxy which creates one port
+forward and three reverse port forwards.
+
+If their superior is running, the ssh connection and its proxy ssh
+connection get resurrected (if necessary) and force-resurrected (always)
+at periodic times defined by the @code{resurrect-time-spec} and
+@code{force-resurrect-time-spec} quoted cron time job specifications,
+@pxref{Guile Syntax,,,mcron,mcron}.
+
+As for the extended port and reverse port forwardings, in this specific
+example, most presumably, the sshd of the host at ip "1.2.3.4" and of
+the client extending the hierarchy are made mutually available to each
+other on their port 2222, and the 2 other extended reverse forwardings
+can be useful to the BTC and XMR node services of the @code{finance}
+hierarchy, @pxref{Configuration examples (whispers finance)}.
+
+The tree of tmpfs extended by this hierarchy has 2 extremities, located
+at @code{/run/whispers/ssh/root-user/tunneler} and
+@code{/run/whispers/ssh/root-user/ssh-agent}, @pxref{Purpose}. As an
+example, the command @command{whispers -l /ssh/root-user restart
+tunneler} will - by default, and in this example - trigger restarting
+the 2 extended persistent ssh connections, without touching the ssh
+agent service, @pxref{The whispers command}.
+
+@cindex ssh forwarding, example
+@lisp
+(service
+ whispers-ssh-service-type
+ (whispers-ssh-configuration
+  (users-groups-keys-forwards
+   (list
+    (ssh-user-group-keys-forwards
+     (user-and-group (whispers-user-group (user "root")
+                                          (group "root")))
+     (keys '("/root/.ssh/id_rsa"))
+     (tunneler? #t)
+     (forwardings
+      (list
+       (whispers-forwarding
+        (forwards
+         (list
+          (port-forward-configuration
+           (entry-port 2222)) ;; from port 2222 to default exit port 22
+          (reverse-port-forward-configuration
+           (entry-port 2222)) ;; from port 2222 to default exit port 22
+          (reverse-port-forward-configuration
+           (entry-port 8333) ;; for bitcoin node, firewall bypassing
+           (exit-port 8333)) ;;
+          (reverse-port-forward-configuration
+           (entry-port 18080)   ;; for monero node, firewall bypassing
+           (exit-port 18080)))) ;;
+         (sshd-host "1.2.3.4")
+         (resurrect? #t)
+         (resurrect-time-spec ''(next-minute '(32)))
+         (force-resurrect? #t)
+         (force-resurrect-time-spec
+          ''(next-minute-from (next-hour '(2)) '(41)))
+         (stealth? #t)
+         (stealth-sshd-host "5.6.7.8")
+         (stealth-proxy-port 3333)))))))))
+@end lisp
+
+@node The vpn hierarchy, The xdg hierarchy, The ssh hierarchy, Whispers services
+@section The vpn hierachy
+
+This section aims to provide VPN function as a set of shepherd services
+in the whispers tree. At the time of writing, it is entirely
+experimental at this stage and nothing more than proof of concept.
+
+Do not try to use the Whispers VPN, since it is probably insecure and it
+will leave your computer's network in inconsistent states whenever a
+network drop occurs.
+
+For demonstration and debugging purposes only, the
+@command{whispers-vpn-tests} command from the @code{whispers-tests}
+package deploys a network of virtual machines and deploys a VPN between
+them.
+
+@node The xdg hierarchy, Unprivileged services, The vpn hierarchy, Whispers services
+@section The xdg hierarchy
+
+This hierarchy actually only extends shepherd processes and their
+associated directories. It simply aims to provide a tmpfs file system
+for storing temporary files in the @code{XDG_RUNTIME_DIR} directory.
+
+There seem to be some problems with the current approach. Sometimes the
+tmpfs file systems of whispers do not unmount to empty directories when
+whispers is stopped, even when X is not running. Some X applications
+complain about the runtime directory permissions.
+
+@node Unprivileged services,  , The xdg hierarchy, Whispers services
+@section Unprivileged services
+
+@code{whispers-user-group} guix records are used to configure whispers
+services running as normal users:
+
+@deftp {Data Type} whispers-user-group
+
+@table @asis
+
+@item @code{user} (default @code{"johndoe"})
+A string. A user name.
+
+@item @code{group} (default @code{"loner"})
+A string. A group name.
+
+@end table
+
+@end deftp
+
+@node The whispers command, Caveats, Whispers services, Top
+@chapter The whispers command
+
+The whispers command is a simple convenience wrapper around the herd
+program, @xref{Invoking herd,,,shepherd,The GNU Shepherd
+Manual}. Instead of specifying a file path to the listening socket of a
+running shepherd in the whispers tree, the user simply provides its
+absolute whispers tree path as an argument to the @command{--lieutenant}
+option of this command.
+
+@lisp
+
+Usage: whispers [--help-herd]
+                [--usage-herd]
+                [--vers-herd]
+                [-l LIEUTENANT-PATH ACTION [SERVICE [ARG...]]]
+
+@end lisp
+
+The @command{-l} option of the @command{whispers} command takes an
+arbitrary number of positional parameters:
+
+@table @command
+
+@item LIEUTENANT-PATH
+Absolute path to a shepherd lieutenant in the whispers tree. Must start
+with a slash character.
+
+@item ACTION
+The shepherd service action to perform.
+
+@item SERVICE
+The shepherd service of which the ACTION is to be performed.
+
+@item ARG...
+Arguments passed to the procedure of the shepherd action.
+
+@end table
+
+If the @command{--lieutenant} switch and its @command{LIEUTENANT-PATH}
+argument are omitted, and if no other valid command-line options is
+given, an action is performed on a service of the shepherd at the root
+of the whispers tree, which is itself a child process of the root
+shepherd PID 1 handled as one of its services. As such, using
+@command{whispers -l / ACTION [SERVICE [ARG...]]} or @command{whispers
+ACTION [SERVICE [ARG...]]} have exactly the same effect.
+
+Command-line options of the @command{whispers} trigger the following
+effects:
+
+@table @command
+
+@item --help
+Display the help message of the @command{whispers} command.
+
+@item --help-herd
+Display the help message of the @command{herd} command.
+
+@item --lieutenant=@var{LIEUTENANT-PATH}
+@itemx -l @var{LIEUTENANT-PATH}
+Absolute path to a shepherd lieutenant in the whispers tree. Must start
+with a slash character.
+
+@item --usage-herd
+Display the short usage message of the @command{herd} command.
+
+@item --vers-herd
+Display the @command{herd} version.
+
+@end table
+
+A few examples of the @command{whispers} command usage are given below:
+
+@table @command
+
+@item whispers status
+Prints the short status of all services handled by the shepherd at the
+top of the hierarchy.
+
+@item whispers -l /ssh/root-user/tunneler status
+Prints the short status of persistent ssh connections running as root
+within the ssh hierarchy, @xref{The ssh hierarchy}.
+
+@item whispers -l /ssh/root-user/restart tunneler
+Restarts the shepherd service for the shepherd process which daemonizes
+the persistent connections of root. The persistent ssh connections
+themselves will be restarted if the @code{%auto-start?} switch is
+toggled in @code{whispers-forwarding} record populating the
+@code{whispers-ssh-configuration} record value of the Guix service of
+type @code{whispers-ssh-service-type}, in the system configuration.
+
+@end table
+
+@node Caveats, Bugs, The whispers command, Top
+@chapter Caveats
+
+When re-configuring the whole Guix system, whispers services or whispers
+itself are not automatically restarted if their configuration has been
+updated.
+
+In order to run whispers service with an updated configuration after
+reconfiguring the Guix system, it is necessary to restart all of the
+whispers process tree from PID 1, using for example @command{herd
+restart whispers}. Re-starting services lower in the tree, such as with
+the @command{whispers} command will not run them according to their
+updated configuration.
+
+@node Bugs, GNU Free Documentation License, Caveats, Top
+@chapter Bugs
+
+Log rotation is not working in @code{/var/log/whispers}. As of writing,
+the cause of this bug is unknown.
+
+@node GNU Free Documentation License, Concept Index, Bugs, Top
+@appendix GNU Free Documentation License
+@cindex license, GNU Free Documentation License
+@include fdl-1.3.texi
+
+@node Concept Index, Programming Index, GNU Free Documentation License, Top
+@unnumbered Concept Index
+@printindex cp
+
+@node Programming Index,  , Concept Index, Top
+@unnumbered Programming Index
+@syncodeindex tp fn
+@syncodeindex vr fn
+@printindex fn
+
+@bye