diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/build.scm | 1 | ||||
| -rw-r--r-- | doc/guix.texi | 456 |
2 files changed, 322 insertions, 135 deletions
diff --git a/doc/build.scm b/doc/build.scm index bf32f85436..eebb493a2e 100644 --- a/doc/build.scm +++ b/doc/build.scm @@ -449,6 +449,7 @@ its <pre class=\"lisp\"> blocks (as produced by 'makeinfo --html')." ("rarr" "→") ("hellip" "…") ("rsquo" "’") + ("nbsp" " ") (e (pk 'unknown-entity e) (primitive-exit 2)))) (define (concatenate-snippets pieces) diff --git a/doc/guix.texi b/doc/guix.texi index 58625666c1..49dd80e9dc 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -346,7 +346,8 @@ Services * Base Services:: Essential system services. * Scheduled Job Execution:: The mcron service. * Log Rotation:: The rottlog service. -* Networking Services:: Network setup, SSH daemon, etc. +* Networking Setup:: Setting up network interfaces. +* Networking Services:: Firewall, SSH daemon, etc. * Unattended Upgrades:: Automated system upgrades. * X Window:: Graphical display. * Printing Services:: Local and remote printer support. @@ -15816,7 +15817,8 @@ declaration. * Base Services:: Essential system services. * Scheduled Job Execution:: The mcron service. * Log Rotation:: The rottlog service. -* Networking Services:: Network setup, SSH daemon, etc. +* Networking Setup:: Setting up network interfaces. +* Networking Services:: Firewall, SSH daemon, etc. * Unattended Upgrades:: Automated system upgrades. * X Window:: Graphical display. * Printing Services:: Local and remote printer support. @@ -17038,167 +17040,210 @@ The list of syslog-controlled files to be rotated. By default it is: "/var/log/maillog")}. @end defvr -@node Networking Services -@subsection Networking Services +@node Networking Setup +@subsection Networking Setup -The @code{(gnu services networking)} module provides services to configure -the network interface. +The @code{(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. -@cindex DHCP, networking service -@defvr {Scheme Variable} dhcp-client-service-type -This is the type of services that run @var{dhcp}, a Dynamic Host Configuration -Protocol (DHCP) client, on all the non-loopback network interfaces. Its value -is the DHCP client package to use, @code{isc-dhcp} by default. -@end defvr +On a laptop, NetworkManager and Connman are by far the most convenient +options, which is why the default desktop services include +NetworkManager (@pxref{Desktop Services, @code{%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. -@deffn {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 @code{<dhcpd-configuration>}. -For example: - -@lisp -(service dhcpd-service-type - (dhcpd-configuration - (config-file (local-file "my-dhcpd.conf")) - (interfaces '("enp0s25")))) -@end lisp -@end deffn - -@deftp {Data Type} dhcpd-configuration -@table @asis -@item @code{package} (default: @code{isc-dhcp}) -The package that provides the DHCP daemon. This package is expected to -provide the daemon at @file{sbin/dhcpd} relative to its output -directory. The default package is the -@uref{https://www.isc.org/products/DHCP, ISC's DHCP server}. -@item @code{config-file} (default: @code{#f}) -The configuration file to use. This is required. It will be passed to -@code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' -object (@pxref{G-Expressions, file-like objects}). See @code{man -dhcpd.conf} for details on the configuration file syntax. -@item @code{version} (default: @code{"4"}) -The DHCP version to use. The ISC DHCP server supports the values ``4'', -``6'', and ``4o6''. These correspond to the @code{dhcpd} program -options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for -details. -@item @code{run-directory} (default: @code{"/run/dhcpd"}) -The run directory to use. At service activation time, this directory -will be created if it does not exist. -@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"}) -The PID file to use. This corresponds to the @code{-pf} option of -@code{dhcpd}. See @code{man dhcpd} for details. -@item @code{interfaces} (default: @code{'()}) -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 @code{dhcpd} invocation when starting -the daemon. It may not be necessary to explicitly specify any -interfaces here; see @code{man dhcpd} for details. -@end table -@end deftp +This section describes the various network setup services available, +starting with static network configuration. @defvr {Scheme Variable} static-networking-service-type -This is the type for statically-configured network interfaces. -@c TODO Document <static-networking> data structures. +This is the type for statically-configured network interfaces. Its +value must be a list of @code{static-networking} records. Each of them +declares a set of @dfn{addresses}, @dfn{routes}, and @dfn{links}, as +show below. + +@cindex network interface controller (NIC) +@cindex NIC, networking interface controller +Here is the simplest configuration, with only one network interface +controller (NIC) and only IPv4 connectivity: + +@example +;; 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"))))) +@end example + +The snippet above can be added to the @code{services} field of your +operating system configuration (@pxref{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.@var{x} +address is on the local area network (LAN). Traffic to addresses +outside the local network is routed @i{via} 10.0.2.2. Host names are +resolved by sending domain name system (DNS) queries to 10.0.2.3. @end defvr -@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @ - [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @ - [#:requirement @code{'(udev)}] -Return a service that starts @var{interface} with address @var{ip}. If -@var{netmask} is true, use it as the network mask. If @var{gateway} is true, -it must be a string specifying the default network gateway. @var{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 -@code{static-networking-service-type} with additional network interfaces -to handle. +@deftp {Data Type} static-networking +This is the data type representing a static network configuration. -For example: +As an example, here is how you would declare the configuration of a +machine with a single network interface controller (NIC) available as +@code{eno1}, and with one IPv4 and one IPv6 address: @lisp -(static-networking-service "eno1" "192.168.1.82" - #:gateway "192.168.1.2" - #:name-servers '("192.168.1.2")) +;; 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"))) @end lisp -@end deffn -@cindex wicd -@cindex wireless -@cindex WiFi -@cindex network management -@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] -Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network -management daemon that aims to simplify wired and wireless networking. +If you are familiar with the @command{ip} command of the +@uref{https://wiki.linuxfoundation.org/networking/iproute2, +@code{iproute2} package} found on Linux-based systems, the declaration +above is equivalent to typing: -This service adds the @var{wicd} package to the global profile, providing -several commands to interact with the daemon and configure networking: -@command{wicd-client}, a graphical user interface, and the @command{wicd-cli} -and @command{wicd-curses} user interfaces. -@end deffn +@example +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 +@end example -@cindex ModemManager +Run @command{man 8 ip} for more info. Venerable GNU/Linux users will +certainly know how to do it with @command{ifconfig} and @command{route}, +but we'll spare you that. -@defvr {Scheme Variable} modem-manager-service-type -This is the service type for the -@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager} -service. The value for this service type is a -@code{modem-manager-configuration} record. +The available fields of this data type are as follows: -This service is part of @code{%desktop-services} (@pxref{Desktop -Services}). -@end defvr +@table @asis +@item @code{addresses} +@itemx @code{links} (default: @code{'()}) +@itemx @code{routes} (default: @code{'()}) +The list of @code{network-address}, @code{network-link}, and +@code{network-route} records for this network (see below). -@deftp {Data Type} modem-manager-configuration -Data type representing the configuration of ModemManager. +@item @code{name-servers} (default: @code{'()}) +The list of IP addresses (strings) of domain name servers. These IP +addresses go to @file{/etc/resolv.conf}. -@table @asis -@item @code{modem-manager} (default: @code{modem-manager}) -The ModemManager package to use. +@item @code{provision} (default: @code{'(networking)}) +If true, this should be a list of symbols for the Shepherd service +corresponding to this network configuration. +@item @code{requirement} (default @code{'()}) +The list of Shepherd services depended on. @end table @end deftp -@cindex USB_ModeSwitch -@cindex Modeswitching +@deftp {Data Type} network-address +This is the data type representing the IP address of a network +interface. -@defvr {Scheme Variable} usb-modeswitch-service-type -This is the service type for the -@uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} -service. The value for this service type is -a @code{usb-modeswitch-configuration} record. +@table @code +@item device +The name of the network interface for this address---e.g., +@code{"eno1"}. -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 -@dfn{modeswitched} before they are usable. The USB_ModeSwitch service type -installs udev rules to automatically modeswitch these devices when they are -plugged in. +@item value +The actual IP address and network mask, in +@uref{https://en.wikipedia.org/wiki/CIDR#CIDR_notation, @acronym{CIDR, +Classless Inter-Domain Routing} notation}, as a string. -This service is part of @code{%desktop-services} (@pxref{Desktop -Services}). -@end defvr +For example, @code{"10.0.2.15/24"} denotes IPv4 address 10.0.2.15 on a +24-bit sub-network---all 10.0.2.@var{x} addresses are on the same local +network. -@deftp {Data Type} usb-modeswitch-configuration -Data type representing the configuration of USB_ModeSwitch. +@item ipv6? +Whether @code{value} denotes an IPv6 address. By default this is +automatically determined. +@end table +@end deftp + +@deftp {Data Type} network-route +This is the data type representing a network route. @table @asis -@item @code{usb-modeswitch} (default: @code{usb-modeswitch}) -The USB_ModeSwitch package providing the binaries for modeswitching. +@item @code{destination} +The route destination (a string), either an IP address or +@code{"default"} to denote the default route. -@item @code{usb-modeswitch-data} (default: @code{usb-modeswitch-data}) -The package providing the device data and udev rules file used by -USB_ModeSwitch. +@item @code{source} (default: @code{#f}) +The route source. -@item @code{config-file} (default: @code{#~(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 -@file{/var/log} among other default settings. If set to @code{#f}, no config -file is used. +@item @code{device} (default: @code{#f}) +The device used for this route---e.g., @code{"eno2"}. + +@item @code{ipv6?} (default: auto) +Whether this is an IPv6 route. By default this is automatically +determined based on @code{destination} or @code{gateway}. + +@item @code{gateway} (default: @code{#f}) +IP address (a string) through which traffic is routed. +@end table +@end deftp + +@deftp {Data Type} network-link +Data type for a network link (@pxref{Link,,, guile-netlink, +Guile-Netlink Manual}). + +@table @code +@item name +The name of the link---e.g., @code{"v0p0"}. + +@item type +A symbol denoting the type of the link---e.g., @code{'veth}. +@item arguments +List of arguments for this type of link. @end table @end deftp +@cindex loopback device +@defvr {Scheme Variable} %loopback-static-networking +This is the @code{static-networking} record representing the ``loopback +device'', @code{lo}, for IP addresses 127.0.0.1 and ::1, and providing +the @code{loopback} Shepherd service. +@end defvr + +@cindex networking, with QEMU +@cindex QEMU, networking +@defvr {Scheme Variable} %qemu-static-networking +This is the @code{static-networking} record representing network setup +when using QEMU's user-mode network stack on @code{eth0} (@pxref{Using +the user mode network stack,,, QEMU, QEMU Documentation}). +@end defvr + +@cindex DHCP, networking service +@defvr {Scheme Variable} dhcp-client-service-type +This is the type of services that run @var{dhcp}, a Dynamic Host Configuration +Protocol (DHCP) client, on all the non-loopback network interfaces. Its value +is the DHCP client package to use, @code{isc-dhcp} by default. +@end defvr + @cindex NetworkManager @defvr {Scheme Variable} network-manager-service-type @@ -17335,6 +17380,139 @@ List of additional command-line arguments to pass to the daemon. @end table @end deftp +@cindex wicd +@cindex wireless +@cindex WiFi +@cindex network management +@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] +Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network +management daemon that aims to simplify wired and wireless networking. + +This service adds the @var{wicd} package to the global profile, providing +several commands to interact with the daemon and configure networking: +@command{wicd-client}, a graphical user interface, and the @command{wicd-cli} +and @command{wicd-curses} user interfaces. +@end deffn + +@cindex ModemManager +Some networking devices such as modems require special care, and this is +what the services below focus on. + +@defvr {Scheme Variable} modem-manager-service-type +This is the service type for the +@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager} +service. The value for this service type is a +@code{modem-manager-configuration} record. + +This service is part of @code{%desktop-services} (@pxref{Desktop +Services}). +@end defvr + +@deftp {Data Type} modem-manager-configuration +Data type representing the configuration of ModemManager. + +@table @asis +@item @code{modem-manager} (default: @code{modem-manager}) +The ModemManager package to use. + +@end table +@end deftp + +@cindex USB_ModeSwitch +@cindex Modeswitching + +@defvr {Scheme Variable} usb-modeswitch-service-type +This is the service type for the +@uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} +service. The value for this service type is +a @code{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 +@dfn{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 @code{%desktop-services} (@pxref{Desktop +Services}). +@end defvr + +@deftp {Data Type} usb-modeswitch-configuration +Data type representing the configuration of USB_ModeSwitch. + +@table @asis +@item @code{usb-modeswitch} (default: @code{usb-modeswitch}) +The USB_ModeSwitch package providing the binaries for modeswitching. + +@item @code{usb-modeswitch-data} (default: @code{usb-modeswitch-data}) +The package providing the device data and udev rules file used by +USB_ModeSwitch. + +@item @code{config-file} (default: @code{#~(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 +@file{/var/log} among other default settings. If set to @code{#f}, no config +file is used. + +@end table +@end deftp + + +@node Networking Services +@subsection Networking Services + +The @code{(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 @command{hostapd}, running the +@command{inetd} ``superdaemon'', and more. This section describes +those. + +@deffn {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 @code{<dhcpd-configuration>}. +For example: + +@lisp +(service dhcpd-service-type + (dhcpd-configuration + (config-file (local-file "my-dhcpd.conf")) + (interfaces '("enp0s25")))) +@end lisp +@end deffn + +@deftp {Data Type} dhcpd-configuration +@table @asis +@item @code{package} (default: @code{isc-dhcp}) +The package that provides the DHCP daemon. This package is expected to +provide the daemon at @file{sbin/dhcpd} relative to its output +directory. The default package is the +@uref{https://www.isc.org/products/DHCP, ISC's DHCP server}. +@item @code{config-file} (default: @code{#f}) +The configuration file to use. This is required. It will be passed to +@code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' +object (@pxref{G-Expressions, file-like objects}). See @code{man +dhcpd.conf} for details on the configuration file syntax. +@item @code{version} (default: @code{"4"}) +The DHCP version to use. The ISC DHCP server supports the values ``4'', +``6'', and ``4o6''. These correspond to the @code{dhcpd} program +options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for +details. +@item @code{run-directory} (default: @code{"/run/dhcpd"}) +The run directory to use. At service activation time, this directory +will be created if it does not exist. +@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"}) +The PID file to use. This corresponds to the @code{-pf} option of +@code{dhcpd}. See @code{man dhcpd} for details. +@item @code{interfaces} (default: @code{'()}) +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 @code{dhcpd} invocation when starting +the daemon. It may not be necessary to explicitly specify any +interfaces here; see @code{man dhcpd} for details. +@end table +@end deftp + @cindex hostapd service, for Wi-Fi access points @cindex Wi-Fi access points, hostapd service @defvr {Scheme Variable} hostapd-service-type @@ -17397,6 +17575,7 @@ network that can be seen on @code{wlan0}, by default. The service's value is a @code{hostapd-configuration} record. @end defvr + @cindex iptables @defvr {Scheme Variable} iptables-service-type This is the service type to set up an iptables configuration. iptables is a @@ -20530,7 +20709,7 @@ a system which relies on @code{%desktop-services}, you may use (operating-system @dots{} - (services %my-desktop-services) + (services %my-desktop-services)) @end lisp @end defvr @@ -30642,11 +30821,18 @@ cluster node that supports multiple storage backends, and installs the "ganeti-instance-guix" "ganeti-instance-debootstrap")) %base-packages)) (services - (append (list (static-networking-service "eth0" "192.168.1.201" - #:netmask "255.255.255.0" - #:gateway "192.168.1.254" - #:name-servers '("192.168.1.252" - "192.168.1.253")) + (append (list (service static-networking-service-type + (list (static-networking + (addresses + (list (network-address + (device "eth0") + (value "192.168.1.201/24")))) + (routes + (list (network-route + (destination "default") + (gateway "192.168.1.254")))) + (name-servers '("192.168.1.252" + "192.168.1.253"))))) ;; Ganeti uses SSH to communicate between nodes. (service openssh-service-type |