diff options
21 files changed, 768 insertions, 399 deletions
diff --git a/nixos/doc/manual/administration/boot-problems.section.md b/nixos/doc/manual/administration/boot-problems.section.md index dee83e7ec22..bca4fdc3fb3 100644 --- a/nixos/doc/manual/administration/boot-problems.section.md +++ b/nixos/doc/manual/administration/boot-problems.section.md @@ -16,7 +16,7 @@ If NixOS fails to boot, there are a number of kernel command line parameters tha `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. +: 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](#opt-fileSystems._name_.neededForBoot) on a file system. `boot.trace` diff --git a/nixos/doc/manual/administration/cleaning-store.chapter.md b/nixos/doc/manual/administration/cleaning-store.chapter.md new file mode 100644 index 00000000000..fb2090b31d8 --- /dev/null +++ b/nixos/doc/manual/administration/cleaning-store.chapter.md @@ -0,0 +1,62 @@ +# Cleaning the Nix Store {#sec-nix-gc} + +Nix has a purely functional model, meaning that packages are never +upgraded in place. Instead new versions of packages end up in a +different location in the Nix store (`/nix/store`). You should +periodically run Nix's *garbage collector* to remove old, unreferenced +packages. This is easy: + +```ShellSession +$ nix-collect-garbage +``` + +Alternatively, you can use a systemd unit that does the same in the +background: + +```ShellSession +# systemctl start nix-gc.service +``` + +You can tell NixOS in `configuration.nix` to run this unit automatically +at certain points in time, for instance, every night at 03:15: + +```nix +nix.gc.automatic = true; +nix.gc.dates = "03:15"; +``` + +The commands above do not remove garbage collector roots, such as old +system configurations. Thus they do not remove the ability to roll back +to previous configurations. The following command deletes old roots, +removing the ability to roll back to them: + +```ShellSession +$ nix-collect-garbage -d +``` + +You can also do this for specific profiles, e.g. + +```ShellSession +$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old +``` + +Note that NixOS system configurations are stored in the profile +`/nix/var/nix/profiles/system`. + +Another way to reclaim disk space (often as much as 40% of the size of +the Nix store) is to run Nix's store optimiser, which seeks out +identical files in the store and replaces them with hard links to a +single copy. + +```ShellSession +$ nix-store --optimise +``` + +Since this command needs to read the entire Nix store, it can take quite +a while to finish. + +## NixOS Boot Entries {#sect-nixos-gc-boot-entries} + +If your `/boot` partition runs out of space, after clearing old profiles +you must rebuild your system with `nixos-rebuild` to update the `/boot` +partition and clear space. diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml deleted file mode 100644 index 526803e429b..00000000000 --- a/nixos/doc/manual/administration/cleaning-store.xml +++ /dev/null @@ -1,63 +0,0 @@ -<chapter 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-gc"> - <title>Cleaning the Nix Store</title> - <para> - Nix has a purely functional model, meaning that packages are never upgraded - in place. Instead new versions of packages end up in a different location in - the Nix store (<filename>/nix/store</filename>). You should periodically run - Nix’s <emphasis>garbage collector</emphasis> to remove old, unreferenced - packages. This is easy: -<screen> -<prompt>$ </prompt>nix-collect-garbage -</screen> - Alternatively, you can use a systemd unit that does the same in the - background: -<screen> -<prompt># </prompt>systemctl start nix-gc.service -</screen> - You can tell NixOS in <filename>configuration.nix</filename> to run this unit - automatically at certain points in time, for instance, every night at 03:15: -<programlisting> -<xref linkend="opt-nix.gc.automatic"/> = true; -<xref linkend="opt-nix.gc.dates"/> = "03:15"; -</programlisting> - </para> - <para> - The commands above do not remove garbage collector roots, such as old system - configurations. Thus they do not remove the ability to roll back to previous - configurations. The following command deletes old roots, removing the ability - to roll back to them: -<screen> -<prompt>$ </prompt>nix-collect-garbage -d -</screen> - You can also do this for specific profiles, e.g. -<screen> -<prompt>$ </prompt>nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old -</screen> - Note that NixOS system configurations are stored in the profile - <filename>/nix/var/nix/profiles/system</filename>. - </para> - <para> - Another way to reclaim disk space (often as much as 40% of the size of the - Nix store) is to run Nix’s store optimiser, which seeks out identical files - in the store and replaces them with hard links to a single copy. -<screen> -<prompt>$ </prompt>nix-store --optimise -</screen> - Since this command needs to read the entire Nix store, it can take quite a - while to finish. - </para> - <section xml:id="sect-nixos-gc-boot-entries"> - <title>NixOS Boot Entries</title> - - <para> - If your <filename>/boot</filename> partition runs out of space, after - clearing old profiles you must rebuild your system with - <literal>nixos-rebuild</literal> to update the <filename>/boot</filename> - partition and clear space. - </para> - </section> -</chapter> diff --git a/nixos/doc/manual/administration/control-groups.chapter.md b/nixos/doc/manual/administration/control-groups.chapter.md new file mode 100644 index 00000000000..abe8dd80b5a --- /dev/null +++ b/nixos/doc/manual/administration/control-groups.chapter.md @@ -0,0 +1,59 @@ +# Control Groups {#sec-cgroups} + +To keep track of the processes in a running system, systemd uses +*control groups* (cgroups). A control group is a set of processes used +to allocate resources such as CPU, memory or I/O bandwidth. There can be +multiple control group hierarchies, allowing each kind of resource to be +managed independently. + +The command `systemd-cgls` lists all control groups in the `systemd` +hierarchy, which is what systemd uses to keep track of the processes +belonging to each service or user session: + +```ShellSession +$ systemd-cgls +├─user +│ └─eelco +│ └─c1 +│ ├─ 2567 -:0 +│ ├─ 2682 kdeinit4: kdeinit4 Running... +│ ├─ ... +│ └─10851 sh -c less -R +└─system + ├─httpd.service + │ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH + │ └─... + ├─dhcpcd.service + │ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf + └─ ... +``` + +Similarly, `systemd-cgls cpu` shows the cgroups in the CPU hierarchy, +which allows per-cgroup CPU scheduling priorities. By default, every +systemd service gets its own CPU cgroup, while all user sessions are in +the top-level CPU cgroup. This ensures, for instance, that a thousand +run-away processes in the `httpd.service` cgroup cannot starve the CPU +for one process in the `postgresql.service` cgroup. (By contrast, it +they were in the same cgroup, then the PostgreSQL process would get +1/1001 of the cgroup's CPU time.) You can limit a service's CPU share in +`configuration.nix`: + +```nix +systemd.services.httpd.serviceConfig.CPUShares = 512; +``` + +By default, every cgroup has 1024 CPU shares, so this will halve the CPU +allocation of the `httpd.service` cgroup. + +There also is a `memory` hierarchy that controls memory allocation +limits; by default, all processes are in the top-level cgroup, so any +service or session can exhaust all available memory. Per-cgroup memory +limits can be specified in `configuration.nix`; for instance, to limit +`httpd.service` to 512 MiB of RAM (excluding swap): + +```nix +systemd.services.httpd.serviceConfig.MemoryLimit = "512M"; +``` + +The command `systemd-cgtop` shows a continuously updated list of all +cgroups with their CPU and memory usage. diff --git a/nixos/doc/manual/administration/control-groups.xml b/nixos/doc/manual/administration/control-groups.xml deleted file mode 100644 index 16d03cc0d1a..00000000000 --- a/nixos/doc/manual/administration/control-groups.xml +++ /dev/null @@ -1,65 +0,0 @@ -<chapter 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-cgroups"> - <title>Control Groups</title> - <para> - To keep track of the processes in a running system, systemd uses - <emphasis>control groups</emphasis> (cgroups). A control group is a set of - processes used to allocate resources such as CPU, memory or I/O bandwidth. - There can be multiple control group hierarchies, allowing each kind of - resource to be managed independently. - </para> - <para> - The command <command>systemd-cgls</command> lists all control groups in the - <literal>systemd</literal> hierarchy, which is what systemd uses to keep - track of the processes belonging to each service or user session: -<screen> -<prompt>$ </prompt>systemd-cgls -├─user -│ └─eelco -│ └─c1 -│ ├─ 2567 -:0 -│ ├─ 2682 kdeinit4: kdeinit4 Running... -│ ├─ <replaceable>...</replaceable> -│ └─10851 sh -c less -R -└─system - ├─httpd.service - │ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH - │ └─<replaceable>...</replaceable> - ├─dhcpcd.service - │ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf - └─ <replaceable>...</replaceable> -</screen> - Similarly, <command>systemd-cgls cpu</command> shows the cgroups in the CPU - hierarchy, which allows per-cgroup CPU scheduling priorities. By default, - every systemd service gets its own CPU cgroup, while all user sessions are in - the top-level CPU cgroup. This ensures, for instance, that a thousand - run-away processes in the <literal>httpd.service</literal> cgroup cannot - starve the CPU for one process in the <literal>postgresql.service</literal> - cgroup. (By contrast, it they were in the same cgroup, then the PostgreSQL - process would get 1/1001 of the cgroup’s CPU time.) You can limit a - service’s CPU share in <filename>configuration.nix</filename>: -<programlisting> -<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.CPUShares = 512; -</programlisting> - By default, every cgroup has 1024 CPU shares, so this will halve the CPU - allocation of the <literal>httpd.service</literal> cgroup. - </para> - <para> - There also is a <literal>memory</literal> hierarchy that controls memory - allocation limits; by default, all processes are in the top-level cgroup, so - any service or session can exhaust all available memory. Per-cgroup memory - limits can be specified in <filename>configuration.nix</filename>; for - instance, to limit <literal>httpd.service</literal> to 512 MiB of RAM - (excluding swap): -<programlisting> -<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.httpd.serviceConfig</link>.MemoryLimit = "512M"; -</programlisting> - </para> - <para> - The command <command>systemd-cgtop</command> shows a continuously updated - list of all cgroups with their CPU and memory usage. - </para> -</chapter> diff --git a/nixos/doc/manual/administration/logging.chapter.md b/nixos/doc/manual/administration/logging.chapter.md new file mode 100644 index 00000000000..4ce6f5e9fa7 --- /dev/null +++ b/nixos/doc/manual/administration/logging.chapter.md @@ -0,0 +1,38 @@ +# Logging {#sec-logging} + +System-wide logging is provided by systemd's *journal*, which subsumes +traditional logging daemons such as syslogd and klogd. Log entries are +kept in binary files in `/var/log/journal/`. The command `journalctl` +allows you to see the contents of the journal. For example, + +```ShellSession +$ journalctl -b +``` + +shows all journal entries since the last reboot. (The output of +`journalctl` is piped into `less` by default.) You can use various +options and match operators to restrict output to messages of interest. +For instance, to get all messages from PostgreSQL: + +```ShellSession +$ journalctl -u postgresql.service +-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. -- +... +Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down +-- Reboot -- +Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET +Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections +``` + +Or to get all messages since the last reboot that have at least a +"critical" severity level: + +```ShellSession +$ journalctl -b -p crit +Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice] +Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1) +``` + +The system journal is readable by root and by users in the `wheel` and +`systemd-journal` groups. All users have a private journal that can be +read using `journalctl`. diff --git a/nixos/doc/manual/administration/logging.xml b/nixos/doc/manual/administration/logging.xml deleted file mode 100644 index da4877fcdf0..00000000000 --- a/nixos/doc/manual/administration/logging.xml +++ /dev/null @@ -1,43 +0,0 @@ -<chapter 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-logging"> - <title>Logging</title> - <para> - System-wide logging is provided by systemd’s <emphasis>journal</emphasis>, - which subsumes traditional logging daemons such as syslogd and klogd. Log - entries are kept in binary files in <filename>/var/log/journal/</filename>. - The command <literal>journalctl</literal> allows you to see the contents of - the journal. For example, -<screen> -<prompt>$ </prompt>journalctl -b -</screen> - shows all journal entries since the last reboot. (The output of - <command>journalctl</command> is piped into <command>less</command> by - default.) You can use various options and match operators to restrict output - to messages of interest. For instance, to get all messages from PostgreSQL: -<screen> -<prompt>$ </prompt>journalctl -u postgresql.service --- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. -- -... -Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down --- Reboot -- -Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET -Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections -</screen> - Or to get all messages since the last reboot that have at least a - “critical” severity level: -<screen> -<prompt>$ </prompt>journalctl -b -p crit -Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice] -Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1) -</screen> - </para> - <para> - The system journal is readable by root and by users in the - <literal>wheel</literal> and <literal>systemd-journal</literal> groups. All - users have a private journal that can be read using - <command>journalctl</command>. - </para> -</chapter> diff --git a/nixos/doc/manual/administration/rebooting.chapter.md b/nixos/doc/manual/administration/rebooting.chapter.md new file mode 100644 index 00000000000..ec4b889b164 --- /dev/null +++ b/nixos/doc/manual/administration/rebooting.chapter.md @@ -0,0 +1,30 @@ +# Rebooting and Shutting Down {#sec-rebooting} + +The system can be shut down (and automatically powered off) by doing: + +```ShellSession +# shutdown +``` + +This is equivalent to running `systemctl poweroff`. + +To reboot the system, run + +```ShellSession +# reboot +``` + +which is equivalent to `systemctl reboot`. Alternatively, you can +quickly reboot the system using `kexec`, which bypasses the BIOS by +directly loading the new kernel into memory: + +```ShellSession +# systemctl kexec +``` + +The machine can be suspended to RAM (if supported) using `systemctl suspend`, +and suspended to disk using `systemctl hibernate`. + +These commands can be run by any user who is logged in locally, i.e. on +a virtual console or in X11; otherwise, the user is asked for +authentication. diff --git a/nixos/doc/manual/administration/rebooting.xml b/nixos/doc/manual/administration/rebooting.xml deleted file mode 100644 index c57d885c5f3..00000000000 --- a/nixos/doc/manual/administration/rebooting.xml +++ /dev/null @@ -1,35 +0,0 @@ -<chapter 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-rebooting"> - <title>Rebooting and Shutting Down</title> - <para> - The system can be shut down (and automatically powered off) by doing: -<screen> -<prompt># </prompt>shutdown -</screen> - This is equivalent to running <command>systemctl poweroff</command>. - </para> - <para> - To reboot the system, run -<screen> -<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> -<prompt># </prompt>systemctl kexec -</screen> - </para> - <para> - The machine can be suspended to RAM (if supported) using <command>systemctl - suspend</command>, and suspended to disk using <command>systemctl - hibernate</command>. - </para> - <para> - These commands can be run by any user who is logged in locally, i.e. on a - virtual console or in X11; otherwise, the user is asked for authentication. - </para> -</chapter> diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml index 19bec1f7794..24fd864956f 100644 --- a/nixos/doc/manual/administration/running.xml +++ b/nixos/doc/manual/administration/running.xml @@ -10,12 +10,12 @@ such as how to use the <command>systemd</command> service manager. </para> </partintro> - <xi:include href="service-mgmt.xml" /> - <xi:include href="rebooting.xml" /> - <xi:include href="user-sessions.xml" /> - <xi:include href="control-groups.xml" /> - <xi:include href="logging.xml" /> - <xi:include href="cleaning-store.xml" /> + <xi:include href="../from_md/administration/service-mgmt.chapter.xml" /> + <xi:include href="../from_md/administration/rebooting.chapter.xml" /> + <xi:include href="../from_md/administration/user-sessions.chapter.xml" /> + <xi:include href="../from_md/administration/control-groups.chapter.xml" /> + <xi:include href="../from_md/administration/logging.chapter.xml" /> + <xi:include href="../from_md/administration/cleaning-store.chapter.xml" /> <xi:include href="containers.xml" /> <xi:include href="troubleshooting.xml" /> </part> diff --git a/nixos/doc/manual/administration/service-mgmt.chapter.md b/nixos/doc/manual/administration/service-mgmt.chapter.md new file mode 100644 index 00000000000..bb0f9b62e91 --- /dev/null +++ b/nixos/doc/manual/administration/service-mgmt.chapter.md @@ -0,0 +1,120 @@ +# Service Management {#sec-systemctl} + +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 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 complex dependencies; for instance, one unit can require +that another unit must be successfully started before the first unit can +be started. When the system boots, it starts a unit named +`default.target`; the dependencies of this unit cause all system +services to be started, file systems to be mounted, swap files to be +activated, and so on. + +## Interacting with a running systemd {#sect-nixos-systemd-general} + +The command `systemctl` is the main way to interact with `systemd`. The +following paragraphs demonstrate ways to interact with any OS running +systemd as init system. NixOS is of no exception. The [next section +](#sect-nixos-systemd-nixos) explains NixOS specific things worth +knowing. + +Without any arguments, `systemctl` the status of active units: + +```ShellSession +$ systemctl +-.mount loaded active mounted / +swapfile.swap loaded active active /swapfile +sshd.service loaded active running SSH Daemon +graphical.target loaded active active Graphical Interface +... +``` + +You can ask for detailed status information about a unit, for instance, +the PostgreSQL database service: + +```ShellSession +$ systemctl status postgresql.service +postgresql.service - PostgreSQL Server + Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service) + Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago + Main PID: 2390 (postgres) + CGroup: name=systemd:/system/postgresql.service + ├─2390 postgres + ├─2418 postgres: writer process + ├─2419 postgres: wal writer process + ├─2420 postgres: autovacuum launcher process + ├─2421 postgres: stats collector process + └─2498 postgres: zabbix zabbix [local] idle + +Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET +Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections +Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started +Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server. +``` + +Note that this shows the status of the unit (active and running), all +the processes belonging to the service, as well as the most recent log +messages from the service. + +Units can be stopped, started or restarted: + +```ShellSession +# systemctl stop postgresql.service +# systemctl start postgresql.service +# systemctl restart postgresql.service +``` + +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). + +## systemd in NixOS {#sect-nixos-systemd-nixos} + +Packages in Nixpkgs sometimes provide systemd units with them, usually +in e.g `#pkg-out#/lib/systemd/`. Putting such a package in +`environment.systemPackages` doesn\'t make the service available to +users or the system. + +In order to enable a systemd *system* service with provided upstream +package, use (e.g): + +```nix +systemd.packages = [ pkgs.packagekit ]; +``` + +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 +`services.#name#.enable = true;`. These services are defined in +Nixpkgs\' [ `nixos/modules/` directory +](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules). In case +the service is simple enough, the above method should work, and start +the service on boot. + +*User* systemd services on the other hand, should be treated +differently. Given a package that has a systemd unit file at +`#pkg-out#/lib/systemd/user/`, using [](#opt-systemd.packages) will +make you able to start the service via `systemctl --user start`, but it +won\'t start automatically on login. However, You can imperatively +enable it by adding the package\'s attribute to +[](#opt-systemd.packages) and then do this (e.g): + +```ShellSession +$ mkdir -p ~/.config/systemd/user/default.target.wants +$ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/ +$ systemctl --user daemon-reload +$ systemctl --user enable syncthing.service +``` + +If you are interested in a timer file, use `timers.target.wants` instead +of `default.target.wants` in the 1st and 2nd command. + +Using `systemctl --user enable syncthing.service` instead of the above, +will work, but it\'ll use the absolute path of `syncthing.service` for +the symlink, and this path is in `/nix/store/.../lib/systemd/user/`. +Hence [garbage collection](#sec-nix-gc) 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. diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml deleted file mode 100644 index 863b0d47f6c..00000000000 --- a/nixos/doc/manual/administration/service-mgmt.xml +++ /dev/null @@ -1,140 +0,0 @@ -<chapter 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-systemctl"> - <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 - 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 - complex dependencies; for instance, one unit can require that another unit - must be successfully started before the first unit can be started. When the - system boots, it starts a unit named <literal>default.target</literal>; the - 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> - <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 / -swapfile.swap loaded active active /swapfile -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: -<screen> -<prompt>$ </prompt>systemctl status postgresql.service -postgresql.service - PostgreSQL Server - Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service) - Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago - Main PID: 2390 (postgres) - CGroup: name=systemd:/system/postgresql.service - ├─2390 postgres - ├─2418 postgres: writer process - ├─2419 postgres: wal writer process - ├─2420 postgres: autovacuum launcher process - ├─2421 postgres: stats collector process - └─2498 postgres: zabbix zabbix [local] idle - -Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET -Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections -Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started -Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server. -</screen> - Note that this shows the status of the unit (active and running), all the - processes belonging to the service, as well as the most recent log messages - from the service. - </para> - <para> - Units can be stopped, started or restarted: -<screen> -<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> - <!-- TODO: document cgroups, draft: - each service and user session is a cgroup - - - 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/user-sessions.chapter.md b/nixos/doc/manual/administration/user-sessions.chapter.md new file mode 100644 index 00000000000..5ff468b3012 --- /dev/null +++ b/nixos/doc/manual/administration/user-sessions.chapter.md @@ -0,0 +1,43 @@ +# User Sessions {#sec-user-sessions} + +Systemd keeps track of all users who are logged into the system (e.g. on +a virtual console or remotely via SSH). The command `loginctl` allows +querying and manipulating user sessions. For instance, to list all user +sessions: + +```ShellSession +$ loginctl + SESSION UID USER SEAT + c1 500 eelco seat0 + c3 0 root seat0 + c4 500 alice +``` + +This shows that two users are logged in locally, while another is logged +in remotely. ("Seats" are essentially the combinations of displays and +input devices attached to the system; usually, there is only one seat.) +To get information about a session: + +```ShellSession +$ loginctl session-status c3 +c3 - root (0) + Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago + Leader: 2536 (login) + Seat: seat0; vc3 + TTY: /dev/tty3 + Service: login; type tty; class user + State: online + CGroup: name=systemd:/user/root/c3 + ├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login -- + ├─10339 -bash + └─10355 w3m nixos.org +``` + +This shows that the user is logged in on virtual console 3. It also +lists the processes belonging to this session. Since systemd keeps track +of this, you can terminate a session in a way that ensures that all the +session's processes are gone: + +```ShellSession +# loginctl terminate-session c3 +``` diff --git a/nixos/doc/manual/administration/user-sessions.xml b/nixos/doc/manual/administration/user-sessions.xml deleted file mode 100644 index 9acb147ac1a..00000000000 --- a/nixos/doc/manual/administration/user-sessions.xml +++ /dev/null @@ -1,45 +0,0 @@ -<chapter 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-user-sessions"> - <title>User Sessions</title> - <para> - Systemd keeps track of all users who are logged into the system (e.g. on a - virtual console or remotely via SSH). The command <command>loginctl</command> - allows querying and manipulating user sessions. For instance, to list all - user sessions: -<screen> -<prompt>$ </prompt>loginctl - SESSION UID USER SEAT - c1 500 eelco seat0 - c3 0 root seat0 - c4 500 alice -</screen> - This shows that two users are logged in locally, while another is logged in - remotely. (“Seats” are essentially the combinations of displays and input - devices attached to the system; usually, there is only one seat.) To get - information about a session: -<screen> -<prompt>$ </prompt>loginctl session-status c3 -c3 - root (0) - Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago - Leader: 2536 (login) - Seat: seat0; vc3 - TTY: /dev/tty3 - Service: login; type tty; class user - State: online - CGroup: name=systemd:/user/root/c3 - ├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login -- - ├─10339 -bash - └─10355 w3m nixos.org -</screen> - This shows that the user is logged in on virtual console 3. It also lists the - processes belonging to this session. Since systemd keeps track of this, you - can terminate a session in a way that ensures that all the session’s - processes are gone: -<screen> -<prompt># </prompt>loginctl terminate-session c3 -</screen> - </para> -</chapter> diff --git a/nixos/doc/manual/from_md/administration/boot-problems.section.xml b/nixos/doc/manual/from_md/administration/boot-problems.section.xml index 4ea01e78f32..144661c86eb 100644 --- a/nixos/doc/manual/from_md/administration/boot-problems.section.xml +++ b/nixos/doc/manual/from_md/administration/boot-problems.section.xml @@ -61,7 +61,7 @@ <link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link>). As a motivating example, this could be useful if you’ve forgotten to set - <link xlink:href="options.html#opt-fileSystems._name_.neededForBoot">neededForBoot</link> + <link linkend="opt-fileSystems._name_.neededForBoot">neededForBoot</link> on a file system. </para> </listitem> diff --git a/nixos/doc/manual/from_md/administration/cleaning-store.chapter.xml b/nixos/doc/manual/from_md/administration/cleaning-store.chapter.xml new file mode 100644 index 00000000000..0ca98dd6e51 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/cleaning-store.chapter.xml @@ -0,0 +1,71 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-nix-gc"> + <title>Cleaning the Nix Store</title> + <para> + Nix has a purely functional model, meaning that packages are never + upgraded in place. Instead new versions of packages end up in a + different location in the Nix store (<literal>/nix/store</literal>). + You should periodically run Nix’s <emphasis>garbage + collector</emphasis> to remove old, unreferenced packages. This is + easy: + </para> + <programlisting> +$ nix-collect-garbage +</programlisting> + <para> + Alternatively, you can use a systemd unit that does the same in the + background: + </para> + <programlisting> +# systemctl start nix-gc.service +</programlisting> + <para> + You can tell NixOS in <literal>configuration.nix</literal> to run + this unit automatically at certain points in time, for instance, + every night at 03:15: + </para> + <programlisting language="bash"> +nix.gc.automatic = true; +nix.gc.dates = "03:15"; +</programlisting> + <para> + The commands above do not remove garbage collector roots, such as + old system configurations. Thus they do not remove the ability to + roll back to previous configurations. The following command deletes + old roots, removing the ability to roll back to them: + </para> + <programlisting> +$ nix-collect-garbage -d +</programlisting> + <para> + You can also do this for specific profiles, e.g. + </para> + <programlisting> +$ nix-env -p /nix/var/nix/profiles/per-user/eelco/profile --delete-generations old +</programlisting> + <para> + Note that NixOS system configurations are stored in the profile + <literal>/nix/var/nix/profiles/system</literal>. + </para> + <para> + Another way to reclaim disk space (often as much as 40% of the size + of the Nix store) is to run Nix’s store optimiser, which seeks out + identical files in the store and replaces them with hard links to a + single copy. + </para> + <programlisting> +$ nix-store --optimise +</programlisting> + <para> + Since this command needs to read the entire Nix store, it can take + quite a while to finish. + </para> + <section xml:id="sect-nixos-gc-boot-entries"> + <title>NixOS Boot Entries</title> + <para> + If your <literal>/boot</literal> partition runs out of space, + after clearing old profiles you must rebuild your system with + <literal>nixos-rebuild</literal> to update the + <literal>/boot</literal> partition and clear space. + </para> + </section> +</chapter> diff --git a/nixos/doc/manual/from_md/administration/control-groups.chapter.xml b/nixos/doc/manual/from_md/administration/control-groups.chapter.xml new file mode 100644 index 00000000000..8dab2c9d44b --- /dev/null +++ b/nixos/doc/manual/from_md/administration/control-groups.chapter.xml @@ -0,0 +1,67 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-cgroups"> + <title>Control Groups</title> + <para> + To keep track of the processes in a running system, systemd uses + <emphasis>control groups</emphasis> (cgroups). A control group is a + set of processes used to allocate resources such as CPU, memory or + I/O bandwidth. There can be multiple control group hierarchies, + allowing each kind of resource to be managed independently. + </para> + <para> + The command <literal>systemd-cgls</literal> lists all control groups + in the <literal>systemd</literal> hierarchy, which is what systemd + uses to keep track of the processes belonging to each service or + user session: + </para> + <programlisting> +$ systemd-cgls +├─user +│ └─eelco +│ └─c1 +│ ├─ 2567 -:0 +│ ├─ 2682 kdeinit4: kdeinit4 Running... +│ ├─ ... +│ └─10851 sh -c less -R +└─system + ├─httpd.service + │ ├─2444 httpd -f /nix/store/3pyacby5cpr55a03qwbnndizpciwq161-httpd.conf -DNO_DETACH + │ └─... + ├─dhcpcd.service + │ └─2376 dhcpcd --config /nix/store/f8dif8dsi2yaa70n03xir8r653776ka6-dhcpcd.conf + └─ ... +</programlisting> + <para> + Similarly, <literal>systemd-cgls cpu</literal> shows the cgroups in + the CPU hierarchy, which allows per-cgroup CPU scheduling + priorities. By default, every systemd service gets its own CPU + cgroup, while all user sessions are in the top-level CPU cgroup. + This ensures, for instance, that a thousand run-away processes in + the <literal>httpd.service</literal> cgroup cannot starve the CPU + for one process in the <literal>postgresql.service</literal> cgroup. + (By contrast, it they were in the same cgroup, then the PostgreSQL + process would get 1/1001 of the cgroup’s CPU time.) You can limit a + service’s CPU share in <literal>configuration.nix</literal>: + </para> + <programlisting language="bash"> +systemd.services.httpd.serviceConfig.CPUShares = 512; +</programlisting> + <para> + By default, every cgroup has 1024 CPU shares, so this will halve the + CPU allocation of the <literal>httpd.service</literal> cgroup. + </para> + <para> + There also is a <literal>memory</literal> hierarchy that controls + memory allocation limits; by default, all processes are in the + top-level cgroup, so any service or session can exhaust all + available memory. Per-cgroup memory limits can be specified in + <literal>configuration.nix</literal>; for instance, to limit + <literal>httpd.service</literal> to 512 MiB of RAM (excluding swap): + </para> + <programlisting language="bash"> +systemd.services.httpd.serviceConfig.MemoryLimit = "512M"; +</programlisting> + <para> + The command <literal>systemd-cgtop</literal> shows a continuously + updated list of all cgroups with their CPU and memory usage. + </para> +</chapter> diff --git a/nixos/doc/manual/from_md/administration/logging.chapter.xml b/nixos/doc/manual/from_md/administration/logging.chapter.xml new file mode 100644 index 00000000000..4da38c065a2 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/logging.chapter.xml @@ -0,0 +1,45 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-logging"> + <title>Logging</title> + <para> + System-wide logging is provided by systemd’s + <emphasis>journal</emphasis>, which subsumes traditional logging + daemons such as syslogd and klogd. Log entries are kept in binary + files in <literal>/var/log/journal/</literal>. The command + <literal>journalctl</literal> allows you to see the contents of the + journal. For example, + </para> + <programlisting> +$ journalctl -b +</programlisting> + <para> + shows all journal entries since the last reboot. (The output of + <literal>journalctl</literal> is piped into <literal>less</literal> + by default.) You can use various options and match operators to + restrict output to messages of interest. For instance, to get all + messages from PostgreSQL: + </para> + <programlisting> +$ journalctl -u postgresql.service +-- Logs begin at Mon, 2013-01-07 13:28:01 CET, end at Tue, 2013-01-08 01:09:57 CET. -- +... +Jan 07 15:44:14 hagbard postgres[2681]: [2-1] LOG: database system is shut down +-- Reboot -- +Jan 07 15:45:10 hagbard postgres[2532]: [1-1] LOG: database system was shut down at 2013-01-07 15:44:14 CET +Jan 07 15:45:13 hagbard postgres[2500]: [1-1] LOG: database system is ready to accept connections +</programlisting> + <para> + Or to get all messages since the last reboot that have at least a + <quote>critical</quote> severity level: + </para> + <programlisting> +$ journalctl -b -p crit +Dec 17 21:08:06 mandark sudo[3673]: pam_unix(sudo:auth): auth could not identify password for [alice] +Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature above threshold, cpu clock throttled (total events = 1) +</programlisting> + <para> + The system journal is readable by root and by users in the + <literal>wheel</literal> and <literal>systemd-journal</literal> + groups. All users have a private journal that can be read using + <literal>journalctl</literal>. + </para> +</chapter> diff --git a/nixos/doc/manual/from_md/administration/rebooting.chapter.xml b/nixos/doc/manual/from_md/administration/rebooting.chapter.xml new file mode 100644 index 00000000000..78ee75afb64 --- /dev/null +++ b/nixos/doc/manual/from_md/administration/rebooting.chapter.xml @@ -0,0 +1,38 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-rebooting"> + <title>Rebooting and Shutting Down</title> + <para> + The system can be shut down (and automatically powered off) by + doing: + </para> + <programlisting> +# shutdown +</programlisting> + <para> + This is equivalent to running <literal>systemctl poweroff</literal>. + </para> + <para> + To reboot the system, run + </para> + <programlisting> +# reboot +</programlisting> + <para> + which is equivalent to <literal>systemctl reboot</literal>. + Alternatively, you can quickly reboot the system using + <literal>kexec</literal>, which bypasses the BIOS by directly + loading the new kernel into memory: + </para> + <programlisting> +# systemctl kexec +</programlisting> + <para> + The machine can be suspended to RAM (if supported) using + <literal>systemctl suspend</literal>, and suspended to disk using + <literal>systemctl hibernate</literal>. + </para> + <para> + These commands can be run by any user who is logged in locally, i.e. + on a virtual console or in X11; otherwise, the user is asked for + authentication. + </para> +</chapter> diff --git a/nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml b/nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml new file mode 100644 index 00000000000..8b01b8f896a --- /dev/null +++ b/nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml @@ -0,0 +1,141 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-systemctl"> + <title>Service Management</title> + <para> + In NixOS, all system services are started and monitored using the + systemd program. systemd is the <quote>init</quote> process of the + system (i.e. PID 1), the parent of all other processes. It manages a + set of so-called <quote>units</quote>, which can be things like + system services (programs), but also mount points, swap files, + devices, targets (groups of units) and more. Units can have complex + dependencies; for instance, one unit can require that another unit + must be successfully started before the first unit can be started. + When the system boots, it starts a unit named + <literal>default.target</literal>; the 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> + <section xml:id="sect-nixos-systemd-general"> + <title>Interacting with a running systemd</title> + <para> + The command <literal>systemctl</literal> is the main way to + interact with <literal>systemd</literal>. The following paragraphs + demonstrate ways to interact with any OS running systemd as init + system. NixOS is of no exception. The + <link linkend="sect-nixos-systemd-nixos">next section </link> + explains NixOS specific things worth knowing. + </para> + <para> + Without any arguments, <literal>systemctl</literal> the status of + active units: + </para> + <programlisting> +$ systemctl +-.mount loaded active mounted / +swapfile.swap loaded active active /swapfile +sshd.service loaded active running SSH Daemon +graphical.target loaded active active Graphical Interface +... +</programlisting> + <para> + You can ask for detailed status information about a unit, for + instance, the PostgreSQL database service: + </para> + <programlisting> +$ systemctl status postgresql.service +postgresql.service - PostgreSQL Server + Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service) + Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago + Main PID: 2390 (postgres) + CGroup: name=systemd:/system/postgresql.service + ├─2390 postgres + ├─2418 postgres: writer process + ├─2419 postgres: wal writer process + ├─2420 postgres: autovacuum launcher process + ├─2421 postgres: stats collector process + └─2498 postgres: zabbix zabbix [local] idle + +Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG: database system was shut down at 2013-01-07 15:55:05 CET +Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG: database system is ready to accept connections +Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG: autovacuum launcher started +Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server. +</programlisting> + <para> + Note that this shows the status of the unit (active and running), + all the processes belonging to the service, as well as the most + recent log messages from the service. + </para> + <para> + Units can be stopped, started or restarted: + </para> + <programlisting> +# systemctl stop postgresql.service +# systemctl start postgresql.service +# systemctl restart postgresql.service +</programlisting> + <para> + 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> + </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): + </para> + <programlisting language="bash"> +systemd.packages = [ pkgs.packagekit ]; +</programlisting> + <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. However, You can + imperatively enable it by adding the package's attribute to + <xref linkend="opt-systemd.packages" /> and then do this (e.g): + </para> + <programlisting> +$ mkdir -p ~/.config/systemd/user/default.target.wants +$ ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/ +$ systemctl --user daemon-reload +$ systemctl --user enable syncthing.service +</programlisting> + <para> + 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 linkend="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/from_md/administration/user-sessions.chapter.xml b/nixos/doc/manual/from_md/administration/user-sessions.chapter.xml new file mode 100644 index 00000000000..e8c64f153fc --- /dev/null +++ b/nixos/doc/manual/from_md/administration/user-sessions.chapter.xml @@ -0,0 +1,46 @@ +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-user-sessions"> + <title>User Sessions</title> + <para> + Systemd keeps track of all users who are logged into the system + (e.g. on a virtual console or remotely via SSH). The command + <literal>loginctl</literal> allows querying and manipulating user + sessions. For instance, to list all user sessions: + </para> + <programlisting> +$ loginctl + SESSION UID USER SEAT + c1 500 eelco seat0 + c3 0 root seat0 + c4 500 alice +</programlisting> + <para> + This shows that two users are logged in locally, while another is + logged in remotely. (<quote>Seats</quote> are essentially the + combinations of displays and input devices attached to the system; + usually, there is only one seat.) To get information about a + session: + </para> + <programlisting> +$ loginctl session-status c3 +c3 - root (0) + Since: Tue, 2013-01-08 01:17:56 CET; 4min 42s ago + Leader: 2536 (login) + Seat: seat0; vc3 + TTY: /dev/tty3 + Service: login; type tty; class user + State: online + CGroup: name=systemd:/user/root/c3 + ├─ 2536 /nix/store/10mn4xip9n7y9bxqwnsx7xwx2v2g34xn-shadow-4.1.5.1/bin/login -- + ├─10339 -bash + └─10355 w3m nixos.org +</programlisting> + <para> + This shows that the user is logged in on virtual console 3. It also + lists the processes belonging to this session. Since systemd keeps + track of this, you can terminate a session in a way that ensures + that all the session’s processes are gone: + </para> + <programlisting> +# loginctl terminate-session c3 +</programlisting> +</chapter> |