Skip to content

Commit

Permalink
[WIP]: systemd management -article (#255)
Browse files Browse the repository at this point in the history 
* assembly and DC file

* corrects the validation errors

* changes

* moves the topic from ref to task

* adds troubleshoot topic

* adds two skeletal framework task topics for enable and start topics

* adds content for enabling services

* add content for start systemd

* adds content for best pract and modifies assm file

* adds more content

* adds more content

* managing systemd targets

* systemd targets

* managing target commands

* content

* adds more information

* more content

* adds refs for systemd

* checklist

* adds systemd targets

* final touches

* part 1-review feedback

* review feedback

* review feedback

* validation checks

* more review

* review feedback

* review feedback-part1

* review feedback-part2

* Fix syntax error in XML declaration

* validation

* review feedback-part3

* feedback-final

* alignment

---------

Co-authored-by: Tom Schraitle <[email protected]>
  • Loading branch information
@Amrita42 @tomschr
Amrita42 and tomschr authored Jul 30, 2024
1 parent cd7ed5b commit b57b91a
Show file tree
Hide file tree
Showing 11 changed files with 713 additions and 60 deletions.
17 changes: 17 additions & 0 deletions DC-systemd-management
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
## ----------------------------
## Doc Config File for the DB Assembly test
## ----------------------------
##
## Basics
MAIN="systemd-management.asm.xml"
SRC_DIR="articles"
IMG_SRC_DIR="images"
## Profiling
PROFOS="generic"
#PROFARCH="x86_64;zseries;power;aarch64"

## stylesheet location
STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2021-ns"

DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"
187 changes: 187 additions & 0 deletions articles/systemd-management.asm.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,187 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- file: templates/articles/assembly.xml -->
<?xml-model href="https://cdn.docbook.org/schema/5.2/rng/assemblyxi.rnc"
type="application/relax-ng-compact-syntax"?>
<!DOCTYPE assembly
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<assembly version="5.2" xml:lang="en"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns="http://docbook.org/ns/docbook">
<!-- resources section references all topic chunks used in the final article
-->
<!-- R E S O U R C E S -->
<!-- Glue files -->
<resources>
<resource xml:id="_systemd-general-more-info" href="../glues/systemd-more-information.xml">https://github.com/SUSE/doc-modular/actions/runs/10160743945/job/28098465613?pr=255
<description>More information about &systemd;</description> </resource>
</resources>

<!-- Concept files -->
<resources>
<resource xml:id="_about-systemd" href="../concepts/what-is-systemd.xml">
<description>About &systemd;</description>
</resource>
<resource xml:id="_systemd-manage-best-practices" href="../concepts/systemd-manage-best-practices.xml">
<description>Best practices for &systemd; management </description>
</resource>
</resources>
<!-- Tasks -->
<resources>
<resource xml:id="_systemd-manage-troubleshoot" href="../tasks/systemd-manage-troubleshoot.xml">
<description>Troubleshooting &systemd; management </description>
</resource>

</resources>
<!-- References -->
<resources>
<resource xml:id="_systemctl-command" href="../references/systemctl-cheatsheet.xml">
<description>Systemctl cheat-sheet</description>
</resource>
<resource xml:id="_systemd-managing-targets" href="../references/systemd-manage-targets.xml">
<description>Manage &systemd; targets</description>
</resource>
<resource xml:id="_starting-systemd-services" href="../references/start-systemd-services.xml">
<description>Starting and stopping &systemd; services</description>
</resource>
<resource xml:id="_enabling-systemd-services" href="../references/enable-systemd-services.xml">
<description>Enabling and disabling &systemd; services </description>
</resource>
<resource xml:id="_terminal-signals-systemd" href="../references/systemd-termination-signal-new.xml">
<description>Sending termination signals to &systemd; services</description>
</resource>
</resources>
<!-- Miscellaneous -->
<resources>
<resource href="../common/legal.xml" xml:id="_legal">
<description>Legal Notice</description>
</resource>
<resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
<description>GNU Free Documentation License</description>
</resource>
</resources>
<!-- S T R U C T U R E -->
<structure renderas="article" xml:id="systemd-services" xml:lang="en">
<merge>
<title>Managing &systemd; Services</title>
<revhistory xml:id="rh-systemd-services">
<revision><date>2023-08-02</date>
<revdescription>
<para>
Initial version.
</para>
</revdescription>
</revision>
</revhistory>
<!-- TODO: provide a listing of possible and validatable meta entry values. Maybe in our geekodoc repo? -->
<!-- add author's e-mail -->
<meta name="maintainer" content="[email protected]" its:translate="no"/>
<!-- ISO date of last update as YYYY-MM-DD -->
<meta name="updated" content="2023-10-26" its:translate="no"/>
<!-- this does not work yet. Use the dm tags listed below for now
<meta name="bugtracker" its:translate="no">
<phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>
<phrase role="component">Non-product-specific documentation</phrase>
<phrase role="product">Smart Docs</phrase>
<phrase role="assignee">[email protected]</phrase>
</meta>
-->
<!-- not supported, yet. Use dm: tag for now
<meta name="translation" its:translate="no">
<phrase role="trans">yes</phrase>
<phrase role="language">de-de,cs-cz</phrase>
</meta>
-->
<!-- enter the platform identifier or a list of
identifiers, separated by ; -->
<meta name="architecture" content="x86;power" its:translate="no"/>
<meta name="productname" its:translate="no">
<!-- enter product name and version --><productname version="15-SP5">&sles;</productname>
</meta>
<meta name="title" its:translate="yes">Managing &systemd; services</meta>
<meta name="description" its:translate="yes">Gives you an understanding and managing of &systemd; services.</meta>
<meta name="social-descr" its:translate="yes">Description of &systemd; services</meta>
<!-- suitable category, comma-separated list of categories -->
<meta name="category" content="Systems Management" its:translate="no"/>
<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
<dm:bugtracker>
<dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
<dm:component>Smart Docs</dm:component>
<dm:product>Documentation</dm:product>
<dm:assignee>[email protected]</dm:assignee>
</dm:bugtracker>
<dm:translation>yes</dm:translation>
</dm:docmanager>
<abstract>
<variablelist>
<varlistentry>
<term>WHAT?</term>
<listitem>
<para>
&systemd; is used to manage system settings and services.
&systemd; organizes tasks into components called <emphasis>units</emphasis> and groups of units into <emphasis>targets</emphasis>.

</para>
</listitem>
</varlistentry>
<varlistentry>
<term>WHY?</term>
<listitem>
<para>
Learn how to manage your system services by using &systemd; to start,stop, enable and disable a service,
send termination signals, use the <command>systemctl</command> command and manage &systemd; targets.
The article also includes troubleshooting and best practices.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>EFFORT</term>
<listitem>
<para>
20 minutes of reading time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>REQUIREMENTS</term>
<listitem>
<itemizedlist>
<listitem>
<para>
Basic understanding of Linux commands
</para>
</listitem>
<listitem>
<para>
Basic understanding of Linux processes, daemons and control groups
</para>
</listitem>
</itemizedlist>
</listitem>
</varlistentry>
</variablelist>
</abstract>
</merge>
<!-- pull in all the topic files you need -->
<!-- pick the appropriate type of include to match your needs -->
<!-- pull in a topic as is -->
<!-- pull in a topic and switch the title -->
<module resourceref="_about-systemd" renderas="section"/>
<module resourceref="_starting-systemd-services" renderas="section"/>
<module resourceref="_enabling-systemd-services" renderas="section"/>
<module resourceref="_terminal-signals-systemd" renderas="section"/>
<module resourceref="_systemd-managing-targets" renderas="section"/>
<module resourceref="_systemd-manage-troubleshoot" renderas="section"/>
<module resourceref="_systemd-manage-best-practices" renderas="section"/>
<module resourceref="_systemctl-command" renderas="section"/>
<module resourceref="_systemd-general-more-info" renderas="section"/>
<module resourceref="_legal" renderas="section"/>
<module resourceref="_gfdl" renderas="appendix"/>

<!-- Troubleshooting -->
</structure>
</assembly>
87 changes: 87 additions & 0 deletions concepts/systemd-manage-best-practices.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="urn:x-suse:xslt:profiling:docbook51-profile.xsl"
type="text/xml"
title="Profiling step"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<topic xml:id="systemd-manage-best-practices"
role="concept" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>Best practices for &systemd; management</title>
<!--add author's email address-->
<meta name="maintainer" content=" [email protected] " its:translate="no"/>
<abstract>
<para>
To manage &systemd; services, try certain best practices that are equipped to handle different situations:
</para>
</abstract>
</info>
<variablelist>
<varlistentry>
<term><emphasis>Check the runtime status of a service</emphasis></term>
<listitem>
<para>To find out the current runtime status of a service:</para>
<screen>&prompt.sudo;systemctl status <replaceable>SERVICE</replaceable></screen>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Use absolute path in your &systemd; unit file</emphasis></term>
<listitem>
<para>
Use an absolute path for executable files and required files, such as configuration files or scripts in your
&systemd; unit file. &systemd; does not rely on the user's environment variables like <literal>$PATH</literal> to locate files.
Use the <emphasis>ExecSearchPath</emphasis> directive in the <literal>[SERVICE]</literal> section.
</para>
<screen>[Service]
ExecSearchPath=<replaceable>ABSOLUTE_PATH</replaceable> </screen>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Use the ExecReload directive</emphasis></term>
<listitem>
<para>
Use the <emphasis>ExecReload</emphasis> directive in the <literal>[SERVICE]</literal> section when you want to define a specific command
that should be executed when you reload a service with the <command>systemctl reload</command> command.
This is useful for services that can dynamically reload their configuration without a restart.
</para>
<screen>[Service]
ExecStart=<replaceable>PATH_TO_EXECUTABLE</replaceable>
ExecReload=<emphasis>PATH_TO_RELOAD_SCRIPT</emphasis></screen>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Use the RestartSec directive </emphasis></term>
<listitem>
<para>
Use the <emphasis>RestartSec</emphasis> directive in the <literal>[SERVICE]</literal> section when you want to
define a delay (in seconds) before the service is restarted after a failure. This is useful for services that require
a specified time to release resources or prevent rapid restart loops that can cause high system load.
</para>
<screen>[Service]
ExecStart=<replaceable>PATH_TO_EXECUTABLE</replaceable>
Restart=on-failure
RestartSec=5 </screen>
</listitem>
</varlistentry>
<varlistentry>
<term><emphasis>Disable emergency mode on a remote machine</emphasis></term>
<listitem>
<para>
You can disable emergency mode on a remote machine, for example, a virtual machine hosted on Google Cloud.
If this mode is enabled, the machine is blocked from connecting to the network.
For example:
</para>
<screen>&prompt.sudo;systemctl mask emergency.service</screen>
<screen>&prompt.sudo;systemctl mask emergency.target</screen>
</listitem>
</varlistentry>
</variablelist>
</topic>
65 changes: 65 additions & 0 deletions glues/systemd-more-information.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<topic xml:id="systemd-general-more-info"
role="glue" xml:lang="en"
xmlns="http://docbook.org/ns/docbook" version="5.2"
xmlns:its="http://www.w3.org/2005/11/its"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:trans="http://docbook.org/ns/transclusion">
<info>
<title>More information</title>
<meta name="maintainer" content="[email protected]" its:translate="no"/>
</info>
<itemizedlist>
<listitem>
<para>
Man 1 systemd
</para>
</listitem>
<listitem>
<para>
Man 1 journalctl
</para>
</listitem>
<listitem>
<para>
Man 1 systemd-cgls
</para>
</listitem>
<listitem>
<para>
Man 1 systemctl
</para>
</listitem>
<listitem>
<para>
Man 5 systemd.service
</para>
</listitem>
<listitem>
<para>
Man 5 systemd.kill
</para>
</listitem>
<listitem>
<para>
Man 7 systemd.boot
</para>
</listitem>
<listitem>
<para>
Introduction to &systemd; basics <link xlink:href="https://documentation.suse.com/smart/systems-management/html/systemd-basics/index.html"> </link>
</para>
</listitem>
<listitem>
<para>
System and Service Manager <link xlink:href="https://systemd.io/"> </link>
</para>
</listitem>
</itemizedlist>
</topic>
Loading

0 comments on commit b57b91a

Please sign in to comment.