Networking Setup (GNU Guix Reference Manual)

12.9.4 Networking Setup

The (gnu services networking) module provides services to configure network interfaces and set up networking on your machine. Those services provide different ways for you to set up your machine: by declaring a static network configuration, by running a Dynamic Host Configuration Protocol (DHCP) client, or by running daemons such as NetworkManager and Connman that automate the whole process, automatically adapt to connectivity changes, and provide a high-level user interface.

On a laptop, NetworkManager and Connman are by far the most convenient options, which is why the default desktop services include NetworkManager (see %desktop-services). For a server, or for a virtual machine or a container, static network configuration or a simple DHCP client are often more appropriate.

This section describes the various network setup services available, starting with static network configuration.

Scheme Variable: static-networking-service-type

This is the type for statically-configured network interfaces. Its value must be a list of static-networking records. Each of them declares a set of addresses, routes, and links, as shown below.

Here is the simplest configuration, with only one network interface controller (NIC) and only IPv4 connectivity:

;; Static networking for one NIC, IPv4-only.
(service static-networking-service-type
         (list (static-networking
                (addresses
                 (list (network-address
                        (device "eno1")
                        (value "10.0.2.15/24"))))
                (routes
                 (list (network-route
                        (destination "default")
                        (gateway "10.0.2.2"))))
                (name-servers '("10.0.2.3")))))

The snippet above can be added to the services field of your operating system configuration (see Using the Configuration System). It will configure your machine to have 10.0.2.15 as its IP address, with a 24-bit netmask for the local network—meaning that any 10.0.2.x address is on the local area network (LAN). Traffic to addresses outside the local network is routed via 10.0.2.2. Host names are resolved by sending domain name system (DNS) queries to 10.0.2.3.

Data Type: static-networking

This is the data type representing a static network configuration.

As an example, here is how you would declare the configuration of a machine with a single network interface controller (NIC) available as eno1, and with one IPv4 and one IPv6 address:

;; Network configuration for one NIC, IPv4 + IPv6.
(static-networking
 (addresses (list (network-address
                   (device "eno1")
                   (value "10.0.2.15/24"))
                  (network-address
                   (device "eno1")
                   (value "2001:123:4567:101::1/64"))))
 (routes (list (network-route
                (destination "default")
                (gateway "10.0.2.2"))
               (network-route
                (destination "default")
                (gateway "2020:321:4567:42::1"))))
 (name-servers '("10.0.2.3")))

If you are familiar with the ip command of the iproute2 package found on Linux-based systems, the declaration above is equivalent to typing:

ip address add 10.0.2.15/24 dev eno1
ip address add 2001:123:4567:101::1/64 dev eno1
ip route add default via inet 10.0.2.2
ip route add default via inet6 2020:321:4567:42::1

Run man 8 ip for more info. Venerable GNU/Linux users will certainly know how to do it with ifconfig and route, but we’ll spare you that.

The available fields of this data type are as follows:

addresses
links (default: '())
routes (default: '()): The list of network-address, network-link, and network-route records for this network (see below).
name-servers (default: '()): The list of IP addresses (strings) of domain name servers. These IP addresses go to /etc/resolv.conf.
provision (default: '(networking)): If true, this should be a list of symbols for the Shepherd service corresponding to this network configuration.
requirement (default '()): The list of Shepherd services depended on.

Data Type: network-address

This is the data type representing the IP address of a network interface.

device

The name of the network interface for this address—e.g., "eno1".

value

The actual IP address and network mask, in CIDR (Classless Inter-Domain Routing) notation, as a string.

For example, "10.0.2.15/24" denotes IPv4 address 10.0.2.15 on a 24-bit sub-network—all 10.0.2.x addresses are on the same local network.

ipv6?

Whether value denotes an IPv6 address. By default this is automatically determined.

Data Type: network-route

This is the data type representing a network route.

destination: The route destination (a string), either an IP address and network mask or "default" to denote the default route.
source (default: #f): The route source.
device (default: #f): The device used for this route—e.g., "eno2".
ipv6? (default: auto): Whether this is an IPv6 route. By default this is automatically determined based on destination or gateway.
gateway (default: #f): IP address (a string) through which traffic is routed.

Data Type: network-link

Data type for a network link (see Link in Guile-Netlink Manual).

name: The name of the link—e.g., "v0p0".
type: A symbol denoting the type of the link—e.g., 'veth.
arguments: List of arguments for this type of link.

Scheme Variable: %loopback-static-networking: This is the static-networking record representing the “loopback device”, lo, for IP addresses 127.0.0.1 and ::1, and providing the loopback Shepherd service.

Scheme Variable: %qemu-static-networking: This is the static-networking record representing network setup when using QEMU’s user-mode network stack on eth0 (see Using the user mode network stack in QEMU Documentation).

Scheme Variable: dhcp-client-service-type: This is the type of services that run dhcp, a Dynamic Host Configuration Protocol (DHCP) client.

Data Type: dhcp-client-configuration

Data type representing the configuration of the DHCP client service.

package (default: isc-dhcp)

DHCP client package to use.

interfaces (default: 'all)

Either 'all or the list of interface names that the DHCP client should listen on—e.g., '("eno1").

When set to 'all, the DHCP client listens on all the available non-loopback interfaces that can be activated. Otherwise the DHCP client listens only on the specified interfaces.

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.

‘default’

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

‘dnsmasq’

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 Virtual Machine). 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 \
 ipv4.addresses 172.28.112.1/24

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

‘none’

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
         (connman-configuration
           (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.
requirement (default: '(user-processes loopback syslogd): List of services that should be started before WPA Supplicant starts.
dbus? (default: #t): Whether to listen for requests on D-Bus.
pid-file (default: "/var/run/wpa_supplicant.pid"): 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.

Some networking devices such as modems require special care, and this is what the services below focus on.

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.