diff options
Diffstat (limited to 'nixos/doc/manual/administration')
10 files changed, 155 insertions, 172 deletions
diff --git a/nixos/doc/manual/administration/boot-problems.section.md b/nixos/doc/manual/administration/boot-problems.section.md new file mode 100644 index 00000000000..dee83e7ec22 --- /dev/null +++ b/nixos/doc/manual/administration/boot-problems.section.md @@ -0,0 +1,41 @@ +# Boot Problems {#sec-boot-problems} + +If NixOS fails to boot, there are a number of kernel command line parameters that may help you to identify or fix the issue. You can add these parameters in the GRUB boot menu by pressing “e” to modify the selected boot entry and editing the line starting with `linux`. The following are some useful kernel command line parameters that are recognised by the NixOS boot scripts or by systemd: + +`boot.shell_on_fail` + +: Allows the user to start a root shell if something goes wrong in stage 1 of the boot process (the initial ramdisk). This is disabled by default because there is no authentication for the root shell. + +`boot.debug1` + +: Start an interactive shell in stage 1 before anything useful has been done. That is, no modules have been loaded and no file systems have been mounted, except for `/proc` and `/sys`. + +`boot.debug1devices` + +: Like `boot.debug1`, but runs stage1 until kernel modules are loaded and device nodes are created. This may help with e.g. making the keyboard work. + +`boot.debug1mounts` + +: Like `boot.debug1` or `boot.debug1devices`, but runs stage1 until all filesystems that are mounted during initrd are mounted (see [neededForBoot](#opt-fileSystems._name_.neededForBoot)). As a motivating example, this could be useful if you've forgotten to set [neededForBoot](options.html#opt-fileSystems._name_.neededForBoot) on a file system. + +`boot.trace` + +: Print every shell command executed by the stage 1 and 2 boot scripts. + +`single` + +: Boot into rescue mode (a.k.a. single user mode). This will cause systemd to start nothing but the unit `rescue.target`, which runs `sulogin` to prompt for the root password and start a root login shell. Exiting the shell causes the system to continue with the normal boot process. + +`systemd.log_level=debug` `systemd.log_target=console` + +: Make systemd very verbose and send log messages to the console instead of the journal. For more parameters recognised by systemd, see systemd(1). + +In addition, these arguments are recognised by the live image only: + +`live.nixos.passwd=password` + +: Set the password for the `nixos` live user. This can be used for SSH access if there are issues using the terminal. + +Notice that for `boot.shell_on_fail`, `boot.debug1`, `boot.debug1devices`, and `boot.debug1mounts`, if you did **not** select "start the new shell as pid 1", and you `exit` from the new shell, boot will proceed normally from the point where it failed, as if you'd chosen "ignore the error and continue". + +If no login prompts or X11 login screens appear (e.g. due to hanging dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start rescue mode (described above). (Also note that since most units have a 90-second timeout before systemd gives up on them, the `agetty` login prompts should appear eventually unless something is very wrong.) diff --git a/nixos/doc/manual/administration/boot-problems.xml b/nixos/doc/manual/administration/boot-problems.xml deleted file mode 100644 index badc374ebcf..00000000000 --- a/nixos/doc/manual/administration/boot-problems.xml +++ /dev/null @@ -1,126 +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-boot-problems"> - <title>Boot Problems</title> - - <para> - If NixOS fails to boot, there are a number of kernel command line parameters - that may help you to identify or fix the issue. You can add these parameters - in the GRUB boot menu by pressing “e” to modify the selected boot entry - and editing the line starting with <literal>linux</literal>. The following - are some useful kernel command line parameters that are recognised by the - NixOS boot scripts or by systemd: - <variablelist> - <varlistentry> - <term> - <literal>boot.shell_on_fail</literal> - </term> - <listitem> - <para> - Allows the user to start a root shell if something goes wrong in stage 1 - of the boot process (the initial ramdisk). This is disabled by default - because there is no authentication for the root shell. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>boot.debug1</literal> - </term> - <listitem> - <para> - Start an interactive shell in stage 1 before anything useful has been - done. That is, no modules have been loaded and no file systems have been - mounted, except for <filename>/proc</filename> and - <filename>/sys</filename>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>boot.debug1devices</literal> - </term> - <listitem> - <para> - Like <literal>boot.debug1</literal>, but runs stage1 until kernel modules are loaded and device nodes are created. - This may help with e.g. making the keyboard work. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>boot.debug1mounts</literal> - </term> - <listitem> - <para> - Like <literal>boot.debug1</literal> or - <literal>boot.debug1devices</literal>, but runs stage1 until all - filesystems that are mounted during initrd are mounted (see - <option><link linkend="opt-fileSystems._name__.neededForBoot">neededForBoot</link></option> - ). As a motivating example, this could be useful if you've forgotten to set - <option><link linkend="opt-fileSystems._name__.neededForBoot">neededForBoot</link></option> - on a file system. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>boot.trace</literal> - </term> - <listitem> - <para> - Print every shell command executed by the stage 1 and 2 boot scripts. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>single</literal> - </term> - <listitem> - <para> - Boot into rescue mode (a.k.a. single user mode). This will cause systemd - to start nothing but the unit <literal>rescue.target</literal>, which - runs <command>sulogin</command> to prompt for the root password and start - a root login shell. Exiting the shell causes the system to continue with - the normal boot process. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>systemd.log_level=debug systemd.log_target=console</literal> - </term> - <listitem> - <para> - Make systemd very verbose and send log messages to the console instead of - the journal. - </para> - </listitem> - </varlistentry> - </variablelist> - For more parameters recognised by systemd, see <citerefentry> - <refentrytitle>systemd</refentrytitle> - <manvolnum>1</manvolnum></citerefentry>. - </para> - - <para> - Notice that for <literal>boot.shell_on_fail</literal>, - <literal>boot.debug1</literal>, <literal>boot.debug1devices</literal>, and - <literal>boot.debug1mounts</literal>, if you did <emphasis>not</emphasis> - select "start the new shell as pid 1", and you <literal>exit</literal> from - the new shell, boot will proceed normally from the point where it failed, as - if you'd chosen "ignore the error and continue". - </para> - - <para> - If no login prompts or X11 login screens appear (e.g. due to hanging - dependencies), you can press Alt+ArrowUp. If you’re lucky, this will start - rescue mode (described above). (Also note that since most units have a - 90-second timeout before systemd gives up on them, the - <command>agetty</command> login prompts should appear eventually unless - something is very wrong.) - </para> -</section> diff --git a/nixos/doc/manual/administration/imperative-containers.xml b/nixos/doc/manual/administration/imperative-containers.xml index 7ded0c11786..bc19acf9f69 100644 --- a/nixos/doc/manual/administration/imperative-containers.xml +++ b/nixos/doc/manual/administration/imperative-containers.xml @@ -14,27 +14,27 @@ <para> You create a container with identifier <literal>foo</literal> as follows: <screen> -# nixos-container create foo +<prompt># </prompt>nixos-container create <replaceable>foo</replaceable> </screen> This creates the container’s root directory in - <filename>/var/lib/containers/foo</filename> and a small configuration file - in <filename>/etc/containers/foo.conf</filename>. It also builds the + <filename>/var/lib/containers/<replaceable>foo</replaceable></filename> and a small configuration file + in <filename>/etc/containers/<replaceable>foo</replaceable>.conf</filename>. It also builds the container’s initial system configuration and stores it in - <filename>/nix/var/nix/profiles/per-container/foo/system</filename>. You can + <filename>/nix/var/nix/profiles/per-container/<replaceable>foo</replaceable>/system</filename>. You can modify the initial configuration of the container on the command line. For instance, to create a container that has <command>sshd</command> running, with the given public key for <literal>root</literal>: <screen> -# nixos-container create foo --config ' +<prompt># </prompt>nixos-container create <replaceable>foo</replaceable> --config ' <xref linkend="opt-services.openssh.enable"/> = true; - <link linkend="opt-users.users._name__.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"]; + <link linkend="opt-users.users._name_.openssh.authorizedKeys.keys">users.users.root.openssh.authorizedKeys.keys</link> = ["ssh-dss AAAAB3N…"]; ' </screen> By default the next free address in the <literal>10.233.0.0/16</literal> subnet will be chosen as container IP. This behavior can be altered by setting <literal>--host-address</literal> and <literal>--local-address</literal>: <screen> -# nixos-container create test --config-file test-container.nix \ +<prompt># </prompt>nixos-container create test --config-file test-container.nix \ --local-address 10.235.1.2 --host-address 10.235.1.1 </screen> </para> @@ -42,7 +42,7 @@ <para> Creating a container does not start it. To start the container, run: <screen> -# nixos-container start foo +<prompt># </prompt>nixos-container start <replaceable>foo</replaceable> </screen> This command will return as soon as the container has booted and has reached <literal>multi-user.target</literal>. On the host, the container runs within @@ -51,7 +51,7 @@ Thus, if something went wrong, you can get status info using <command>systemctl</command>: <screen> -# systemctl status container@foo +<prompt># </prompt>systemctl status container@<replaceable>foo</replaceable> </screen> </para> @@ -59,22 +59,22 @@ If the container has started successfully, you can log in as root using the <command>root-login</command> operation: <screen> -# nixos-container root-login foo -[root@foo:~]# +<prompt># </prompt>nixos-container root-login <replaceable>foo</replaceable> +<prompt>[root@foo:~]#</prompt> </screen> Note that only root on the host can do this (since there is no authentication). You can also get a regular login prompt using the <command>login</command> operation, which is available to all users on the host: <screen> -# nixos-container login foo +<prompt># </prompt>nixos-container login <replaceable>foo</replaceable> foo login: alice Password: *** </screen> With <command>nixos-container run</command>, you can execute arbitrary commands in the container: <screen> -# nixos-container run foo -- uname -a +<prompt># </prompt>nixos-container run <replaceable>foo</replaceable> -- uname -a Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux </screen> </para> @@ -85,18 +85,18 @@ Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux <literal>/var/lib/container/<replaceable>name</replaceable>/etc/nixos/configuration.nix</literal>, and run <screen> -# nixos-container update foo +<prompt># </prompt>nixos-container update <replaceable>foo</replaceable> </screen> This will build and activate the new configuration. You can also specify a new configuration on the command line: <screen> -# nixos-container update foo --config ' +<prompt># </prompt>nixos-container update <replaceable>foo</replaceable> --config ' <xref linkend="opt-services.httpd.enable"/> = true; <xref linkend="opt-services.httpd.adminAddr"/> = "foo@example.org"; <xref linkend="opt-networking.firewall.allowedTCPPorts"/> = [ 80 ]; ' -# curl http://$(nixos-container show-ip foo)/ +<prompt># </prompt>curl http://$(nixos-container show-ip <replaceable>foo</replaceable>)/ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">… </screen> However, note that this will overwrite the container’s @@ -117,7 +117,7 @@ Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux by using <command>systemctl</command> on the container’s service unit. To destroy a container, including its file system, do <screen> -# nixos-container destroy foo +<prompt># </prompt>nixos-container destroy <replaceable>foo</replaceable> </screen> </para> </section> diff --git a/nixos/doc/manual/administration/maintenance-mode.xml b/nixos/doc/manual/administration/maintenance-mode.xml index 71e3f9ea665..74abfdd7c66 100644 --- a/nixos/doc/manual/administration/maintenance-mode.xml +++ b/nixos/doc/manual/administration/maintenance-mode.xml @@ -8,7 +8,7 @@ <para> You can enter rescue mode by running: <screen> -# systemctl rescue</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. diff --git a/nixos/doc/manual/administration/network-problems.xml b/nixos/doc/manual/administration/network-problems.xml index 570f5835884..1035e4e056a 100644 --- a/nixos/doc/manual/administration/network-problems.xml +++ b/nixos/doc/manual/administration/network-problems.xml @@ -16,12 +16,12 @@ disable the use of the binary cache by adding <option>--option use-binary-caches false</option>, e.g. <screen> -# nixos-rebuild switch --option use-binary-caches false +<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> -# nixos-rebuild switch --option binary-caches http://my-cache.example.org/ +<prompt># </prompt>nixos-rebuild switch --option binary-caches <replaceable>http://my-cache.example.org/</replaceable> </screen> </para> </section> diff --git a/nixos/doc/manual/administration/rebooting.xml b/nixos/doc/manual/administration/rebooting.xml index a5abd6f0258..c57d885c5f3 100644 --- a/nixos/doc/manual/administration/rebooting.xml +++ b/nixos/doc/manual/administration/rebooting.xml @@ -7,20 +7,20 @@ <para> The system can be shut down (and automatically powered off) by doing: <screen> -# shutdown +<prompt># </prompt>shutdown </screen> This is equivalent to running <command>systemctl poweroff</command>. </para> <para> To reboot the system, run <screen> -# reboot +<prompt># </prompt>reboot </screen> which is equivalent to <command>systemctl reboot</command>. Alternatively, you can quickly reboot the system using <literal>kexec</literal>, which bypasses the BIOS by directly loading the new kernel into memory: <screen> -# systemctl kexec +<prompt># </prompt>systemctl kexec </screen> </para> <para> diff --git a/nixos/doc/manual/administration/rollback.xml b/nixos/doc/manual/administration/rollback.xml index fb87810ba46..80d79e1a53f 100644 --- a/nixos/doc/manual/administration/rollback.xml +++ b/nixos/doc/manual/administration/rollback.xml @@ -20,16 +20,16 @@ has booted, you can make the selected configuration the default for subsequent boots: <screen> -# /run/current-system/bin/switch-to-configuration boot</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> -# nixos-rebuild switch --rollback</screen> +<prompt># </prompt>nixos-rebuild switch --rollback</screen> This is equivalent to running: <screen> -# /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</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> diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml index 1b9c745eb59..863b0d47f6c 100644 --- a/nixos/doc/manual/administration/service-mgmt.xml +++ b/nixos/doc/manual/administration/service-mgmt.xml @@ -6,7 +6,7 @@ <title>Service Management</title> <para> In NixOS, all system services are started and monitored using the systemd - program. Systemd is the “init” process of the system (i.e. PID 1), the + program. systemd is the “init” process of the system (i.e. PID 1), the parent of all other processes. It manages a set of so-called “units”, which can be things like system services (programs), but also mount points, swap files, devices, targets (groups of units) and more. Units can have @@ -16,10 +16,17 @@ dependencies of this unit cause all system services to be started, file systems to be mounted, swap files to be activated, and so on. </para> - <para> - The command <command>systemctl</command> is the main way to interact with - <command>systemd</command>. Without any arguments, it shows the status of - active units: + <section xml:id="sect-nixos-systemd-general"> + <title>Interacting with a running systemd</title> + <para> + The command <command>systemctl</command> is the main way to interact with + <command>systemd</command>. The following paragraphs demonstrate ways to + interact with any OS running systemd as init system. NixOS is of no + exception. The <link xlink:href="#sect-nixos-systemd-nixos">next section + </link> explains NixOS specific things worth knowing. + </para> + <para> + Without any arguments, <literal>systmctl</literal> the status of active units: <screen> <prompt>$ </prompt>systemctl -.mount loaded active mounted / @@ -28,10 +35,10 @@ sshd.service loaded active running SSH Daemon graphical.target loaded active active Graphical Interface <replaceable>...</replaceable> </screen> - </para> - <para> - You can ask for detailed status information about a unit, for instance, the - PostgreSQL database service: + </para> + <para> + You can ask for detailed status information about a unit, for instance, the + PostgreSQL database service: <screen> <prompt>$ </prompt>systemctl status postgresql.service postgresql.service - PostgreSQL Server @@ -58,15 +65,76 @@ Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server. <para> Units can be stopped, started or restarted: <screen> -# systemctl stop postgresql.service -# systemctl start postgresql.service -# systemctl restart postgresql.service +<prompt># </prompt>systemctl stop postgresql.service +<prompt># </prompt>systemctl start postgresql.service +<prompt># </prompt>systemctl restart postgresql.service </screen> - These operations are synchronous: they wait until the service has finished - starting or stopping (or has failed). Starting a unit will cause the - dependencies of that unit to be started as well (if necessary). - </para> -<!-- - cgroups: each service and user session is a cgroup + These operations are synchronous: they wait until the service has finished + starting or stopping (or has failed). Starting a unit will cause the + dependencies of that unit to be started as well (if necessary). + </para> + <!-- TODO: document cgroups, draft: + each service and user session is a cgroup -- cgroup resource management --> + - cgroup resource management --> + </section> + <section xml:id="sect-nixos-systemd-nixos"> + <title>systemd in NixOS</title> + <para> + Packages in Nixpkgs sometimes provide systemd units with them, usually in + e.g <literal>#pkg-out#/lib/systemd/</literal>. Putting such a package in + <literal>environment.systemPackages</literal> doesn't make the service + available to users or the system. + </para> + <para> + In order to enable a systemd <emphasis>system</emphasis> service with + provided upstream package, use (e.g): +<programlisting> +<xref linkend="opt-systemd.packages"/> = [ pkgs.packagekit ]; +</programlisting> + </para> + <para> + Usually NixOS modules written by the community do the above, plus take care of + other details. If a module was written for a service you are interested in, + you'd probably need only to use + <literal>services.#name#.enable = true;</literal>. These services are defined + in Nixpkgs' + <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules"> + <literal>nixos/modules/</literal> directory </link>. In case the service is + simple enough, the above method should work, and start the service on boot. + </para> + <para> + <emphasis>User</emphasis> systemd services on the other hand, should be + treated differently. Given a package that has a systemd unit file at + <literal>#pkg-out#/lib/systemd/user/</literal>, using + <xref linkend="opt-systemd.packages"/> will make you able to start the service via + <literal>systemctl --user start</literal>, but it won't start automatically on login. + <!-- TODO: Document why systemd.packages doesn't work for user services or fix this. + https://github.com/NixOS/nixpkgs/blob/2cd6594a8710a801038af2b72348658f732ce84a/nixos/modules/system/boot/systemd-lib.nix#L177-L198 + + This has been talked over at https://discourse.nixos.org/t/how-to-enable-upstream-systemd-user-services-declaratively/7649/5 + --> + However, You can imperatively enable it by adding the package's attribute to + <link linkend="opt-environment.systemPackages"> + <literal>systemd.packages</literal></link> and then do this (e.g): +<screen> +<prompt>$ </prompt>mkdir -p ~/.config/systemd/user/default.target.wants +<prompt>$ </prompt>ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/ +<prompt>$ </prompt>systemctl --user daemon-reload +<prompt>$ </prompt>systemctl --user enable syncthing.service +</screen> + If you are interested in a timer file, use <literal>timers.target.wants</literal> + instead of <literal>default.target.wants</literal> in the 1st and 2nd command. + </para> + <para> + Using <literal>systemctl --user enable syncthing.service</literal> instead of + the above, will work, but it'll use the absolute path of + <literal>syncthing.service</literal> for the symlink, and this path is in + <literal>/nix/store/.../lib/systemd/user/</literal>. Hence + <link xlink:href="#sec-nix-gc">garbage collection</link> will remove that file + and you will wind up with a broken symlink in your systemd configuration, which + in turn will not make the service / timer start on login. + </para> + </section> </chapter> + diff --git a/nixos/doc/manual/administration/troubleshooting.xml b/nixos/doc/manual/administration/troubleshooting.xml index 6496e7bde38..b055acadacf 100644 --- a/nixos/doc/manual/administration/troubleshooting.xml +++ b/nixos/doc/manual/administration/troubleshooting.xml @@ -8,7 +8,7 @@ This chapter describes solutions to common problems you might encounter when you manage your NixOS system. </para> - <xi:include href="boot-problems.xml" /> + <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" /> diff --git a/nixos/doc/manual/administration/user-sessions.xml b/nixos/doc/manual/administration/user-sessions.xml index 80daf6bdbff..9acb147ac1a 100644 --- a/nixos/doc/manual/administration/user-sessions.xml +++ b/nixos/doc/manual/administration/user-sessions.xml @@ -39,7 +39,7 @@ c3 - root (0) can terminate a session in a way that ensures that all the session’s processes are gone: <screen> -# loginctl terminate-session c3 +<prompt># </prompt>loginctl terminate-session c3 </screen> </para> </chapter> |