Next: Unattended Upgrades, Previous: Networking Setup, Up: Services [Contents][Index]
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.
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"))))
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.
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)))
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.
ssidThe 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.
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.
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
"))))
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).
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:
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).
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.
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.
List of host names used as the default NTP servers. These are servers of the NTP Pool Project.
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.
addressThe address of the server, as a string.
optionsNTPD 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))))
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/"))))
This variable is a list of the server addresses defined in
%ntp-servers.
openntpd (default: openntpd)The openntpd package 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.
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 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 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.
nameA string, the name must correspond to an entry in /etc/services.
socket-typeOne of 'stream, 'dgram, 'raw, 'rdm or
'seqpacket.
protocolA 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.
userA 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.
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.
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.
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.
Services of this type can be extended by other services to specify
onion services (in addition to those already specified in
tor-configuration) as in this example:
(simple-service 'my-extra-onion-service tor-service-type
(list (tor-onion-service-configuration
(name "extra-onion-service")
(mapping '((80 . "127.0.0.1:8080"))))))
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 <tor-onion-service-configuration> records to use.
For any onion service you include in this list, appropriate
configuration to enable the onion service will be automatically added to
the default configuration file.
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.
transport-plugins (default: '())The list of <tor-transport-plugin> records to use.
For any transport plugin you include in this list, appropriate
configuration line to enable transport plugin will be automatically
added to the default configuration file.
Data Type representing a Tor Onion Service configuration.
See the Tor
project’s documentation for more information.
Available tor-onion-service-configuration fields are:
name (type: string)Name for this Onion Service. This creates a
/var/lib/tor/hidden-services/name directory, where the
hostname file contains the ‘.onion’ host name for this Onion
Service.
mapping (type: alist)Association list of port to address mappings. The following example:
'((22 . "127.0.0.1:22") (80 . "127.0.0.1:8080"))
maps ports 22 and 80 of the Onion Service to the local ports 22 and 8080.
Data type representing a Tor pluggable transport plugin in
tor-configuration. Plugguble transports are programs
that disguise Tor traffic, which can be useful in case Tor is
censored. See the the Tor project’s
documentation and
specification for more information.
Each transport plugin corresponds either to
ClientTransportPlugin ... or to
ServerTransportPlugin ... line in the default
configuration file, see man tor.
Available tor-transport-plugin fields are:
role (default: 'client)This must be either 'client or 'server. Otherwise,
an error is raised. Set the 'server value if you want to
run a bridge to help censored users connect to the Tor network, see
the Tor project’s brige guide. Set the 'client value
if you want to connect to somebody else’s bridge, see
the Tor project’s
“Get Bridges” page. In both cases the required
additional configuration should be provided via
#:config-file option of tor-configuration.
protocol (default: "obfs4")A string that specifies a pluggable transport protocol.
programThis must be a “file-like” object or a string pointing to the pluggable transport plugin executable. This option allows the Tor daemon run inside the container to access the executable and all the references (e.g. package dependencies) attached to it.
Suppose you would like Tor daemon to use obfs4 type obfuscation and
to connect to Tor network via obfs4 bridge (a nonpublic Tor relay with
support for obfs4 type obfuscation). Then you may go to
https://bridges.torproject.org/
and get there a couple of bridge lines (each starts with obfs4 ...)
and use these lines in tor-service-type configuration as follows:
(service tor-service-type
(tor-configuration
(config-file (plain-file "torrc"
"\
UseBridges 1
Bridge obfs4 ...
Bridge obfs4 ..."))
(transport-plugins
(list (tor-transport-plugin
(program
(file-append
go-gitlab-torproject-org-tpo-anti-censorship-pluggable-transports-lyrebird
"/bin/lyrebird")))))))
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.
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 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.
This is the data type for rsync “modules”. A module is a directory exported over the rsync protocol. The available fields are as follows:
nameThe 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-nameName 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.
This is the service type for the syncthing daemon, The value for this service type is a
syncthing-configuration record as in this example:
(service syncthing-service-type
(syncthing-configuration (user "alice")))
Note: This service is also available for Guix Home, where it runs directly with your user privileges (see
home-syncthing-service-type).
See below for details about 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.
Type of the service that runs the GNU lsh secure shell (SSH)
daemon, lshd. The value for this service is a
<lsh-configuration> object.
Data type representing the configuration of lshd.
lsh (default: lsh) (type: file-like)The package object of the GNU lsh secure shell (SSH) daemon.
daemonic? (default: #t) (type: boolean)Whether to detach from the controlling terminal.
host-key (default: "/etc/lsh/host-key") (type: string)File containing the host key. This file must be readable by root only.
interfaces (default: '()) (type: list)List of host names or addresses that lshd will listen on.
If empty, lshd listens for connections on all the network
interfaces.
port-number (default: 22) (type: integer)Port to listen on.
allow-empty-passwords? (default: #f) (type: boolean)Whether to accept log-ins with empty passwords.
root-login? (default: #f) (type: boolean)Whether to accept log-ins as root.
syslog-output? (default: #t) (type: boolean)Whether to log lshd standard output to syslogd.
This will make the service depend on the existence of a syslogd service.
pid-file? (default: #f) (type: boolean)When #t, lshd writes its PID to the file specified in
pid-file.
pid-file (default: "/var/run/lshd.pid") (type: string)File that lshd will write its PID to.
x11-forwarding? (default: #t) (type: boolean)Whether to enable X11 forwarding.
tcp/ip-forwarding? (default: #t) (type: boolean)Whether to enable TCP/IP forwarding.
password-authentication? (default: #t) (type: boolean)Whether to accept log-ins using password authentication.
public-key-authentication? (default: #t) (type: boolean)Whether to accept log-ins using public key authentication.
initialize? (default: #t) (type: boolean)When #f, 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).
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")))))
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"))))
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"))
Type of the service that runs the
Dropbear SSH daemon,
whose value is a <dropbear-configuration> object.
For example, to specify a Dropbear service listening on port 1234:
(service dropbear-service-type (dropbear-configuration
(port-number 1234)))
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.
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"))))
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.
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 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.
This service type adds a list of known Facebook hosts to the
/etc/hosts file.
(see Host Names in The GNU C Library Reference Manual)
Each line contains an entry that maps a known server name of the Facebook
on-line service—e.g., www.facebook.com—to unroutable IPv4 and
IPv6 addresses.
This mechanism can prevent programs running locally, such as Web browsers, from accessing Facebook.
The (gnu services avahi) provides the following definition.
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 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.
This is the type of the Open vSwitch
service, whose value should be an openvswitch-configuration
object.
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.
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 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.
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 private key. DO NOT share this with anyone!
PrivateKey: 5c750...
}
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 a dynamic 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 PrivateKey option.
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 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.
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]