Next: , Previous: , Up: Services   [Contents][Index]


12.9.5 Networking Services

The (gnu services networking) module discussed in the previous section provides services for more advanced setups: providing a DHCP service for others to use, filtering packets with iptables or nftables, running a WiFi access point with hostapd, running the inetd “superdaemon”, and more. This section describes those.

Scheme Procedure: dhcpd-service-type

This type defines a service that runs a DHCP daemon. To create a service of this type, you must supply a <dhcpd-configuration>. For example:

(service dhcpd-service-type
         (dhcpd-configuration
          (config-file (local-file "my-dhcpd.conf"))
          (interfaces '("enp0s25"))))
Data Type: dhcpd-configuration
package (default: isc-dhcp)

The package that provides the DHCP daemon. This package is expected to provide the daemon at sbin/dhcpd relative to its output directory. The default package is the ISC’s DHCP server.

config-file (default: #f)

The configuration file to use. This is required. It will be passed to dhcpd via its -cf option. This may be any “file-like” object (see file-like objects). See man dhcpd.conf for details on the configuration file syntax.

version (default: "4")

The DHCP version to use. The ISC DHCP server supports the values “4”, “6”, and “4o6”. These correspond to the dhcpd program options -4, -6, and -4o6. See man dhcpd for details.

run-directory (default: "/run/dhcpd")

The run directory to use. At service activation time, this directory will be created if it does not exist.

pid-file (default: "/run/dhcpd/dhcpd.pid")

The PID file to use. This corresponds to the -pf option of dhcpd. See man dhcpd for details.

interfaces (default: '())

The names of the network interfaces on which dhcpd should listen for broadcasts. If this list is not empty, then its elements (which must be strings) will be appended to the dhcpd invocation when starting the daemon. It may not be necessary to explicitly specify any interfaces here; see man dhcpd for details.

Scheme Variable: hostapd-service-type

This is the service type to run the hostapd daemon to set up WiFi (IEEE 802.11) access points and authentication servers. Its associated value must be a hostapd-configuration as shown below:

;; Use wlan1 to run the access point for "My Network".
(service hostapd-service-type
         (hostapd-configuration
          (interface "wlan1")
          (ssid "My Network")
          (channel 12)))
Data Type: hostapd-configuration

This data type represents the configuration of the hostapd service, with the following fields:

package (default: hostapd)

The hostapd package to use.

interface (default: "wlan0")

The network interface to run the WiFi access point.

ssid

The SSID (service set identifier), a string that identifies this network.

broadcast-ssid? (default: #t)

Whether to broadcast this SSID.

channel (default: 1)

The WiFi channel to use.

driver (default: "nl80211")

The driver interface type. "nl80211" is used with all Linux mac80211 drivers. Use "none" if building hostapd as a standalone RADIUS server that does # not control any wireless/wired driver.

extra-settings (default: "")

Extra settings to append as-is to the hostapd configuration file. See https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf for the configuration file reference.

Scheme Variable: simulated-wifi-service-type

This is the type of a service to simulate WiFi networking, which can be useful in virtual machines for testing purposes. The service loads the Linux kernel mac80211_hwsim module and starts hostapd to create a pseudo WiFi network that can be seen on wlan0, by default.

The service’s value is a hostapd-configuration record.

Scheme Variable: iptables-service-type

This is the service type to set up an iptables configuration. iptables is a packet filtering framework supported by the Linux kernel. This service supports configuring iptables for both IPv4 and IPv6. A simple example configuration rejecting all incoming connections except those to the ssh port 22 is shown below.

(service iptables-service-type
         (iptables-configuration
          (ipv4-rules (plain-file "iptables.rules" "*filter
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp-port-unreachable
COMMIT
"))
          (ipv6-rules (plain-file "ip6tables.rules" "*filter
:INPUT ACCEPT
:FORWARD ACCEPT
:OUTPUT ACCEPT
-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp6-port-unreachable
COMMIT
"))))
Data Type: iptables-configuration

The data type representing the configuration of iptables.

iptables (default: iptables)

The iptables package that provides iptables-restore and ip6tables-restore.

ipv4-rules (default: %iptables-accept-all-rules)

The iptables rules to use. It will be passed to iptables-restore. This may be any “file-like” object (see file-like objects).

ipv6-rules (default: %iptables-accept-all-rules)

The ip6tables rules to use. It will be passed to ip6tables-restore. This may be any “file-like” object (see file-like objects).

Scheme Variable: nftables-service-type

This is the service type to set up a nftables configuration. nftables is a netfilter project that aims to replace the existing iptables, ip6tables, arptables and ebtables framework. It provides a new packet filtering framework, a new user-space utility nft, and a compatibility layer for iptables. This service comes with a default ruleset %default-nftables-ruleset that rejecting all incoming connections except those to the ssh port 22. To use it, simply write:

Data Type: nftables-configuration

The data type representing the configuration of nftables.

package (default: nftables)

The nftables package that provides nft.

ruleset (default: %default-nftables-ruleset)

The nftables ruleset to use. This may be any “file-like” object (see file-like objects).

Scheme Variable: ntp-service-type

This is the type of the service running the Network Time Protocol (NTP) daemon, ntpd. The daemon will keep the system clock synchronized with that of the specified NTP servers.

The value of this service is an ntpd-configuration object, as described below.

Data Type: ntp-configuration

This is the data type for the NTP service configuration.

servers (default: %ntp-servers)

This is the list of servers (<ntp-server> records) with which ntpd will be synchronized. See the ntp-server data type definition below.

allow-large-adjustment? (default: #t)

This determines whether ntpd is allowed to make an initial adjustment of more than 1,000 seconds.

ntp (default: ntp)

The NTP package to use.

Scheme Variable: %ntp-servers

List of host names used as the default NTP servers. These are servers of the NTP Pool Project.

Data Type: ntp-server

The data type representing the configuration of a NTP server.

type (default: 'server)

The type of the NTP server, given as a symbol. One of 'pool, 'server, 'peer, 'broadcast or 'manycastclient.

address

The address of the server, as a string.

options

NTPD options to use with that specific server, given as a list of option names and/or of option names and values tuples. The following example define a server to use with the options iburst and prefer, as well as version 3 and a maxpoll time of 16 seconds.

(ntp-server
 (type 'server)
 (address "some.ntp.server.org")
 (options `(iburst (version 3) (maxpoll 16) prefer))))
Scheme Procedure: openntpd-service-type

Run the ntpd, the Network Time Protocol (NTP) daemon, as implemented by OpenNTPD. The daemon will keep the system clock synchronized with that of the given servers.

(service
 openntpd-service-type
 (openntpd-configuration
  (listen-on '("127.0.0.1" "::1"))
  (sensor '("udcf0 correction 70000"))
  (constraint-from '("www.gnu.org"))
  (constraints-from '("https://www.google.com/"))))

Scheme Variable: %openntpd-servers

This variable is a list of the server addresses defined in %ntp-servers.

Data Type: openntpd-configuration
openntpd (default: (file-append openntpd "/sbin/ntpd"))

The openntpd executable to use.

listen-on (default: '("127.0.0.1" "::1"))

A list of local IP addresses or hostnames the ntpd daemon should listen on.

query-from (default: '())

A list of local IP address the ntpd daemon should use for outgoing queries.

sensor (default: '())

Specify a list of timedelta sensor devices ntpd should use. ntpd will listen to each sensor that actually exists and ignore non-existent ones. See upstream documentation for more information.

server (default: '())

Specify a list of IP addresses or hostnames of NTP servers to synchronize to.

servers (default: %openntp-servers)

Specify a list of IP addresses or hostnames of NTP pools to synchronize to.

constraint-from (default: '())

ntpd can be configured to query the ‘Date’ from trusted HTTPS servers via TLS. This time information is not used for precision but acts as an authenticated constraint, thereby reducing the impact of unauthenticated NTP man-in-the-middle attacks. Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide a constraint.

constraints-from (default: '())

As with constraint from, specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide a constraint. Should the hostname resolve to multiple IP addresses, ntpd will calculate a median constraint from all of them.

Scheme variable: inetd-service-type

This service runs the inetd (see inetd invocation in GNU Inetutils) daemon. inetd listens for connections on internet sockets, and lazily starts the specified server program when a connection is made on one of these sockets.

The value of this service is an inetd-configuration object. The following example configures the inetd daemon to provide the built-in echo service, as well as an smtp service which forwards smtp traffic over ssh to a server smtp-server behind a gateway hostname:

(service
 inetd-service-type
 (inetd-configuration
  (entries (list
            (inetd-entry
             (name "echo")
             (socket-type 'stream)
             (protocol "tcp")
             (wait? #f)
             (user "root"))
            (inetd-entry
             (node "127.0.0.1")
             (name "smtp")
             (socket-type 'stream)
             (protocol "tcp")
             (wait? #f)
             (user "root")
             (program (file-append openssh "/bin/ssh"))
             (arguments
              '("ssh" "-qT" "-i" "/path/to/ssh_key"
                "-W" "smtp-server:25" "user@hostname")))))))

See below for more details about inetd-configuration.

Data Type: inetd-configuration

Data type representing the configuration of inetd.

program (default: (file-append inetutils "/libexec/inetd"))

The inetd executable to use.

entries (default: '())

A list of inetd service entries. Each entry should be created by the inetd-entry constructor.

Data Type: inetd-entry

Data type representing an entry in the inetd configuration. Each entry corresponds to a socket where inetd will listen for requests.

node (default: #f)

Optional string, a comma-separated list of local addresses inetd should use when listening for this service. See Configuration file in GNU Inetutils for a complete description of all options.

name

A string, the name must correspond to an entry in /etc/services.

socket-type

One of 'stream, 'dgram, 'raw, 'rdm or 'seqpacket.

protocol

A string, must correspond to an entry in /etc/protocols.

wait? (default: #t)

Whether inetd should wait for the server to exit before listening to new service requests.

user

A string containing the user (and, optionally, group) name of the user as whom the server should run. The group name can be specified in a suffix, separated by a colon or period, i.e. "user", "user:group" or "user.group".

program (default: "internal")

The server program which will serve the requests, or "internal" if inetd should use a built-in service.

arguments (default: '())

A list strings or file-like objects, which are the server program’s arguments, starting with the zeroth argument, i.e. the name of the program itself. For inetd’s internal services, this entry must be '() or '("internal").

See Configuration file in GNU Inetutils for a more detailed discussion of each configuration field.

Scheme Variable: opendht-service-type

This is the type of the service running a OpenDHT node, dhtnode. The daemon can be used to host your own proxy service to the distributed hash table (DHT), for example to connect to with Jami, among other applications.

Important: When using the OpenDHT proxy server, the IP addresses it “sees” from the clients should be addresses reachable from other peers. In practice this means that a publicly reachable address is best suited for a proxy server, outside of your private network. For example, hosting the proxy server on a IPv4 private local network and exposing it via port forwarding could work for external peers, but peers local to the proxy would have their private addresses shared with the external peers, leading to connectivity problems.

The value of this service is a opendht-configuration object, as described below.

Data Type: opendht-configuration

Available opendht-configuration fields are:

opendht (default: opendht) (type: file-like)

The opendht package to use.

peer-discovery? (default: #f) (type: boolean)

Whether to enable the multicast local peer discovery mechanism.

enable-logging? (default: #f) (type: boolean)

Whether to enable logging messages to syslog. It is disabled by default as it is rather verbose.

debug? (default: #f) (type: boolean)

Whether to enable debug-level logging messages. This has no effect if logging is disabled.

bootstrap-host (default: "bootstrap.jami.net:4222") (type: maybe-string)

The node host name that is used to make the first connection to the network. A specific port value can be provided by appending the :PORT suffix. By default, it uses the Jami bootstrap nodes, but any host can be specified here. It’s also possible to disable bootstrapping by explicitly setting this field to the %unset-value value.

port (default: 4222) (type: maybe-number)

The UDP port to bind to. When left unspecified, an available port is automatically selected.

proxy-server-port (type: maybe-number)

Spawn a proxy server listening on the specified port.

proxy-server-port-tls (type: maybe-number)

Spawn a proxy server listening to TLS connections on the specified port.

Scheme Variable: tor-service-type

This is the type for a service that runs the Tor anonymous networking daemon. The service is configured using a <tor-configuration> record. By default, the Tor daemon runs as the tor unprivileged user, which is a member of the tor group.

Data Type: tor-configuration
tor (default: tor)

The package that provides the Tor daemon. This package is expected to provide the daemon at bin/tor relative to its output directory. The default package is the Tor Project’s implementation.

config-file (default: (plain-file "empty" ""))

The configuration file to use. It will be appended to a default configuration file, and the final configuration file will be passed to tor via its -f option. This may be any “file-like” object (see file-like objects). See man tor for details on the configuration file syntax.

hidden-services (default: '())

The list of <hidden-service> records to use. For any hidden service you include in this list, appropriate configuration to enable the hidden service will be automatically added to the default configuration file. You may conveniently create <hidden-service> records using the tor-hidden-service procedure described below.

socks-socket-type (default: 'tcp)

The default socket type that Tor should use for its SOCKS socket. This must be either 'tcp or 'unix. If it is 'tcp, then by default Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost). If it is 'unix, then Tor will listen on the UNIX domain socket /var/run/tor/socks-sock, which will be made writable by members of the tor group.

If you want to customize the SOCKS socket in more detail, leave socks-socket-type at its default value of 'tcp and use config-file to override the default by providing your own SocksPort option.

control-socket? (default: #f)

Whether or not to provide a “control socket” by which Tor can be controlled to, for instance, dynamically instantiate tor onion services. If #t, Tor will listen for control commands on the UNIX domain socket /var/run/tor/control-sock, which will be made writable by members of the tor group.

Scheme Procedure: tor-hidden-service name mapping

Define a new Tor hidden service called name and implementing mapping. mapping is a list of port/host tuples, such as:

 '((22 "127.0.0.1:22")
   (80 "127.0.0.1:8080"))

In this example, port 22 of the hidden service is mapped to local port 22, and port 80 is mapped to local port 8080.

This creates a /var/lib/tor/hidden-services/name directory, where the hostname file contains the .onion host name for the hidden service.

See the Tor project’s documentation for more information.

The (gnu services rsync) module provides the following services:

You might want an rsync daemon if you have files that you want available so anyone (or just yourself) can download existing files or upload new files.

Scheme Variable: rsync-service-type

This is the service type for the rsync daemon, The value for this service type is a rsync-configuration record as in this example:

;; Export two directories over rsync.  By default rsync listens on
;; all the network interfaces.
(service rsync-service-type
         (rsync-configuration
           (modules (list (rsync-module
                            (name "music")
                            (file-name "/srv/zik")
                            (read-only? #f))
                          (rsync-module
                            (name "movies")
                            (file-name "/home/charlie/movies"))))))

See below for details about rsync-configuration.

Data Type: rsync-configuration

Data type representing the configuration for rsync-service.

package (default: rsync)

rsync package to use.

address (default: #f)

IP address on which rsync listens for incoming connections. If unspecified, it defaults to listening on all available addresses.

port-number (default: 873)

TCP port on which rsync listens for incoming connections. If port is less than 1024 rsync needs to be started as the root user and group.

pid-file (default: "/var/run/rsyncd/rsyncd.pid")

Name of the file where rsync writes its PID.

lock-file (default: "/var/run/rsyncd/rsyncd.lock")

Name of the file where rsync writes its lock file.

log-file (default: "/var/log/rsyncd.log")

Name of the file where rsync writes its log file.

user (default: "root")

Owner of the rsync process.

group (default: "root")

Group of the rsync process.

uid (default: "rsyncd")

User name or user ID that file transfers to and from that module should take place as when the daemon was run as root.

gid (default: "rsyncd")

Group name or group ID that will be used when accessing the module.

modules (default: %default-modules)

List of “modules”—i.e., directories exported over rsync. Each element must be a rsync-module record, as described below.

Data Type: rsync-module

This is the data type for rsync “modules”. A module is a directory exported over the rsync protocol. The available fields are as follows:

name

The module name. This is the name that shows up in URLs. For example, if the module is called music, the corresponding URL will be rsync://host.example.org/music.

file-name

Name of the directory being exported.

comment (default: "")

Comment associated with the module. Client user interfaces may display it when they obtain the list of available modules.

read-only? (default: #t)

Whether or not client will be able to upload files. If this is false, the uploads will be authorized if permissions on the daemon side permit it.

chroot? (default: #t)

When this is true, the rsync daemon changes root to the module’s directory before starting file transfers with the client. This improves security, but requires rsync to run as root.

timeout (default: 300)

Idle time in seconds after which the daemon closes a connection with the client.

The (gnu services syncthing) module provides the following services:

You might want a syncthing daemon if you have files between two or more computers and want to sync them in real time, safely protected from prying eyes.

Scheme Variable: syncthing-service-type

This is the service type for the syncthing daemon, The value for this service type is a syncthing-configuration record as in this example:

See below for details about syncthing-configuration.

Data Type: syncthing-configuration

Data type representing the configuration for syncthing-service-type.

syncthing (default: syncthing)

syncthing package to use.

arguments (default: ’())

List of command-line arguments passing to syncthing binary.

logflags (default: 0)

Sum of logging flags, see Syncthing documentation logflags.

user (default: #f)

The user as which the Syncthing service is to be run. This assumes that the specified user exists.

group (default: "users")

The group as which the Syncthing service is to be run. This assumes that the specified group exists.

home (default: #f)

Common configuration and data directory. The default configuration directory is $HOME of the specified Syncthing user.

Furthermore, (gnu services ssh) provides the following services.

Scheme Procedure: lsh-service [#:host-key "/etc/lsh/host-key"] [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] [#:allow-empty-passwords? #f] [#:root-login? #f] [#:syslog-output? #t] [#:x11-forwarding? #t] [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] [#:public-key-authentication? #t] [#:initialize? #t]

Run the lshd program from lsh to listen on port port-number. host-key must designate a file containing the host key, and readable only by root.

When daemonic? is true, lshd will detach from the controlling terminal and log its output to syslogd, unless one sets syslog-output? to false. Obviously, it also makes lsh-service depend on existence of syslogd service. When pid-file? is true, lshd writes its PID to the file called pid-file.

When initialize? is true, automatically create the seed and host key upon service activation if they do not exist yet. This may take long and require interaction.

When initialize? is false, it is up to the user to initialize the randomness generator (see lsh-make-seed in LSH Manual), and to create a key pair with the private key stored in file host-key (see lshd basics in LSH Manual).

When interfaces is empty, lshd listens for connections on all the network interfaces; otherwise, interfaces must be a list of host names or addresses.

allow-empty-passwords? specifies whether to accept log-ins with empty passwords, and root-login? specifies whether to accept log-ins as root.

The other options should be self-descriptive.

Scheme Variable: openssh-service-type

This is the type for the OpenSSH secure shell daemon, sshd. Its value must be an openssh-configuration record as in this example:

(service openssh-service-type
         (openssh-configuration
           (x11-forwarding? #t)
           (permit-root-login 'prohibit-password)
           (authorized-keys
             `(("alice" ,(local-file "alice.pub"))
               ("bob" ,(local-file "bob.pub"))))))

See below for details about openssh-configuration.

This service can be extended with extra authorized keys, as in this example:

(service-extension openssh-service-type
                   (const `(("charlie"
                             ,(local-file "charlie.pub")))))
Data Type: openssh-configuration

This is the configuration record for OpenSSH’s sshd.

openssh (default openssh)

The OpenSSH package to use.

pid-file (default: "/var/run/sshd.pid")

Name of the file where sshd writes its PID.

port-number (default: 22)

TCP port on which sshd listens for incoming connections.

max-connections (default: 200)

Hard limit on the maximum number of simultaneous client connections, enforced by the inetd-style Shepherd service (see make-inetd-constructor in The GNU Shepherd Manual).

permit-root-login (default: #f)

This field determines whether and when to allow logins as root. If #f, root logins are disallowed; if #t, they are allowed. If it’s the symbol 'prohibit-password, then root logins are permitted but not with password-based authentication.

allow-empty-passwords? (default: #f)

When true, users with empty passwords may log in. When false, they may not.

password-authentication? (default: #t)

When true, users may log in with their password. When false, they have other authentication methods.

public-key-authentication? (default: #t)

When true, users may log in using public key authentication. When false, users have to use other authentication method.

Authorized public keys are stored in ~/.ssh/authorized_keys. This is used only by protocol version 2.

x11-forwarding? (default: #f)

When true, forwarding of X11 graphical client connections is enabled—in other words, ssh options -X and -Y will work.

allow-agent-forwarding? (default: #t)

Whether to allow agent forwarding.

allow-tcp-forwarding? (default: #t)

Whether to allow TCP forwarding.

gateway-ports? (default: #f)

Whether to allow gateway ports.

challenge-response-authentication? (default: #f)

Specifies whether challenge response authentication is allowed (e.g. via PAM).

use-pam? (default: #t)

Enables the Pluggable Authentication Module interface. If set to #t, this will enable PAM authentication using challenge-response-authentication? and password-authentication?, in addition to PAM account and session module processing for all authentication types.

Because PAM challenge response authentication usually serves an equivalent role to password authentication, you should disable either challenge-response-authentication? or password-authentication?.

print-last-log? (default: #t)

Specifies whether sshd should print the date and time of the last user login when a user logs in interactively.

subsystems (default: '(("sftp" "internal-sftp")))

Configures external subsystems (e.g. file transfer daemon).

This is a list of two-element lists, each of which containing the subsystem name and a command (with optional arguments) to execute upon subsystem request.

The command internal-sftp implements an in-process SFTP server. Alternatively, one can specify the sftp-server command:

(service openssh-service-type
         (openssh-configuration
          (subsystems
           `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
accepted-environment (default: '())

List of strings describing which environment variables may be exported.

Each string gets on its own line. See the AcceptEnv option in man sshd_config.

This example allows ssh-clients to export the COLORTERM variable. It is set by terminal emulators, which support colors. You can use it in your shell’s resource file to enable colors for the prompt and commands if this variable is set.

(service openssh-service-type
         (openssh-configuration
           (accepted-environment '("COLORTERM"))))
authorized-keys (default: '())

This is the list of authorized keys. Each element of the list is a user name followed by one or more file-like objects that represent SSH public keys. For example:

(openssh-configuration
  (authorized-keys
    `(("rekado" ,(local-file "rekado.pub"))
      ("chris" ,(local-file "chris.pub"))
      ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))

registers the specified public keys for user accounts rekado, chris, and root.

Additional authorized keys can be specified via service-extension.

Note that this does not interfere with the use of ~/.ssh/authorized_keys.

generate-host-keys? (default: #t)

Whether to generate host key pairs with ssh-keygen -A under /etc/ssh if there are none.

Generating key pairs takes a few seconds when enough entropy is available and is only done once. You might want to turn it off for instance in a virtual machine that does not need it because host keys are provided in some other way, and where the extra boot time is a problem.

log-level (default: 'info)

This is a symbol specifying the logging level: quiet, fatal, error, info, verbose, debug, etc. See the man page for sshd_config for the full list of level names.

extra-content (default: "")

This field can be used to append arbitrary text to the configuration file. It is especially useful for elaborate configurations that cannot be expressed otherwise. This configuration, for example, would generally disable root logins, but permit them from one specific IP address:

(openssh-configuration
  (extra-content "\
Match Address 192.168.0.1
  PermitRootLogin yes"))
Scheme Procedure: dropbear-service [config]

Run the Dropbear SSH daemon with the given config, a <dropbear-configuration> object.

For example, to specify a Dropbear service listening on port 1234, add this call to the operating system’s services field:

(dropbear-service (dropbear-configuration
                    (port-number 1234)))
Data Type: dropbear-configuration

This data type represents the configuration of a Dropbear SSH daemon.

dropbear (default: dropbear)

The Dropbear package to use.

port-number (default: 22)

The TCP port where the daemon waits for incoming connections.

syslog-output? (default: #t)

Whether to enable syslog output.

pid-file (default: "/var/run/dropbear.pid")

File name of the daemon’s PID file.

root-login? (default: #f)

Whether to allow root logins.

allow-empty-passwords? (default: #f)

Whether to allow empty passwords.

password-authentication? (default: #t)

Whether to enable password-based authentication.

Scheme Variable: autossh-service-type

This is the type for the AutoSSH program that runs a copy of ssh and monitors it, restarting it as necessary should it die or stop passing traffic. AutoSSH can be run manually from the command-line by passing arguments to the binary autossh from the package autossh, but it can also be run as a Guix service. This latter use case is documented here.

AutoSSH can be used to forward local traffic to a remote machine using an SSH tunnel, and it respects the ~/.ssh/config of the user it is run as.

For example, to specify a service running autossh as the user pino and forwarding all local connections to port 8081 to remote:8081 using an SSH tunnel, add this call to the operating system’s services field:

(service autossh-service-type
         (autossh-configuration
          (user "pino")
          (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))
Data Type: autossh-configuration

This data type represents the configuration of an AutoSSH service.

user (default "autossh")

The user as which the AutoSSH service is to be run. This assumes that the specified user exists.

poll (default 600)

Specifies the connection poll time in seconds.

first-poll (default #f)

Specifies how many seconds AutoSSH waits before the first connection test. After this first test, polling is resumed at the pace defined in poll. When set to #f, the first poll is not treated specially and will also use the connection poll specified in poll.

gate-time (default 30)

Specifies how many seconds an SSH connection must be active before it is considered successful.

log-level (default 1)

The log level, corresponding to the levels used by syslog—so 0 is the most silent while 7 is the chattiest.

max-start (default #f)

The maximum number of times SSH may be (re)started before AutoSSH exits. When set to #f, no maximum is configured and AutoSSH may restart indefinitely.

message (default "")

The message to append to the echo message sent when testing connections.

port (default "0")

The ports used for monitoring the connection. When set to "0", monitoring is disabled. When set to "n" where n is a positive integer, ports n and n+1 are used for monitoring the connection, such that port n is the base monitoring port and n+1 is the echo port. When set to "n:m" where n and m are positive integers, the ports n and m are used for monitoring the connection, such that port n is the base monitoring port and m is the echo port.

ssh-options (default '())

The list of command-line arguments to pass to ssh when it is run. Options -f and -M are reserved for AutoSSH and may cause undefined behaviour.

Scheme Variable: webssh-service-type

This is the type for the WebSSH program that runs a web SSH client. WebSSH can be run manually from the command-line by passing arguments to the binary wssh from the package webssh, but it can also be run as a Guix service. This latter use case is documented here.

For example, to specify a service running WebSSH on loopback interface on port 8888 with reject policy with a list of allowed to connection hosts, and NGINX as a reverse-proxy to this service listening for HTTPS connection, add this call to the operating system’s services field:

(service webssh-service-type
  (webssh-configuration (address "127.0.0.1")
                        (port 8888)
                        (policy 'reject)
                        (known-hosts '("localhost ecdsa-sha2-nistp256 AAAA…"
                                       "127.0.0.1 ecdsa-sha2-nistp256 AAAA…"))))

(service nginx-service-type
         (nginx-configuration
          (server-blocks
           (list
            (nginx-server-configuration
             (inherit %webssh-configuration-nginx)
             (server-name '("webssh.example.com"))
             (listen '("443 ssl"))
             (ssl-certificate (letsencrypt-certificate "webssh.example.com"))
             (ssl-certificate-key (letsencrypt-key "webssh.example.com"))
             (locations
              (cons (nginx-location-configuration
                     (uri "/.well-known")
                     (body '("root /var/www;")))
                    (nginx-server-configuration-locations %webssh-configuration-nginx))))))))
Data Type: webssh-configuration

Data type representing the configuration for webssh-service.

package (default: webssh)

webssh package to use.

user-name (default: "webssh")

User name or user ID that file transfers to and from that module should take place.

group-name (default: "webssh")

Group name or group ID that will be used when accessing the module.

address (default: #f)

IP address on which webssh listens for incoming connections.

port (default: 8888)

TCP port on which webssh listens for incoming connections.

policy (default: #f)

Connection policy. reject policy requires to specify known-hosts.

known-hosts (default: ’())

List of hosts which allowed for SSH connection from webssh.

log-file (default: "/var/log/webssh.log")

Name of the file where webssh writes its log file.

log-level (default: #f)

Logging level.

Scheme Variable: %facebook-host-aliases

This variable contains a string for use in /etc/hosts (see Host Names in The GNU C Library Reference Manual). Each line contains a entry that maps a known server name of the Facebook on-line service—e.g., www.facebook.com—to the local host—127.0.0.1 or its IPv6 equivalent, ::1.

This variable is typically used in the hosts-file field of an operating-system declaration (see /etc/hosts):

(use-modules (gnu) (guix))

(operating-system
  (host-name "mymachine")
  ;; ...
  (hosts-file
    ;; Create a /etc/hosts file with aliases for "localhost"
    ;; and "mymachine", as well as for Facebook servers.
    (plain-file "hosts"
                (string-append (local-host-aliases host-name)
                               %facebook-host-aliases))))

This mechanism can prevent programs running locally, such as Web browsers, from accessing Facebook.

The (gnu services avahi) provides the following definition.

Scheme Variable: avahi-service-type

This is the service that runs avahi-daemon, a system-wide mDNS/DNS-SD responder that allows for service discovery and “zero-configuration” host name lookups (see https://avahi.org/). Its value must be an avahi-configuration record—see below.

This service extends the name service cache daemon (nscd) so that it can resolve .local host names using nss-mdns. See Name Service Switch, for information on host name resolution.

Additionally, add the avahi package to the system profile so that commands such as avahi-browse are directly usable.

Data Type: avahi-configuration

Data type representation the configuration for Avahi.

host-name (default: #f)

If different from #f, use that as the host name to publish for this machine; otherwise, use the machine’s actual host name.

publish? (default: #t)

When true, allow host names and services to be published (broadcast) over the network.

publish-workstation? (default: #t)

When true, avahi-daemon publishes the machine’s host name and IP address via mDNS on the local network. To view the host names published on your local network, you can run:

avahi-browse _workstation._tcp
wide-area? (default: #f)

When true, DNS-SD over unicast DNS is enabled.

ipv4? (default: #t)
ipv6? (default: #t)

These fields determine whether to use IPv4/IPv6 sockets.

domains-to-browse (default: '())

This is a list of domains to browse.

Scheme Variable: openvswitch-service-type

This is the type of the Open vSwitch service, whose value should be an openvswitch-configuration object.

Data Type: openvswitch-configuration

Data type representing the configuration of Open vSwitch, a multilayer virtual switch which is designed to enable massive network automation through programmatic extension.

package (default: openvswitch)

Package object of the Open vSwitch.

Scheme Variable: pagekite-service-type

This is the service type for the PageKite service, a tunneling solution for making localhost servers publicly visible, even from behind restrictive firewalls or NAT without forwarded ports. The value for this service type is a pagekite-configuration record.

Here’s an example exposing the local HTTP and SSH daemons:

(service pagekite-service-type
         (pagekite-configuration
           (kites '("http:@kitename:localhost:80:@kitesecret"
                    "raw/22:@kitename:localhost:22:@kitesecret"))
           (extra-file "/etc/pagekite.rc")))
Data Type: pagekite-configuration

Data type representing the configuration of PageKite.

package (default: pagekite)

Package object of PageKite.

kitename (default: #f)

PageKite name for authenticating to the frontend server.

kitesecret (default: #f)

Shared secret for authenticating to the frontend server. You should probably put this inside extra-file instead.

frontend (default: #f)

Connect to the named PageKite frontend server instead of the pagekite.net service.

kites (default: '("http:@kitename:localhost:80:@kitesecret"))

List of service kites to use. Exposes HTTP on port 80 by default. The format is proto:kitename:host:port:secret.

extra-file (default: #f)

Extra configuration file to read, which you are expected to create manually. Use this to add additional options and manage shared secrets out-of-band.

Scheme Variable: yggdrasil-service-type

The service type for connecting to the Yggdrasil network, an early-stage implementation of a fully end-to-end encrypted IPv6 network.

Yggdrasil provides name-independent routing with cryptographically generated addresses. Static addressing means you can keep the same address as long as you want, even if you move to a new location, or generate a new address (by generating new keys) whenever you want. https://yggdrasil-network.github.io/2018/07/28/addressing.html

Pass it a value of yggdrasil-configuration to connect it to public peers and/or local peers.

Here is an example using public peers and a static address. The static signing and encryption keys are defined in /etc/yggdrasil-private.conf (the default value for config-file).

;; part of the operating-system declaration
(service yggdrasil-service-type
              (yggdrasil-configuration
               (autoconf? #f) ;; use only the public peers
               (json-config
               ;; choose one from
               ;; https://github.com/yggdrasil-network/public-peers
                '((peers . #("tcp://1.2.3.4:1337"))))
               ;; /etc/yggdrasil-private.conf is the default value for config-file
               ))
# sample content for /etc/yggdrasil-private.conf
{
  # Your public key. Your peers may ask you for this to put
  # into their AllowedPublicKeys configuration.
  PublicKey: 64277...

  # Your private key. DO NOT share this with anyone!
  PrivateKey: 5c750...
}
Data Type: yggdrasil-configuration

Data type representing the configuration of Yggdrasil.

package (default: yggdrasil)

Package object of Yggdrasil.

json-config (default: '())

Contents of /etc/yggdrasil.conf. Will be merged with /etc/yggdrasil-private.conf. Note that these settings are stored in the Guix store, which is readable to all users. Do not store your private keys in it. See the output of yggdrasil -genconf for a quick overview of valid keys and their default values.

autoconf? (default: #f)

Whether to use automatic mode. Enabling it makes Yggdrasil use adynamic IP and peer with IPv6 neighbors.

log-level (default: 'info)

How much detail to include in logs. Use 'debug for more detail.

log-to (default: 'stdout)

Where to send logs. By default, the service logs standard output to /var/log/yggdrasil.log. The alternative is 'syslog, which sends output to the running syslog service.

config-file (default: "/etc/yggdrasil-private.conf")

What HJSON file to load sensitive data from. This is where private keys should be stored, which are necessary to specify if you don’t want a randomized address after each restart. Use #f to disable. Options defined in this file take precedence over json-config. Use the output of yggdrasil -genconf as a starting point. To configure a static address, delete everything except these options:

  • EncryptionPublicKey
  • EncryptionPrivateKey
  • SigningPublicKey
  • SigningPrivateKey
Scheme Variable: ipfs-service-type

The service type for connecting to the IPFS network, a global, versioned, peer-to-peer file system. Pass it a ipfs-configuration to change the ports used for the gateway and API.

Here’s an example configuration, using some non-standard ports:

(service ipfs-service-type
         (ipfs-configuration
          (gateway "/ip4/127.0.0.1/tcp/8880")
          (api "/ip4/127.0.0.1/tcp/8881")))
Data Type: ipfs-configuration

Data type representing the configuration of IPFS.

package (default: go-ipfs)

Package object of IPFS.

gateway (default: "/ip4/127.0.0.1/tcp/8082")

Address of the gateway, in ‘multiaddress’ format.

api (default: "/ip4/127.0.0.1/tcp/5001")

Address of the API endpoint, in ‘multiaddress’ format.

Scheme Variable: keepalived-service-type

This is the type for the Keepalived routing software, keepalived. Its value must be an keepalived-configuration record as in this example for master machine:

(service keepalived-service-type
         (keepalived-configuration
           (config-file (local-file "keepalived-master.conf"))))

where keepalived-master.conf:

vrrp_instance my-group {
  state MASTER
  interface enp9s0
  virtual_router_id 100
  priority 100
  unicast_peer { 10.0.0.2 }
  virtual_ipaddress {
    10.0.0.4/24
  }
}

and for backup machine:

(service keepalived-service-type
         (keepalived-configuration
          (config-file (local-file "keepalived-backup.conf"))))

where keepalived-backup.conf:

vrrp_instance my-group {
  state BACKUP
  interface enp9s0
  virtual_router_id 100
  priority 99
  unicast_peer { 10.0.0.3 }
  virtual_ipaddress {
    10.0.0.4/24
  }
}

Next: Unattended Upgrades, Previous: Networking Setup, Up: Services   [Contents][Index]