nixpkgs/doc/manual/configuration.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="ch-configuration">

<title>Configuring NixOS</title>

<para>This chapter describes how to configure various aspects of a
NixOS machine through the configuration file
<filename>/etc/nixos/configuration.nix</filename>.  As described in
<xref linkend="sec-changing-config" />, changes to that file only take
effect after you run <command>nixos-rebuild</command>.</para>


<!--===============================================================-->

<section><title>Networking</title>

<section><title>Secure shell access</title>

<para>Secure shell (SSH) access to your machine can be enabled by
setting:

<programlisting>
services.openssh.enable = true;
</programlisting>

By default, root logins using a password are disallowed.  They can be
disabled entirely by setting
<literal>services.openssh.permitRootLogin</literal> 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>
users.extraUsers.alice.openssh.authorizedKeys.keys =
  [ "ssh-dss AAAAB3NzaC1kc3MAAACBAPIkGWVEt4..." ];
</programlisting>

</para>

</section>


<section><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>
networking.interfaces.eth0 = { ipAddress = "192.168.1.2"; prefixLength = 24; };
</programlisting>

(The network prefix can also be specified using the option
<literal>subnetMask</literal>,
e.g. <literal>"255.255.255.0"</literal>, but this is deprecated.)
Typically you’ll also want to set a default gateway and set of name
servers:

<programlisting>
networking.defaultGateway = "192.168.1.1";
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 <option>networking.hostName</option>:

<programlisting>
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>


<section><title>IPv6 configuration</title>

<para>IPv6 is enabled by default.  Stateless address autoconfiguration
is used to automatically assign IPv6 addresses to all interfaces.  You
can disable IPv6 support globally by setting:

<programlisting>
networking.enableIPv6 = false;
</programlisting>

</para>

</section>


<section><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 can be enabled as follows:

<programlisting>
networking.firewall.enable = true;
</programlisting>

You can open specific TCP ports to the outside world:

<programlisting>
networking.firewall.allowedTCPPorts = [ 80 443 ];
</programlisting>

Note that TCP port 22 (ssh) is opened automatically if the SSH daemon
is enabled (<option>services.openssh.enable = true</option>).  UDP
ports can be opened through
<option>networking.firewall.allowedUDPPorts</option>.  Also of
interest is

<programlisting>
networking.firewall.allowPing = true;
</programlisting>

to allow the machine to respond to ping requests.  (ICMPv6 pings are
always allowed.)</para>

</section>


<section><title>Wireless networks</title>

<para>
NixOS will start wpa_supplicant for you if you enable this setting:

<programlisting>
networking.wireless.enable = true;
</programlisting>

NixOS currently does not generate wpa_supplicant's
configuration file, <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 the <command>wpa_passphrase</command> tool might be useful
to generate the <literal>wpa_supplicant.conf</literal>.

<screen>
$ 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>
$ systemctl restart wpa_supplicant.service</screen>
</para>


</section>


<section><title>Ad-hoc configuration</title>

<para>You can use <option>networking.localCommands</option> 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>
networking.localCommands =
  ''
    ip -6 addr add 2001:610:685:1::1/64 dev eth0
  '';
</programlisting>

</para>

</section>


<!-- TODO: OpenVPN, NAT -->


</section>


<!-- TODO: declarative package installation; X11; user management;
     Apache; libvirtd virtualisation -->


</chapter>