Merge pull request #129083 from bobby285271/pr12
nixos/doc: convert Chapter 49, 50, 51, 52, 53, 54 to CommonMark
This commit is contained in:
Jörg Thalheim
GitHub
commit
c0735214e1
@ -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`
|
||||
|
||||
|
||||
62
nixos/doc/manual/administration/cleaning-store.chapter.md
Normal file
62
nixos/doc/manual/administration/cleaning-store.chapter.md
Normal file
@ -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.
|
||||
@ -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>
|
||||
59
nixos/doc/manual/administration/control-groups.chapter.md
Normal file
59
nixos/doc/manual/administration/control-groups.chapter.md
Normal file
@ -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.
|
||||
@ -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>
|
||||
38
nixos/doc/manual/administration/logging.chapter.md
Normal file
38
nixos/doc/manual/administration/logging.chapter.md
Normal file
@ -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`.
|
||||
@ -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>
|
||||
30
nixos/doc/manual/administration/rebooting.chapter.md
Normal file
30
nixos/doc/manual/administration/rebooting.chapter.md
Normal file
@ -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.
|
||||
@ -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>
|
||||
@ -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>
|
||||
|
||||
120
nixos/doc/manual/administration/service-mgmt.chapter.md
Normal file
120
nixos/doc/manual/administration/service-mgmt.chapter.md
Normal file
@ -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.
|
||||
@ -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>
|
||||
|
||||
43
nixos/doc/manual/administration/user-sessions.chapter.md
Normal file
43
nixos/doc/manual/administration/user-sessions.chapter.md
Normal file
@ -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
|
||||
```
|
||||
@ -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>
|
||||
@ -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>
|
||||
|
||||
@ -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>
|
||||
@ -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>
|
||||
45
nixos/doc/manual/from_md/administration/logging.chapter.xml
Normal file
45
nixos/doc/manual/from_md/administration/logging.chapter.xml
Normal file
@ -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>
|
||||
@ -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>
|
||||
141
nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml
Normal file
141
nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml
Normal file
@ -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>
|
||||
@ -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>
|
||||
Loading…
Reference in New Issue
Block a user