swendel/nixpkgs
1
0
Fork 0
mirror of https://github.com/SebastianWendel/nixpkgs.git synced 2024-10-02 01:50:18 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #128892 from bobby285271/pr4

Browse source 
nixos/doc: convert "Chapter 13. Networking" to CommonMark
This commit is contained in:
Jörg Thalheim 2021-09-07 06:20:04 +01:00 committed by GitHub
parent c0735214e1 69bf2d1ed5
commit 96c98af211
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
25 changed files with 661 additions and 374 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
nixos/doc/manual/configuration/ad-hoc-network-config.section.md Normal file
View file

@ -0,0 +1,13 @@
# Ad-Hoc Configuration {#ad-hoc-network-config}
You can use [](#opt-networking.localCommands) to
specify shell commands to be run at the end of `network-setup.service`. This
is useful for doing network configuration not covered by the existing NixOS
modules. For instance, to statically configure an IPv6 address:
```nix
networking.localCommands =
''
ip -6 addr add 2001:610:685:1::1/64 dev eth0
'';
```

20
nixos/doc/manual/configuration/ad-hoc-network-config.xml
View file

@ -1,20 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ad-hoc-network-config">
<title>Ad-Hoc Configuration</title>
<para>
You can use <xref linkend="opt-networking.localCommands"/> to specify shell
commands to be run at the end of <literal>network-setup.service</literal>.
This is useful for doing network configuration not covered by the existing
NixOS modules. For instance, to statically configure an IPv6 address:
<programlisting>
<xref linkend="opt-networking.localCommands"/> =
''
ip -6 addr add 2001:610:685:1::1/64 dev eth0
'';
</programlisting>
</para>
</section>

32
nixos/doc/manual/configuration/firewall.section.md Normal file
View file

@ -0,0 +1,32 @@
# Firewall {#sec-firewall}
NixOS has a simple stateful firewall that blocks incoming connections
and other unexpected packets. The firewall applies to both IPv4 and IPv6
traffic. It is enabled by default. It can be disabled as follows:
```nix
networking.firewall.enable = false;
```
If the firewall is enabled, you can open specific TCP ports to the
outside world:
```nix
networking.firewall.allowedTCPPorts = [ 80 443 ];
```
Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is
enabled (`services.openssh.enable = true`). UDP ports can be opened through
[](#opt-networking.firewall.allowedUDPPorts).
To open ranges of TCP ports:
```nix
networking.firewall.allowedTCPPortRanges = [
{ from = 4000; to = 4007; }
{ from = 8000; to = 8010; }
];
```
Similarly, UDP port ranges can be opened through
[](#opt-networking.firewall.allowedUDPPortRanges).

37
nixos/doc/manual/configuration/firewall.xml
View file

@ -1,37 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-firewall">
<title>Firewall</title>
<para>
NixOS has a simple stateful firewall that blocks incoming connections and
other unexpected packets. The firewall applies to both IPv4 and IPv6 traffic.
It is enabled by default. It can be disabled as follows:
<programlisting>
<xref linkend="opt-networking.firewall.enable"/> = false;
</programlisting>
If the firewall is enabled, you can open specific TCP ports to the outside
world:
<programlisting>
<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 443 ];
</programlisting>
Note that TCP port 22 (ssh) is opened automatically if the SSH daemon is
enabled (<option><xref linkend="opt-services.openssh.enable"/> =
true</option>). UDP ports can be opened through
<xref linkend="opt-networking.firewall.allowedUDPPorts"/>.
</para>
<para>
To open ranges of TCP ports:
<programlisting>
<xref linkend="opt-networking.firewall.allowedTCPPortRanges"/> = [
{ from = 4000; to = 4007; }
{ from = 8000; to = 8010; }
];
</programlisting>
Similarly, UDP port ranges can be opened through
<xref linkend="opt-networking.firewall.allowedUDPPortRanges"/>.
</para>
</section>

35
nixos/doc/manual/configuration/ipv4-config.section.md Normal file
View file

@ -0,0 +1,35 @@
# IPv4 Configuration {#sec-ipv4}
By default, NixOS uses DHCP (specifically, `dhcpcd`) to automatically
configure network interfaces. However, you can configure an interface
manually as follows:
```nix
networking.interfaces.eth0.ipv4.addresses = [ {
address = "192.168.1.2";
prefixLength = 24;
} ];
```
Typically you'll also want to set a default gateway and set of name
servers:
```nix
networking.defaultGateway = "192.168.1.1";
networking.nameservers = [ "8.8.8.8" ];
```
::: {.note}
Statically configured interfaces are set up by the systemd service
`interface-name-cfg.service`. The default gateway and name server
configuration is performed by `network-setup.service`.
:::
The host name is set using [](#opt-networking.hostName):
```nix
networking.hostName = "cartman";
```
The default host name is `nixos`. Set it to the empty string (`""`) to
allow the DHCP server to provide the host name.

43
nixos/doc/manual/configuration/ipv4-config.xml
View file

@ -1,43 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-ipv4">
<title>IPv4 Configuration</title>
<para>
By default, NixOS uses DHCP (specifically, <command>dhcpcd</command>) to
automatically configure network interfaces. However, you can configure an
interface manually as follows:
<programlisting>
<link linkend="opt-networking.interfaces._name_.ipv4.addresses">networking.interfaces.eth0.ipv4.addresses</link> = [ {
address = "192.168.1.2";
prefixLength = 24;
} ];
</programlisting>
Typically you’ll also want to set a default gateway and set of name
servers:
<programlisting>
<xref linkend="opt-networking.defaultGateway"/> = "192.168.1.1";
<xref linkend="opt-networking.nameservers"/> = [ "8.8.8.8" ];
</programlisting>
</para>
<note>
<para>
Statically configured interfaces are set up by the systemd service
<replaceable>interface-name</replaceable><literal>-cfg.service</literal>.
The default gateway and name server configuration is performed by
<literal>network-setup.service</literal>.
</para>
</note>
<para>
The host name is set using <xref linkend="opt-networking.hostName"/>:
<programlisting>
<xref linkend="opt-networking.hostName"/> = "cartman";
</programlisting>
The default host name is <literal>nixos</literal>. Set it to the empty string
(<literal>""</literal>) to allow the DHCP server to provide the host name.
</para>
</section>

42
nixos/doc/manual/configuration/ipv6-config.section.md Normal file
View file

@ -0,0 +1,42 @@
# IPv6 Configuration {#sec-ipv6}
IPv6 is enabled by default. Stateless address autoconfiguration is used
to automatically assign IPv6 addresses to all interfaces, and Privacy
Extensions (RFC 4946) are enabled by default. You can adjust the default
for this by setting [](#opt-networking.tempAddresses). This option
may be overridden on a per-interface basis by
[](#opt-networking.interfaces._name_.tempAddress). You can disable
IPv6 support globally by setting:
```nix
networking.enableIPv6 = false;
```
You can disable IPv6 on a single interface using a normal sysctl (in
this example, we use interface `eth0`):
```nix
boot.kernel.sysctl."net.ipv6.conf.eth0.disable_ipv6" = true;
```
As with IPv4 networking interfaces are automatically configured via
DHCPv6. You can configure an interface manually:
```nix
networking.interfaces.eth0.ipv6.addresses = [ {
address = "fe00:aa:bb:cc::2";
prefixLength = 64;
} ];
```
For configuring a gateway, optionally with explicitly specified
interface:
```nix
networking.defaultGateway6 = {
address = "fe00::1";
interface = "enp0s3";
};
```
See [](#sec-ipv4) for similar examples and additional information.

54
nixos/doc/manual/configuration/ipv6-config.xml
View file

@ -1,54 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-ipv6">
<title>IPv6 Configuration</title>
<para>
IPv6 is enabled by default. Stateless address autoconfiguration is used to
automatically assign IPv6 addresses to all interfaces, and Privacy
Extensions (RFC 4946) are enabled by default. You can adjust the default
for this by setting <xref linkend="opt-networking.tempAddresses"/>.
This option may be overridden on a per-interface basis by
<xref linkend="opt-networking.interfaces._name_.tempAddress"/>.
You can disable IPv6 support globally by setting:
<programlisting>
<xref linkend="opt-networking.enableIPv6"/> = false;
</programlisting>
</para>
<para>
You can disable IPv6 on a single interface using a normal sysctl (in this
example, we use interface <varname>eth0</varname>):
<programlisting>
<xref linkend="opt-boot.kernel.sysctl"/>."net.ipv6.conf.eth0.disable_ipv6" = true;
</programlisting>
</para>
<para>
As with IPv4 networking interfaces are automatically configured via DHCPv6.
You can configure an interface manually:
<programlisting>
<link linkend="opt-networking.interfaces._name_.ipv6.addresses">networking.interfaces.eth0.ipv6.addresses</link> = [ {
address = "fe00:aa:bb:cc::2";
prefixLength = 64;
} ];
</programlisting>
</para>
<para>
For configuring a gateway, optionally with explicitly specified interface:
<programlisting>
<xref linkend="opt-networking.defaultGateway6"/> = {
address = "fe00::1";
interface = "enp0s3";
};
</programlisting>
</para>
<para>
See <xref linkend='sec-ipv4' /> for similar examples and additional
information.
</para>
</section>

42
nixos/doc/manual/configuration/network-manager.section.md Normal file
View file

@ -0,0 +1,42 @@
# NetworkManager {#sec-networkmanager}
To facilitate network configuration, some desktop environments use
NetworkManager. You can enable NetworkManager by setting:
```nix
networking.networkmanager.enable = true;
```
some desktop managers (e.g., GNOME) enable NetworkManager automatically
for you.
All users that should have permission to change network settings must
belong to the `networkmanager` group:
```nix
users.users.alice.extraGroups = [ "networkmanager" ];
```
NetworkManager is controlled using either `nmcli` or `nmtui`
(curses-based terminal user interface). See their manual pages for
details on their usage. Some desktop environments (GNOME, KDE) have
their own configuration tools for NetworkManager. On XFCE, there is no
configuration tool for NetworkManager by default: by enabling
[](#opt-programs.nm-applet.enable), the graphical applet will be
installed and will launch automatically when the graphical session is
started.
::: {.note}
`networking.networkmanager` and `networking.wireless` (WPA Supplicant)
can be used together if desired. To do this you need to instruct
NetworkManager to ignore those interfaces like:
```nix
networking.networkmanager.unmanaged = [
"*" "except:type:wwan" "except:type:gsm"
];
```
Refer to the option description for the exact syntax and references to
external documentation.
:::

48
nixos/doc/manual/configuration/network-manager.xml
View file

@ -1,48 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-networkmanager">
<title>NetworkManager</title>
<para>
To facilitate network configuration, some desktop environments use
NetworkManager. You can enable NetworkManager by setting:
<programlisting>
<xref linkend="opt-networking.networkmanager.enable"/> = true;
</programlisting>
some desktop managers (e.g., GNOME) enable NetworkManager automatically for
you.
</para>
<para>
All users that should have permission to change network settings must belong
to the <code>networkmanager</code> group:
<programlisting>
<link linkend="opt-users.users._name_.extraGroups">users.users.alice.extraGroups</link> = [ "networkmanager" ];
</programlisting>
</para>
<para>
NetworkManager is controlled using either <command>nmcli</command> or
<command>nmtui</command> (curses-based terminal user interface). See their
manual pages for details on their usage. Some desktop environments (GNOME,
KDE) have their own configuration tools for NetworkManager. On XFCE, there is
no configuration tool for NetworkManager by default: by enabling <xref linkend="opt-programs.nm-applet.enable"/>, the
graphical applet will be installed and will launch automatically when the graphical session is started.
</para>
<note>
<para>
<code>networking.networkmanager</code> and <code>networking.wireless</code>
(WPA Supplicant) can be used together if desired. To do this you need to instruct
NetworkManager to ignore those interfaces like:
<programlisting>
<xref linkend="opt-networking.networkmanager.unmanaged"/> = [
"*" "except:type:wwan" "except:type:gsm"
];
</programlisting>
Refer to the option description for the exact syntax and references to external documentation.
</para>
</note>
</section>

16
nixos/doc/manual/configuration/networking.xml
View file

@ -8,13 +8,13 @@
This section describes how to configure networking components on your NixOS
machine.
</para>
<xi:include href="network-manager.xml" />
<xi:include href="ssh.xml" />
<xi:include href="ipv4-config.xml" />
<xi:include href="ipv6-config.xml" />
<xi:include href="firewall.xml" />
<xi:include href="wireless.xml" />
<xi:include href="ad-hoc-network-config.xml" />
<xi:include href="renaming-interfaces.xml" />
<xi:include href="../from_md/configuration/network-manager.section.xml" />
<xi:include href="../from_md/configuration/ssh.section.xml" />
<xi:include href="../from_md/configuration/ipv4-config.section.xml" />
<xi:include href="../from_md/configuration/ipv6-config.section.xml" />
<xi:include href="../from_md/configuration/firewall.section.xml" />
<xi:include href="../from_md/configuration/wireless.section.xml" />
<xi:include href="../from_md/configuration/ad-hoc-network-config.section.xml" />
<xi:include href="../from_md/configuration/renaming-interfaces.section.xml" />
<!-- TODO: OpenVPN, NAT -->
</chapter>

51
nixos/doc/manual/configuration/renaming-interfaces.section.md Normal file
View file

@ -0,0 +1,51 @@
# Renaming network interfaces {#sec-rename-ifs}
NixOS uses the udev [predictable naming
scheme](https://systemd.io/PREDICTABLE_INTERFACE_NAMES/) to assign names
to network interfaces. This means that by default cards are not given
the traditional names like `eth0` or `eth1`, whose order can change
unpredictably across reboots. Instead, relying on physical locations and
firmware information, the scheme produces names like `ens1`, `enp2s0`,
etc.
These names are predictable but less memorable and not necessarily
stable: for example installing new hardware or changing firmware
settings can result in a [name
change](https://github.com/systemd/systemd/issues/3715#issue-165347602).
If this is undesirable, for example if you have a single ethernet card,
you can revert to the traditional scheme by setting
[](#opt-networking.usePredictableInterfaceNames)
to `false`.
## Assigning custom names {#sec-custom-ifnames}
In case there are multiple interfaces of the same type, it's better to
assign custom names based on the device hardware address. For example,
we assign the name `wan` to the interface with MAC address
`52:54:00:12:01:01` using a netword link unit:
```nix
systemd.network.links."10-wan" = {
matchConfig.MACAddress = "52:54:00:12:01:01";
linkConfig.Name = "wan";
};
```
Note that links are directly read by udev, *not networkd*, and will work
even if networkd is disabled.
Alternatively, we can use a plain old udev rule:
```nix
services.udev.initrdRules = ''
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
'';
```
::: {.warning}
The rule must be installed in the initrd using
`services.udev.initrdRules`, not the usual `services.udev.extraRules`
option. This is to avoid race conditions with other programs controlling
the interface.
:::

67
nixos/doc/manual/configuration/renaming-interfaces.xml
View file

@ -1,67 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-rename-ifs">
<title>Renaming network interfaces</title>
<para>
NixOS uses the udev
<link xlink:href="https://systemd.io/PREDICTABLE_INTERFACE_NAMES/">predictable naming scheme</link>
to assign names to network interfaces. This means that by default
cards are not given the traditional names like
<literal>eth0</literal> or <literal>eth1</literal>, whose order can
change unpredictably across reboots. Instead, relying on physical
locations and firmware information, the scheme produces names like
<literal>ens1</literal>, <literal>enp2s0</literal>, etc.
</para>
<para>
These names are predictable but less memorable and not necessarily
stable: for example installing new hardware or changing firmware
settings can result in a
<link xlink:href="https://github.com/systemd/systemd/issues/3715#issue-165347602">name change</link>.
If this is undesirable, for example if you have a single ethernet
card, you can revert to the traditional scheme by setting
<xref linkend="opt-networking.usePredictableInterfaceNames"/> to
<literal>false</literal>.
</para>
<section xml:id="sec-custom-ifnames">
<title>Assigning custom names</title>
<para>
In case there are multiple interfaces of the same type, it’s better to
assign custom names based on the device hardware address. For
example, we assign the name <literal>wan</literal> to the interface
with MAC address <literal>52:54:00:12:01:01</literal> using a
netword link unit:
</para>
<programlisting>
<link linkend="opt-systemd.network.links">systemd.network.links."10-wan"</link> = {
matchConfig.MACAddress = "52:54:00:12:01:01";
linkConfig.Name = "wan";
};
</programlisting>
<para>
Note that links are directly read by udev, <emphasis>not networkd</emphasis>,
and will work even if networkd is disabled.
</para>
<para>
Alternatively, we can use a plain old udev rule:
</para>
<programlisting>
<link linkend="opt-services.udev.initrdRules">services.udev.initrdRules</link> = ''
SUBSYSTEM=="net", ACTION=="add", DRIVERS=="?*", \
ATTR{address}=="52:54:00:12:01:01", KERNEL=="eth*", NAME="wan"
'';
</programlisting>
<warning><para>
The rule must be installed in the initrd using
<literal>services.udev.initrdRules</literal>, not the usual
<literal>services.udev.extraRules</literal> option. This is to avoid race
conditions with other programs controlling the interface.
</para></warning>
</section>
</section>

19
nixos/doc/manual/configuration/ssh.section.md Normal file
View file

@ -0,0 +1,19 @@
# Secure Shell Access {#sec-ssh}
Secure shell (SSH) access to your machine can be enabled by setting:
```nix
services.openssh.enable = true;
```
By default, root logins using a password are disallowed. They can be
disabled entirely by setting
[](#opt-services.openssh.permitRootLogin) to `"no"`.
You can declaratively specify authorised RSA/DSA public keys for a user
as follows:
```nix
users.users.alice.openssh.authorizedKeys.keys =
[ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
```

27
nixos/doc/manual/configuration/ssh.xml
View file

@ -1,27 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-ssh">
<title>Secure Shell Access</title>
<para>
Secure shell (SSH) access to your machine can be enabled by setting:
<programlisting>
<xref linkend="opt-services.openssh.enable"/> = true;
</programlisting>
By default, root logins using a password are disallowed. They can be disabled
entirely by setting <xref linkend="opt-services.openssh.permitRootLogin"/> to
<literal>"no"</literal>.
</para>
<para>
You can declaratively specify authorised RSA/DSA public keys for a user as
follows:
<!-- FIXME: this might not work if the user is unmanaged. -->
<programlisting>
<link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.alice.openssh.authorizedKeys.keys</link> =
[ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
</programlisting>
</para>
</section>

67
nixos/doc/manual/configuration/wireless.section.md Normal file
View file

@ -0,0 +1,67 @@
# Wireless Networks {#sec-wireless}
For a desktop installation using NetworkManager (e.g., GNOME), you just
have to make sure the user is in the `networkmanager` group and you can
skip the rest of this section on wireless networks.
NixOS will start wpa_supplicant for you if you enable this setting:
```nix
networking.wireless.enable = true;
```
NixOS lets you specify networks for wpa_supplicant declaratively:
```nix
networking.wireless.networks = {
echelon = { # SSID with no spaces or special characters
psk = "abcdefgh";
};
"echelon's AP" = { # SSID with spaces and/or special characters
psk = "ijklmnop";
};
echelon = { # Hidden SSID
hidden = true;
psk = "qrstuvwx";
};
free.wifi = {}; # Public wireless network
};
```
Be aware that keys will be written to the nix store in plaintext! When
no networks are set, it will default to using a configuration file at
`/etc/wpa_supplicant.conf`. You should edit this file yourself to define
wireless networks, WPA keys and so on (see wpa_supplicant.conf(5)).
If you are using WPA2 you can generate pskRaw key using
`wpa_passphrase`:
```ShellSession
$ wpa_passphrase ESSID PSK
network={
ssid="echelon"
#psk="abcdefgh"
psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
}
```
```nix
networking.wireless.networks = {
echelon = {
pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
};
}
```
or you can use it to directly generate the `wpa_supplicant.conf`:
```ShellSession
# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf
```
After you have edited the `wpa_supplicant.conf`, you need to restart the
wpa_supplicant service.
```ShellSession
# systemctl restart wpa_supplicant.service
```

70
nixos/doc/manual/configuration/wireless.xml
View file

@ -1,70 +0,0 @@
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-wireless">
<title>Wireless Networks</title>
<para>
For a desktop installation using NetworkManager (e.g., GNOME), you just have
to make sure the user is in the <code>networkmanager</code> group and you can
skip the rest of this section on wireless networks.
</para>
<para>
NixOS will start wpa_supplicant for you if you enable this setting:
<programlisting>
<xref linkend="opt-networking.wireless.enable"/> = true;
</programlisting>
NixOS lets you specify networks for wpa_supplicant declaratively:
<programlisting>
<xref linkend="opt-networking.wireless.networks"/> = {
echelon = { # SSID with no spaces or special characters
psk = "abcdefgh";
};
"echelon's AP" = { # SSID with spaces and/or special characters
psk = "ijklmnop";
};
echelon = { # Hidden SSID
hidden = true;
psk = "qrstuvwx";
};
free.wifi = {}; # Public wireless network
};
</programlisting>
Be aware that keys will be written to the nix store in plaintext! When no
networks are set, it will default to using a configuration file at
<literal>/etc/wpa_supplicant.conf</literal>. You should edit this file
yourself to define wireless networks, WPA keys and so on (see <citerefentry>
<refentrytitle>wpa_supplicant.conf</refentrytitle>
<manvolnum>5</manvolnum> </citerefentry>).
</para>
<para>
If you are using WPA2 you can generate pskRaw key using
<command>wpa_passphrase</command>:
<screen>
<prompt>$ </prompt>wpa_passphrase ESSID PSK
network={
ssid="echelon"
#psk="abcdefgh"
psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
}
</screen>
<programlisting>
<xref linkend="opt-networking.wireless.networks"/> = {
echelon = {
pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
};
}
</programlisting>
or you can use it to directly generate the
<literal>wpa_supplicant.conf</literal>:
<screen>
<prompt># </prompt>wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>
After you have edited the <literal>wpa_supplicant.conf</literal>, you need to
restart the wpa_supplicant service.
<screen>
<prompt># </prompt>systemctl restart wpa_supplicant.service</screen>
</para>
</section>

16
nixos/doc/manual/from_md/configuration/ad-hoc-network-config.section.xml Normal file
View file

@ -0,0 +1,16 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="ad-hoc-network-config">
<title>Ad-Hoc Configuration</title>
<para>
You can use <xref linkend="opt-networking.localCommands" /> to
specify shell commands to be run at the end of
<literal>network-setup.service</literal>. This is useful for doing
network configuration not covered by the existing NixOS modules. For
instance, to statically configure an IPv6 address:
</para>
<programlisting language="bash">
networking.localCommands =
''
ip -6 addr add 2001:610:685:1::1/64 dev eth0
'';
</programlisting>
</section>

39
nixos/doc/manual/from_md/configuration/firewall.section.xml Normal file
View file

@ -0,0 +1,39 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-firewall">
<title>Firewall</title>
<para>
NixOS has a simple stateful firewall that blocks incoming
connections and other unexpected packets. The firewall applies to
both IPv4 and IPv6 traffic. It is enabled by default. It can be
disabled as follows:
</para>
<programlisting language="bash">
networking.firewall.enable = false;
</programlisting>
<para>
If the firewall is enabled, you can open specific TCP ports to the
outside world:
</para>
<programlisting language="bash">
networking.firewall.allowedTCPPorts = [ 80 443 ];
</programlisting>
<para>
Note that TCP port 22 (ssh) is opened automatically if the SSH
daemon is enabled
(<literal>services.openssh.enable = true</literal>). UDP ports can
be opened through
<xref linkend="opt-networking.firewall.allowedUDPPorts" />.
</para>
<para>
To open ranges of TCP ports:
</para>
<programlisting language="bash">
networking.firewall.allowedTCPPortRanges = [
{ from = 4000; to = 4007; }
{ from = 8000; to = 8010; }
];
</programlisting>
<para>
Similarly, UDP port ranges can be opened through
<xref linkend="opt-networking.firewall.allowedUDPPortRanges" />.
</para>
</section>

43
nixos/doc/manual/from_md/configuration/ipv4-config.section.xml Normal file
View file

@ -0,0 +1,43 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-ipv4">
<title>IPv4 Configuration</title>
<para>
By default, NixOS uses DHCP (specifically,
<literal>dhcpcd</literal>) to automatically configure network
interfaces. However, you can configure an interface manually as
follows:
</para>
<programlisting language="bash">
networking.interfaces.eth0.ipv4.addresses = [ {
address = &quot;192.168.1.2&quot;;
prefixLength = 24;
} ];
</programlisting>
<para>
Typically you’ll also want to set a default gateway and set of name
servers:
</para>
<programlisting language="bash">
networking.defaultGateway = &quot;192.168.1.1&quot;;
networking.nameservers = [ &quot;8.8.8.8&quot; ];
</programlisting>
<note>
<para>
Statically configured interfaces are set up by the systemd service
<literal>interface-name-cfg.service</literal>. The default gateway
and name server configuration is performed by
<literal>network-setup.service</literal>.
</para>
</note>
<para>
The host name is set using
<xref linkend="opt-networking.hostName" />:
</para>
<programlisting language="bash">
networking.hostName = &quot;cartman&quot;;
</programlisting>
<para>
The default host name is <literal>nixos</literal>. Set it to the
empty string (<literal>&quot;&quot;</literal>) to allow the DHCP
server to provide the host name.
</para>
</section>

47
nixos/doc/manual/from_md/configuration/ipv6-config.section.xml Normal file
View file

@ -0,0 +1,47 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-ipv6">
<title>IPv6 Configuration</title>
<para>
IPv6 is enabled by default. Stateless address autoconfiguration is
used to automatically assign IPv6 addresses to all interfaces, and
Privacy Extensions (RFC 4946) are enabled by default. You can adjust
the default for this by setting
<xref linkend="opt-networking.tempAddresses" />. This option may be
overridden on a per-interface basis by
<xref linkend="opt-networking.interfaces._name_.tempAddress" />. You
can disable IPv6 support globally by setting:
</para>
<programlisting language="bash">
networking.enableIPv6 = false;
</programlisting>
<para>
You can disable IPv6 on a single interface using a normal sysctl (in
this example, we use interface <literal>eth0</literal>):
</para>
<programlisting language="bash">
boot.kernel.sysctl.&quot;net.ipv6.conf.eth0.disable_ipv6&quot; = true;
</programlisting>
<para>
As with IPv4 networking interfaces are automatically configured via
DHCPv6. You can configure an interface manually:
</para>
<programlisting language="bash">
networking.interfaces.eth0.ipv6.addresses = [ {
address = &quot;fe00:aa:bb:cc::2&quot;;
prefixLength = 64;
} ];
</programlisting>
<para>
For configuring a gateway, optionally with explicitly specified
interface:
</para>
<programlisting language="bash">
networking.defaultGateway6 = {
address = &quot;fe00::1&quot;;
interface = &quot;enp0s3&quot;;
};
</programlisting>
<para>
See <xref linkend="sec-ipv4" /> for similar examples and additional
information.
</para>
</section>

49
nixos/doc/manual/from_md/configuration/network-manager.section.xml Normal file
View file

@ -0,0 +1,49 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-networkmanager">
<title>NetworkManager</title>
<para>
To facilitate network configuration, some desktop environments use
NetworkManager. You can enable NetworkManager by setting:
</para>
<programlisting language="bash">
networking.networkmanager.enable = true;
</programlisting>
<para>
some desktop managers (e.g., GNOME) enable NetworkManager
automatically for you.
</para>
<para>
All users that should have permission to change network settings
must belong to the <literal>networkmanager</literal> group:
</para>
<programlisting language="bash">
users.users.alice.extraGroups = [ &quot;networkmanager&quot; ];
</programlisting>
<para>
NetworkManager is controlled using either <literal>nmcli</literal>
or <literal>nmtui</literal> (curses-based terminal user interface).
See their manual pages for details on their usage. Some desktop
environments (GNOME, KDE) have their own configuration tools for
NetworkManager. On XFCE, there is no configuration tool for
NetworkManager by default: by enabling
<xref linkend="opt-programs.nm-applet.enable" />, the graphical
applet will be installed and will launch automatically when the
graphical session is started.
</para>
<note>
<para>
<literal>networking.networkmanager</literal> and
<literal>networking.wireless</literal> (WPA Supplicant) can be
used together if desired. To do this you need to instruct
NetworkManager to ignore those interfaces like:
</para>
<programlisting language="bash">
networking.networkmanager.unmanaged = [
&quot;*&quot; &quot;except:type:wwan&quot; &quot;except:type:gsm&quot;
];
</programlisting>
<para>
Refer to the option description for the exact syntax and
references to external documentation.
</para>
</note>
</section>

62
nixos/doc/manual/from_md/configuration/renaming-interfaces.section.xml Normal file
View file

@ -0,0 +1,62 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-rename-ifs">
<title>Renaming network interfaces</title>
<para>
NixOS uses the udev
<link xlink:href="https://systemd.io/PREDICTABLE_INTERFACE_NAMES/">predictable
naming scheme</link> to assign names to network interfaces. This
means that by default cards are not given the traditional names like
<literal>eth0</literal> or <literal>eth1</literal>, whose order can
change unpredictably across reboots. Instead, relying on physical
locations and firmware information, the scheme produces names like
<literal>ens1</literal>, <literal>enp2s0</literal>, etc.
</para>
<para>
These names are predictable but less memorable and not necessarily
stable: for example installing new hardware or changing firmware
settings can result in a
<link xlink:href="https://github.com/systemd/systemd/issues/3715#issue-165347602">name
change</link>. If this is undesirable, for example if you have a
single ethernet card, you can revert to the traditional scheme by
setting
<xref linkend="opt-networking.usePredictableInterfaceNames" /> to
<literal>false</literal>.
</para>
<section xml:id="sec-custom-ifnames">
<title>Assigning custom names</title>
<para>
In case there are multiple interfaces of the same type, it’s
better to assign custom names based on the device hardware
address. For example, we assign the name <literal>wan</literal> to
the interface with MAC address
<literal>52:54:00:12:01:01</literal> using a netword link unit:
</para>
<programlisting language="bash">
systemd.network.links.&quot;10-wan&quot; = {
matchConfig.MACAddress = &quot;52:54:00:12:01:01&quot;;
linkConfig.Name = &quot;wan&quot;;
};
</programlisting>
<para>
Note that links are directly read by udev, <emphasis>not
networkd</emphasis>, and will work even if networkd is disabled.
</para>
<para>
Alternatively, we can use a plain old udev rule:
</para>
<programlisting language="bash">
services.udev.initrdRules = ''
SUBSYSTEM==&quot;net&quot;, ACTION==&quot;add&quot;, DRIVERS==&quot;?*&quot;, \
ATTR{address}==&quot;52:54:00:12:01:01&quot;, KERNEL==&quot;eth*&quot;, NAME=&quot;wan&quot;
'';
</programlisting>
<warning>
<para>
The rule must be installed in the initrd using
<literal>services.udev.initrdRules</literal>, not the usual
<literal>services.udev.extraRules</literal> option. This is to
avoid race conditions with other programs controlling the
interface.
</para>
</warning>
</section>
</section>

23
nixos/doc/manual/from_md/configuration/ssh.section.xml Normal file
View file

@ -0,0 +1,23 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-ssh">
<title>Secure Shell Access</title>
<para>
Secure shell (SSH) access to your machine can be enabled by setting:
</para>
<programlisting language="bash">
services.openssh.enable = true;
</programlisting>
<para>
By default, root logins using a password are disallowed. They can be
disabled entirely by setting
<xref linkend="opt-services.openssh.permitRootLogin" /> to
<literal>&quot;no&quot;</literal>.
</para>
<para>
You can declaratively specify authorised RSA/DSA public keys for a
user as follows:
</para>
<programlisting language="bash">
users.users.alice.openssh.authorizedKeys.keys =
[ &quot;ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4...&quot; ];
</programlisting>
</section>

73
nixos/doc/manual/from_md/configuration/wireless.section.xml Normal file
View file

@ -0,0 +1,73 @@
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-wireless">
<title>Wireless Networks</title>
<para>
For a desktop installation using NetworkManager (e.g., GNOME), you
just have to make sure the user is in the
<literal>networkmanager</literal> group and you can skip the rest of
this section on wireless networks.
</para>
<para>
NixOS will start wpa_supplicant for you if you enable this setting:
</para>
<programlisting language="bash">
networking.wireless.enable = true;
</programlisting>
<para>
NixOS lets you specify networks for wpa_supplicant declaratively:
</para>
<programlisting language="bash">
networking.wireless.networks = {
echelon = { # SSID with no spaces or special characters
psk = &quot;abcdefgh&quot;;
};
&quot;echelon's AP&quot; = { # SSID with spaces and/or special characters
psk = &quot;ijklmnop&quot;;
};
echelon = { # Hidden SSID
hidden = true;
psk = &quot;qrstuvwx&quot;;
};
free.wifi = {}; # Public wireless network
};
</programlisting>
<para>
Be aware that keys will be written to the nix store in plaintext!
When no networks are set, it will default to using a configuration
file at <literal>/etc/wpa_supplicant.conf</literal>. You should edit
this file yourself to define wireless networks, WPA keys and so on
(see wpa_supplicant.conf(5)).
</para>
<para>
If you are using WPA2 you can generate pskRaw key using
<literal>wpa_passphrase</literal>:
</para>
<programlisting>
$ wpa_passphrase ESSID PSK
network={
ssid=&quot;echelon&quot;
#psk=&quot;abcdefgh&quot;
psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
}
</programlisting>
<programlisting language="bash">
networking.wireless.networks = {
echelon = {
pskRaw = &quot;dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435&quot;;
};
}
</programlisting>
<para>
or you can use it to directly generate the
<literal>wpa_supplicant.conf</literal>:
</para>
<programlisting>
# wpa_passphrase ESSID PSK &gt; /etc/wpa_supplicant.conf
</programlisting>
<para>
After you have edited the <literal>wpa_supplicant.conf</literal>,
you need to restart the wpa_supplicant service.
</para>
<programlisting>
# systemctl restart wpa_supplicant.service
</programlisting>
</section>