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

8.8.4 Networking Services

The (gnu services networking) module provides services to configure the network interface.

Scheme Variable: dhcp-client-service-type

This is the type of services that run dhcp, a Dynamic Host Configuration Protocol (DHCP) client, on all the non-loopback network interfaces. Its value is the DHCP client package to use, isc-dhcp by default.

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

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: static-networking-service-type

This is the type for statically-configured network interfaces.

Scheme Procedure: static-networking-service interface ip [#:netmask #f] [#:gateway #f] [#:name-servers '()] [#:requirement '(udev)]

Return a service that starts interface with address ip. If netmask is true, use it as the network mask. If gateway is true, it must be a string specifying the default network gateway. requirement can be used to declare a dependency on another service before configuring the interface.

This procedure can be called several times, one for each network interface of interest. Behind the scenes what it does is extend static-networking-service-type with additional network interfaces to handle.

For example:

(static-networking-service "eno1" ""
                           #:gateway ""
                           #:name-servers '(""))
Scheme Procedure: wicd-service [#:wicd wicd]

Return a service that runs Wicd, a network management daemon that aims to simplify wired and wireless networking.

This service adds the wicd package to the global profile, providing several commands to interact with the daemon and configure networking: wicd-client, a graphical user interface, and the wicd-cli and wicd-curses user interfaces.

Scheme Variable: modem-manager-service-type

This is the service type for the ModemManager service. The value for this service type is a modem-manager-configuration record.

This service is part of %desktop-services (see Desktop Services).

Data Type: modem-manager-configuration

Data type representing the configuration of ModemManager.

modem-manager (default: modem-manager)

The ModemManager package to use.

Scheme Variable: usb-modeswitch-service-type

This is the service type for the USB_ModeSwitch service. The value for this service type is a usb-modeswitch-configuration record.

When plugged in, some USB modems (and other USB devices) initially present themselves as a read-only storage medium and not as a modem. They need to be modeswitched before they are usable. The USB_ModeSwitch service type installs udev rules to automatically modeswitch these devices when they are plugged in.

This service is part of %desktop-services (see Desktop Services).

Data Type: usb-modeswitch-configuration

Data type representing the configuration of USB_ModeSwitch.

usb-modeswitch (default: usb-modeswitch)

The USB_ModeSwitch package providing the binaries for modeswitching.

usb-modeswitch-data (default: usb-modeswitch-data)

The package providing the device data and udev rules file used by USB_ModeSwitch.

config-file (default: #~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf"))

Which config file to use for the USB_ModeSwitch dispatcher. By default the config file shipped with USB_ModeSwitch is used which disables logging to /var/log among other default settings. If set to #f, no config file is used.

Scheme Variable: network-manager-service-type

This is the service type for the NetworkManager service. The value for this service type is a network-manager-configuration record.

This service is part of %desktop-services (see Desktop Services).

Data Type: network-manager-configuration

Data type representing the configuration of NetworkManager.

network-manager (default: network-manager)

The NetworkManager package to use.

dns (default: "default")

Processing mode for DNS, which affects how NetworkManager uses the resolv.conf configuration file.


NetworkManager will update resolv.conf to reflect the nameservers provided by currently active connections.


NetworkManager will run dnsmasq as a local caching nameserver, using a conditional forwarding configuration if you are connected to a VPN, and then update resolv.conf to point to the local nameserver.

With this setting, you can share your network connection. For example when you want to share your network connection to another laptop via an Ethernet cable, you can open nm-connection-editor and configure the Wired connection’s method for IPv4 and IPv6 to be “Shared to other computers” and reestablish the connection (or reboot).

You can also set up a host-to-guest connection to QEMU VMs (see Installing Guix in a VM). With a host-to-guest connection, you can e.g. access a Web server running on the VM (see Web Services) from a Web browser on your host system, or connect to the VM via SSH (see openssh-service-type). To set up a host-to-guest connection, run this command once:

nmcli connection add type tun \
 connection.interface-name tap0 \
 tun.mode tap tun.owner $(id -u) \
 ipv4.method shared \

Then each time you launch your QEMU VM (see Running Guix in a VM), pass -nic tap,ifname=tap0,script=no,downscript=no to qemu-system-....


NetworkManager will not modify resolv.conf.

vpn-plugins (default: '())

This is the list of available plugins for virtual private networks (VPNs). An example of this is the network-manager-openvpn package, which allows NetworkManager to manage VPNs via OpenVPN.

Scheme Variable: connman-service-type

This is the service type to run Connman, a network connection manager.

Its value must be an connman-configuration record as in this example:

(service connman-service-type
           (disable-vpn? #t)))

See below for details about connman-configuration.

Data Type: connman-configuration

Data Type representing the configuration of connman.

connman (default: connman)

The connman package to use.

disable-vpn? (default: #f)

When true, disable connman’s vpn plugin.

Scheme Variable: wpa-supplicant-service-type

This is the service type to run WPA supplicant, an authentication daemon required to authenticate against encrypted WiFi or ethernet networks.

Data Type: wpa-supplicant-configuration

Data type representing the configuration of WPA Supplicant.

It takes the following parameters:

wpa-supplicant (default: wpa-supplicant)

The WPA Supplicant package to use.

dbus? (default: #t)

Whether to listen for requests on D-Bus.

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

Where to store the PID file.

interface (default: #f)

If this is set, it must specify the name of a network interface that WPA supplicant will control.

config-file (default: #f)

Optional configuration file to use.

extra-options (default: '())

List of additional command-line arguments to pass to the daemon.

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
          (ipv4-rules (plain-file "iptables.rules" "*filter
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp-port-unreachable
          (ipv6-rules (plain-file "ip6tables.rules" "*filter
-A INPUT -p tcp --dport 22 -j ACCEPT
-A INPUT -j REJECT --reject-with icmp6-port-unreachable
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: 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 (host names) with which ntpd will be synchronized.

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

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.

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.

  (listen-on '("" "::1"))
  (sensor '("udcf0 correction 70000"))
  (constraint-from '(""))
  (constraints-from '(""))
  (allow-large-adjustment? #t)))

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

The openntpd executable to use.

listen-on (default: '("" "::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: %ntp-servers)

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

servers (default: '())

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.

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

Determines if ntpd is allowed to make an initial adjustment of more than 180 seconds.

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:

  (entries (list
             (name "echo")
             (socket-type 'stream)
             (protocol "tcp")
             (wait? #f)
             (user "root"))
             (node "")
             (name "smtp")
             (socket-type 'stream)
             (protocol "tcp")
             (wait? #f)
             (user "root")
             (program (file-append openssh "/bin/ssh"))
              '("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.


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


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


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.


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

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

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

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:

(service rsync-service-type)

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.

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

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.

use-chroot? (default: #t)

Whether to use chroot for rsync shared directory.

share-path (default: /srv/rsync)

Location of the rsync shared directory.

share-comment (default: "Rsync share")

Comment of the rsync shared directory.

read-only? (default: #f)

Read-write permissions to shared directory.

timeout (default: 300)

I/O timeout in seconds.

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.

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
           (x11-forwarding? #t)
           (permit-root-login 'without-password)
             `(("alice" ,(local-file ""))
               ("bob" ,(local-file ""))))))

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 "")))))
Data Type: openssh-configuration

This is the configuration record for OpenSSH’s sshd.

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

Name of the file where sshd writes its PID.

port-number (default: 22)

TCP port on which sshd listens for incoming connections.

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 'without-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. Alternately, one can specify the sftp-server command:

(service openssh-service-type
           `(("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 ressource file to enable colors for the prompt and commands if this variable is set.

(service openssh-service-type
           (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:

    `(("rekado" ,(local-file ""))
      ("chris" ,(local-file ""))
      ("root" ,(local-file "") ,(local-file "")))))

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.

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:

  (extra-content "\
Match Address
  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/")

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: %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.,—to the local host— 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))

  (host-name "mymachine")
  ;; ...
    ;; 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)

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 Its value must be a zero-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.

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