nixos: nixos/doc/manual/administration/service-mgmt.xml to CommonMark

4 files changed, 264 insertions, 141 deletions

diff --git a/nixos/doc/manual/administration/running.xml b/nixos/doc/manual/administration/running.xml
index 19bec1f7794..73dff469192 100644
--- a/nixos/doc/manual/administration/running.xml
+++ b/nixos/doc/manual/administration/running.xml
@@ -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" />
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..ba5c4cf15d5
--- /dev/null
+++ b/nixos/doc/manual/administration/service-mgmt.chapter.md
@@ -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.
diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml
deleted file mode 100644
index 863b0d47f6c..00000000000
--- a/nixos/doc/manual/administration/service-mgmt.xml
+++ /dev/null
@@ -1,140 +0,0 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="sec-systemctl">
- <title>Service Management</title>
- <para>
-  In NixOS, all system services are started and monitored using the systemd
-  program. systemd is the “init” process of the system (i.e. PID 1), the
-  parent of all other processes. It manages a set of so-called “units”,
-  which can be things like system services (programs), but also mount points,
-  swap files, devices, targets (groups of units) and more. Units can have
-  complex dependencies; for instance, one unit can require that another unit
-  must be successfully started before the first unit can be started. When the
-  system boots, it starts a unit named <literal>default.target</literal>; the
-  dependencies of this unit cause all system services to be started, file
-  systems to be mounted, swap files to be activated, and so on.
- </para>
- <section xml:id="sect-nixos-systemd-general">
-  <title>Interacting with a running systemd</title>
-   <para>
-    The command <command>systemctl</command> is the main way to interact with
-    <command>systemd</command>. The following paragraphs demonstrate ways to
-    interact with any OS running systemd as init system. NixOS is of no
-    exception. The <link xlink:href="#sect-nixos-systemd-nixos">next section
-    </link> explains NixOS specific things worth knowing.
-   </para>
-   <para>
-    Without any arguments, <literal>systmctl</literal> the status of active units:
-<screen>
-<prompt>$ </prompt>systemctl
--.mount          loaded active mounted   /
-swapfile.swap    loaded active active    /swapfile
-sshd.service     loaded active running   SSH Daemon
-graphical.target loaded active active    Graphical Interface
-<replaceable>...</replaceable>
-</screen>
-  </para>
-  <para>
-   You can ask for detailed status information about a unit, for instance, the
-   PostgreSQL database service:
-<screen>
-<prompt>$ </prompt>systemctl status postgresql.service
-postgresql.service - PostgreSQL Server
-          Loaded: loaded (/nix/store/pn3q73mvh75gsrl8w7fdlfk3fq5qm5mw-unit/postgresql.service)
-          Active: active (running) since Mon, 2013-01-07 15:55:57 CET; 9h ago
-        Main PID: 2390 (postgres)
-          CGroup: name=systemd:/system/postgresql.service
-                  ├─2390 postgres
-                  ├─2418 postgres: writer process
-                  ├─2419 postgres: wal writer process
-                  ├─2420 postgres: autovacuum launcher process
-                  ├─2421 postgres: stats collector process
-                  └─2498 postgres: zabbix zabbix [local] idle
-
-Jan 07 15:55:55 hagbard postgres[2394]: [1-1] LOG:  database system was shut down at 2013-01-07 15:55:05 CET
-Jan 07 15:55:57 hagbard postgres[2390]: [1-1] LOG:  database system is ready to accept connections
-Jan 07 15:55:57 hagbard postgres[2420]: [1-1] LOG:  autovacuum launcher started
-Jan 07 15:55:57 hagbard systemd[1]: Started PostgreSQL Server.
-</screen>
-  Note that this shows the status of the unit (active and running), all the
-  processes belonging to the service, as well as the most recent log messages
-  from the service.
- </para>
- <para>
-  Units can be stopped, started or restarted:
-<screen>
-<prompt># </prompt>systemctl stop postgresql.service
-<prompt># </prompt>systemctl start postgresql.service
-<prompt># </prompt>systemctl restart postgresql.service
-</screen>
-   These operations are synchronous: they wait until the service has finished
-   starting or stopping (or has failed). Starting a unit will cause the
-   dependencies of that unit to be started as well (if necessary).
-  </para>
-  <!-- TODO: document cgroups, draft:
-   each service and user session is a cgroup
-
-   - cgroup resource management -->
- </section>
- <section xml:id="sect-nixos-systemd-nixos">
-  <title>systemd in NixOS</title>
-  <para>
-   Packages in Nixpkgs sometimes provide systemd units with them, usually in
-   e.g <literal>#pkg-out#/lib/systemd/</literal>. Putting such a package in
-   <literal>environment.systemPackages</literal> doesn't make the service
-   available to users or the system.
-  </para>
-  <para>
-   In order to enable a systemd <emphasis>system</emphasis> service with
-   provided upstream package, use (e.g):
-<programlisting>
-<xref linkend="opt-systemd.packages"/> = [ pkgs.packagekit ];
-</programlisting>
-  </para>
-  <para>
-   Usually NixOS modules written by the community do the above, plus take care of
-   other details. If a module was written for a service you are interested in,
-   you'd probably need only to use
-   <literal>services.#name#.enable = true;</literal>. These services are defined
-   in Nixpkgs'
-   <link xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/modules">
-   <literal>nixos/modules/</literal> directory </link>. In case the service is
-   simple enough, the above method should work, and start the service on boot.
-  </para>
-  <para>
-   <emphasis>User</emphasis> systemd services on the other hand, should be
-   treated differently. Given a package that has a systemd unit file at
-   <literal>#pkg-out#/lib/systemd/user/</literal>, using
-   <xref linkend="opt-systemd.packages"/> will make you able to start the service via
-   <literal>systemctl --user start</literal>, but it won't start automatically on login.
-   <!-- TODO: Document why systemd.packages doesn't work for user services or fix this.
-   https://github.com/NixOS/nixpkgs/blob/2cd6594a8710a801038af2b72348658f732ce84a/nixos/modules/system/boot/systemd-lib.nix#L177-L198
-
-   This has been talked over at https://discourse.nixos.org/t/how-to-enable-upstream-systemd-user-services-declaratively/7649/5
-   -->
-   However, You can imperatively enable it by adding the package's attribute to
-   <link linkend="opt-environment.systemPackages">
-   <literal>systemd.packages</literal></link> and then do this (e.g):
-<screen>
-<prompt>$ </prompt>mkdir -p ~/.config/systemd/user/default.target.wants
-<prompt>$ </prompt>ln -s /run/current-system/sw/lib/systemd/user/syncthing.service ~/.config/systemd/user/default.target.wants/
-<prompt>$ </prompt>systemctl --user daemon-reload
-<prompt>$ </prompt>systemctl --user enable syncthing.service
-</screen>
-   If you are interested in a timer file, use <literal>timers.target.wants</literal>
-   instead of <literal>default.target.wants</literal> in the 1st and 2nd command.
-  </para>
-  <para>
-   Using <literal>systemctl --user enable syncthing.service</literal> instead of
-   the above, will work, but it'll use the absolute path of
-   <literal>syncthing.service</literal> for the symlink, and this path is in
-   <literal>/nix/store/.../lib/systemd/user/</literal>. Hence
-   <link xlink:href="#sec-nix-gc">garbage collection</link> will remove that file
-   and you will wind up with a broken symlink in your systemd configuration, which
-   in turn will not make the service / timer start on login.
-  </para>
- </section>
-</chapter>
-
diff --git a/nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml b/nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml
new file mode 100644
index 00000000000..0e1fceb50d0
--- /dev/null
+++ b/nixos/doc/manual/from_md/administration/service-mgmt.chapter.xml
@@ -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>