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 @@ - - Cleaning the Nix Store - - 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: - -$ nix-collect-garbage - - Alternatively, you can use a systemd unit that does the same in the - background: - -# 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: - - = true; - = "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: - -$ nix-collect-garbage -d - - You can also do this for specific profiles, e.g. - -$ 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. - -$ nix-store --optimise - - Since this command needs to read the entire Nix store, it can take quite a - while to finish. - -
- NixOS 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/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 @@ - - Control Groups - - 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: - -$ 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: - -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): - -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/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 @@ - - 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, - -$ 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: - -$ 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: - -$ 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/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 @@ - - Rebooting and Shutting Down - - The system can be shut down (and automatically powered off) by doing: - -# shutdown - - This is equivalent to running systemctl poweroff. - - - To reboot the system, run - -# 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: - -# 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/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 systemd service manager. - - - - - - + + + + + + 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 @@ - - Service Management - - 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 - - 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 - explains NixOS specific things worth knowing. - - - Without any arguments, systmctl the status of active units: - -$ 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: - -$ 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: - -# 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 - - 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): - - = [ 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 . 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 - 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 - - systemd.packages and then do this (e.g): - -$ 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 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/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 @@ - - 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: - -$ 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: - -$ 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: - -# loginctl terminate-session c3 - - - 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 @@ neededForBoot). As a motivating example, this could be useful if you’ve forgotten to set - neededForBoot + neededForBoot on a file system. 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 @@ + + Cleaning the Nix Store + + 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: + + +$ nix-collect-garbage + + + Alternatively, you can use a systemd unit that does the same in the + background: + + +# 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.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: + + +$ nix-collect-garbage -d + + + You can also do this for specific profiles, e.g. + + +$ 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. + + +$ nix-store --optimise + + + Since this command needs to read the entire Nix store, it can take + quite a while to finish. + +
+ NixOS 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/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 @@ + + Control Groups + + 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: + + +$ 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: + + +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): + + +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/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 @@ + + 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, + + +$ 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: + + +$ 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: + + +$ 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/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 @@ + + Rebooting and Shutting Down + + The system can be shut down (and automatically powered off) by + doing: + + +# shutdown + + + This is equivalent to running systemctl poweroff. + + + To reboot the system, run + + +# 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: + + +# 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/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 @@ + + Service Management + + 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 + + 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 + explains NixOS specific things worth knowing. + + + Without any arguments, systemctl the status of + active units: + + +$ 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: + + +$ 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: + + +# 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 + + 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): + + +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 . 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 + 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 + and then do this (e.g): + + +$ 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 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/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 @@ + + 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: + + +$ 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: + + +$ 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: + + +# loginctl terminate-session c3 + +