nixos/doc/manual/administration/imperative-containers.section.md

   1 # Imperative Container Management {#sec-imperative-containers}
   2
   3 We'll cover imperative container management using `nixos-container`
   4 first. Be aware that container management is currently only possible as
   5 `root`.
   6
   7 You create a container with identifier `foo` as follows:
   8
   9 ```ShellSession
  10 # nixos-container create foo
  11 ```
  12
  13 This creates the container's root directory in `/var/lib/nixos-containers/foo`
  14 and a small configuration file in `/etc/nixos-containers/foo.conf`. It also
  15 builds the container's initial system configuration and stores it in
  16 `/nix/var/nix/profiles/per-container/foo/system`. You can modify the
  17 initial configuration of the container on the command line. For
  18 instance, to create a container that has `sshd` running, with the given
  19 public key for `root`:
  20
  21 ```ShellSession
  22 # nixos-container create foo --config '
  23   services.openssh.enable = true;
  24   users.users.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];
  25 '
  26 ```
  27
  28 By default the next free address in the `10.233.0.0/16` subnet will be
  29 chosen as container IP. This behavior can be altered by setting
  30 `--host-address` and `--local-address`:
  31
  32 ```ShellSession
  33 # nixos-container create test --config-file test-container.nix \
  34     --local-address 10.235.1.2 --host-address 10.235.1.1
  35 ```
  36
  37 Creating a container does not start it. To start the container, run:
  38
  39 ```ShellSession
  40 # nixos-container start foo
  41 ```
  42
  43 This command will return as soon as the container has booted and has
  44 reached `multi-user.target`. On the host, the container runs within a
  45 systemd unit called `container@container-name.service`. Thus, if
  46 something went wrong, you can get status info using `systemctl`:
  47
  48 ```ShellSession
  49 # systemctl status container@foo
  50 ```
  51
  52 If the container has started successfully, you can log in as root using
  53 the `root-login` operation:
  54
  55 ```ShellSession
  56 # nixos-container root-login foo
  57 [root@foo:~]#
  58 ```
  59
  60 Note that only root on the host can do this (since there is no
  61 authentication). You can also get a regular login prompt using the
  62 `login` operation, which is available to all users on the host:
  63
  64 ```ShellSession
  65 # nixos-container login foo
  66 foo login: alice
  67 Password: ***
  68 ```
  69
  70 With `nixos-container run`, you can execute arbitrary commands in the
  71 container:
  72
  73 ```ShellSession
  74 # nixos-container run foo -- uname -a
  75 Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
  76 ```
  77
  78 There are several ways to change the configuration of the container.
  79 First, on the host, you can edit
  80 `/var/lib/container/name/etc/nixos/configuration.nix`, and run
  81
  82 ```ShellSession
  83 # nixos-container update foo
  84 ```
  85
  86 This will build and activate the new configuration. You can also specify
  87 a new configuration on the command line:
  88
  89 ```ShellSession
  90 # nixos-container update foo --config '
  91   services.httpd.enable = true;
  92   services.httpd.adminAddr = "foo@example.org";
  93   networking.firewall.allowedTCPPorts = [ 80 ];
  94 '
  95
  96 # curl http://$(nixos-container show-ip foo)/
  97 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
  98 ```
  99
 100 However, note that this will overwrite the container's
 101 `/etc/nixos/configuration.nix`.
 102
 103 Alternatively, you can change the configuration from within the
 104 container itself by running `nixos-rebuild switch` inside the container.
 105 Note that the container by default does not have a copy of the NixOS
 106 channel, so you should run `nix-channel --update` first.
 107
 108 Containers can be stopped and started using `nixos-container
 109   stop` and `nixos-container start`, respectively, or by using
 110 `systemctl` on the container's service unit. To destroy a container,
 111 including its file system, do
 112
 113 ```ShellSession
 114 # nixos-container destroy foo
 115 ```