mirror of
https://github.com/NixOS/nixpkgs.git
synced 2024-11-18 19:51:17 +00:00
Merge pull request #128935 from bobby285271/pr7
nixos/doc: convert "Chapter 56. Troubleshooting" to CommonMark
This commit is contained in:
Jörg Thalheim
GitHub
commit
5de68de484
11
nixos/doc/manual/administration/maintenance-mode.section.md
Normal file
11
nixos/doc/manual/administration/maintenance-mode.section.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-maintenance-mode">
|
||||
<title>Maintenance Mode</title>
|
||||
|
||||
<para>
|
||||
You can enter rescue mode by running:
|
||||
<screen>
|
||||
<prompt># </prompt>systemctl rescue</screen>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
21
nixos/doc/manual/administration/network-problems.section.md
Normal file
21
nixos/doc/manual/administration/network-problems.section.md
Normal file
|
|
@ -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/
|
||||
```
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-nix-network-issues">
|
||||
<title>Network Problems</title>
|
||||
|
||||
<para>
|
||||
Nix uses a so-called <emphasis>binary cache</emphasis> to optimise building a
|
||||
package from source into downloading it as a pre-built binary. That is,
|
||||
whenever a command like <command>nixos-rebuild</command> 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
|
||||
<uri>https://cache.nixos.org/</uri>. 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>--option
|
||||
use-binary-caches false</option>, e.g.
|
||||
<screen>
|
||||
<prompt># </prompt>nixos-rebuild switch --option use-binary-caches false
|
||||
</screen>
|
||||
If you have an alternative binary cache at your disposal, you can use it
|
||||
instead:
|
||||
<screen>
|
||||
<prompt># </prompt>nixos-rebuild switch --option binary-caches <replaceable>http://my-cache.example.org/</replaceable>
|
||||
</screen>
|
||||
</para>
|
||||
</section>
|
||||
38
nixos/doc/manual/administration/rollback.section.md
Normal file
38
nixos/doc/manual/administration/rollback.section.md
Normal file
|
|
@ -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
|
||||
```
|
||||
|
|
@ -1,41 +0,0 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-rollback">
|
||||
<title>Rolling Back Configuration Changes</title>
|
||||
|
||||
<para>
|
||||
After running <command>nixos-rebuild</command> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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:
|
||||
<screen>
|
||||
<prompt># </prompt>/run/current-system/bin/switch-to-configuration boot</screen>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Second, you can switch to the previous configuration in a running system:
|
||||
<screen>
|
||||
<prompt># </prompt>nixos-rebuild switch --rollback</screen>
|
||||
This is equivalent to running:
|
||||
<screen>
|
||||
<prompt># </prompt>/nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
|
||||
where <replaceable>N</replaceable> is the number of the NixOS system
|
||||
configuration. To get a list of the available configurations, do:
|
||||
<screen>
|
||||
<prompt>$ </prompt>ls -l /nix/var/nix/profiles/system-*-link
|
||||
<replaceable>...</replaceable>
|
||||
lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link -> /nix/store/202b...-nixos-13.07pre4932_5a676e4-4be1055
|
||||
</screen>
|
||||
</para>
|
||||
</section>
|
||||
28
nixos/doc/manual/administration/store-corruption.section.md
Normal file
28
nixos/doc/manual/administration/store-corruption.section.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -1,36 +0,0 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="sec-nix-store-corruption">
|
||||
<title>Nix Store Corruption</title>
|
||||
|
||||
<para>
|
||||
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 <command>sync</command> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If the corruption is in a path in the closure of the NixOS system
|
||||
configuration, you can fix it by doing
|
||||
<screen>
|
||||
<prompt># </prompt>nixos-rebuild switch --repair
|
||||
</screen>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You can also scan the entire Nix store for corrupt paths:
|
||||
<screen>
|
||||
<prompt># </prompt>nix-store --verify --check-contents --repair
|
||||
</screen>
|
||||
Any corrupt paths will be redownloaded if they’re available in a binary
|
||||
cache; otherwise, they cannot be repaired.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -9,8 +9,8 @@
|
|||
you manage your NixOS system.
|
||||
</para>
|
||||
<xi:include href="../from_md/administration/boot-problems.section.xml" />
|
||||
<xi:include href="maintenance-mode.xml" />
|
||||
<xi:include href="rollback.xml" />
|
||||
<xi:include href="store-corruption.xml" />
|
||||
<xi:include href="network-problems.xml" />
|
||||
<xi:include href="../from_md/administration/maintenance-mode.section.xml" />
|
||||
<xi:include href="../from_md/administration/rollback.section.xml" />
|
||||
<xi:include href="../from_md/administration/store-corruption.section.xml" />
|
||||
<xi:include href="../from_md/administration/network-problems.section.xml" />
|
||||
</chapter>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,14 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-maintenance-mode">
|
||||
<title>Maintenance Mode</title>
|
||||
<para>
|
||||
You can enter rescue mode by running:
|
||||
</para>
|
||||
<programlisting>
|
||||
# systemctl rescue
|
||||
</programlisting>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,25 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-network-issues">
|
||||
<title>Network Problems</title>
|
||||
<para>
|
||||
Nix uses a so-called <emphasis>binary cache</emphasis> to optimise
|
||||
building a package from source into downloading it as a pre-built
|
||||
binary. That is, whenever a command like
|
||||
<literal>nixos-rebuild</literal> 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
|
||||
<literal>https://cache.nixos.org/</literal>. 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 <literal>--option use-binary-caches false</literal>, e.g.
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch --option use-binary-caches false
|
||||
</programlisting>
|
||||
<para>
|
||||
If you have an alternative binary cache at your disposal, you can
|
||||
use it instead:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
|
||||
</programlisting>
|
||||
</section>
|
||||
42
nixos/doc/manual/from_md/administration/rollback.section.xml
Normal file
42
nixos/doc/manual/from_md/administration/rollback.section.xml
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-rollback">
|
||||
<title>Rolling Back Configuration Changes</title>
|
||||
<para>
|
||||
After running <literal>nixos-rebuild</literal> 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.
|
||||
</para>
|
||||
<para>
|
||||
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 <quote>NixOS -
|
||||
All configurations</quote>. 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:
|
||||
</para>
|
||||
<programlisting>
|
||||
# /run/current-system/bin/switch-to-configuration boot
|
||||
</programlisting>
|
||||
<para>
|
||||
Second, you can switch to the previous configuration in a running
|
||||
system:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch --rollback
|
||||
</programlisting>
|
||||
<para>
|
||||
This is equivalent to running:
|
||||
</para>
|
||||
<programlisting>
|
||||
# /nix/var/nix/profiles/system-N-link/bin/switch-to-configuration switch
|
||||
</programlisting>
|
||||
<para>
|
||||
where <literal>N</literal> is the number of the NixOS system
|
||||
configuration. To get a list of the available configurations, do:
|
||||
</para>
|
||||
<programlisting>
|
||||
$ 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
|
||||
</programlisting>
|
||||
</section>
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-store-corruption">
|
||||
<title>Nix Store Corruption</title>
|
||||
<para>
|
||||
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
|
||||
<literal>sync</literal> 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.
|
||||
</para>
|
||||
<para>
|
||||
If the corruption is in a path in the closure of the NixOS system
|
||||
configuration, you can fix it by doing
|
||||
</para>
|
||||
<programlisting>
|
||||
# nixos-rebuild switch --repair
|
||||
</programlisting>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
You can also scan the entire Nix store for corrupt paths:
|
||||
</para>
|
||||
<programlisting>
|
||||
# nix-store --verify --check-contents --repair
|
||||
</programlisting>
|
||||
<para>
|
||||
Any corrupt paths will be redownloaded if they’re available in a
|
||||
binary cache; otherwise, they cannot be repaired.
|
||||
</para>
|
||||
</section>
|
||||
Loading…
Reference in a new issue