diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix
index 913058746b35..264a8bcef27c 100644
--- a/nixos/doc/manual/default.nix
+++ b/nixos/doc/manual/default.nix
@@ -254,12 +254,17 @@ in rec {
# Generate the NixOS manpages.
manpages = runCommand "nixos-manpages"
{ inherit sources;
- nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin ];
+ nativeBuildInputs = [
+ buildPackages.libxml2.bin
+ buildPackages.libxslt.bin
+ buildPackages.installShellFiles
+ ];
allowedReferences = ["out"];
}
''
# Generate manpages.
- mkdir -p $out/share/man
+ mkdir -p $out/share/man/man8
+ installManPage ${./manpages}/*
xsltproc --nonet \
--maxdepth 6000 \
--param man.output.in.separate.dir 1 \
diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml
deleted file mode 100644
index fa7c8c0c6d79..000000000000
--- a/nixos/doc/manual/man-nixos-build-vms.xml
+++ /dev/null
@@ -1,138 +0,0 @@
-
-
- nixos-build-vms
- 8
- NixOS
-
-
-
- nixos-build-vms
- build a network of virtual machines from a network of NixOS configurations
-
-
-
- nixos-build-vms
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- name
- value
-
-
-
- network.nix
-
-
-
-
- Description
-
- This command builds a network of QEMU-KVM virtual machines of a Nix
- expression specifying a network of NixOS machines. The virtual network can
- be started by executing the bin/run-vms shell script
- that is generated by this command. By default, a result
- symlink is produced that points to the generated virtual network.
-
-
- A network Nix expression has the following structure:
-
-{
- test1 = {pkgs, config, ...}:
- {
- services.openssh.enable = true;
- nixpkgs.localSystem.system = "i686-linux";
- deployment.targetHost = "test1.example.net";
-
- # Other NixOS options
- };
-
- test2 = {pkgs, config, ...}:
- {
- services.openssh.enable = true;
- services.httpd.enable = true;
- environment.systemPackages = [ pkgs.lynx ];
- nixpkgs.localSystem.system = "x86_64-linux";
- deployment.targetHost = "test2.example.net";
-
- # Other NixOS options
- };
-}
-
- Each attribute in the expression represents a machine in the network (e.g.
- test1 and test2) referring to a
- function defining a NixOS configuration. In each NixOS configuration, two
- attributes have a special meaning. The
- deployment.targetHost specifies the address (domain name
- or IP address) of the system which is used by ssh to
- perform remote deployment operations. The
- nixpkgs.localSystem.system attribute can be used to
- specify an architecture for the target machine, such as
- i686-linux which builds a 32-bit NixOS configuration.
- Omitting this property will build the configuration for the same
- architecture as the host system.
-
-
-
- Options
-
- This command accepts the following options:
-
-
-
-
-
-
-
-
- Shows a trace of the output.
-
-
-
-
-
-
-
-
-
- Do not create a 'result' symlink.
-
-
-
-
-
- ,
-
-
-
- Shows the usage of this command to the user.
-
-
-
-
-
- namevalue
-
-
- Set the Nix configuration option
- name to value.
- This overrides settings in the Nix configuration file (see
- nix.conf5).
-
-
-
-
-
-
diff --git a/nixos/doc/manual/man-nixos-enter.xml b/nixos/doc/manual/man-nixos-enter.xml
deleted file mode 100644
index 41f0e6b97515..000000000000
--- a/nixos/doc/manual/man-nixos-enter.xml
+++ /dev/null
@@ -1,154 +0,0 @@
-
-
- nixos-enter
- 8
- NixOS
-
-
-
- nixos-enter
- run a command in a NixOS chroot environment
-
-
-
- nixos-enter
-
-
-
-
- root
-
-
-
-
-
-
- system
-
-
-
-
-
-
- shell-command
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- arguments
-
-
-
-
- Description
-
- This command runs a command in a NixOS chroot environment, that is, in a
- filesystem hierarchy previously prepared using
- nixos-install.
-
-
-
- Options
-
- This command accepts the following options:
-
-
-
-
-
-
-
-
- The path to the NixOS system you want to enter. It defaults to
- /mnt.
-
-
-
-
-
-
-
-
-
- The NixOS system configuration to use. It defaults to
- /nix/var/nix/profiles/system. You can enter a
- previous NixOS configuration by specifying a path such as
- /nix/var/nix/profiles/system-106-link.
-
-
-
-
-
-
-
-
-
-
-
-
- The bash command to execute.
-
-
-
-
-
-
-
-
-
- Suppresses all output from the activation script of the target system.
-
-
-
-
-
-
-
-
-
- Interpret the remaining arguments as the program name and arguments to be
- invoked. The program is not executed in a shell.
-
-
-
-
-
-
- Examples
-
- Start an interactive shell in the NixOS installation in
- /mnt:
-
-
-# nixos-enter --root /mnt
-
-
- Run a shell command:
-
-
-# nixos-enter -c 'ls -l /; cat /proc/mounts'
-
-
- Run a non-shell command:
-
-
-# nixos-enter -- cat /proc/mounts
-
-
-
diff --git a/nixos/doc/manual/man-nixos-generate-config.xml b/nixos/doc/manual/man-nixos-generate-config.xml
deleted file mode 100644
index 9ac3b918ff69..000000000000
--- a/nixos/doc/manual/man-nixos-generate-config.xml
+++ /dev/null
@@ -1,214 +0,0 @@
-
-
- nixos-generate-config
- 8
- NixOS
-
-
-
- nixos-generate-config
- generate NixOS configuration modules
-
-
-
- nixos-generate-config
-
-
-
-
-
-
-
-
- root
-
-
-
-
-
-
- dir
-
-
-
-
- Description
-
- This command writes two NixOS configuration modules:
-
-
-
-
-
-
-
- This module sets NixOS configuration options based on your current
- hardware configuration. In particular, it sets the
- option to reflect all currently mounted file
- systems, the option to reflect active swap
- devices, and the options to ensure that
- the initial ramdisk contains any kernel modules necessary for mounting
- the root file system.
-
-
- If this file already exists, it is overwritten. Thus, you should not
- modify it manually. Rather, you should include it from your
- /etc/nixos/configuration.nix, and re-run
- nixos-generate-config to update it whenever your
- hardware configuration changes.
-
-
-
-
-
-
-
-
-
- This is the main NixOS system configuration module. If it already
- exists, it’s left unchanged. Otherwise,
- nixos-generate-config will write a template for you
- to customise.
-
-
-
-
-
-
-
- Options
-
- This command accepts the following options:
-
-
-
-
-
-
-
-
- If this option is given, treat the directory
- root as the root of the file system. This
- means that configuration files will be written to
- root/etc/nixos, and that
- any file systems outside of root are ignored
- for the purpose of generating the option.
-
-
-
-
-
-
-
-
-
- If this option is given, write the configuration files to the directory
- dir instead of
- /etc/nixos.
-
-
-
-
-
-
-
-
-
- Overwrite /etc/nixos/configuration.nix if it already
- exists.
-
-
-
-
-
-
-
-
-
- Omit everything concerning file systems and swap devices from the
- hardware configuration.
-
-
-
-
-
-
-
-
-
- Don't generate configuration.nix or
- hardware-configuration.nix and print the hardware
- configuration to stdout only.
-
-
-
-
-
-
- Examples
-
- This command is typically used during NixOS installation to write initial
- configuration modules. For example, if you created and mounted the target
- file systems on /mnt and
- /mnt/boot, you would run:
-
-$ nixos-generate-config --root /mnt
-
- The resulting file
- /mnt/etc/nixos/hardware-configuration.nix might look
- like this:
-
-# Do not modify this file! It was generated by ‘nixos-generate-config’
-# and may be overwritten by future invocations. Please make changes
-# to /etc/nixos/configuration.nix instead.
-{ config, pkgs, ... }:
-
-{
- imports =
- [ <nixos/modules/installer/scan/not-detected.nix>
- ];
-
- boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];
- boot.kernelModules = [ "kvm-intel" ];
- boot.extraModulePackages = [ ];
-
- fileSystems."/" =
- { device = "/dev/disk/by-label/nixos";
- fsType = "ext3";
- options = [ "rw" "data=ordered" "relatime" ];
- };
-
- fileSystems."/boot" =
- { device = "/dev/sda1";
- fsType = "ext3";
- options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ];
- };
-
- swapDevices =
- [ { device = "/dev/sda2"; }
- ];
-
- nix.maxJobs = 8;
-}
-
- It will also create a basic
- /mnt/etc/nixos/configuration.nix, which you should edit
- to customise the logical configuration of your system. This file includes
- the result of the hardware scan as follows:
-
- imports = [ ./hardware-configuration.nix ];
-
-
-
- After installation, if your hardware configuration changes, you can run:
-
-$ nixos-generate-config
-
- to update /etc/nixos/hardware-configuration.nix. Your
- /etc/nixos/configuration.nix will
- not be overwritten.
-
-
-
diff --git a/nixos/doc/manual/man-nixos-install.xml b/nixos/doc/manual/man-nixos-install.xml
deleted file mode 100644
index eb6680b65677..000000000000
--- a/nixos/doc/manual/man-nixos-install.xml
+++ /dev/null
@@ -1,357 +0,0 @@
-
-
- nixos-install
- 8
- NixOS
-
-
-
- nixos-install
- install bootloader and NixOS
-
-
-
- nixos-install
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- path
-
-
-
-
-
-
- root
-
-
-
-
-
-
- path
-
-
-
- flake-uri
-
-
-
-
-
-
-
-
-
-
-
-
- channel
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- number
-
-
-
- number
-
-
-
- namevalue
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Description
-
- This command installs NixOS in the file system mounted on
- /mnt, based on the NixOS configuration specified in
- /mnt/etc/nixos/configuration.nix. It performs the
- following steps:
-
-
-
- It copies Nix and its dependencies to
- /mnt/nix/store.
-
-
-
-
- It runs Nix in /mnt to build the NixOS configuration
- specified in /mnt/etc/nixos/configuration.nix.
-
-
-
-
- It installs the current channel nixos in the target channel
- profile (unless is specified).
-
-
-
-
- It installs the GRUB boot loader on the device specified in the option
- (unless
- is specified), and generates a GRUB
- configuration file that boots into the NixOS configuration just
- installed.
-
-
-
-
- It prompts you for a password for the root account (unless
- is specified).
-
-
-
-
-
- This command is idempotent: if it is interrupted or fails due to a temporary
- problem (e.g. a network issue), you can safely re-run it.
-
-
-
- Options
-
- This command accepts the following options:
-
-
-
- /
-
- Increases the level of verbosity of diagnostic messages
- printed on standard error. For each Nix operation, the information
- printed on standard output is well-defined; any diagnostic
- information is printed on standard error, never on standard
- output.
- Please note that this option may be specified repeatedly.
-
-
-
-
-
-
-
-
- Defaults to /mnt. If this option is given, treat the
- directory root as the root of the NixOS
- installation.
-
-
-
-
-
-
-
-
-
- If this option is provided, nixos-install will install
- the specified closure rather than attempt to build one from
- /mnt/etc/nixos/configuration.nix.
-
-
- The closure must be an appropriately configured NixOS system, with boot
- loader and partition configuration that fits the target host. Such a
- closure is typically obtained with a command such as nix-build
- -I nixos-config=./configuration.nix '<nixpkgs/nixos>' -A system
- --no-out-link
-
-
-
-
-
- flake-uri#name
-
-
-
- Build the NixOS system from the specified flake.
- The flake must contain an output named
- nixosConfigurations.name.
-
-
-
-
-
-
-
-
-
- If this option is provided, do not copy the current
- nixos channel to the target host. Instead, use the
- specified derivation.
-
-
-
-
-
-
-
-
-
- Add a path to the Nix expression search path. This option may be given
- multiple times. See the NIX_PATH environment variable for information on
- the semantics of the Nix search path. Paths added through
- -I take precedence over NIX_PATH.
-
-
-
-
-
-
-
-
-
-
-
-
- Sets the maximum number of build jobs that Nix will perform in parallel
- to the specified number. The default is 1. A higher
- value is useful on SMP systems or to exploit I/O latency.
-
-
-
-
-
-
-
-
-
- Sets the value of the NIX_BUILD_CORES environment variable
- in the invocation of builders. Builders can use this variable at their
- discretion to control the maximum amount of parallelism. For instance, in
- Nixpkgs, if the derivation attribute
- enableParallelBuilding is set to
- true, the builder passes the
- flag to GNU Make. The
- value 0 means that the builder should use all
- available CPU cores in the system.
-
-
-
-
-
- namevalue
-
-
-
- Set the Nix configuration option name to
- value.
-
-
-
-
-
-
-
-
-
- Causes Nix to print out a stack trace in case of Nix expression
- evaluation errors.
-
-
-
-
-
-
-
-
-
- Causes Nix to continue building derivations as far as possible
- in the face of failed builds.
-
-
-
-
-
-
-
-
-
- Synonym for man nixos-install.
-
-
-
-
-
-
- Examples
-
- A typical NixOS installation is done by creating and mounting a file system
- on /mnt, generating a NixOS configuration in
- /mnt/etc/nixos/configuration.nix, and running
- nixos-install. For instance, if we want to install NixOS
- on an ext4 file system created in
- /dev/sda1:
-
-$ mkfs.ext4 /dev/sda1
-$ mount /dev/sda1 /mnt
-$ nixos-generate-config --root /mnt
-$ # edit /mnt/etc/nixos/configuration.nix
-$ nixos-install
-$ reboot
-
-
-
-
diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml
deleted file mode 100644
index b921386d0df0..000000000000
--- a/nixos/doc/manual/man-nixos-option.xml
+++ /dev/null
@@ -1,134 +0,0 @@
-
-
- nixos-option
- 8
- NixOS
-
-
-
- nixos-option
- inspect a NixOS configuration
-
-
-
- nixos-option
-
-
-
-
-
-
-
-
-
- path
-
-
-
- option.name
-
-
-
-
- Description
-
- This command evaluates the configuration specified in
- /etc/nixos/configuration.nix and returns the properties
- of the option name given as argument.
-
-
- When the option name is not an option, the command prints the list of
- attributes contained in the attribute set.
-
-
-
- Options
-
- This command accepts the following options:
-
-
-
-
-
-
-
- Print all the values at or below the specified path recursively.
-
-
-
-
-
- path
-
-
-
- This option is passed to the underlying
- nix-instantiate invocation.
-
-
-
-
-
-
- Environment
-
-
-
- NIXOS_CONFIG
-
-
-
- Path to the main NixOS configuration module. Defaults to
- /etc/nixos/configuration.nix.
-
-
-
-
-
-
- Examples
-
- Investigate option values:
-$ nixos-option boot.loader
-This attribute set contains:
-generationsDir
-grub
-initScript
-
-$ nixos-option boot.loader.grub.enable
-Value:
-true
-
-Default:
-true
-
-Description:
-Whether to enable the GNU GRUB boot loader.
-
-Declared by:
- "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix"
-
-Defined by:
- "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix"
-
-
-
-
- Bugs
-
- The author listed in the following section is wrong. If there is any other
- bug, please report to Nicolas Pierron.
-
-
-
- See also
-
-
- configuration.nix
- 5
-
-
-
-
diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml
deleted file mode 100644
index bf0f4aafa142..000000000000
--- a/nixos/doc/manual/man-nixos-rebuild.xml
+++ /dev/null
@@ -1,781 +0,0 @@
-
-
- nixos-rebuild
- 8
- NixOS
-
-
-
-
- nixos-rebuild
- reconfigure a NixOS machine
-
-
-
-
- nixos-rebuild
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- builder-spec
-
-
-
-
-
- flake-uri
-
-
-
-
-
-
-
- input-nameflake-uri
-
-
-
-
-
-
-
-
-
-
-
-
-
- name
-
-
-
-
-
-
-
-
-
-
-
- name
-
-
-
-
-
- host
-
-
-
- host
-
-
-
-
-
-
-
-
-
-
-
-
-
- NIX_PATH
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- number
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Description
-
-
- This command updates the system so that it corresponds to the
- configuration specified in
- /etc/nixos/configuration.nix or
- /etc/nixos/flake.nix. Thus, every time you
- modify the configuration or any other NixOS module, you must run
- nixos-rebuild to make the changes take
- effect. It builds the new system in
- /nix/store, runs its activation script, and
- stop and (re)starts any system services if needed. Please note that
- user services need to be started manually as they aren't detected
- by the activation script at the moment.
-
-
-
- This command has one required argument, which specifies the desired
- operation. It must be one of the following:
-
-
-
-
-
-
-
-
- Build and activate the new configuration, and make it the boot default.
- That is, the configuration is added to the GRUB boot menu as the default
- menu entry, so that subsequent reboots will boot the system into the new
- configuration. Previous configurations activated with
- nixos-rebuild switch or nixos-rebuild
- boot remain available in the GRUB menu.
-
-
- Note that if you are using specializations, running just
- nixos-rebuild switch will switch you back to the
- unspecialized, base system - in that case, you might want to use this
- instead:
-
-$ nixos-rebuild switch --specialisation your-specialisation-name
-
- This command will build all specialisations and make them bootable just
- like regular nixos-rebuild switch does - the only
- thing different is that it will switch to given specialisation instead
- of the base system; it can be also used to switch from the base system
- into a specialised one, or to switch between specialisations.
-
-
-
-
-
-
-
-
-
-
- Build the new configuration and make it the boot default (as with
- nixos-rebuild switch), but do not activate it. That
- is, the system continues to run the previous configuration until the
- next reboot.
-
-
-
-
-
-
-
-
-
-
- Build and activate the new configuration, but do not add it to the GRUB
- boot menu. Thus, if you reboot the system (or if it crashes), you will
- automatically revert to the default configuration (i.e. the
- configuration resulting from the last call to nixos-rebuild
- switch or nixos-rebuild boot).
-
-
- Note that if you are using specialisations, running just
- nixos-rebuild test will activate the unspecialised,
- base system - in that case, you might want to use this instead:
-
-$ nixos-rebuild test --specialisation your-specialisation-name
-
- This command can be also used to switch from the base system into a
- specialised one, or to switch between specialisations.
-
-
-
-
-
-
-
-
-
-
- Build the new configuration, but neither activate it nor add it to the
- GRUB boot menu. It leaves a symlink named result in
- the current directory, which points to the output of the top-level
- “system” derivation. This is essentially the same as doing
-
-$ nix-build /path/to/nixpkgs/nixos -A system
-
- Note that you do not need to be root to run
- nixos-rebuild build.
-
-
-
-
-
-
-
-
-
-
- Show what store paths would be built or downloaded by any of the
- operations above, but otherwise do nothing.
-
-
-
-
-
-
-
-
-
-
- Build the new configuration, but instead of activating it, show what
- changes would be performed by the activation (i.e. by
- nixos-rebuild test). For instance, this command will
- print which systemd units would be restarted. The list of changes is not
- guaranteed to be complete.
-
-
-
-
-
-
-
-
-
-
- Opens configuration.nix in the default editor.
-
-
-
-
-
-
-
-
-
-
- Build a script that starts a NixOS virtual machine with the desired
- configuration. It leaves a symlink result in the
- current directory that points (under
- result/bin/run-hostname-vm)
- at the script that starts the VM. Thus, to test a NixOS configuration in
- a virtual machine, you should do the following:
-
-$ nixos-rebuild build-vm
-$ ./result/bin/run-*-vm
-
-
-
-
- The VM is implemented using the qemu package. For
- best performance, you should load the kvm-intel or
- kvm-amd kernel modules to get hardware
- virtualisation.
-
-
-
- The VM mounts the Nix store of the host through the 9P file system. The
- host Nix store is read-only, so Nix commands that modify the Nix store
- will not work in the VM. This includes commands such as
- nixos-rebuild; to change the VM’s configuration,
- you must halt the VM and re-run the commands above.
-
-
-
- The VM has its own ext3 root file system, which is
- automatically created when the VM is first started, and is persistent
- across reboots of the VM. It is stored in
- ./hostname.qcow2.
-
-
-
-
-
-
-
-
-
-
-
- Like , but boots using the regular boot loader
- of your configuration (e.g., GRUB 1 or 2), rather than booting directly
- into the kernel and initial ramdisk of the system. This allows you to
- test whether the boot loader works correctly. However, it does not
- guarantee that your NixOS configuration will boot successfully on the
- host hardware (i.e., after running nixos-rebuild
- switch), because the hardware and boot loader configuration in
- the VM are different. The boot loader is installed on an automatically
- generated virtual disk containing a /boot
- partition.
-
-
-
-
-
-
-
-
- Options
-
- This command accepts the following options:
-
-
-
-
-
-
-
-
-
-
-
-
- Update the root user's channel named nixos
- before rebuilding the system.
-
-
- In addition to the nixos channel, the root
- user's channels which have a file named
- .update-on-nixos-rebuild in their base
- directory will also be updated.
-
-
- Passing updates all of the root
- user's channels.
-
-
-
-
-
-
-
-
-
-
- Causes the boot loader to be (re)installed on the device specified by the
- relevant configuration options.
-
-
-
-
-
-
-
-
-
-
- Normally, nixos-rebuild first builds the
- nixUnstable attribute in Nixpkgs, and uses the
- resulting instance of the Nix package manager to build the new system
- configuration. This is necessary if the NixOS modules use features not
- provided by the currently installed version of Nix. This option disables
- building a new Nix.
-
-
-
-
-
-
-
-
-
-
- Equivalent to . This option is
- useful if you call nixos-rebuild frequently
- (e.g. if you’re hacking on a NixOS module).
-
-
-
-
-
-
-
-
-
-
- Instead of building a new configuration as specified by
- /etc/nixos/configuration.nix, roll back to the
- previous configuration. (The previous configuration is defined as the one
- before the “current” generation of the Nix profile
- /nix/var/nix/profiles/system.)
-
-
-
-
-
-
- builder-spec
-
-
-
- Allow ad-hoc remote builders for building the new system. This requires
- the user executing nixos-rebuild (usually root) to be
- configured as a trusted user in the Nix daemon. This can be achieved by
- using the nix.settings.trusted-users NixOS option. Examples
- values for that option are described in the Remote builds
- chapter in the Nix manual, (i.e. --builders
- "ssh://bigbrother x86_64-linux"). By specifying an empty string
- existing builders specified in /etc/nix/machines can
- be ignored: --builders "" for example when they are
- not reachable due to network connectivity.
-
-
-
-
-
-
-
-
-
-
-
-
-
- Instead of using the Nix profile
- /nix/var/nix/profiles/system to keep track of the
- current and previous system configurations, use
- /nix/var/nix/profiles/system-profiles/name.
- When you use GRUB 2, for every system profile created with this flag,
- NixOS will create a submenu named “NixOS - Profile
- 'name'” in GRUB’s boot menu, containing
- the current and previous configurations of this profile.
-
-
- For instance, if you want to test a configuration file named
- test.nix without affecting the default system
- profile, you would do:
-
-$ nixos-rebuild switch -p test -I nixos-config=./test.nix
-
- The new configuration will appear in the GRUB 2 submenu “NixOS -
- Profile 'test'”.
-
-
-
-
-
-
-
-
-
-
-
-
-
- Activates given specialisation; when not specified, switching and testing
- will activate the base, unspecialised system.
-
-
-
-
-
-
-
-
-
-
- Instead of building the new configuration locally, use the specified host
- to perform the build. The host needs to be accessible with ssh, and must
- be able to perform Nix builds. If the option
- is not set, the build will be copied back
- to the local machine when done.
-
-
- Note that, if is not specified, Nix will
- be built both locally and remotely. This is because the configuration
- will always be evaluated locally even though the building might be
- performed remotely.
-
-
- You can include a remote user name in the host name
- (user@host). You can also set ssh options by
- defining the NIX_SSHOPTS environment variable.
-
-
-
-
-
-
-
-
-
-
- Specifies the NixOS target host. By setting this to something other than
- an empty string, the system activation will happen
- on the remote host instead of the local machine. The remote host needs to
- be accessible over ssh, and for the commands ,
- and you need root access.
-
-
-
- If is not explicitly specified or empty,
- building will take place locally.
-
-
-
- You can include a remote user name in the host name
- (user@host). You can also set ssh options by
- defining the NIX_SSHOPTS environment variable.
-
-
-
- Note that nixos-rebuild honors the
- nixpkgs.crossSystem setting of the given configuration
- but disregards the true architecture of the target host. Hence the
- nixpkgs.crossSystem setting has to match the target
- platform or else activation will fail.
-
-
-
-
-
-
-
-
-
-
- When set, nixos-rebuild will add
- to each invocation of nix-copy-closure. This will only affect the
- behavior of nixos-rebuild if or
- is also set. This is useful when
- the target-host connection to cache.nixos.org is faster than the
- connection between hosts.
-
-
-
-
-
-
-
-
-
-
- When set, nixos-rebuild prefixes remote commands that run on
- the and
- systems with sudo. Setting this option allows
- deploying as a non-root user.
-
-
-
-
-
-
- flake-uri#name
-
-
-
- Build the NixOS system from the specified flake. It defaults to
- the directory containing the target of the symlink
- /etc/nixos/flake.nix, if it exists. The
- flake must contain an output named
- nixosConfigurations.name. If
- name is omitted, it default to the
- current host name.
-
-
-
-
-
-
-
-
-
-
- Do not imply if
- /etc/nixos/flake.nix exists. With this
- option, it is possible to build non-flake NixOS configurations
- even if the current NixOS systems uses flakes.
-
-
-
-
-
-
-
- In addition, nixos-rebuild accepts various Nix-related
- flags, including / , ,
- , ,
- , , and /
- . See the Nix manual for details.
-
-
-
-
- Environment
-
-
-
-
- NIXOS_CONFIG
-
-
-
- Path to the main NixOS configuration module. Defaults to
- /etc/nixos/configuration.nix.
-
-
-
-
-
-
- NIX_PATH
-
-
-
- A colon-separated list of directories used to look up Nix expressions enclosed in angle brackets (e.g <nixpkgs>). Example
-
- nixpkgs=./my-nixpkgs
-
-
-
-
-
-
-
- NIX_SSHOPTS
-
-
-
- Additional options to be passed to ssh on the command
- line.
-
-
-
-
-
-
-
- Files
-
-
-
-
-
- /etc/nixos/flake.nix
-
-
-
- If this file exists, then nixos-rebuild will
- use it as if the option was given. This
- file may be a symlink to a flake.nix in an
- actual flake; thus /etc/nixos need not be a
- flake.
-
-
-
-
-
-
- /run/current-system
-
-
-
- A symlink to the currently active system configuration in the Nix store.
-
-
-
-
-
-
- /nix/var/nix/profiles/system
-
-
-
- The Nix profile that contains the current and previous system
- configurations. Used to generate the GRUB boot menu.
-
-
-
-
-
-
-
-
- Bugs
-
- This command should be renamed to something more descriptive.
-
-
-
diff --git a/nixos/doc/manual/man-nixos-version.xml b/nixos/doc/manual/man-nixos-version.xml
deleted file mode 100644
index 507c5035ed8d..000000000000
--- a/nixos/doc/manual/man-nixos-version.xml
+++ /dev/null
@@ -1,158 +0,0 @@
-
-
- nixos-version
- 8
- NixOS
-
-
- nixos-version
- show the NixOS version
-
-
-
- nixos-version
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Description
-
- This command shows the version of the currently active NixOS configuration.
- For example:
-$ nixos-version
-16.03.1011.6317da4 (Emu)
-
- The version consists of the following elements:
-
-
-
- 16.03
-
-
-
- The NixOS release, indicating the year and month in which it was
- released (e.g. March 2016).
-
-
-
-
-
- 1011
-
-
-
- The number of commits in the Nixpkgs Git repository between the start of
- the release branch and the commit from which this version was built.
- This ensures that NixOS versions are monotonically increasing. It is
- git when the current NixOS configuration was built
- from a checkout of the Nixpkgs Git repository rather than from a NixOS
- channel.
-
-
-
-
-
- 6317da4
-
-
-
- The first 7 characters of the commit in the Nixpkgs Git repository from
- which this version was built.
-
-
-
-
-
- Emu
-
-
-
- The code name of the NixOS release. The first letter of the code name
- indicates that this is the N'th stable NixOS release; for example, Emu
- is the fifth release.
-
-
-
-
-
-
-
-
- Options
-
-
- This command accepts the following options:
-
-
-
-
-
-
-
-
-
-
-
-
-
- Show the full SHA1 hash of the Git commit from which this configuration
- was built, e.g.
-$ nixos-version --hash
-6317da40006f6bc2480c6781999c52d88dde2acf
-
-
-
-
-
-
-
-
-
-
-
- Show the configuration revision if available. This could be the full SHA1
- hash of the Git commit of the system flake, if you add
- { system.configurationRevision = self.rev or "dirty"; }
- to the modules array of your flake.nix system configuration e.g.
-$ nixos-version --configuration-revision
-aa314ebd1592f6cdd53cb5bba8bcae97d9323de8
-
-
-
-
-
-
-
-
-
-
-
- Print a JSON representation of the versions of NixOS and the
- top-level configuration flake.
-
-
-
-
-
-
-
-
-
diff --git a/nixos/doc/manual/man-pages.xml b/nixos/doc/manual/man-pages.xml
index 58f73521e94f..0186221bddce 100644
--- a/nixos/doc/manual/man-pages.xml
+++ b/nixos/doc/manual/man-pages.xml
@@ -15,11 +15,4 @@
-
-
-
-
-
-
-
diff --git a/nixos/doc/manual/manpages/README.md b/nixos/doc/manual/manpages/README.md
new file mode 100644
index 000000000000..ed2682e5332d
--- /dev/null
+++ b/nixos/doc/manual/manpages/README.md
@@ -0,0 +1,55 @@
+# NixOS manpages
+
+This is the collection of NixOS manpages, excluding `configuration.nix(5)`.
+
+Man pages are written in [`mdoc(7)` format](https://mandoc.bsd.lv/man/mdoc.7.html) and should be portable between mandoc and groff for rendering (though minor differences may occur, mandoc and groff seem to have slightly different spacing rules.)
+
+Being written in `mdoc` these manpages use semantic markup. This file provides a guideline on where to apply which of the semantic elements of `mdoc`.
+
+### Command lines and arguments
+
+In any manpage, commands, flags and arguments to the *current* executable should be marked according to their semantics. Commands, flags and arguments passed to *other* executables should not be marked like this and should instead be considered as code examples and marked with `Ql`.
+
+ - Use `Fl` to mark flag arguments, `Ar` for their arguments.
+ - Repeating arguments should be marked by adding ellipses (`...`).
+ - Use `Cm` to mark literal string arguments, e.g. the `boot` command argument passed to `nixos-rebuild`.
+ - Optional flags or arguments should be marked with `Op`. This includes optional repeating arguments.
+ - Required flags or arguments should not be marked.
+ - Mutually exclusive groups of arguments should be enclosed in curly brackets, preferrably created with `Bro`/`Brc` blocks.
+
+When an argument is used in an example it should be marked up with `Ar` again to differentiate it from a constant. For example, a command with a `--host name` flag that calls ssh to retrieve the host's local time would signify this thusly:
+```
+This will run
+.Ic ssh Ar name Ic time
+to retrieve the remote time.
+```
+
+### Paths, NixOS options, environment variables
+
+Constant paths should be marked with `Pa`, NixOS options with `Va`, and environment variables with `Ev`.
+
+Generated paths, e.g. `result/bin/run-hostname-vm` (where `hostname` is a variable or arguments) should be marked as `Ql` inline literals with their variable components marked appropriately.
+
+ - Taking `hostname` from an argument become `.Ql result/bin/run- Ns Ar hostname Ns -vm`
+ - Taking `hostname` from a variable otherwise defined becomes `.Ql result/bin/run- Ns Va hostname Ns -vm`
+
+### Code examples and other commands
+
+In free text names and complete invocations of other commands (e.g. `ssh` or `tar -xvf src.tar`) should be marked with `Ic`, fragments of command lines should be marked with `Ql`.
+
+Larger code blocks or those that cannot be shown inline should use indented literal display block markup for their contents, i.e.
+```
+.Bd -literal -offset indent
+...
+.Ed
+```
+Contents of code blocks may be marked up further, e.g. if they refer to arguments that will be subsituted into them:
+```
+.Bd -literal -offset indent
+{
+ options.hostname = "\c
+.Ar hostname Ns \c
+";
+}
+.Ed
+```
diff --git a/nixos/doc/manual/manpages/nixos-build-vms.8 b/nixos/doc/manual/manpages/nixos-build-vms.8
new file mode 100644
index 000000000000..abf06b5dd596
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-build-vms.8
@@ -0,0 +1,109 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-build-vms \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-build-vms 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-build-vms
+.Nd build a network of virtual machines from a network of NixOS configurations
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-build-vms
+.Op Fl -show-trace
+.Op Fl -no-out-link
+.Op Fl -help
+.Op Fl -option Ar name value
+.Pa network.nix
+.
+.
+.
+.Sh DESCRIPTION
+.
+This command builds a network of QEMU\-KVM virtual machines of a Nix expression
+specifying a network of NixOS machines. The virtual network can be started by
+executing the
+.Pa bin/run-vms
+shell script that is generated by this command. By default, a
+.Pa result
+symlink is produced that points to the generated virtual network.
+.
+.Pp
+A network Nix expression has the following structure:
+.Bd -literal -offset indent
+{
+ test1 = {pkgs, config, ...}:
+ {
+ services.openssh.enable = true;
+ nixpkgs.localSystem.system = "i686-linux";
+ deployment.targetHost = "test1.example.net";
+
+ # Other NixOS options
+ };
+
+ test2 = {pkgs, config, ...}:
+ {
+ services.openssh.enable = true;
+ services.httpd.enable = true;
+ environment.systemPackages = [ pkgs.lynx ];
+ nixpkgs.localSystem.system = "x86_64-linux";
+ deployment.targetHost = "test2.example.net";
+
+ # Other NixOS options
+ };
+}
+.Ed
+.
+.Pp
+Each attribute in the expression represents a machine in the network
+.Ns (e.g.
+.Va test1
+and
+.Va test2 Ns
+) referring to a function defining a NixOS configuration. In each NixOS
+configuration, two attributes have a special meaning. The
+.Va deployment.targetHost
+specifies the address (domain name or IP address) of the system which is used by
+.Ic ssh
+to perform remote deployment operations. The
+.Va nixpkgs.localSystem.system
+attribute can be used to specify an architecture for the target machine, such as
+.Ql i686-linux
+which builds a 32-bit NixOS configuration. Omitting this property will build the
+configuration for the same architecture as the host system.
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -show-trace
+Shows a trace of the output.
+.
+.It Fl -no-out-link
+Do not create a
+.Pa result
+symlink.
+.
+.It Fl h , -help
+Shows the usage of this command to the user.
+.
+.It Fl -option Ar name Va value
+Set the Nix configuration option
+.Va name
+to
+.Va value Ns
+\&. This overrides settings in the Nix configuration file (see
+.Xr nix.conf 5 Ns
+).
+.El
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-enter.8 b/nixos/doc/manual/manpages/nixos-enter.8
new file mode 100644
index 000000000000..bc8df31e5f2d
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-enter.8
@@ -0,0 +1,76 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-enter \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-enter 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-enter
+.Nd run a command in a NixOS chroot environment
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-enter
+.Op Fl -root Ar root
+.Op Fl -system Ar system
+.Op Fl -command | c Ar shell-command
+.Op Fl -silent
+.Op Fl -help
+.Op Fl - Ar arguments ...
+.
+.
+.
+.Sh DESCRIPTION
+This command runs a command in a NixOS chroot environment, that is, in a filesystem hierarchy previously prepared using
+.Xr nixos-install 8 .
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -root Ar root
+The path to the NixOS system you want to enter. It defaults to
+.Pa /mnt Ns
+\&.
+.It Fl -system Ar system
+The NixOS system configuration to use. It defaults to
+.Pa /nix/var/nix/profiles/system Ns
+\&. You can enter a previous NixOS configuration by specifying a path such as
+.Pa /nix/var/nix/profiles/system-106-link Ns
+\&.
+.
+.It Fl -command Ar shell-command , Fl c Ar shell-command
+The bash command to execute.
+.
+.It Fl -silent
+Suppresses all output from the activation script of the target system.
+.
+.It Fl -
+Interpret the remaining arguments as the program name and arguments to be invoked.
+The program is not executed in a shell.
+.El
+.
+.
+.
+.Sh EXAMPLES
+.Bl -tag -width indent
+.It Ic nixos-enter --root /mnt
+Start an interactive shell in the NixOS installation in
+.Pa /mnt Ns .
+.
+.It Ic nixos-enter -c 'ls -l /; cat /proc/mounts'
+Run a shell command.
+.
+.It Ic nixos-enter -- cat /proc/mounts
+Run a non-shell command.
+.El
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-generate-config.8 b/nixos/doc/manual/manpages/nixos-generate-config.8
new file mode 100644
index 000000000000..8b9bb4d42483
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-generate-config.8
@@ -0,0 +1,169 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-generate-config \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-generate-config 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-generate-config
+.Nd generate NixOS configuration modules
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-generate-config
+.Op Fl -force
+.Op Fl -root Ar root
+.Op Fl -dir Ar dir
+.
+.
+.
+.Sh DESCRIPTION
+This command writes two NixOS configuration modules:
+.Bl -tag -width indent
+.It Pa /etc/nixos/hardware-configuration.nix
+This module sets NixOS configuration options based on your current hardware
+configuration. In particular, it sets the
+.Va fileSystem
+option to reflect all currently mounted file systems, the
+.Va swapDevices
+option to reflect active swap devices, and the
+.Va boot.initrd.*
+options to ensure that the initial ramdisk contains any kernel modules necessary
+for mounting the root file system.
+.Pp
+If this file already exists, it is overwritten. Thus, you should not modify it
+manually. Rather, you should include it from your
+.Pa /etc/nixos/configuration.nix Ns
+, and re-run
+.Nm
+to update it whenever your hardware configuration changes.
+.
+.It Pa /etc/nixos/configuration.nix
+This is the main NixOS system configuration module. If it already exists, it’s
+left unchanged. Otherwise,
+.Nm
+will write a template for you to customise.
+.El
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -root Ar root
+If this option is given, treat the directory
+.Ar root
+as the root of the file system. This means that configuration files will be written to
+.Ql Ar root Ns /etc/nixos Ns
+, and that any file systems outside of
+.Ar root
+are ignored for the purpose of generating the
+.Va fileSystems
+option.
+.
+.It Fl -dir Ar dir
+If this option is given, write the configuration files to the directory
+.Ar dir
+instead of
+.Pa /etc/nixos Ns
+\&.
+.
+.It Fl -force
+Overwrite
+.Pa /etc/nixos/configuration.nix
+if it already exists.
+.
+.It Fl -no-filesystems
+Omit everything concerning file systems and swap devices from the hardware configuration.
+.
+.It Fl -show-hardware-config
+Don't generate
+.Pa configuration.nix
+or
+.Pa hardware-configuration.nix
+and print the hardware configuration to stdout only.
+.El
+.
+.
+.
+.Sh EXAMPLES
+This command is typically used during NixOS installation to write initial
+configuration modules. For example, if you created and mounted the target file
+systems on
+.Pa /mnt
+and
+.Pa /mnt/boot Ns
+, you would run:
+.Bd -literal -offset indent
+$ nixos-generate-config --root /mnt
+.Ed
+.
+.Pp
+The resulting file
+.Pa /mnt/etc/nixos/hardware-configuration.nix
+might look like this:
+.Bd -literal -offset indent
+# Do not modify this file! It was generated by 'nixos-generate-config'
+# and may be overwritten by future invocations. Please make changes
+# to /etc/nixos/configuration.nix instead.
+{ config, pkgs, ... }:
+
+{
+ imports =
+ [
+ ];
+
+ boot.initrd.availableKernelModules = [ "ehci_hcd" "ahci" ];
+ boot.kernelModules = [ "kvm-intel" ];
+ boot.extraModulePackages = [ ];
+
+ fileSystems."/" =
+ { device = "/dev/disk/by-label/nixos";
+ fsType = "ext3";
+ options = [ "rw" "data=ordered" "relatime" ];
+ };
+
+ fileSystems."/boot" =
+ { device = "/dev/sda1";
+ fsType = "ext3";
+ options = [ "rw" "errors=continue" "user_xattr" "acl" "barrier=1" "data=writeback" "relatime" ];
+ };
+
+ swapDevices =
+ [ { device = "/dev/sda2"; }
+ ];
+
+ nix.maxJobs = 8;
+}
+.Ed
+.
+.Pp
+It will also create a basic
+.Pa /mnt/etc/nixos/configuration.nix Ns
+, which you should edit to customise the logical configuration of your system. \
+This file includes the result of the hardware scan as follows:
+.Bd -literal -offset indent
+imports = [ ./hardware-configuration.nix ];
+.Ed
+.
+.Pp
+After installation, if your hardware configuration changes, you can run:
+.Bd -literal -offset indent
+$ nixos-generate-config
+.Ed
+.
+.Pp
+to update
+.Pa /etc/nixos/hardware-configuration.nix Ns
+\&. Your
+.Pa /etc/nixos/configuration.nix
+will
+.Em not
+be overwritten.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-install.8 b/nixos/doc/manual/manpages/nixos-install.8
new file mode 100644
index 000000000000..dc0a5da275d8
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-install.8
@@ -0,0 +1,195 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-install \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-install 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-install
+.Nd install bootloader and NixOS
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-install
+.Op Fl -verbose | v
+.Op Fl I Ar path
+.Op Fl -root Ar root
+.Op Fl -system Ar path
+.Op Fl -flake Ar flake-uri
+.Op Fl -impure
+.Op Fl -channel Ar channel
+.Op Fl -no-channel-copy
+.Op Fl -no-root-password | -no-root-passwd
+.Op Fl -no-bootloader
+.Op Fl -max-jobs | j Ar number
+.Op Fl -cores Ar number
+.Op Fl -option Ar name value
+.Op Fl -show-trace
+.Op Fl -keep-going
+.Op Fl -help
+.
+.
+.
+.Sh DESCRIPTION
+This command installs NixOS in the file system mounted on
+.Pa /mnt Ns
+, based on the NixOS configuration specified in
+.Pa /mnt/etc/nixos/configuration.nix Ns
+\&. It performs the following steps:
+.
+.Bl -enum
+.It
+It copies Nix and its dependencies to
+.Pa /mnt/nix/store Ns
+\&.
+.
+.It
+It runs Nix in
+.Pa /mnt
+to build the NixOS configuration specified in
+.Pa /mnt/etc/nixos/configuration.nix Ns
+\&.
+.
+.It
+It installs the current channel
+.Dq nixos
+in the target channel profile (unless
+.Fl -no-channel-copy
+is specified).
+.
+.It
+It installs the GRUB boot loader on the device specified in the option
+.Va boot.loader.grub.device
+(unless
+.Fl -no-bootloader
+is specified), and generates a GRUB configuration file that boots into the NixOS
+configuration just installed.
+.
+.It
+It prompts you for a password for the root account (unless
+.Fl -no-root-password
+is specified).
+.El
+.
+.Pp
+This command is idempotent: if it is interrupted or fails due to a temporary
+problem (e.g. a network issue), you can safely re-run it.
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -verbose , v
+Increases the level of verbosity of diagnostic messages printed on standard
+error. For each Nix operation, the information printed on standard output is
+well-defined; any diagnostic information is printed on standard error, never on
+standard output.
+.Pp
+Please note that this option may be specified repeatedly.
+.
+.It Fl -root Ar root
+Defaults to
+.Pa /mnt Ns
+\&. If this option is given, treat the directory
+.Ar root
+as the root of the NixOS installation.
+.
+.It Fl -system Ar path
+If this option is provided,
+.Nm
+will install the specified closure rather than attempt to build one from
+.Pa /mnt/etc/nixos/configuration.nix Ns
+\&.
+.Pp
+The closure must be an appropriately configured NixOS system, with boot loader
+and partition configuration that fits the target host. Such a closure is
+typically obtained with a command such as
+.Ic nix-build -I nixos-config=./configuration.nix '' -A system --no-out-link Ns
+\&.
+.
+.It Fl -flake Ar flake-uri Ns # Ns Ar name
+Build the NixOS system from the specified flake. The flake must contain an
+output named
+.Ql nixosConfigurations. Ns Ar name Ns
+\&.
+.
+.It Fl -channel Ar channel
+If this option is provided, do not copy the current
+.Dq nixos
+channel to the target host. Instead, use the specified derivation.
+.
+.It Fl I Ar Path
+Add a path to the Nix expression search path. This option may be given multiple
+times. See the
+.Ev NIX_PATH
+environment variable for information on the semantics of the Nix search path. Paths added through
+.Fl I
+take precedence over
+.Ev NIX_PATH Ns
+\&.
+.
+.It Fl -max-jobs , j Ar number
+Sets the maximum number of build jobs that Nix will perform in parallel to the
+specified number. The default is 1. A higher value is useful on SMP systems or
+to exploit I/O latency.
+.
+.It Fl -cores Ar N
+Sets the value of the
+.Ev NIX_BUILD_CORES
+environment variable in the invocation of builders. Builders can use this
+variable at their discretion to control the maximum amount of parallelism. For
+instance, in Nixpkgs, if the derivation attribute
+.Va enableParallelBuilding
+is set to true, the builder passes the
+.Fl j Ns Va N
+flag to GNU Make. The value 0 means that the builder should use all available CPU cores in the system.
+.
+.It Fl -option Ar name value
+Set the Nix configuration option
+.Ar name
+to
+.Ar value Ns
+\&.
+.
+.It Fl -show-trace
+Causes Nix to print out a stack trace in case of Nix expression evaluation errors.
+.
+.It Fl -keep-going
+Causes Nix to continue building derivations as far as possible in the face of failed builds.
+.
+.It Fl -help
+Synonym for
+.Ic man nixos-install Ns
+\&.
+.El
+.
+.
+.
+.Sh EXAMPLES
+A typical NixOS installation is done by creating and mounting a file system on
+.Pa /mnt Ns
+, generating a NixOS configuration in
+.Pa /mnt/etc/nixos/configuration.nix Ns
+, and running
+.Nm Ns
+\&. For instance, if we want to install NixOS on an ext4 file system created in
+.Pa /dev/sda1 Ns
+:
+.Bd -literal -offset indent
+$ mkfs.ext4 /dev/sda1
+$ mount /dev/sda1 /mnt
+$ nixos-generate-config --root /mnt
+$ # edit /mnt/etc/nixos/configuration.nix
+$ nixos-install
+$ reboot
+.Ed
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-option.8 b/nixos/doc/manual/manpages/nixos-option.8
new file mode 100644
index 000000000000..79cc113cfaf2
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-option.8
@@ -0,0 +1,93 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-option \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-option 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-option
+.Nd inspect a NixOS configuration
+.
+.
+.
+.Sh SYNOPSIS
+.Nm
+.Op Fl r | -recursive
+.Op Fl I Ar path
+.Ar option.name
+.
+.
+.
+.Sh DESCRIPTION
+This command evaluates the configuration specified in
+.Pa /etc/nixos/configuration.nix
+and returns the properties of the option name given as argument.
+.
+.Pp
+When the option name is not an option, the command prints the list of attributes
+contained in the attribute set.
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl r , -recursive
+Print all the values at or below the specified path recursively.
+.
+.It Fl I Ar path
+This option is passed to the underlying
+.Xr nix-instantiate 1
+invocation.
+.El
+.
+.
+.
+.Sh ENVIRONMENT
+.Bl -tag -width indent
+.It Ev NIXOS_CONFIG
+Path to the main NixOS configuration module. Defaults to
+.Pa /etc/nixos/configuration.nix Ns
+\&.
+.El
+.
+.
+.
+.Sh EXAMPLES
+Investigate option values:
+.Bd -literal -offset indent
+$ nixos-option boot.loader
+This attribute set contains:
+generationsDir
+grub
+initScript
+
+$ nixos-option boot.loader.grub.enable
+Value:
+true
+
+Default:
+true
+
+Description:
+Whether to enable the GNU GRUB boot loader.
+
+Declared by:
+ "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix"
+
+Defined by:
+ "/nix/var/nix/profiles/per-user/root/channels/nixos/nixpkgs/nixos/modules/system/boot/loader/grub/grub.nix"
+.Ed
+.
+.
+.
+.Sh SEE ALSO
+.Xr configuration.nix 5
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Nicolas Pierron
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-rebuild.8 b/nixos/doc/manual/manpages/nixos-rebuild.8
new file mode 100644
index 000000000000..8ff59d6da9cf
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-rebuild.8
@@ -0,0 +1,456 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-rebuild \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-rebuild 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-rebuild
+.Nd reconfigure a NixOS machine
+.
+.
+.
+.Sh SYNOPSIS
+.Nm
+.Bro
+.Cm switch | boot | test | build | dry-build | dry-activate | edit | build-vm | build-vm-with-bootloader
+.Brc
+.br
+.Op Fl -upgrade | -upgrade-all
+.Op Fl -install-bootloader
+.Op Fl -no-build-nix
+.Op Fl -fast
+.Op Fl -rollback
+.Op Fl -builders Ar builder-spec
+.br
+.Op Fl -flake Ar flake-uri
+.Op Fl -no-flake
+.Op Fl -override-input Ar input-name flake-uri
+.br
+.Op Fl -profile-name | p Ar name
+.Op Fl -specialisation | c Ar name
+.br
+.Op Fl -build-host Va host
+.Op Fl -target-host Va host
+.Op Fl -use-remote-sudo
+.br
+.Op Fl -show-trace
+.Op Fl I Va NIX_PATH
+.Op Fl -verbose | v
+.Op Fl -impure
+.Op Fl -max-jobs | j Va number
+.Op Fl -keep-failed | K
+.Op Fl -keep-going | k
+.
+.
+.
+.Sh DESCRIPTION
+This command updates the system so that it corresponds to the
+configuration specified in
+.Pa /etc/nixos/configuration.nix
+or
+.Pa /etc/nixos/flake.nix Ns
+\&. Thus, every time you modify the configuration or any other NixOS module, you
+must run
+.Nm
+to make the changes take effect. It builds the new system in
+.Pa /nix/store Ns
+, runs its activation script, and stop and (re)starts any system services if
+needed. Please note that user services need to be started manually as they
+aren't detected by the activation script at the moment.
+.
+.Pp
+This command has one required argument, which specifies the desired
+operation. It must be one of the following:
+.Bl -tag -width indent
+.It Cm switch
+Build and activate the new configuration, and make it the boot default. That
+is, the configuration is added to the GRUB boot menu as the default
+menu entry, so that subsequent reboots will boot the system into the new
+configuration. Previous configurations activated with
+.Ic nixos-rebuild switch
+or
+.Ic nixos-rebuild boot
+remain available in the GRUB menu.
+.Pp
+Note that if you are using specializations, running just
+.Ic nixos-rebuild switch
+will switch you back to the unspecialized, base system \(em in that case, you
+might want to use this instead:
+.Bd -literal -offset indent
+$ nixos-rebuild switch --specialisation your-specialisation-name
+.Ed
+.Pp
+This command will build all specialisations and make them bootable just
+like regular
+.Ic nixos-rebuild switch
+does \(em the only thing different is that it will switch to given
+specialisation instead of the base system; it can be also used to switch from
+the base system into a specialised one, or to switch between specialisations.
+.
+.It Cm boot
+Build the new configuration and make it the boot default (as with
+.Ic nixos-rebuild switch Ns
+), but do not activate it. That is, the system continues to run the previous
+configuration until the next reboot.
+.
+.It Cm test
+Build and activate the new configuration, but do not add it to the GRUB
+boot menu. Thus, if you reboot the system (or if it crashes), you will
+automatically revert to the default configuration (i.e. the
+configuration resulting from the last call to
+.Ic nixos-rebuild switch
+or
+.Ic nixos-rebuild boot Ns
+).
+.Pp
+Note that if you are using specialisations, running just
+.Ic nixos-rebuild test
+will activate the unspecialised, base system \(em in that case, you might want
+to use this instead:
+.Bd -literal -offset indent
+$ nixos-rebuild test --specialisation your-specialisation-name
+.Ed
+.Pp
+This command can be also used to switch from the base system into a
+specialised one, or to switch between specialisations.
+.
+.It Cm build
+Build the new configuration, but neither activate it nor add it to the
+GRUB boot menu. It leaves a symlink named
+.Pa result
+in the current directory, which points to the output of the top-level
+.Dq system
+derivation. This is essentially the same as doing
+.Bd -literal -offset indent
+$ nix-build /path/to/nixpkgs/nixos -A system
+.Ed
+.Pp
+Note that you do not need to be root to run
+.Ic nixos-rebuild build Ns
+\&.
+.
+.It Cm dry-build
+Show what store paths would be built or downloaded by any of the
+operations above, but otherwise do nothing.
+.
+.It Cm dry-activate
+Build the new configuration, but instead of activating it, show what
+changes would be performed by the activation (i.e. by
+.Ic nixos-rebuild test Ns
+). For instance, this command will print which systemd units would be restarted.
+The list of changes is not guaranteed to be complete.
+.
+.It Cm edit
+Opens
+.Pa configuration.nix
+in the default editor.
+.
+.It Cm build-vm
+Build a script that starts a NixOS virtual machine with the desired
+configuration. It leaves a symlink
+.Pa result
+in the current directory that points (under
+.Ql result/bin/run\- Ns Va hostname Ns \-vm Ns
+)
+at the script that starts the VM. Thus, to test a NixOS configuration in
+a virtual machine, you should do the following:
+.Bd -literal -offset indent
+$ nixos-rebuild build-vm
+$ ./result/bin/run-*-vm
+.Ed
+.Pp
+The VM is implemented using the
+.Ql qemu
+package. For best performance, you should load the
+.Ql kvm-intel
+or
+.Ql kvm-amd
+kernel modules to get hardware virtualisation.
+.Pp
+The VM mounts the Nix store of the host through the 9P file system. The
+host Nix store is read-only, so Nix commands that modify the Nix store
+will not work in the VM. This includes commands such as
+.Nm Ns
+; to change the VM’s configuration, you must halt the VM and re-run the commands
+above.
+.Pp
+The VM has its own ext3 root file system, which is automatically created when
+the VM is first started, and is persistent across reboots of the VM. It is
+stored in
+.Ql ./ Ns Va hostname Ns .qcow2 Ns
+\&.
+.\" The entire file system hierarchy of the host is available in
+.\" the VM under
+.\" .Pa /hostfs Ns
+.\" .
+.
+.It Cm build-vm-with-bootloader
+Like
+.Cm build-vm Ns
+, but boots using the regular boot loader of your configuration (e.g. GRUB 1 or
+2), rather than booting directly into the kernel and initial ramdisk of the
+system. This allows you to test whether the boot loader works correctly. \
+However, it does not guarantee that your NixOS configuration will boot
+successfully on the host hardware (i.e., after running
+.Ic nixos-rebuild switch Ns
+), because the hardware and boot loader configuration in the VM are different.
+The boot loader is installed on an automatically generated virtual disk
+containing a
+.Pa /boot
+partition.
+.El
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -upgrade , -upgrade-all
+Update the root user's channel named
+.Ql nixos
+before rebuilding the system.
+.Pp
+In addition to the
+.Ql nixos
+channel, the root user's channels which have a file named
+.Ql .update-on-nixos-rebuild
+in their base directory will also be updated.
+.Pp
+Passing
+.Fl -upgrade-all
+updates all of the root user's channels.
+.
+.It Fl -install-bootloader
+Causes the boot loader to be (re)installed on the device specified by the
+relevant configuration options.
+.
+.It Fl -no-build-nix
+Normally,
+.Nm
+first builds the
+.Ql nixUnstable
+attribute in Nixpkgs, and uses the resulting instance of the Nix package manager
+to build the new system configuration. This is necessary if the NixOS modules
+use features not provided by the currently installed version of Nix. This option
+disables building a new Nix.
+.
+.It Fl -fast
+Equivalent to
+.Fl -no-build-nix Ns
+\&. This option is useful if you call
+.Nm
+frequently (e.g. if you’re hacking on a NixOS module).
+.
+.It Fl -rollback
+Instead of building a new configuration as specified by
+.Pa /etc/nixos/configuration.nix Ns
+, roll back to the previous configuration. (The previous configuration is
+defined as the one before the “current” generation of the Nix profile
+.Pa /nix/var/nix/profiles/system Ns
+\&.)
+.
+.It Fl -builders Ar builder-spec
+Allow ad-hoc remote builders for building the new system. This requires
+the user executing
+.Nm
+(usually root) to be configured as a trusted user in the Nix daemon. This can be
+achieved by using the
+.Va nix.settings.trusted-users
+NixOS option. Examples values for that option are described in the
+.Dq Remote builds
+chapter in the Nix manual, (i.e.
+.Ql --builders \(dqssh://bigbrother x86_64-linux\(dq Ns
+). By specifying an empty string existing builders specified in
+.Pa /etc/nix/machines
+can be ignored:
+.Ql --builders \(dq\(dq
+for example when they are not reachable due to network connectivity.
+.
+.It Fl -profile-name Ar name , Fl p Ar name
+Instead of using the Nix profile
+.Pa /nix/var/nix/profiles/system
+to keep track of the current and previous system configurations, use
+.Pa /nix/var/nix/profiles/system-profiles/ Ns Va name Ns
+\&. When you use GRUB 2, for every system profile created with this flag, NixOS
+will create a submenu named
+.Dq NixOS - Profile Va name
+in GRUB’s boot menu, containing the current and previous configurations of this profile.
+.Pp
+For instance, if you want to test a configuration file named
+.Pa test.nix
+without affecting the default system profile, you would do:
+.Bd -literal -offset indent
+$ nixos-rebuild switch -p test -I nixos-config=./test.nix
+.Ed
+.Pp
+The new configuration will appear in the GRUB 2 submenu
+.Dq NixOS - Profile 'test' Ns
+\&.
+.
+.It Fl -specialisation Ar name , Fl c Ar name
+Activates given specialisation; when not specified, switching and testing
+will activate the base, unspecialised system.
+.
+.It Fl -build-host Ar host
+Instead of building the new configuration locally, use the specified host
+to perform the build. The host needs to be accessible with
+.Ic ssh Ns ,
+and must be able to perform Nix builds. If the option
+.Fl -target-host
+is not set, the build will be copied back to the local machine when done.
+.Pp
+Note that, if
+.Fl -no-build-nix
+is not specified, Nix will be built both locally and remotely. This is because
+the configuration will always be evaluated locally even though the building
+might be performed remotely.
+.Pp
+You can include a remote user name in the host name
+.Ns ( Va user@host Ns
+). You can also set ssh options by defining the
+.Ev NIX_SSHOPTS
+environment variable.
+.
+.It Fl -target-host Ar host
+Specifies the NixOS target host. By setting this to something other than an
+empty string, the system activation will happen on the remote host instead of
+the local machine. The remote host needs to be accessible over
+.Ic ssh Ns ,
+and for the commands
+.Cm switch Ns
+,
+.Cm boot
+and
+.Cm test
+you need root access.
+.Pp
+If
+.Fl -build-host
+is not explicitly specified or empty, building will take place locally.
+.Pp
+You can include a remote user name in the host name
+.Ns ( Va user@host Ns
+). You can also set ssh options by defining the
+.Ev NIX_SSHOPTS
+environment variable.
+.Pp
+Note that
+.Nm
+honors the
+.Va nixpkgs.crossSystem
+setting of the given configuration but disregards the true architecture of the
+target host. Hence the
+.Va nixpkgs.crossSystem
+setting has to match the target platform or else activation will fail.
+.
+.It Fl -use-substitutes
+When set, nixos-rebuild will add
+.Fl -use-substitutes
+to each invocation of nix-copy-closure. This will only affect the behavior of
+nixos-rebuild if
+.Fl -target-host
+or
+.Fl -build-host
+is also set. This is useful when the target-host connection to cache.nixos.org
+is faster than the connection between hosts.
+.
+.It Fl -use-remote-sudo
+When set, nixos-rebuild prefixes remote commands that run on the
+.Fl -build-host
+and
+.Fl -target-host
+systems with
+.Ic sudo Ns
+\&. Setting this option allows deploying as a non-root user.
+.
+.It Fl -flake Va flake-uri Ns Op Va #name
+Build the NixOS system from the specified flake. It defaults to the directory
+containing the target of the symlink
+.Pa /etc/nixos/flake.nix Ns
+, if it exists. The flake must contain an output named
+.Ql nixosConfigurations. Ns Va name Ns
+\&. If
+.Va name
+is omitted, it default to the current host name.
+.
+.It Fl -no-flake
+Do not imply
+.Fl -flake
+if
+.Pa /etc/nixos/flake.nix
+exists. With this option, it is possible to build non-flake NixOS configurations
+even if the current NixOS systems uses flakes.
+.El
+.Pp
+In addition,
+.Nm
+accepts various Nix-related flags, including
+.Fl -max-jobs Ns ,
+.Fl j Ns ,
+.Fl I Ns ,
+.Fl -show-trace Ns ,
+.Fl -keep-failed Ns ,
+.Fl -keep-going Ns ,
+.Fl -impure Ns ,
+.Fl -verbose Ns , and
+.Fl v Ns
+\&. See the Nix manual for details.
+.
+.
+.
+.Sh ENVIRONMENT
+.Bl -tag -width indent
+.It Ev NIXOS_CONFIG
+Path to the main NixOS configuration module. Defaults to
+.Pa /etc/nixos/configuration.nix Ns
+\&.
+.
+.It Ev NIX_PATH
+A colon-separated list of directories used to look up Nix expressions enclosed
+in angle brackets (e.g. ). Example:
+.Bd -literal -offset indent
+nixpkgs=./my-nixpkgs
+.Ed
+.
+.It Ev NIX_SSHOPTS
+Additional options to be passed to
+.Ic ssh
+on the command line.
+.El
+.
+.
+.
+.Sh FILES
+.Bl -tag -width indent
+.It Pa /etc/nixos/flake.nix
+If this file exists, then
+.Nm
+will use it as if the
+.Fl -flake
+option was given. This file may be a symlink to a
+.Pa flake.nix
+in an actual flake; thus
+.Pa /etc/nixos
+need not be a flake.
+.
+.It Pa /run/current-system
+A symlink to the currently active system configuration in the Nix store.
+.
+.It Pa /nix/var/nix/profiles/system
+The Nix profile that contains the current and previous system
+configurations. Used to generate the GRUB boot menu.
+.El
+.
+.
+.
+.Sh BUGS
+This command should be renamed to something more descriptive.
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors
diff --git a/nixos/doc/manual/manpages/nixos-version.8 b/nixos/doc/manual/manpages/nixos-version.8
new file mode 100644
index 000000000000..980ee8b1f49e
--- /dev/null
+++ b/nixos/doc/manual/manpages/nixos-version.8
@@ -0,0 +1,90 @@
+.Dd January 1, 1980
+.\" nixpkgs groff will use Nixpkgs as the OS in the title by default, taking it from
+.\" doc-default-operating-system. mandoc doesn't have this register set by default,
+.\" so we can use it as a groff/mandoc switch.
+.ie ddoc-default-operating-system .Dt nixos-version \&8 "NixOS System Manager's Manual"
+.el .Dt nixos-version 8
+.Os NixOS
+.Sh NAME
+.Nm nixos-version
+.Nd show the NixOS version
+.
+.
+.
+.Sh SYNOPSIS
+.Nm nixos-version
+.Op Fl -hash
+.Op Fl -revision
+.Op Fl -configuration-revision
+.Op Fl -json
+.
+.
+.
+.Sh DESCRIPTION
+This command shows the version of the currently active NixOS configuration. For example:
+.Bd -literal -offset indent
+$ nixos-version
+16.03.1011.6317da4 (Emu)
+.Ed
+.
+.Pp
+The version consists of the following elements:
+.Bl -tag -width indent
+.It Ql 16.03
+The NixOS release, indicating the year and month in which it was released
+(e.g. March 2016).
+.It Ql 1011
+The number of commits in the Nixpkgs Git repository between the start of the
+release branch and the commit from which this version was built. This ensures
+that NixOS versions are monotonically increasing. It is
+.Ql git
+when the current NixOS configuration was built from a checkout of the Nixpkgs
+Git repository rather than from a NixOS channel.
+.It Ql 6317da4
+The first 7 characters of the commit in the Nixpkgs Git repository from which
+this version was built.
+.It Ql Emu
+The code name of the NixOS release. The first letter of the code name indicates
+that this is the N'th stable NixOS release; for example, Emu is the fifth
+release.
+.El
+.
+.
+.
+.Sh OPTIONS
+.Bl -tag -width indent
+.It Fl -hash , -revision
+Show the full SHA1 hash of the Git commit from which this configuration was
+built, e.g.
+.Bd -literal -offset indent
+$ nixos-version --hash
+6317da40006f6bc2480c6781999c52d88dde2acf
+.Ed
+.
+.It Fl -configuration-revision
+Show the configuration revision if available. This could be the full SHA1 hash
+of the Git commit of the system flake, if you add
+.Bd -literal -offset indent
+{ system.configurationRevision = self.rev or "dirty"; }
+.Ed
+.Pp
+to the
+.Ql modules
+array of your flake.nix system configuration e.g.
+.Bd -literal -offset indent
+$ nixos-version --configuration-revision
+aa314ebd1592f6cdd53cb5bba8bcae97d9323de8
+.Ed
+.
+.It Fl -json
+Print a JSON representation of the versions of NixOS and the top-level
+configuration flake.
+.El
+.
+.
+.
+.Sh AUTHORS
+.An -nosplit
+.An Eelco Dolstra
+and
+.An the Nixpkgs/NixOS contributors