diff --git a/.gitattributes b/.gitattributes index dae59aa844a..9cd3992297e 100644 --- a/.gitattributes +++ b/.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 diff --git a/.gitignore b/.gitignore index 08510b0ec2e..01477579293 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,6 @@ mkosi.local.conf .dir-locals-2.el .vscode/ /pkg/ +/doc-migration/.venv +/doc-migration/build +.venv diff --git a/doc-migration/Makefile b/doc-migration/Makefile new file mode 100644 index 00000000000..d0c3cbf1020 --- /dev/null +++ b/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) diff --git a/doc-migration/README.md b/doc-migration/README.md new file mode 100644 index 00000000000..34bad8f1f51 --- /dev/null +++ b/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: `` 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`` 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 diff --git a/doc-migration/convert.sh b/doc-migration/convert.sh new file mode 100755 index 00000000000..879ddadb6e7 --- /dev/null +++ b/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 diff --git a/doc-migration/db2rst.py b/doc-migration/db2rst.py new file mode 100644 index 00000000000..5efb40478ee --- /dev/null +++ b/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, + x + 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 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'\"([{ 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 `` 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 ' ' + + +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) diff --git a/doc-migration/main.py b/doc-migration/main.py new file mode 100644 index 00000000000..fbd289293f7 --- /dev/null +++ b/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() diff --git a/doc-migration/source/_ext/autogen_index.py b/doc-migration/source/_ext/autogen_index.py new file mode 100644 index 00000000000..80d26bfb92b --- /dev/null +++ b/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, } diff --git a/doc-migration/source/_ext/directive_roles.py b/doc-migration/source/_ext/directive_roles.py new file mode 100644 index 00000000000..012ad19747d --- /dev/null +++ b/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, + } diff --git a/doc-migration/source/_ext/external_man_links.py b/doc-migration/source/_ext/external_man_links.py new file mode 100644 index 00000000000..4bc2104268d --- /dev/null +++ b/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} diff --git a/doc-migration/source/_static/css/custom.css b/doc-migration/source/_static/css/custom.css new file mode 100644 index 00000000000..c2ad3fc7060 --- /dev/null +++ b/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; +} diff --git a/doc-migration/source/_static/systemd-logo.svg b/doc-migration/source/_static/systemd-logo.svg new file mode 100644 index 00000000000..a8af438dca7 --- /dev/null +++ b/doc-migration/source/_static/systemd-logo.svg @@ -0,0 +1,7 @@ + diff --git a/doc-migration/source/code-examples/c/event-quick-child.c b/doc-migration/source/code-examples/c/event-quick-child.c new file mode 100644 index 00000000000..828f0cd6f4b --- /dev/null +++ b/doc-migration/source/code-examples/c/event-quick-child.c @@ -0,0 +1,43 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#define _GNU_SOURCE 1 +#include +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/glib-event-glue.c b/doc-migration/source/code-examples/c/glib-event-glue.c new file mode 100644 index 00000000000..61e8bf6463d --- /dev/null +++ b/doc-migration/source/code-examples/c/glib-event-glue.c @@ -0,0 +1,48 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/hwdb-usb-device.c b/doc-migration/source/code-examples/c/hwdb-usb-device.c new file mode 100644 index 00000000000..3ce3ccd87f5 --- /dev/null +++ b/doc-migration/source/code-examples/c/hwdb-usb-device.c @@ -0,0 +1,31 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#define _GNU_SOURCE 1 +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/id128-app-specific.c b/doc-migration/source/code-examples/c/id128-app-specific.c new file mode 100644 index 00000000000..b8982c75f85 --- /dev/null +++ b/doc-migration/source/code-examples/c/id128-app-specific.c @@ -0,0 +1,13 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include + +#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; +} diff --git a/doc-migration/source/code-examples/c/inotify-watch-tmp.c b/doc-migration/source/code-examples/c/inotify-watch-tmp.c new file mode 100644 index 00000000000..07ee8f6754b --- /dev/null +++ b/doc-migration/source/code-examples/c/inotify-watch-tmp.c @@ -0,0 +1,58 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include +#include + +#include + +#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; +} diff --git a/doc-migration/source/code-examples/c/journal-enumerate-fields.c b/doc-migration/source/code-examples/c/journal-enumerate-fields.c new file mode 100644 index 00000000000..3d35b001786 --- /dev/null +++ b/doc-migration/source/code-examples/c/journal-enumerate-fields.c @@ -0,0 +1,21 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/journal-iterate-foreach.c b/doc-migration/source/code-examples/c/journal-iterate-foreach.c new file mode 100644 index 00000000000..9c0fa0eaf13 --- /dev/null +++ b/doc-migration/source/code-examples/c/journal-iterate-foreach.c @@ -0,0 +1,30 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/journal-iterate-poll.c b/doc-migration/source/code-examples/c/journal-iterate-poll.c new file mode 100644 index 00000000000..6b78296267a --- /dev/null +++ b/doc-migration/source/code-examples/c/journal-iterate-poll.c @@ -0,0 +1,28 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#define _GNU_SOURCE 1 +#include +#include +#include + +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); +} diff --git a/doc-migration/source/code-examples/c/journal-iterate-unique.c b/doc-migration/source/code-examples/c/journal-iterate-unique.c new file mode 100644 index 00000000000..f44303d75cd --- /dev/null +++ b/doc-migration/source/code-examples/c/journal-iterate-unique.c @@ -0,0 +1,27 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/journal-iterate-wait.c b/doc-migration/source/code-examples/c/journal-iterate-wait.c new file mode 100644 index 00000000000..69d3cccb34a --- /dev/null +++ b/doc-migration/source/code-examples/c/journal-iterate-wait.c @@ -0,0 +1,44 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/journal-stream-fd.c b/doc-migration/source/code-examples/c/journal-stream-fd.c new file mode 100644 index 00000000000..595091af810 --- /dev/null +++ b/doc-migration/source/code-examples/c/journal-stream-fd.c @@ -0,0 +1,31 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#define _GNU_SOURCE 1 +#include +#include +#include +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/logcontrol-example.c b/doc-migration/source/code-examples/c/logcontrol-example.c new file mode 100644 index 00000000000..23e73846cdb --- /dev/null +++ b/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 +#include +#include +#include +#include +#include + +#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; +} diff --git a/doc-migration/source/code-examples/c/notify-selfcontained-example.c b/doc-migration/source/code-examples/c/notify-selfcontained-example.c new file mode 100644 index 00000000000..6bbe4f2e3ba --- /dev/null +++ b/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 +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +#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; +} diff --git a/doc-migration/source/code-examples/c/path-documents.c b/doc-migration/source/code-examples/c/path-documents.c new file mode 100644 index 00000000000..994f20bcf4e --- /dev/null +++ b/doc-migration/source/code-examples/c/path-documents.c @@ -0,0 +1,19 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include +#include + +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; +} diff --git a/doc-migration/source/code-examples/c/print-unit-path-call-method.c b/doc-migration/source/code-examples/c/print-unit-path-call-method.c new file mode 100644 index 00000000000..15e8d3f51b2 --- /dev/null +++ b/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 +#include +#include +#include + +#include + +#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; +} diff --git a/doc-migration/source/code-examples/c/print-unit-path.c b/doc-migration/source/code-examples/c/print-unit-path.c new file mode 100644 index 00000000000..737244feb0d --- /dev/null +++ b/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 +#include +#include +#include + +#include + +#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; +} diff --git a/doc-migration/source/code-examples/c/sd-bus-container-append.c b/doc-migration/source/code-examples/c/sd-bus-container-append.c new file mode 100644 index 00000000000..07a24f24cc6 --- /dev/null +++ b/doc-migration/source/code-examples/c/sd-bus-container-append.c @@ -0,0 +1,20 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include + +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); +} diff --git a/doc-migration/source/code-examples/c/sd-bus-container-read.c b/doc-migration/source/code-examples/c/sd-bus-container-read.c new file mode 100644 index 00000000000..5ede316c03b --- /dev/null +++ b/doc-migration/source/code-examples/c/sd-bus-container-read.c @@ -0,0 +1,27 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include + +#include + +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); +} diff --git a/doc-migration/source/code-examples/c/sd_bus_error-example.c b/doc-migration/source/code-examples/c/sd_bus_error-example.c new file mode 100644 index 00000000000..3836f5e642a --- /dev/null +++ b/doc-migration/source/code-examples/c/sd_bus_error-example.c @@ -0,0 +1,18 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#include +#include +#include +#include + +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)); +} diff --git a/doc-migration/source/code-examples/c/vtable-example.c b/doc-migration/source/code-examples/c/vtable-example.c new file mode 100644 index 00000000000..2e8994471a0 --- /dev/null +++ b/doc-migration/source/code-examples/c/vtable-example.c @@ -0,0 +1,143 @@ +/* SPDX-License-Identifier: MIT-0 */ + +#define _GNU_SOURCE 1 +#include +#include +#include +#include +#include +#include + +#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; +} diff --git a/doc-migration/source/code-examples/py/90-rearrange-path.py b/doc-migration/source/code-examples/py/90-rearrange-path.py new file mode 100755 index 00000000000..5c727e411ec --- /dev/null +++ b/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)) diff --git a/doc-migration/source/code-examples/py/check-os-release-simple.py b/doc-migration/source/code-examples/py/check-os-release-simple.py new file mode 100644 index 00000000000..ce73c77b14a --- /dev/null +++ b/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!') diff --git a/doc-migration/source/code-examples/py/check-os-release.py b/doc-migration/source/code-examples/py/check-os-release.py new file mode 100644 index 00000000000..19b193ec76a --- /dev/null +++ b/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!') diff --git a/doc-migration/source/code-examples/py/notify-selfcontained-example.py b/doc-migration/source/code-examples/py/notify-selfcontained-example.py new file mode 100644 index 00000000000..a1efb419ced --- /dev/null +++ b/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") diff --git a/doc-migration/source/code-examples/sh/check-os-release.sh b/doc-migration/source/code-examples/sh/check-os-release.sh new file mode 100644 index 00000000000..12f7ee12cc5 --- /dev/null +++ b/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 diff --git a/doc-migration/source/conf.py b/doc-migration/source/conf.py new file mode 100644 index 00000000000..36b1eaa0c1f --- /dev/null +++ b/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' +] diff --git a/doc-migration/source/docs/busctl.rst b/doc-migration/source/docs/busctl.rst new file mode 100644 index 00000000000..df67b5eca56 --- /dev/null +++ b/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] [...] + +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 []`` +---------------------- + +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 [...]`` +-------------------------- + +Dump messages being exchanged. If + 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 [...]`` +-------------------------- + +Similar to ``monitor`` but +writes the output in pcapng format (for details, see +`PCAP Next Generation (pcapng) Capture File Format `_). +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 [...]`` +----------------------- + +Shows an object tree of one or more +services. If 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 []`` +----------------------------------------------- + +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 [[...]]`` +----------------------------------------------------------------------------- + +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 [[...]]`` +------------------------------------------------------------------- + +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 `` +---------------------------------------------------------- + +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 `` +--------------------------------------------------------------------------------- + +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=
`` +----------------------- + +Connect to the bus specified by +
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 +":."). + +.. 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=`` +------------------- + +When showing messages being exchanged, show only the +subset matching . +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=`` +----------------- + +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=`` +------------------------- + +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=`` +----------------------- + +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=`` +-------------------------------------------- + +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=`` +-------------------- + +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=`` +-------------------------- + +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=`` +----------------------- + +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=`` +--------------------------- + +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 `_). 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 `_, :ref:`sd-bus(3)`, :ref:`varlinkctl(1)`, :ref:`systemd(1)`, :ref:`machinectl(1)`, :die-net:`wireshark(1)` \ No newline at end of file diff --git a/doc-migration/source/docs/includes/sd_journal_get_data.rst b/doc-migration/source/docs/includes/sd_journal_get_data.rst new file mode 100644 index 00000000000..962fa8321ad --- /dev/null +++ b/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 `` + +.. 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)` \ No newline at end of file diff --git a/doc-migration/source/docs/journalctl.rst b/doc-migration/source/docs/journalctl.rst new file mode 100644 index 00000000000..15a9526348e --- /dev/null +++ b/doc-migration/source/docs/journalctl.rst @@ -0,0 +1,1110 @@ +.. SPDX-License-Identifier: LGPL-2.1-or-later: + +:title: journalctl + +:manvolnum: 1 + +.. _journalctl(1): + +============= +journalctl(1) +============= + +.. only:: html + + journalctl — Print log entries from the systemd journal + ####################################################### + + Synopsis + ######## + +``journalctl`` [OPTIONS...] [MATCHES...] + +Description +=========== + +``journalctl`` is used to print the log entries stored in the journal by +:ref:`systemd-journald.service(8)` +and +:ref:`systemd-journal-remote.service(8)`. + +If called without parameters, it will show the contents of the journal accessible to the calling +user, starting with the oldest entry collected. + +If one or more match arguments are passed, the output is filtered accordingly. A match is in the +format "FIELD=VALUE", e.g. "_SYSTEMD_UNIT=httpd.service", referring to +the components of a structured journal entry. See +:ref:`systemd.journal-fields(7)` +for a list of well-known fields. If multiple matches are specified matching different fields, the log +entries are filtered by both, i.e. the resulting output will show only entries matching all the specified +matches of this kind. If two matches apply to the same field, then they are automatically matched as +alternatives, i.e. the resulting output will show entries matching any of the specified matches for the +same field. Finally, the character "+" may appear as a separate word between other terms +on the command line. This causes all matches before and after to be combined in a disjunction +(i.e. logical OR). + +It is also possible to filter the entries by specifying an absolute file path as an argument. The +file path may be a file or a symbolic link and the file must exist at the time of the query. If a file +path refers to an executable binary, an "_EXE=" match for the canonicalized binary path +is added to the query. If a file path refers to an executable script, a "_COMM=" match +for the script name is added to the query. If a file path refers to a device node, +"_KERNEL_DEVICE=" matches for the kernel name of the device and for each of its ancestor +devices is added to the query. Symbolic links are dereferenced, kernel names are synthesized, and parent +devices are identified from the environment at the time of the query. In general, a device node is the +best proxy for an actual device, as log entries do not usually contain fields that identify an actual +device. For the resulting log entries to be correct for the actual device, the relevant parts of the +environment at the time the entry was logged, in particular the actual device corresponding to the device +node, must have been the same as those at the time of the query. Because device nodes generally change +their corresponding devices across reboots, specifying a device node path causes the resulting entries to +be restricted to those from the current boot. + +Additional constraints may be added using options ``--boot``, +``--unit=``, etc., to further limit what entries will be shown (logical AND). + +Output is interleaved from all accessible journal files, whether they are rotated or currently +being written, and regardless of whether they belong to the system itself or are accessible user +journals. The ``--header`` option can be used to identify which files +*are* being shown. + +The set of journal files which will be used can be modified using the ``--user``, +``--system``, ``--directory=``, and ``--file=`` options, see +below. + +All users are granted access to their private per-user journals. However, by default, only root and +users who are members of a few special groups are granted access to the system journal and the journals +of other users. Members of the groups "systemd-journal", "adm", and +"wheel" can read all journal files. Note that the two latter groups traditionally have +additional privileges specified by the distribution. Members of the "wheel" group can +often perform administrative tasks. + +The output is paged through ``less`` by default, and long lines are "truncated" to +screen width. The hidden part can be viewed by using the left-arrow and right-arrow keys. Paging can be +disabled; see the ``--no-pager`` option and the "Environment" section below. + +When outputting to a tty, lines are colored according to priority: lines of level ERROR and higher +are colored red; lines of level WARNING are colored yellow; lines of level NOTICE are highlighted; +lines of level INFO are displayed normally; lines of level DEBUG are colored grey. + +To write entries *to* the journal, a few methods may be used. In general, output +from systemd units is automatically connected to the journal, see +:ref:`systemd-journald.service(8)`. +In addition, +:ref:`systemd-cat(1)` +may be used to send messages to the journal directly. + +Source Options +============== + +The following options control where to read journal records from: + +``--system, --user`` +-------------------- + +Show messages from system services and the kernel (with +``--system``). Show messages from service of current user (with +``--user``). If neither is specified, show all messages that the user can see. + +The ``--user`` option affects how ``--unit=`` arguments are +treated. See ``--unit=``. + +Note that ``--user`` only works if persistent logging is enabled, via the +``Storage=`` setting in +:ref:`journald.conf(5)`. + +.. only:: html + + .. versionadded:: 205 + +``-M, --machine=`` +------------------ + +Show messages from a running, local container. Specify a container name to connect +to. + +.. only:: html + + .. versionadded:: 209 + +``-m, --merge`` +--------------- + +Show entries interleaved from all available journals, including remote +ones. + +.. only:: html + + .. versionadded:: 190 + +``-D , --directory=`` +------------------------------- + +Takes a directory path as argument. If specified, journalctl will operate on the +specified journal directory instead of the default runtime and system +journal paths. + +.. only:: html + + .. versionadded:: 187 + +``-i , --file=`` +---------------------------- + +Takes a file glob as an argument. If specified, journalctl will operate on the +specified journal files matching instead of the default runtime and +system journal paths. May be specified multiple times, in which case files will be suitably +interleaved. + +.. only:: html + + .. versionadded:: 205 + +``--root=`` +----------------- + +Takes a directory path as an argument. If specified, ``journalctl`` +will operate on journal directories and catalog file hierarchy underneath the specified directory +instead of the root directory (e.g. ``--update-catalog`` will create +``/var/lib/systemd/catalog/database``, and journal +files under ``/run/journal/`` or +``/var/log/journal/`` will be displayed). + +.. only:: html + + .. versionadded:: 201 + +``--image=`` +------------------- + +Takes a path to a disk image file or block device node. If specified, +``journalctl`` will operate on the file system in the indicated disk image. This +option is similar to ``--root=``, but operates on file systems stored in disk images or +block devices, thus providing an easy way to extract log data from disk images. The disk image should +either contain just a file system or a set of file systems within a GPT partition table, following +the `Discoverable Partitions +Specification `_. For further information on supported disk images, see +:ref:`systemd-nspawn(1)`'s +switch of the same name. + +.. only:: html + + .. versionadded:: 247 + +.. include:: ../includes/standard-options.rst + :start-after: .. inclusion-marker-do-not-remove image-policy-open + :end-before: .. inclusion-end-marker-do-not-remove image-policy-open + +``--namespace=`` +--------------------------- + +Takes a journal namespace identifier string as argument. If not specified the data +collected by the default namespace is shown. If specified shows the log data of the specified +namespace instead. If the namespace is specified as "*" data from all namespaces is +shown, interleaved. If the namespace identifier is prefixed with "+" data from the +specified namespace and the default namespace is shown, interleaved, but no other. For details about +journal namespaces see +:ref:`systemd-journald.service(8)`. + +.. only:: html + + .. versionadded:: 245 + +Filtering Options +================= + +The following options control how to filter journal records: + +``-S, --since=, -U, --until=`` +------------------------------ + +Start showing entries on or newer than the specified date, or on or older than the +specified date, respectively. Date specifications should be of the format "2012-10-30 +18:17:16". If the time part is omitted, "00:00:00" is assumed. If only +the seconds component is omitted, ":00" is assumed. If the date component is +omitted, the current day is assumed. Alternatively the strings "yesterday", +"today", "tomorrow" are understood, which refer to 00:00:00 of the +day before the current day, the current day, or the day after the current day, +respectively. "now" refers to the current time. Finally, relative times may be +specified, prefixed with "-" or "+", referring to times before or +after the current time, respectively. For complete time and date specification, see +:ref:`systemd.time(7)`. Note +that ``--output=short-full`` prints timestamps that follow precisely this format. + +.. only:: html + + .. versionadded:: 195 + +``-c, --cursor=`` +----------------- + +Start showing entries from the location in the journal specified by the passed +cursor. + +.. only:: html + + .. versionadded:: 193 + +``--after-cursor=`` +------------------- + +Start showing entries from the location in the journal *after* +the location specified by the passed cursor. The cursor is shown when the +``--show-cursor`` option is used. + +.. only:: html + + .. versionadded:: 206 + +``--cursor-file=`` +------------------------ + +If exists and contains a cursor, start showing +entries *after* this location. Otherwise show entries according to the other +given options. At the end, write the cursor of the last entry to +. Use this option to continually read the journal by sequentially +calling ``journalctl``. + +.. only:: html + + .. versionadded:: 242 + +``-b [[][<±offset>]|all], --boot[=[][<±offset>]|all]`` +-------------------------------------------------------------- + +Show messages from a specific boot. This will add a match for +"_BOOT_ID=". + +The argument may be empty, in which case logs for the current boot will be shown. + +If the boot ID is omitted, a positive will look up the boots +starting from the beginning of the journal, and an equal-or-less-than zero + will look up boots starting from the end of the journal. Thus, +``1`` means the first boot found in the journal in chronological order, +``2`` the second and so on; while ``-0`` is the last boot, +``-1`` the boot before last, and so on. An empty +is equivalent to specifying ``-0``, except when the current boot is not the last +boot (e.g. because ``--directory=`` was specified to look at logs from a different +machine). + +If the 32-character is specified, it may optionally be followed +by which identifies the boot relative to the one given by boot +. Negative values mean earlier boots and positive values mean later +boots. If is not specified, a value of zero is assumed, and the +logs for the boot given by are shown. + +The special argument ``all`` can be used to negate the effect of an earlier +use of ``-b``. + +.. only:: html + + .. versionadded:: 186 + +``-u, --unit=|`` +------------------------------- + +Show messages for the specified systemd unit (such as +a service unit), or for any of the units matched by . If a pattern +is specified, a list of unit names found in the journal is compared with the specified pattern and +all that match are used. For each unit name, a match is added for messages from the unit +("_SYSTEMD_UNIT="), along with additional matches for +messages from systemd and messages about coredumps for the specified unit. A match is also added for +"_SYSTEMD_SLICE=", such that if the provided + is a +:ref:`systemd.slice(5)` +unit, all logs of children of the slice will be shown. + +With ``--user``, all ``--unit=`` arguments will be converted to match +user messages as if specified with ``--user-unit=``. + +This parameter can be specified multiple times. + +.. only:: html + + .. versionadded:: 195 + +``--user-unit=`` +---------------- + +Show messages for the specified user session unit. This will add a match for messages +from the unit ("_SYSTEMD_USER_UNIT=" and "_UID=") and additional +matches for messages from session systemd and messages about coredumps for the specified unit. A +match is also added for "_SYSTEMD_USER_SLICE=", such +that if the provided is a +:ref:`systemd.slice(5)` +unit, all logs of children of the unit will be shown. + +This parameter can be specified multiple times. + +.. only:: html + + .. versionadded:: 198 + +``-t, --identifier=`` +---------------------------------------- + +Show messages for the specified syslog identifier +. + +This parameter can be specified multiple times. + +.. only:: html + + .. versionadded:: 217 + +``-T, --exclude-identifier=`` +------------------------------------------------ + +Exclude messages for the specified syslog identifier +. + +This parameter can be specified multiple times. + +.. only:: html + + .. versionadded:: 256 + +``-p, --priority=`` +------------------- + +Filter output by message priorities or priority ranges. Takes either a single numeric +or textual log level (i.e. between 0/"emerg" and 7/"debug"), or a +range of numeric/text log levels in the form FROM..TO. The log levels are the usual syslog log levels +as documented in :man-pages:`syslog(3)`, +i.e. "emerg"(0), "alert"(1), "crit"(2), +"err"(3), "warning"(4), "notice"(5), +"info"(6), "debug"(7). If a single log level is specified, all +messages with this log level or a lower (hence more important) log level are shown. If a range is +specified, all messages within the range are shown, including both the start and the end value of the +range. This will add "PRIORITY=" matches for the specified +priorities. + +.. only:: html + + .. versionadded:: 188 + +``--facility=`` +--------------- + +Filter output by syslog facility. Takes a comma-separated list of numbers or +facility names. The names are the usual syslog facilities as documented in :man-pages:`syslog(3)`. +``--facility=help`` may be used to display a list of known facility names and exit. + +.. only:: html + + .. versionadded:: 245 + +``-g, --grep=`` +--------------- + +Filter output to entries where the ``MESSAGE=`` field matches the +specified regular expression. PERL-compatible regular expressions are used, see `pcre2pattern(3) `_ +for a detailed description of the syntax. + +If the pattern is all lowercase, matching is case insensitive. Otherwise, matching is case +sensitive. This can be overridden with the ``--case-sensitive`` option, see +below. + +When used with ``--lines=`` (not prefixed with "+"), +``--reverse`` is implied. + +.. only:: html + + .. versionadded:: 237 + +``--case-sensitive[=BOOLEAN]`` +------------------------------ + +Make pattern matching case sensitive or case insensitive. + +.. only:: html + + .. versionadded:: 237 + +``-k, --dmesg`` +--------------- + +Show only kernel messages. This implies ``-b`` and adds the match +"_TRANSPORT=kernel". + +.. only:: html + + .. versionadded:: 205 + +Output Options +============== + +The following options control how journal records are printed: + +``-o, --output=`` +----------------- + +Controls the formatting of the journal entries that are shown. Takes one of the +following options: + +.. option:: short + + is the default and generates an output that is mostly identical to the + formatting of classic syslog files, showing one line per journal entry. + + .. only:: html + + .. versionadded:: 206 +.. option:: short-full + + is very similar, but shows timestamps in the format the + ``--since=`` and ``--until=`` options accept. Unlike the timestamp + information shown in ``short`` output mode this mode includes weekday, year and + timezone information in the output, and is locale-independent. + + .. only:: html + + .. versionadded:: 232 +.. option:: short-iso + + is very similar, but shows timestamps in the + `RFC 3339 `_ profile of ISO 8601. + + .. only:: html + + .. versionadded:: 206 +.. option:: short-iso-precise + + as for ``short-iso`` but includes full microsecond + precision. + + .. only:: html + + .. versionadded:: 234 +.. option:: short-precise + + is very similar, but shows classic syslog timestamps with full microsecond + precision. + + .. only:: html + + .. versionadded:: 207 +.. option:: short-monotonic + + is very similar, but shows monotonic timestamps instead of wallclock + timestamps. + + .. only:: html + + .. versionadded:: 206 +.. option:: short-delta + + as for ``short-monotonic`` but includes the time difference + to the previous entry. + Maybe unreliable time differences are marked by a "*". + + .. only:: html + + .. versionadded:: 252 +.. option:: short-unix + + is very similar, but shows seconds passed since January 1st 1970 UTC instead of + wallclock timestamps ("UNIX time"). The time is shown with microsecond accuracy. + + .. only:: html + + .. versionadded:: 230 +.. option:: verbose + + shows the full-structured entry items with all fields. + + .. only:: html + + .. versionadded:: 206 +.. option:: export + + serializes the journal into a binary (but mostly text-based) stream suitable + for backups and network transfer (see `Journal Export + Format `_ for more information). To import the binary stream back into native journald + format use + :ref:`systemd-journal-remote(8)`. + + .. only:: html + + .. versionadded:: 206 +.. option:: json + + formats entries as JSON objects, separated by newline characters (see `Journal JSON Format `_ + for more information). Field values are generally encoded as JSON strings, with three exceptions: + 1. Fields larger than 4096 bytes are encoded as ``null`` + values. (This may be turned off by passing ``--all``, but be aware that this may + allocate overly long JSON objects.) + Journal entries permit non-unique fields within the same log entry. JSON does + not allow non-unique fields within objects. Due to this, if a non-unique field is encountered a + JSON array is used as field value, listing all field values as elements. + Fields containing non-printable or non-UTF8 bytes are encoded as arrays + containing the raw bytes individually formatted as unsigned numbers. + Note that this encoding is reversible (with the exception of the size limit). + + .. only:: html + + .. versionadded:: 206 +.. option:: json-pretty + + formats entries as JSON data structures, but formats them in multiple lines in + order to make them more readable by humans. + + .. only:: html + + .. versionadded:: 206 +.. option:: json-sse + + formats entries as JSON data structures, but wraps them in a format suitable for + `Server-Sent + Events `_. + + .. only:: html + + .. versionadded:: 206 +.. option:: json-seq + + formats entries as JSON data structures, but prefixes them with an ASCII Record + Separator character (0x1E) and suffixes them with an ASCII Line Feed character (0x0A), in + accordance with `JavaScript Object Notation + (JSON) Text Sequences `_ ("application/json-seq"). + + .. only:: html + + .. versionadded:: 240 +.. option:: cat + + generates a very terse output, only showing the actual message of each journal + entry with no metadata, not even a timestamp. If combined with the + ``--output-fields=`` option will output the listed fields for each log record, + instead of the message. + + .. only:: html + + .. versionadded:: 206 +.. option:: with-unit + + similar to ``short-full``, but prefixes the unit and user unit names + instead of the traditional syslog identifier. Useful when using templated instances, as it will + include the arguments in the unit names. + + .. only:: html + + .. versionadded:: 239 + +``--truncate-newline`` +---------------------- + +Truncate each log message at the first newline character on output, so that only the +first line of each message is displayed. + +.. only:: html + + .. versionadded:: 254 + +``--output-fields=`` +-------------------- + +A comma separated list of the fields which should be included in the output. This +has an effect only for the output modes which would normally show all fields +(``verbose``, ``export``, ``json``, +``json-pretty``, ``json-sse`` and ``json-seq``), as well as +on ``cat``. For the former, the "__CURSOR", +"__REALTIME_TIMESTAMP", "__MONOTONIC_TIMESTAMP", and +"_BOOT_ID" fields are always printed. + +.. only:: html + + .. versionadded:: 236 + +``-n, --lines=`` +---------------- + +Show the most recent journal events and limit the number of events shown. The argument +is a positive integer or "all" to disable the limit. Additionally, if the number is +prefixed with "+", the oldest journal events are used instead. The default value is +10 if no argument is given. + +If ``--follow`` is used, this option is implied. When not prefixed with "+" +and used with ``--grep=``, ``--reverse`` is implied. + +``-r, --reverse`` +----------------- + +Reverse output so that the newest entries are displayed first. + +.. only:: html + + .. versionadded:: 198 + +``--show-cursor`` +----------------- + +The cursor is shown after the last entry after two dashes: + +.. code-block:: sh + + -- cursor: s=0639… +The format of the cursor is private and subject to change. + +.. only:: html + + .. versionadded:: 209 + +``--utc`` +--------- + +Express time in Coordinated Universal Time (UTC). + +.. only:: html + + .. versionadded:: 217 + +``-x, --catalog`` +----------------- + +Augment log lines with explanation texts from the message catalog. This will add +explanatory help texts to log messages in the output where this is available. These short help texts +will explain the context of an error or log event, possible solutions, as well as pointers to support +forums, developer documentation, and any other relevant manuals. Note that help texts are not +available for all messages, but only for selected ones. For more information on the message catalog, +see `Journal Message Catalogs `_. + +Note: when attaching ``journalctl`` output to bug reports, please do +*not* use ``-x``. + +.. only:: html + + .. versionadded:: 196 + +``--no-hostname`` +----------------- + +Don't show the hostname field of log messages originating from the local host. This +switch has an effect only on the ``short`` family of output modes (see above). + +Note: this option does not remove occurrences of the hostname from log entries themselves, so +it does not prevent the hostname from being visible in the logs. + +.. only:: html + + .. versionadded:: 230 + +``--no-full, --full, -l`` +------------------------- + +Ellipsize fields when they do not fit in available columns. The default is to show +full fields, allowing them to wrap or be truncated by the pager, if one is used. + +The old options ``-l``/``--full`` are not useful anymore, except to +undo ``--no-full``. + +.. only:: html + + .. versionadded:: 196 + +``-a, --all`` +------------- + +Show all fields in full, even if they include unprintable characters or are very +long. By default, fields with unprintable characters are abbreviated as "blob data". (Note that the +pager may escape unprintable characters again.) + +``-f, --follow`` +---------------- + +Show only the most recent journal entries, and continuously print new entries as +they are appended to the journal. + +``--no-tail`` +------------- + +Show all stored output lines, even in follow mode. Undoes the effect of +``--lines=``. + +``-q, --quiet`` +--------------- + +Suppresses all informational messages (i.e. "-- Journal begins at …", "-- Reboot +--"), any warning messages regarding inaccessible system journals when run as a normal +user. + +Pager Control Options +===================== + +The following options control page support: + +.. include:: ../includes/standard-options.rst + :start-after: .. inclusion-marker-do-not-remove no-pager + :end-before: .. inclusion-end-marker-do-not-remove no-pager + +``-e, --pager-end`` +------------------- + +Immediately jump to the end of the journal inside the implied pager tool. This +implies ``-n1000`` to guarantee that the pager will not buffer logs of unbounded +size. This may be overridden with an explicit ``-n`` with some other numeric value, +while ``-nall`` will disable this cap. Note that this option is only supported for +the :man-pages:`less(1)` +pager. + +.. only:: html + + .. versionadded:: 198 + +Forward Secure Sealing (FSS) Options +==================================== + +The following options may be used together with the ``--setup-keys`` command described +below: + +``--interval=`` +--------------- + +Specifies the change interval for the sealing key when generating an FSS key pair +with ``--setup-keys``. Shorter intervals increase CPU consumption but shorten the time +range of undetectable journal alterations. Defaults to 15min. + +.. only:: html + + .. versionadded:: 189 + +``--verify-key=`` +----------------- + +Specifies the FSS verification key to use for the ``--verify`` +operation. + +.. only:: html + + .. versionadded:: 189 + +``--force`` +----------- + +When ``--setup-keys`` is passed and Forward Secure Sealing (FSS) has +already been configured, recreate FSS keys. + +.. only:: html + + .. versionadded:: 206 + +Commands +======== + +The following commands are understood. If none is specified the default is to display journal records: + +``-N, --fields`` +---------------- + +Print all field names currently used in all entries of the journal. + +.. only:: html + + .. versionadded:: 229 + +``-F, --field=`` +---------------- + +Print all possible data values the specified field can take in all entries of the +journal. + +.. only:: html + + .. versionadded:: 195 + +``--list-boots`` +---------------- + +Show a tabular list of boot numbers (relative to the current boot), their IDs, and the +timestamps of the first and last message pertaining to the boot. When specified with +``-n/--lines=[+]`` option, only the +first (when the number prefixed with "+") or the last (without prefix) + entries will be shown. When specified with +``-r/--reverse``, the list will be shown in the reverse order. + +.. only:: html + + .. versionadded:: 209 + +``--disk-usage`` +---------------- + +Shows the current disk usage of all journal files. This shows the sum of the disk +usage of all archived and active journal files. + +.. only:: html + + .. versionadded:: 190 + +``--vacuum-size=, --vacuum-time=, --vacuum-files=`` +--------------------------------------------------- + +``--vacuum-size=`` removes the oldest archived journal files until the +disk space they use falls below the specified size. Accepts the usual "K", +"M", "G" and "T" suffixes (to the base of +1024). + +``--vacuum-time=`` removes archived journal files older than the specified +timespan. Accepts the usual "s" (default), "m", +"h", "days", "weeks", "months", +and "years" suffixes, see +:ref:`systemd.time(7)` for +details. + +``--vacuum-files=`` leaves only the specified number of separate journal +files. + +Note that running ``--vacuum-size=`` has only an indirect effect on the output +shown by ``--disk-usage``, as the latter includes active journal files, while the +vacuuming operation only operates on archived journal files. Similarly, +``--vacuum-files=`` might not actually reduce the number of journal files to below the +specified number, as it will not remove active journal files. + +``--vacuum-size=``, ``--vacuum-time=`` and +``--vacuum-files=`` may be combined in a single invocation to enforce any combination of +a size, a time and a number of files limit on the archived journal files. Specifying any of these +three parameters as zero is equivalent to not enforcing the specific limit, and is thus +redundant. + +These three switches may also be combined with ``--rotate`` into one command. If +so, all active files are rotated first, and the requested vacuuming operation is executed right +after. The rotation has the effect that all currently active files are archived (and potentially new, +empty journal files opened as replacement), and hence the vacuuming operation has the greatest effect +as it can take all log data written so far into account. + +.. only:: html + + .. versionadded:: 218 + +``--verify`` +------------ + +Check the journal file for internal consistency. If the file has been generated +with FSS enabled and the FSS verification key has been specified with +``--verify-key=``, authenticity of the journal file is verified. + +.. only:: html + + .. versionadded:: 189 + +``--sync`` +---------- + +Asks the journal daemon to write all yet unwritten journal data to the backing file +system and synchronize all journals. This call does not return until the synchronization operation +is complete. This command guarantees that any log messages written before its invocation are safely +stored on disk at the time it returns. + +.. only:: html + + .. versionadded:: 228 + +``--relinquish-var`` +-------------------- + +Asks the journal daemon for the reverse operation to ``--flush``: if +requested the daemon will write further log data to ``/run/log/journal/`` and +stops writing to ``/var/log/journal/``. A subsequent call to +``--flush`` causes the log output to switch back to +``/var/log/journal/``, see above. + +.. only:: html + + .. versionadded:: 243 + +``--smart-relinquish-var`` +-------------------------- + +Similar to ``--relinquish-var``, but executes no operation if the root +file system and ``/var/log/journal/`` reside on the same mount point. This operation +is used during system shutdown in order to make the journal daemon stop writing data to +``/var/log/journal/`` in case that directory is located on a mount point that needs +to be unmounted. + +.. only:: html + + .. versionadded:: 243 + +``--flush`` +----------- + +Asks the journal daemon to flush any log data stored in +``/run/log/journal/`` into ``/var/log/journal/``, if persistent +storage is enabled. This call does not return until the operation is complete. Note that this call is +idempotent: the data is only flushed from ``/run/log/journal/`` into +``/var/log/journal/`` once during system runtime (but see +``--relinquish-var`` below), and this command exits cleanly without executing any +operation if this has already happened. This command effectively guarantees that all data is flushed +to ``/var/log/journal/`` at the time it returns. + +.. only:: html + + .. versionadded:: 217 + +``--rotate`` +------------ + +Asks the journal daemon to rotate journal files. This call does not return until +the rotation operation is complete. Journal file rotation has the effect that all currently active +journal files are marked as archived and renamed, so that they are never written to in future. New +(empty) journal files are then created in their place. This operation may be combined with +``--vacuum-size=``, ``--vacuum-time=`` and +``--vacuum-file=`` into a single command, see above. + +.. only:: html + + .. versionadded:: 227 + +``--header`` +------------ + +Instead of showing journal contents, show internal header information of the +journal fields accessed. + +This option is particularly useful when trying to identify out-of-order journal entries, as +happens for example when the machine is booted with the wrong system time. + +.. only:: html + + .. versionadded:: 187 + +``--list-catalog [<128-bit-ID…>]`` +---------------------------------- + +List the contents of the message catalog as a table of message IDs, plus their +short description strings. + +If any <128-bit-ID>s are specified, only those entries are +shown. + +.. only:: html + + .. versionadded:: 196 + +``--dump-catalog [<128-bit-ID…>]`` +---------------------------------- + +Show the contents of the message catalog, with entries separated by a line +consisting of two dashes and the ID (the format is the same as ``.catalog`` +files). + +If any <128-bit-ID>s are specified, only those entries are +shown. + +.. only:: html + + .. versionadded:: 199 + +``--update-catalog`` +-------------------- + +Update the message catalog index. This command needs to be executed each time new +catalog files are installed, removed, or updated to rebuild the binary catalog +index. + +.. only:: html + + .. versionadded:: 196 + +``--setup-keys`` +---------------- + +Instead of showing journal contents, generate a new key pair for Forward Secure +Sealing (FSS). This will generate a sealing key and a verification key. The sealing key is stored in +the journal data directory and shall remain on the host. The verification key should be stored +externally. Refer to the ``Seal=`` option in +:ref:`journald.conf(5)` for +information on Forward Secure Sealing and for a link to a refereed scholarly paper detailing the +cryptographic theory it is based on. + +.. only:: html + + .. versionadded:: 189 + +.. 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 + +Exit status +=========== + +On success, 0 is returned; otherwise, a non-zero failure code is returned. + +.. include:: ../includes/common-variables.rst + +Examples +======== + +Without arguments, all collected logs are shown unfiltered: + +.. code-block:: sh + + journalctl + +With one match specified, all entries with a field matching the expression are shown: + +.. code-block:: sh + + journalctl _SYSTEMD_UNIT=avahi-daemon.service + journalctl _SYSTEMD_CGROUP=/user.slice/user-42.slice/session-c1.scope + +If two different fields are matched, only entries matching both expressions at the same time are +shown: + +.. code-block:: sh + + journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + +If two matches refer to the same field, all entries matching either expression are shown: + +.. code-block:: sh + + journalctl _SYSTEMD_UNIT=avahi-daemon.service _SYSTEMD_UNIT=dbus.service + +If the separator "+" is used, two expressions may be combined in a logical OR. The +following will show all messages from the Avahi service process with the PID 28097 plus all messages from +the D-Bus service (from any of its processes): + +.. code-block:: sh + + journalctl _SYSTEMD_UNIT=avahi-daemon.service _PID=28097 + _SYSTEMD_UNIT=dbus.service + +To show all fields emitted *by* a unit and *about* the unit, +option ``-u``/``--unit=`` should be used. ``journalctl -u +`` expands to a complex filter similar to + +.. code-block:: sh + + _SYSTEMD_UNIT=.service + + UNIT=.service _PID=1 + + OBJECT_SYSTEMD_UNIT=.service _UID=0 + + COREDUMP_UNIT=.service _UID=0 MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 + +(see +:ref:`systemd.journal-fields(7)` +for an explanation of those patterns). + +Show all logs generated by the D-Bus executable: + +.. code-block:: sh + + journalctl /usr/bin/dbus-daemon + +Show all kernel logs from previous boot: + +.. code-block:: sh + + journalctl -k -b -1 + +Show a live log display from a system service ``apache.service``: + +.. code-block:: sh + + journalctl -f -u apache + +See Also +======== + +:ref:`systemd(1)`, :ref:`systemd-cat(1)`, :ref:`systemd-journald.service(8)`, :ref:`systemctl(1)`, :ref:`coredumpctl(1)`, :ref:`systemd.journal-fields(7)`, :ref:`journald.conf(5)`, :ref:`systemd.time(7)`, :ref:`systemd-journal-remote.service(8)`, :ref:`systemd-journal-upload.service(8)` \ No newline at end of file diff --git a/doc-migration/source/docs/os-release.rst b/doc-migration/source/docs/os-release.rst new file mode 100644 index 00000000000..baec59b32ab --- /dev/null +++ b/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.`` + +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`` `_. + +``/etc/initrd-release`` +----------------------- + +In the `initrd `_, +``/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.`` +---------------------------------------------------------- + +``/usr/lib/extension-release.d/extension-release.`` +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 `_ 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.`` filename, the + 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 `_ 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 `_, 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 `_. 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 `_, 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.``, + `initrd `_ 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.`` + 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 `_ 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 `_ 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)` \ No newline at end of file diff --git a/doc-migration/source/docs/repart.d.rst b/doc-migration/source/docs/repart.d.rst new file mode 100644 index 00000000000..502878d5e3e --- /dev/null +++ b/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 `_. + +.. 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 `_. 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.`` 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)` \ No newline at end of file diff --git a/doc-migration/source/docs/runlevel.rst b/doc-migration/source/docs/runlevel.rst new file mode 100644 index 00000000000..f9627f8feb6 --- /dev/null +++ b/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)` \ No newline at end of file diff --git a/doc-migration/source/docs/systemD-directives.rst b/doc-migration/source/docs/systemD-directives.rst new file mode 100644 index 00000000000..408ca19ddc0 --- /dev/null +++ b/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:: diff --git a/doc-migration/source/docs/systemd.rst b/doc-migration/source/docs/systemd.rst new file mode 100644 index 00000000000..11ae5546553 --- /dev/null +++ b/doc-migration/source/docs/systemd.rst @@ -0,0 +1,1464 @@ +.. SPDX-License-Identifier: LGPL-2.1-or-later: + +:title: systemd + +:manvolnum: 1 + +.. _systemd(1): + +========== +systemd(1) +========== + +.. only:: html + + systemd — init — systemd system and service manager + ################################################### + + Synopsis + ######## + +``/usr/lib/systemd/systemd`` [OPTIONS...], ``init`` [OPTIONS...] {COMMAND} + +Description +=========== + +systemd is a system and service manager for Linux operating systems. When run as first process on +boot (as PID 1), it acts as init system that brings up and maintains userspace services. Separate +instances are started for logged-in users to start their services. + +``systemd`` is usually not invoked directly by the user, but is installed as the +``/sbin/init`` symlink and started during early boot. The user manager instances are +started automatically through the +:ref:`user@.service(5)` +service. + +For compatibility with SysV, if the binary is called as ``init`` and is not the +first process on the machine (PID is not 1), it will execute ``telinit`` and pass all +command line arguments unmodified. That means ``init`` and ``telinit`` are +mostly equivalent when invoked from normal login sessions. See +:ref:`telinit(8)` for more +information. + +When run as a system instance, systemd interprets the +configuration file ``system.conf`` and the files +in ``system.conf.d`` directories; when run as a +user instance, systemd interprets the configuration file +``user.conf`` and the files in +``user.conf.d`` directories. See +:ref:`systemd-system.conf(5)` +for more information. + +``systemd`` contains native implementations of various tasks that need to be +executed as part of the boot process. For example, it sets the hostname or configures the loopback +network device. It also sets up and mounts various API file systems, such as ``/sys/``, +``/proc/``, and ``/dev/``. + +``systemd`` will also reset the system clock during early boot if it appears to be +set incorrectly. See "System clock epoch" section below. + +Note that some but not all interfaces provided by systemd are covered by the +`Interface Portability and Stability Promise `_. + +The D-Bus API of ``systemd`` is described in +:ref:`org.freedesktop.systemd1(5)` +and +:ref:`org.freedesktop.LogControl1(5)`. + +Systems which invoke systemd in a container or initrd environment should implement the `Container Interface `_ or +`initrd Interface `_ +specifications, respectively. + +Units +===== + +systemd provides a dependency system between various +entities called "units" of 11 different types. Units encapsulate +various objects that are relevant for system boot-up and +maintenance. The majority of units are configured in unit +configuration files, whose syntax and basic set of options is +described in +:ref:`systemd.unit(5)`, +however some are created automatically from other configuration +files, dynamically from system state or programmatically at runtime. +Units may be "active" (meaning started, bound, plugged in, …, +depending on the unit type, see below), or "inactive" (meaning +stopped, unbound, unplugged, …), as well as in the process of +being activated or deactivated, i.e. between the two states (these +states are called "activating", "deactivating"). A special +"failed" state is available as well, which is very similar to +"inactive" and is entered when the service failed in some way +(process returned error code on exit, or crashed, an operation +timed out, or after too many restarts). If this state is entered, +the cause will be logged, for later reference. Note that the +various unit types may have a number of additional substates, +which are mapped to the five generalized unit states described +here. + +The following unit types are available: + +1. Service units, which start and control daemons + and the processes they consist of. For details, see + :ref:`systemd.service(5)`. + Socket units, which encapsulate local IPC or + network sockets in the system, useful for socket-based + activation. For details about socket units, see + :ref:`systemd.socket(5)`, + for details on socket-based activation and other forms of + activation, see + :ref:`daemon(7)`. + Target units are useful to group units, or + provide well-known synchronization points during boot-up, see + :ref:`systemd.target(5)`. + Device units expose kernel devices in systemd + and may be used to implement device-based activation. For + details, see + :ref:`systemd.device(5)`. + Mount units control mount points in the file + system, for details see + :ref:`systemd.mount(5)`. + Automount units provide automount capabilities, + for on-demand mounting of file systems as well as parallelized + boot-up. See + :ref:`systemd.automount(5)`. + Timer units are useful for triggering activation + of other units based on timers. You may find details in + :ref:`systemd.timer(5)`. + Swap units are very similar to mount units and + encapsulate memory swap partitions or files of the operating + system. They are described in + :ref:`systemd.swap(5)`. + Path units may be used to activate other + services when file system objects change or are modified. See + :ref:`systemd.path(5)`. + Slice units may be used to group units which + manage system processes (such as service and scope units) in a + hierarchical tree for resource management purposes. See + :ref:`systemd.slice(5)`. + Scope units are similar to service units, but + manage foreign processes instead of starting them as well. See + :ref:`systemd.scope(5)`. + +Units are named as their configuration files. Some units +have special semantics. A detailed list is available in +:ref:`systemd.special(7)`. + +systemd knows various kinds of dependencies, including +positive and negative requirement dependencies (i.e. +``Requires=`` and ``Conflicts=``) as +well as ordering dependencies (``After=`` and +``Before=``). NB: ordering and requirement +dependencies are orthogonal. If only a requirement dependency +exists between two units (e.g. ``foo.service`` +requires ``bar.service``), but no ordering +dependency (e.g. ``foo.service`` after +``bar.service``) and both are requested to start, +they will be started in parallel. It is a common pattern that both +requirement and ordering dependencies are placed between two +units. Also note that the majority of dependencies are implicitly +created and maintained by systemd. In most cases, it should be +unnecessary to declare additional dependencies manually, however +it is possible to do this. + +Application programs and units (via dependencies) may +request state changes of units. In systemd, these requests are +encapsulated as 'jobs' and maintained in a job queue. Jobs may +succeed or can fail, their execution is ordered based on the +ordering dependencies of the units they have been scheduled +for. + +On boot systemd activates the target unit +``default.target`` whose job is to activate +on-boot services and other on-boot units by pulling them in via +dependencies. Usually, the unit name is just an alias (symlink) for +either ``graphical.target`` (for fully-featured +boots into the UI) or ``multi-user.target`` (for +limited console-only boots for use in embedded or server +environments, or similar; a subset of graphical.target). However, +it is at the discretion of the administrator to configure it as an +alias to any other target unit. See +:ref:`systemd.special(7)` +for details about these target units. + +On first boot, ``systemd`` will enable or disable units according to preset policy. +See :ref:`systemd.preset(5)` +and "First Boot Semantics" in +:ref:`machine-id(5)`. + +systemd only keeps a minimal set of units loaded into memory. Specifically, the only units that are +kept loaded into memory are those for which at least one of the following conditions is true: + +1. It is in an active, activating, deactivating or failed state (i.e. in any unit state except for "inactive") + It has a job queued for it + It is a dependency of at least one other unit that is loaded into memory + It has some form of resource still allocated (e.g. a service unit that is inactive but for which + a process is still lingering that ignored the request to be terminated) + It has been pinned into memory programmatically by a D-Bus call + +systemd will automatically and implicitly load units from disk — if they are not loaded yet — as soon as +operations are requested for them. Thus, in many respects, the fact whether a unit is loaded or not is invisible to +clients. Use ``systemctl list-units --all`` to comprehensively list all units currently loaded. Any +unit for which none of the conditions above applies is promptly unloaded. Note that when a unit is unloaded from +memory its accounting data is flushed out too. However, this data is generally not lost, as a journal log record +is generated declaring the consumed resources whenever a unit shuts down. + +Processes systemd spawns are placed in individual Linux control groups named after the unit which +they belong to in the private systemd hierarchy. (see `Control Groups v2 `_ for more information +about control groups, or short "cgroups"). systemd uses this to effectively keep track of +processes. Control group information is maintained in the kernel, and is accessible via the file system +hierarchy (beneath ``/sys/fs/cgroup/``), or in tools such as :man-pages:`systemd-cgls(1)` or +:man-pages:`ps(1)` (``ps +xawf -eo pid,user,cgroup,args`` is particularly useful to list all processes and the systemd +units they belong to.). + +systemd is compatible with the SysV init system to a large +degree: SysV init scripts are supported and simply read as an +alternative (though limited) configuration file format. The SysV +``/dev/initctl`` interface is provided, and +compatibility implementations of the various SysV client tools are +available. In addition to that, various established Unix +functionality such as ``/etc/fstab`` or the +``utmp`` database are supported. + +systemd has a minimal transaction system: if a unit is +requested to start up or shut down it will add it and all its +dependencies to a temporary transaction. Then, it will verify if +the transaction is consistent (i.e. whether the ordering of all +units is cycle-free). If it is not, systemd will try to fix it up, +and removes non-essential jobs from the transaction that might +remove the loop. Also, systemd tries to suppress non-essential +jobs in the transaction that would stop a running service. Finally +it is checked whether the jobs of the transaction contradict jobs +that have already been queued, and optionally the transaction is +aborted then. If all worked out and the transaction is consistent +and minimized in its impact it is merged with all already +outstanding jobs and added to the run queue. Effectively this +means that before executing a requested operation, systemd will +verify that it makes sense, fixing it if possible, and only +failing if it really cannot work. + +Note that transactions are generated independently of a unit's +state at runtime, hence, for example, if a start job is requested on an +already started unit, it will still generate a transaction and wake up any +inactive dependencies (and cause propagation of other jobs as per the +defined relationships). This is because the enqueued job is at the time of +execution compared to the target unit's state and is marked successful and +complete when both satisfy. However, this job also pulls in other +dependencies due to the defined relationships and thus leads to, in our +example, start jobs for any of those inactive units getting queued as +well. + +Units may be generated dynamically at boot and system +manager reload time, for example based on other configuration +files or parameters passed on the kernel command line. For details, see +:ref:`systemd.generator(7)`. + +Directories +=========== + +``System unit directories`` +--------------------------- + +The systemd system manager reads unit +configuration from various directories. Packages that want to +install unit files shall place them in the directory returned +by ``pkg-config systemd +--variable=systemdsystemunitdir``. Other directories +checked are ``/usr/local/lib/systemd/system`` +and ``/usr/lib/systemd/system``. User +configuration always takes precedence. ``pkg-config +systemd --variable=systemdsystemconfdir`` returns the +path of the system configuration directory. Packages should +alter the content of these directories only with the +``enable`` and ``disable`` +commands of the +:ref:`systemctl(1)` +tool. Full list of directories is provided in +:ref:`systemd.unit(5)`. + +``User unit directories`` +------------------------- + +Similar rules apply for the user unit +directories. However, here the +`XDG +Base Directory specification `_ is followed to find +units. Applications should place their unit files in the +directory returned by ``pkg-config systemd +--variable=systemduserunitdir``. Global configuration +is done in the directory reported by ``pkg-config +systemd --variable=systemduserconfdir``. The +``enable`` and ``disable`` +commands of the +:ref:`systemctl(1)` +tool can handle both global (i.e. for all users) and private +(for one user) enabling/disabling of units. Full list of +directories is provided in +:ref:`systemd.unit(5)`. + +``SysV init scripts directory`` +------------------------------- + +The location of the SysV init script directory +varies between distributions. If systemd cannot find a native +unit file for a requested service, it will look for a SysV +init script of the same name (with the +``.service`` suffix +removed). + +``SysV runlevel link farm directory`` +------------------------------------- + +The location of the SysV runlevel link farm +directory varies between distributions. systemd will take the +link farm into account when figuring out whether a service +shall be enabled. Note that a service unit with a native unit +configuration file cannot be started by activating it in the +SysV runlevel link farm. + +Signals +======= + +The service listens to various UNIX process signals that can be used to request various actions +asynchronously. The signal handling is enabled very early during boot, before any further processes are +invoked. However, a supervising container manager or similar that intends to request these operations via +this mechanism must take into consideration that this functionality is not available during the earliest +initialization phase. An sd_notify() notification message carrying the +``X_SYSTEMD_SIGNALS_LEVEL=2`` field is emitted once the signal handlers are enabled, see +below. This may be used to schedule submission of these signals correctly. + +``SIGTERM`` +----------- + +Upon receiving this signal the systemd system +manager serializes its state, reexecutes itself and +deserializes the saved state again. This is mostly equivalent +to ``systemctl daemon-reexec``. + +systemd user managers will start the +``exit.target`` unit when this signal is +received. This is mostly equivalent to ``systemctl +--user start exit.target +--job-mode=replace-irreversibly``. + +``SIGINT`` +---------- + +Upon receiving this signal the systemd system manager will start the +``ctrl-alt-del.target`` unit. This is mostly equivalent to +``systemctl start ctrl-alt-del.target --job-mode=replace-irreversibly``. If +this signal is received more than 7 times per 2s, an immediate reboot is triggered. Note +that pressing +:kbd:`Ctrl` + :kbd:`Alt` + :kbd:`Del` on the +console will trigger this signal. Hence, if a reboot is hanging, pressing +:kbd:`Ctrl` + :kbd:`Alt` + :kbd:`Del` more than +7 times in 2 seconds is a relatively safe way to trigger an immediate reboot. + +systemd user managers treat this signal the same way as +``SIGTERM``. + +``SIGWINCH`` +------------ + +When this signal is received the systemd +system manager will start the +``kbrequest.target`` unit. This is mostly +equivalent to ``systemctl start +kbrequest.target``. + +This signal is ignored by systemd user +managers. + +``SIGPWR`` +---------- + +When this signal is received the systemd +manager will start the ``sigpwr.target`` +unit. This is mostly equivalent to ``systemctl start +sigpwr.target``. + +``SIGUSR1`` +----------- + +When this signal is received the systemd +manager will try to reconnect to the D-Bus +bus. + +``SIGUSR2`` +----------- + +When this signal is received the systemd +manager will log its complete state in human-readable form. +The data logged is the same as printed by +``systemd-analyze dump``. + +``SIGHUP`` +---------- + +Reloads the complete daemon configuration. +This is mostly equivalent to ``systemctl +daemon-reload``. + +``SIGRTMIN+0`` +-------------- + +Enters default mode, starts the +``default.target`` unit. This is mostly +equivalent to ``systemctl isolate +default.target``. + +``SIGRTMIN+1`` +-------------- + +Enters rescue mode, starts the +``rescue.target`` unit. This is mostly +equivalent to ``systemctl isolate +rescue.target``. + +``SIGRTMIN+2`` +-------------- + +Enters emergency mode, starts the +``emergency.service`` unit. This is mostly +equivalent to ``systemctl isolate +emergency.service``. + +``SIGRTMIN+3`` +-------------- + +Halts the machine, starts the +``halt.target`` unit. This is mostly +equivalent to ``systemctl start halt.target +--job-mode=replace-irreversibly``. + +``SIGRTMIN+4`` +-------------- + +Powers off the machine, starts the +``poweroff.target`` unit. This is mostly +equivalent to ``systemctl start poweroff.target +--job-mode=replace-irreversibly``. + +``SIGRTMIN+5`` +-------------- + +Reboots the machine, starts the +``reboot.target`` unit. This is mostly +equivalent to ``systemctl start reboot.target +--job-mode=replace-irreversibly``. + +``SIGRTMIN+6`` +-------------- + +Reboots the machine via kexec, starts the +``kexec.target`` unit. This is mostly +equivalent to ``systemctl start kexec.target +--job-mode=replace-irreversibly``. + +``SIGRTMIN+7`` +-------------- + +Reboots userspace, starts the ``soft-reboot.target`` unit. This is +mostly equivalent to ``systemctl start soft-reboot.target +--job-mode=replace-irreversibly``. + +.. only:: html + + .. versionadded:: 254 + +``SIGRTMIN+13`` +--------------- + +Immediately halts the machine. + +``SIGRTMIN+14`` +--------------- + +Immediately powers off the machine. + +``SIGRTMIN+15`` +--------------- + +Immediately reboots the machine. + +``SIGRTMIN+16`` +--------------- + +Immediately reboots the machine with kexec. + +``SIGRTMIN+17`` +--------------- + +Immediately reboots the userspace. + +.. only:: html + + .. versionadded:: 254 + +``SIGRTMIN+20`` +--------------- + +Enables display of status messages on the +console, as controlled via +``systemd.show_status=1`` on the kernel command +line. + +``SIGRTMIN+21`` +--------------- + +Disables display of +status messages on the console, as +controlled via +``systemd.show_status=0`` +on the kernel command +line. + +``SIGRTMIN+22`` +--------------- + +Sets the service manager's log level to "debug", in a fashion equivalent to +``systemd.log_level=debug`` on the kernel command line. + +``SIGRTMIN+23`` +--------------- + +Restores the log level to its configured value. The configured value is derived from – in order +of priority – the value specified with ``systemd.log-level=`` on the kernel command line, or the +value specified with ``LogLevel=`` in the configuration file, or the built-in default of +"info". + +.. only:: html + + .. versionadded:: 239 + +``SIGRTMIN+24`` +--------------- + +Immediately exits the manager (only available +for --user instances). + +.. only:: html + + .. versionadded:: 195 + +``SIGRTMIN+25`` +--------------- + +Upon receiving this signal the systemd manager will reexecute itself. This +is mostly equivalent to ``systemctl daemon-reexec`` except that it will be +done asynchronously. + +The systemd system manager treats this signal the same way as +``SIGTERM``. + +.. only:: html + + .. versionadded:: 250 + +``SIGRTMIN+26`` +--------------- + +Restores the log target to its configured value. The configured value is derived from – in +order of priority – the value specified with ``systemd.log-target=`` on the kernel command line, +or the value specified with ``LogTarget=`` in the configuration file, or the built-in +default. + +.. only:: html + + .. versionadded:: 239 + +``SIGRTMIN+27, SIGRTMIN+28`` +---------------------------- + +Sets the log target to "console" on ``SIGRTMIN+27`` (or +"kmsg" on ``SIGRTMIN+28``), in a fashion equivalent to +``systemd.log_target=console`` (or ``systemd.log_target=kmsg`` on +``SIGRTMIN+28``) on the kernel command line. + +.. only:: html + + .. versionadded:: 239 + +Environment +=========== + +The environment block for the system manager is initially set by the kernel. (In particular, +"key=value" assignments on the kernel command line are turned into environment +variables for PID 1). For the user manager, the system manager sets the environment as described in the +"Environment Variables in Spawned Processes" section of +:ref:`systemd.exec(5)`. The +``DefaultEnvironment=`` setting in the system manager applies to all services including +``user@.service``. Additional entries may be configured (as for any other service) +through the ``Environment=`` and ``EnvironmentFile=`` settings for +``user@.service`` (see +:ref:`systemd.exec(5)`). Also, +additional environment variables may be set through the ``ManagerEnvironment=`` setting in +:ref:`systemd-system.conf(5)` +and +:ref:`systemd-user.conf(5)`. + +Some of the variables understood by ``systemd``: + +``$SYSTEMD_LOG_LEVEL`` +---------------------- + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove log-level-body + :end-before: .. inclusion-end-marker-do-not-remove log-level-body + +This can be overridden with :directive:environment-variables:option:`--log-level=`. + +``$SYSTEMD_LOG_COLOR`` +---------------------- + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove log-color-body + :end-before: .. inclusion-end-marker-do-not-remove log-color-body + +This can be overridden with :directive:environment-variables:option:`--log-color=`. + +``$SYSTEMD_LOG_TIME`` +--------------------- + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove log-time-body + :end-before: .. inclusion-end-marker-do-not-remove log-time-body + +This can be overridden with :directive:environment-variables:option:`--log-time=`. + +.. only:: html + + .. versionadded:: 246 + +``$SYSTEMD_LOG_LOCATION`` +------------------------- + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove log-location-body + :end-before: .. inclusion-end-marker-do-not-remove log-location-body + +This can be overridden with :directive:environment-variables:option:`--log-location=`. + +``$SYSTEMD_LOG_TID`` +-------------------- + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove log-tid-body + :end-before: .. inclusion-end-marker-do-not-remove log-tid-body + +.. only:: html + + .. versionadded:: 247 + +``$SYSTEMD_LOG_TARGET`` +----------------------- + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove log-target-body + :end-before: .. inclusion-end-marker-do-not-remove log-target-body + +This can be overridden with :directive:environment-variables:option:`--log-target=`. + +``$SYSTEMD_LOG_RATELIMIT_KMSG`` +------------------------------- + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove log-ratelimit-kmsg-body + :end-before: .. inclusion-end-marker-do-not-remove log-ratelimit-kmsg-body + +.. only:: html + + .. versionadded:: 254 + +``$XDG_CONFIG_HOME, $XDG_CONFIG_DIRS, $XDG_DATA_HOME, $XDG_DATA_DIRS`` +---------------------------------------------------------------------- + +The systemd user manager uses these variables +in accordance to the `XDG +Base Directory specification `_ to find its +configuration. + +``$SYSTEMD_UNIT_PATH, $SYSTEMD_GENERATOR_PATH, $SYSTEMD_ENVIRONMENT_GENERATOR_PATH`` +------------------------------------------------------------------------------------ + +Controls where systemd looks for unit files and +generators. + +These variables may contain a list of paths, separated by colons +(":"). When set, if the list ends with an empty +component ("...:"), this list is prepended to the +usual set of paths. Otherwise, the specified list replaces the usual +set of paths. + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove pager + :end-before: .. inclusion-end-marker-do-not-remove pager + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove less + :end-before: .. inclusion-end-marker-do-not-remove less + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove lesscharset + :end-before: .. inclusion-end-marker-do-not-remove lesscharset + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove lesssecure + :end-before: .. inclusion-end-marker-do-not-remove lesssecure + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove colors + :end-before: .. inclusion-end-marker-do-not-remove colors + +.. include:: ../includes/common-variables.rst + :start-after: .. inclusion-marker-do-not-remove urlify + :end-before: .. inclusion-end-marker-do-not-remove urlify + +``$LISTEN_PID, $LISTEN_FDS, $LISTEN_FDNAMES`` +--------------------------------------------- + +Set by systemd for supervised processes during +socket-based activation. See +:ref:`sd_listen_fds(3)` +for more information. + +``$NOTIFY_SOCKET`` +------------------ + +Set by service manager for its services for status and readiness notifications. Also +consumed by service manager for notifying supervising container managers or service managers up the +stack about its own progress. See +:ref:`sd_notify(3)` and the +relevant section below for more information. + +For further environment variables understood by systemd and its various components, see `Known Environment Variables `_. + +Kernel Command Line +=================== + +When run as the system instance, systemd parses a number of options listed below. They can be +specified as kernel command line arguments which are parsed from a number of sources depending on the +environment in which systemd is executed. If run inside a Linux container, these options are parsed from +the command line arguments passed to systemd itself, next to any of the command line options listed in +the Options section above. If run outside of Linux containers, these arguments are parsed from +``/proc/cmdline`` and from the "SystemdOptions" EFI variable +(on EFI systems) instead. Options from ``/proc/cmdline`` have higher priority. + +Note: use of "SystemdOptions" is deprecated. + +The following variables are understood: + +``systemd.unit=, rd.systemd.unit=`` +----------------------------------- + +Overrides the unit to activate on boot. Defaults to +``default.target``. This may be used to temporarily boot into a different boot unit, +for example ``rescue.target`` or ``emergency.service``. See +:ref:`systemd.special(7)` +for details about these units. The option prefixed with "rd." is honored only in the +initrd, while the one that is not prefixed only in the main system. + +``systemd.dump_core`` +--------------------- + +Takes a boolean argument or enables the option if specified +without an argument. If enabled, the systemd manager (PID 1) dumps core when +it crashes. Otherwise, no core dump is created. Defaults to enabled. + +.. only:: html + + .. versionadded:: 233 + +``systemd.crash_chvt`` +---------------------- + +Takes a positive integer, or a boolean argument. Can be also specified without an +argument, with the same effect as a positive boolean. If a positive integer (in the range 1–63) is +specified, the system manager (PID 1) will activate the specified virtual terminal when it crashes. +Defaults to disabled, meaning that no such switch is attempted. If set to enabled, the virtual +terminal the kernel messages are written to is used instead. + +.. only:: html + + .. versionadded:: 233 + +``systemd.crash_shell`` +----------------------- + +Takes a boolean argument or enables the option if specified +without an argument. If enabled, the system manager (PID 1) spawns a shell +when it crashes, after a 10s delay. Otherwise, no shell is spawned. Defaults +to disabled, for security reasons, as the shell is not protected by password +authentication. + +.. only:: html + + .. versionadded:: 233 + +``systemd.crash_action=`` +------------------------- + +Takes one of "freeze", "reboot" or +"poweroff". Defaults to "freeze". If set to +"freeze", the system will hang indefinitely when the system manager (PID 1) crashes. +If set to "reboot", the system manager (PID 1) will reboot the machine automatically +when it crashes, after a 10s delay. If set to "poweroff", the system manager (PID 1) +will power off the machine immediately when it crashes. If combined with +:directive:kernel-commandline-options:var:`systemd.crash_shell`, the configured crash action is executed after the shell +exits. + +.. only:: html + + .. versionadded:: 256 + +``systemd.confirm_spawn`` +------------------------- + +Takes a boolean argument or a path to the virtual console +where the confirmation messages should be emitted. Can be also specified +without an argument, with the same effect as a positive boolean. If enabled, +the system manager (PID 1) asks for confirmation when spawning processes +using :directive:kernel-commandline-options:option:`/dev/console`. If a path or a console name (such as +"ttyS0") is provided, the virtual console pointed to by this +path or described by the give name will be used instead. Defaults to disabled. + +.. only:: html + + .. versionadded:: 233 + +``systemd.service_watchdogs=`` +------------------------------ + +Takes a boolean argument. If disabled, all service runtime +watchdogs (:directive:kernel-commandline-options:option:`WatchdogSec=`) and emergency actions (e.g. +:directive:kernel-commandline-options:option:`OnFailure=` or :directive:kernel-commandline-options:option:`StartLimitAction=`) are +ignored by the system manager (PID 1); see +:ref:`systemd.service(5)`. +Defaults to enabled, i.e. watchdogs and failure actions are processed +normally. The hardware watchdog is not affected by this +option. + +.. only:: html + + .. versionadded:: 237 + +``systemd.show_status`` +----------------------- + +Takes a boolean argument or the constants :directive:kernel-commandline-options:constant:`error` and +:directive:kernel-commandline-options:constant:`auto`. Can be also specified without an argument, with the same effect as a +positive boolean. If enabled, the systemd manager (PID 1) shows terse service status updates on the +console during bootup. With :directive:kernel-commandline-options:constant:`error`, only messages about failures are shown, but +boot is otherwise quiet. :directive:kernel-commandline-options:constant:`auto` behaves like :directive:kernel-commandline-options:option:`false` until there is +a significant delay in boot. Defaults to enabled, unless :directive:kernel-commandline-options:option:`quiet` is passed as kernel +command line option, in which case it defaults to :directive:kernel-commandline-options:constant:`error`. If specified overrides +the system manager configuration file option :directive:kernel-commandline-options:option:`ShowStatus=`, see +:ref:`systemd-system.conf(5)`. + +.. only:: html + + .. versionadded:: 233 + +``systemd.status_unit_format=`` +------------------------------- + +Takes :directive:kernel-commandline-options:option:`name`, :directive:kernel-commandline-options:option:`description` or +:directive:kernel-commandline-options:option:`combined` as the value. If :directive:kernel-commandline-options:option:`name`, the system manager will use unit +names in status messages. If :directive:kernel-commandline-options:option:`combined`, the system manager will use unit names and +description in status messages. When specified, overrides the system manager configuration file +option :directive:kernel-commandline-options:option:`StatusUnitFormat=`, see +:ref:`systemd-system.conf(5)`. + +.. only:: html + + .. versionadded:: 243 + +``systemd.log_color, systemd.log_level=, systemd.log_location, systemd.log_target=, systemd.log_time, systemd.log_tid, systemd.log_ratelimit_kmsg`` +--------------------------------------------------------------------------------------------------------------------------------------------------- + +Controls log output, with the same effect as the +:directive:kernel-commandline-options:var:`$SYSTEMD_LOG_COLOR`, :directive:kernel-commandline-options:var:`$SYSTEMD_LOG_LEVEL`, +:directive:kernel-commandline-options:var:`$SYSTEMD_LOG_LOCATION`, :directive:kernel-commandline-options:var:`$SYSTEMD_LOG_TARGET`, +:directive:kernel-commandline-options:var:`$SYSTEMD_LOG_TIME`, :directive:kernel-commandline-options:var:`$SYSTEMD_LOG_TID` and +:directive:kernel-commandline-options:var:`$SYSTEMD_LOG_RATELIMIT_KMSG` environment variables described above. +:directive:kernel-commandline-options:var:`systemd.log_color`, :directive:kernel-commandline-options:var:`systemd.log_location`, +:directive:kernel-commandline-options:var:`systemd.log_time`, :directive:kernel-commandline-options:var:`systemd.log_tid` and +:directive:kernel-commandline-options:var:`systemd.log_ratelimit_kmsg` can be specified without +an argument, with the same effect as a positive boolean. + +``systemd.default_standard_output=, systemd.default_standard_error=`` +--------------------------------------------------------------------- + +Controls default standard output and error output for services and sockets. That is, +controls the default for :directive:kernel-commandline-options:option:`StandardOutput=` and :directive:kernel-commandline-options:option:`StandardError=` (see +:ref:`systemd.exec(5)` for +details). Takes one of :directive:kernel-commandline-options:option:`inherit`, :directive:kernel-commandline-options:option:`null`, :directive:kernel-commandline-options:option:`tty`, +:directive:kernel-commandline-options:option:`journal`, :directive:kernel-commandline-options:option:`journal+console`, :directive:kernel-commandline-options:option:`kmsg`, +:directive:kernel-commandline-options:option:`kmsg+console`. If the argument is omitted +:directive:kernel-commandline-options:var:`systemd.default-standard-output=` defaults to :directive:kernel-commandline-options:option:`journal` and +:directive:kernel-commandline-options:var:`systemd.default-standard-error=` to :directive:kernel-commandline-options:option:`inherit`. + +``systemd.setenv=`` +------------------- + +Takes a string argument in the form +VARIABLE=VALUE. May be used to set default environment +variables to add to forked child processes. May be used more +than once to set multiple variables. + +``systemd.machine_id=`` +----------------------- + +Takes a 32 character hex value to be +used for setting the machine-id. Intended mostly for +network booting where the same machine-id is desired +for every boot. + +.. only:: html + + .. versionadded:: 229 + +``systemd.set_credential=, systemd.set_credential_binary=`` +----------------------------------------------------------- + +Sets a system credential, which can then be propagated to system services using the +:directive:kernel-commandline-options:var:`ImportCredential=` or :directive:kernel-commandline-options:var:`LoadCredential=` setting, see +:ref:`systemd.exec(5)` for +details. Takes a pair of credential name and value, separated by a colon. The +:directive:kernel-commandline-options:var:`systemd.set_credential=` parameter expects the credential value in literal text +form, the :directive:kernel-commandline-options:var:`systemd.set_credential_binary=` parameter takes binary data encoded in +Base64. Note that the kernel command line is typically accessible by unprivileged programs in +``/proc/cmdline``. Thus, this mechanism is not suitable for transferring sensitive +data. Use it only for data that is not sensitive (e.g. public keys/certificates, rather than private +keys), or in testing/debugging environments. + +For further information see `System and Service +Credentials `_ documentation. + +.. only:: html + + .. versionadded:: 251 + +``systemd.import_credentials=`` +------------------------------- + +Takes a boolean argument. If false disables importing credentials from the kernel +command line, the DMI/SMBIOS OEM string table, the qemu_fw_cfg subsystem or the EFI kernel +stub. + +.. only:: html + + .. versionadded:: 251 + +``quiet`` +--------- + +Turn off status output at boot, much like +:directive:kernel-commandline-options:var:`systemd.show_status=no` would. Note that +this option is also read by the kernel itself and disables +kernel log output. Passing this option hence turns off the +usual output from both the system manager and the kernel. + +.. only:: html + + .. versionadded:: 186 + +``debug`` +--------- + +Turn on debugging output. This is equivalent +to :directive:kernel-commandline-options:var:`systemd.log_level=debug`. Note that this +option is also read by the kernel itself and enables kernel +debug output. Passing this option hence turns on the debug +output from both the system manager and the +kernel. + +.. only:: html + + .. versionadded:: 205 + +``emergency, rd.emergency, -b`` +------------------------------- + +Boot into emergency mode. This is equivalent +to :directive:kernel-commandline-options:var:`systemd.unit=emergency.target` or +:directive:kernel-commandline-options:var:`rd.systemd.unit=emergency.target`, respectively, and +provided for compatibility reasons and to be easier to type. + +.. only:: html + + .. versionadded:: 186 + +``rescue, rd.rescue, single, s, S, 1`` +-------------------------------------- + +Boot into rescue mode. This is equivalent to +:directive:kernel-commandline-options:var:`systemd.unit=rescue.target` or +:directive:kernel-commandline-options:var:`rd.systemd.unit=rescue.target`, respectively, and +provided for compatibility reasons and to be easier to type. + +.. only:: html + + .. versionadded:: 186 + +``2, 3, 4, 5`` +-------------- + +Boot into the specified legacy SysV runlevel. +These are equivalent to +:directive:kernel-commandline-options:var:`systemd.unit=runlevel2.target`, +:directive:kernel-commandline-options:var:`systemd.unit=runlevel3.target`, +:directive:kernel-commandline-options:var:`systemd.unit=runlevel4.target`, and +:directive:kernel-commandline-options:var:`systemd.unit=runlevel5.target`, +respectively, and provided for compatibility reasons and to be +easier to type. + +.. only:: html + + .. versionadded:: 186 + +``locale.LANG=, locale.LANGUAGE=, locale.LC_CTYPE=, locale.LC_NUMERIC=, locale.LC_TIME=, locale.LC_COLLATE=, locale.LC_MONETARY=, locale.LC_MESSAGES=, locale.LC_PAPER=, locale.LC_NAME=, locale.LC_ADDRESS=, locale.LC_TELEPHONE=, locale.LC_MEASUREMENT=, locale.LC_IDENTIFICATION=`` +--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- + +Set the system locale to use. This overrides +the settings in ``/etc/locale.conf``. For +more information, see +:man-pages:`locale.conf(5)` +and +:man-pages:`locale(7)`. + +.. only:: html + + .. versionadded:: 186 + +For other kernel command line parameters understood by +components of the core OS, please refer to +:ref:`kernel-command-line(7)`. + +System Credentials +================== + +During initialization the service manager will import credentials from various sources into the +system's set of credentials, which can then be propagated into services and consumed by +generators: + +* When the service manager first initializes it will read system credentials from SMBIOS + Type 11 vendor strings + ``io.systemd.credential:=``, + and + ``io.systemd.credential.binary:=``. + At the same time it will import credentials from QEMU "fw_cfg". (Note + that the SMBIOS mechanism is generally preferred, because it is faster and generic.) + Credentials may be passed via the kernel command line, using the + ``systemd.set-credential=`` parameter, see above. + Credentials may be passed from the UEFI environment via + :ref:`systemd-stub(7)`. + When the service manager is invoked during the initrd → host transition it will import + all files in ``/run/credentials/@initrd/`` as system credentials. + +Invoke +:ref:`systemd-creds(1)` as +follows to see the list of credentials passed into the system: + +.. code-block:: sh + + # systemd-creds --system list + +For further information see `System and Service +Credentials `_ documentation. + +The service manager when run as PID 1 consumes the following system credentials: + +``vmm.notify_socket`` +--------------------- + +Contains a :directive:system-credentials:constant:`AF_VSOCK` or :directive:system-credentials:constant:`AF_UNIX` address where to +send a :directive:system-credentials:constant:`READY=1` notification message when the service manager has completed +booting. See +:ref:`sd_notify(3)` and +the next section for more information. Note that in case the hypervisor does not support +:directive:system-credentials:constant:`SOCK_DGRAM` over :directive:system-credentials:constant:`AF_VSOCK`, +:directive:system-credentials:constant:`SOCK_SEQPACKET` will be tried instead. The credential payload for +:directive:system-credentials:constant:`AF_VSOCK` should be a string in the form +"vsock:CID:PORT". "vsock-stream", "vsock-dgram" +and "vsock-seqpacket" can be used instead of "vsock" to force +usage of the corresponding socket type. + +This feature is useful for machine managers or other processes on the host to receive a +notification via VSOCK when a virtual machine has finished booting. + +.. only:: html + + .. versionadded:: 254 + +``system.machine_id`` +--------------------- + +Takes a 128bit hexadecimal ID to initialize ``/etc/machine-id`` from, if the +file is not set up yet. See +:ref:`machine-id(5)` for +details. + +.. only:: html + + .. versionadded:: 254 + +For a list of system credentials various other components of systemd consume, see +:ref:`systemd.system-credentials(7)`. + +Readiness Protocol +================== + +The service manager implements a readiness notification protocol both between the manager and its +services (i.e. down the stack), and between the manager and a potential supervisor further up the stack +(the latter could be a machine or container manager, or in case of a per-user service manager the system +service manager instance). The basic protocol (and the suggested API for it) is described in +:ref:`sd_notify(3)`. + +The notification socket the service manager (including PID 1) uses for reporting readiness to its +own supervisor is set via the usual ``$NOTIFY_SOCKET`` environment variable (see +above). Since this is directly settable only for container managers and for the per-user instance of the +service manager, an additional mechanism to configure this is available, in particular intended for use +in VM environments: the ``vmm.notify_socket`` system credential (see above) may be set to +a suitable socket (typically an ``AF_VSOCK`` one) via SMBIOS Type 11 vendor strings. For +details see above. + +The notification protocol from the service manager up the stack towards a supervisor supports a +number of extension fields that allow a supervisor to learn about specific properties of the system and +track its boot progress. Specifically the following fields are sent: + +* An ``X_SYSTEMD_HOSTNAME=…`` message will be sent out once the initial + hostname for the system has been determined. Note that during later runtime the hostname might be + changed again programmatically, and (currently) no further notifications are sent out in that case. + + .. only:: html + + .. versionadded:: 256 + An ``X_SYSTEMD_MACHINE_ID=…`` message will be sent out once the machine + ID of the system has been determined. See + :ref:`machine-id(5)` for + details. + + .. only:: html + + .. versionadded:: 256 + An ``X_SYSTEMD_SIGNALS_LEVEL=…`` message will be sent out once the + service manager installed the various UNIX process signal handlers described above. The field's value + is an unsigned integer formatted as decimal string, and indicates the supported UNIX process signal + feature level of the service manager. Currently, only a single feature level is defined: + + * ``X_SYSTEMD_SIGNALS_LEVEL=2`` covers the various UNIX process signals + documented above – which are a superset of those supported by the historical SysV init + system. + Signals sent to PID 1 before this message is sent might not be handled correctly yet. A consumer + of these messages should parse the value as an unsigned integer indication the level of support. For + now only the mentioned level 2 is defined, but later on additional levels might be defined with higher + integers, that will implement a superset of the currently defined behaviour. + + .. only:: html + + .. versionadded:: 256 + ``X_SYSTEMD_UNIT_ACTIVE=…`` and + ``X_SYSTEMD_UNIT_INACTIVE=…`` messages will be sent out for each target unit as it + becomes active or stops being active. This is useful to track boot progress and functionality. For + example, once the ``ssh-access.target`` unit is reported started SSH access is + typically available, see + :ref:`systemd.special(7)` for + details. + + .. only:: html + + .. versionadded:: 256 + An ``X_SYSTEMD_SHUTDOWN=…`` message will be sent out very shortly before + the system shuts down. The value is one of the strings "reboot", + "halt", "poweroff", "kexec" and indicates which kind + of shutdown is being executed. + + .. only:: html + + .. versionadded:: 256 + An ``X_SYSTEMD_REBOOT_PARAMETER=…`` message will also be sent out very + shortly before the system shuts down. Its value is the reboot argument as configured with + ``systemctl --reboot-argument=…``. + + .. only:: html + + .. versionadded:: 256 + +Note that these extension fields are sent in addition to the regular "READY=1" and +"RELOADING=1" notifications. + +Options +======= + +``systemd`` is only very rarely invoked directly, since it is started early and is +already running by the time users may interact with it. Normally, tools like +:ref:`systemctl(1)` are used to +give commands to the manager. Since ``systemd`` is usually not invoked directly, the +options listed below are mostly useful for debugging and special purposes. + +Introspection and debugging options +----------------------------------- + +Those options are used for testing and introspection, and ``systemd`` may +be invoked with them at any time: + +.. option:: --dump-configuration-items + + Dump understood unit configuration items. This outputs a terse but complete list of + configuration items understood in unit definition files. + +.. option:: --dump-bus-properties + + Dump exposed bus properties. This outputs a terse but complete list of properties + exposed on D-Bus. + + .. only:: html + + .. versionadded:: 239 + +.. option:: --test + + Determine the initial start-up transaction (i.e. the list of jobs enqueued at + start-up), dump it and exit — without actually executing any of the determined jobs. This option is + useful for debugging only. Note that during regular service manager start-up additional units not + shown by this operation may be started, because hardware, socket, bus or other kinds of activation + might add additional jobs as the transaction is executed. Use ``--system`` to request + the initial transaction of the system service manager (this is also the implied default), combine + with ``--user`` to request the initial transaction of the per-user service manager + instead. + +.. option:: --system, --user + + When used in conjunction with ``--test``, selects whether to calculate + the initial transaction for the system instance or for a per-user instance. These options have no + effect when invoked without ``--test``, as during regular + (i.e. non-``--test``) invocations the service manager will automatically detect + whether it shall operate in system or per-user mode, by checking whether the PID it is run as is 1 + or not. Note that it is not supported booting and maintaining a system with the service manager + running in ``--system`` mode but with a PID other than 1. + +.. 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 + +Options that duplicate kernel command line settings +--------------------------------------------------- + +Those options correspond directly to options listed above in "Kernel Command Line". Both forms +may be used equivalently for the system manager, but it is recommended to use the forms listed above in +this context, because they are properly namespaced. When an option is specified both on the kernel +command line and as a normal command line argument, the latter has higher precedence. + +When ``systemd`` is used as a user manager, the kernel command line is ignored and +only the options described below are understood. Nevertheless, ``systemd`` is usually +started in this mode through the +:ref:`user@.service(5)` +service, which is shared between all users. It may be more convenient to use configuration files to +modify settings (see +:ref:`systemd-user.conf(5)`), +or environment variables. See the "Environment" section above for a discussion of how the environment +block is set. + +.. option:: --unit= + + Set default unit to activate on startup. If not specified, defaults to + ``default.target``. See ``systemd.unit=`` above. + +.. option:: --dump-core + + Enable core dumping on crash. This switch has no effect when running as user + instance. Same as ``systemd.dump_core=`` above. + +.. option:: --crash-vt= + + Switch to a specific virtual console (VT) on crash. This switch has no effect when + running as user instance. Same as ``systemd.crash_chvt=`` above (but not the + different spelling!). + + .. only:: html + + .. versionadded:: 227 + +.. option:: --crash-shell + + Run a shell on crash. This switch has no effect when running as user instance. See + ``systemd.crash_shell=`` above. + +.. option:: --crash-action= + + Specify what to do when the system manager (PID 1) crashes. This switch has no + effect when systemd is running as user instance. See ``systemd.crash_action=`` + above. + + .. only:: html + + .. versionadded:: 256 + +.. option:: --confirm-spawn + + Ask for confirmation when spawning processes. This switch has no effect when run as + user instance. See ``systemd.confirm_spawn`` above. + +.. option:: --show-status + + Show terse unit status information on the console during boot-up and shutdown. See + ``systemd.show_status`` above. + + .. only:: html + + .. versionadded:: 244 + +.. option:: --log-color + + Highlight important log messages. See ``systemd.log_color`` above. + + .. only:: html + + .. versionadded:: 244 + +.. option:: --log-level= + + Set log level. See ``systemd.log_level`` above. + +.. option:: --log-location + + Include code location in log messages. See ``systemd.log_location`` + above. + + .. only:: html + + .. versionadded:: 244 + +.. option:: --log-target= + + Set log target. See ``systemd.log_target`` above. + +.. option:: --log-time= + + Prefix console messages with timestamp. See ``systemd.log_time`` above. + + .. only:: html + + .. versionadded:: 246 + +.. option:: --machine-id= + + Override the machine-id set on the hard drive. See + ``systemd.machine_id=`` above. + + .. only:: html + + .. versionadded:: 229 + +.. option:: --service-watchdogs + + Globally enable/disable all service watchdog timeouts and emergency actions. See + ``systemd.service_watchdogs`` above. + + .. only:: html + + .. versionadded:: 237 + +.. option:: --default-standard-output=, --default-standard-error= + + Sets the default output or error output for all services and sockets, + respectively. See ``systemd.default_standard_output=`` and + ``systemd.default_standard_error=`` above. + +System clock epoch +================== + +When ``systemd`` is started or restarted, it may set the system clock to the +"epoch". This mechanism is used to ensure that the system clock remains somewhat reasonably initialized +and roughly monotonic across reboots, in case no battery-backed local RTC is available or it does not +work correctly. + +The epoch is the lowest date above which the system clock time is assumed to be set correctly. When +initializing, the local clock is *advanced* to the epoch if it was set to a lower +value. As a special case, if the local clock is sufficiently far in the future (by default 15 years, but +this can be configured at build time), the hardware clock is assumed to be broken, and the system clock +is *rewound* to the epoch. + +The epoch is set to the highest of: the build time of ``systemd``, the +modification time ("mtime") of ``/usr/lib/clock-epoch``, and the modification time of +``/var/lib/systemd/timesync/clock``. + +Files +===== + +``/run/systemd/notify`` +----------------------- + +Daemon status notification socket. This is an +``AF_UNIX`` datagram socket and is used to +implement the daemon notification logic as implemented by +:ref:`sd_notify(3)`. + +``/run/systemd/private`` +------------------------ + +Used internally as communication channel +between +:ref:`systemctl(1)` +and the systemd process. This is an +``AF_UNIX`` stream socket. This interface is +private to systemd and should not be used in external +projects. + +``/dev/initctl`` +---------------- + +Limited compatibility support for the SysV +client interface, as implemented by the +``systemd-initctl.service`` unit. This is a +named pipe in the file system. This interface is obsolete and +should not be used in new applications. + +``/usr/lib/clock-epoch`` +------------------------ + +The modification time ("mtime") of this file is used for the time epoch, see previous +section. + +.. only:: html + + .. versionadded:: 247 + +``/var/lib/systemd/timesync/clock`` +----------------------------------- + +The modification time ("mtime") of this file is updated by +:ref:`systemd-timesyncd.service(8)`. +If present, the modification time of file is used for the epoch, see previous section. + +.. only:: html + + .. versionadded:: 257 + +History +======= + +``systemd 252`` +--------------- + +Kernel command-line arguments ``systemd.unified_cgroup_hierarchy`` +and ``systemd.legacy_systemd_cgroup_controller`` were deprecated. Please switch to +the unified cgroup hierarchy. + +.. only:: html + + .. versionadded:: 252 + +See Also +======== + +The `systemd Homepage `_, :ref:`systemd-system.conf(5)`, :man-pages:`locale.conf(5)`, :ref:`systemctl(1)`, :ref:`journalctl(1)`, :ref:`systemd-notify(1)`, :ref:`daemon(7)`, :ref:`sd-daemon(3)`, :ref:`org.freedesktop.systemd1(5)`, :ref:`systemd.unit(5)`, :ref:`systemd.special(7)`, :die-net:`pkg-config(1)`, :ref:`kernel-command-line(7)`, :man-pages:`bootup(7)`, :ref:`systemd.directives(7)` + +For more information about the concepts and +ideas behind systemd, please refer to the +`Original Design Document `_. \ No newline at end of file diff --git a/doc-migration/source/includes/common-variables.rst b/doc-migration/source/includes/common-variables.rst new file mode 100644 index 00000000000..f1dd27253ac --- /dev/null +++ b/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) `_ + 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) `_, + ``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: syslog, syslog-or-kmsg 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) `_ and + `more(1) `_, 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) `_ + 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) `_ + 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) `_ + implements secure mode.) + + Note: when commands are invoked with elevated privileges, for example under `sudo(8) `_ or + `pkexec(1) `_, 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. + + $NO_COLOR + If set (to any value), and $SYSTEMD_COLORS is not set, equivalent to + . See no-color.org. + + + +.. 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 diff --git a/doc-migration/source/includes/libsystemd-pkgconfig.rst b/doc-migration/source/includes/libsystemd-pkgconfig.rst new file mode 100644 index 00000000000..0e3f1e0af42 --- /dev/null +++ b/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) `_ +file. + +.. include:: ./includes/threads-aware.rst + :start-after: .. inclusion-marker-do-not-remove getenv + :end-before: .. inclusion-end-marker-do-not-remove getenv diff --git a/doc-migration/source/includes/sd_journal_get_data.rst b/doc-migration/source/includes/sd_journal_get_data.rst new file mode 100644 index 00000000000..bb39516049d --- /dev/null +++ b/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 + +.. 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)` diff --git a/doc-migration/source/includes/standard-options.rst b/doc-migration/source/includes/standard-options.rst new file mode 100644 index 00000000000..31dde813738 --- /dev/null +++ b/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=`` +------------------- + + 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=`` +----------------- + + 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=`` +--------------------------- + + 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 `_. + 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 diff --git a/doc-migration/source/includes/threads-aware.rst b/doc-migration/source/includes/threads-aware.rst new file mode 100644 index 00000000000..2d851f6f0f4 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc-migration/source/includes/user-system-options.rst b/doc-migration/source/includes/user-system-options.rst new file mode 100644 index 00000000000..8c7473a7326 --- /dev/null +++ b/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 + ``. 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 diff --git a/doc-migration/source/index.rst b/doc-migration/source/index.rst new file mode 100644 index 00000000000..3d26e49b16e --- /dev/null +++ b/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` \ No newline at end of file