nixpkgs/nixos/doc/manual/administration/imperative-containers.xml
Graham Christensen 9622cd3b38
Revert "Revert "doc: Update section about imperative containers""
I fixed the problem.

This reverts commit 74df71bc8b.
2018-09-29 20:43:06 -04:00

117 lines
4.3 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<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>
Well 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>
# nixos-container create foo
</screen>
This creates the containers 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
containers 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 '
<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>
</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 successfully, 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>
To change the configuration of the container, 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 '
<xref linkend="opt-services.httpd.enable"/> = true;
<xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org";
<xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ];
'
# curl http://$(nixos-container show-ip foo)/
&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
</screen>
However, note that this will overwrite the containers
<filename>/etc/nixos/configuration.nix</filename>.
</para>
<para>
Note that in previous versions of NixOS (17.09 and earlier) one could also
use all nix-related commands (like <command>nixos-rebuild switch</command>)
from inside the container. However, since the release of Nix 2.0 this is not
supported anymore. Supporting Nix commands inside the container might be
possible again in future versions. See
<link xlink:href="https://github.com/NixOS/nixpkgs/issues/40355">the github
issue</link> for tracking progress on this issue.
</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 containers service unit. To
destroy a container, including its file system, do
<screen>
# nixos-container destroy foo
</screen>
</para>
</section>