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


6.2.7.4 Networking Services

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

Scheme Procedure: dhcp-client-service [#:dhcp isc-dhcp]

Return a service that runs dhcp, a Dynamic Host Configuration Protocol (DHCP) client, on all the non-loopback network interfaces.

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

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: 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 "split DNS" configuration if you are connected to a VPN, and then update resolv.conf to point to the local nameserver.

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, enable 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. It is configured to listen for requests on D-Bus.

The value of this service is the wpa-supplicant package to use. Thus, it can be instantiated like this:

(use-modules (gnu services networking))

(service wpa-supplicant-service-type)
Scheme Procedure: ntp-service [#:ntp ntp] [#:servers %ntp-servers] [#:allow-large-adjustment? #f]

Return a service that runs the daemon from ntp, the Network Time Protocol package. The daemon will keep the system clock synchronized with that of servers. allow-large-adjustment? determines whether ntpd is allowed to make an initial adjustment of more than 1,000 seconds.

Scheme Variable: %ntp-servers

List of host names used as the default NTP servers.

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/"))
  (allow-large-adjustment? #t)))

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 acutally exists and ignore non-existant 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:

(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 Procedure: tor-service [config-file] [#:tor tor]

Return a service to run the Tor anonymous networking daemon.

The daemon runs as the tor unprivileged user. It is passed config-file, a file-like object, with an additional User tor line and lines for hidden services added via tor-hidden-service. Run man tor for information about the configuration file.

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 type for the rsync rsync daemon, 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/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.

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
         (openssh-configuration
           (x11-forwarding? #t)
           (permit-root-login 'without-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.

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.

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.

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

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: %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 Procedure: avahi-service [#:avahi avahi] [#:host-name #f] [#:publish? #t] [#:ipv4? #t] [#:ipv6? #t] [#:wide-area? #f] [#:domains-to-browse '()] [#:debug? #f]

Return a service that runs avahi-daemon, a system-wide mDNS/DNS-SD responder that allows for service discovery and "zero-configuration" host name lookups (see http://avahi.org/), and extends the name service cache daemon (nscd) so that it can resolve .local host names using nss-mdns. Additionally, add the avahi package to the system profile so that commands such as avahi-browse are directly usable.

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

When publish? is true, publishing of host names and services is allowed; in particular, avahi-daemon will publish the machine’s host name and IP address via mDNS on the local network.

When wide-area? is true, DNS-SD over unicast DNS is enabled.

Boolean values ipv4? and ipv6? determine whether to use IPv4/IPv6 sockets.

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]