summary refs log tree commit diff
path: root/nixos/doc/manual/from_md/administration/declarative-containers.section.xml
diff options
context:
space:
mode:
Diffstat (limited to 'nixos/doc/manual/from_md/administration/declarative-containers.section.xml')
-rw-r--r--nixos/doc/manual/from_md/administration/declarative-containers.section.xml60
1 files changed, 60 insertions, 0 deletions
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 00000000000..7b35520d567
--- /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_10;
+      };
+  };
+</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 = &quot;192.168.100.10&quot;;
+  localAddress = &quot;192.168.100.11&quot;;
+};
+</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>