Whispers
********

This manual documents Whispers version 0.1.0.

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''.

Definitions
***********

Whispers is a multi-user process tree of shepherd processes and their services, see 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:

Hierarchy
     The part of the whispers process tree constituted of shepherd processes proper is referred to as the whispers 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.

Superior
     The parent process of a process running inside the whispers process tree is called its 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.

Lieutenant
     A child process and service of a shepherd running inside the hierarchy is called a lieutenant of that shepherd process. While non-shepherd processes of the whispers tree are also lieutenants, they cannot have lieutenants themselves.

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 whispers is a simple wrapper around herd providing a convenience switch to control all services in the hierarchy, see 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, see 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 elogind, its dependencies or the facilities it provides.

A directory tree of imbricated tmpfs file systems is also deployed on-demand under /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 herd to trigger the stop action of its service in PID 1, namely by using the 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 /run/whispers directory.

Log files of the whispers hierarchy and its shepherd services are all stored under the path /var/log/whispers, with a sub-directory tree mimicking the hierarchy in its current and past states. All log files should be rotated by default through their respective hierarchy Shepherd's log-rotation service.

Various Scheme sub-modules of (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, see 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, The whispers service.

The whispers service
********************

The (whispers services whispers) scheme module provides a Guix shepherd service which extends a multi-user process tree of shepherd services.

 -- Variable: whispers-service-type
     This is the type for the service extending the shepherd with a whispers process tree. Its value must be an whispers-configuration record.

 -- Data Type: whispers-configuration

     coreutils-package (default coreutils)
          A file-like-object. The coreutils package to use.

     util-linux-package (default util-linux)
          A file-like-object. the util-linux package to use.

     whispers-package (default whispers)
          A file-like-object. the whispers package to use, see The whispers command.

     name (default 'whispers)
          A symbol. The shepherd provision of this whispers service in its superior or PID 1.

     lieutenants (default '())
          A list of Guix service objects. The lieutenants of this whispers service.

     log-rotation? (default #t)
          A boolean value. Whether this shepherd's log-rotation service should be activated. At the time of writing, only a default configuration of the rotation service is supported.

     requires (default '())
          A list of symbols. The list of shepherd provisions that this service requires in its superior or PID 1, a.k.a its dependencies.

     user (default "root")
          A string. The name of the user running this whispers service.

     extend-user? (default #f)
          A boolean value. Whether 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.

     group (default "root")
          A string. The name of the group this whispers service is run as.

     extend-group? (default #f)
          A boolean value. Whether 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.

     timeout (default '(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.

     extra-packages (default (list))
          A list of Guix records of type package. A list of extra packages to include in the profile that this service extends the Guix service of type guix-profile-service-type with.

     extra-actions (default (list))
          A list of shepherd-action records. Extra actions that are provided for this service in its superior or PID 1.

     pre-start-action? (default #f)
          A boolean value. Whether this service performs a shepherd action named pre-start in its superior of PID 1, as part of its start action, immediately before its shepherd process is run by its superior or PID 1. If this flag is set, the pre-start action must be defined within the extra-actions field of this record.

     post-stop-action? (default #f)
          A boolean value. Whether this service performs a shepherd action named post-stop in its superior of PID 1, as part of its stop action, immediately after its shepherd process is terminated by its superior or PID 1. If this flag is set, the pre-start action must be defined within the extra-actions field of this record.

     %auto-start? (default #t)
          A boolean value. Whether this service's superior or PID 1 should automatically start this service when it is started itself.

Service extension relationships
*******************************

The service of type whispers-service-type (see The whispers service) extends multiple other services (see Service Types and Services (GNU guix)):

account-service-type

shepherd-root-service-type
     See Shepherd Services (GNU guix).

mcron-service-type
     See Scheduled Job Execution (GNU guix).

profile-service-type
     See Service Reference (GNU guix).

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 service-extension targeting the service of type 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 service-extension targeting the services of type profile-service-type, mcron-service-type and/or 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.

Other service extensions of services within the whispers service tree should be silently ignored.

On the hand, the service of type 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 whispers services whispers module make use of this mechanism, see Whispers services.

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 whispers services whispers. The facilities offered make configuration simpler than if they were done by hand using general whispers records (see 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 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, see System Configuration (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 root-user. This is done to avoid conflicts, because every shepherd daemon has a built-in service which provisions the symbol root.

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 finance hierarchy. Those features are provided by the whispers services whispers finance module.

Configuring the finance hierachy and services
---------------------------------------------

 -- Variable: 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 whispers-finance-configuration record.

 -- Data Type: whispers-finance-configuration

     users-groups-nodes (default ())
          A list of 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.

A record of type crypto-user-group-nodes configures the hierarchy and its services for a single user of the system.

 -- Data Type: crypto-user-group-nodes

     user-and-group (default (whispers-user-group))
          A record of the whispers-user-group type, see Unprivileged services. Its default is the record type's default record.

     nodes (default (nodes-configuration)
          A record of the nodes-configuration type. Its default is the record type's default record.

A record of type 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.

 -- Data Type: nodes-configuration

     (bitcoin? (default #f)
          A boolean value, whether to extend a bitcoin node as a service.

     (btc-node (default (bitcoin-node-configuration))
          A record of the bitcoin-node-configuration type. Its default is the record type's default record.

     (monero? (default #f)
          A boolean value

     (xmr-node (default (monero-node-configuration))
          A record of the monero-node-configuration type. Its default is the record type's default record.

When the finance hierarchy extends a bitcoin node, the node is configured by a record of type bitcoin-node-configuration .

 -- Data Type: bitcoin-node-configuration

     bitcoin-package (default bitcoin-core)
          A file-like object. The bitcoin package to use.

     walletdir-opt? (default #f)
          A boolean value. Whether to set the -walletdir option explicitly for the service.

     walletdir (default "")
          A string. The value for the -walletdir option when it is explicitly set.

     proxy-opt? (default #f)
          A boolean value. Whether to set the -proxy option explicitly for the service.

     proxy (default "")
          A string. The value for the -proxy option when it is explicitly set.

     %auto-start? (default #t)
          A boolean value. Whether the service should be started automatically when its superior starts.

When the finance hierarchy extends a monero node, the node is configured by a record of type monero-node-configuration .

 -- Data Type: monero-node-configuration

     bitcoin-package (default bitcoin-core)
          A file-like object. The bitcoin package to use.

     proxy-opt? (default #f)
          A boolean value. Whether to set the --proxy option explicitly for the service.

     proxy (default "")
          A string. The value for the --proxy option when it is explicitly set.

     proxy-opt? (default #f)
          A boolean value. Whether to set the --tx-proxy option explicitly for the service.

     proxy (default "")
          A string. The value for the --tx-proxy option when it is explicitly set.

     prune-blockchain-opt? (default #f)
          A boolean value. Whether to use the --prune-blockchain option for the service.

     %auto-start? (default #t)
          A boolean value. Whether the service should be started automatically when its superior starts.

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 whispers-finance-service-type does not take care of extending this proxy automatically; it can be done for example using a service of type whispers-ssh-service-type, see The ssh hierarchy. Incidentally, should it be desirable or necessary, a service of type 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.

     (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"))))))))

The gps hierarchy
=================

A gpsd service can be deployed as shepherd services run by an unprivileged user within the gps hierarchy. Those features are provided by the whispers services whispers gps module.

Configuring the gps hierarchy and services
------------------------------------------

 -- Variable: 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 gps-user-group-configs records.

 -- Data Type: gps-user-group-configs

     user-and-group (default (whispers-user-group))
          A record of the whispers-user-group type, see Unprivileged services. Its default is the record type's default record.

     gpsd? (default #t)
          A boolean value. Whether to extend gpsd(s) as service(s) for this user in the hierarchy.

     gpsd-configs (default (list (gpsd-configuration)))
          A list of records of the gpsd-configuration type. The default is a list whose single member is the default value of a gpsd-configuration record.

The whispers services gps module exports the gpsd-configuration record type which is used to configure a single gpsd service for a user in the hierarchy.

 -- Data Type: gpsd-configuration

     gpsd-package (default gpsd)
          A file-like object. The gpsd package to use.

     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 gpsd- and the value of port field of this record.

     source (default "/dev/ttyUSB0)
          A string. The source from which gpsd receives gps data input.

     port (default 2947)
          An integer. The port on which gpsd serves GPS data for other programs.

     listen-any? (default #f)
          A boolean value. Whether gpsd should listen on any interface, as opposed to just listening on loopback.

     %auto-start? (default #t)
          A boolean value. Whether the service should be started automatically when its superior starts.

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.

     (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")))))))

The mail hierarchy
==================

An 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 whispers services whispers mail module.

Configuring the mail hierarchy and services
-------------------------------------------

 -- Variable: 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 whispers-mail-configuration record.

 -- Data Type: whispers-mail-configuration

     users-groups-services (default ())
          A list of 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.

 -- Data Type: user-group-services

     user-and-group (default (whispers-user-group))
          A record of the whispers-user-group type, see Unprivileged services. Its default is the record type's default record.

     services (default (mail-services-configuration))
          A record of the mail-services-configuration type. The default is the default value of a mail-services-configuration record.

A record of type mail-services-configuration configures mail services for a single user in the hierarchy.

 -- Data Type: mail-services-configuration

     user-and-group (default #f)
          A boolean value, whether an hydroxide service should be deployed for this user in the hierarchy.

     hydroxide-service (default (hydroxide-service-configuration))
          A record of the hydroxide-configuration type. The default is the default value of a hydroxide-service-configuration record.

A record of type hydroxide-service-configuration configures the hydroxide service for a single user in the hierarchy.

 -- Data Type: hydroxide-service-configuration

     hydroxide-package (default hydroxide)
          A file-like object. The hydroxide package to use.

     https-proxy? (default #f)
          A boolean value. Whether hydroxide should connect to the proton mail servers behind a proxy.

     https-proxy (default "socks5://localhost:8971")
          A string specifying the proxy that hydroxide will use, when applicable per the provision of the https-proxy? field. The proxy is set using this string by exporting it as the value of an https_proxy variable into hydroxide's environment.

     imap? (default #t)
          A boolean value. Whether hydroxide should listen to IMAP protocol requests from the loopback interface.

     smtp? (default #t)
          A boolean value. Whether hydroxide should listen to IMAP protocol requests from the loopback interface.

     carddav? (default #t)
          A boolean value. Whether hydroxide should listen to IMAP protocol requests from the loopback interface.

     %auto-start? (default #t)
          A boolean value. Whether the service should be started automatically when its superior starts.

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 whispers-mail-service-type does not take care of extending this proxy automatically, it can be done for example using a service of type whispers-ssh-service-type, see 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.

     (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"))))))))

The ssh hierarchy
=================

The facilities in the whispers services whispers ssh module provide ssh-related features to a system and its users:

ssh forwarding
     A wrapper around the 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, see SSH Tunneler Reference Manual. While not as general as the baseline ssh tunneler Guix service, configuration through whispers is probably simpler in some aspects.

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.

Configuring the ssh hierarchy and services
------------------------------------------

 -- Variable: 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 whispers-ssh-configuration record.

 -- Data Type: whispers-ssh-configuration

     ssh-package (default openssh)
          A file-like object. The ssh package to use.

     users-groups-keys-forwards (default ())
          A list of 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.

A record of type ssh-user-group-keys-forwards configures the hierarchy and its services for a single user of the system.

 -- Data Type: ssh-user-group-keys-forwards

     user-and-group (default (whispers-user-group))
          A record of the whispers-user-group type, see Unprivileged services. Its default is the record type's default record.

     agent? (default #t)
          A boolean value. Whether to extend an ssh agent as a service for this user in the hierarchy.

     keys (default ())
          A list of strings. Paths to ssh keys to load into the agent automatically.

     tunneler? (default #f)
          A boolean value. Whether to extend ssh tunneling/forwarding as a service for this user in the hierarchy.

     forwardings (default ())
          A list of of records of the whispers-forwarding type. Each member of the list configures one ssh connection with forwarding(s).

A record of type whispers-forwarding configures a service which daemonizes a single ssh connection.

 -- Data Type: whispers-forwarding

     forwards (default ())
          A list of records of type ssh-forward-configuration, see Client system configuration (SSH Tunneler Reference Manual). Each member of this list configures one forwarding of the connection.

     name-prefix (default "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.

     suffix-name? (default #t)
          A boolean value. Whether to add a computed suffix that describes the forwardings to stealth-name-prefix.

     use-agent? (default #t)
          A boolean value. Whether the connection should use the keys loaded into a running ssh agent.

     clear-password? (default #f)
          A boolean value. Whether to wrap the connection in sshpass. This is strictly discouraged for security and privacy in general, and this should probably never be used on a multi-user computer. Toggling this field in a system configuration is even worse than using sshpass directly from command-line, see the clear-password field documentation for why.

     clear-password (default "")
          A string. The password that sshpass will use, when configured to do so. Be advised that this password goes into the Guix store in clear-text.

     sshd-user (default "root")
          A string. The user for ssh to connect as on the sshd-host.

     sshd-host (default "127.0.0.1")
          A string. The sshd host to connect to.

     sshd-port (default 22)
          An integer. The port used to connect to the sshd on sshd-host.

     strict-check (default "yes")
          A string. Whether ssh will perform strict key checking of the presented host keys when connecting.

     known-hosts-files (default ("~/.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.

     server-alive-interval (default 30)
          An integer, which is passed as the value for the corresponding options of ssh.

     server-alive-count-max (default 6)
          An integer, which is passed as the value for the corresponding options of ssh.

     resurrect? (default #t)
          A boolean value. Whether the superior shepherd of the connection service should perform a resurrect action on the service through an extended mcron job, see Shepherd actions (SSH Tunneler Reference Manual).

     resurrect-time-spec (default ''(next-minute '(47)))
          A quoted cron time job specification, see Guile Syntax (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 resurrect? field of this record.

     force-resurrect? (default #t)
          A boolean value. Whether the superior shepherd of the connection service should perform a force-resurrect action on the service through an extended mcron job, see Shepherd actions (SSH Tunneler Reference Manual).

     force-resurrect-time-spec (default ''(next-hour '(3)))
          A quoted cron time job specification, see Guile Syntax (mcron), defining the time at which the service and, when applicable, its proxy service are force-resurrected, when configured to do so through the force-resurrect? field of this record.

     timeout (default 5)
          An integer. The timeout in seconds for starting the service.

     stealth? (default #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 persistent-ssh-service-type (see Client system configuration (SSH Tunneler Reference Manual)) and is also configured by fields of this record (see below).

     stealth-name-prefix (default "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.

     stealth-suffix-name? (default #t)
          A boolean value. Whether to add a computed suffix that describes the forwarding used for proxying to stealth-name-prefix.

     stealth-use-agent? (default #t)
          A boolean value. Whether the proxy connection should use the keys loaded into a running ssh agent, when the stealth? field of this record is toggled.

     stealth-clear-password? (default #f)
          A boolean value. Whether to wrap the proxy connection in sshpass. This is strictly discouraged for security and privacy in general, and this should probably never be used on a multi-user computer. Toggling this field in a system configuration is even worse than using sshpass directly from command-line, see the stealth-clear-password field documentation for why.

     stealth-clear-password (default "")
          A string. The password that sshpass will use, when the 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.

     stealth-sshd-user (default "root")
          A string. The user for ssh to connect as on the stealth sshd-host, when the stealth? field of this record is toggled.

     stealth-sshd-host (default "127.0.0.1")
          A string. The sshd host to connect to for the proxy connection, when the stealth? field of this record is toggled.

     stealth-sshd-port (default 22)
          An integer. The port used to connect to the sshd on sshd-host, when the stealth? field of this record is toggled.

     stealth-strict-check (default "yes")
          A string. Whether ssh will perform strict key checking of the presented host keys when connecting the proxy connection, when the stealth? field of this record is toggled.

     stealth-known-hosts-files (default ("~/.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 stealth? field of this record is toggled.

     stealth-server-alive-interval (default 30)
          An integer, which is passed as the value for the corresponding options of ssh for the proxy connection, when the stealth? field of this record is toggled.

     stealth-server-alive-count-max (default 6)
          An integer, which is passed as the value for the corresponding options of ssh for the proxy connection, when the stealth? field of this record is toggled.

     stealth-timeout (default 5)
          An integer. The timeout in seconds for starting the proxy connection service, when the stealth? field of this record is toggled.

     stealth-proxy-port (default 8585)
          An integer. The port that the proxy connection exposes on localhost as part of the dynamic forward to stealth-sshd-host, when the 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.

     stealth-extra-forwards (default '())
          A list of records of type ssh-forward-configuration, see Client system configuration (SSH Tunneler Reference Manual). Each of its members configures a forwarding to be added to the ssh connection of the client running whispers to the sshd of the proxy server providing stealth, in addition to the dynamic forward used for stealth proper.

     %auto-start? (default #t))
          A boolean value. Whether the service and, when the stealth? field of this record is toggled, its proxying service should be automatically started by their superior shepherd when it starts.

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 resurrect-time-spec and force-resurrect-time-spec quoted cron time job specifications, see Guile Syntax (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 finance hierarchy, see Configuration examples (whispers finance).

The tree of tmpfs extended by this hierarchy has 2 extremities, located at /run/whispers/ssh/root-user/tunneler and /run/whispers/ssh/root-user/ssh-agent, see Purpose. As an example, the 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, see The whispers command.

     (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)))))))))

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 whispers-vpn-tests command from the whispers-tests package deploys a network of virtual machines and deploys a VPN between them.

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 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.

Unprivileged services
=====================

whispers-user-group guix records are used to configure whispers services running as normal users:

 -- Data Type: whispers-user-group

     user (default "johndoe")
          A string. A user name.

     group (default "loner")
          A string. A group name.

The whispers command
********************

The whispers command is a simple convenience wrapper around the herd program, see Invoking herd (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 --lieutenant option of this command.

     Usage: whispers [--help-herd]
                     [--usage-herd]
                     [--vers-herd]
                     [-l LIEUTENANT-PATH ACTION [SERVICE [ARG...]]]

The -l option of the whispers command takes an arbitrary number of positional parameters:

LIEUTENANT-PATH
     Absolute path to a shepherd lieutenant in the whispers tree. Must start with a slash character.

ACTION
     The shepherd service action to perform.

SERVICE
     The shepherd service of which the ACTION is to be performed.

ARG...
     Arguments passed to the procedure of the shepherd action.

If the --lieutenant switch and its 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 whispers -l / ACTION [SERVICE [ARG...]] or whispers ACTION [SERVICE [ARG...]] have exactly the same effect.

Command-line options of the whispers trigger the following effects:

--help
     Display the help message of the whispers command.

--help-herd
     Display the help message of the herd command.

--lieutenant=LIEUTENANT-PATH
-l LIEUTENANT-PATH
     Absolute path to a shepherd lieutenant in the whispers tree. Must start with a slash character.

--usage-herd
     Display the short usage message of the herd command.

--vers-herd
     Display the herd version.

A few examples of the whispers command usage are given below:

whispers status
     Prints the short status of all services handled by the shepherd at the top of the hierarchy.

whispers -l /ssh/root-user/tunneler status
     Prints the short status of persistent ssh connections running as root within the ssh hierarchy, see The ssh hierarchy.

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 %auto-start? switch is toggled in whispers-forwarding record populating the whispers-ssh-configuration record value of the Guix service of type whispers-ssh-service-type, in the system configuration.

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 herd restart whispers. Re-starting services lower in the tree, such as with the whispers command will not run them according to their updated configuration.

Bugs
****

GNU Free Documentation License
******************************

     [file fdl-1.3.texi not included]