diff options
Diffstat (limited to 'nixos/doc/manual/containers.xml')
| -rw-r--r-- | nixos/doc/manual/containers.xml | 242 |
1 files changed, 0 insertions, 242 deletions
diff --git a/nixos/doc/manual/containers.xml b/nixos/doc/manual/containers.xml deleted file mode 100644 index 2530d5195212..000000000000 --- a/nixos/doc/manual/containers.xml +++ /dev/null @@ -1,242 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xml:id="ch-containers"> - -<title>Containers</title> - -<para>NixOS allows you to easily run other NixOS instances as -<emphasis>containers</emphasis>. Containers are a light-weight -approach to virtualisation that runs software in the container at the -same speed as in the host system. NixOS containers share the Nix store -of the host, making container creation very efficient.</para> - -<warning><para>Currently, NixOS containers are not perfectly isolated -from the host system. This means that a user with root access to the -container can do things that affect the host. So you should not give -container root access to untrusted users.</para></warning> - -<para>NixOS containers can be created in two ways: imperatively, using -the command <command>nixos-container</command>, and declaratively, by -specifying them in your <filename>configuration.nix</filename>. The -declarative approach implies that containers get upgraded along with -your host system when you run <command>nixos-rebuild</command>, which -is often not what you want. By contrast, in the imperative approach, -containers are configured and updated independently from the host -system.</para> - - -<section><title>Imperative container management</title> - -<para>We’ll cover imperative container management using -<command>nixos-container</command> first. You create a container with -identifier <literal>foo</literal> as follows: - -<screen> -$ nixos-container create foo -</screen> - -This creates the container’s root directory in -<filename>/var/lib/containers/foo</filename> and a small configuration -file in <filename>/etc/containers/foo.conf</filename>. It also builds -the container’s initial system configuration and stores it in -<filename>/nix/var/nix/profiles/per-container/foo/system</filename>. You -can modify the initial configuration of the container on the command -line. For instance, to create a container that has -<command>sshd</command> running, with the given public key for -<literal>root</literal>: - -<screen> -$ nixos-container create foo --config 'services.openssh.enable = true; \ - users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];' -</screen> - -</para> - -<para>Creating a container does not start it. To start the container, -run: - -<screen> -$ nixos-container start foo -</screen> - -This command will return as soon as the container has booted and has -reached <literal>multi-user.target</literal>. On the host, the -container runs within a systemd unit called -<literal>container@<replaceable>container-name</replaceable>.service</literal>. -Thus, if something went wrong, you can get status info using -<command>systemctl</command>: - -<screen> -$ systemctl status container@foo -</screen> - -</para> - -<para>If the container has started succesfully, you can log in as -root using the <command>root-login</command> operation: - -<screen> -$ nixos-container root-login foo -[root@foo:~]# -</screen> - -Note that only root on the host can do this (since there is no -authentication). You can also get a regular login prompt using the -<command>login</command> operation, which is available to all users on -the host: - -<screen> -$ nixos-container login foo -foo login: alice -Password: *** -</screen> - -With <command>nixos-container run</command>, you can execute arbitrary -commands in the container: - -<screen> -$ nixos-container run foo -- uname -a -Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux -</screen> - -</para> - -<para>There are several ways to change the configuration of the -container. First, on the host, you can edit -<literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>, -and run - -<screen> -$ nixos-container update foo -</screen> - -This will build and activate the new configuration. You can also -specify a new configuration on the command line: - -<screen> -$ nixos-container update foo --config 'services.httpd.enable = true; \ - services.httpd.adminAddr = "foo@example.org";' - -$ curl http://$(nixos-container show-ip foo)/ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">… -</screen> - -However, note that this will overwrite the container’s -<filename>/etc/nixos/configuration.nix</filename>.</para> - -<para>Alternatively, you can change the configuration from within the -container itself by running <command>nixos-rebuild switch</command> -inside the container. Note that the container by default does not have -a copy of the NixOS channel, so you should run <command>nix-channel ---update</command> first.</para> - -<para>Containers can be stopped and started using -<literal>nixos-container stop</literal> and <literal>nixos-container -start</literal>, respectively, or by using -<command>systemctl</command> on the container’s service unit. To -destroy a container, including its file system, do - -<screen> -$ nixos-container destroy foo -</screen> - -</para> - -</section> - - -<section><title>Declarative container specification</title> - -<para>You can also specify containers and their configuration in the -host’s <filename>configuration.nix</filename>. For example, the -following specifies that there shall be a container named -<literal>database</literal> running PostgreSQL: - -<programlisting> -containers.database = - { config = - { config, pkgs, ... }: - { services.postgresql.enable = true; - services.postgresql.package = pkgs.postgresql92; - }; - }; -</programlisting> - -If you run <literal>nixos-rebuild switch</literal>, the container will -be built and started. If the container was already running, it will be -updated in place, without rebooting.</para> - -<para>By default, declarative containers share the network namespace -of the host, meaning that they can listen on (privileged) -ports. However, they cannot change the network configuration. You can -give a container its own network as follows: - -<programlisting> -containers.database = - { privateNetwork = true; - hostAddress = "192.168.100.10"; - localAddress = "192.168.100.11"; - }; -</programlisting> - -This gives the container a private virtual Ethernet interface with IP -address <literal>192.168.100.11</literal>, which is hooked up to a -virtual Ethernet interface on the host with IP address -<literal>192.168.100.10</literal>. (See the next section for details -on container networking.)</para> - -<para>To disable the container, just remove it from -<filename>configuration.nix</filename> and run <literal>nixos-rebuild -switch</literal>. Note that this will not delete the root directory of -the container in <literal>/var/lib/containers</literal>.</para> - -</section> - - -<section><title>Networking</title> - -<para>When you create a container using <literal>nixos-container -create</literal>, it gets it own private IPv4 address in the range -<literal>10.233.0.0/16</literal>. You can get the container’s IPv4 -address as follows: - -<screen> -$ nixos-container show-ip foo -10.233.4.2 - -$ ping -c1 10.233.4.2 -64 bytes from 10.233.4.2: icmp_seq=1 ttl=64 time=0.106 ms -</screen> - -</para> - -<para>Networking is implemented using a pair of virtual Ethernet -devices. The network interface in the container is called -<literal>eth0</literal>, while the matching interface in the host is -called <literal>ve-<replaceable>container-name</replaceable></literal> -(e.g., <literal>ve-foo</literal>). The container has its own network -namespace and the <literal>CAP_NET_ADMIN</literal> capability, so it -can perform arbitrary network configuration such as setting up -firewall rules, without affecting or having access to the host’s -network.</para> - -<para>By default, containers cannot talk to the outside network. If -you want that, you should set up Network Address Translation (NAT) -rules on the host to rewrite container traffic to use your external -IP address. This can be accomplished using the following configuration -on the host: - -<programlisting> -networking.nat.enable = true; -networking.nat.internalInterfaces = ["ve-+"]; -networking.nat.externalInterface = "eth0"; -</programlisting> -where <literal>eth0</literal> should be replaced with the desired -external interface. Note that <literal>ve-+</literal> is a wildcard -that matches all container interfaces.</para> - -</section> - - -</chapter> - |