Adding Systemd content for Fedora docs hackfest

en-US/modules/concept_systemd.adoc

@@ -0,0 +1,51 @@
+[#systemd]
+= Systemd
+
+Systemd is a system and service manager for Linux, compatible with SysV and LSB init scripts. Systemd provides:
+
+* Aggressive parallelization capabilities
+* Uses socket and D-Bus activation for starting services
+* Offers on-demand starting of daemons, keeps track of processes using Linux cgroups
+* Supports snapshotting and restoring of the system state
+* Maintains mount and automount points
+* Implements an elaborate transactional dependency-based service control logic.
+
+The `systemctl` command is the primary tool to manage Systemd. It combines the functionality of SysVinit's `service` and `chkconfig` commands into a single tool you can use to enable and disable services permanently or only for the current session.
+
+Systemd manages _units_, which are representations of system resources and services. This following list shows the unit types that Systemd can manage:
+
+service::
+  A service on the system, including instructions for starting, restarting, and stopping the service.
+
+socket::
+  A network socket associated with a service.
+
+device::
+  A device specifically managed with Systemd.
+
+mount::
+  A mountpoint managed with Systemd.
+
+automount::
+  A mountpoint automatically mounted on boot.
+  
+swap::
+  Swap space on the system.
+
+target::
+  A synchronization point for other units. Usually used to start enabled services on boot.
+
+path::
+  A path for path-based activation. For example, you can start services based on the state of a certain path, such as whether it exists or not.
+
+timer::
+  A timer to schedule activation of another unit.
+
+snapshot::
+  A snapshot of the current Systemd state. Usually used to rollback after making temporary changes to Systemd.
+
+slice::
+  Restrivtion of resources through Linux Control Group nodes (cgroups).
+
+scope::
+  Information from Systemd bus interfaces. Usually used to manage external system processes.

en-US/modules/proc_converting-sysvinit-services.adoc

@@ -0,0 +1,93 @@
+[#converting-sysvinit-services]
+= Converting SysVinit services
+
+Older versions of Fedora use SysVinit scripts to manage services. This section provides some guidelines on how to convert a SysVinit script to a Systemd equivalent.
+
+.Prerequisites
+
+* You are logged in as a user with administrator-level permissions.
+
+* You have a custom SysVinit script to convert to a Systemd configuration.
+
+.Procedure
+
+. Identify the runlevels in your SysVinit script. This is usually defined with `chkconfig` directive in the commented section at the beginning of the script. For example, the following indicates the service is using runlevels 3, 4, and 5:
++
+----
+# chkconfig: 235 20 80
+----
++
+Systemd uses targets instead of runlevels. Use the table in <<#converting-sysvinit-services>> to map the runlevels to targets. In this example, runlevels 2, 3, and 5 are all multi-user runlevels, so the Systemd service can use the following:
++
+----
+[Install]
+WantedBy=multi-user.target
+----
++
+If you enable the custom Systemd service to start at boot (`systemctl enable foo.service`), Systemd loads the service when loading the `multi-user.target` at boot time.
+
+. Identify the dependent services and targets. For example, if the custom service requires network connectivity, specify the `network.target` as a dependency:
++
+----
+[Unit]
+Description=My custom service
+Requires=network.target
+----
+
+. Identify the command used to start the service in the SysVinit script and convert this to the Systemd equivalent. For example, the script might contain a `start` function in the following format:
++
+----
+start() {
+	echo "Starting My Custom Service..."
+  /usr/bin/myservice -D
+}
+----
++
+In this example, the `/usr/bin/myservice` command is the custom service command set to daemonize with the `-D` option. Set the `ExecStart` parameter to use this command:
++
+----
+[Service]
+ExecStart=/usr/bin/myservice -D
+----
+
+. Check the SysVinit script to see if the service uses a special command to restart the service. For example, the script might contain a `reboot` function that reloads the service:
++
+----
+reboot() {
+	echo "Reloading My Custom Service..."
+  /usr/bin/myservice reload
+}
+----
++
+In this example, the `/usr/bin/myservice` command is the custom service command and reloads the service using the `reload` subcommand. Set the `ExecReload` parameter to use this command:
++
+----
+[Service]
+ExecReload=/usr/bin/myservice reload
+----
++
+Alternatively, you can omit `ExecReload` and use the default behavior, which kills the service and starts it again.
+
+. Check the SysVinit script to see if the service uses a special command to stop the service. For example, the script might contain a `stop` function that reloads the service:
++
+----
+reboot() {
+	echo "Stopping My Custom Service..."
+  /usr/bin/myservice shutdown
+}
+----
++
+In this example, the `/usr/bin/myservice` command is the custom service command and stop the service gracefully using the `shutdown` subcommand. Set the `ExecStop` parameter to use this command:
++
+----
+[Service]
+ExecStop=/usr/bin/myservice shutdown
+----
++
+Alternatively, you can omit `ExecStop` and use the default behavior, which kills the service.
+
+. Review the SysVinit script and identify any additional parameters or functions. Use Systemd parameters to replicate any identified SysVinit functions that might be relevant to your service.
+
+.Related Information
+
+* See <<#common-service-parameters>> for more information about the parameters used in this procedure.

en-US/modules/proc_creating-new-systemd-services.adoc

@@ -0,0 +1,97 @@
+[#creating-new-systemd-services]
+= Creating new Systemd services
+
+This example shows how to create a unit file for a custom service. Custom unit files are located in `/etc/systemd/system/` and have a `.service` extension. For example, a custom `foo` service uses `/etc/systemd/system/foo.service` unit file.
+
+.Prerequisites
+
+* You are logged in as a user with administrator-level permissions.
+
+.Procedure
+
+This procedure creates a basic configuration file to control the `foo` service.
+
+. Create and edit the new configuration file:
++
+----
+$ sudo vi /etc/systemd/system/foo.service
+----
+
+. The next few steps describe each section its parameters to add to the file:
+
+.. The `[Unit]` section provides basic information about the service. The `foo` service uses the following parameters:
++
+`Description`::
+  A string describing the unit. Systemd displays this description next to the unit name in the user interface. 
+`Requires`::
+  Defines unit to use as a dependency for the service. If you activate the unit, Systemd activates the units listed in `Requires` as well. For example, the `foo` service might require network connectivity, which means the `foo` services requires `network.target` as a dependency. 
++
+The resulting `[Unit]` section looks like this:
++
+----
+[Unit]
+Description=My custom service
+Requires=network.target
+----
+
+.. The `[Service]` section provides instructions on how to control the service. The `foo` service uses the following parameters:
++
+`Type`::
+  Defines the type of Systemd service. In this example, the `foo` service is a `simple` service, which starts the service without any special consideration.
+`ExecStart`::
+  The command to run to start the service. This includes the full path to the command and arguments to modify the service.
++
+The resulting `[Service]` section looks like this:
++
+----
+[Service]
+Type=simple
+ExecStart=/usr/bin/sleep infinity
+----
+
+.. The `[Install]` section provides instructions on how Systemd installs the service. The `foo` service uses the following parameters:
++
+`WantedBy`::
+  Defines which service triggers the custom service if enabled with `systemctl enable`. This is mostly used for starting the custom service on boot. In this example, `foo.service` uses `multi-user.target`, which starts `foo.service` when Systemd loads `multi-user.target` on boot.
+
+. The full `foo.service` file contains the following contents:
++
+----
+[Unit]
+Description=My custom service
+Requires=network.target
+
+[Service]
+Type=simple
+ExecStart=/usr/bin/sleep infinity
+
+[Install]
+WantedBy=multi-user.target
+----
++
+Save the file.
+
+. Start the custom `foo` service:
++
+----
+$ sudo systemctl start foo
+----
+
+. Check the status of the service to ensure the service is running:
++
+----
+$ systemctl status foo
+● foo.service - My custom service
+   Loaded: loaded (/etc/systemd/system/foo.service; static; vendor preset: disabled)
+   Active: active (running) since Thu 2017-12-14 14:09:12 AEST; 6s ago
+ Main PID: 31837 (sleep)
+    Tasks: 1 (limit: 4915)
+   CGroup: /system.slice/foo.service
+           └─31837 /usr/bin/sleep infinity
+
+Dec 14 14:09:12 dansmachine systemd[1]: Started My custom service.
+----
+
+.Related Information
+
+* See <<#common-service-parameters>> for more information about the parameters used in this procedure.

en-US/modules/proc_modifying-existing-systemd-services.adoc

@@ -0,0 +1,44 @@
+[#modifying-existing-systemd-services]
+= Modifying existing Systemd services
+
+This example shows how to modify an existing service. The files for service modification are stored in a directory within `/etc/systemd/system`. This directory is named after the service. For example, this procedure modifies the `httpd` service.
+
+.Prerequisites
+
+* You are logged in as a user with administrator-level permissions.
+
+* You have a configured `httpd` server running through Systemd.
+
+.Procedure
+
+. Create a directory for the service modification in the following format: `[SERVICE NAME].service.d`. For example, the directory for the `httpd.service` modification is `httpd.service.d`:
++
+----
+$ sudo mkdir /etc/systemd/system/httpd.service.d/
+----
+
+. Create a configuration file within this directory:
++
+----
+$ sudo vi /etc/systemd/system/httpd.service.d/custom.conf
+----
+
+. Add your custom configuration. For example:
++
+----
+[Service]
+Restart=always
+RestartSec=30
+----
+
+. Save the file.
+
+. Restart the `httpd` service:
++
+----
+$ sudo systemctl restart httpd
+----
+
+.Related Information
+
+* See <<#common-service-parameters>> for more information about the parameters used in this procedure.

en-US/modules/proc_starting-stopping-and-querying-systemd-services.adoc

@@ -0,0 +1,64 @@
+[#starting-stopping-and-querying-systemd-services]
+= Starting, stopping, and querying Systemd services
+
+You can perform various management tasks to control Systemd services using the `systemctl` command. The following is a set of example commands to demonstrate how to use `systemctl` to manage Systemd services.
+
+.Prerequisites
+
+* You are logged in as a user with administrator-level permissions.
+
+.Procedure
+
+The following commands control the `foo` service:
+
+* Activate a service immediately:
++
+----
+$ sudo systemctl start foo 
+----
+
+* Deactivate a service immediately:
++
+----
+$ sudo systemctl stop foo 
+----
+
+* Restart a service:
++
+----
+$ sudo systemctl restart foo 
+----
+
+* Show the status of a service including if it is running or not:
++
+----
+$ sudo systemctl status foo 
+----
+
+* Enable a service to be started on bootup:
++
+----
+$ sudo systemctl enable foo 
+----
+
+* Disable a service to not start during bootup:
++
+----
+$ sudo systemctl disable foo 
+----
+
+* Prevent a service from starting dynamically or even manually unless unmasked:
++
+----
+$ sudo systemctl mask foo 
+----
+
+* Check if a service is already enabled or not:
++
+----
+$ sudo systemctl is-enabled foo
+----
+
+.Related Information
+
+* Run `man systemctl` for more details.

en-US/modules/ref_common-service-parameters.adoc

@@ -0,0 +1,118 @@
+[#common-service-parameters]
+= Common service parameters
+
+.Unit Parameters
+
+This section contains parameters you can use in the `[Unit]` section of a service. These parameters are common to other Systemd units.
+
+This list is a summarized version. For a full list of these parameters and their descriptions, run `man systemd.unit`.
+
+Description::
+  A free-form string describing the service. 
+
+Documentation::
+  A space-separated list of URIs referencing documentation for this service or its configuration. Accepted are only URIs of the following types: `http://`, `https://`, `file:`, `info:`, `man:`. 
+
+Requires::
+  Configures requirement dependencies on other services. If this service gets activated, the units listed here are activated too. If one of the dependent services fails to activate, Systemd does not start this service. This option may be specified more than once or you can specify multiple space-separated units.
+
+Wants::
+  Similar to `Requires`, except failed units do not have any effect on the service.
+
+BindsTo::
+  Similar to `Requires`, except stopping the dependent units also stops the service.
+
+PartOf::
+  Similar to `Requires`, except the stopping and restarting dependent units also stop and restart the service.
+
+Conflicts::
+  A space-separated list of unit names that, if running, cause the service not to run.
+
+Before, After::
+  A space-separated list of unit names that configures the ordering of dependencies between services.
+
+OnFailure::
+  A space-separated list of unit names that are activated when this service enters a failed state.
+
+.Install Parameters
+
+This section contains parameters you can use in the `[Install]` section of a service. These parameters are common to other Systemd units.
+
+This list is a summarized version. For a full list of these parameters and their descriptions, run `man systemd.unit`.
+
+Alias::
+    A space-separated list of additional names this service shall be installed under. The names listed here must have the same suffix (i.e. type) as the service filename.
+
+RequiredBy, WantedBy::
+    Defines the service as dependent of another service. This usually define the target to trigger an enabled service to run. These options are analogous to the `Requires` and `Wants` in the `[Units]` section.
+
+Also::
+    Additional units to install or uninstall when this service is installed or uninstalled.
+
+.Service Parameters
+
+This section contains parameters you can use in the `[Service]` section of a service unit. These parameters are specific only to Systemd service units.
+
+This list is a summarized version. For a full list of these parameters and their descriptions, run `man systemd.unit`.
+
+Type::
+  Configures the process start-up type for this service service:
++
+* `simple` - The service starts as the main process. This is the default.
+* `forking` - The service calls forked processes and run as part of the main daemon.
+* `oneshot` - Similar to `simple`, except the process must exits before Systemd starts follow-up services.
+* `dbus` - Similar to `simple`, except the daemon acquires a name of the D-Bus bus.
+* `notify` - Similar to `simple`, except the daemon sends a motification message using `sd_notify` or an equivalent call after starting up.
+* `idle` - Similar to `simple`, except the execution of the service is delayed until all active jobs are dispatched.
+
+RemainAfterExit::
+  A boolean value that specifies whether the service shall be considered active even if all its processes exited. Defaults to no.
+
+GuessMainPID::
+  A boolean value that specifies whether Systemd should guess the main PID of a service if it cannot be determined reliably. This option is ignored unless `Type=forking` is set and `PIDFile` is not set. Defaults to yes.
+
+PIDFile::
+  An absolute filename pointing to the PID file of this daemon. Use of this option is recommended for services where `Type=forking`. Systemd reads the PID of the main process of the daemon after start-up of the service. Systemd does not write to the file configured here, although it removes the file after the service has shut down. 
+
+BusName::
+  A D-Bus bus name to reach this service. This option is mandatory for services where `Type=dbus`.
+
+ExecStart::
+  The commands and arguments executed when the service starts.
+
+ExecStartPre, ExecStartPost::
+  Additional commands that are executed before or after the command in `ExecStart`.
+
+ExecReload::
+  The commands and arguments to execute when the service reloads.
+
+ExecStop::
+  The commands and arguments to execute when the service stops. 
+
+ExecStopPost::
+  Additional commands to executed after the service stops.
+
+RestartSec::
+  The time in seconds to sleep before restarting a service.
+
+TimeoutStartSec::
+  The time in seconds to wait for the service to start.
+
+TimeoutStopSec::
+  The time in seconds to wait for the service to stop.
+
+TimeoutSec::
+  A shorthand for configuring both `TimeoutStartSec` and `TimeoutStopSec` simultaneously. 
+
+RuntimeMaxSec::
+  A maximum time in seconds for the service to run. Pass `infinity` (the default) to configure no runtime limit.
+
+Restart::
+  Configures whether to restart the service when the service's process exits, is killed, or reaches a timeout:
++
+* `no` - The service will not be restarted. This is the default.
+* `on-success` - Restart only when the service process exits cleanly (exit code 0).
+* `on-failure` - Restart only when the service process does not exit cleanly (node-zero exit code).
+* `on-abnormal` - Restart if the process terminates with a signal or when a timeout occurs.
+* `on-abort` - Restart if the process exits due to an uncaught signal not specified as a clean exit status.
+* `always` - Always restart.

en-US/modules/ref_mapping-runlevel-to-targets.adoc

@@ -0,0 +1,31 @@
+[#mapping-runlevels-to-targets]
+= Mapping runlevels to targets
+
+Systemd targets serve a similar purpose to SysVinit runlevels but act a little different. Each target has a name instead of a number and each serves a specific purpose. Systemd implements some targets by inheriting all of the services of another target and adding additional services to it. Some Systemd targets mimic the common sysvinit runlevels, which means you can switch targets with the familiar `telinit RUNLEVEL` command. The runlevels assigned a specific purpose on vanilla Fedora installs (0, 1, 3, 5, and 6) have a 1:1 mapping with a specific systemd target.
+
+However, this is not the case for user-defined runlevels 2 and 4. To make use of those runlevels, create a new named systemd target such as `/etc/systemd/system/$YOURTARGET` that takes one of the existing runlevels as a base, make a directory `/etc/systemd/system/$YOURTARGET.wants`, and then symlink the additional services to enable into that directory.
+
+The following is a mapping of SysVinit runlevels to Systemd targets.
+
+[cols="2,5,5",options="header"]
+.Runlevel to target mapping
+|===
+|Sysvinit Runlevel |Systemd Target |Notes
+
+|0 |runlevel0.target, poweroff.target |Halt the system.
+
+|1, s, single |runlevel1.target, rescue.target |Single user mode.
+
+|2, 4 |runlevel2.target, runlevel4.target, multi-user.target
+|User-defined/Site-specific runlevels. By default, identical to 3.
+
+|3 |runlevel3.target, multi-user.target |Multi-user, non-graphical.
+Users can usually login via multiple consoles or via the network.
+
+|5 |runlevel5.target, graphical.target |Multi-user, graphical. Usually
+has all the services of runlevel 3 plus a graphical login.
+
+|6 |runlevel6.target, reboot.target |Reboot
+
+|emergency |emergency.target |Emergency shell
+|===

en-US/modules/ref_mapping-service-commands.adoc

@@ -0,0 +1,62 @@
+[#mapping-service-commands]
+= Mapping service commands
+
+The following table demonstrates the Systemd equivalent of SysVinit commands.
+
+[NOTE]
+All recent versions of systemctl assume the '.service' suffix if left off the service name. For example, 'systemctl start frobozz.service' is the same as 'systemctl start frobozz'
+
+[cols=",,",options="header",]
+|===
+|Sysvinit Command |Systemd Command |Notes
+|service frobozz start |systemctl start frobozz |Used to start a service
+(not reboot persistent)
+
+|service frobozz stop |systemctl stop frobozz |Used to stop a service
+(not reboot persistent)
+
+|service frobozz restart |systemctl restart frobozz |Used to stop and
+then start a service
+
+|service frobozz reload |systemctl reload frobozz |When supported,
+reloads the config file without interrupting pending operations.
+
+|service frobozz condrestart |systemctl condrestart frobozz |Restarts if
+the service is already running.
+
+|service frobozz status |systemctl status frobozz |Tells whether a
+service is currently running.
+
+|ls /etc/rc.d/init.d/ |systemctl (or) systemctl list-unit-files
+--type=service (or) +
+ls /lib/systemd/system/*.service /etc/systemd/system/*.service |Used to
+list the services that can be started or stopped +
+Used to list all the services and other units
+
+|chkconfig frobozz on |systemctl enable frobozz |Turn the service on,
+for start at next boot, or other trigger.
+
+|chkconfig frobozz off |systemctl disable frobozz |Turn the service off
+for the next reboot, or any other trigger.
+
+|chkconfig frobozz |systemctl is-enabled frobozz |Used to check whether
+a service is configured to start or not in the current environment.
+
+|chkconfig --list |systemctl list-unit-files --type=service (or) ls
+/etc/systemd/system/*.wants/ |Print a table of services that lists which
+runlevels each is configured on or off
+
+|chkconfig --list | grep 5:on |systemctl list-dependencies
+graphical.target |Print a table of services that will be started when
+booting into graphical mode
+
+|chkconfig frobozz --list |ls
+/etc/systemd/system/*.wants/frobozz.service |Used to list what levels
+this service is configured on or off
+
+|chkconfig frobozz --add |systemctl daemon-reload |Used when you create
+a new service file or modify any configuration
+|===
+
+[NOTE]
+All `/sbin/service` and `/sbin/chkconfig` commands listed in the table continue to work on Systemd-based systems and are translated to native equivalents as necessary. The only exception is `chkconfig --list`.