me/guix
Archived
1
0
Fork 0
Code Activity

doc: Add new "Networking Setup" node for the main setup options.

Browse source 
This should make it easier to find how to get started setting up
networking.

* doc/guix.texi (Networking Setup): New section.
(Networking Services): Remove 'static-networking-service',
'dhcp-client-service-type', 'network-manager-service-type',
'connman-service-type', 'wicd-service', 'modem-manager-service-type',
'usb-modeswitch-service-type', and 'wpa-supplicant-service-type'.
This commit is contained in:
Ludovic Courtès 2021-10-24 17:11:52 +02:00
parent 33c498b9ee
commit a4d33fef31
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5
1 changed files with 160 additions and 129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

289
doc/guix.texi
View file

@ -344,7 +344,8 @@ Services
* Base Services:: Essential system services. * Base Services:: Essential system services.
* Scheduled Job Execution:: The mcron service. * Scheduled Job Execution:: The mcron service.
* Log Rotation:: The rottlog 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. * Unattended Upgrades:: Automated system upgrades.
* X Window:: Graphical display. * X Window:: Graphical display.
* Printing Services:: Local and remote printer support. * Printing Services:: Local and remote printer support.
@ -15606,7 +15607,8 @@ declaration.
* Base Services:: Essential system services. * Base Services:: Essential system services.
* Scheduled Job Execution:: The mcron service. * Scheduled Job Execution:: The mcron service.
* Log Rotation:: The rottlog 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. * Unattended Upgrades:: Automated system upgrades.
* X Window:: Graphical display. * X Window:: Graphical display.
* Printing Services:: Local and remote printer support. * Printing Services:: Local and remote printer support.
@ -16828,63 +16830,26 @@ The list of syslog-controlled files to be rotated. By default it is:
"/var/log/maillog")}. "/var/log/maillog")}.
@end defvr @end defvr
@node Networking Services @node Networking Setup
@subsection Networking Services @subsection Networking Setup
The @code{(gnu services networking)} module provides services to configure The @code{(gnu services networking)} module provides services to
the network interface. 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 On a laptop, NetworkManager and Connman are by far the most convenient
@defvr {Scheme Variable} dhcp-client-service-type options, which is why the default desktop services include
This is the type of services that run @var{dhcp}, a Dynamic Host Configuration NetworkManager (@pxref{Desktop Services, @code{%desktop-services}}).
Protocol (DHCP) client, on all the non-loopback network interfaces. Its value For a server, or for a virtual machine or a container, static network
is the DHCP client package to use, @code{isc-dhcp} by default. configuration or a simple DHCP client are often more appropriate.
@end defvr
@deffn {Scheme Procedure} dhcpd-service-type This section describes the various network setup services available,
This type defines a service that runs a DHCP daemon. To create a starting with static network configuration.
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
@defvr {Scheme Variable} static-networking-service-type @defvr {Scheme Variable} static-networking-service-type
This is the type for statically-configured network interfaces. This is the type for statically-configured network interfaces.
@ -16914,81 +16879,13 @@ For example:
@end lisp @end lisp
@end deffn @end deffn
@cindex wicd @cindex DHCP, networking service
@cindex wireless @defvr {Scheme Variable} dhcp-client-service-type
@cindex WiFi This is the type of services that run @var{dhcp}, a Dynamic Host Configuration
@cindex network management Protocol (DHCP) client, on all the non-loopback network interfaces. Its value
@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] is the DHCP client package to use, @code{isc-dhcp} by default.
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
@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 @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
@cindex NetworkManager @cindex NetworkManager
@defvr {Scheme Variable} network-manager-service-type @defvr {Scheme Variable} network-manager-service-type
@ -17125,6 +17022,139 @@ List of additional command-line arguments to pass to the daemon.
@end table @end table
@end deftp @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 hostapd service, for Wi-Fi access points
@cindex Wi-Fi access points, hostapd service @cindex Wi-Fi access points, hostapd service
@defvr {Scheme Variable} hostapd-service-type @defvr {Scheme Variable} hostapd-service-type
@ -17187,6 +17217,7 @@ network that can be seen on @code{wlan0}, by default.
The service's value is a @code{hostapd-configuration} record. The service's value is a @code{hostapd-configuration} record.
@end defvr @end defvr
@cindex iptables @cindex iptables
@defvr {Scheme Variable} iptables-service-type @defvr {Scheme Variable} iptables-service-type
This is the service type to set up an iptables configuration. iptables is a This is the service type to set up an iptables configuration. iptables is a