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. - - - - - - name value - - - 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 - - - - name value - - - - - - - - - - - - - - - - - - - - - - - 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. - - - - - - name value - - - - 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-name flake-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