diff options
Diffstat (limited to 'nixos')
10 files changed, 455 insertions, 245 deletions
diff --git a/nixos/doc/manual/administration/container-networking.section.md b/nixos/doc/manual/administration/container-networking.section.md new file mode 100644 index 000000000000..0873768376cc --- /dev/null +++ b/nixos/doc/manual/administration/container-networking.section.md @@ -0,0 +1,44 @@ +# Container Networking {#sec-container-networking} + +When you create a container using `nixos-container create`, it gets it +own private IPv4 address in the range `10.233.0.0/16`. You can get the +container's IPv4 address as follows: + +```ShellSession +# 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 +``` + +Networking is implemented using a pair of virtual Ethernet devices. The +network interface in the container is called `eth0`, while the matching +interface in the host is called `ve-container-name` (e.g., `ve-foo`). +The container has its own network namespace and the `CAP_NET_ADMIN` +capability, so it can perform arbitrary network configuration such as +setting up firewall rules, without affecting or having access to the +host's network. + +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: + +```nix +networking.nat.enable = true; +networking.nat.internalInterfaces = ["ve-+"]; +networking.nat.externalInterface = "eth0"; +``` + +where `eth0` should be replaced with the desired external interface. +Note that `ve-+` is a wildcard that matches all container interfaces. + +If you are using Network Manager, you need to explicitly prevent it from +managing container interfaces: + +```nix +networking.networkmanager.unmanaged = [ "interface-name:ve-*" ]; +``` + +You may need to restart your system for the changes to take effect. diff --git a/nixos/doc/manual/administration/container-networking.xml b/nixos/doc/manual/administration/container-networking.xml deleted file mode 100644 index 42486f01fe8c..000000000000 --- a/nixos/doc/manual/administration/container-networking.xml +++ /dev/null @@ -1,59 +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-container-networking"> - <title>Container 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> -<prompt># </prompt>nixos-container show-ip foo -10.233.4.2 - -<prompt>$ </prompt>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> -<xref linkend="opt-networking.nat.enable"/> = true; -<xref linkend="opt-networking.nat.internalInterfaces"/> = ["ve-+"]; -<xref linkend="opt-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> - - <para> - If you are using Network Manager, you need to explicitly prevent it from - managing container interfaces: -<programlisting> -networking.networkmanager.unmanaged = [ "interface-name:ve-*" ]; -</programlisting> - </para> - - <para> - You may need to restart your system for the changes to take effect. - </para> -</section> diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml index 0d3355e56a58..8e0e300f367b 100644 --- a/nixos/doc/manual/administration/containers.xml +++ b/nixos/doc/manual/administration/containers.xml @@ -28,7 +28,7 @@ contrast, in the imperative approach, containers are configured and updated independently from the host system. </para> - <xi:include href="imperative-containers.xml" /> - <xi:include href="declarative-containers.xml" /> - <xi:include href="container-networking.xml" /> + <xi:include href="../from_md/administration/imperative-containers.section.xml" /> + <xi:include href="../from_md/administration/declarative-containers.section.xml" /> + <xi:include href="../from_md/administration/container-networking.section.xml" /> </chapter> diff --git a/nixos/doc/manual/administration/declarative-containers.section.md b/nixos/doc/manual/administration/declarative-containers.section.md new file mode 100644 index 000000000000..273672fc10ca --- /dev/null +++ b/nixos/doc/manual/administration/declarative-containers.section.md @@ -0,0 +1,48 @@ +# Declarative Container Specification {#sec-declarative-containers} + +You can also specify containers and their configuration in the host's +`configuration.nix`. For example, the following specifies that there +shall be a container named `database` running PostgreSQL: + +```nix +containers.database = + { config = + { config, pkgs, ... }: + { services.postgresql.enable = true; + services.postgresql.package = pkgs.postgresql_9_6; + }; + }; +``` + +If you run `nixos-rebuild switch`, the container will be built. If the +container was already running, it will be updated in place, without +rebooting. The container can be configured to start automatically by +setting `containers.database.autoStart = true` in its configuration. + +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: + +```nix +containers.database = { + privateNetwork = true; + hostAddress = "192.168.100.10"; + localAddress = "192.168.100.11"; +}; +``` + +This gives the container a private virtual Ethernet interface with IP +address `192.168.100.11`, which is hooked up to a virtual Ethernet +interface on the host with IP address `192.168.100.10`. (See the next +section for details on container networking.) + +To disable the container, just remove it from `configuration.nix` and +run `nixos-rebuild + switch`. Note that this will not delete the root directory of the +container in `/var/lib/containers`. Containers can be destroyed using +the imperative method: `nixos-container destroy foo`. + +Declarative containers can be started and stopped using the +corresponding systemd service, e.g. +`systemctl start container@database`. diff --git a/nixos/doc/manual/administration/declarative-containers.xml b/nixos/doc/manual/administration/declarative-containers.xml deleted file mode 100644 index d03dbc4d7055..000000000000 --- a/nixos/doc/manual/administration/declarative-containers.xml +++ /dev/null @@ -1,60 +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-declarative-containers"> - <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, ... }: - { <xref linkend="opt-services.postgresql.enable"/> = true; - <xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_9_6; - }; - }; -</programlisting> - If you run <literal>nixos-rebuild switch</literal>, the container will be - built. If the container was already running, it will be updated in place, - without rebooting. The container can be configured to start automatically by - setting <literal>containers.database.autoStart = true</literal> in its - configuration. - </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 = { - <link linkend="opt-containers._name_.privateNetwork">privateNetwork</link> = true; - <link linkend="opt-containers._name_.hostAddress">hostAddress</link> = "192.168.100.10"; - <link linkend="opt-containers._name_.localAddress">localAddress</link> = "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>. Containers can be - destroyed using the imperative method: <literal>nixos-container destroy - foo</literal>. - </para> - - <para> - Declarative containers can be started and stopped using the corresponding - systemd service, e.g. <literal>systemctl start container@database</literal>. - </para> -</section> diff --git a/nixos/doc/manual/administration/imperative-containers.section.md b/nixos/doc/manual/administration/imperative-containers.section.md new file mode 100644 index 000000000000..05196bf5d819 --- /dev/null +++ b/nixos/doc/manual/administration/imperative-containers.section.md @@ -0,0 +1,115 @@ +# Imperative Container Management {#sec-imperative-containers} + +We'll cover imperative container management using `nixos-container` +first. Be aware that container management is currently only possible as +`root`. + +You create a container with identifier `foo` as follows: + +```ShellSession +# nixos-container create foo +``` + +This creates the container's root directory in `/var/lib/containers/foo` +and a small configuration file in `/etc/containers/foo.conf`. It also +builds the container's initial system configuration and stores it in +`/nix/var/nix/profiles/per-container/foo/system`. You can modify the +initial configuration of the container on the command line. For +instance, to create a container that has `sshd` running, with the given +public key for `root`: + +```ShellSession +# nixos-container create foo --config ' + services.openssh.enable = true; + users.users.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"]; +' +``` + +By default the next free address in the `10.233.0.0/16` subnet will be +chosen as container IP. This behavior can be altered by setting +`--host-address` and `--local-address`: + +```ShellSession +# nixos-container create test --config-file test-container.nix \ + --local-address 10.235.1.2 --host-address 10.235.1.1 +``` + +Creating a container does not start it. To start the container, run: + +```ShellSession +# nixos-container start foo +``` + +This command will return as soon as the container has booted and has +reached `multi-user.target`. On the host, the container runs within a +systemd unit called `container@container-name.service`. Thus, if +something went wrong, you can get status info using `systemctl`: + +```ShellSession +# systemctl status container@foo +``` + +If the container has started successfully, you can log in as root using +the `root-login` operation: + +```ShellSession +# nixos-container root-login foo +[root@foo:~]# +``` + +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 +`login` operation, which is available to all users on the host: + +```ShellSession +# nixos-container login foo +foo login: alice +Password: *** +``` + +With `nixos-container run`, you can execute arbitrary commands in the +container: + +```ShellSession +# 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 +``` + +There are several ways to change the configuration of the container. +First, on the host, you can edit +`/var/lib/container/name/etc/nixos/configuration.nix`, and run + +```ShellSession +# nixos-container update foo +``` + +This will build and activate the new configuration. You can also specify +a new configuration on the command line: + +```ShellSession +# nixos-container update foo --config ' + services.httpd.enable = true; + services.httpd.adminAddr = "foo@example.org"; + networking.firewall.allowedTCPPorts = [ 80 ]; +' + +# curl http://$(nixos-container show-ip foo)/ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">… +``` + +However, note that this will overwrite the container's +`/etc/nixos/configuration.nix`. + +Alternatively, you can change the configuration from within the +container itself by running `nixos-rebuild switch` inside the container. +Note that the container by default does not have a copy of the NixOS +channel, so you should run `nix-channel --update` first. + +Containers can be stopped and started using `nixos-container + stop` and `nixos-container start`, respectively, or by using +`systemctl` on the container's service unit. To destroy a container, +including its file system, do + +```ShellSession +# nixos-container destroy foo +``` diff --git a/nixos/doc/manual/administration/imperative-containers.xml b/nixos/doc/manual/administration/imperative-containers.xml deleted file mode 100644 index bc19acf9f690..000000000000 --- a/nixos/doc/manual/administration/imperative-containers.xml +++ /dev/null @@ -1,123 +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-imperative-containers"> - <title>Imperative Container Management</title> - - <para> - We’ll cover imperative container management using - <command>nixos-container</command> first. Be aware that container management - is currently only possible as <literal>root</literal>. - </para> - - <para> - You create a container with identifier <literal>foo</literal> as follows: -<screen> -<prompt># </prompt>nixos-container create <replaceable>foo</replaceable> -</screen> - This creates the container’s root directory in - <filename>/var/lib/containers/<replaceable>foo</replaceable></filename> and a small configuration file - in <filename>/etc/containers/<replaceable>foo</replaceable>.conf</filename>. It also builds the - container’s initial system configuration and stores it in - <filename>/nix/var/nix/profiles/per-container/<replaceable>foo</replaceable>/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> -<prompt># </prompt>nixos-container create <replaceable>foo</replaceable> --config ' - <xref linkend="opt-services.openssh.enable"/> = true; - <link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"]; -' -</screen> - By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen - as container IP. This behavior can be altered by setting <literal>--host-address</literal> and - <literal>--local-address</literal>: -<screen> -<prompt># </prompt>nixos-container create test --config-file test-container.nix \ - --local-address 10.235.1.2 --host-address 10.235.1.1 -</screen> - </para> - - <para> - Creating a container does not start it. To start the container, run: -<screen> -<prompt># </prompt>nixos-container start <replaceable>foo</replaceable> -</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> -<prompt># </prompt>systemctl status container@<replaceable>foo</replaceable> -</screen> - </para> - - <para> - If the container has started successfully, you can log in as root using the - <command>root-login</command> operation: -<screen> -<prompt># </prompt>nixos-container root-login <replaceable>foo</replaceable> -<prompt>[root@foo:~]#</prompt> -</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> -<prompt># </prompt>nixos-container login <replaceable>foo</replaceable> -foo login: alice -Password: *** -</screen> - With <command>nixos-container run</command>, you can execute arbitrary - commands in the container: -<screen> -<prompt># </prompt>nixos-container run <replaceable>foo</replaceable> -- 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> -<prompt># </prompt>nixos-container update <replaceable>foo</replaceable> -</screen> - This will build and activate the new configuration. You can also specify a - new configuration on the command line: -<screen> -<prompt># </prompt>nixos-container update <replaceable>foo</replaceable> --config ' - <xref linkend="opt-services.httpd.enable"/> = true; - <xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org"; - <xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ]; -' - -<prompt># </prompt>curl http://$(nixos-container show-ip <replaceable>foo</replaceable>)/ -<!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> -<prompt># </prompt>nixos-container destroy <replaceable>foo</replaceable> -</screen> - </para> -</section> diff --git a/nixos/doc/manual/from_md/administration/container-networking.section.xml b/nixos/doc/manual/from_md/administration/container-networking.section.xml new file mode 100644 index 000000000000..788a2b7b0acb --- /dev/null +++ b/nixos/doc/manual/from_md/administration/container-networking.section.xml @@ -0,0 +1,54 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-container-networking"> + <title>Container 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: + </para> + <programlisting> +# 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 +</programlisting> + <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-container-name</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: + </para> + <programlisting language="bash"> +networking.nat.enable = true; +networking.nat.internalInterfaces = ["ve-+"]; +networking.nat.externalInterface = "eth0"; +</programlisting> + <para> + 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> + <para> + If you are using Network Manager, you need to explicitly prevent it + from managing container interfaces: + </para> + <programlisting language="bash"> +networking.networkmanager.unmanaged = [ "interface-name:ve-*" ]; +</programlisting> + <para> + You may need to restart your system for the changes to take effect. + </para> +</section> diff --git a/nixos/doc/manual/from_md/administration/declarative-containers.section.xml b/nixos/doc/manual/from_md/administration/declarative-containers.section.xml new file mode 100644 index 000000000000..a918314a2723 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/declarative-containers.section.xml @@ -0,0 +1,60 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-declarative-containers"> + <title>Declarative Container Specification</title> + <para> + You can also specify containers and their configuration in the + host’s <literal>configuration.nix</literal>. For example, the + following specifies that there shall be a container named + <literal>database</literal> running PostgreSQL: + </para> + <programlisting language="bash"> +containers.database = + { config = + { config, pkgs, ... }: + { services.postgresql.enable = true; + services.postgresql.package = pkgs.postgresql_9_6; + }; + }; +</programlisting> + <para> + If you run <literal>nixos-rebuild switch</literal>, the container + will be built. If the container was already running, it will be + updated in place, without rebooting. The container can be configured + to start automatically by setting + <literal>containers.database.autoStart = true</literal> in its + configuration. + </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: + </para> + <programlisting language="bash"> +containers.database = { + privateNetwork = true; + hostAddress = "192.168.100.10"; + localAddress = "192.168.100.11"; +}; +</programlisting> + <para> + 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 + <literal>configuration.nix</literal> 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>. Containers can be destroyed + using the imperative method: + <literal>nixos-container destroy foo</literal>. + </para> + <para> + Declarative containers can be started and stopped using the + corresponding systemd service, e.g. + <literal>systemctl start container@database</literal>. + </para> +</section> diff --git a/nixos/doc/manual/from_md/administration/imperative-containers.section.xml b/nixos/doc/manual/from_md/administration/imperative-containers.section.xml new file mode 100644 index 000000000000..59ecfdee5af0 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/imperative-containers.section.xml @@ -0,0 +1,131 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-imperative-containers"> + <title>Imperative Container Management</title> + <para> + We’ll cover imperative container management using + <literal>nixos-container</literal> first. Be aware that container + management is currently only possible as <literal>root</literal>. + </para> + <para> + You create a container with identifier <literal>foo</literal> as + follows: + </para> + <programlisting> +# nixos-container create foo +</programlisting> + <para> + This creates the container’s root directory in + <literal>/var/lib/containers/foo</literal> and a small configuration + file in <literal>/etc/containers/foo.conf</literal>. It also builds + the container’s initial system configuration and stores it in + <literal>/nix/var/nix/profiles/per-container/foo/system</literal>. + You can modify the initial configuration of the container on the + command line. For instance, to create a container that has + <literal>sshd</literal> running, with the given public key for + <literal>root</literal>: + </para> + <programlisting> +# nixos-container create foo --config ' + services.openssh.enable = true; + users.users.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"]; +' +</programlisting> + <para> + By default the next free address in the + <literal>10.233.0.0/16</literal> subnet will be chosen as container + IP. This behavior can be altered by setting + <literal>--host-address</literal> and + <literal>--local-address</literal>: + </para> + <programlisting> +# nixos-container create test --config-file test-container.nix \ + --local-address 10.235.1.2 --host-address 10.235.1.1 +</programlisting> + <para> + Creating a container does not start it. To start the container, run: + </para> + <programlisting> +# nixos-container start foo +</programlisting> + <para> + 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@container-name.service</literal>. Thus, if + something went wrong, you can get status info using + <literal>systemctl</literal>: + </para> + <programlisting> +# systemctl status container@foo +</programlisting> + <para> + If the container has started successfully, you can log in as root + using the <literal>root-login</literal> operation: + </para> + <programlisting> +# nixos-container root-login foo +[root@foo:~]# +</programlisting> + <para> + 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 + <literal>login</literal> operation, which is available to all users + on the host: + </para> + <programlisting> +# nixos-container login foo +foo login: alice +Password: *** +</programlisting> + <para> + With <literal>nixos-container run</literal>, you can execute + arbitrary commands in the container: + </para> + <programlisting> +# 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 +</programlisting> + <para> + There are several ways to change the configuration of the container. + First, on the host, you can edit + <literal>/var/lib/container/name/etc/nixos/configuration.nix</literal>, + and run + </para> + <programlisting> +# nixos-container update foo +</programlisting> + <para> + This will build and activate the new configuration. You can also + specify a new configuration on the command line: + </para> + <programlisting> +# nixos-container update foo --config ' + services.httpd.enable = true; + services.httpd.adminAddr = "foo@example.org"; + networking.firewall.allowedTCPPorts = [ 80 ]; +' + +# curl http://$(nixos-container show-ip foo)/ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">… +</programlisting> + <para> + However, note that this will overwrite the container’s + <literal>/etc/nixos/configuration.nix</literal>. + </para> + <para> + Alternatively, you can change the configuration from within the + container itself by running <literal>nixos-rebuild switch</literal> + inside the container. Note that the container by default does not + have a copy of the NixOS channel, so you should run + <literal>nix-channel --update</literal> 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 + <literal>systemctl</literal> on the container’s service unit. To + destroy a container, including its file system, do + </para> + <programlisting> +# nixos-container destroy foo +</programlisting> +</section> |