Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCTEAM-1553: article for systemd targets #377

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

DOCTEAM-1553: article for systemd targets #377

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
74bc865
article for systemd targets
Amrita42 Oct 30, 2024
5634b4f
remove patch
Amrita42 Oct 30, 2024
6ae25d0
validation
Amrita42 Nov 7, 2024
a420d64
validation issues
Amrita42 Nov 8, 2024
80099d2
adds steps
Amrita42 Nov 12, 2024
ea8049f
more steps
Amrita42 Nov 13, 2024
2c8dd95
more steps
Amrita42 Nov 13, 2024
c5c3da3
more
Amrita42 Nov 13, 2024
1d3bfe7
final steps
Amrita42 Nov 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions DC-systemd-settargets
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
MAIN="systemd-settargets.asm.xml"
ROOTID="systemd-settargets"
SRC_DIR="articles"
IMG_SRC_DIR="images"

PROFCONDITION="suse-product"
PROFOS="sles"
#PROFCONDITION="suse-product;beta"
#PROFCONDITION="community-project"

STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
169 changes: 169 additions & 0 deletions articles/systemd-settargets.asm.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,169 @@
<?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">
<description>More information about &systemd;</description> </resource>
</resources>
<!-- Concept files -->
<resources>
<resource xml:id="_concept-systemd-targets" href="../concepts/systemd-targets.xml">
<description>&systemd; targets</description>
</resource>
</resources>
<!-- Tasks -->
<resources>
<resource xml:id="_systemd-set-targets" href="../tasks/systemd-set-targets.xml">
<description>Setting up a &systemd; target </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-settargets" xml:lang="en">
<merge>
<title>Introduction to &systemd; Basics</title>
<revhistory xml:id="rh-systemd-services">
<revision><date>2024-10-30f</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" its:translate="no">
<phrase>&x86-64;</phrase>
<phrase>&power;</phrase>
</meta>
<meta name="productname" its:translate="no">
<productname condition="16.0" os="sles">&productname;</productname>
<productname condition="6.0" os="slmicro">&productname;</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" its:translate="no">
<phrase>Systems Management</phrase>
</meta>
<meta name="task" its:translate="no">
<phrase>Administration</phrase>
<phrase>Configuration</phrase>
</meta>
<meta name="series" its:translate="no">Product &amp; Solutions</meta>

<dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
<dm:bugtracker>
<dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
<dm:component>Documentation</dm:component>
<dm:product os="sles">SUSE Linux Enterprise Server 16.0</dm:product>
<dm:product os="slmicro">SUSE Linux Enterprise Micro 6.0</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 about &systemd; targets and how to create a custom &systemd; target.
</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 and &systemd;
</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="_concept-systemd-targets" renderas="section"/>
<module resourceref="_systemd-set-targets" renderas="section"/>
<module resourceref="_systemd-general-more-info" renderas="section"/>
<module resourceref="_legal" renderas="section"/>
<module resourceref="_gfdl" renderas="appendix"/>

<!-- Troubleshooting -->
</structure>
</assembly>
136 changes: 136 additions & 0 deletions tasks/systemd-set-targets.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,136 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
[
<!ENTITY % entities SYSTEM "../common/generic-entities.ent">
%entities;
]>
<!-- refers to legacy doc: https://github.com/SUSE/doc-sle/blob/main/xml/adm_sudo.xml -->
<!-- point back to this document with a similar comment added to your legacy doc piece -->
<!-- refer to README.md for file and id naming conventions -->
<!-- metadata is dealt with on the assembly level -->
<topic xml:id="systemd-set-targets"
role="task" 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>
<meta name="maintainer" content="[email protected]" its:translate="no"/>
<title>Setting up a &systemd; target</title>
<abstract>
<para>
To set up a &systemd; target, you need to create a new target unit file and define any required dependencies.
A target is a group of unit files that manages the state of services. A target can be used to control groups of services
or define system states.
</para>
</abstract>
</info>
<procedure>
<step>
<para>Create a new file with the <literal>.target</literal> extension in <filename>/etc/systemd/system/</filename>. </para>
<para>For example:</para>
<screen>&prompt.sudo; <command>vi /etc/systemd/system/test.target</command></screen>
</step>
<step>
<para>Define the target with basic configuration.</para>
<para>For example:</para>
<screen>[Unit]
Description= Test target
Requires=multi-user.target
After=multi-user.target

[Install]
WantedBy=multi-user.target
</screen>
<itemizedlist>
<listitem>
<para>
<emphasis>Requires:</emphasis> specifies that <literal>multi-user.target</literal> must be reached
for <literal>test.target</literal> to be active.
</para>
</listitem>
<listitem>
<para>
<emphasis>After:</emphasis> specifies that this target starts after the <literal>multi-user.target</literal>.
</para>
</listitem>
<listitem>
<para>
<emphasis>WantedBy:</emphasis> specifies that this target should be a part of <literal>multi-user.target</literal>.
</para>
</listitem>
</itemizedlist>
</step>
<step>
<para>Set permissions for the target file. </para>
<para>For example:</para>
<screen>&prompt.sudo; <command>sudo chmod 644 /etc/systemd/system/test.target
</command></screen> </step>
<step>
<para>Link the required services to the target file. Create a <literal>.wants</literal> directory and then create
symbolic links to the services you want to include in your custom target.</para>
<para>For example:</para>
<screen>&prompt.sudo; <command>mkdir -p /etc/systemd/system/custom.target.wants/ </command></screen>
<screen>&prompt.sudo; <command>sudo ln -s /etc/systemd/system/test.service /etc/systemd/system/custom.target.wants/
</command></screen>
</step>
<step>
<para>Reload &systemd;. </para>
<para>For example:</para>
<screen>&prompt.sudo; <command>systemctl daemon-reload</command></screen> </step>
<step>
<para>Start and enable the target. </para>
<para>For example:</para>
<screen>&prompt.sudo; <command>systemctl start test.target</command></screen>
<screen>&prompt.sudo; <command>systemctl enable test.target</command></screen>
</step>
<step>
<para>Verify the status of the custom target. </para>
<para>For example:</para>
<screen>&prompt.sudo; <command>systemctl status test.target</command></screen>
</step>
<step>
<para>Verify all the units that are part of this target. </para>
<para>For example:</para>
<screen>&prompt.sudo; <command>systemctl list-dependencies test.target </command></screen>
</step>
<step><para>Your custom &systemd; target is set up and configured.</para></step>
</procedure>
<para>You can use the following common configuration options: </para>
<itemizedlist>
<listitem>
<para>
<emphasis>Description:</emphasis> human-readable description of the target.
</para>
</listitem>
<listitem>
<para>
<emphasis>Documentation:</emphasis> URIs to documentation.</para>
</listitem>
<listitem>
<para>
<emphasis>AllowIsolate:</emphasis>
If set to <literal>true</literal>, this unit can be used with the <command>systemctl isolate</command> command.
</para>
</listitem>
<listitem>
<para>
<emphasis>Wants:</emphasis>
Units that can be started but is not mandatory.
</para>
</listitem>
<listitem>
<para>
<emphasis>After/Before:</emphasis>
the order of the dependency.
</para>
</listitem>
<listitem>
<para>
<emphasis>Conflicts:</emphasis>
units that should not be active while this target is active.
</para>
</listitem>
</itemizedlist>
</topic>