Merge f41f8eb4a2 into 2b60615a41

I'm not sure if 4 is the appropriate value in all cases, but at least
for the two files in that are in the test list, it works better.

Also, we need to remove newlines from the title to let it render correctly.

Signed-off-by: Ayham Kteash <ayham@thehoodiefirm.com>

.gitattributes

@@ -2,6 +2,7 @@
 *.gpg  binary generated
 *.bmp  binary
 *.base64 generated
+*.rst conflict-marker-size=100
 
 # Mark files as "generated", i.e. no license applies to them.
 # This includes output from programs, directive lists generated by grepping

.gitignore

@@ -39,3 +39,6 @@ mkosi.local.conf
 .dir-locals-2.el
 .vscode/
 /pkg/
+/doc-migration/.venv
+/doc-migration/build
+.venv

doc-migration/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc-migration/README.md

@@ -0,0 +1,172 @@
+# Migration of Documentation from Docbook to Sphinx
+
+- [Migration of Documentation from Docbook to Sphinx](#migration-of-documentation-from-docbook-to-sphinx)
+  - [Prerequisites](#prerequisites)
+  - [Transformation Process](#transformation-process)
+    - [1. Docbook to `rst`](#1-docbook-to-rst)
+    - [2. `rst` to Sphinx](#2-rst-to-sphinx)
+      - [Sphinx Extensions](#sphinx-extensions)
+        - [sphinxcontrib-globalsubs](#sphinxcontrib-globalsubs)
+      - [Custom Sphinx Extensions](#custom-sphinx-extensions)
+        - [directive_roles.py (90% done)](#directive_rolespy-90-done)
+        - [external_man_links.py](#external_man_linkspy)
+      - [Includes](#includes)
+  - [Todo:](#todo)
+
+## Prerequisites
+
+Python dependencies for parsing docbook files and generating `rst`:
+
+- `lxml`
+
+Python dependencies for generating `html` and `man` pages from `rst`:
+
+- `sphinx`
+- `sphinxcontrib-globalsubs`
+- `furo` (The Sphinx theme)
+
+To install these (see [Sphinx Docs](https://www.sphinx-doc.org/en/master/tutorial/getting-started.html#setting-up-your-project-and-development-environment)):
+
+```sh
+# Generate a Python env:
+$ python3 -m venv .venv
+$ source .venv/bin/activate
+# Install deps
+$ python3 -m pip install -U lxml
+$ python3 -m pip install -U sphinx
+$ python3 -m pip install -U sphinxcontrib-globalsubs
+$ python3 -m pip install -U furo
+$ cd doc-migration && ./convert.sh
+```
+
+## Transformation Process
+
+You can run the entire process with `./convert.sh` in the `doc-migration` folder. The individual steps are:
+
+### 1. Docbook to `rst`
+
+Use the `main.py` script to convert a single Docbook file to `rst`:
+
+```sh
+# in the `doc-migration` folder:
+$ python3 main.py --file ../man/busctl.xml --output 'in-progress'
+```
+
+This file calls `db2rst.py` that parses Docbook elements on each file, does some string transformation to the contents of each, and glues them all back together again. It will also output info on unhandled elements, so we know whether our converter is feature complete and can achieve parity with the old docs.
+
+To run the script against all files you can use :
+
+```sh
+# in the `doc-migration` folder:
+$ python3 main.py --dir ../man --output 'in-progress'
+```
+
+> When using the script to convert all files at once in our man folder we recommend using "in-progress" folder name as our output dir so we don't end up replacing some the files that were converted and been marked as finished inside the source folder.
+
+After using the above script at least once you will get two files(`errors.json`,`successes_with_unhandled_tags.json`) in the output dir.
+
+`errors.json` will have all the files that failed to convert to rst with the respective error message for each file.
+running : `python3 main.py --errored` will only process the files that had an error and present in `errors.json`
+
+`successes_with_unhandled_tags.json` will have all the files that were converted but there were still some tags that are not defined in `db2rst.py` yet.
+
+running : `python3 main.py --unhandled-only` will only process the files that are present in `successes_with_unhandled_tags.json`
+
+This is to avoid running all files at once when we only need to work on files that are not completely processed.
+
+### 2. `rst` to Sphinx
+
+```sh
+# in the `/doc-migration` folder
+$ rm -rf build
+# ☝️ if you already have a build
+$ make html man
+```
+
+- The `html` files end up in `/doc-migration/build/html`. Open the `index.html` there to browse the docs.
+- The `man` files end up in `/doc-migration/build/man`. Preview an individual file with `$ mandoc -l build/man/busctl.1`
+
+#### Sphinx Extensions
+
+We use the following Sphinx extensions to achieve parity with the old docs:
+
+##### sphinxcontrib-globalsubs
+
+Allows referencing variables in the `global_substitutions` object in `/doc-migrations/source/conf.py` (the Sphinx config file).
+
+#### Custom Sphinx Extensions
+
+##### directive_roles.py (90% done)
+
+This is used to add custom Sphinx directives and roles to generate systemD directive lists page.
+
+To achieve the functionality exiting in `tools/make-directive-index.py` by building the Directive Index page from custom Sphinx role, here is an example:
+
+The formula for those sphinx roles is like this: `:directive:{directive_id}:{type}`
+
+For example we can use an inline Sphinx role like this:
+
+```
+ :directive:environment-variables:var:`SYSEXT_SCOPE=`
+```
+
+This will be then inserted in the SystemD directive page on build under the group `environment-variables`
+we can use the `{type}` to have more control over how this will be treated inside the Directive Index page.
+
+##### external_man_links.py
+
+This is used to create custom sphinx roles to handle external links for man pages to avoid having full urls in rst for example:
+
+`:die-net:`refentrytitle(manvolnum)` will lead to 'http://linux.die.net/man/{manvolnum}/{refentrytitle}'
+a full list of these roles can be found in [external_man_links](source/_ext/external_man_links.py).
+
+#### Includes
+
+1. Versions
+   In the Docbook files you may find lines like these: `<xi:include href="version-info.xml" xpointer="v205"/>` which would render into `Added in version 205` in the docs. This is now archived with the existing [sphinx directive ".. versionadded::"](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded) and represented as `.. versionadded:: 205` in the rst file
+
+2. Code Snippets
+   These can be included with the [literalinclude directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-literalinclude) when living in their own file.
+
+   Example:
+
+  ```rst
+  .. literalinclude:: ./check-os-release-simple.py
+  :language: python
+  ```
+
+  There is also the option to include a [code block](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block) directly in the rst file.
+
+  Example:
+
+  ```rst
+  .. code-block:: sh
+
+  a{sv} 3 One s Eins Two u 2 Yes b true
+
+  ```
+
+3. Text Snippets
+
+  There are a few xml files were sections of these files are reused in multiple other files. While it is no problem to include a whole other rst file the concept of only including a part of that file is a bit more tricky. You can choose to include text partial that starts after a specific text and also to stop before reaching another text. So we decided it would be best to add start and stop markers to define the section in these source files. These markers are: `.. inclusion-marker-do-not-remove` / ``So that a`<xi:include href="standard-options.xml" xpointer="no-pager" />` turns into:
+
+  ```rst
+  .. include:: ./standard-options.rst
+    :start-after: .. inclusion-marker-do-not-remove no-pager
+    :end-before: .. inclusion-end-marker-do-not-remove no-pager
+  ```
+
+## Todo
+
+An incomplete list.
+
+- [ ] Custom Link transformations:
+  - [ ] `custom-man.xsl`
+  - [x] `custom-html.xsl`
+- [ ] See whether `tools/tools/xml_helper.py` does anything we don’t do, this also contains useful code for:
+  - [ ] Build a man index, as in `tools/make-man-index.py`
+  - [x] Build a directives index, as in `tools/make-directive-index.py`
+  - [ ] DBUS doc generation `tools/update-dbus-docs.py`
+- [ ] See whether `tools/update-man-rules.py` does anything we don’t do
+- [ ] Make sure the `man_pages` we generate for Sphinx’s `conf.py` match the Meson rules in `man/rules/meson.build`
+- [ ] Re-implement check-api-docs

doc-migration/convert.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# SPDX-License-Identifier: LGPL-2.1-or-later
+
+# Array of XML filenames
+files=("sd_journal_get_data" "busctl" "systemd" "journalctl" "os-release")
+
+# Directory paths
+input_dir="../man"
+output_dir="source/docs"
+
+echo "---------------------"
+echo "Converting xml to rst"
+echo ""
+# Iterate over the filenames
+for file in "${files[@]}"; do
+    echo "------------------"
+    python3 main.py --dir ${input_dir} --output ${output_dir} --file "${file}.xml"
+done
+
+# Clean and build
+rm -rf build
+
+echo "--------------------"
+echo "Building Sphinx Docs"
+echo "--------------------"
+make html

doc-migration/db2rst.py

@@ -0,0 +1,830 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+# SPDX-License-Identifier: LGPL-2.1-or-later
+"""
+    DocBook to ReST converter
+    =========================
+    This script may not work out of the box, but is easy to extend.
+    If you extend it, please send me a patch: wojdyr at gmail.
+
+    Docbook has >400 elements, most of them are not supported (yet).
+    ``pydoc db2rst`` shows the list of supported elements.
+
+    In reST, inline markup can not be nested (major deficiency of reST).
+    Since it is not clear what to do with, say,
+    <subscript><emphasis>x</emphasis></subscript>
+    the script outputs incorrect (nested) reST (:sub:`*x*`)
+    and it is up to user to decide how to change it.
+
+    Usage: db2rst.py file.xml > file.rst
+
+    Ported to Python3 in 2024 by neighbourhood.ie
+
+    :copyright: 2009 by Marcin Wojdyr.
+    :license: BSD.
+"""
+
+# If this option is True, XML comment are discarded. Otherwise, they are
+# converted to ReST comments.
+# Note that ReST doesn't support inline comments. XML comments
+# are converted to ReST comment blocks, what may break paragraphs.
+from source import conf
+import lxml.etree as ET
+import re
+import sys
+import os
+from pathlib import Path
+REMOVE_COMMENTS = False
+
+# id attributes of DocBook elements are translated to ReST labels.
+# If this option is False, only labels that are used in links are generated.
+WRITE_UNUSED_LABELS = False
+
+
+# The Files have sections that are used as includes in other files
+FILES_USED_FOR_INCLUDES = ['sd_journal_get_data.xml', 'standard-options.xml',
+                           'user-system-options.xml', 'common-variables.xml', 'standard-conf.xml',
+                           'libsystemd-pkgconfig.xml', 'threads-aware.xml']
+
+# to avoid dupliate error reports
+_not_handled_tags = set()
+
+# to remember which id/labels are really needed
+_linked_ids = set()
+
+# buffer that is flushed after the end of paragraph,
+# used for ReST substitutions
+_buffer = ""
+
+_indent_next_listItem_by = 0
+
+
+def _run(input_file, output_dir):
+    sys.stderr.write("Parsing XML file `%s'...\n" % input_file)
+
+    parser = ET.XMLParser(remove_comments=REMOVE_COMMENTS, no_network=False)
+    tree = ET.parse(input_file, parser=parser)
+
+    for elem in tree.iter():
+        if elem.tag in ("xref", "link"):
+            _linked_ids.add(elem.get("linkend"))
+
+    output_file = os.path.join(output_dir, os.path.basename(
+        input_file).replace('.xml', '.rst'))
+
+    with open(output_file, 'w') as file:
+        file.write(TreeRoot(tree.getroot()).encode('utf-8').decode('utf-8'))
+
+
+def _warn(s):
+    sys.stderr.write("WARNING: %s\n" % s)
+
+
+def _supports_only(el, tags):
+    "print warning if there are unexpected children"
+    for i in el:
+        if i.tag not in tags:
+            _warn("%s/%s skipped." % (el.tag, i.tag))
+
+
+def _what(el):
+    "returns string describing the element, such as <para> or Comment"
+    if isinstance(el.tag, str):
+        return "<%s>" % el.tag
+    elif isinstance(el, ET._Comment):
+        return "Comment"
+    else:
+        return str(el)
+
+
+def _has_only_text(el):
+    "print warning if there are any children"
+    if list(el):
+        _warn("children of %s are skipped: %s" % (_get_path(el),
+                                                  ", ".join(_what(i) for i in el)))
+
+
+def _has_no_text(el):
+    "print warning if there is any non-blank text"
+    if el.text is not None and not el.text.isspace():
+        _warn("skipping text of <%s>: %s" % (_get_path(el), el.text))
+    for i in el:
+        if i.tail is not None and not i.tail.isspace():
+            _warn("skipping tail of <%s>: %s" % (_get_path(i), i.tail))
+
+
+def _includes(el):
+    file_path_pathlib = Path(el.get('href'))
+    file_extension = file_path_pathlib.suffix
+    include_files = FILES_USED_FOR_INCLUDES
+    if file_extension == '.xml':
+        if el.get('href') == 'version-info.xml':
+            versionString = conf.global_substitutions.get(
+                el.get("xpointer"))
+            # `\n\n   \n\n   ` forces a newline and subsequent indent.
+            # The empty spaces are stripped later
+            return f".. only:: html\n\n   \n\n   .. versionadded:: {versionString}\n\n   "
+        elif not el.get("xpointer"):
+            return f".. include:: ../includes/{el.get('href').replace('xml', 'rst')}"
+        elif el.get('href') in include_files:
+            return f""".. include:: ../includes/{el.get('href').replace('xml', 'rst')}
+                    :start-after: .. inclusion-marker-do-not-remove {el.get("xpointer")}
+                    :end-before: .. inclusion-end-marker-do-not-remove {el.get("xpointer")}
+                    """
+
+    elif file_extension == '.c':
+        return f""".. literalinclude:: /code-examples/c/{el.get('href')}
+                    :language: c
+                """
+    elif file_extension == '.py':
+        return f""".. literalinclude:: /code-examples/py/{el.get('href')}
+                    :language: python
+                """
+    elif file_extension == '.sh':
+        return f""".. literalinclude:: /code-examples/sh/{el.get('href')}
+                    :language: shell
+                """
+
+
+def _conv(el):
+    "element to string conversion; usually calls element_name() to do the job"
+    if el.tag in globals():
+        s = globals()[el.tag](el)
+        assert s, "Error: %s -> None\n" % _get_path(el)
+        return s
+    elif isinstance(el, ET._Comment):
+        return Comment(el) if (el.text and not el.text.isspace()) else ""
+    else:
+        if el.tag not in _not_handled_tags:
+            # Convert version references to `versionAdded` directives
+            if el.tag == "{http://www.w3.org/2001/XInclude}include":
+                return _includes(el)
+            else:
+                _warn("Don't know how to handle <%s>" % el.tag)
+                _warn(" ... from path: %s" % _get_path(el))
+                _not_handled_tags.add(el.tag)
+        return _concat(el)
+
+
+def _no_special_markup(el):
+    return _concat(el)
+
+
+def _remove_indent_and_escape(s, tag):
+    if tag == "programlisting":
+        return s
+    "remove indentation from the string s, escape some of the special chars"
+    s = "\n".join(i.lstrip().replace("\\", "\\\\") for i in s.splitlines())
+    # escape inline mark-up start-string characters (even if there is no
+    # end-string, docutils show warning if the start-string is not escaped)
+    # TODO: handle also Unicode: ‘ “ ’ « ¡ ¿ as preceding chars
+    s = re.sub(r"([\s'\"([{</:-])"  # start-string is preceded by one of these
+               r"([|*`[])"  # the start-string
+               r"(\S)",    # start-string is followed by non-whitespace
+               r"\1\\\2\3",  # insert backslash
+               s)
+    return s
+
+
+def _concat(el):
+    "concatate .text with children (_conv'ed to text) and their tails"
+    s = ""
+    id = el.get("id")
+    if id is not None and (WRITE_UNUSED_LABELS or id in _linked_ids):
+        s += "\n\n.. _%s:\n\n" % id
+    if el.text is not None:
+        s += _remove_indent_and_escape(el.text, el.tag)
+    for i in el:
+        s += _conv(i)
+        if i.tail is not None:
+            if len(s) > 0 and not s[-1].isspace() and i.tail[0] in " \t":
+                s += i.tail[0]
+            s += _remove_indent_and_escape(i.tail, el.tag)
+    return s.strip()
+
+
+def _original_xml(el):
+    return ET.tostring(el, with_tail=False).decode('utf-8')
+
+
+def _no_markup(el):
+    s = ET.tostring(el, with_tail=False).decode('utf-8')
+    s = re.sub(r"<.+?>", " ", s)  # remove tags
+    s = re.sub(r"\s+", " ", s)  # replace all blanks with single space
+    return s
+
+
+def _get_level(el):
+    "return number of ancestors"
+    return sum(1 for i in el.iterancestors())
+
+
+def _get_path(el):
+    t = [el] + list(el.iterancestors())
+    return "/".join(str(i.tag) for i in reversed(t))
+
+
+def _make_title(t, level, indentLevel=0):
+    t = t.replace('\n', ' ').strip()
+
+    if level == 1:
+        return "\n\n" + "=" * len(t) + "\n" + t + "\n" + "=" * len(t)
+
+    char = ["#", "=", "-", "~", "^", "."]
+    underline = char[level-2] * len(t)
+    indentation = " "*indentLevel
+    return f"\n\n{indentation}{t}\n{indentation}{underline}"
+
+
+def _join_children(el, sep):
+    _has_no_text(el)
+    return sep.join(_conv(i) for i in el)
+
+
+def _block_separated_with_blank_line(el):
+    s = ""
+    id = el.get("id")
+    if id is not None:
+        s += "\n\n.. inclusion-marker-do-not-remove %s\n\n" % id
+    s += "\n\n" + _concat(el)
+    if id is not None:
+        s += "\n\n.. inclusion-end-marker-do-not-remove %s\n\n" % id
+    return s
+
+
+def _indent(el, indent, first_line=None, suppress_blank_line=False):
+    "returns indented block with exactly one blank line at the beginning"
+    start = "\n\n"
+    if suppress_blank_line:
+        start = ""
+
+    # lines = [" "*indent + i for i in _concat(el).splitlines()
+    #         if i and not i.isspace()]
+    # TODO: This variant above strips empty lines within elements. We don’t want that to happen, at least not always
+    lines = [" "*indent + i for i in _concat(el).splitlines()
+             if i]
+    if first_line is not None:
+        # replace indentation of the first line with prefix `first_line'
+        lines[0] = first_line + lines[0][indent:]
+    return start + "\n".join(lines)
+
+
+def _normalize_whitespace(s):
+    return " ".join(s.split())
+
+###################           DocBook elements        #####################
+
+# special "elements"
+
+
+def TreeRoot(el):
+    output = _conv(el)
+    # add .. SPDX-License-Identifier: LGPL-2.1-or-later:
+    output = '\n\n'.join(
+        ['.. SPDX-License-Identifier: LGPL-2.1-or-later:', output])
+    # remove trailing whitespace
+    output = re.sub(r"[ \t]+\n", "\n", output)
+    # leave only one blank line
+    output = re.sub(r"\n{3,}", "\n\n", output)
+    return output
+
+
+def Comment(el):
+    return _indent(el, 12, ".. COMMENT: ")
+
+# Meta refs
+
+
+def refentry(el):
+    return _concat(el)
+
+# FIXME: how to ignore/delete a tag???
+
+
+def refentryinfo(el):
+    # ignore
+    return '  '
+
+
+def refnamediv(el):
+    # return '**Name** \n\n' + _make_title(_join_children(el, ' — '), 2)
+    return '.. only:: html\n\n' + _make_title(_join_children(el, ' — '), 2, 3)
+
+
+def refsynopsisdiv(el):
+    # return '**Synopsis** \n\n' + _make_title(_join_children(el, ' '), 3)
+    s = ""
+    s += _make_title('Synopsis', 2, 3)
+    s += '\n\n'
+    s += _join_children(el, ', ')
+    return s
+
+
+def refname(el):
+    _has_only_text(el)
+    return "%s" % el.text
+
+
+def refpurpose(el):
+    _has_only_text(el)
+    return "%s" % el.text
+
+
+def cmdsynopsis(el):
+    return _join_children(el, ' ')
+
+
+def arg(el):
+    text = el.text
+    if text is None:
+        text = _join_children(el, '')
+    # choice: req, opt, plain
+    choice = el.get("choice")
+    if choice == 'opt':
+        return f"[%s{'...' if el.get('rep') == 'repeat' else ''}]" % text
+    elif choice == 'req':
+        return "{%s}" % text
+    elif choice == 'plain':
+        return "%s" % text
+    else:
+        "print warning if there another choice"
+        _warn("skipping arg with choice of: %s" % (choice))
+
+
+# general inline elements
+
+def emphasis(el):
+    return "*%s*" % _concat(el).strip()
+
+
+phrase = emphasis
+citetitle = emphasis
+
+
+acronym = _no_special_markup
+
+
+def command(el):
+    # Only enclose in backticks if it’s not part of a term
+    # (which is already enclosed in backticks)
+    isInsideTerm = False
+    for term in el.iterancestors(tag='term'):
+        isInsideTerm = True
+
+    if isInsideTerm:
+        return _concat(el).strip()
+    return "``%s``" % _concat(el).strip()
+
+
+def literal(el):
+    return "\"%s\"" % _concat(el).strip()
+
+
+def varname(el):
+    isInsideTerm = False
+    for term in el.iterancestors(tag='term'):
+        isInsideTerm = True
+
+    if isInsideTerm:
+        return _concat(el).strip()
+
+    classname = ''
+    for varlist in el.iterancestors(tag='variablelist'):
+        if varlist.attrib.get('class', '') != '':
+            classname = varlist.attrib['class']
+    if len(classname) > 0:
+        return f":directive:{classname}:var:`%s`" % _concat(el).strip()
+    return "``%s``" % _concat(el).strip()
+
+
+def option(el):
+    isInsideTerm = False
+    for term in el.iterancestors(tag='term'):
+        isInsideTerm = True
+
+    if isInsideTerm:
+        return _concat(el).strip()
+
+    classname = ''
+    for varlist in el.iterancestors(tag='variablelist'):
+        if varlist.attrib.get('class', '') != '':
+            classname = varlist.attrib['class']
+    if len(classname) > 0:
+        return f":directive:{classname}:option:`%s`" % _concat(el).strip()
+    return "``%s``" % _concat(el).strip()
+
+
+def constant(el):
+    isInsideTerm = False
+    for term in el.iterancestors(tag='term'):
+        isInsideTerm = True
+
+    if isInsideTerm:
+        return _concat(el).strip()
+
+    classname = ''
+    for varlist in el.iterancestors(tag='variablelist'):
+        if varlist.attrib.get('class', '') != '':
+            classname = varlist.attrib['class']
+    if len(classname) > 0:
+        return f":directive:{classname}:constant:`%s`" % _concat(el).strip()
+    return "``%s``" % _concat(el).strip()
+
+
+filename = command
+
+
+def optional(el):
+    return "[%s]" % _concat(el).strip()
+
+
+def replaceable(el):
+    return "<%s>" % _concat(el).strip()
+
+
+def term(el):
+    if el.getparent().index(el) != 0:
+        return ' '
+
+    level = _get_level(el)
+    if level > 5:
+        level = 5
+    # Sometimes, there are multiple terms for one entry. We want those displayed in a single line, so we gather them all up and parse them together
+    hasMultipleTerms = False
+    titleStrings = [_concat(el).strip()]
+    title = ''
+    for term in el.itersiblings(tag='term'):
+        # We only arrive here if there is more than one `<term>` in the `el`
+        hasMultipleTerms = True
+        titleStrings.append(_concat(term).strip())
+
+    if hasMultipleTerms:
+        title = ', '.join(titleStrings)
+        # return _make_title(f"``{titleString}``", 4)
+    else:
+        title = _concat(el).strip()
+
+    if level >= 5:
+        global _indent_next_listItem_by
+        _indent_next_listItem_by += 3
+        return f".. option:: {title}\n\n   \n\n   "
+    return _make_title(f"``{title}``", level) + '\n\n'
+
+# links
+
+
+def ulink(el):
+    url = el.get("url")
+    text = _concat(el).strip()
+    if text.startswith(".. image::"):
+        return "%s\n   :target: %s\n\n" % (text, url)
+    elif url == text:
+        return text
+    elif not text:
+        return "`<%s>`_" % (url)
+    else:
+        return "`%s <%s>`_" % (text, url)
+
+# TODO: other elements are ignored
+
+
+def xref(el):
+    _has_no_text(el)
+    id = el.get("linkend")
+    return ":ref:`%s`" % id if id in _linked_ids else ":ref:`%s <%s>`" % (id, id)
+
+
+def link(el):
+    _has_no_text(el)
+    return "`%s`_" % el.get("linkend")
+
+
+# lists
+
+def itemizedlist(el):
+    return _indent(el, 2, "* ", True)
+
+
+def orderedlist(el):
+    return _indent(el, 2, "1. ", True)
+
+
+def simplelist(el):
+    type = el.get("type")
+    if type == "inline":
+        return _join_children(el, ', ')
+    else:
+        return _concat(el)
+
+
+def member(el):
+    return _concat(el)
+
+# varlists
+
+
+def variablelist(el):
+    return _concat(el)
+
+
+def varlistentry(el):
+    s = ""
+    id = el.get("id")
+    if id is not None:
+        s += "\n\n.. inclusion-marker-do-not-remove %s\n\n" % id
+    for i in el:
+        if i.tag == 'term':
+            s += _conv(i) + '\n\n'
+        else:
+            # Handle nested list items, this is mainly for
+            # options that have options
+            if i.tag == 'listitem':
+                global _indent_next_listItem_by
+                s += _indent(i, _indent_next_listItem_by, None, True)
+                _indent_next_listItem_by = 0
+            else:
+                s += _indent(i, 0, None, True)
+    if id is not None:
+        s += "\n\n.. inclusion-end-marker-do-not-remove %s\n\n" % id
+    return s
+
+
+def listitem(el):
+    _supports_only(
+        el, ["para", "simpara", "{http://www.w3.org/2001/XInclude}include"])
+    return _block_separated_with_blank_line(el)
+
+# sections
+
+
+def example(el):
+    # FIXME: too hacky?
+    elements = [i for i in el]
+    first, rest = elements[0], elements[1:]
+
+    return _make_title(_concat(first), 4) + "\n\n" + "".join(_conv(i) for i in rest)
+
+
+def sect1(el):
+    return _block_separated_with_blank_line(el)
+
+
+def sect2(el):
+    return _block_separated_with_blank_line(el)
+
+
+def sect3(el):
+    return _block_separated_with_blank_line(el)
+
+
+def sect4(el):
+    return _block_separated_with_blank_line(el)
+
+
+def section(el):
+    return _block_separated_with_blank_line(el)
+
+
+def title(el):
+    return _make_title(_concat(el).strip(), _get_level(el) + 1)
+
+# bibliographic elements
+
+
+def author(el):
+    _has_only_text(el)
+    return "\n\n.. _author:\n\n**%s**" % el.text
+
+
+def date(el):
+    _has_only_text(el)
+    return "\n\n.. _date:\n\n%s" % el.text
+
+# references
+
+
+def citerefentry(el):
+    project = el.get("project")
+    refentrytitle = el.xpath("refentrytitle")[0].text
+    manvolnum = el.xpath("manvolnum")[0].text
+
+    extlink_formats = {
+        'man-pages': f':man-pages:`{refentrytitle}({manvolnum})`',
+        'die-net': f':die-net:`{refentrytitle}({manvolnum})`',
+        'mankier': f':mankier:`{refentrytitle}({manvolnum})`',
+        'archlinux': f':archlinux:`{refentrytitle}({manvolnum})`',
+        'debian': f':debian:`{refentrytitle}({manvolnum})`',
+        'freebsd': f':freebsd:`{refentrytitle}({manvolnum})`',
+        'dbus': f':dbus:`{refentrytitle}({manvolnum})`',
+    }
+
+    if project in extlink_formats:
+        return extlink_formats[project]
+
+    if project == 'url':
+        url = el.get("url")
+        return f"`{refentrytitle}({manvolnum}) <{url}>`_"
+
+    return f":ref:`{refentrytitle}({manvolnum})`"
+
+
+def refmeta(el):
+    refentrytitle = el.find('refentrytitle').text
+    manvolnum = el.find('manvolnum').text
+
+    meta_title = f":title: {refentrytitle}"
+
+    meta_manvolnum = f":manvolnum: {manvolnum}"
+
+    doc_title = ".. _%s:" % _join_children(
+        el, '') + '\n\n' + _make_title(_join_children(el, ''), 1)
+
+    return '\n\n'.join([meta_title, meta_manvolnum, doc_title])
+
+
+def refentrytitle(el):
+    if el.get("url"):
+        return ulink(el)
+    else:
+        return _concat(el)
+
+
+def manvolnum(el):
+    return "(%s)" % el.text
+
+# media objects
+
+
+def imageobject(el):
+    return _indent(el, 3, ".. image:: ", True)
+
+
+def imagedata(el):
+    _has_no_text(el)
+    return el.get("fileref")
+
+
+def videoobject(el):
+    return _indent(el, 3, ".. raw:: html\n\n", True)
+
+
+def videodata(el):
+    _has_no_text(el)
+    src = el.get("fileref")
+    return '    <video src="%s" controls>\n' % src + \
+        '      Your browser does not support the <code>video</code> element.\n' + \
+        '    </video>'
+
+
+def programlisting(el):
+    xi_include = el.find('.//{http://www.w3.org/2001/XInclude}include')
+    if xi_include is not None:
+        return _includes(xi_include)
+    else:
+        return f"\n\n.. code-block:: sh\n\n   \n\n{_indent(el, 3)}\n\n"
+
+
+def screen(el):
+    return _indent(el, 3, "::\n\n", False) + "\n\n"
+
+
+def synopsis(el):
+    return _indent(el, 3, "::\n\n", False) + "\n\n"
+
+
+def funcsynopsis(el):
+    return _concat(el)
+
+
+def funcsynopsisinfo(el):
+    return "``%s``" % _concat(el)
+
+
+def funcprototype(el):
+    funcdef = ''.join(el.find('.//funcdef').itertext())
+    params = el.findall('.//paramdef')
+    param_list = [''.join(param.itertext()) for param in params]
+    s = ".. code-block:: \n\n   "
+    s += f"{funcdef}("
+    s += ",\n\t".join(param_list)
+    s += ");"
+    return s
+
+
+def paramdef(el):
+    return el
+
+
+def funcdef(el):
+    return el
+
+
+def function(el):
+    return _concat(el).strip()
+
+
+def parameter(el):
+    return el
+
+
+def table(el):
+    title = _concat(el.find('title'))
+    headers = el.findall('.//thead/row/entry')
+    rows = el.findall('.//tbody/row')
+
+    # Collect header names
+    header_texts = [_concat(header) for header in headers]
+
+    # Collect row data
+    row_data = []
+    for row in rows:
+        entries = row.findall('entry')
+        row_data.append([_concat(entry) for entry in entries])
+
+    # Create the table in reST list-table format
+    rst_table = []
+    rst_table.append(f".. list-table:: {title}")
+    rst_table.append("   :header-rows: 1")
+    rst_table.append("")
+
+    # Add header row
+    header_line = "   * - " + "\n     - ".join(header_texts)
+    rst_table.append(header_line)
+
+    # Add rows
+    for row in row_data:
+        row_line = "   * - " + "\n     - ".join(row)
+        rst_table.append(row_line)
+
+    return '\n'.join(rst_table)
+
+
+def userinput(el):
+    return _indent(el, 3, "\n\n")
+
+
+def computeroutput(el):
+    return _indent(el, 3, "\n\n")
+
+
+# miscellaneous
+def keycombo(el):
+    return _join_children(el, ' + ')
+
+
+def keycap(el):
+    return ":kbd:`%s`" % el.text
+
+
+def warning(el):
+    return ".. warning::`%s`" % el.text
+
+
+def para(el):
+    return _block_separated_with_blank_line(el) + '\n\n \n\n'
+
+
+def simpara(el):
+    return _block_separated_with_blank_line(el)
+
+
+def important(el):
+    return _indent(el, 3, ".. note:: ", True)
+
+
+def itemizedlist(el):
+    return _indent(el, 2, "* ", True)
+
+
+def orderedlist(el):
+    return _indent(el, 2, "1. ", True)
+
+
+def refsect1(el):
+    return _block_separated_with_blank_line(el)
+
+
+def refsect2(el):
+    return _block_separated_with_blank_line(el)
+
+
+def refsect3(el):
+    return _block_separated_with_blank_line(el)
+
+
+def refsect4(el):
+    return _block_separated_with_blank_line(el)
+
+
+def refsect5(el):
+    return _block_separated_with_blank_line(el)
+
+
+def convert_xml_to_rst(xml_file_path, output_dir):
+    try:
+        _run(xml_file_path, output_dir)
+        return list(_not_handled_tags), ''
+    except Exception as e:
+        _warn('Failed to convert file %s' % xml_file_path)
+        return [], str(e)

doc-migration/main.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+
+import os
+import json
+import argparse
+from typing import List
+from db2rst import convert_xml_to_rst
+
+FILES_USED_FOR_INCLUDES = [
+    'sd_journal_get_data.xml', 'standard-options.xml', 'user-system-options.xml',
+    'common-variables.xml', 'standard-conf.xml', 'libsystemd-pkgconfig.xml', 'threads-aware.xml'
+]
+
+INCLUDES_DIR = "includes"
+
+
+def load_files_from_json(json_path: str) -> List[str]:
+    """
+    Loads a list of filenames from a JSON file.
+
+    Parameters:
+    json_path (str): Path to the JSON file.
+
+    Returns:
+    List[str]: List of filenames.
+    """
+    if not os.path.isfile(json_path):
+        print(f"Error: The file '{json_path}' does not exist.")
+        return []
+
+    with open(json_path, 'r') as json_file:
+        data = json.load(json_file)
+
+    return [entry['file'] for entry in data]
+
+
+def update_json_file(json_path: str, updated_entries: List[dict]) -> None:
+    """
+    Updates a JSON file with new entries.
+
+    Parameters:
+    json_path (str): Path to the JSON file.
+    updated_entries (List[dict]): List of updated entries to write to the JSON file.
+    """
+    with open(json_path, 'w') as json_file:
+        json.dump(updated_entries, json_file, indent=4)
+
+
+def process_xml_files_in_directory(dir: str, output_dir: str, specific_file: str = None, errored: bool = False, unhandled_only: bool = False) -> None:
+    """
+    Processes all XML files in a specified directory, logs results to a JSON file.
+
+    Parameters:
+    dir (str): Path to the directory containing XML files.
+    output_dir (str): Path to the JSON file for logging results.
+    specific_file (str, optional): Specific XML file to process. Defaults to None.
+    errored (bool, optional): Flag to process only files listed in errors.json. Defaults to False.
+    unhandled_only (bool, optional): Flag to process only files listed in successes_with_unhandled_tags.json. Defaults to False.
+    """
+    files_output_dir = os.path.join(output_dir, "files")
+    includes_output_dir = os.path.join(output_dir, INCLUDES_DIR)
+    os.makedirs(files_output_dir, exist_ok=True)
+    os.makedirs(includes_output_dir, exist_ok=True)
+
+    files_to_process = []
+
+    if errored:
+        errors_json_path = os.path.join(output_dir, "errors.json")
+        files_to_process = load_files_from_json(errors_json_path)
+        if not files_to_process:
+            print("No files to process from errors.json. Exiting.")
+            return
+    elif unhandled_only:
+        unhandled_json_path = os.path.join(
+            output_dir, "successes_with_unhandled_tags.json")
+        files_to_process = load_files_from_json(unhandled_json_path)
+        if not files_to_process:
+            print("No files to process from successes_with_unhandled_tags.json. Exiting.")
+            return
+    elif specific_file:
+        specific_file_path = os.path.join(dir, specific_file)
+        if os.path.isfile(specific_file_path):
+            files_to_process = [specific_file]
+        else:
+            print(f"Error: The file '{
+                  specific_file}' does not exist in the directory '{dir}'.")
+            return
+    else:
+        files_to_process = [f for f in os.listdir(dir) if f.endswith(".xml")]
+
+    errors_json_path = os.path.join(output_dir, "errors.json")
+    unhandled_json_path = os.path.join(
+        output_dir, "successes_with_unhandled_tags.json")
+
+    existing_errors = []
+    existing_unhandled = []
+
+    if os.path.exists(errors_json_path):
+        with open(errors_json_path, 'r') as json_file:
+            existing_errors = json.load(json_file)
+
+    if os.path.exists(unhandled_json_path):
+        with open(unhandled_json_path, 'r') as json_file:
+            existing_unhandled = json.load(json_file)
+
+    updated_errors = []
+    updated_successes_with_unhandled_tags = []
+
+    for filename in files_to_process:
+        filepath = os.path.join(dir, filename)
+        output_subdir = includes_output_dir if filename in FILES_USED_FOR_INCLUDES else files_output_dir
+        print('converting file: ', filename)
+        try:
+            unhandled_tags, error = convert_xml_to_rst(filepath, output_subdir)
+            if error:
+                result = {
+                    "file": filename,
+                    "status": "error",
+                    "unhandled_tags": unhandled_tags,
+                    "error": error
+                }
+                updated_errors.append(result)
+            else:
+                result = {
+                    "file": filename,
+                    "status": "success",
+                    "unhandled_tags": unhandled_tags,
+                    "error": error
+                }
+                if len(unhandled_tags) > 0:
+                    updated_successes_with_unhandled_tags.append(result)
+
+            existing_errors = [
+                entry for entry in existing_errors if entry['file'] != filename]
+            existing_unhandled = [
+                entry for entry in existing_unhandled if entry['file'] != filename]
+
+        except Exception as e:
+            result = {
+                "file": filename,
+                "status": "error",
+                "unhandled_tags": [],
+                "error": str(e)
+            }
+            updated_errors.append(result)
+
+    if not errored:
+        updated_errors += existing_errors
+
+    if not unhandled_only:
+        updated_successes_with_unhandled_tags += existing_unhandled
+
+    update_json_file(errors_json_path, updated_errors)
+    update_json_file(unhandled_json_path,
+                     updated_successes_with_unhandled_tags)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Process XML files and save results to a directory.")
+    parser.add_argument(
+        "--dir", type=str, help="Path to the directory containing XML files.", default="../man")
+    parser.add_argument(
+        "--output", type=str, help="Path to the output directory for results and log files.", default="in-progress")
+    parser.add_argument(
+        "--file", type=str, help="If provided, the script will only process the specified file.", default=None)
+    parser.add_argument("--errored", action='store_true',
+                        help="Process only files listed in errors.json.")
+    parser.add_argument("--unhandled-only", action='store_true',
+                        help="Process only files listed in successes_with_unhandled_tags.json.")
+
+    args = parser.parse_args()
+
+    process_xml_files_in_directory(
+        args.dir, args.output, args.file, args.errored, args.unhandled_only)
+
+
+if __name__ == "__main__":
+    main()

doc-migration/source/_ext/autogen_index.py

@@ -0,0 +1,63 @@
+import os
+from sphinx.application import Sphinx
+from sphinx.util.console import bold
+from sphinx.util.typing import ExtensionMetadata
+
+
+def generate_toctree(app: Sphinx):
+    root_dir = app.srcdir
+
+    index_path = os.path.join(root_dir, 'index.rst')
+    if not os.path.exists(index_path):
+        app.logger.warning(
+            f"{index_path} does not exist, skipping generation.")
+        return
+
+    with open(index_path, 'w') as index_file:
+        index_file.write(""".. SPDX-License-Identifier: LGPL-2.1-or-later
+.. systemd documentation master file, created by
+   sphinx-quickstart on Wed Jun 26 16:24:13 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+systemd — System and Service Manager
+===================================
+
+.. manual reference to a doc by its reference label
+   see: https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations
+.. Manual links
+.. ------------
+.. :ref:`busctl(1)`
+.. :ref:`systemd(1)`
+.. OR using the toctree to pull in files
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
+.. This only works if we restructure our headings to match
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
+   and then only have single top-level heading with the command name
+
+.. toctree::
+   :maxdepth: 1\n
+""")
+
+        for subdir, _, files in os.walk(root_dir + '/docs'):
+            if subdir == root_dir:
+                continue
+            for file in files:
+                if file.endswith('.rst'):
+                    file_path = os.path.relpath(
+                        os.path.join(subdir, file), root_dir)
+                    # remove the .rst extension
+                    index_file.write(f"   {file_path[:-4]}\n")
+
+        index_file.write("""
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search` """)
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.connect('builder-inited', generate_toctree)
+    return {'version': '0.1', 'parallel_read_safe': True, 'parallel_write_safe': True, }

doc-migration/source/_ext/directive_roles.py

@@ -0,0 +1,196 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+from __future__ import annotations
+from typing import List, Dict, Any
+from docutils import nodes
+
+from sphinx.locale import _
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxRole, SphinxDirective
+from sphinx.util.typing import ExtensionMetadata
+
+
+class directive_list(nodes.General, nodes.Element):
+    pass
+
+
+class InlineDirectiveRole(SphinxRole):
+    def run(self) -> tuple[List[nodes.Node], List[nodes.system_message]]:
+        target_id = f'directive-{self.env.new_serialno("directive")}-{
+            self.text}'
+
+        target_node = nodes.target('', self.text, ids=[target_id])
+
+        if not hasattr(self.env, 'directives'):
+            self.env.directives = []
+
+        self.env.directives.append({
+            'name': self.name,
+            'text': self.text,
+            'docname': self.env.docname,
+            'lineno': self.lineno,
+            'target_id': target_id,
+        })
+
+        return [target_node], []
+
+
+class ListDirectiveRoles(SphinxDirective):
+    def run(self) -> List[nodes.Node]:
+        return [directive_list('')]
+
+
+def register_directive_roles(app: Sphinx) -> None:
+    directives_data: List[Dict[str, Any]] = app.config.directives_data
+    role_types: List[str] = app.config.role_types
+
+    for directive in directives_data:
+        dir_id: str = directive['id']
+        for role_type in role_types:
+            role_name = f'directive:{dir_id}:{role_type}'
+            app.add_role(role_name, InlineDirectiveRole())
+
+
+def get_directive_metadata(app: Sphinx) -> Dict[str, Dict[str, Any]]:
+    directives_data: List[Dict[str, Any]] = app.config.directives_data
+    return {directive['id']: directive for directive in directives_data}
+
+
+def group_directives_by_id(env) -> Dict[str, List[Dict[str, Any]]]:
+    grouped_directives: Dict[str, List[Dict[str, Any]]] = {}
+    for dir_info in getattr(env, 'directives', []):
+        dir_id = dir_info['name'].split(':')[1]
+        if dir_id not in grouped_directives:
+            grouped_directives[dir_id] = []
+        grouped_directives[dir_id].append(dir_info)
+    return grouped_directives
+
+
+def create_reference_node(app: Sphinx, dir_info: Dict[str, Any], from_doc_name: str) -> nodes.reference:
+    ref_node = nodes.reference('', '')
+    ref_node['refdocname'] = dir_info['docname']
+    ref_node['refuri'] = app.builder.get_relative_uri(
+        from_doc_name, dir_info['docname']) + '#' + dir_info['target_id']
+
+    metadata: Dict[str, Any] = app.builder.env.metadata.get(
+        dir_info['docname'], {})
+    title: str = metadata.get('title', 'Unknown Title')
+    manvolnum: str = metadata.get('manvolnum', 'Unknown Volume')
+
+    ref_node.append(nodes.Text(f'{title}({manvolnum})'))
+    return ref_node
+
+
+def render_reference_node(references: List[nodes.reference]) -> nodes.paragraph:
+    para = nodes.inline()
+
+    for i, ref_node in enumerate(references):
+        para += ref_node
+        if i < len(references) - 1:
+            para += nodes.Text(", ")
+
+    return para
+
+
+def render_option(directive_text: str, references: List[nodes.reference]) -> nodes.section:
+    section = nodes.section()
+
+    title = nodes.title(text=directive_text, classes=['directive-header'])
+    title_id = nodes.make_id(directive_text)
+    title['ids'] = [title_id]
+    title['names'] = [directive_text]
+    section['ids'] = [title_id]
+    section += title
+
+    node = render_reference_node(references)
+    section += node
+
+    return section
+
+
+def render_variable(directive_text: str, references: List[nodes.reference]) -> nodes.section:
+    section = nodes.section()
+
+    title = nodes.title(text=directive_text, classes=['directive-header'])
+    title_id = nodes.make_id(directive_text)
+    title['ids'] = [title_id]
+    title['names'] = [directive_text]
+    section['ids'] = [title_id]
+    section += title
+
+    node = render_reference_node(references)
+    section += node
+
+    return section
+
+
+def render_constant(directive_text: str, references: List[nodes.reference]) -> nodes.section:
+    section = nodes.section()
+
+    title = nodes.title(text=directive_text, classes=['directive-header'])
+    title_id = nodes.make_id(directive_text)
+    title['ids'] = [title_id]
+    title['names'] = [directive_text]
+    section['ids'] = [title_id]
+    section += title
+
+    node = render_reference_node(references)
+    section += node
+
+    return section
+
+
+def process_items(app: Sphinx, doctree: nodes.document, from_doc_name: str) -> None:
+    env = app.builder.env
+    directive_lookup: Dict[str, Dict[str, Any]] = get_directive_metadata(app)
+    grouped_directives: Dict[str, List[Dict[str, Any]]
+                             ] = group_directives_by_id(env)
+
+    render_map = {
+        'option': render_option,
+        'var': render_variable,
+        'constant': render_constant,
+    }
+
+    for node in doctree.findall(directive_list):
+        content: List[nodes.section] = []
+
+        for dir_id, directives in grouped_directives.items():
+            directive_meta = directive_lookup.get(
+                dir_id, {'title': 'Unknown', 'description': 'No description available.'})
+            section = nodes.section(ids=[dir_id])
+            section += nodes.title(text=directive_meta['title'])
+            section += nodes.paragraph(text=directive_meta['description'])
+
+            directive_references: Dict[str, List[nodes.reference]] = {}
+
+            for dir_info in directives:
+                directive_text: str = dir_info['text']
+                role_type: str = dir_info['name'].split(':')[-1]
+
+                if directive_text not in directive_references:
+                    directive_references[directive_text] = []
+
+                ref_node = create_reference_node(app, dir_info, from_doc_name)
+                directive_references[directive_text].append(ref_node)
+
+            for directive_text, references in directive_references.items():
+                render_fn = render_map.get(role_type, render_option)
+                rendered_section = render_fn(directive_text, references)
+                section += rendered_section
+
+            content.append(section)
+        node.replace_self(content)
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_config_value('directives_data', [], 'env')
+    app.add_config_value('role_types', [], 'env')
+
+    register_directive_roles(app)
+    app.add_directive('list_directive_roles', ListDirectiveRoles)
+    app.connect('doctree-resolved', process_items)
+    return {
+        'version': '0.1',
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

doc-migration/source/_ext/external_man_links.py

@@ -0,0 +1,59 @@
+from typing import List, Dict, Tuple, Any
+from docutils import nodes
+from docutils.parsers.rst import roles, states
+import re
+
+# Define the extlink_formats dictionary with type annotations
+extlink_formats: Dict[str, str] = {
+    'man-pages': 'https://man7.org/linux/man-pages/man{manvolnum}/{refentrytitle}.{manvolnum}.html',
+    'die-net': 'http://linux.die.net/man/{manvolnum}/{refentrytitle}',
+    'mankier': 'https://www.mankier.com/{manvolnum}/{refentrytitle}',
+    'archlinux': 'https://man.archlinux.org/man/{refentrytitle}.{manvolnum}.en.html',
+    'debian': 'https://manpages.debian.org/unstable/{refentrytitle}/{refentrytitle}.{manvolnum}.en.html',
+    'freebsd': 'https://www.freebsd.org/cgi/man.cgi?query={refentrytitle}&sektion={manvolnum}',
+    'dbus': 'https://dbus.freedesktop.org/doc/dbus-specification.html#{refentrytitle}',
+}
+
+
+def man_role(
+    name: str,
+    rawtext: str,
+    text: str,
+    lineno: int,
+    inliner: states.Inliner,
+    options: Dict[str, Any] = {}
+) -> Tuple[List[nodes.reference], List[nodes.system_message]]:
+    # Regex to match text like 'locale(7)'
+    pattern = re.compile(r'(.+)\((\d+)\)')
+    match = pattern.match(text)
+    if not match:
+        msg = inliner.reporter.error(
+            f'Invalid man page format {text}, expected format "name(section)"',
+            nodes.literal_block(rawtext, rawtext),
+            line=lineno
+        )
+        return [inliner.problematic(rawtext, rawtext, msg)], [msg]
+
+    refentrytitle, manvolnum = match.groups()
+
+    if name not in extlink_formats:
+        msg = inliner.reporter.error(
+            f'Unknown man page role {name}',
+            nodes.literal_block(rawtext, rawtext),
+            line=lineno
+        )
+        return [inliner.problematic(rawtext, rawtext, msg)], [msg]
+
+    url = extlink_formats[name].format(
+        manvolnum=manvolnum, refentrytitle=refentrytitle
+    )
+    node = nodes.reference(
+        rawtext, f'{refentrytitle}({manvolnum})', refuri=url, **options
+    )
+    return [node], []
+
+
+def setup(app: Any) -> Dict[str, bool]:
+    for role in extlink_formats.keys():
+        roles.register_local_role(role, man_role)
+    return {'parallel_read_safe': True, 'parallel_write_safe': True}

doc-migration/source/_static/css/custom.css

@@ -0,0 +1,28 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+
+.sidebar-logo {
+  margin-inline: 0;
+}
+
+section {
+  margin-block-end: 2em;
+}
+
+/* Make right sidebar wider to accomodate long titles */
+.toc-drawer {
+  width: 100%;
+}
+
+/* Make Toc section headers bold */
+.toc-tree li a:has(+ ul) {
+  font-weight: 600;
+}
+
+.sig-name,
+.sig-prename {
+  color: var(--color-content-foreground);
+}
+
+.std.option {
+  margin-left: 2rem;
+}

doc-migration/source/_static/systemd-logo.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="202" height="26" viewBox="0 0 202 26" id="systemd-logo">
+    <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+    <path d="M0 0v26h10v-4H4V4h6V0zm76 0v4h6v18h-6v4h10V0z" fill="currentColor"/>
+    <path d="M113.498 14.926q-4.5-.96-4.5-3.878 0-1.079.609-1.981.621-.902 1.781-1.441 1.16-.54 2.707-.54 1.63 0 2.848.528 1.219.516 1.875 1.453.656.926.656 2.121h-3.539q0-.762-.457-1.183-.457-.434-1.394-.434-.774 0-1.243.363-.457.364-.457.938 0 .55.516.89.527.34 1.781.575 1.5.28 2.543.738 1.043.445 1.653 1.242.62.797.62 2.027 0 1.114-.667 2.004-.657.88-1.887 1.383-1.219.504-2.836.504-1.711 0-2.965-.621-1.242-.633-1.898-1.617-.645-.985-.645-2.051h3.34q.036.914.656 1.36.621.433 1.594.433.902 0 1.383-.34.492-.351.492-.937 0-.364-.223-.61-.21-.258-.773-.48-.55-.223-1.57-.446zm19.384-7.606l-5.086 14.58q-.293.831-.726 1.523-.434.703-1.266 1.195-.832.504-2.098.504-.457 0-.75-.048-.281-.046-.785-.176v-2.672q.176.02.527.02.95 0 1.418-.293.47-.293.715-.961l.352-.926-4.43-12.738h3.797l2.262 7.687 2.285-7.687zm5.884 7.606q-4.5-.96-4.5-3.878 0-1.079.61-1.981.62-.902 1.781-1.441 1.16-.54 2.707-.54 1.629 0 2.848.528 1.218.516 1.875 1.453.656.926.656 2.121h-3.539q0-.762-.457-1.183-.457-.434-1.395-.434-.773 0-1.242.363-.457.364-.457.938 0 .55.516.89.527.34 1.781.575 1.5.28 2.543.738 1.043.445 1.652 1.242.621.797.621 2.027 0 1.114-.668 2.004-.656.88-1.886 1.383-1.219.504-2.836.504-1.711 0-2.965-.621-1.242-.633-1.899-1.617-.644-.985-.644-2.051h3.34q.036.914.656 1.36.621.433 1.594.433.902 0 1.383-.34.492-.351.492-.937 0-.364-.223-.61-.21-.258-.773-.48-.551-.223-1.57-.446zm13.983 2.403q.574 0 .984-.082v2.66q-.914.328-2.086.328-3.727 0-3.727-3.797V9.899h-1.793V7.321h1.793v-3.14h3.54v3.14h2.132v2.578h-2.133v6.129q0 .75.293 1.031.293.27.997.27zm14.228-2.519h-8.016q.2 1.183.985 1.886.785.691 2.015.691.914 0 1.688-.34.785-.351 1.336-1.042l1.699 1.957q-.668.96-1.957 1.617-1.278.656-3 .656-1.946 0-3.387-.82-1.43-.82-2.203-2.227-.762-1.406-.762-3.105v-.446q0-1.898.715-3.386.715-1.489 2.063-2.32 1.347-.844 3.187-.844 1.793 0 3.059.761 1.265.762 1.922 2.168.656 1.395.656 3.293zm-3.469-2.65q-.024-1.03-.574-1.628-.54-.598-1.617-.598-1.008 0-1.582.668-.563.668-.739 1.84h4.512zm19.923-5.073q1.934 0 2.989 1.148 1.054 1.148 1.054 3.727v8.039h-3.539V11.95q0-.797-.21-1.23-.212-.446-.61-.61-.387-.164-.984-.164-.715 0-1.219.352-.504.34-.797.972.02.082.02.27V20h-3.54v-8.015q0-.797-.21-1.242-.211-.445-.61-.621-.386-.176-.996-.176-.68 0-1.183.304-.492.293-.797.844V20h-3.539V7.32h3.316l.118 1.419q.633-.797 1.547-1.22.926-.433 2.086-.433 1.172 0 2.016.48.855.47 1.312 1.442.633-.926 1.582-1.418.961-.504 2.203-.504zM201.398 2v18h-3.187l-.176-1.359q-1.243 1.594-3.212 1.594-1.535 0-2.66-.82-1.113-.832-1.699-2.285-.574-1.454-.574-3.317v-.246q0-1.934.574-3.398.586-1.465 1.7-2.274 1.124-.808 2.683-.808 1.805 0 3.012 1.37V2.001zm-5.672 15.376q1.488 0 2.133-1.266v-4.898q-.61-1.266-2.11-1.266-1.207 0-1.77.984-.55.985-.55 2.637v.246q0 1.629.54 2.602.55.96 1.757.96z" fill="currentColor"/>
+    <path d="M45 13L63 3v20z" fill="#30d475"/>
+    <circle cx="30" cy="13" r="9" fill="#30d475"/>
+</svg>

doc-migration/source/code-examples/c/event-quick-child.c

@@ -0,0 +1,43 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <assert.h>
+#include <stdio.h>
+#include <unistd.h>
+#include <systemd/sd-event.h>
+
+int main(int argc, char **argv) {
+  pid_t pid = fork();
+  assert(pid >= 0);
+
+  /* SIGCHLD signal must be blocked for sd_event_add_child to work */
+  sigset_t ss;
+  sigemptyset(&ss);
+  sigaddset(&ss, SIGCHLD);
+  sigprocmask(SIG_BLOCK, &ss, NULL);
+
+  if (pid == 0)  /* child */
+    sleep(1);
+
+  else {         /* parent */
+    sd_event *e = NULL;
+    int r;
+
+    /* Create the default event loop */
+    sd_event_default(&e);
+    assert(e);
+
+    /* We create a floating child event source (attached to 'e').
+     * The default handler will be called with 666 as userdata, which
+     * will become the exit value of the loop. */
+    r = sd_event_add_child(e, NULL, pid, WEXITED, NULL, (void*) 666);
+    assert(r >= 0);
+
+    r = sd_event_loop(e);
+    assert(r == 666);
+
+    sd_event_unref(e);
+  }
+
+  return 0;
+}

doc-migration/source/code-examples/c/glib-event-glue.c

@@ -0,0 +1,48 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdlib.h>
+#include <glib.h>
+#include <systemd/sd-event.h>
+
+typedef struct SDEventSource {
+  GSource source;
+  GPollFD pollfd;
+  sd_event *event;
+} SDEventSource;
+
+static gboolean event_prepare(GSource *source, gint *timeout_) {
+  return sd_event_prepare(((SDEventSource *)source)->event) > 0;
+}
+
+static gboolean event_check(GSource *source) {
+  return sd_event_wait(((SDEventSource *)source)->event, 0) > 0;
+}
+
+static gboolean event_dispatch(GSource *source, GSourceFunc callback, gpointer user_data) {
+  return sd_event_dispatch(((SDEventSource *)source)->event) > 0;
+}
+
+static void event_finalize(GSource *source) {
+  sd_event_unref(((SDEventSource *)source)->event);
+}
+
+static GSourceFuncs event_funcs = {
+  .prepare = event_prepare,
+  .check = event_check,
+  .dispatch = event_dispatch,
+  .finalize = event_finalize,
+};
+
+GSource *g_sd_event_create_source(sd_event *event) {
+  SDEventSource *source;
+
+  source = (SDEventSource *)g_source_new(&event_funcs, sizeof(SDEventSource));
+
+  source->event = sd_event_ref(event);
+  source->pollfd.fd = sd_event_get_fd(event);
+  source->pollfd.events = G_IO_IN | G_IO_HUP | G_IO_ERR;
+
+  g_source_add_poll((GSource *)source, &source->pollfd);
+
+  return (GSource *)source;
+}

doc-migration/source/code-examples/c/hwdb-usb-device.c

@@ -0,0 +1,31 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <stdio.h>
+#include <stdint.h>
+#include <systemd/sd-hwdb.h>
+
+int print_usb_properties(uint16_t vid, uint16_t pid) {
+  char match[128];
+  sd_hwdb *hwdb;
+  const char *key, *value;
+  int r;
+
+  /* Match this USB vendor and product ID combination */
+  snprintf(match, sizeof match, "usb:v%04Xp%04X", vid, pid);
+
+  r = sd_hwdb_new(&hwdb);
+  if (r < 0)
+    return r;
+
+  SD_HWDB_FOREACH_PROPERTY(hwdb, match, key, value)
+    printf("%s: \"%s\" → \"%s\"\n", match, key, value);
+
+  sd_hwdb_unref(hwdb);
+  return 0;
+}
+
+int main(int argc, char **argv) {
+  print_usb_properties(0x046D, 0xC534);
+  return 0;
+}

doc-migration/source/code-examples/c/id128-app-specific.c

@@ -0,0 +1,13 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdio.h>
+#include <systemd/sd-id128.h>
+
+#define OUR_APPLICATION_ID SD_ID128_MAKE(c2,73,27,73,23,db,45,4e,a6,3b,b9,6e,79,b5,3e,97)
+
+int main(int argc, char *argv[]) {
+  sd_id128_t id;
+  sd_id128_get_machine_app_specific(OUR_APPLICATION_ID, &id);
+  printf("Our application ID: " SD_ID128_FORMAT_STR "\n", SD_ID128_FORMAT_VAL(id));
+  return 0;
+}

doc-migration/source/code-examples/c/inotify-watch-tmp.c

@@ -0,0 +1,58 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdio.h>
+#include <string.h>
+#include <sys/inotify.h>
+
+#include <systemd/sd-event.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+static int inotify_handler(sd_event_source *source,
+                           const struct inotify_event *event,
+                           void *userdata) {
+
+  const char *desc = NULL;
+
+  sd_event_source_get_description(source, &desc);
+
+  if (event->mask & IN_Q_OVERFLOW)
+    printf("inotify-handler <%s>: overflow\n", desc);
+  else if (event->mask & IN_CREATE)
+    printf("inotify-handler <%s>: create on %s\n", desc, event->name);
+  else if (event->mask & IN_DELETE)
+    printf("inotify-handler <%s>: delete on %s\n", desc, event->name);
+  else if (event->mask & IN_MOVED_TO)
+    printf("inotify-handler <%s>: moved-to on %s\n", desc, event->name);
+
+  /* Terminate the program if an "exit" file appears */
+  if ((event->mask & (IN_CREATE|IN_MOVED_TO)) &&
+      strcmp(event->name, "exit") == 0)
+    sd_event_exit(sd_event_source_get_event(source), 0);
+
+  return 1;
+}
+
+int main(int argc, char **argv) {
+  _cleanup_(sd_event_unrefp) sd_event *event = NULL;
+  _cleanup_(sd_event_source_unrefp) sd_event_source *source1 = NULL, *source2 = NULL;
+
+  const char *path1 = argc > 1 ? argv[1] : "/tmp";
+  const char *path2 = argc > 2 ? argv[2] : NULL;
+
+  /* Note: failure handling is omitted for brevity */
+
+  sd_event_default(&event);
+
+  sd_event_add_inotify(event, &source1, path1,
+                       IN_CREATE | IN_DELETE | IN_MODIFY | IN_MOVED_TO,
+                       inotify_handler, NULL);
+  if (path2)
+    sd_event_add_inotify(event, &source2, path2,
+                         IN_CREATE | IN_DELETE | IN_MODIFY | IN_MOVED_TO,
+                         inotify_handler, NULL);
+
+  sd_event_loop(event);
+
+  return 0;
+}

doc-migration/source/code-examples/c/journal-enumerate-fields.c

@@ -0,0 +1,21 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <stdio.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+  sd_journal *j;
+  const char *field;
+  int r;
+
+  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+  if (r < 0) {
+    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+    return 1;
+  }
+  SD_JOURNAL_FOREACH_FIELD(j, field)
+    printf("%s\n", field);
+  sd_journal_close(j);
+  return 0;
+}

doc-migration/source/code-examples/c/journal-iterate-foreach.c

@@ -0,0 +1,30 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <stdio.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+  int r;
+  sd_journal *j;
+
+  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+  if (r < 0) {
+    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+    return 1;
+  }
+  SD_JOURNAL_FOREACH(j) {
+    const char *d;
+    size_t l;
+
+    r = sd_journal_get_data(j, "MESSAGE", (const void **)&d, &l);
+    if (r < 0) {
+      fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
+      continue;
+    }
+
+    printf("%.*s\n", (int) l, d);
+  }
+  sd_journal_close(j);
+  return 0;
+}

doc-migration/source/code-examples/c/journal-iterate-poll.c

@@ -0,0 +1,28 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <poll.h>
+#include <time.h>
+#include <systemd/sd-journal.h>
+
+int wait_for_changes(sd_journal *j) {
+  uint64_t t;
+  int msec;
+  struct pollfd pollfd;
+
+  sd_journal_get_timeout(j, &t);
+  if (t == (uint64_t) -1)
+    msec = -1;
+  else {
+    struct timespec ts;
+    uint64_t n;
+    clock_gettime(CLOCK_MONOTONIC, &ts);
+    n = (uint64_t) ts.tv_sec * 1000000 + ts.tv_nsec / 1000;
+    msec = t > n ? (int) ((t - n + 999) / 1000) : 0;
+  }
+
+  pollfd.fd = sd_journal_get_fd(j);
+  pollfd.events = sd_journal_get_events(j);
+  poll(&pollfd, 1, msec);
+  return sd_journal_process(j);
+}

doc-migration/source/code-examples/c/journal-iterate-unique.c

@@ -0,0 +1,27 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <stdio.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+  sd_journal *j;
+  const void *d;
+  size_t l;
+  int r;
+
+  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+  if (r < 0) {
+    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+    return 1;
+  }
+  r = sd_journal_query_unique(j, "_SYSTEMD_UNIT");
+  if (r < 0) {
+    fprintf(stderr, "Failed to query journal: %s\n", strerror(-r));
+    return 1;
+  }
+  SD_JOURNAL_FOREACH_UNIQUE(j, d, l)
+    printf("%.*s\n", (int) l, (const char*) d);
+  sd_journal_close(j);
+  return 0;
+}

doc-migration/source/code-examples/c/journal-iterate-wait.c

@@ -0,0 +1,44 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <stdio.h>
+#include <systemd/sd-journal.h>
+
+int main(int argc, char *argv[]) {
+  int r;
+  sd_journal *j;
+
+  r = sd_journal_open(&j, SD_JOURNAL_LOCAL_ONLY);
+  if (r < 0) {
+    fprintf(stderr, "Failed to open journal: %s\n", strerror(-r));
+    return 1;
+  }
+
+  for (;;)  {
+    const void *d;
+    size_t l;
+    r = sd_journal_next(j);
+    if (r < 0) {
+      fprintf(stderr, "Failed to iterate to next entry: %s\n", strerror(-r));
+      break;
+    }
+    if (r == 0) {
+      /* Reached the end, let's wait for changes, and try again */
+      r = sd_journal_wait(j, (uint64_t) -1);
+      if (r < 0) {
+        fprintf(stderr, "Failed to wait for changes: %s\n", strerror(-r));
+        break;
+      }
+      continue;
+    }
+    r = sd_journal_get_data(j, "MESSAGE", &d, &l);
+    if (r < 0) {
+      fprintf(stderr, "Failed to read message field: %s\n", strerror(-r));
+      continue;
+    }
+    printf("%.*s\n", (int) l, (const char*) d);
+  }
+
+  sd_journal_close(j);
+  return 0;
+}

doc-migration/source/code-examples/c/journal-stream-fd.c

@@ -0,0 +1,31 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <errno.h>
+#include <syslog.h>
+#include <stdio.h>
+#include <unistd.h>
+#include <systemd/sd-journal.h>
+#include <systemd/sd-daemon.h>
+
+int main(int argc, char *argv[]) {
+  int fd;
+  FILE *log;
+
+  fd = sd_journal_stream_fd("test", LOG_INFO, 1);
+  if (fd < 0) {
+    fprintf(stderr, "Failed to create stream fd: %s\n", strerror(-fd));
+    return 1;
+  }
+
+  log = fdopen(fd, "w");
+  if (!log) {
+    fprintf(stderr, "Failed to create file object: %s\n", strerror(errno));
+    close(fd);
+    return 1;
+  }
+  fprintf(log, "Hello World!\n");
+  fprintf(log, SD_WARNING "This is a warning!\n");
+  fclose(log);
+  return 0;
+}

doc-migration/source/code-examples/c/logcontrol-example.c

@@ -0,0 +1,251 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* Implements the LogControl1 interface as per specification:
+ * https://www.freedesktop.org/software/systemd/man/org.freedesktop.LogControl1.html
+ *
+ * Compile with 'cc logcontrol-example.c $(pkg-config --libs --cflags libsystemd)'
+ *
+ * To get and set properties via busctl:
+ *
+ * $ busctl --user get-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              SyslogIdentifier
+ *   s "example"
+ * $ busctl --user get-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              LogTarget
+ *   s "journal"
+ * $ busctl --user get-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              LogLevel
+ *   s "info"
+ * $ busctl --user set-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              LogLevel \
+ *                              "s" debug
+ * $ busctl --user get-property org.freedesktop.Example \
+ *                              /org/freedesktop/LogControl1 \
+ *                              org.freedesktop.LogControl1 \
+ *                              LogLevel
+ *   s "debug"
+ */
+
+#include <errno.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <syslog.h>
+#include <systemd/sd-bus.h>
+#include <systemd/sd-journal.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+static int log_error(int log_level, int error, const char *str) {
+  sd_journal_print(log_level, "%s failed: %s", str, strerror(-error));
+  return error;
+}
+
+typedef enum LogTarget {
+  LOG_TARGET_JOURNAL,
+  LOG_TARGET_KMSG,
+  LOG_TARGET_SYSLOG,
+  LOG_TARGET_CONSOLE,
+  _LOG_TARGET_MAX,
+} LogTarget;
+
+static const char* const log_target_table[_LOG_TARGET_MAX] = {
+  [LOG_TARGET_JOURNAL] = "journal",
+  [LOG_TARGET_KMSG]    = "kmsg",
+  [LOG_TARGET_SYSLOG]  = "syslog",
+  [LOG_TARGET_CONSOLE] = "console",
+};
+
+static const char* const log_level_table[LOG_DEBUG + 1] = {
+  [LOG_EMERG]   = "emerg",
+  [LOG_ALERT]   = "alert",
+  [LOG_CRIT]    = "crit",
+  [LOG_ERR]     = "err",
+  [LOG_WARNING] = "warning",
+  [LOG_NOTICE]  = "notice",
+  [LOG_INFO]    = "info",
+  [LOG_DEBUG]   = "debug",
+};
+
+typedef struct object {
+  const char *syslog_identifier;
+  LogTarget log_target;
+  int log_level;
+} object;
+
+static int property_get(
+                sd_bus *bus,
+                const char *path,
+                const char *interface,
+                const char *property,
+                sd_bus_message *reply,
+                void *userdata,
+                sd_bus_error *error) {
+
+  object *o = userdata;
+
+  if (strcmp(property, "LogLevel") == 0)
+    return sd_bus_message_append(reply, "s", log_level_table[o->log_level]);
+
+  if (strcmp(property, "LogTarget") == 0)
+    return sd_bus_message_append(reply, "s", log_target_table[o->log_target]);
+
+  if (strcmp(property, "SyslogIdentifier") == 0)
+    return sd_bus_message_append(reply, "s", o->syslog_identifier);
+
+  return sd_bus_error_setf(error,
+                           SD_BUS_ERROR_UNKNOWN_PROPERTY,
+                           "Unknown property '%s'",
+                           property);
+}
+
+static int property_set(
+                sd_bus *bus,
+                const char *path,
+                const char *interface,
+                const char *property,
+                sd_bus_message *message,
+                void *userdata,
+                sd_bus_error *error) {
+
+  object *o = userdata;
+  const char *value;
+  int r;
+
+  r = sd_bus_message_read(message, "s", &value);
+  if (r < 0)
+    return r;
+
+  if (strcmp(property, "LogLevel") == 0) {
+    int i;
+    for (i = 0; i < LOG_DEBUG + 1; i++)
+      if (strcmp(value, log_level_table[i]) == 0) {
+        o->log_level = i;
+        setlogmask(LOG_UPTO(i));
+        return 0;
+      }
+
+    return sd_bus_error_setf(error,
+                             SD_BUS_ERROR_INVALID_ARGS,
+                             "Invalid value for LogLevel: '%s'",
+                             value);
+  }
+
+  if (strcmp(property, "LogTarget") == 0) {
+    LogTarget i;
+    for (i = 0; i < _LOG_TARGET_MAX; i++)
+      if (strcmp(value, log_target_table[i]) == 0) {
+        o->log_target = i;
+        return 0;
+      }
+
+    return sd_bus_error_setf(error,
+                             SD_BUS_ERROR_INVALID_ARGS,
+                             "Invalid value for LogTarget: '%s'",
+                             value);
+  }
+
+  return sd_bus_error_setf(error,
+                           SD_BUS_ERROR_UNKNOWN_PROPERTY,
+                           "Unknown property '%s'",
+                           property);
+}
+
+/* https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html
+ */
+static const sd_bus_vtable vtable[] = {
+  SD_BUS_VTABLE_START(0),
+  SD_BUS_WRITABLE_PROPERTY(
+    "LogLevel", "s",
+    property_get, property_set,
+    0,
+    0),
+  SD_BUS_WRITABLE_PROPERTY(
+    "LogTarget", "s",
+    property_get, property_set,
+    0,
+    0),
+  SD_BUS_PROPERTY(
+    "SyslogIdentifier", "s",
+    property_get,
+    0,
+    SD_BUS_VTABLE_PROPERTY_CONST),
+  SD_BUS_VTABLE_END
+};
+
+int main(int argc, char **argv) {
+  /* The bus should be relinquished before the program terminates. The cleanup
+   * attribute allows us to do it nicely and cleanly whenever we exit the
+   * block.
+   */
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+
+  object o = {
+    .log_level = LOG_INFO,
+    .log_target = LOG_TARGET_JOURNAL,
+    .syslog_identifier = "example",
+  };
+  int r;
+
+  /* https://man7.org/linux/man-pages/man3/setlogmask.3.html
+   * Programs using syslog() instead of sd_journal can use this API to cut logs
+   * emission at the source.
+   */
+  setlogmask(LOG_UPTO(o.log_level));
+
+  /* Acquire a connection to the bus, letting the library work out the details.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_default.html
+   */
+  r = sd_bus_default(&bus);
+  if (r < 0)
+    return log_error(o.log_level, r, "sd_bus_default()");
+
+  /* Publish an interface on the bus, specifying our well-known object access
+   * path and public interface name.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_add_object.html
+   * https://dbus.freedesktop.org/doc/dbus-tutorial.html
+   */
+  r = sd_bus_add_object_vtable(bus, NULL,
+                               "/org/freedesktop/LogControl1",
+                               "org.freedesktop.LogControl1",
+                               vtable,
+                               &o);
+  if (r < 0)
+    return log_error(o.log_level, r, "sd_bus_add_object_vtable()");
+
+  /* By default the service is assigned an ephemeral name. Also add a fixed
+   * one, so that clients know whom to call.
+   * https://www.freedesktop.org/software/systemd/man/sd_bus_request_name.html
+   */
+  r = sd_bus_request_name(bus, "org.freedesktop.Example", 0);
+  if (r < 0)
+    return log_error(o.log_level, r, "sd_bus_request_name()");
+
+  for (;;) {
+    /* https://www.freedesktop.org/software/systemd/man/sd_bus_wait.html
+     */
+    r = sd_bus_wait(bus, UINT64_MAX);
+    if (r < 0)
+      return log_error(o.log_level, r, "sd_bus_wait()");
+    /* https://www.freedesktop.org/software/systemd/man/sd_bus_process.html
+     */
+    r = sd_bus_process(bus, NULL);
+    if (r < 0)
+      return log_error(o.log_level, r, "sd_bus_process()");
+  }
+
+  /* https://www.freedesktop.org/software/systemd/man/sd_bus_release_name.html
+   */
+  r = sd_bus_release_name(bus, "org.freedesktop.Example");
+  if (r < 0)
+    return log_error(o.log_level, r, "sd_bus_release_name()");
+
+  return 0;
+}

doc-migration/source/code-examples/c/notify-selfcontained-example.c

@@ -0,0 +1,188 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* Implement the systemd notify protocol without external dependencies.
+ * Supports both readiness notification on startup and on reloading,
+ * according to the protocol defined at:
+ * https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
+ * This protocol is guaranteed to be stable as per:
+ * https://systemd.io/PORTABILITY_AND_STABILITY/ */
+
+#define _GNU_SOURCE 1
+#include <errno.h>
+#include <inttypes.h>
+#include <signal.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+#include <time.h>
+#include <unistd.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+static void closep(int *fd) {
+  if (!fd || *fd < 0)
+    return;
+
+  close(*fd);
+  *fd = -1;
+}
+
+static int notify(const char *message) {
+  union sockaddr_union {
+    struct sockaddr sa;
+    struct sockaddr_un sun;
+  } socket_addr = {
+    .sun.sun_family = AF_UNIX,
+  };
+  size_t path_length, message_length;
+  _cleanup_(closep) int fd = -1;
+  const char *socket_path;
+
+  /* Verify the argument first */
+  if (!message)
+    return -EINVAL;
+
+  message_length = strlen(message);
+  if (message_length == 0)
+    return -EINVAL;
+
+  /* If the variable is not set, the protocol is a noop */
+  socket_path = getenv("NOTIFY_SOCKET");
+  if (!socket_path)
+    return 0; /* Not set? Nothing to do */
+
+  /* Only AF_UNIX is supported, with path or abstract sockets */
+  if (socket_path[0] != '/' && socket_path[0] != '@')
+    return -EAFNOSUPPORT;
+
+  path_length = strlen(socket_path);
+  /* Ensure there is room for NUL byte */
+  if (path_length >= sizeof(socket_addr.sun.sun_path))
+    return -E2BIG;
+
+  memcpy(socket_addr.sun.sun_path, socket_path, path_length);
+
+  /* Support for abstract socket */
+  if (socket_addr.sun.sun_path[0] == '@')
+    socket_addr.sun.sun_path[0] = 0;
+
+  fd = socket(AF_UNIX, SOCK_DGRAM|SOCK_CLOEXEC, 0);
+  if (fd < 0)
+    return -errno;
+
+  if (connect(fd, &socket_addr.sa, offsetof(struct sockaddr_un, sun_path) + path_length) != 0)
+    return -errno;
+
+  ssize_t written = write(fd, message, message_length);
+  if (written != (ssize_t) message_length)
+    return written < 0 ? -errno : -EPROTO;
+
+  return 1; /* Notified! */
+}
+
+static int notify_ready(void) {
+  return notify("READY=1");
+}
+
+static int notify_reloading(void) {
+  /* A buffer with length sufficient to format the maximum UINT64 value. */
+  char reload_message[sizeof("RELOADING=1\nMONOTONIC_USEC=18446744073709551615")];
+  struct timespec ts;
+  uint64_t now;
+
+  /* Notify systemd that we are reloading, including a CLOCK_MONOTONIC timestamp in usec
+   * so that the program is compatible with a Type=notify-reload service. */
+
+  if (clock_gettime(CLOCK_MONOTONIC, &ts) < 0)
+    return -errno;
+
+  if (ts.tv_sec < 0 || ts.tv_nsec < 0 ||
+      (uint64_t) ts.tv_sec > (UINT64_MAX - (ts.tv_nsec / 1000ULL)) / 1000000ULL)
+    return -EINVAL;
+
+  now = (uint64_t) ts.tv_sec * 1000000ULL + (uint64_t) ts.tv_nsec / 1000ULL;
+
+  if (snprintf(reload_message, sizeof(reload_message), "RELOADING=1\nMONOTONIC_USEC=%" PRIu64, now) < 0)
+    return -EINVAL;
+
+  return notify(reload_message);
+}
+
+static int notify_stopping(void) {
+  return notify("STOPPING=1");
+}
+
+static volatile sig_atomic_t reloading = 0;
+static volatile sig_atomic_t terminating = 0;
+
+static void signal_handler(int sig) {
+  if (sig == SIGHUP)
+    reloading = 1;
+  else if (sig == SIGINT || sig == SIGTERM)
+    terminating = 1;
+}
+
+int main(int argc, char **argv) {
+  struct sigaction sa = {
+    .sa_handler = signal_handler,
+    .sa_flags = SA_RESTART,
+  };
+  int r;
+
+  /* Setup signal handlers */
+  sigemptyset(&sa.sa_mask);
+  sigaction(SIGHUP, &sa, NULL);
+  sigaction(SIGINT, &sa, NULL);
+  sigaction(SIGTERM, &sa, NULL);
+
+  /* Do more service initialization work here … */
+
+  /* Now that all the preparations steps are done, signal readiness */
+
+  r = notify_ready();
+  if (r < 0) {
+    fprintf(stderr, "Failed to notify readiness to $NOTIFY_SOCKET: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  while (!terminating) {
+    if (reloading) {
+      reloading = false;
+
+      /* As a separate but related feature, we can also notify the manager
+       * when reloading configuration. This allows accurate state-tracking,
+       * and also automated hook-in of 'systemctl reload' without having to
+       * specify manually an ExecReload= line in the unit file. */
+
+      r = notify_reloading();
+      if (r < 0) {
+        fprintf(stderr, "Failed to notify reloading to $NOTIFY_SOCKET: %s\n", strerror(-r));
+        return EXIT_FAILURE;
+      }
+
+      /* Do some reconfiguration work here … */
+
+      r = notify_ready();
+      if (r < 0) {
+        fprintf(stderr, "Failed to notify readiness to $NOTIFY_SOCKET: %s\n", strerror(-r));
+        return EXIT_FAILURE;
+      }
+    }
+
+    /* Do some daemon work here … */
+    sleep(5);
+  }
+
+  r = notify_stopping();
+  if (r < 0) {
+    fprintf(stderr, "Failed to report termination to $NOTIFY_SOCKET: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  /* Do some shutdown work here … */
+
+  return EXIT_SUCCESS;
+}

doc-migration/source/code-examples/c/path-documents.c

@@ -0,0 +1,19 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <systemd/sd-path.h>
+
+int main(void) {
+  int r;
+  char *t;
+
+  r = sd_path_lookup(SD_PATH_USER_DOCUMENTS, NULL, &t);
+  if (r < 0)
+    return EXIT_FAILURE;
+
+  printf("~/Documents: %s\n", t);
+  free(t);
+
+  return EXIT_SUCCESS;
+}

doc-migration/source/code-examples/c/print-unit-path-call-method.c

@@ -0,0 +1,50 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* This is equivalent to:
+ * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \
+ *       org.freedesktop.systemd1.Manager GetUnitByPID $$
+ *
+ * Compile with 'cc print-unit-path-call-method.c -lsystemd'
+ */
+
+#include <errno.h>
+#include <stdio.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+#include <systemd/sd-bus.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+#define DESTINATION "org.freedesktop.systemd1"
+#define PATH        "/org/freedesktop/systemd1"
+#define INTERFACE   "org.freedesktop.systemd1.Manager"
+#define MEMBER      "GetUnitByPID"
+
+static int log_error(int error, const char *message) {
+  fprintf(stderr, "%s: %s\n", message, strerror(-error));
+  return error;
+}
+
+int main(int argc, char **argv) {
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+  _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
+  _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL;
+  int r;
+
+  r = sd_bus_open_system(&bus);
+  if (r < 0)
+    return log_error(r, "Failed to acquire bus");
+
+  r = sd_bus_call_method(bus, DESTINATION, PATH, INTERFACE, MEMBER, &error, &reply, "u", (unsigned) getpid());
+  if (r < 0)
+    return log_error(r, MEMBER " call failed");
+
+  const char *ans;
+  r = sd_bus_message_read(reply, "o", &ans);
+  if (r < 0)
+    return log_error(r, "Failed to read reply");
+
+  printf("Unit path is \"%s\".\n", ans);
+
+  return 0;
+}

doc-migration/source/code-examples/c/print-unit-path.c

@@ -0,0 +1,59 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+/* This is equivalent to:
+ * busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 \
+ *       org.freedesktop.systemd1.Manager GetUnitByPID $$
+ *
+ * Compile with 'cc print-unit-path.c -lsystemd'
+ */
+
+#include <errno.h>
+#include <stdio.h>
+#include <sys/types.h>
+#include <unistd.h>
+
+#include <systemd/sd-bus.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+#define DESTINATION "org.freedesktop.systemd1"
+#define PATH        "/org/freedesktop/systemd1"
+#define INTERFACE   "org.freedesktop.systemd1.Manager"
+#define MEMBER      "GetUnitByPID"
+
+static int log_error(int error, const char *message) {
+  fprintf(stderr, "%s: %s\n", message, strerror(-error));
+  return error;
+}
+
+int main(int argc, char **argv) {
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+  _cleanup_(sd_bus_error_free) sd_bus_error error = SD_BUS_ERROR_NULL;
+  _cleanup_(sd_bus_message_unrefp) sd_bus_message *reply = NULL, *m = NULL;
+  int r;
+
+  r = sd_bus_open_system(&bus);
+  if (r < 0)
+    return log_error(r, "Failed to acquire bus");
+
+  r = sd_bus_message_new_method_call(bus, &m,
+                                     DESTINATION, PATH, INTERFACE, MEMBER);
+  if (r < 0)
+    return log_error(r, "Failed to create bus message");
+
+  r = sd_bus_message_append(m, "u", (unsigned) getpid());
+  if (r < 0)
+    return log_error(r, "Failed to append to bus message");
+
+  r = sd_bus_call(bus, m, -1, &error, &reply);
+  if (r < 0)
+    return log_error(r, MEMBER " call failed");
+
+  const char *ans;
+  r = sd_bus_message_read(reply, "o", &ans);
+  if (r < 0)
+    return log_error(r, "Failed to read reply");
+
+  printf("Unit path is \"%s\".\n", ans);
+
+  return 0;
+}

doc-migration/source/code-examples/c/sd-bus-container-append.c

@@ -0,0 +1,20 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <systemd/sd-bus.h>
+
+int append_strings_to_message(sd_bus_message *m, const char *const *arr) {
+  const char *s;
+  int r;
+
+  r = sd_bus_message_open_container(m, 'a', "s");
+  if (r < 0)
+    return r;
+
+  for (s = *arr; *s; s++) {
+    r = sd_bus_message_append(m, "s", s);
+    if (r < 0)
+      return r;
+  }
+
+  return sd_bus_message_close_container(m);
+}

doc-migration/source/code-examples/c/sd-bus-container-read.c

@@ -0,0 +1,27 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <stdio.h>
+
+#include <systemd/sd-bus.h>
+
+int read_strings_from_message(sd_bus_message *m) {
+  int r;
+
+  r = sd_bus_message_enter_container(m, 'a', "s");
+  if (r < 0)
+    return r;
+
+  for (;;) {
+    const char *s;
+
+    r = sd_bus_message_read(m, "s", &s);
+    if (r < 0)
+      return r;
+    if (r == 0)
+      break;
+
+    printf("%s\n", s);
+  }
+
+  return sd_bus_message_exit_container(m);
+}

doc-migration/source/code-examples/c/sd_bus_error-example.c

@@ -0,0 +1,18 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#include <errno.h>
+#include <string.h>
+#include <unistd.h>
+#include <systemd/sd-bus.h>
+
+int writer_with_negative_errno_return(int fd, sd_bus_error *error) {
+  const char *message = "Hello, World!\n";
+
+  ssize_t n = write(fd, message, strlen(message));
+  if (n >= 0)
+    return n; /* On success, return the number of bytes written, possibly 0. */
+
+  /* On error, initialize the error structure, and also propagate the errno
+   * value that write(2) set for us. */
+  return sd_bus_error_set_errnof(error, errno, "Failed to write to fd %i: %s", fd, strerror(errno));
+}

doc-migration/source/code-examples/c/vtable-example.c

@@ -0,0 +1,143 @@
+/* SPDX-License-Identifier: MIT-0 */
+
+#define _GNU_SOURCE 1
+#include <errno.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <systemd/sd-bus.h>
+
+#define _cleanup_(f) __attribute__((cleanup(f)))
+
+typedef struct object {
+  char *name;
+  uint32_t number;
+} object;
+
+static int method(sd_bus_message *m, void *userdata, sd_bus_error *error) {
+  int r;
+
+  printf("Got called with userdata=%p\n", userdata);
+
+  if (sd_bus_message_is_method_call(m,
+                                    "org.freedesktop.systemd.VtableExample",
+                                    "Method4"))
+    return 1;
+
+  const char *string;
+  r = sd_bus_message_read(m, "s", &string);
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_message_read() failed: %s\n", strerror(-r));
+    return 0;
+  }
+
+  r = sd_bus_reply_method_return(m, "s", string);
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_reply_method_return() failed: %s\n", strerror(-r));
+    return 0;
+  }
+
+  return 1;
+}
+
+static const sd_bus_vtable vtable[] = {
+        SD_BUS_VTABLE_START(0),
+        SD_BUS_METHOD(
+            "Method1", "s", "s", method, 0),
+        SD_BUS_METHOD_WITH_NAMES_OFFSET(
+            "Method2",
+            "so", SD_BUS_PARAM(string) SD_BUS_PARAM(path),
+            "s", SD_BUS_PARAM(returnstring),
+            method, offsetof(object, number),
+            SD_BUS_VTABLE_DEPRECATED),
+        SD_BUS_METHOD_WITH_ARGS_OFFSET(
+            "Method3",
+            SD_BUS_ARGS("s", string, "o", path),
+            SD_BUS_RESULT("s", returnstring),
+            method, offsetof(object, number),
+            SD_BUS_VTABLE_UNPRIVILEGED),
+        SD_BUS_METHOD_WITH_ARGS(
+            "Method4",
+            SD_BUS_NO_ARGS,
+            SD_BUS_NO_RESULT,
+            method,
+            SD_BUS_VTABLE_UNPRIVILEGED),
+        SD_BUS_SIGNAL(
+            "Signal1",
+            "so",
+            0),
+        SD_BUS_SIGNAL_WITH_NAMES(
+            "Signal2",
+            "so", SD_BUS_PARAM(string) SD_BUS_PARAM(path),
+            0),
+        SD_BUS_SIGNAL_WITH_ARGS(
+            "Signal3",
+            SD_BUS_ARGS("s", string, "o", path),
+            0),
+        SD_BUS_WRITABLE_PROPERTY(
+            "AutomaticStringProperty", "s", NULL, NULL,
+            offsetof(object, name),
+            SD_BUS_VTABLE_PROPERTY_EMITS_CHANGE),
+        SD_BUS_WRITABLE_PROPERTY(
+            "AutomaticIntegerProperty", "u", NULL, NULL,
+            offsetof(object, number),
+            SD_BUS_VTABLE_PROPERTY_EMITS_INVALIDATION),
+        SD_BUS_VTABLE_END
+};
+
+int main(int argc, char **argv) {
+  _cleanup_(sd_bus_flush_close_unrefp) sd_bus *bus = NULL;
+  int r;
+
+  sd_bus_default(&bus);
+
+  object object = { .number = 666 };
+  object.name = strdup("name");
+  if (!object.name) {
+    fprintf(stderr, "OOM\n");
+    return EXIT_FAILURE;
+  }
+
+  r = sd_bus_add_object_vtable(bus, NULL,
+                               "/org/freedesktop/systemd/VtableExample",
+                               "org.freedesktop.systemd.VtableExample",
+                               vtable,
+                               &object);
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_add_object_vtable() failed: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  r = sd_bus_request_name(bus,
+                          "org.freedesktop.systemd.VtableExample",
+                          0);
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_request_name() failed: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  for (;;) {
+    r = sd_bus_wait(bus, UINT64_MAX);
+    if (r < 0) {
+      fprintf(stderr, "sd_bus_wait() failed: %s\n", strerror(-r));
+      return EXIT_FAILURE;
+    }
+
+    r = sd_bus_process(bus, NULL);
+    if (r < 0) {
+      fprintf(stderr, "sd_bus_process() failed: %s\n", strerror(-r));
+      return EXIT_FAILURE;
+    }
+  }
+
+  r = sd_bus_release_name(bus, "org.freedesktop.systemd.VtableExample");
+  if (r < 0) {
+    fprintf(stderr, "sd_bus_release_name() failed: %s\n", strerror(-r));
+    return EXIT_FAILURE;
+  }
+
+  free(object.name);
+
+  return 0;
+}

doc-migration/source/code-examples/py/90-rearrange-path.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT-0
+
+"""
+
+Proof-of-concept systemd environment generator that makes sure that bin dirs
+are always after matching sbin dirs in the path.
+(Changes /sbin:/bin:/foo/bar to /bin:/sbin:/foo/bar.)
+
+This generator shows how to override the configuration possibly created by
+earlier generators. It would be easier to write in bash, but let's have it
+in Python just to prove that we can, and to serve as a template for more
+interesting generators.
+
+"""
+
+import os
+import pathlib
+
+def rearrange_bin_sbin(path):
+    """Make sure any pair of …/bin, …/sbin directories is in this order
+
+    >>> rearrange_bin_sbin('/bin:/sbin:/usr/sbin:/usr/bin')
+    '/bin:/sbin:/usr/bin:/usr/sbin'
+    """
+    items = [pathlib.Path(p) for p in path.split(':')]
+    for i in range(len(items)):
+        if 'sbin' in items[i].parts:
+            ind = items[i].parts.index('sbin')
+            bin = pathlib.Path(*items[i].parts[:ind], 'bin', *items[i].parts[ind+1:])
+            if bin in items[i+1:]:
+                j = i + 1 + items[i+1:].index(bin)
+                items[i], items[j] = items[j], items[i]
+    return ':'.join(p.as_posix() for p in items)
+
+if __name__ == '__main__':
+    path = os.environ['PATH'] # This should be always set.
+                              # If it's not, we'll just crash, which is OK too.
+    new = rearrange_bin_sbin(path)
+    if new != path:
+        print('PATH={}'.format(new))

doc-migration/source/code-examples/py/check-os-release-simple.py

@@ -0,0 +1,12 @@
+#!/usr/bin/python
+# SPDX-License-Identifier: MIT-0
+
+import platform
+os_release = platform.freedesktop_os_release()
+
+pretty_name = os_release.get('PRETTY_NAME', 'Linux')
+print(f'Running on {pretty_name!r}')
+
+if 'fedora' in [os_release.get('ID', 'linux'),
+                *os_release.get('ID_LIKE', '').split()]:
+    print('Looks like Fedora!')

doc-migration/source/code-examples/py/check-os-release.py

@@ -0,0 +1,37 @@
+#!/usr/bin/python
+# SPDX-License-Identifier: MIT-0
+
+import ast
+import re
+import sys
+
+def read_os_release():
+    try:
+        filename = '/etc/os-release'
+        f = open(filename)
+    except FileNotFoundError:
+        filename = '/usr/lib/os-release'
+        f = open(filename)
+
+    for line_number, line in enumerate(f, start=1):
+        line = line.rstrip()
+        if not line or line.startswith('#'):
+            continue
+        m = re.match(r'([A-Z][A-Z_0-9]+)=(.*)', line)
+        if m:
+            name, val = m.groups()
+            if val and val[0] in '"\'':
+                val = ast.literal_eval(val)
+            yield name, val
+        else:
+            print(f'{filename}:{line_number}: bad line {line!r}',
+                  file=sys.stderr)
+
+os_release = dict(read_os_release())
+
+pretty_name = os_release.get('PRETTY_NAME', 'Linux')
+print(f'Running on {pretty_name!r}')
+
+if 'debian' in [os_release.get('ID', 'linux'),
+                *os_release.get('ID_LIKE', '').split()]:
+    print('Looks like Debian!')

doc-migration/source/code-examples/py/notify-selfcontained-example.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: MIT-0
+#
+# Implement the systemd notify protocol without external dependencies.
+# Supports both readiness notification on startup and on reloading,
+# according to the protocol defined at:
+# https://www.freedesktop.org/software/systemd/man/latest/sd_notify.html
+# This protocol is guaranteed to be stable as per:
+# https://systemd.io/PORTABILITY_AND_STABILITY/
+
+import errno
+import os
+import signal
+import socket
+import sys
+import time
+
+reloading = False
+terminating = False
+
+def notify(message):
+    if not message:
+        raise ValueError("notify() requires a message")
+
+    socket_path = os.environ.get("NOTIFY_SOCKET")
+    if not socket_path:
+        return
+
+    if socket_path[0] not in ("/", "@"):
+        raise OSError(errno.EAFNOSUPPORT, "Unsupported socket type")
+
+    # Handle abstract socket.
+    if socket_path[0] == "@":
+        socket_path = "\0" + socket_path[1:]
+
+    with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM | socket.SOCK_CLOEXEC) as sock:
+        sock.connect(socket_path)
+        sock.sendall(message)
+
+def notify_ready():
+    notify(b"READY=1")
+
+def notify_reloading():
+    microsecs = time.clock_gettime_ns(time.CLOCK_MONOTONIC) // 1000
+    notify(f"RELOADING=1\nMONOTONIC_USEC={microsecs}".encode())
+
+def notify_stopping():
+    notify(b"STOPPING=1")
+
+def reload(signum, frame):
+    global reloading
+    reloading = True
+
+def terminate(signum, frame):
+    global terminating
+    terminating = True
+
+def main():
+    print("Doing initial setup")
+    global reloading, terminating
+
+    # Set up signal handlers.
+    print("Setting up signal handlers")
+    signal.signal(signal.SIGHUP, reload)
+    signal.signal(signal.SIGINT, terminate)
+    signal.signal(signal.SIGTERM, terminate)
+
+    # Do any other setup work here.
+
+    # Once all setup is done, signal readiness.
+    print("Done setting up")
+    notify_ready()
+
+    print("Starting loop")
+    while not terminating:
+        if reloading:
+            print("Reloading")
+            reloading = False
+
+            # Support notifying the manager when reloading configuration.
+            # This allows accurate state tracking as well as automatically
+            # enabling 'systemctl reload' without needing to manually
+            # specify an ExecReload= line in the unit file.
+
+            notify_reloading()
+
+            # Do some reconfiguration work here.
+
+            print("Done reloading")
+            notify_ready()
+
+        # Do the real work here ...
+
+        print("Sleeping for five seconds")
+        time.sleep(5)
+
+    print("Terminating")
+    notify_stopping()
+
+if __name__ == "__main__":
+    sys.stdout.reconfigure(line_buffering=True)
+    print("Starting app")
+    main()
+    print("Stopped app")

doc-migration/source/code-examples/sh/check-os-release.sh

@@ -0,0 +1,11 @@
+#!/bin/sh -eu
+# SPDX-License-Identifier: MIT-0
+
+test -e /etc/os-release && os_release='/etc/os-release' || os_release='/usr/lib/os-release'
+. "${os_release}"
+
+echo "Running on ${PRETTY_NAME:-Linux}"
+
+if [ "${ID:-linux}" = "debian" ] || [ "${ID_LIKE#*debian*}" != "${ID_LIKE}" ]; then
+    echo "Looks like Debian!"
+fi

doc-migration/source/conf.py

@@ -0,0 +1,212 @@
+# SPDX-License-Identifier: LGPL-2.1-or-later
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import sys
+import os
+project = 'systemd'
+copyright = '2024, systemd'
+author = 'systemd'
+
+
+sys.path.append(os.path.abspath("./_ext"))
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ['sphinxcontrib.globalsubs',
+              'directive_roles', 'external_man_links', 'autogen_index']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']
+html_title = ''
+html_css_files = [
+    'css/custom.css',
+]
+html_theme_options = {
+    # TODO: update these `source`-options with the proper values
+    "source_repository": "https://github.com/neighbourhoodie/nh-systemd",
+    "source_branch": "man_pages_in_sphinx",
+    "source_directory": "doc-migration/source/",
+    "light_logo": "systemd-logo.svg",
+    "dark_logo": "systemd-logo.svg",
+    "light_css_variables": {
+        "color-brand-primary": "#35a764",
+        "color-brand-content": "#35a764",
+    },
+}
+
+
+man_pages = [
+    ('busctl', 'busctl', 'Introspect the bus', None, '1'),
+    ('journalctl', 'journalctl', 'Print log entries from the systemd journal', None, '1'),
+    ('os-release', 'os-release', 'Operating system identification', None, '5'),
+    ('systemd', 'systemd, init', 'systemd system and service manager', None, '1'),
+]
+
+global_substitutions = {f'v{n}': f'{n}' for n in range(183, 300)} | {
+    # Custom Entities
+    'MOUNT_PATH': '{{MOUNT_PATH}}',
+    'UMOUNT_PATH': '{{UMOUNT_PATH}}',
+    'SYSTEM_GENERATOR_DIR': '{{SYSTEM_GENERATOR_DIR}}',
+    'USER_GENERATOR_DIR': '{{USER_GENERATOR_DIR}}',
+    'SYSTEM_ENV_GENERATOR_DIR': '{{SYSTEM_ENV_GENERATOR_DIR}}',
+    'USER_ENV_GENERATOR_DIR': '{{USER_ENV_GENERATOR_DIR}}',
+    'CERTIFICATE_ROOT': '{{CERTIFICATE_ROOT}}',
+    'FALLBACK_HOSTNAME': '{{FALLBACK_HOSTNAME}}',
+    'MEMORY_ACCOUNTING_DEFAULT': "{{ 'yes' if MEMORY_ACCOUNTING_DEFAULT else 'no' }}",
+    'KILL_USER_PROCESSES': "{{ 'yes' if KILL_USER_PROCESSES else 'no' }}",
+    'DEBUGTTY': '{{DEBUGTTY}}',
+    'RC_LOCAL_PATH': '{{RC_LOCAL_PATH}}',
+    'HIGH_RLIMIT_NOFILE': '{{HIGH_RLIMIT_NOFILE}}',
+    'DEFAULT_DNSSEC_MODE': '{{DEFAULT_DNSSEC_MODE_STR}}',
+    'DEFAULT_DNS_OVER_TLS_MODE': '{{DEFAULT_DNS_OVER_TLS_MODE_STR}}',
+    'DEFAULT_TIMEOUT': '{{DEFAULT_TIMEOUT_SEC}} s',
+    'DEFAULT_USER_TIMEOUT': '{{DEFAULT_USER_TIMEOUT_SEC}} s',
+    'DEFAULT_KEYMAP': '{{SYSTEMD_DEFAULT_KEYMAP}}',
+    'fedora_latest_version': '40',
+    'fedora_cloud_release': '1.10',
+}
+
+# Existing lists of directive groups
+directives_data = [
+    {
+        "id": "unit-directives",
+        "title": "Unit directives",
+        "description": "Directives for configuring units, used in unit files."
+    },
+    {
+        "id": "kernel-commandline-options",
+        "title": "Options on the kernel command line",
+        "description": "Kernel boot options for configuring the behaviour of the systemd process."
+    },
+    {
+        "id": "smbios-type-11-options",
+        "title": "SMBIOS Type 11 Variables",
+        "description": "Data passed from VMM to system via SMBIOS Type 11."
+    },
+    {
+        "id": "environment-variables",
+        "title": "Environment variables",
+        "description": "Environment variables understood by the systemd manager and other programs and environment variable-compatible settings."
+    },
+    {
+        "id": "system-credentials",
+        "title": "System Credentials",
+        "description": "System credentials understood by the system and service manager and various other components:"
+    },
+    {
+        "id": "efi-variables",
+        "title": "EFI variables",
+        "description": "EFI variables understood by\n    "
+    },
+    {
+        "id": "home-directives",
+        "title": "Home Area/User Account directives",
+        "description": "Directives for configuring home areas and user accounts via\n    "
+    },
+    {
+        "id": "udev-directives",
+        "title": "UDEV directives",
+        "description": "Directives for configuring systemd units through the udev database."
+    },
+    {
+        "id": "network-directives",
+        "title": "Network directives",
+        "description": "Directives for configuring network links through the net-setup-link udev builtin and networks\n    through systemd-networkd."
+    },
+    {
+        "id": "journal-directives",
+        "title": "Journal fields",
+        "description": "Fields in the journal events with a well known meaning."
+    },
+    {
+        "id": "pam-directives",
+        "title": "PAM configuration directives",
+        "description": "Directives for configuring PAM behaviour."
+    },
+    {
+        "id": "fstab-options",
+        "title": 'fstab-options',
+        "description": "Options which influence mounted filesystems and encrypted volumes."
+    },
+    {
+        "id": "nspawn-directives",
+        "title": 'nspawn-directives',
+        "description": "Directives for configuring systemd-nspawn containers."
+    },
+    {
+        "id": "config-directives",
+        "title": "Program configuration options",
+        "description": "Directives for configuring the behaviour of the systemd process and other tools through\n    configuration files."
+    },
+    {
+        "id": "options",
+        "title": "Command line options",
+        "description": "Command-line options accepted by programs in the systemd suite."
+    },
+    {
+        "id": "constants",
+        "title": "Constants",
+        "description": "Various constants used and/or defined by systemd."
+    },
+    {
+        "id": "dns",
+        "title": "DNS resource record types",
+        "description": "No description available"
+    },
+    {
+        "id": "miscellaneous",
+        "title": "Miscellaneous options and directives",
+        "description": "Other configuration elements which don't fit in any of the above groups."
+    },
+    {
+        "id": "specifiers",
+        "title": "Specifiers",
+        "description": "Short strings which are substituted in configuration directives."
+    },
+    {
+        "id": "filenames",
+        "title": "Files and directories",
+        "description": "Paths and file names referred to in the documentation."
+    },
+    {
+        "id": "dbus-interface",
+        "title": "D-Bus interfaces",
+        "description": "Interfaces exposed over D-Bus."
+    },
+    {
+        "id": "dbus-method",
+        "title": "D-Bus methods",
+        "description": "Methods exposed in the D-Bus interface."
+    },
+    {
+        "id": "dbus-property",
+        "title": "D-Bus properties",
+        "description": "Properties exposed in the D-Bus interface."
+    },
+    {
+        "id": "dbus-signal",
+        "title": "D-Bus signals",
+        "description": "Signals emitted in the D-Bus interface."
+    }
+]
+
+role_types = [
+    'constant',
+    'var',
+    'option'
+]

doc-migration/source/docs/busctl.rst

@@ -0,0 +1,593 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+:title: busctl
+
+:manvolnum: 1
+
+.. _busctl(1):
+
+=========
+busctl(1)
+=========
+
+.. only:: html
+
+   busctl — Introspect the bus
+   ###########################
+
+   Synopsis
+   ########
+
+``busctl`` [OPTIONS...] [COMMAND] [<NAME>...]
+
+Description
+===========
+
+``busctl`` may be used to
+introspect and monitor the D-Bus bus.
+
+Commands
+========
+
+The following commands are understood:
+
+``list``
+--------
+
+Show all peers on the bus, by their service
+names. By default, shows both unique and well-known names, but
+this may be changed with the ``--unique`` and
+``--acquired`` switches. This is the default
+operation if no command is specified.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``status [<SERVICE>]``
+----------------------
+
+Show process information and credentials of a
+bus service (if one is specified by its unique or well-known
+name), a process (if one is specified by its numeric PID), or
+the owner of the bus (if no parameter is
+specified).
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``monitor [<SERVICE>...]``
+--------------------------
+
+Dump messages being exchanged. If
+<SERVICE> is specified, show messages
+to or from this peer, identified by its well-known or unique
+name. Otherwise, show all messages on the bus. Use
+:kbd:`Ctrl` + :kbd:`C`
+to terminate the dump.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``capture [<SERVICE>...]``
+--------------------------
+
+Similar to ``monitor`` but
+writes the output in pcapng format (for details, see
+`PCAP Next Generation (pcapng) Capture File Format <https://github.com/pcapng/pcapng/>`_).
+Make sure to redirect standard output to a file or pipe. Tools like
+:die-net:`wireshark(1)`
+may be used to dissect and view the resulting
+files.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``tree [<SERVICE>...]``
+-----------------------
+
+Shows an object tree of one or more
+services. If <SERVICE> is specified,
+show object tree of the specified services only. Otherwise,
+show all object trees of all services on the bus that acquired
+at least one well-known name.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``introspect <SERVICE> <OBJECT> [<INTERFACE>]``
+-----------------------------------------------
+
+Show interfaces, methods, properties and
+signals of the specified object (identified by its path) on
+the specified service. If the interface argument is passed, the
+output is limited to members of the specified
+interface.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``call <SERVICE> <OBJECT> <INTERFACE> <METHOD> [<SIGNATURE>[<ARGUMENT>...]]``
+-----------------------------------------------------------------------------
+
+Invoke a method and show the response. Takes a
+service name, object path, interface name and method name. If
+parameters shall be passed to the method call, a signature
+string is required, followed by the arguments, individually
+formatted as strings. For details on the formatting used, see
+below. To suppress output of the returned data, use the
+``--quiet`` option.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``emit <OBJECT> <INTERFACE> <SIGNAL> [<SIGNATURE>[<ARGUMENT>...]]``
+-------------------------------------------------------------------
+
+Emit a signal. Takes an object path, interface name and method name. If parameters
+shall be passed, a signature string is required, followed by the arguments, individually formatted as
+strings. For details on the formatting used, see below. To specify the destination of the signal,
+use the ``--destination=`` option.
+
+.. only:: html
+
+   .. versionadded:: 242
+
+``get-property <SERVICE> <OBJECT> <INTERFACE> <PROPERTY>``
+----------------------------------------------------------
+
+Retrieve the current value of one or more
+object properties. Takes a service name, object path,
+interface name and property name. Multiple properties may be
+specified at once, in which case their values will be shown one
+after the other, separated by newlines. The output is, by
+default, in terse format. Use ``--verbose`` for a
+more elaborate output format.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``set-property <SERVICE> <OBJECT> <INTERFACE> <PROPERTY> <SIGNATURE> <ARGUMENT>``
+---------------------------------------------------------------------------------
+
+Set the current value of an object
+property. Takes a service name, object path, interface name,
+property name, property signature, followed by a list of
+parameters formatted as strings.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``help``
+--------
+
+Show command syntax help.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+Options
+=======
+
+The following options are understood:
+
+``--address=<ADDRESS>``
+-----------------------
+
+Connect to the bus specified by
+<ADDRESS> instead of using suitable
+defaults for either the system or user bus (see
+``--system`` and ``--user``
+options).
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--show-machine``
+------------------
+
+When showing the list of peers, show a
+column containing the names of containers they belong to.
+See
+:ref:`systemd-machined.service(8)`.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--unique``
+------------
+
+When showing the list of peers, show only
+"unique" names (of the form
+":<number>.<number>").
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--acquired``
+--------------
+
+The opposite of ``--unique`` —
+only "well-known" names will be shown.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--activatable``
+-----------------
+
+When showing the list of peers, show only
+peers which have actually not been activated yet, but may be
+started automatically if accessed.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--match=<MATCH>``
+-------------------
+
+When showing messages being exchanged, show only the
+subset matching <MATCH>.
+See
+:ref:`sd_bus_add_match(3)`.
+
+.. only:: html
+
+   .. versionadded:: 209
+
+``--size=``
+-----------
+
+When used with the ``capture`` command,
+specifies the maximum bus message size to capture
+("snaplen"). Defaults to 4096 bytes.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--list``
+----------
+
+When used with the ``tree`` command, shows a
+flat list of object paths instead of a tree.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``-q, --quiet``
+---------------
+
+When used with the ``call`` command,
+suppresses display of the response message payload. Note that even
+if this option is specified, errors returned will still be
+printed and the tool will indicate success or failure with
+the process exit code.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--verbose``
+-------------
+
+When used with the ``call`` or
+``get-property`` command, shows output in a
+more verbose format.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--xml-interface``
+-------------------
+
+When used with the ``introspect`` call, dump the XML description received from
+the D-Bus ``org.freedesktop.DBus.Introspectable.Introspect`` call instead of the
+normal output.
+
+.. only:: html
+
+   .. versionadded:: 243
+
+``--json=<MODE>``
+-----------------
+
+When used with the ``call`` or ``get-property`` command, shows output
+formatted as JSON. Expects one of "short" (for the shortest possible output without any
+redundant whitespace or line breaks) or "pretty" (for a pretty version of the same, with
+indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
+way, which means type information is embedded into the JSON object tree.
+
+.. only:: html
+
+   .. versionadded:: 240
+
+``-j``
+------
+
+Equivalent to ``--json=pretty`` when invoked interactively from a terminal. Otherwise
+equivalent to ``--json=short``, in particular when the output is piped to some other
+program.
+
+.. only:: html
+
+   .. versionadded:: 240
+
+``--expect-reply=<BOOL>``
+-------------------------
+
+When used with the ``call`` command,
+specifies whether ``busctl`` shall wait for
+completion of the method call, output the returned method
+response data, and return success or failure via the process
+exit code. If this is set to "no", the
+method call will be issued but no response is expected, the
+tool terminates immediately, and thus no response can be
+shown, and no success or failure is returned via the exit
+code. To only suppress output of the reply message payload,
+use ``--quiet`` above. Defaults to
+"yes".
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--auto-start=<BOOL>``
+-----------------------
+
+When used with the ``call`` or ``emit`` command, specifies
+whether the method call should implicitly activate the
+called service, should it not be running yet but is
+configured to be auto-started. Defaults to
+"yes".
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--allow-interactive-authorization=<BOOL>``
+--------------------------------------------
+
+When used with the ``call`` command,
+specifies whether the services may enforce interactive
+authorization while executing the operation, if the security
+policy is configured for this. Defaults to
+"yes".
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--timeout=<SECS>``
+--------------------
+
+When used with the ``call`` command,
+specifies the maximum time to wait for method call
+completion. If no time unit is specified, assumes
+seconds. The usual other units are understood, too (ms, us,
+s, min, h, d, w, month, y). Note that this timeout does not
+apply if ``--expect-reply=no`` is used, as the
+tool does not wait for any reply message then. When not
+specified or when set to 0, the default of
+"25s" is assumed.
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--augment-creds=<BOOL>``
+--------------------------
+
+Controls whether credential data reported by
+``list`` or ``status`` shall
+be augmented with data from
+``/proc/``. When this is turned on, the data
+shown is possibly inconsistent, as the data read from
+``/proc/`` might be more recent than the rest of
+the credential information. Defaults to "yes".
+
+.. only:: html
+
+   .. versionadded:: 218
+
+``--watch-bind=<BOOL>``
+-----------------------
+
+Controls whether to wait for the specified ``AF_UNIX`` bus socket to appear in the
+file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
+the socket is created and then connect to it.
+
+.. only:: html
+
+   .. versionadded:: 237
+
+``--destination=<SERVICE>``
+---------------------------
+
+Takes a service name. When used with the ``emit`` command, a signal is
+emitted to the specified service.
+
+.. only:: html
+
+   .. versionadded:: 242
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove user
+                    :end-before: .. inclusion-end-marker-do-not-remove user
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove system
+                    :end-before: .. inclusion-end-marker-do-not-remove system
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove host
+                    :end-before: .. inclusion-end-marker-do-not-remove host
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove machine
+                    :end-before: .. inclusion-end-marker-do-not-remove machine
+
+.. include:: ../includes/user-system-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove capsule
+                    :end-before: .. inclusion-end-marker-do-not-remove capsule
+
+``-l, --full``
+--------------
+
+Do not ellipsize the output in ``list`` command.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+.. include:: ../includes/standard-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove no-pager
+                    :end-before: .. inclusion-end-marker-do-not-remove no-pager
+
+.. include:: ../includes/standard-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove no-legend
+                    :end-before: .. inclusion-end-marker-do-not-remove no-legend
+
+.. include:: ../includes/standard-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove help
+                    :end-before: .. inclusion-end-marker-do-not-remove help
+
+.. include:: ../includes/standard-options.rst
+                    :start-after: .. inclusion-marker-do-not-remove version
+                    :end-before: .. inclusion-end-marker-do-not-remove version
+
+Parameter Formatting
+====================
+
+The ``call`` and
+``set-property`` commands take a signature string
+followed by a list of parameters formatted as string (for details
+on D-Bus signature strings, see the `Type
+system chapter of the D-Bus specification <https://dbus.freedesktop.org/doc/dbus-specification.html#type-system>`_). For simple
+types, each parameter following the signature should simply be the
+parameter's value formatted as string. Positive boolean values may
+be formatted as "true", "yes",
+"on", or "1"; negative boolean
+values may be specified as "false",
+"no", "off", or
+"0". For arrays, a numeric argument for the
+number of entries followed by the entries shall be specified. For
+variants, the signature of the contents shall be specified,
+followed by the contents. For dictionaries and structs, the
+contents of them shall be directly specified.
+
+For example,
+
+.. code-block:: sh
+
+   s jawoll
+
+is the formatting
+of a single string "jawoll".
+
+.. code-block:: sh
+
+   as 3 hello world foobar
+
+is the formatting of a string array with three entries,
+"hello", "world" and
+"foobar".
+
+.. code-block:: sh
+
+   a{sv} 3 One s Eins Two u 2 Yes b true
+
+is the formatting of a dictionary
+array that maps strings to variants, consisting of three
+entries. The string "One" is assigned the
+string "Eins". The string
+"Two" is assigned the 32-bit unsigned
+integer 2. The string "Yes" is assigned a
+positive boolean.
+
+Note that the ``call``,
+``get-property``, ``introspect``
+commands will also generate output in this format for the returned
+data. Since this format is sometimes too terse to be easily
+understood, the ``call`` and
+``get-property`` commands may generate a more
+verbose, multi-line output when passed the
+``--verbose`` option.
+
+Examples
+========
+
+Write and Read a Property
+-------------------------
+
+The following two commands first write a property and then
+read it back. The property is found on the
+"/org/freedesktop/systemd1" object of the
+"org.freedesktop.systemd1" service. The name of
+the property is "LogLevel" on the
+"org.freedesktop.systemd1.Manager"
+interface. The property contains a single string:
+
+.. code-block:: sh
+
+   # busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
+   # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
+   s "debug"
+
+Terse and Verbose Output
+------------------------
+
+The following two commands read a property that contains
+an array of strings, and first show it in terse format, followed
+by verbose format:
+
+.. code-block:: sh
+
+   $ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
+   as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
+   $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
+   ARRAY "s" {
+           STRING "LANG=en_US.UTF-8";
+           STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
+   };
+
+Invoking a Method
+-----------------
+
+The following command invokes the
+"StartUnit" method on the
+"org.freedesktop.systemd1.Manager"
+interface of the
+"/org/freedesktop/systemd1" object
+of the "org.freedesktop.systemd1"
+service, and passes it two strings
+"cups.service" and
+"replace". As a result of the method
+call, a single object path parameter is received and
+shown:
+
+.. code-block:: sh
+
+   # busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
+   o "/org/freedesktop/systemd1/job/42684"
+
+See Also
+========
+
+:dbus:`dbus-daemon(1)`, `D-Bus <https://www.freedesktop.org/wiki/Software/dbus>`_, :ref:`sd-bus(3)`, :ref:`varlinkctl(1)`, :ref:`systemd(1)`, :ref:`machinectl(1)`, :die-net:`wireshark(1)`

doc-migration/source/docs/includes/sd_journal_get_data.rst

@@ -0,0 +1,315 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+:title: sd_journal_get_data
+
+:manvolnum: 3
+
+.. _sd_journal_get_data(3):
+
+======================
+sd_journal_get_data(3)
+======================
+
+.. only:: html
+
+   sd_journal_get_data — sd_journal_enumerate_data — sd_journal_enumerate_available_data — sd_journal_restart_data — SD_JOURNAL_FOREACH_DATA — sd_journal_set_data_threshold — sd_journal_get_data_threshold — Read data fields from the current journal entry
+   ###########################################################################################################################################################################################################################################################
+
+   Synopsis
+   ########
+
+``#include <systemd/sd-journal.h>``
+
+.. code-block::
+
+   int sd_journal_get_data(sd_journal *j,
+	const char *field,
+	const void **data,
+	size_t *length);
+
+.. code-block::
+
+   int sd_journal_enumerate_data(sd_journal *j,
+	const void **data,
+	size_t *length);
+
+.. code-block::
+
+   int sd_journal_enumerate_available_data(sd_journal *j,
+	const void **data,
+	size_t *length);
+
+.. code-block::
+
+   void sd_journal_restart_data(sd_journal *j);
+
+.. code-block::
+
+   SD_JOURNAL_FOREACH_DATA(sd_journal *j,
+	const void *data,
+	size_t length);
+
+.. code-block::
+
+   int sd_journal_set_data_threshold(sd_journal *j,
+	size_t sz);
+
+.. code-block::
+
+   int sd_journal_get_data_threshold(sd_journal *j,
+	size_t *sz);
+
+Description
+===========
+
+sd_journal_get_data() gets the data object associated with a specific field
+from the current journal entry. It takes four arguments: the journal context object, a string with the
+field name to request, plus a pair of pointers to pointer/size variables where the data object and its
+size shall be stored in. The field name should be an entry field name. Well-known field names are listed in
+:ref:`systemd.journal-fields(7)`,
+but any field can be specified. The returned data is in a read-only memory map and is only valid until
+the next invocation of sd_journal_get_data(),
+sd_journal_enumerate_data(),
+sd_journal_enumerate_available_data(), or when the read pointer is altered. Note
+that the data returned will be prefixed with the field name and "=". Also note that, by
+default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned
+off with sd_journal_set_data_threshold() (see below).
+
+sd_journal_enumerate_data() may be used
+to iterate through all fields of the current entry. On each
+invocation the data for the next field is returned. The order of
+these fields is not defined. The data returned is in the same
+format as with sd_journal_get_data() and also
+follows the same life-time semantics.
+
+sd_journal_enumerate_available_data() is similar to
+sd_journal_enumerate_data(), but silently skips any fields which may be valid, but
+are too large or not supported by current implementation.
+
+sd_journal_restart_data() resets the
+data enumeration index to the beginning of the entry. The next
+invocation of sd_journal_enumerate_data()
+will return the first field of the entry again.
+
+Note that the SD_JOURNAL_FOREACH_DATA() macro may be used as a handy wrapper
+around sd_journal_restart_data() and
+sd_journal_enumerate_available_data().
+
+Note that these functions will not work before
+:ref:`sd_journal_next(3)`
+(or related call) has been called at least once, in order to
+position the read pointer at a valid entry.
+
+sd_journal_set_data_threshold() may be
+used to change the data field size threshold for data returned by
+sd_journal_get_data(),
+sd_journal_enumerate_data() and
+sd_journal_enumerate_unique(). This threshold
+is a hint only: it indicates that the client program is interested
+only in the initial parts of the data fields, up to the threshold
+in size — but the library might still return larger data objects.
+That means applications should not rely exclusively on this
+setting to limit the size of the data fields returned, but need to
+apply an explicit size limit on the returned data as well. This
+threshold defaults to 64K by default. To retrieve the complete
+data fields this threshold should be turned off by setting it to
+0, so that the library always returns the complete data objects.
+It is recommended to set this threshold as low as possible since
+this relieves the library from having to decompress large
+compressed data objects in full.
+
+sd_journal_get_data_threshold() returns
+the currently configured data field size threshold.
+
+Return Value
+============
+
+sd_journal_get_data() returns 0 on success or a negative errno-style error
+code. sd_journal_enumerate_data() and
+sd_journal_enumerate_available_data() return a positive integer if the next field
+has been read, 0 when no more fields remain, or a negative errno-style error code.
+sd_journal_restart_data() doesn't return anything.
+sd_journal_set_data_threshold() and sd_journal_get_threshold()
+return 0 on success or a negative errno-style error code.
+
+Errors
+------
+
+Returned errors may indicate the following problems:
+
+.. inclusion-marker-do-not-remove EINVAL
+
+.. option:: -EINVAL
+
+   One of the required parameters is ``NULL`` or invalid.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EINVAL
+
+.. inclusion-marker-do-not-remove ECHILD
+
+.. option:: -ECHILD
+
+   The journal object was created in a different process, library or module instance.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ECHILD
+
+.. inclusion-marker-do-not-remove EADDRNOTAVAIL
+
+.. option:: -EADDRNOTAVAIL
+
+   The read pointer is not positioned at a valid entry;
+   :ref:`sd_journal_next(3)`
+   or a related call has not been called at least once.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EADDRNOTAVAIL
+
+.. inclusion-marker-do-not-remove ENOENT
+
+.. option:: -ENOENT
+
+   The current entry does not include the specified field.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOENT
+
+.. inclusion-marker-do-not-remove ENOMEM
+
+.. option:: -ENOMEM
+
+   Memory allocation failed.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOMEM
+
+.. inclusion-marker-do-not-remove ENOBUFS
+
+.. option:: -ENOBUFS
+
+   A compressed entry is too large.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOBUFS
+
+.. inclusion-marker-do-not-remove E2BIG
+
+.. option:: -E2BIG
+
+   The data field is too large for this computer architecture (e.g. above 4 GB on a
+   32-bit architecture).
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove E2BIG
+
+.. inclusion-marker-do-not-remove EPROTONOSUPPORT
+
+.. option:: -EPROTONOSUPPORT
+
+   The journal is compressed with an unsupported method or the journal uses an
+   unsupported feature.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EPROTONOSUPPORT
+
+.. inclusion-marker-do-not-remove EBADMSG
+
+.. option:: -EBADMSG
+
+   The journal is corrupted (possibly just the entry being iterated over).
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EBADMSG
+
+.. inclusion-marker-do-not-remove EIO
+
+.. option:: -EIO
+
+   An I/O error was reported by the kernel.
+
+   .. only:: html
+
+      .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EIO
+
+Notes
+=====
+
+.. include:: ../includes/threads-aware.rst
+                    :start-after: .. inclusion-marker-do-not-remove strict
+                    :end-before: .. inclusion-end-marker-do-not-remove strict
+
+.. include:: ../includes/libsystemd-pkgconfig.rst
+                    :start-after: .. inclusion-marker-do-not-remove pkgconfig-text
+                    :end-before: .. inclusion-end-marker-do-not-remove pkgconfig-text
+
+Examples
+========
+
+See
+:ref:`sd_journal_next(3)`
+for a complete example how to use
+sd_journal_get_data().
+
+Use the
+SD_JOURNAL_FOREACH_DATA() macro to
+iterate through all fields of the current journal
+entry:
+
+.. code-block:: sh
+
+   …
+   int print_fields(sd_journal *j) {
+     const void *data;
+     size_t length;
+     SD_JOURNAL_FOREACH_DATA(j, data, length)
+       printf("%.*s\n", (int) length, data);
+   }
+   …
+
+History
+=======
+
+sd_journal_get_data(),
+sd_journal_enumerate_data(),
+sd_journal_restart_data(), and
+SD_JOURNAL_FOREACH_DATA() were added in version 187.
+
+sd_journal_set_data_threshold() and
+sd_journal_get_data_threshold() were added in version 196.
+
+sd_journal_enumerate_available_data() was added in version 246.
+
+See Also
+========
+
+:ref:`systemd(1)`, :ref:`systemd.journal-fields(7)`, :ref:`sd-journal(3)`, :ref:`sd_journal_open(3)`, :ref:`sd_journal_next(3)`, :ref:`sd_journal_get_realtime_usec(3)`, :ref:`sd_journal_query_unique(3)`

doc-migration/source/docs/os-release.rst

@@ -0,0 +1,576 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+:title: os-release
+
+:manvolnum: 5
+
+.. _os-release(5):
+
+=============
+os-release(5)
+=============
+
+.. only:: html
+
+   os-release — initrd-release — extension-release — Operating system identification
+   #################################################################################
+
+   Synopsis
+   ########
+
+``/etc/os-release``
+``/usr/lib/os-release``
+``/etc/initrd-release``
+``/usr/lib/extension-release.d/extension-release.<IMAGE>``
+
+Description
+===========
+
+The ``/etc/os-release`` and
+``/usr/lib/os-release`` files contain operating
+system identification data.
+
+The format of ``os-release`` is a newline-separated list of
+environment-like shell-compatible variable assignments. It is possible to source the configuration from
+Bourne shell scripts, however, beyond mere variable assignments, no shell features are supported (this
+means variable expansion is explicitly not supported), allowing applications to read the file without
+implementing a shell compatible execution engine. Variable assignment values must be enclosed in double
+or single quotes if they include spaces, semicolons or other special characters outside of A–Z, a–z,
+0–9. (Assignments that do not include these special characters may be enclosed in quotes too, but this is
+optional.) Shell special characters ("$", quotes, backslash, backtick) must be escaped with backslashes,
+following shell style. All strings should be in UTF-8 encoding, and non-printable characters should not
+be used. Concatenation of multiple individually quoted strings is not supported. Lines beginning with "#"
+are treated as comments. Blank lines are permitted and ignored.
+
+The file ``/etc/os-release`` takes
+precedence over ``/usr/lib/os-release``.
+Applications should check for the former, and exclusively use its
+data if it exists, and only fall back to
+``/usr/lib/os-release`` if it is missing.
+Applications should not read data from both files at the same
+time. ``/usr/lib/os-release`` is the recommended
+place to store OS release information as part of vendor trees.
+``/etc/os-release`` should be a relative symlink
+to ``/usr/lib/os-release``, to provide
+compatibility with applications only looking at
+``/etc/``. A relative symlink instead of an
+absolute symlink is necessary to avoid breaking the link in a
+chroot or initrd environment.
+
+``os-release`` contains data that is
+defined by the operating system vendor and should generally not be
+changed by the administrator.
+
+As this file only encodes names and identifiers it should
+not be localized.
+
+The ``/etc/os-release`` and
+``/usr/lib/os-release`` files might be symlinks
+to other files, but it is important that the file is available
+from earliest boot on, and hence must be located on the root file
+system.
+
+``os-release`` must not contain repeating keys. Nevertheless, readers should pick
+the entries later in the file in case of repeats, similarly to how a shell sourcing the file would. A
+reader may warn about repeating entries.
+
+For a longer rationale for ``os-release``
+please refer to the `Announcement of ``/etc/os-release`` <https://0pointer.de/blog/projects/os-release>`_.
+
+``/etc/initrd-release``
+-----------------------
+
+In the `initrd <https://docs.kernel.org/admin-guide/initrd.html>`_,
+``/etc/initrd-release`` plays the same role as ``os-release`` in the
+main system. Additionally, the presence of that file means that the system is in the initrd phase.
+``/etc/os-release`` should be symlinked to ``/etc/initrd-release``
+(or vice versa), so programs that only look for ``/etc/os-release`` (as described
+above) work correctly.
+
+The rest of this document that talks about ``os-release`` should be understood
+to apply to ``initrd-release`` too.
+
+``/usr/lib/extension-release.d/extension-release.<IMAGE>``
+----------------------------------------------------------
+
+``/usr/lib/extension-release.d/extension-release.<IMAGE>``
+plays the same role for extension images as ``os-release`` for the main system, and
+follows the syntax and rules as described in the `Portable Services <https://systemd.io/PORTABLE_SERVICES>`_ page. The purpose of this
+file is to identify the extension and to allow the operating system to verify that the extension image
+matches the base OS. This is typically implemented by checking that the ``ID=`` options
+match, and either ``SYSEXT_LEVEL=`` exists and matches too, or if it is not present,
+``VERSION_ID=`` exists and matches. This ensures ABI/API compatibility between the
+layers and prevents merging of an incompatible image in an overlay.
+
+In order to identify the extension image itself, the same fields defined below can be added to the
+``extension-release`` file with a ``SYSEXT_`` prefix (to disambiguate
+from fields used to match on the base image). E.g.: ``SYSEXT_ID=myext``,
+``SYSEXT_VERSION_ID=1.2.3``.
+
+In the ``extension-release.<IMAGE>`` filename, the
+<IMAGE> part must exactly match the file name of the containing image with the
+suffix removed. In case it is not possible to guarantee that an image file name is stable and doesn't
+change between the build and the deployment phases, it is possible to relax this check: if exactly one
+file whose name matches "``extension-release.*``" is present in this
+directory, and the file is tagged with a ``user.extension-release.strict``
+:man-pages:`xattr(7)` set to the
+string "0", it will be used instead.
+
+The rest of this document that talks about ``os-release`` should be understood
+to apply to ``extension-release`` too.
+
+Options
+=======
+
+The following OS identifications parameters may be set using
+``os-release``:
+
+General information identifying the operating system
+----------------------------------------------------
+
+.. option:: NAME=
+
+   A string identifying the operating system, without a version component, and
+   suitable for presentation to the user. If not set, a default of "NAME=Linux" may
+   be used.
+
+   Examples: "NAME=Fedora", "NAME="Debian GNU/Linux"".
+
+.. option:: ID=
+
+   A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
+   and "-") identifying the operating system, excluding any version information and suitable for
+   processing by scripts or usage in generated filenames. If not set, a default of
+   "ID=linux" may be used. Note that even though this string may not include
+   characters that require shell quoting, quoting may nevertheless be used.
+
+   Examples: "ID=fedora", "ID=debian".
+
+.. option:: ID_LIKE=
+
+   A space-separated list of operating system identifiers in the same syntax as the
+   :directive:environment-variables:var:`ID=` setting. It should list identifiers of operating systems that are closely
+   related to the local operating system in regards to packaging and programming interfaces, for
+   example listing one or more OS identifiers the local OS is a derivative from.  An OS should
+   generally only list other OS identifiers it itself is a derivative of, and not any OSes that are
+   derived from it, though symmetric relationships are possible. Build scripts and similar should
+   check this variable if they need to identify the local operating system and the value of
+   :directive:environment-variables:var:`ID=` is not recognized. Operating systems should be listed in order of how
+   closely the local operating system relates to the listed ones, starting with the closest. This
+   field is optional.
+
+   Examples: for an operating system with "ID=centos", an assignment of
+   "ID_LIKE="rhel fedora"" would be appropriate. For an operating system with
+   "ID=ubuntu", an assignment of "ID_LIKE=debian" is appropriate.
+
+.. option:: PRETTY_NAME=
+
+   A pretty operating system name in a format suitable for presentation to the
+   user. May or may not contain a release code name or OS version of some kind, as suitable. If not
+   set, a default of "PRETTY_NAME="Linux"" may be used
+
+   Example: "PRETTY_NAME="Fedora 17 (Beefy Miracle)"".
+
+.. option:: CPE_NAME=
+
+   A CPE name for the operating system, in URI binding syntax, following the `Common Platform Enumeration Specification <http://scap.nist.gov/specifications/cpe/>`_ as
+   proposed by the NIST. This field is optional.
+
+   Example: "CPE_NAME="cpe:/o:fedoraproject:fedora:17""
+
+.. option:: VARIANT=
+
+   A string identifying a specific variant or edition of the operating system suitable
+   for presentation to the user. This field may be used to inform the user that the configuration of
+   this system is subject to a specific divergent set of rules or default configuration settings. This
+   field is optional and may not be implemented on all systems.
+
+   Examples: "VARIANT="Server Edition"", "VARIANT="Smart Refrigerator
+   Edition"".
+
+   Note: this field is for display purposes only. The :directive:environment-variables:var:`VARIANT_ID` field should
+   be used for making programmatic decisions.
+
+   .. only:: html
+
+      .. versionadded:: 220
+
+.. option:: VARIANT_ID=
+
+   A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_" and
+   "-"), identifying a specific variant or edition of the operating system. This may be interpreted by
+   other packages in order to determine a divergent default configuration. This field is optional and
+   may not be implemented on all systems.
+
+   Examples: "VARIANT_ID=server", "VARIANT_ID=embedded".
+
+   .. only:: html
+
+      .. versionadded:: 220
+
+Information about the version of the operating system
+-----------------------------------------------------
+
+.. option:: VERSION=
+
+   A string identifying the operating system version, excluding any OS name
+   information, possibly including a release code name, and suitable for presentation to the
+   user. This field is optional.
+
+   Examples: "VERSION=17", "VERSION="17 (Beefy Miracle)"".
+
+.. option:: VERSION_ID=
+
+   A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
+   a–z, ".", "_" and "-") identifying the operating system version, excluding any OS name information
+   or release code name, and suitable for processing by scripts or usage in generated filenames. This
+   field is optional.
+
+   Examples: "VERSION_ID=17", "VERSION_ID=11.04".
+
+.. option:: VERSION_CODENAME=
+
+   A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
+   and "-") identifying the operating system release code name, excluding any OS name information or
+   release version, and suitable for processing by scripts or usage in generated filenames. This field
+   is optional and may not be implemented on all systems.
+
+   Examples: "VERSION_CODENAME=buster",
+   "VERSION_CODENAME=xenial".
+
+   .. only:: html
+
+      .. versionadded:: 231
+
+.. option:: BUILD_ID=
+
+   A string uniquely identifying the system image originally used as the installation
+   base. In most cases, :directive:environment-variables:var:`VERSION_ID` or
+   :directive:environment-variables:var:`IMAGE_ID`+:directive:environment-variables:var:`IMAGE_VERSION` are updated when the entire system
+   image is replaced during an update. :directive:environment-variables:var:`BUILD_ID` may be used in distributions where
+   the original installation image version is important: :directive:environment-variables:var:`VERSION_ID` would change
+   during incremental system updates, but :directive:environment-variables:var:`BUILD_ID` would not. This field is
+   optional.
+
+   Examples: "BUILD_ID="2013-03-20.3"", "BUILD_ID=201303203".
+
+   .. only:: html
+
+      .. versionadded:: 200
+
+.. option:: IMAGE_ID=
+
+   A lower-case string (no spaces or other characters outside of 0–9, a–z, ".", "_"
+   and "-"), identifying a specific image of the operating system. This is supposed to be used for
+   environments where OS images are prepared, built, shipped and updated as comprehensive, consistent
+   OS images. This field is optional and may not be implemented on all systems, in particularly not on
+   those that are not managed via images but put together and updated from individual packages and on
+   the local system.
+
+   Examples: "IMAGE_ID=vendorx-cashier-system",
+   "IMAGE_ID=netbook-image".
+
+   .. only:: html
+
+      .. versionadded:: 249
+
+.. option:: IMAGE_VERSION=
+
+   A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
+   a–z, ".", "_" and "-") identifying the OS image version. This is supposed to be used together with
+   :directive:environment-variables:var:`IMAGE_ID` described above, to discern different versions of the same image.
+
+   Examples: "IMAGE_VERSION=33", "IMAGE_VERSION=47.1rc1".
+
+   .. only:: html
+
+      .. versionadded:: 249
+
+To summarize: if the image updates are built and shipped as comprehensive units,
+``IMAGE_ID``+``IMAGE_VERSION`` is the best fit. Otherwise, if updates
+eventually completely replace previously installed contents, as in a typical binary distribution,
+``VERSION_ID`` should be used to identify major releases of the operating system.
+``BUILD_ID`` may be used instead or in addition to ``VERSION_ID`` when
+the original system image version is important.
+
+Presentation information and links
+----------------------------------
+
+.. option:: HOME_URL=, DOCUMENTATION_URL=, SUPPORT_URL=, BUG_REPORT_URL=, PRIVACY_POLICY_URL=
+
+   Links to resources on the Internet related to the operating system.
+   :directive:environment-variables:var:`HOME_URL=` should refer to the homepage of the operating system, or alternatively
+   some homepage of the specific version of the operating system.
+   :directive:environment-variables:var:`DOCUMENTATION_URL=` should refer to the main documentation page for this
+   operating system.  :directive:environment-variables:var:`SUPPORT_URL=` should refer to the main support page for the
+   operating system, if there is any. This is primarily intended for operating systems which vendors
+   provide support for. :directive:environment-variables:var:`BUG_REPORT_URL=` should refer to the main bug reporting page
+   for the operating system, if there is any. This is primarily intended for operating systems that
+   rely on community QA. :directive:environment-variables:var:`PRIVACY_POLICY_URL=` should refer to the main privacy
+   policy page for the operating system, if there is any. These settings are optional, and providing
+   only some of these settings is common. These URLs are intended to be exposed in "About this system"
+   UIs behind links with captions such as "About this Operating System", "Obtain Support", "Report a
+   Bug", or "Privacy Policy". The values should be in `RFC3986 format <https://tools.ietf.org/html/rfc3986>`_, and should be
+   "http:" or "https:" URLs, and possibly "mailto:"
+   or "tel:". Only one URL shall be listed in each setting. If multiple resources
+   need to be referenced, it is recommended to provide an online landing page linking all available
+   resources.
+
+   Examples: "HOME_URL="https://fedoraproject.org/"",
+   "BUG_REPORT_URL="https://bugzilla.redhat.com/"".
+
+.. option:: SUPPORT_END=
+
+   The date at which support for this version of the OS ends. (What exactly "lack of
+   support" means varies between vendors, but generally users should assume that updates, including
+   security fixes, will not be provided.) The value is a date in the ISO 8601 format
+   "YYYY-MM-DD", and specifies the first day on which support *is
+   not* provided.
+
+   For example, "SUPPORT_END=2001-01-01" means that the system was supported
+   until the end of the last day of the previous millennium.
+
+   .. only:: html
+
+      .. versionadded:: 252
+
+.. option:: LOGO=
+
+   A string, specifying the name of an icon as defined by `freedesktop.org Icon Theme
+   Specification <https://standards.freedesktop.org/icon-theme-spec/latest>`_. This can be used by graphical applications to display an operating system's
+   or distributor's logo. This field is optional and may not necessarily be implemented on all
+   systems.
+
+   Examples: "LOGO=fedora-logo", "LOGO=distributor-logo-opensuse"
+
+   .. only:: html
+
+      .. versionadded:: 240
+
+.. option:: ANSI_COLOR=
+
+   A suggested presentation color when showing the OS name on the console. This should
+   be specified as string suitable for inclusion in the ESC [ m ANSI/ECMA-48 escape code for setting
+   graphical rendition. This field is optional.
+
+   Examples: "ANSI_COLOR="0;31"" for red, "ANSI_COLOR="1;34""
+   for light blue, or "ANSI_COLOR="0;38;2;60;110;180"" for Fedora blue.
+
+.. option:: VENDOR_NAME=
+
+   The name of the OS vendor. This is the name of the organization or company which
+   produces the OS. This field is optional.
+
+   This name is intended to be exposed in "About this system" UIs or software update UIs when
+   needed to distinguish the OS vendor from the OS itself. It is intended to be human readable.
+
+   Examples: "VENDOR_NAME="Fedora Project"" for Fedora Linux,
+   "VENDOR_NAME="Canonical"" for Ubuntu.
+
+   .. only:: html
+
+      .. versionadded:: 254
+
+.. option:: VENDOR_URL=
+
+   The homepage of the OS vendor. This field is optional. The
+   :directive:environment-variables:var:`VENDOR_NAME=` field should be set if this one is, although clients must be
+   robust against either field not being set.
+
+   The value should be in `RFC3986 format <https://tools.ietf.org/html/rfc3986>`_, and should be
+   "http:" or "https:" URLs. Only one URL shall be listed in the
+   setting.
+
+   Examples: "VENDOR_URL="https://fedoraproject.org/"",
+   "VENDOR_URL="https://canonical.com/"".
+
+   .. only:: html
+
+      .. versionadded:: 254
+
+Distribution-level defaults and metadata
+----------------------------------------
+
+.. option:: DEFAULT_HOSTNAME=
+
+   A string specifying the hostname if
+   :ref:`hostname(5)` is not
+   present and no other configuration source specifies the hostname. Must be either a single DNS label
+   (a string composed of 7-bit ASCII lower-case characters and no spaces or dots, limited to the
+   format allowed for DNS domain name labels), or a sequence of such labels separated by single dots
+   that forms a valid DNS FQDN. The hostname must be at most 64 characters, which is a Linux
+   limitation (DNS allows longer names).
+
+   See :ref:`org.freedesktop.hostname1(5)`
+   for a description of how
+   :ref:`systemd-hostnamed.service(8)`
+   determines the fallback hostname.
+
+   .. only:: html
+
+      .. versionadded:: 248
+
+.. option:: ARCHITECTURE=
+
+   A string that specifies which CPU architecture the userspace binaries require.
+   The architecture identifiers are the same as for :directive:environment-variables:var:`ConditionArchitecture=`
+   described in :ref:`systemd.unit(5)`.
+   The field is optional and should only be used when just single architecture is supported.
+   It may provide redundant information when used in a GPT partition with a GUID type that already
+   encodes the architecture. If this is not the case, the architecture should be specified in
+   e.g., an extension image, to prevent an incompatible host from loading it.
+
+   .. only:: html
+
+      .. versionadded:: 252
+
+.. option:: SYSEXT_LEVEL=
+
+   A lower-case string (mostly numeric, no spaces or other characters outside of 0–9,
+   a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which
+   extension images are supported. See ``/usr/lib/extension-release.d/extension-release.<IMAGE>``,
+   `initrd <https://docs.kernel.org/admin-guide/initrd.html>`_ and
+   :ref:`systemd-sysext(8)`)
+   for more information.
+
+   Examples: "SYSEXT_LEVEL=2", "SYSEXT_LEVEL=15.14".
+
+   .. only:: html
+
+      .. versionadded:: 248
+
+.. option:: CONFEXT_LEVEL=
+
+   Semantically the same as :directive:environment-variables:var:`SYSEXT_LEVEL=` but for confext images.
+   See ``/etc/extension-release.d/extension-release.<IMAGE>``
+   for more information.
+
+   Examples: "CONFEXT_LEVEL=2", "CONFEXT_LEVEL=15.14".
+
+   .. only:: html
+
+      .. versionadded:: 254
+
+.. option:: SYSEXT_SCOPE=
+
+   Takes a space-separated list of one or more of the strings
+   "system", "initrd" and "portable". This field is
+   only supported in ``extension-release.d/`` files and indicates what environments
+   the system extension is applicable to: i.e. to regular systems, to initrds, or to portable service
+   images. If unspecified, "SYSEXT_SCOPE=system portable" is implied, i.e. any system
+   extension without this field is applicable to regular systems and to portable service environments,
+   but not to initrd environments.
+
+   .. only:: html
+
+      .. versionadded:: 250
+
+.. option:: CONFEXT_SCOPE=
+
+   Semantically the same as :directive:environment-variables:var:`SYSEXT_SCOPE=` but for confext images.
+
+   .. only:: html
+
+      .. versionadded:: 254
+
+.. option:: PORTABLE_PREFIXES=
+
+   Takes a space-separated list of one or more valid prefix match strings for the
+   `Portable Services <https://systemd.io/PORTABLE_SERVICES>`_ logic.
+   This field serves two purposes: it is informational, identifying portable service images as such
+   (and thus allowing them to be distinguished from other OS images, such as bootable system images).
+   It is also used when a portable service image is attached: the specified or implied portable
+   service prefix is checked against the list specified here, to enforce restrictions how images may
+   be attached to a system.
+
+   .. only:: html
+
+      .. versionadded:: 250
+
+Notes
+-----
+
+If you are using this file to determine the OS or a specific version of it, use the
+``ID`` and ``VERSION_ID`` fields, possibly with
+``ID_LIKE`` as fallback for ``ID``. When looking for an OS identification
+string for presentation to the user use the ``PRETTY_NAME`` field.
+
+Note that operating system vendors may choose not to provide version information, for example to
+accommodate for rolling releases. In this case, ``VERSION`` and
+``VERSION_ID`` may be unset. Applications should not rely on these fields to be
+set.
+
+Operating system vendors may extend the file format and introduce new fields. It is highly
+recommended to prefix new fields with an OS specific name in order to avoid name clashes. Applications
+reading this file must ignore unknown fields.
+
+Example: "DEBIAN_BTS="debbugs://bugs.debian.org/"".
+
+Container and sandbox runtime managers may make the host's identification data available to
+applications by providing the host's ``/etc/os-release`` (if available, otherwise
+``/usr/lib/os-release`` as a fallback) as
+``/run/host/os-release``.
+
+Examples
+========
+
+``os-release`` file for Fedora Workstation
+------------------------------------------
+
+.. code-block:: sh
+
+   NAME=Fedora
+   VERSION="32 (Workstation Edition)"
+   ID=fedora
+   VERSION_ID=32
+   PRETTY_NAME="Fedora 32 (Workstation Edition)"
+   ANSI_COLOR="0;38;2;60;110;180"
+   LOGO=fedora-logo-icon
+   CPE_NAME="cpe:/o:fedoraproject:fedora:32"
+   HOME_URL="https://fedoraproject.org/"
+   DOCUMENTATION_URL="https://docs.fedoraproject.org/en-US/fedora/f32/system-administrators-guide/"
+   SUPPORT_URL="https://fedoraproject.org/wiki/Communicating_and_getting_help"
+   BUG_REPORT_URL="https://bugzilla.redhat.com/"
+   REDHAT_BUGZILLA_PRODUCT="Fedora"
+   REDHAT_BUGZILLA_PRODUCT_VERSION=32
+   REDHAT_SUPPORT_PRODUCT="Fedora"
+   REDHAT_SUPPORT_PRODUCT_VERSION=32
+   PRIVACY_POLICY_URL="https://fedoraproject.org/wiki/Legal:PrivacyPolicy"
+   VARIANT="Workstation Edition"
+   VARIANT_ID=workstation
+
+``extension-release`` file for an extension for Fedora Workstation 32
+---------------------------------------------------------------------
+
+.. code-block:: sh
+
+   ID=fedora
+   VERSION_ID=32
+
+Reading ``os-release`` in :man-pages:`sh(1)`
+--------------------------------------------
+
+.. literalinclude:: /code-examples/sh/check-os-release.sh
+                    :language: shell
+
+Reading ``os-release`` in :die-net:`python(1)` (versions >= 3.10)
+-----------------------------------------------------------------
+
+.. literalinclude:: /code-examples/py/check-os-release-simple.py
+                    :language: python
+
+See docs for `platform.freedesktop_os_release <https://docs.python.org/3/library/platform.html#platform.freedesktop_os_release>`_ for more details.
+
+Reading ``os-release`` in :die-net:`python(1)` (any version)
+------------------------------------------------------------
+
+.. literalinclude:: /code-examples/py/check-os-release.py
+                    :language: python
+
+Note that the above version that uses the built-in implementation is preferred
+in most cases, and the open-coded version here is provided for reference.
+
+See Also
+========
+
+:ref:`systemd(1)`, :die-net:`lsb_release(1)`, :ref:`hostname(5)`, :ref:`machine-id(5)`, :ref:`machine-info(5)`

doc-migration/source/docs/repart.d.rst

@@ -0,0 +1,862 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+:title: repart.d
+
+:manvolnum: 5
+
+.. _repart.d(5):
+
+===========
+repart.d(5)
+===========
+
+.. only:: html
+
+   repart.d — Partition Definition Files for Automatic Boot-Time Repartitioning
+   ############################################################################
+
+   Synopsis
+   ########
+
+``/etc/repart.d/\*.conf``
+``/run/repart.d/\*.conf``
+``/usr/local/lib/repart.d/\*.conf``
+``/usr/lib/repart.d/\*.conf``
+
+Description
+===========
+
+``repart.d/\*.conf`` files describe basic properties of partitions of block
+devices of the local system. They may be used to declare types, names and sizes of partitions that shall
+exist. The
+:ref:`systemd-repart(8)`
+service reads these files and attempts to add new partitions currently missing and enlarge existing
+partitions according to these definitions. Operation is generally incremental, i.e. when applied, what
+exists already is left intact, and partitions are never shrunk, moved or deleted.
+
+These definition files are useful for implementing operating system images that are prepared and
+delivered with minimally sized images (for example lacking any state or swap partitions), and which on
+first boot automatically take possession of any remaining disk space following a few basic rules.
+
+Currently, support for partition definition files is only implemented for GPT partition
+tables.
+
+Partition files are generally matched against any partitions already existing on disk in a simple
+algorithm: the partition files are sorted by their filename (ignoring the directory prefix), and then
+compared in order against existing partitions matching the same partition type UUID. Specifically, the
+first existing partition with a specific partition type UUID is assigned the first definition file with
+the same partition type UUID, and the second existing partition with a specific type UUID the second
+partition file with the same type UUID, and so on. Any left-over partition files that have no matching
+existing partition are assumed to define new partition that shall be created. Such partitions are
+appended to the end of the partition table, in the order defined by their names utilizing the first
+partition slot greater than the highest slot number currently in use. Any existing partitions that have
+no matching partition file are left as they are.
+
+Note that these definitions may only be used to create and initialize new partitions or to grow
+existing ones. In the latter case it will not grow the contained files systems however; separate
+mechanisms, such as
+:ref:`systemd-growfs(8)` may be
+used to grow the file systems inside of these partitions. Partitions may also be marked for automatic
+growing via the ``GrowFileSystem=`` setting, in which case the file system is grown on
+first mount by tools that respect this flag. See below for details.
+
+[Partition] Section Options
+===========================
+
+``Type=``
+---------
+
+The GPT partition type UUID to match. This may be a GPT partition type UUID such as
+``4f68bce3-e8cd-4db1-96e7-fbcaf984b709``, or an identifier.
+Architecture specific partition types can use one of these architecture identifiers:
+``alpha``, ``arc``, ``arm`` (32-bit),
+``arm64`` (64-bit, aka aarch64), ``ia64``,
+``loongarch64``, ``mips-le``, ``mips64-le``,
+``parisc``, ``ppc``, ``ppc64``,
+``ppc64-le``, ``riscv32``, ``riscv64``,
+``s390``, ``s390x``, ``tilegx``,
+``x86`` (32-bit, aka i386) and ``x86-64`` (64-bit, aka amd64).
+
+The supported identifiers are:
+
+.. list-table:: GPT partition type identifiers
+   :header-rows: 1
+   * - Identifier
+     - Explanation
+   * - ``esp``
+     - EFI System Partition
+   * - ``xbootldr``
+     - Extended Boot Loader Partition
+   * - ``swap``
+     - Swap partition
+   * - ``home``
+     - Home (``/home/``) partition
+   * - ``srv``
+     - Server data (``/srv/``) partition
+   * - ``var``
+     - Variable data (``/var/``) partition
+   * - ``tmp``
+     - Temporary data (``/var/tmp/``) partition
+   * - ``linux-generic``
+     - Generic Linux file system partition
+   * - ``root``
+     - Root file system partition type appropriate for the local architecture (an alias for an architecture root file system partition type listed below, e.g. ``root-x86-64``)
+   * - ``root-verity``
+     - Verity data for the root file system partition for the local architecture
+   * - ``root-verity-sig``
+     - Verity signature data for the root file system partition for the local architecture
+   * - ``root-secondary``
+     - Root file system partition of the secondary architecture of the local architecture (usually the matching 32-bit architecture for the local 64-bit architecture)
+   * - ``root-secondary-verity``
+     - Verity data for the root file system partition of the secondary architecture
+   * - ``root-secondary-verity-sig``
+     - Verity signature data for the root file system partition of the secondary architecture
+   * - ``root-{arch}``
+     - Root file system partition of the given architecture (such as ``root-x86-64`` or ``root-riscv64``)
+   * - ``root-{arch}-verity``
+     - Verity data for the root file system partition of the given architecture
+   * - ``root-{arch}-verity-sig``
+     - Verity signature data for the root file system partition of the given architecture
+   * - ``usr``
+     - ``/usr/`` file system partition type appropriate for the local architecture (an alias for an architecture ``/usr/`` file system partition type listed below, e.g. ``usr-x86-64``)
+   * - ``usr-verity``
+     - Verity data for the ``/usr/`` file system partition for the local architecture
+   * - ``usr-verity-sig``
+     - Verity signature data for the ``/usr/`` file system partition for the local architecture
+   * - ``usr-secondary``
+     - ``/usr/`` file system partition of the secondary architecture of the local architecture (usually the matching 32-bit architecture for the local 64-bit architecture)
+   * - ``usr-secondary-verity``
+     - Verity data for the ``/usr/`` file system partition of the secondary architecture
+   * - ``usr-secondary-verity-sig``
+     - Verity signature data for the ``/usr/`` file system partition of the secondary architecture
+   * - ``usr-{arch}``
+     - ``/usr/`` file system partition of the given architecture
+   * - ``usr-{arch}-verity``
+     - Verity data for the ``/usr/`` file system partition of the given architecture
+   * - ``usr-{arch}-verity-sig``
+     - Verity signature data for the ``/usr/`` file system partition of the given architecture
+This setting defaults to ``linux-generic``.
+
+Most of the partition type UUIDs listed above are defined in the `Discoverable Partitions
+Specification <https://uapi-group.org/specifications/specs/discoverable_partitions_specification>`_.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+``Label=``
+----------
+
+The textual label to assign to the partition if none is assigned yet. Note that this
+setting is not used for matching. It is also not used when a label is already set for an existing
+partition. It is thus only used when a partition is newly created or when an existing one had a no
+label set (that is: an empty label). If not specified a label derived from the partition type is
+automatically used. Simple specifier expansion is supported, see below.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+``UUID=``
+---------
+
+The UUID to assign to the partition if none is assigned yet. Note that this
+setting is not used for matching. It is also not used when a UUID is already set for an existing
+partition. It is thus only used when a partition is newly created or when an existing one had a
+all-zero UUID set. If set to "null", the UUID is set to all zeroes. If not specified
+a UUID derived from the partition type is automatically used.
+
+.. only:: html
+
+   .. versionadded:: 246
+
+``Priority=``
+-------------
+
+A numeric priority to assign to this partition, in the range -2147483648…2147483647,
+with smaller values indicating higher priority, and higher values indicating smaller priority. This
+priority is used in case the configured size constraints on the defined partitions do not permit
+fitting all partitions onto the available disk space. If the partitions do not fit, the highest
+numeric partition priority of all defined partitions is determined, and all defined partitions with
+this priority are removed from the list of new partitions to create (which may be multiple, if the
+same priority is used for multiple partitions). The fitting algorithm is then tried again. If the
+partitions still do not fit, the now highest numeric partition priority is determined, and the
+matching partitions removed too, and so on. Partitions of a priority of 0 or lower are never
+removed. If all partitions with a priority above 0 are removed and the partitions still do not fit on
+the device the operation fails. Note that this priority has no effect on ordering partitions, for
+that use the alphabetical order of the filenames of the partition definition files. Defaults to
+0.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+``Weight=``
+-----------
+
+A numeric weight to assign to this partition in the range 0…1000000. Available disk
+space is assigned the defined partitions according to their relative weights (subject to the size
+constraints configured with ``SizeMinBytes=``, ``SizeMaxBytes=``), so
+that a partition with weight 2000 gets double the space as one with weight 1000, and a partition with
+weight 333 a third of that. Defaults to 1000.
+
+The ``Weight=`` setting is used to distribute available disk space in an
+"elastic" fashion, based on the disk size and existing partitions. If a partition shall have a fixed
+size use both ``SizeMinBytes=`` and ``SizeMaxBytes=`` with the same
+value in order to fixate the size to one value, in which case the weight has no
+effect.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+``PaddingWeight=``
+------------------
+
+Similar to ``Weight=``, but sets a weight for the free space after the
+partition (the "padding"). When distributing available space the weights of all partitions and all
+defined padding is summed, and then each partition and padding gets the fraction defined by its
+weight. Defaults to 0, i.e. by default no padding is applied.
+
+Padding is useful if empty space shall be left for later additions or a safety margin at the
+end of the device or between partitions.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+``SizeMinBytes=, SizeMaxBytes=``
+--------------------------------
+
+Specifies minimum and maximum size constraints in bytes. Takes the usual K, M, G, T,
+…  suffixes (to the base of 1024). If ``SizeMinBytes=`` is specified the partition is
+created at or grown to at least the specified size. If ``SizeMaxBytes=`` is specified
+the partition is created at or grown to at most the specified size. The precise size is determined
+through the weight value configured with ``Weight=``, see above. When
+``SizeMinBytes=`` is set equal to ``SizeMaxBytes=`` the configured
+weight has no effect as the partition is explicitly sized to the specified fixed value. Note that
+partitions are never created smaller than 4096 bytes, and since partitions are never shrunk the
+previous size of the partition (in case the partition already exists) is also enforced as lower bound
+for the new size. The values should be specified as multiples of 4096 bytes, and are rounded upwards
+(in case of ``SizeMinBytes=``) or downwards (in case of
+``SizeMaxBytes=``) otherwise. If the backing device does not provide enough space to
+fulfill the constraints placing the partition will fail. For partitions that shall be created,
+depending on the setting of ``Priority=`` (see above) the partition might be dropped
+and the placing algorithm restarted. By default a minimum size constraint of 10M and no maximum size
+constraint is set.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+``PaddingMinBytes=, PaddingMaxBytes=``
+--------------------------------------
+
+Specifies minimum and maximum size constraints in bytes for the free space after the
+partition (the "padding"). Semantics are similar to ``SizeMinBytes=`` and
+``SizeMaxBytes=``, except that unlike partition sizes free space can be shrunk and can
+be as small as zero. By default no size constraints on padding are set, so that only
+``PaddingWeight=`` determines the size of the padding applied.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+``CopyBlocks=``
+---------------
+
+Takes a path to a regular file, block device node, char device node or directory, or
+the special value "auto". If specified and the partition is newly created, the data
+from the specified path is written to the newly created partition, on the block level. If a directory
+is specified, the backing block device of the file system the directory is on is determined, and the
+data read directly from that. This option is useful to efficiently replicate existing file systems
+onto new partitions on the block level — for example to build a simple OS installer or an OS image
+builder. Specify ``/dev/urandom`` as value to initialize a partition with random
+data.
+
+If the special value "auto" is specified, the source to copy from is
+automatically picked up from the running system (or the image specified with
+``--image=`` — if used). A partition that matches both the configured partition type (as
+declared with ``Type=`` described above), and the currently mounted directory
+appropriate for that partition type is determined. For example, if the partition type is set to
+"root" the partition backing the root directory (``/``) is used as
+source to copy from — if its partition type is set to "root" as well. If the
+declared type is "usr" the partition backing ``/usr/`` is used as
+source to copy blocks from — if its partition type is set to "usr" too. The logic is
+capable of automatically tracking down the backing partitions for encrypted and Verity-enabled
+volumes. "CopyBlocks=auto" is useful for implementing "self-replicating" systems,
+i.e. systems that are their own installer.
+
+The file specified here must have a size that is a multiple of the basic block size 512 and not
+be empty. If this option is used, the size allocation algorithm is slightly altered: the partition is
+created at least as big as required to fit the data in, i.e. the data size is an additional minimum
+size value taken into consideration for the allocation algorithm, similar to and in addition to the
+``SizeMin=`` value configured above.
+
+This option has no effect if the partition it is declared for already exists, i.e. existing
+data is never overwritten. Note that the data is copied in before the partition table is updated,
+i.e. before the partition actually is persistently created. This provides robustness: it is
+guaranteed that the partition either doesn't exist or exists fully populated; it is not possible that
+the partition exists but is not or only partially populated.
+
+This option cannot be combined with ``Format=`` or
+``CopyFiles=``.
+
+.. only:: html
+
+   .. versionadded:: 246
+
+``Format=``
+-----------
+
+Takes a file system name, such as "ext4", "btrfs",
+"xfs", "vfat", "erofs",
+"squashfs" or the special value "swap". If specified and the partition
+is newly created it is formatted with the specified file system (or as swap device). The file system
+UUID and label are automatically derived from the partition UUID and label. If this option is used,
+the size allocation algorithm is slightly altered: the partition is created at least as big as
+required for the minimal file system of the specified type (or 4KiB if the minimal size is not
+known).
+
+This option has no effect if the partition already exists.
+
+Similarly to the behaviour of ``CopyBlocks=``, the file system is formatted
+before the partition is created, ensuring that the partition only ever exists with a fully
+initialized file system.
+
+This option cannot be combined with ``CopyBlocks=``.
+
+.. only:: html
+
+   .. versionadded:: 247
+
+``CopyFiles=``
+--------------
+
+Takes a pair of colon separated absolute file system paths. The first path refers to
+a source file or directory on the host, the second path refers to a target in the file system of the
+newly created partition and formatted file system. This setting may be used to copy files or
+directories from the host into the file system that is created due to the ``Format=``
+option. If ``CopyFiles=`` is used without ``Format=`` specified
+explicitly, "Format=" with a suitable default is implied (currently
+"vfat" for "ESP" and "XBOOTLDR" partitions, and
+"ext4" otherwise, but this may change in the future). This option may be used
+multiple times to copy multiple files or directories from host into the newly formatted file system.
+The colon and second path may be omitted in which case the source path is also used as the target
+path (relative to the root of the newly created file system). If the source path refers to a
+directory it is copied recursively.
+
+This option has no effect if the partition already exists: it cannot be used to copy additional
+files into an existing partition, it may only be used to populate a file system created anew.
+
+The copy operation is executed before the file system is registered in the partition table,
+thus ensuring that a file system populated this way only ever exists fully initialized.
+
+Note that ``CopyFiles=`` will skip copying files that aren't supported by the
+target filesystem (e.g symlinks, fifos, sockets and devices on vfat). When an unsupported file type
+is encountered, ``systemd-repart`` will skip copying this file and write a log message
+about it.
+
+Note that ``systemd-repart`` does not change the UIDs/GIDs of any copied files
+and directories. When running ``systemd-repart`` as an unprivileged user to build an
+image of files and directories owned by the same user, you can run ``systemd-repart``
+in a user namespace with the current user mapped to the root user to make sure the files and
+directories in the image are owned by the root user.
+
+Note that when populating XFS filesystems with ``systemd-repart`` and loop
+devices are not available, populating XFS filesystems with files containing spaces, tabs or newlines
+might fail on old versions of
+:man-pages:`mkfs.xfs(8)`
+due to limitations of its protofile format.
+
+Note that when populating XFS filesystems with ``systemd-repart`` and loop
+devices are not available, extended attributes will not be copied into generated XFS filesystems
+due to limitations :man-pages:`mkfs.xfs(8)`'s
+protofile format.
+
+This option cannot be combined with ``CopyBlocks=``.
+
+When
+:ref:`systemd-repart(8)` is
+invoked with the ``--copy-source=`` command line switch the file paths are taken
+relative to the specified directory. If ``--copy-source=`` is not used, but the
+``--image=`` or ``--root=`` switches are used, the source paths are taken
+relative to the specified root directory or disk image root.
+
+.. only:: html
+
+   .. versionadded:: 247
+
+``ExcludeFiles=, ExcludeFilesTarget=``
+--------------------------------------
+
+Takes an absolute file system path referring to a source file or directory on the
+host. This setting may be used to exclude files or directories from the host from being copied into
+the file system when ``CopyFiles=`` is used. This option may be used multiple times to
+exclude multiple files or directories from host from being copied into the newly formatted file
+system.
+
+If the path is a directory and ends with "/", only the directory's
+contents are excluded but not the directory itself. If the path is a directory and does not end with
+"/", both the directory and its contents are excluded.
+
+``ExcludeFilesTarget=`` is like ``ExcludeFiles=`` except that
+instead of excluding the path on the host from being copied into the partition, we exclude any files
+and directories from being copied into the given path in the partition.
+
+When
+:ref:`systemd-repart(8)`
+is invoked with the ``--image=`` or ``--root=`` command line switches the
+paths specified are taken relative to the specified root directory or disk image root.
+
+.. only:: html
+
+   .. versionadded:: 254
+
+``MakeDirectories=``
+--------------------
+
+Takes one or more absolute paths, separated by whitespace, each declaring a directory
+to create within the new file system. Behaviour is similar to ``CopyFiles=``, but
+instead of copying in a set of files this just creates the specified directories with the default
+mode of 0755 owned by the root user and group, plus all their parent directories (with the same
+ownership and access mode). To configure directories with different ownership or access mode, use
+``CopyFiles=`` and specify a source tree to copy containing appropriately
+owned/configured directories. This option may be used more than once to create multiple
+directories. When ``CopyFiles=`` and ``MakeDirectories=`` are used
+together the former is applied first. If a directory listed already exists no operation is executed
+(in particular, the ownership/access mode of the directories is left as is).
+
+The primary use case for this option is to create a minimal set of directories that may be
+mounted over by other partitions contained in the same disk image. For example, a disk image where
+the root file system is formatted at first boot might want to automatically pre-create
+``/usr/`` in it this way, so that the "usr" partition may
+over-mount it.
+
+Consider using
+:ref:`systemd-tmpfiles(8)`
+with its ``--image=`` option to pre-create other, more complex directory hierarchies (as
+well as other inodes) with fine-grained control of ownership, access modes and other file
+attributes.
+
+.. only:: html
+
+   .. versionadded:: 249
+
+``Subvolumes=``
+---------------
+
+Takes one or more absolute paths, separated by whitespace, each declaring a directory
+that should be a subvolume within the new file system. This option may be used more than once to
+specify multiple directories. Note that this setting does not create the directories themselves, that
+can be configured with ``MakeDirectories=`` and ``CopyFiles=``.
+
+Note that this option only takes effect if the target filesystem supports subvolumes, such as
+"btrfs".
+
+Note that due to limitations of "mkfs.btrfs", this option is only supported
+when running with ``--offline=no``.
+
+.. only:: html
+
+   .. versionadded:: 255
+
+``DefaultSubvolume=``
+---------------------
+
+Takes an absolute path specifying the default subvolume within the new filesystem.
+Note that this setting does not create the subvolume itself, that can be configured with
+``Subvolumes=``.
+
+Note that this option only takes effect if the target filesystem supports subvolumes, such as
+"btrfs".
+
+Note that due to limitations of "mkfs.btrfs", this option is only supported
+when running with ``--offline=no``.
+
+.. only:: html
+
+   .. versionadded:: 256
+
+``Encrypt=``
+------------
+
+Takes one of "off", "key-file",
+"tpm2" and "key-file+tpm2" (alternatively, also accepts a boolean
+value, which is mapped to "off" when false, and "key-file" when
+true). Defaults to "off". If not "off" the partition will be
+formatted with a LUKS2 superblock, before the blocks configured with ``CopyBlocks=``
+are copied in or the file system configured with ``Format=`` is created.
+
+The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If
+"key-file" or "key-file+tpm2" is used, a key is added to the LUKS2
+superblock, configurable with the ``--key-file=`` option to
+``systemd-repart``. If "tpm2" or "key-file+tpm2" is
+used, a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured
+with the ``--tpm2-device=`` and ``--tpm2-pcrs=`` options to
+``systemd-repart``.
+
+When used this slightly alters the size allocation logic as the implicit, minimal size limits
+of ``Format=`` and ``CopyBlocks=`` are increased by the space necessary
+for the LUKS2 superblock (see above).
+
+This option has no effect if the partition already exists.
+
+.. only:: html
+
+   .. versionadded:: 247
+
+``Verity=``
+-----------
+
+Takes one of "off", "data",
+"hash" or "signature". Defaults to "off". If set
+to "off" or "data", the partition is populated with content as
+specified by ``CopyBlocks=`` or ``CopyFiles=``. If set to
+"hash", the partition will be populated with verity hashes from the matching verity
+data partition. If set to "signature", the partition will be populated with a JSON
+object containing a signature of the verity root hash of the matching verity hash partition.
+
+A matching verity partition is a partition with the same verity match key (as configured with
+``VerityMatchKey=``).
+
+If not explicitly configured, the data partition's UUID will be set to the first 128
+bits of the verity root hash. Similarly, if not configured, the hash partition's UUID will be set to
+the final 128 bits of the verity root hash. The verity root hash itself will be included in the
+output of ``systemd-repart``.
+
+This option has no effect if the partition already exists.
+
+Usage of this option in combination with ``Encrypt=`` is not supported.
+
+For each unique ``VerityMatchKey=`` value, a single verity data partition
+("Verity=data") and a single verity hash partition ("Verity=hash")
+must be defined.
+
+.. only:: html
+
+   .. versionadded:: 252
+
+``VerityMatchKey=``
+-------------------
+
+Takes a short, user-chosen identifier string. This setting is used to find sibling
+verity partitions for the current verity partition. See the description for
+``Verity=``.
+
+.. only:: html
+
+   .. versionadded:: 252
+
+``VerityDataBlockSizeBytes=``
+-----------------------------
+
+Configures the data block size of the generated verity hash partition. Must be between 512 and
+4096 bytes and must be a power of 2. Defaults to the sector size if configured explicitly, or the underlying
+block device sector size, or 4K if systemd-repart is not operating on a block device.
+
+.. only:: html
+
+   .. versionadded:: 255
+
+``VerityHashBlockSizeBytes=``
+-----------------------------
+
+Configures the hash block size of the generated verity hash partition. Must be between 512 and
+4096 bytes and must be a power of 2. Defaults to the sector size if configured explicitly, or the underlying
+block device sector size, or 4K if systemd-repart is not operating on a block device.
+
+.. only:: html
+
+   .. versionadded:: 255
+
+``FactoryReset=``
+-----------------
+
+Takes a boolean argument. If specified the partition is marked for removal during a
+factory reset operation. This functionality is useful to implement schemes where images can be reset
+into their original state by removing partitions and creating them anew. Defaults to off.
+
+.. only:: html
+
+   .. versionadded:: 245
+
+``Flags=``
+----------
+
+Configures the 64-bit GPT partition flags field to set for the partition when creating
+it. This option has no effect if the partition already exists. If not specified the flags values is
+set to all zeroes, except for the three bits that can also be configured via
+``NoAuto=``, ``ReadOnly=`` and ``GrowFileSystem=``; see
+below for details on the defaults for these three flags. Specify the flags value in hexadecimal (by
+prefixing it with "0x"), binary (prefix "0b") or decimal (no
+prefix).
+
+.. only:: html
+
+   .. versionadded:: 249
+
+``NoAuto=, ReadOnly=, GrowFileSystem=``
+---------------------------------------
+
+Configures the No-Auto, Read-Only and Grow-File-System partition flags (bit 63, 60
+and 59) of the partition table entry, as defined by the `Discoverable Partitions Specification <https://uapi-group.org/specifications/specs/discoverable_partitions_specification>`_. Only
+available for partition types supported by the specification. This option is a friendly way to set
+bits 63, 60 and 59 of the partition flags value without setting any of the other bits, and may be set
+via ``Flags=`` too, see above.
+
+If ``Flags=`` is used in conjunction with one or more of
+``NoAuto=``/``ReadOnly=``/``GrowFileSystem=`` the latter
+control the value of the relevant flags, i.e. the high-level settings
+``NoAuto=``/``ReadOnly=``/``GrowFileSystem=`` override
+the relevant bits of the low-level setting ``Flags=``.
+
+Note that the three flags affect only automatic partition mounting, as implemented by
+:ref:`systemd-gpt-auto-generator(8)`
+or the ``--image=`` option of various commands (such as
+:ref:`systemd-nspawn(1)`). It
+has no effect on explicit mounts, such as those done via :man-pages:`mount(8)` or
+:man-pages:`fstab(5)`.
+
+If both bit 50 and 59 are set for a partition (i.e. the partition is marked both read-only and
+marked for file system growing) the latter is typically without effect: the read-only flag takes
+precedence in most tools reading these flags, and since growing the file system involves writing to
+the partition it is consequently ignored.
+
+``NoAuto=`` defaults to off. ``ReadOnly=`` defaults to on for
+Verity partition types, and off for all others. ``GrowFileSystem=`` defaults to on for
+all partition types that support it, except if the partition is marked read-only (and thus
+effectively, defaults to off for Verity partitions).
+
+.. only:: html
+
+   .. versionadded:: 249
+
+``SplitName=``
+--------------
+
+Configures the suffix to append to split artifacts when the ``--split``
+option of
+:ref:`systemd-repart(8)` is
+used. Simple specifier expansion is supported, see below. Defaults to "%t". To
+disable split artifact generation for a partition, set ``SplitName=`` to
+"-".
+
+.. only:: html
+
+   .. versionadded:: 252
+
+``Minimize=``
+-------------
+
+Takes one of "off", "best", and
+"guess" (alternatively, also accepts a boolean value, which is mapped to
+"off" when false, and "best" when true). Defaults to
+"off". If set to "best", the partition will have the minimal size
+required to store the sources configured with ``CopyFiles=``. "best"
+is currently only supported for read-only filesystems. If set to "guess", the
+partition is created at least as big as required to store the sources configured with
+``CopyFiles=``. Note that unless the filesystem is a read-only filesystem,
+``systemd-repart`` will have to populate the filesystem twice to guess the minimal
+required size, so enabling this option might slow down repart when populating large partitions.
+
+.. only:: html
+
+   .. versionadded:: 253
+
+``MountPoint=``
+---------------
+
+Specifies where and how the partition should be mounted. Takes at least one and at
+most two fields separated with a colon (":"). The first field specifies where the
+partition should be mounted. The second field specifies extra mount options to append to the default
+mount options. These fields correspond to the second and fourth column of the
+:man-pages:`fstab(5)`
+format. This setting may be specified multiple times to mount the partition multiple times. This can
+be used to add mounts for different btrfs subvolumes located on the same btrfs partition.
+
+Note that this setting is only taken into account when ``--generate-fstab=`` is
+specified on the ``systemd-repart`` command line.
+
+.. only:: html
+
+   .. versionadded:: 256
+
+``EncryptedVolume=``
+--------------------
+
+Specify how the encrypted partition should be set up. Takes at least one and at most
+three fields separated with a colon (":"). The first field specifies the encrypted
+volume name under ``/dev/mapper/``. If not specified, "luks-UUID"
+will be used where "UUID" is the LUKS UUID. The second field specifies the keyfile
+to use following the same format as specified in crypttab. The third field specifies a
+comma-delimited list of crypttab options. These fields correspond to the first, third and fourth
+column of the
+:ref:`crypttab(5)` format.
+
+Note that this setting is only taken into account when ``--generate-crypttab=``
+is specified on the ``systemd-repart`` command line.
+
+.. only:: html
+
+   .. versionadded:: 256
+
+Specifiers
+==========
+
+Specifiers may be used in the ``Label=``, ``CopyBlocks=``,
+``CopyFiles=``, ``MakeDirectories=``, ``SplitName=``
+settings. The following expansions are understood:
+
+.. list-table:: Specifiers available
+   :header-rows: 1
+
+   * - Specifier
+     - Meaning
+     - Details
+
+Additionally, for the ``SplitName=`` setting, the following specifiers are also
+understood:
+
+.. list-table:: Specifiers available
+   :header-rows: 1
+
+   * - Specifier
+     - Meaning
+     - Details
+   * - "%T"
+     - Partition Type UUID
+     - The partition type UUID, as configured with ``Type=``
+   * - "%t"
+     - Partition Type Identifier
+     - The partition type identifier corresponding to the partition type UUID
+   * - "%U"
+     - Partition UUID
+     - The partition UUID, as configured with ``UUID=``
+   * - "%n"
+     - Partition Number
+     - The partition number assigned to the partition
+
+Environment
+===========
+
+Extra filesystem formatting options can be provided using filesystem-specific environment variables:
+``$SYSTEMD_REPART_MKFS_OPTIONS_BTRFS``, ``$SYSTEMD_REPART_MKFS_OPTIONS_XFS``,
+``$SYSTEMD_REPART_MKFS_OPTIONS_VFAT``, ``$SYSTEMD_REPART_MKFS_OPTIONS_EROFS``,
+and ``$SYSTEMD_REPART_MKFS_OPTIONS_SQUASHFS``. Each variable accepts valid
+``mkfs.<filesystem>`` command-line arguments.
+The content of those variables is passed as-is to the command, without any verification.
+
+Examples
+========
+
+Grow the root partition to the full disk size at first boot
+-----------------------------------------------------------
+
+With the following file the root partition is automatically grown to the full disk if possible
+during boot.
+
+.. code-block:: sh
+
+   # /usr/lib/repart.d/50-root.conf
+   [Partition]
+   Type=root
+
+Create a swap and home partition automatically on boot, if missing
+------------------------------------------------------------------
+
+The home partition gets all available disk space while the swap partition gets 1G at most and 64M
+at least. We set a priority > 0 on the swap partition to ensure the swap partition is not used if not
+enough space is available. For every three bytes assigned to the home partition the swap partition gets
+assigned one.
+
+.. code-block:: sh
+
+   # /usr/lib/repart.d/60-home.conf
+   [Partition]
+   Type=home
+
+.. code-block:: sh
+
+   # /usr/lib/repart.d/70-swap.conf
+   [Partition]
+   Type=swap
+   SizeMinBytes=64M
+   SizeMaxBytes=1G
+   Priority=1
+   Weight=333
+
+Create B partitions in an A/B Verity setup, if missing
+------------------------------------------------------
+
+Let's say the vendor intends to update OS images in an A/B setup, i.e. with two root partitions
+(and two matching Verity partitions) that shall be used alternatingly during upgrades. To minimize
+image sizes the original image is shipped only with one root and one Verity partition (the "A" set),
+and the second root and Verity partitions (the "B" set) shall be created on first boot on the free
+space on the medium.
+
+.. code-block:: sh
+
+   # /usr/lib/repart.d/50-root.conf
+   [Partition]
+   Type=root
+   SizeMinBytes=512M
+   SizeMaxBytes=512M
+
+.. code-block:: sh
+
+   # /usr/lib/repart.d/60-root-verity.conf
+   [Partition]
+   Type=root-verity
+   SizeMinBytes=64M
+   SizeMaxBytes=64M
+
+The definitions above cover the "A" set of root partition (of a fixed 512M size) and Verity
+partition for the root partition (of a fixed 64M size). Let's use symlinks to create the "B" set of
+partitions, since after all they shall have the same properties and sizes as the "A" set.
+
+.. code-block:: sh
+
+   # ln -s 50-root.conf /usr/lib/repart.d/70-root-b.conf
+   # ln -s 60-root-verity.conf /usr/lib/repart.d/80-root-verity-b.conf
+
+Create a data partition and corresponding verity partitions from a OS tree
+--------------------------------------------------------------------------
+
+Assuming we have an OS tree at ``/var/tmp/os-tree`` that we want
+to package in a root partition together with matching verity partitions, we can do so as follows:
+
+.. code-block:: sh
+
+   # 50-root.conf
+   [Partition]
+   Type=root
+   CopyFiles=/var/tmp/os-tree
+   Verity=data
+   VerityMatchKey=root
+   Minimize=guess
+
+.. code-block:: sh
+
+   # 60-root-verity.conf
+   [Partition]
+   Type=root-verity
+   Verity=hash
+   VerityMatchKey=root
+   # Explicitly set the hash and data block size to 4K
+   VerityDataBlockSizeBytes=4096
+   VerityHashBlockSizeBytes=4096
+   Minimize=best
+
+.. code-block:: sh
+
+   # 70-root-verity-sig.conf
+   [Partition]
+   Type=root-verity-sig
+   Verity=signature
+   VerityMatchKey=root
+
+See Also
+========
+
+:ref:`systemd(1)`, :ref:`systemd-repart(8)`, :man-pages:`sfdisk(8)`, :ref:`systemd-cryptenroll(1)`

doc-migration/source/docs/runlevel.rst

@@ -0,0 +1,113 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+:title: runlevel
+
+:manvolnum: 8
+
+.. _runlevel(8):
+
+===========
+runlevel(8)
+===========
+
+.. only:: html
+
+   runlevel — Print previous and current SysV runlevel
+   ###################################################
+
+   Synopsis
+   ########
+
+``runlevel`` [options...]
+
+Overview
+========
+
+"Runlevels" are an obsolete way to start and stop groups of
+services used in SysV init. systemd provides a compatibility layer
+that maps runlevels to targets, and associated binaries like
+``runlevel``. Nevertheless, only one runlevel can
+be "active" at a given time, while systemd can activate multiple
+targets concurrently, so the mapping to runlevels is confusing
+and only approximate. Runlevels should not be used in new code,
+and are mostly useful as a shorthand way to refer the matching
+systemd targets in kernel boot parameters.
+
+.. list-table:: Mapping between runlevels and systemd targets
+   :header-rows: 1
+
+   * - Runlevel
+     - Target
+   * - 0
+     - ``poweroff.target``
+   * - 1
+     - ``rescue.target``
+   * - 2, 3, 4
+     - ``multi-user.target``
+   * - 5
+     - ``graphical.target``
+   * - 6
+     - ``reboot.target``
+
+Description
+===========
+
+``runlevel`` prints the previous and current
+SysV runlevel if they are known.
+
+The two runlevel characters are separated by a single space
+character. If a runlevel cannot be determined, N is printed
+instead. If neither can be determined, the word "unknown" is
+printed.
+
+Unless overridden in the environment, this will check the
+utmp database for recent runlevel changes.
+
+Options
+=======
+
+The following option is understood:
+
+``--help``
+----------
+
+Exit status
+===========
+
+If one or both runlevels could be determined, 0 is returned,
+a non-zero failure code otherwise.
+
+Environment
+===========
+
+``$RUNLEVEL``
+-------------
+
+If :directive:environment-variables:var:`$RUNLEVEL` is set,
+``runlevel`` will print this value as current
+runlevel and ignore utmp.
+
+``$PREVLEVEL``
+--------------
+
+If :directive:environment-variables:var:`$PREVLEVEL` is set,
+``runlevel`` will print this value as previous
+runlevel and ignore utmp.
+
+Files
+=====
+
+``/run/utmp``
+-------------
+
+The utmp database ``runlevel`` reads the previous and current runlevel
+from.
+
+.. only:: html
+
+   .. versionadded:: 237
+
+See Also
+========
+
+:ref:`systemd(1)`, :ref:`systemd.target(5)`, :ref:`systemctl(1)`

doc-migration/source/docs/systemD-directives.rst

@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:title: systemd.directives
+
+:manvolnum: 7
+
+
+.. _systemD-directives(7):
+
+=========
+systemd.directives(7)
+=========
+
+Index of configuration directives
+
+
+.. list_directive_roles::

doc-migration/source/includes/common-variables.rst

@@ -0,0 +1,266 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:orphan:
+
+Environment
+###########
+
+.. inclusion-marker-do-not-remove log-level
+
+``$SYSTEMD_LOG_LEVEL``
+----------------------
+.. inclusion-marker-do-not-remove log-level-body
+
+   The maximum log level of emitted messages (messages with a higher
+   log level, i.e. less important ones, will be suppressed). Takes a comma-separated list of values. A
+   value may be either one of (in order of decreasing importance) ``emerg``,
+   ``alert``, ``crit``, ``err``,
+   ``warning``, ``notice``, ``info``,
+   ``debug``, or an integer in the range 0…7. See
+   `syslog(3) <https://man7.org/linux/man-pages/man3/syslog.3.html>`_
+   for more information. Each value may optionally be prefixed with one of ``console``,
+   ``syslog``, ``kmsg`` or ``journal`` followed by a
+   colon to set the maximum log level for that specific log target (e.g.
+   ``SYSTEMD_LOG_LEVEL=debug,console:info`` specifies to log at debug level except when
+   logging to the console which should be at info level). Note that the global maximum log level takes
+   priority over any per target maximum log levels.
+
+.. inclusion-end-marker-do-not-remove log-level-body
+
+.. inclusion-end-marker-do-not-remove log-level
+
+.. inclusion-marker-do-not-remove log-color
+
+``$SYSTEMD_LOG_COLOR``
+----------------------
+.. inclusion-marker-do-not-remove log-color-body
+
+   A boolean. If true, messages written to the tty will be colored
+   according to priority.
+
+   This setting is only useful when messages are written directly to the terminal, because
+   :ref:`journalctl(1)` and
+   other tools that display logs will color messages based on the log level on their own.
+
+.. inclusion-end-marker-do-not-remove log-color-body
+
+.. inclusion-end-marker-do-not-remove log-color
+
+.. inclusion-marker-do-not-remove log-time
+
+``$SYSTEMD_LOG_TIME``
+---------------------
+.. inclusion-marker-do-not-remove log-time-body
+
+   A boolean. If true, console log messages will be prefixed with a
+   timestamp.
+
+   This setting is only useful when messages are written directly to the terminal or a file, because
+   :ref:`journalctl(1)` and
+   other tools that display logs will attach timestamps based on the entry metadata on their own.
+
+.. inclusion-end-marker-do-not-remove log-time-body
+
+.. inclusion-end-marker-do-not-remove log-time
+
+.. inclusion-marker-do-not-remove log-location
+
+``$SYSTEMD_LOG_LOCATION``
+-------------------------
+
+.. inclusion-marker-do-not-remove log-location-body
+
+   A boolean. If true, messages will be prefixed with a filename
+   and line number in the source code where the message originates.
+
+   Note that the log location is often attached as metadata to journal entries anyway. Including it
+   directly in the message text can nevertheless be convenient when debugging programs.
+
+.. inclusion-end-marker-do-not-remove log-location-body
+
+.. inclusion-end-marker-do-not-remove log-location
+
+.. inclusion-marker-do-not-remove log-tid
+
+``$SYSTEMD_LOG_TID``
+--------------------
+.. inclusion-marker-do-not-remove log-tid-body
+
+   A boolean. If true, messages will be prefixed with the current
+   numerical thread ID (TID).
+
+   Note that the this :directive:options:const:`information` is attached as metadata to journal entries anyway. Including it
+   directly in the message text can nevertheless be convenient when debugging programs.
+
+.. inclusion-end-marker-do-not-remove log-tid-body
+
+.. inclusion-end-marker-do-not-remove log-tid
+
+.. inclusion-marker-do-not-remove log-target
+
+``$SYSTEMD_LOG_TARGET``
+-----------------------
+.. inclusion-marker-do-not-remove log-target-body
+
+   The destination for log messages. One of
+   ``console`` (log to the attached tty), ``console-prefixed`` (log to
+   the attached tty but with prefixes encoding the log level and "facility", see `syslog(3) <https://man7.org/linux/man-pages/man3/syslog.3.html>`_,
+   ``kmsg`` (log to the kernel circular log buffer), ``journal`` (log to
+   the journal), ``journal-or-kmsg`` (log to the journal if available, and to kmsg
+   otherwise), ``auto`` (determine the appropriate log target automatically, the default),
+   ``null`` (disable log output).
+
+   .. COMMENT: <constant>syslog</constant>, <constant>syslog-or-kmsg</constant> are deprecated
+
+.. inclusion-end-marker-do-not-remove log-target-body
+
+.. inclusion-end-marker-do-not-remove log-target
+
+.. inclusion-marker-do-not-remove log-ratelimit-kmsg
+
+``$SYSTEMD_LOG_RATELIMIT_KMSG``
+-------------------------------
+.. inclusion-marker-do-not-remove log-ratelimit-kmsg-body
+
+   Whether to ratelimit kmsg or not. Takes a boolean.
+   Defaults to ``true``. If disabled, systemd will not ratelimit messages written to kmsg.
+
+.. inclusion-end-marker-do-not-remove log-ratelimit-kmsg-body
+
+.. inclusion-end-marker-do-not-remove log-ratelimit-kmsg
+
+.. inclusion-marker-do-not-remove pager
+
+``$SYSTEMD_PAGER``
+------------------
+.. inclusion-marker-do-not-remove pager-body
+
+   Pager to use when ``--no-pager`` is not given; overrides
+   ``$PAGER``. If neither ``$SYSTEMD_PAGER`` nor ``$PAGER`` are set, a
+   set of well-known pager implementations are tried in turn, including
+   `less(1) <https://man7.org/linux/man-pages/man1/less.1.html>`_ and
+   `more(1) <https://man7.org/linux/man-pages/man1/more.1.html>`_, until one is found. If
+   no pager implementation is discovered no pager is invoked. Setting this environment variable to an empty string
+   or the value ``cat`` is equivalent to passing ``--no-pager``.
+
+   Note: if ``$SYSTEMD_PAGERSECURE`` is not set, ``$SYSTEMD_PAGER``
+   (as well as ``$PAGER``) will be silently ignored.
+
+.. inclusion-end-marker-do-not-remove pager-body
+
+.. inclusion-end-marker-do-not-remove pager
+
+.. inclusion-marker-do-not-remove less
+
+``$SYSTEMD_LESS``
+-----------------
+.. inclusion-marker-do-not-remove less-body
+
+   Override the options passed to ``less`` (by default
+   ``FRSXMK``).
+
+   Users might want to change two options in particular:
+
+   ``K``
+   -----
+      This option instructs the pager to exit immediately when
+      :kbd:`Ctrl` + :kbd:`C` is pressed. To allow
+      ``less`` to handle :kbd:`Ctrl` + :kbd:`C`
+      itself to switch back to the pager command prompt, unset this option.
+
+      If the value of ``$SYSTEMD_LESS`` does not include ``K``,
+      and the pager that is invoked is ``less``,
+      :kbd:`Ctrl` + :kbd:`C` will be ignored by the
+      executable, and needs to be handled by the pager.
+
+   ``X``
+   -----
+      This option instructs the pager to not send termcap initialization and deinitialization
+      strings to the terminal. It is set by default to allow command output to remain visible in the
+      terminal even after the pager exits. Nevertheless, this prevents some pager functionality from
+      working, in particular paged output cannot be scrolled with the mouse.
+
+   Note that setting the regular ``$LESS`` environment variable has no effect
+   for ``less`` invocations by systemd tools.
+
+   See
+   `less(1) <https://man7.org/linux/man-pages/man1/less.1.html>`_
+   for more discussion.
+
+.. inclusion-end-marker-do-not-remove less-body
+
+.. inclusion-end-marker-do-not-remove less
+
+.. inclusion-marker-do-not-remove lesscharset
+
+``$SYSTEMD_LESSCHARSET``
+------------------------
+
+   Override the charset passed to ``less`` (by default ``utf-8``, if
+   the invoking terminal is determined to be UTF-8 compatible).
+
+   Note that setting the regular ``$LESSCHARSET`` environment variable has no effect
+   for ``less`` invocations by systemd tools.
+
+.. inclusion-end-marker-do-not-remove lesscharset
+
+.. inclusion-marker-do-not-remove lesssecure
+
+``$SYSTEMD_PAGERSECURE``
+------------------------
+
+   Takes a boolean argument. When true, the "secure" mode of the pager is enabled; if
+   false, disabled. If ``$SYSTEMD_PAGERSECURE`` is not set at all, secure mode is enabled
+   if the effective UID is not the same as the owner of the login session, see
+   `geteuid(2) <https://man7.org/linux/man-pages/man2/geteuid.2.html>`_
+   and :ref:`sd_pid_get_owner_uid(3)`.
+   In secure mode, ``LESSSECURE=1`` will be set when invoking the pager, and the pager shall
+   disable commands that open or create new files or start new subprocesses. When
+   ``$SYSTEMD_PAGERSECURE`` is not set at all, pagers which are not known to implement
+   secure mode will not be used. (Currently only
+   `less(1) <https://man7.org/linux/man-pages/man1/less.1.html>`_
+   implements secure mode.)
+
+   Note: when commands are invoked with elevated privileges, for example under `sudo(8) <https://man7.org/linux/man-pages/man8/sudo.8.html>`_ or
+   `pkexec(1) <http://linux.die.net/man/ 1/pkexec>`_, care
+   must be taken to ensure that unintended interactive features are not enabled. "Secure" mode for the
+   pager may be enabled automatically as describe above. Setting ``SYSTEMD_PAGERSECURE=0``
+   or not removing it from the inherited environment allows the user to invoke arbitrary commands. Note
+   that if the ``$SYSTEMD_PAGER`` or ``$PAGER`` variables are to be
+   honoured, ``$SYSTEMD_PAGERSECURE`` must be set too. It might be reasonable to completely
+   disable the pager using ``--no-pager`` instead.
+
+.. inclusion-end-marker-do-not-remove lesssecure
+
+.. inclusion-marker-do-not-remove colors
+
+``$SYSTEMD_COLORS``
+-------------------
+
+   Takes a boolean argument. When true, ``systemd`` and related utilities
+   will use colors in their output, otherwise the output will be monochrome. Additionally, the variable can
+   take one of the following special values: ``16``, ``256`` to restrict the use
+   of colors to the base 16 or 256 ANSI colors, respectively. This can be specified to override the automatic
+   decision based on ``$TERM`` and what the console is connected to.
+
+.. COMMENT: This is not documented on purpose, because it is not clear if $NO_COLOR will become supported
+            widely enough. So let's provide support, but without advertising this.
+            <varlistentry id='no-color'>
+            <term><varname>$NO_COLOR</varname></term>
+            <listitem><para>If set (to any value), and <varname>$SYSTEMD_COLORS</varname> is not set, equivalent to
+            <option>SYSTEMD_COLORS=0</option>. See <ulink url="https://no-color.org/">no-color.org</ulink>.</para>
+            </listitem>
+            </varlistentry>
+
+.. inclusion-end-marker-do-not-remove colors
+
+.. inclusion-marker-do-not-remove urlify
+
+``$SYSTEMD_URLIFY``
+-------------------
+
+   The value must be a boolean. Controls whether clickable links should be generated in
+   the output for terminal emulators supporting this. This can be specified to override the decision that
+   ``systemd`` makes based on ``$TERM`` and other conditions.
+
+.. inclusion-end-marker-do-not-remove urlify

doc-migration/source/includes/libsystemd-pkgconfig.rst

@@ -0,0 +1,15 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:orphan:
+
+Notes
+#####
+
+Functions described here are available as a shared
+library, which can be compiled against and linked to with the
+``libsystemd```pkg-config(1) <http://linux.die.net/man/ 1/pkg-config>`_
+file.
+
+.. include:: ./includes/threads-aware.rst
+                    :start-after: .. inclusion-marker-do-not-remove getenv
+                    :end-before: .. inclusion-end-marker-do-not-remove getenv

doc-migration/source/includes/sd_journal_get_data.rst

@@ -0,0 +1,296 @@
+:title: sd_journal_get_data
+:manvolnum: 3
+
+.. _sd_journal_get_data(3):
+
+======================
+sd_journal_get_data(3)
+======================
+
+**Name**
+
+sd_journal_get_data — sd_journal_enumerate_data — sd_journal_enumerate_available_data — sd_journal_restart_data — SD_JOURNAL_FOREACH_DATA — sd_journal_set_data_threshold — sd_journal_get_data_threshold — Read data fields from the current journal entry
+###########################################################################################################################################################################################################################################################
+
+**Synopsis**
+
+#include <systemd/sd-journal.h>
+
+.. code-block::sh
+
+   int ``sd_journal_get_data``
+   sd_journal *j
+   const char *field
+   const void \**data
+   size_t *length
+
+   int ``sd_journal_enumerate_data``
+   sd_journal *j
+   const void \**data
+   size_t *length
+
+   int ``sd_journal_enumerate_available_data``
+   sd_journal *j
+   const void \**data
+   size_t *length
+
+   void ``sd_journal_restart_data``
+   sd_journal *j
+
+   ``SD_JOURNAL_FOREACH_DATA``
+   sd_journal *j
+   const void *data
+   size_t length
+
+   int ``sd_journal_set_data_threshold``
+   sd_journal *j
+   size_t sz
+
+   int ``sd_journal_get_data_threshold``
+   sd_journal *j
+   size_t *sz
+
+Description
+===========
+
+``sd_journal_get_data()`` gets the data object associated with a specific field
+from the current journal entry. It takes four arguments: the journal context object, a string with the
+field name to request, plus a pair of pointers to pointer/size variables where the data object and its
+size shall be stored in. The field name should be an entry field name. Well-known field names are listed in
+:ref:`systemd.journal-fields(7)`,
+but any field can be specified. The returned data is in a read-only memory map and is only valid until
+the next invocation of ``sd_journal_get_data()``,
+``sd_journal_enumerate_data()``,
+``sd_journal_enumerate_available_data()``, or when the read pointer is altered. Note
+that the data returned will be prefixed with the field name and ``=``. Also note that, by
+default, data fields larger than 64K might get truncated to 64K. This threshold may be changed and turned
+off with ``sd_journal_set_data_threshold()`` (see below).
+
+``sd_journal_enumerate_data()`` may be used
+to iterate through all fields of the current entry. On each
+invocation the data for the next field is returned. The order of
+these fields is not defined. The data returned is in the same
+format as with ``sd_journal_get_data()`` and also
+follows the same life-time semantics.
+
+``sd_journal_enumerate_available_data()`` is similar to
+``sd_journal_enumerate_data()``, but silently skips any fields which may be valid, but
+are too large or not supported by current implementation.
+
+``sd_journal_restart_data()`` resets the
+data enumeration index to the beginning of the entry. The next
+invocation of ``sd_journal_enumerate_data()``
+will return the first field of the entry again.
+
+Note that the ``SD_JOURNAL_FOREACH_DATA()`` macro may be used as a handy wrapper
+around ``sd_journal_restart_data()`` and
+``sd_journal_enumerate_available_data()``.
+
+Note that these functions will not work before
+:ref:`sd_journal_next(3)`
+(or related call) has been called at least once, in order to
+position the read pointer at a valid entry.
+
+``sd_journal_set_data_threshold()`` may be
+used to change the data field size threshold for data returned by
+``sd_journal_get_data()``,
+``sd_journal_enumerate_data()`` and
+``sd_journal_enumerate_unique()``. This threshold
+is a hint only: it indicates that the client program is interested
+only in the initial parts of the data fields, up to the threshold
+in size — but the library might still return larger data objects.
+That means applications should not rely exclusively on this
+setting to limit the size of the data fields returned, but need to
+apply an explicit size limit on the returned data as well. This
+threshold defaults to 64K by default. To retrieve the complete
+data fields this threshold should be turned off by setting it to
+0, so that the library always returns the complete data objects.
+It is recommended to set this threshold as low as possible since
+this relieves the library from having to decompress large
+compressed data objects in full.
+
+``sd_journal_get_data_threshold()`` returns
+the currently configured data field size threshold.
+
+Return Value
+============
+
+``sd_journal_get_data()`` returns 0 on success or a negative errno-style error
+code. ``sd_journal_enumerate_data()`` and
+``sd_journal_enumerate_available_data()`` return a positive integer if the next field
+has been read, 0 when no more fields remain, or a negative errno-style error code.
+``sd_journal_restart_data()`` doesn't return anything.
+``sd_journal_set_data_threshold()`` and ``sd_journal_get_threshold()``
+return 0 on success or a negative errno-style error code.
+
+Errors
+------
+
+Returned errors may indicate the following problems:
+
+.. inclusion-marker-do-not-remove EINVAL
+
+-EINVAL
+-------
+
+   One of the required parameters is ``NULL`` or invalid.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EINVAL
+
+.. inclusion-marker-do-not-remove ECHILD
+
+-ECHILD
+-------
+
+   The journal object was created in a different process, library or module instance.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ECHILD
+
+.. inclusion-marker-do-not-remove EADDRNOTAVAIL
+
+-EADDRNOTAVAIL
+--------------
+
+   The read pointer is not positioned at a valid entry;
+   :ref:`sd_journal_next(3)`
+   or a related call has not been called at least once.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EADDRNOTAVAIL
+
+.. inclusion-marker-do-not-remove ENOENT
+
+-ENOENT
+-------
+
+   The current entry does not include the specified field.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOENT
+
+.. inclusion-marker-do-not-remove ENOMEM
+
+-ENOMEM
+-------
+
+   Memory allocation failed.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOMEM
+
+.. inclusion-marker-do-not-remove ENOBUFS
+
+-ENOBUFS
+--------
+
+   A compressed entry is too large.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove ENOBUFS
+
+.. inclusion-marker-do-not-remove E2BIG
+
+-E2BIG
+------
+
+   The data field is too large for this computer architecture (e.g. above 4 GB on a
+   32-bit architecture).
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove E2BIG
+
+.. inclusion-marker-do-not-remove EPROTONOSUPPORT
+
+-EPROTONOSUPPORT
+----------------
+
+   The journal is compressed with an unsupported method or the journal uses an
+   unsupported feature.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EPROTONOSUPPORT
+
+.. inclusion-marker-do-not-remove EBADMSG
+
+-EBADMSG
+--------
+
+   The journal is corrupted (possibly just the entry being iterated over).
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EBADMSG
+
+.. inclusion-marker-do-not-remove EIO
+
+-EIO
+----
+
+   An I/O error was reported by the kernel.
+
+   .. versionadded:: 246
+
+.. inclusion-end-marker-do-not-remove EIO
+
+Notes
+=====
+
+.. include:: ./threads-aware.rst
+                    :start-after: .. inclusion-marker-do-not-remove strict
+                    :end-before: .. inclusion-end-marker-do-not-remove strict
+
+.. include:: ./libsystemd-pkgconfig.rst
+                    :start-after: .. inclusion-marker-do-not-remove pkgconfig-text
+                    :end-before: .. inclusion-end-marker-do-not-remove pkgconfig-text
+
+Examples
+========
+
+See
+:ref:`sd_journal_next(3)`
+for a complete example how to use
+``sd_journal_get_data()``.
+
+Use the
+``SD_JOURNAL_FOREACH_DATA()`` macro to
+iterate through all fields of the current journal
+entry:
+
+.. code-block:: sh
+
+   …
+   int print_fields(sd_journal *j) {
+     const void *data;
+     size_t length;
+     SD_JOURNAL_FOREACH_DATA(j, data, length)
+       printf("%.*s\n", (int) length, data);
+   }
+   …
+
+History
+=======
+
+``sd_journal_get_data()``,
+``sd_journal_enumerate_data()``,
+``sd_journal_restart_data()``, and
+``SD_JOURNAL_FOREACH_DATA()`` were added in version 187.
+
+``sd_journal_set_data_threshold()`` and
+``sd_journal_get_data_threshold()`` were added in version 196.
+
+``sd_journal_enumerate_available_data()`` was added in version 246.
+
+See Also
+========
+
+:ref:`systemd(1)`, :ref:`systemd.journal-fields(7)`, :ref:`sd-journal(3)`, :ref:`sd_journal_open(3)`, :ref:`sd_journal_next(3)`, :ref:`sd_journal_get_realtime_usec(3)`, :ref:`sd_journal_query_unique(3)`

doc-migration/source/includes/standard-options.rst

@@ -0,0 +1,164 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:orphan:
+.. inclusion-marker-do-not-remove help
+
+``-h, --help``
+--------------
+
+   Print a short help text and exit.
+
+.. inclusion-end-marker-do-not-remove help
+
+.. inclusion-marker-do-not-remove version
+
+``--version``
+-------------
+
+   Print a short version string and exit.
+
+.. inclusion-end-marker-do-not-remove version
+
+.. inclusion-marker-do-not-remove no-pager
+
+``--no-pager``
+--------------
+
+   Do not pipe output into a pager.
+
+.. inclusion-end-marker-do-not-remove no-pager
+
+.. inclusion-marker-do-not-remove no-ask-password
+
+``--no-ask-password``
+---------------------
+
+   Do not query the user for authentication for privileged operations.
+
+.. inclusion-end-marker-do-not-remove no-ask-password
+
+.. inclusion-marker-do-not-remove legend
+
+``--legend=<BOOL>``
+-------------------
+
+   Enable or disable printing of the legend, i.e. column headers and the footer with hints. The
+   legend is printed by default, unless disabled with ``--quiet`` or similar.
+
+.. inclusion-end-marker-do-not-remove legend
+
+.. inclusion-marker-do-not-remove no-legend
+
+``--no-legend``
+---------------
+
+   Do not print the legend, i.e. column headers and the
+   footer with hints.
+
+.. inclusion-end-marker-do-not-remove no-legend
+
+.. inclusion-marker-do-not-remove cat-config
+
+``--cat-config``
+----------------
+
+   Copy the contents of config files to standard output.
+   Before each file, the filename is printed as a comment.
+
+.. inclusion-end-marker-do-not-remove cat-config
+
+.. inclusion-marker-do-not-remove tldr
+
+``--tldr``
+----------
+
+   Copy the contents of config files to standard output. Only the "interesting" parts of the
+   configuration files are printed, comments and empty lines are skipped. Before each file, the filename
+   is printed as a comment.
+
+.. inclusion-end-marker-do-not-remove tldr
+
+.. inclusion-marker-do-not-remove json
+
+``--json=<MODE>``
+-----------------
+
+   Shows output formatted as JSON. Expects one of ``short`` (for the
+   shortest possible output without any redundant whitespace or line breaks), ``pretty``
+   (for a pretty version of the same, with indentation and line breaks) or ``off`` (to turn
+   off JSON output, the default).
+
+.. inclusion-end-marker-do-not-remove json
+
+.. inclusion-marker-do-not-remove j
+
+``-j``
+------
+
+   Equivalent to ``--json=pretty`` if running on a terminal, and
+   ``--json=short`` otherwise.
+
+.. inclusion-end-marker-do-not-remove j
+
+.. inclusion-marker-do-not-remove signal
+
+``-s, --signal=``
+-----------------
+
+   When used with ``kill``, choose which signal to send to selected processes. Must
+   be one of the well-known signal specifiers such as ``SIGTERM``,
+   ``SIGINT`` or ``SIGSTOP``. If omitted, defaults to
+   ``SIGTERM``.
+
+   The special value ``help`` will list the known values and the program will exit
+   immediately, and the special value ``list`` will list known values along with the
+   numerical signal numbers and the program will exit immediately.
+
+.. inclusion-end-marker-do-not-remove signal
+
+.. inclusion-marker-do-not-remove image-policy-open
+
+``--image-policy=<policy>``
+---------------------------
+
+   Takes an image policy string as argument, as per
+   :ref:`systemd.image-policy(7)`. The
+   policy is enforced when operating on the disk image specified via ``--image=``, see
+   above. If not specified defaults to the ``*`` policy, i.e. all recognized file systems
+   in the image are used.
+
+.. inclusion-end-marker-do-not-remove image-policy-open
+
+.. inclusion-marker-do-not-remove esp-path
+
+``--esp-path=``
+---------------
+
+   Path to the EFI System Partition (ESP). If not specified, ``/efi/``,
+   ``/boot/``, and ``/boot/efi/`` are checked in turn. It is
+   recommended to mount the ESP to ``/efi/``, if possible.
+
+.. inclusion-end-marker-do-not-remove esp-path
+
+.. inclusion-marker-do-not-remove boot-path
+
+``--boot-path=``
+----------------
+
+   Path to the Extended Boot Loader partition, as defined in the
+   `Boot Loader Specification <https://uapi-group.org/specifications/specs/boot_loader_specification>`_.
+   If not specified, ``/boot/`` is checked. It is recommended to mount the Extended Boot
+   Loader partition to ``/boot/``, if possible.
+
+.. inclusion-end-marker-do-not-remove boot-path
+
+.. inclusion-marker-do-not-remove option-P
+
+``-P``
+------
+
+   Equivalent to ``--value`` ``--property=``, i.e. shows the value of the
+   property without the property name or ``=``. Note that using ``-P`` once
+   will also affect all properties listed with ``-p``/``--property=``.
+
+.. inclusion-end-marker-do-not-remove option-P

doc-migration/source/includes/threads-aware.rst

@@ -0,0 +1,28 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later:
+
+.. inclusion-marker-do-not-remove strict
+
+All functions listed here are thread-agnostic and only a single specific thread may operate on a
+given object during its entire lifetime. It's safe to allocate multiple independent objects and use each from a
+specific thread in parallel. However, it's not safe to allocate such an object in one thread, and operate or free it
+from any other, even if locking is used to ensure these threads don't operate on it at the very same time.
+
+.. inclusion-end-marker-do-not-remove strict
+
+.. inclusion-marker-do-not-remove safe
+
+All functions listed here are thread-safe and may be called in parallel from multiple threads.
+
+.. inclusion-end-marker-do-not-remove safe
+
+.. inclusion-marker-do-not-remove getenv
+
+The code described here uses
+:man-pages:`getenv(3)`,
+which is declared to be not multi-thread-safe. This means that the code calling the functions described
+here must not call
+:man-pages:`setenv(3)`
+from a parallel thread. It is recommended to only do calls to ``setenv()``
+from an early phase of the program when no other threads have been started.
+
+.. inclusion-end-marker-do-not-remove getenv

doc-migration/source/includes/user-system-options.rst

@@ -0,0 +1,70 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+
+:orphan:
+
+.. inclusion-marker-do-not-remove user
+
+``--user``
+----------
+
+   Talk to the service manager of the calling user,
+   rather than the service manager of the system.
+
+.. inclusion-end-marker-do-not-remove user
+
+.. inclusion-marker-do-not-remove system
+
+``--system``
+------------
+
+   Talk to the service manager of the system. This is the
+   implied default.
+
+.. inclusion-end-marker-do-not-remove system
+
+.. inclusion-marker-do-not-remove host
+
+``-H, --host=``
+---------------
+
+   Execute the operation remotely. Specify a hostname, or a
+   username and hostname separated by ``@``, to
+   connect to. The hostname may optionally be suffixed by a
+   port ssh is listening on, separated by ``:``, and then a
+   container name, separated by ``/``, which
+   connects directly to a specific container on the specified
+   host. This will use SSH to talk to the remote machine manager
+   instance. Container names may be enumerated with
+   ``machinectl -H
+   <HOST>``. Put IPv6 addresses in brackets.
+
+.. inclusion-end-marker-do-not-remove host
+
+.. inclusion-marker-do-not-remove machine
+
+``-M, --machine=``
+------------------
+
+   Execute operation on a local container. Specify a container name to connect to, optionally
+   prefixed by a user name to connect as and a separating ``@`` character. If the special
+   string ``.host`` is used in place of the container name, a connection to the local
+   system is made (which is useful to connect to a specific user's user bus: ``--user
+   --machine=lennart@.host``). If the ``@`` syntax is not used, the connection is
+   made as root user. If the ``@`` syntax is used either the left hand side or the right hand
+   side may be omitted (but not both) in which case the local user name and ``.host`` are
+   implied.
+
+.. inclusion-end-marker-do-not-remove machine
+
+.. inclusion-marker-do-not-remove capsule
+
+``-C, --capsule=``
+------------------
+
+   Execute operation on a capsule. Specify a capsule name to connect to. See
+   :ref:`capsule@.service(5)` for
+   details about capsules.
+
+   .. versionadded:: 256
+
+.. inclusion-end-marker-do-not-remove capsule

doc-migration/source/index.rst

@@ -0,0 +1,39 @@
+.. SPDX-License-Identifier: LGPL-2.1-or-later
+.. systemd documentation master file, created by
+   sphinx-quickstart on Wed Jun 26 16:24:13 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+systemd — System and Service Manager
+===================================
+
+.. manual reference to a doc by its reference label
+   see: https://www.sphinx-doc.org/en/master/usage/referencing.html#cross-referencing-arbitrary-locations
+.. Manual links
+.. ------------
+.. :ref:`busctl(1)`
+.. :ref:`systemd(1)`
+.. OR using the toctree to pull in files
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree
+.. This only works if we restructure our headings to match
+   https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
+   and then only have single top-level heading with the command name
+
+.. toctree::
+   :maxdepth: 1
+
+   docs/busctl
+   docs/runlevel
+   docs/journalctl
+   docs/os-release
+   docs/systemd
+   docs/systemD-directives
+   docs/repart.d
+   docs/includes/sd_journal_get_data
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`