Add section on network configuration topics

doc/manual/configuration.xml

@@ -0,0 +1,169 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xml:id="ch-configuration">
+
+<title>Configuration</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>TODO</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>
+
+
+</chapter>

doc/manual/installation.xml

@@ -329,7 +329,7 @@ You can then upgrade NixOS to the latest version in the channel by
 running
 
 <screen>
-$ nix-channel --update
+$ nix-channel --update nixos
 </screen>
 
 and running the <command>nixos-rebuild</command> command as described

doc/manual/manual.xml

@@ -50,6 +50,7 @@
 
 
   <xi:include href="installation.xml" />
+  <xi:include href="configuration.xml" />
   <!-- <xi:include href="userconfiguration.xml" /> -->
   <xi:include href="troubleshooting.xml" />
   <xi:include href="development.xml" />