From 0ac3e57ac1caa8249b966acda47ae3c08e5d31f1 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Fri, 2 Jul 2021 11:57:33 +0800 Subject: [PATCH 1/3] nixos: nixos/doc/manual/administration/imperative-containers.xml to CommonMark --- .../doc/manual/administration/containers.xml | 2 +- .../imperative-containers.section.md | 115 +++++++++++++++ .../administration/imperative-containers.xml | 123 ---------------- .../imperative-containers.section.xml | 131 ++++++++++++++++++ 4 files changed, 247 insertions(+), 124 deletions(-) create mode 100644 nixos/doc/manual/administration/imperative-containers.section.md delete mode 100644 nixos/doc/manual/administration/imperative-containers.xml create mode 100644 nixos/doc/manual/from_md/administration/imperative-containers.section.xml diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml index 0d3355e56a58..0ea6844146e8 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. - + 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)/ +… +``` + +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 @@ -
- Imperative Container Management - - - 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: - -# 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: - -# nixos-container create foo --config ' - = 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: - -# 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: - -# 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: - -# systemctl status container@foo - - - - - If the container has started successfully, you can log in as root using the - root-login operation: - -# 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: - -# nixos-container login foo -foo login: alice -Password: *** - - With nixos-container run, you can execute arbitrary - commands in the container: - -# 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 - -# nixos-container update foo - - This will build and activate the new configuration. You can also specify a - new configuration on the command line: - -# nixos-container update foo --config ' - = true; - = "foo@example.org"; - = [ 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 - -# nixos-container destroy foo - - -
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 @@ +
+ Imperative Container Management + + 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: + + +# 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: + + +# 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: + + +# 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: + + +# 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: + + +# systemctl status container@foo + + + If the container has started successfully, you can log in as root + using the root-login operation: + + +# 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: + + +# nixos-container login foo +foo login: alice +Password: *** + + + With nixos-container run, you can execute + arbitrary commands in the container: + + +# 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 + + +# nixos-container update foo + + + This will build and activate the new configuration. You can also + specify a new configuration on the command line: + + +# 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 + + +# nixos-container destroy foo + +
From 4f0efa8d7db269720192f6a4e3a2ffcbe35e30b3 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Fri, 2 Jul 2021 11:58:34 +0800 Subject: [PATCH 2/3] nixos: nixos/doc/manual/administration/declarative-containers.xml to CommonMark --- .../doc/manual/administration/containers.xml | 2 +- .../declarative-containers.section.md | 48 +++++++++++++++ .../administration/declarative-containers.xml | 60 ------------------- .../declarative-containers.section.xml | 60 +++++++++++++++++++ 4 files changed, 109 insertions(+), 61 deletions(-) create mode 100644 nixos/doc/manual/administration/declarative-containers.section.md delete mode 100644 nixos/doc/manual/administration/declarative-containers.xml create mode 100644 nixos/doc/manual/from_md/administration/declarative-containers.section.xml diff --git a/nixos/doc/manual/administration/containers.xml b/nixos/doc/manual/administration/containers.xml index 0ea6844146e8..f149ce7bbfe6 100644 --- a/nixos/doc/manual/administration/containers.xml +++ b/nixos/doc/manual/administration/containers.xml @@ -29,6 +29,6 @@ independently from the host system. - + 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 @@ -
- Declarative Container Specification - - - 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: - -containers.database = - { config = - { config, pkgs, ... }: - { = true; - = 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: - -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/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 @@ +
+ Declarative Container Specification + + 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: + + +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: + + +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. + +
From 9b52df304bb8e4f2ef0f00ad1cdabcc3243e7733 Mon Sep 17 00:00:00 2001 From: Bobby Rong Date: Fri, 2 Jul 2021 11:59:12 +0800 Subject: [PATCH 3/3] nixos: nixos/doc/manual/administration/container-networking.xml to CommonMark --- .../container-networking.section.md | 44 ++++++++++++++ .../administration/container-networking.xml | 59 ------------------- .../doc/manual/administration/containers.xml | 2 +- .../container-networking.section.xml | 54 +++++++++++++++++ 4 files changed, 99 insertions(+), 60 deletions(-) create mode 100644 nixos/doc/manual/administration/container-networking.section.md delete mode 100644 nixos/doc/manual/administration/container-networking.xml create mode 100644 nixos/doc/manual/from_md/administration/container-networking.section.xml 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 @@ -
- 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: - -# 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: - - = true; - = ["ve-+"]; - = "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: - -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/containers.xml b/nixos/doc/manual/administration/containers.xml index f149ce7bbfe6..8e0e300f367b 100644 --- a/nixos/doc/manual/administration/containers.xml +++ b/nixos/doc/manual/administration/containers.xml @@ -30,5 +30,5 @@ - + 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 @@ +
+ 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: + + +# 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: + + +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: + + +networking.networkmanager.unmanaged = [ "interface-name:ve-*" ]; + + + You may need to restart your system for the changes to take effect. + +