3
0
Fork 0
forked from mirrors/nixpkgs
nixpkgs/nixos/doc/manual/from_md/administration/imperative-containers.section.xml
adisbladis f535d6f45e nixos-container: Use new configuration & state directories
We need to move NixOS containers somewhere else so these don't clash
with Podman, Skopeo & other container software in the libpod &
cri-o/cri-u/libcontainer ecosystems.

The state directory move is not strictly a requirement but is good for
consistency.
2022-04-27 18:35:08 +12:00

133 lines
4.7 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" xml:id="sec-imperative-containers">
<title>Imperative Container Management</title>
<para>
Well 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 containers root directory in
<literal>/var/lib/nixos-containers/foo</literal> and a small
configuration file in
<literal>/etc/nixos-containers/foo.conf</literal>. It also builds
the containers 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 = [&quot;ssh-dss AAAAB3N…&quot;];
'
</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 = &quot;foo@example.org&quot;;
networking.firewall.allowedTCPPorts = [ 80 ];
'
# curl http://$(nixos-container show-ip foo)/
&lt;!DOCTYPE HTML PUBLIC &quot;-//W3C//DTD HTML 3.2 Final//EN&quot;&gt;
</programlisting>
<para>
However, note that this will overwrite the containers
<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 containers service unit. To
destroy a container, including its file system, do
</para>
<programlisting>
# nixos-container destroy foo
</programlisting>
</section>