mirror of
https://github.com/NixOS/nixpkgs.git
synced 2025-04-17 04:48:38 +00:00
nixos: nixos/doc/manual/administration/service-mgmt.xml to CommonMark
This commit is contained in:
Bobby Rong
parent
7918dc5148
commit
d37933c01f
@ -10,7 +10,7 @@
|
||||
such as how to use the <command>systemd</command> service manager.
|
||||
</para>
|
||||
</partintro>
|
||||
<xi:include href="service-mgmt.xml" />
|
||||
<xi:include href="../from_md/administration/service-mgmt.chapter.xml" />
|
||||
<xi:include href="rebooting.xml" />
|
||||
<xi:include href="user-sessions.xml" />
|
||||
<xi:include href="control-groups.xml" />
|
||||
|
||||
121
nixos/doc/manual/administration/service-mgmt.chapter.md
Normal file
121
nixos/doc/manual/administration/service-mgmt.chapter.md
Normal file
@ -0,0 +1,121 @@
|
||||
# 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, `systmctl` 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 [
|
||||
`systemd.packages`](#opt-environment.systemPackages) 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>
|
||||
|
||||
142
nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml
Normal file
142
nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml
Normal file
@ -0,0 +1,142 @@
|
||||
<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>systmctl</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
|
||||
<link linkend="opt-environment.systemPackages">
|
||||
<literal>systemd.packages</literal></link> 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>
|
||||
Loading…
Reference in New Issue
Block a user