diff --git a/nixos/doc/manual/administration/maintenance-mode.section.md b/nixos/doc/manual/administration/maintenance-mode.section.md new file mode 100644 index 000000000000..0aec013c0a9b --- /dev/null +++ b/nixos/doc/manual/administration/maintenance-mode.section.md @@ -0,0 +1,11 @@ +# Maintenance Mode {#sec-maintenance-mode} + +You can enter rescue mode by running: + +```ShellSession +# systemctl rescue +``` + +This will eventually give you a single-user root shell. Systemd will +stop (almost) all system services. To get out of maintenance mode, just +exit from the rescue shell. diff --git a/nixos/doc/manual/administration/maintenance-mode.xml b/nixos/doc/manual/administration/maintenance-mode.xml deleted file mode 100644 index 74abfdd7c663..000000000000 --- a/nixos/doc/manual/administration/maintenance-mode.xml +++ /dev/null @@ -1,16 +0,0 @@ -
- Maintenance Mode - - - You can enter rescue mode by running: - -# systemctl rescue - This will eventually give you a single-user root shell. Systemd will stop - (almost) all system services. To get out of maintenance mode, just exit from - the rescue shell. - -
diff --git a/nixos/doc/manual/administration/network-problems.section.md b/nixos/doc/manual/administration/network-problems.section.md new file mode 100644 index 000000000000..d360120d72d0 --- /dev/null +++ b/nixos/doc/manual/administration/network-problems.section.md @@ -0,0 +1,21 @@ +# Network Problems {#sec-nix-network-issues} + +Nix uses a so-called *binary cache* to optimise building a package from +source into downloading it as a pre-built binary. That is, whenever a +command like `nixos-rebuild` needs a path in the Nix store, Nix will try +to download that path from the Internet rather than build it from +source. The default binary cache is `https://cache.nixos.org/`. If this +cache is unreachable, Nix operations may take a long time due to HTTP +connection timeouts. You can disable the use of the binary cache by +adding `--option use-binary-caches false`, e.g. + +```ShellSession +# nixos-rebuild switch --option use-binary-caches false +``` + +If you have an alternative binary cache at your disposal, you can use it +instead: + +```ShellSession +# nixos-rebuild switch --option binary-caches http://my-cache.example.org/ +``` diff --git a/nixos/doc/manual/administration/network-problems.xml b/nixos/doc/manual/administration/network-problems.xml deleted file mode 100644 index 1035e4e056a9..000000000000 --- a/nixos/doc/manual/administration/network-problems.xml +++ /dev/null @@ -1,27 +0,0 @@ -
- Network Problems - - - Nix uses a so-called binary cache to optimise building a - package from source into downloading it as a pre-built binary. That is, - whenever a command like nixos-rebuild needs a path in the - Nix store, Nix will try to download that path from the Internet rather than - build it from source. The default binary cache is - https://cache.nixos.org/. If this cache is unreachable, Nix - operations may take a long time due to HTTP connection timeouts. You can - disable the use of the binary cache by adding , e.g. - -# nixos-rebuild switch --option use-binary-caches false - - If you have an alternative binary cache at your disposal, you can use it - instead: - -# nixos-rebuild switch --option binary-caches http://my-cache.example.org/ - - -
diff --git a/nixos/doc/manual/administration/rollback.section.md b/nixos/doc/manual/administration/rollback.section.md new file mode 100644 index 000000000000..290d685a2a18 --- /dev/null +++ b/nixos/doc/manual/administration/rollback.section.md @@ -0,0 +1,38 @@ +# Rolling Back Configuration Changes {#sec-rollback} + +After running `nixos-rebuild` to switch to a new configuration, you may +find that the new configuration doesn't work very well. In that case, +there are several ways to return to a previous configuration. + +First, the GRUB boot manager allows you to boot into any previous +configuration that hasn't been garbage-collected. These configurations +can be found under the GRUB submenu "NixOS - All configurations". This +is especially useful if the new configuration fails to boot. After the +system has booted, you can make the selected configuration the default +for subsequent boots: + +```ShellSession +# /run/current-system/bin/switch-to-configuration boot +``` + +Second, you can switch to the previous configuration in a running +system: + +```ShellSession +# nixos-rebuild switch --rollback +``` + +This is equivalent to running: + +```ShellSession +# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch +``` + +where `N` is the number of the NixOS system configuration. To get a +list of the available configurations, do: + +```ShellSession +$ ls -l /nix/var/nix/profiles/system-*-link +... +lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055 +``` diff --git a/nixos/doc/manual/administration/rollback.xml b/nixos/doc/manual/administration/rollback.xml deleted file mode 100644 index 80d79e1a53f1..000000000000 --- a/nixos/doc/manual/administration/rollback.xml +++ /dev/null @@ -1,41 +0,0 @@ -
- Rolling Back Configuration Changes - - - After running nixos-rebuild to switch to a new - configuration, you may find that the new configuration doesn’t work very - well. In that case, there are several ways to return to a previous - configuration. - - - - First, the GRUB boot manager allows you to boot into any previous - configuration that hasn’t been garbage-collected. These configurations can - be found under the GRUB submenu “NixOS - All configurations”. This is - especially useful if the new configuration fails to boot. After the system - has booted, you can make the selected configuration the default for - subsequent boots: - -# /run/current-system/bin/switch-to-configuration boot - - - - Second, you can switch to the previous configuration in a running system: - -# nixos-rebuild switch --rollback - This is equivalent to running: - -# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch - where N is the number of the NixOS system - configuration. To get a list of the available configurations, do: - -$ ls -l /nix/var/nix/profiles/system-*-link -... -lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055 - - -
diff --git a/nixos/doc/manual/administration/store-corruption.section.md b/nixos/doc/manual/administration/store-corruption.section.md new file mode 100644 index 000000000000..bd8a5772b37c --- /dev/null +++ b/nixos/doc/manual/administration/store-corruption.section.md @@ -0,0 +1,28 @@ +# Nix Store Corruption {#sec-nix-store-corruption} + +After a system crash, it's possible for files in the Nix store to become +corrupted. (For instance, the Ext4 file system has the tendency to +replace un-synced files with zero bytes.) NixOS tries hard to prevent +this from happening: it performs a `sync` before switching to a new +configuration, and Nix's database is fully transactional. If corruption +still occurs, you may be able to fix it automatically. + +If the corruption is in a path in the closure of the NixOS system +configuration, you can fix it by doing + +```ShellSession +# nixos-rebuild switch --repair +``` + +This will cause Nix to check every path in the closure, and if its +cryptographic hash differs from the hash recorded in Nix's database, the +path is rebuilt or redownloaded. + +You can also scan the entire Nix store for corrupt paths: + +```ShellSession +# nix-store --verify --check-contents --repair +``` + +Any corrupt paths will be redownloaded if they're available in a binary +cache; otherwise, they cannot be repaired. diff --git a/nixos/doc/manual/administration/store-corruption.xml b/nixos/doc/manual/administration/store-corruption.xml deleted file mode 100644 index b9d11152d5e1..000000000000 --- a/nixos/doc/manual/administration/store-corruption.xml +++ /dev/null @@ -1,36 +0,0 @@ -
- Nix Store Corruption - - - After a system crash, it’s possible for files in the Nix store to become - corrupted. (For instance, the Ext4 file system has the tendency to replace - un-synced files with zero bytes.) NixOS tries hard to prevent this from - happening: it performs a sync before switching to a new - configuration, and Nix’s database is fully transactional. If corruption - still occurs, you may be able to fix it automatically. - - - - If the corruption is in a path in the closure of the NixOS system - configuration, you can fix it by doing - -# nixos-rebuild switch --repair - - This will cause Nix to check every path in the closure, and if its - cryptographic hash differs from the hash recorded in Nix’s database, the - path is rebuilt or redownloaded. - - - - You can also scan the entire Nix store for corrupt paths: - -# nix-store --verify --check-contents --repair - - Any corrupt paths will be redownloaded if they’re available in a binary - cache; otherwise, they cannot be repaired. - -
diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml index b055acadacf3..d447b537335b 100644 --- a/nixos/doc/manual/administration/troubleshooting.xml +++ b/nixos/doc/manual/administration/troubleshooting.xml @@ -9,8 +9,8 @@ you manage your NixOS system. - - - - + + + + diff --git a/nixos/doc/manual/from_md/administration/maintenance-mode.section.xml b/nixos/doc/manual/from_md/administration/maintenance-mode.section.xml new file mode 100644 index 000000000000..c86b1911c117 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/maintenance-mode.section.xml @@ -0,0 +1,14 @@ +
+ Maintenance Mode + + You can enter rescue mode by running: + + +# systemctl rescue + + + This will eventually give you a single-user root shell. Systemd will + stop (almost) all system services. To get out of maintenance mode, + just exit from the rescue shell. + +
diff --git a/nixos/doc/manual/from_md/administration/network-problems.section.xml b/nixos/doc/manual/from_md/administration/network-problems.section.xml new file mode 100644 index 000000000000..4c0598ca94e8 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/network-problems.section.xml @@ -0,0 +1,25 @@ +
+ Network Problems + + Nix uses a so-called binary cache to optimise + building a package from source into downloading it as a pre-built + binary. That is, whenever a command like + nixos-rebuild needs a path in the Nix store, Nix + will try to download that path from the Internet rather than build + it from source. The default binary cache is + https://cache.nixos.org/. If this cache is + unreachable, Nix operations may take a long time due to HTTP + connection timeouts. You can disable the use of the binary cache by + adding --option use-binary-caches false, e.g. + + +# nixos-rebuild switch --option use-binary-caches false + + + If you have an alternative binary cache at your disposal, you can + use it instead: + + +# nixos-rebuild switch --option binary-caches http://my-cache.example.org/ + +
diff --git a/nixos/doc/manual/from_md/administration/rollback.section.xml b/nixos/doc/manual/from_md/administration/rollback.section.xml new file mode 100644 index 000000000000..a8df053011c5 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/rollback.section.xml @@ -0,0 +1,42 @@ +
+ Rolling Back Configuration Changes + + After running nixos-rebuild to switch to a new + configuration, you may find that the new configuration doesn’t work + very well. In that case, there are several ways to return to a + previous configuration. + + + First, the GRUB boot manager allows you to boot into any previous + configuration that hasn’t been garbage-collected. These + configurations can be found under the GRUB submenu NixOS - + All configurations. This is especially useful if the new + configuration fails to boot. After the system has booted, you can + make the selected configuration the default for subsequent boots: + + +# /run/current-system/bin/switch-to-configuration boot + + + Second, you can switch to the previous configuration in a running + system: + + +# nixos-rebuild switch --rollback + + + This is equivalent to running: + + +# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch + + + where N is the number of the NixOS system + configuration. To get a list of the available configurations, do: + + +$ ls -l /nix/var/nix/profiles/system-*-link +... +lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055 + +
diff --git a/nixos/doc/manual/from_md/administration/store-corruption.section.xml b/nixos/doc/manual/from_md/administration/store-corruption.section.xml new file mode 100644 index 000000000000..9ed572d484dc --- /dev/null +++ b/nixos/doc/manual/from_md/administration/store-corruption.section.xml @@ -0,0 +1,34 @@ +
+ Nix Store Corruption + + After a system crash, it’s possible for files in the Nix store to + become corrupted. (For instance, the Ext4 file system has the + tendency to replace un-synced files with zero bytes.) NixOS tries + hard to prevent this from happening: it performs a + sync before switching to a new configuration, and + Nix’s database is fully transactional. If corruption still occurs, + you may be able to fix it automatically. + + + If the corruption is in a path in the closure of the NixOS system + configuration, you can fix it by doing + + +# nixos-rebuild switch --repair + + + This will cause Nix to check every path in the closure, and if its + cryptographic hash differs from the hash recorded in Nix’s database, + the path is rebuilt or redownloaded. + + + You can also scan the entire Nix store for corrupt paths: + + +# nix-store --verify --check-contents --repair + + + Any corrupt paths will be redownloaded if they’re available in a + binary cache; otherwise, they cannot be repaired. + +