mirrors/systemd
0
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-02 14:53:35 +08:00
Code Issues Packages Projects Releases Wiki Activity
5e21da878c
systemd/man/common-variables.xml

211 lines
11 KiB
XML
Raw Normal View History

man: use xinclude to de-deduplicate common text I only tested with python-lxml. I'm not sure if xml.etree should be deprecated.
2014-02-12 13:55:38 +08:00
<?xml version="1.0"?>
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 21:40:58 +08:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 12:23:58 +08:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
Add missing headers and SPDX identifiers to man pages
2017-11-19 00:52:56 +08:00
man: use xinclude to de-deduplicate common text I only tested with python-lxml. I'm not sure if xml.etree should be deprecated.
2014-02-12 13:55:38 +08:00
<refsect1>
man: expand the documentation of $SYSTEMD_PAGER and related environment variables Document the default pagers used, as well as $SYSTEMD_LESSCHARSET. Fixes: #4143
2016-10-11 23:45:49 +08:00
<title>Environment</title>
<variablelist class='environment-variables'>
man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools.
2021-02-28 20:22:06 +08:00
<varlistentry id='log-level'>
<term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
man: reuse common-variables in systemd(1) This requires a bit of gimnastics, but I think it's still better than status quo ante, and better than duplicating the text.
2021-02-28 20:41:58 +08:00
<listitem><para id='log-level-body'>The maximum log level of emitted messages (messages with a higher
log level, i.e. less important ones, will be suppressed). Either one of (in order of decreasing
importance) <constant>emerg</constant>, <constant>alert</constant>, <constant>crit</constant>,
man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools.
2021-02-28 20:22:06 +08:00
<constant>err</constant>, <constant>warning</constant>, <constant>notice</constant>,
<constant>info</constant>, <constant>debug</constant>, or an integer in the range 0…7. See
<citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
for more information.</para>
</listitem>
</varlistentry>
<varlistentry id='log-color'>
<term><varname>$SYSTEMD_LOG_COLOR</varname></term>
man: reuse common-variables in systemd(1) This requires a bit of gimnastics, but I think it's still better than status quo ante, and better than duplicating the text.
2021-02-28 20:41:58 +08:00
<listitem><para id='log-color-body'>A boolean. If true, messages written to the tty will be colored
according to priority.</para>
man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools.
2021-02-28 20:22:06 +08:00
<para>This setting is only useful when messages are written directly to the terminal, because
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
other tools that display logs will color messages based on the log level on their own.</para>
</listitem>
</varlistentry>
<varlistentry id='log-time'>
<term><varname>$SYSTEMD_LOG_TIME</varname></term>
man: update docs on systemd-system.conf logging (LogTime=) (#19846) Updating documentation for systemd to reflect that logging is done in the console.
2021-06-08 14:54:07 +08:00
<listitem><para id='log-time-body'>A boolean. If true, console log messages will be prefixed with a
man: reuse common-variables in systemd(1) This requires a bit of gimnastics, but I think it's still better than status quo ante, and better than duplicating the text.
2021-02-28 20:41:58 +08:00
timestamp.</para>
man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools.
2021-02-28 20:22:06 +08:00
<para>This setting is only useful when messages are written directly to the terminal or a file, because
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
other tools that display logs will attach timestamps based on the entry metadata on their own.</para>
</listitem>
</varlistentry>
<varlistentry id='log-location'>
<term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
man: reuse common-variables in systemd(1) This requires a bit of gimnastics, but I think it's still better than status quo ante, and better than duplicating the text.
2021-02-28 20:41:58 +08:00
<listitem><para id='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.</para>
man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools.
2021-02-28 20:22:06 +08:00
<para>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.</para>
</listitem>
</varlistentry>
<varlistentry id='log-tid'>
<term><varname>$SYSTEMD_LOG_TID</varname></term>
man: reuse common-variables in systemd(1) This requires a bit of gimnastics, but I think it's still better than status quo ante, and better than duplicating the text.
2021-02-28 20:41:58 +08:00
<listitem><para id='log-tid-body'>A boolean. If true, messages will be prefixed with the current
numerical thread ID (TID).</para>
man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools.
2021-02-28 20:22:06 +08:00
<para>Note that the this information is attached as metadata to journal entries anyway. Including it
directly in the message text can nevertheless be convenient when debugging programs.</para>
</listitem>
</varlistentry>
<varlistentry id='log-target'>
<term><varname>$SYSTEMD_LOG_TARGET</varname></term>
man: reuse common-variables in systemd(1) This requires a bit of gimnastics, but I think it's still better than status quo ante, and better than duplicating the text.
2021-02-28 20:41:58 +08:00
<listitem><para id='log-target-body'>The destination for log messages. One of
<constant>console</constant> (log to the attached tty), <constant>console-prefixed</constant> (log to
the attached tty but with prefixes encoding the log level and "facility", see <citerefentry
man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools.
2021-02-28 20:22:06 +08:00
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
<constant>kmsg</constant> (log to the kernel circular log buffer), <constant>journal</constant> (log to
the journal), <constant>journal-or-kmsg</constant> (log to the journal if available, and to kmsg
tree-wide: fix typo
2021-03-02 13:13:34 +08:00
otherwise), <constant>auto</constant> (determine the appropriate log target automatically, the default),
man: describe various logging configuration variables Fixes #17484. This patch affects systemctl(1), as well as all man pages that include all of common-variables.xml, i.e. most of our command line tools.
2021-02-28 20:22:06 +08:00
<constant>null</constant> (disable log output).</para>
<!-- <constant>syslog</constant>, <constant>syslog-or-kmsg</constant> are deprecated -->
</listitem>
</varlistentry>
log: Add knob to disable kmsg ratelimiting This allows us to disable kmsg ratelimiting in the integration tests and mkosi for easier debugging.
2023-04-20 16:31:37 +08:00
<varlistentry id='log-ratelimit-kmsg'>
<term><varname>$SYSTEMD_LOG_RATELIMIT_KMSG</varname></term>
<listitem><para id='log-ratelimit-kmsg-body'> Whether to ratelimit kmsg or not. Takes a boolean.
Defaults to <literal>true</literal>. If disabled, systemd will not ratelimit messages written to kmsg.
</para></listitem>
</varlistentry>
man: expand the documentation of $SYSTEMD_PAGER and related environment variables Document the default pagers used, as well as $SYSTEMD_LESSCHARSET. Fixes: #4143
2016-10-11 23:45:49 +08:00
<varlistentry id='pager'>
<term><varname>$SYSTEMD_PAGER</varname></term>
<listitem><para>Pager to use when <option>--no-pager</option> is not given; overrides
<varname>$PAGER</varname>. If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a
set of well-known pager implementations are tried in turn, including
man: fix links to external man pages linkchecker ftw!
2017-05-07 23:29:40 +08:00
<citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
<citerefentry project='man-pages'><refentrytitle>more</refentrytitle><manvolnum>1</manvolnum></citerefentry>, until one is found. If
man: expand the documentation of $SYSTEMD_PAGER and related environment variables Document the default pagers used, as well as $SYSTEMD_LESSCHARSET. Fixes: #4143
2016-10-11 23:45:49 +08:00
no pager implementation is discovered no pager is invoked. Setting this environment variable to an empty string
man: note more clearly that $SYSTEMD_PAGER requires $SYSTEMD_PAGERSECURE
2022-01-22 22:49:54 +08:00
or the value <literal>cat</literal> is equivalent to passing <option>--no-pager</option>.</para>
<para>Note: if <varname>$SYSTEMD_PAGERSECURE</varname> is not set, <varname>$SYSTEMD_PAGER</varname>
(as well as <varname>$PAGER</varname>) will be silently ignored.</para></listitem>
man: expand the documentation of $SYSTEMD_PAGER and related environment variables Document the default pagers used, as well as $SYSTEMD_LESSCHARSET. Fixes: #4143
2016-10-11 23:45:49 +08:00
</varlistentry>
<varlistentry id='less'>
<term><varname>$SYSTEMD_LESS</varname></term>
<listitem><para>Override the options passed to <command>less</command> (by default
basic/pager: ignore ^C when piping to less and K is not set Normally, we want to immediately quit on ^C. But when we are running under less, people may set SYSTEMD_LESS without K, in which case they can use ^C to communicate with less, and e.g. start and stop following input. Fixes #6405.
2018-11-12 02:04:00 +08:00
<literal>FRSXMK</literal>).</para>
man: describe $LESS options more fully https://bugzilla.redhat.com/show_bug.cgi?id=1655316
2019-07-21 18:32:17 +08:00
<para>Users might want to change two options in particular:</para>
man: fix a few bogus entries in directives index When wrong element types are used, directives are sometimes placed in the wrong section. Also, strip part of text starting with "'", which is used in a few places and which is displayed improperly in the index.
2019-11-22 03:33:26 +08:00
<variablelist>
man: describe $LESS options more fully https://bugzilla.redhat.com/show_bug.cgi?id=1655316
2019-07-21 18:32:17 +08:00
<varlistentry>
<term><option>K</option></term>
<para>This option instructs the pager to exit immediately when
<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> is pressed. To allow
<command>less</command> to handle <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
itself to switch back to the pager command prompt, unset this option.</para>
<para>If the value of <varname>$SYSTEMD_LESS</varname> does not include <literal>K</literal>,
and the pager that is invoked is <command>less</command>,
<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> will be ignored by the
executable, and needs to be handled by the pager.</para>
</varlistentry>
<varlistentry>
<term><option>X</option></term>
<para>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.</para>
</varlistentry>
</variablelist>
<para>See
<citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for more discussion.</para></listitem>
man: expand the documentation of $SYSTEMD_PAGER and related environment variables Document the default pagers used, as well as $SYSTEMD_LESSCHARSET. Fixes: #4143
2016-10-11 23:45:49 +08:00
</varlistentry>
<varlistentry id='lesscharset'>
<term><varname>$SYSTEMD_LESSCHARSET</varname></term>
<listitem><para>Override the charset passed to <command>less</command> (by default <literal>utf-8</literal>, if
the invoking terminal is determined to be UTF-8 compatible).</para></listitem>
</varlistentry>
pager: set $LESSSECURE whenver we invoke a pager Some extra safety when invoked via "sudo". With this we address a genuine design flaw of sudo, and we shouldn't need to deal with this. But it's still a good idea to disable this surface given how exotic it is. Prompted by #5666
2020-09-01 01:37:13 +08:00
<varlistentry id='lesssecure'>
pager: make pager secure when under euid is changed or explicitly requested The variable is renamed to SYSTEMD_PAGERSECURE (because it's not just about less now), and we automatically enable secure mode in certain cases, but not otherwise. This approach is more nuanced, but should provide a better experience for users: - Previusly we would set LESSSECURE=1 and trust the pager to make use of it. But this has an effect only on less. We need to not start pagers which are insecure when in secure mode. In particular more is like that and is a very popular pager. - We don't enable secure mode always, which means that those other pagers can reasonably used. - We do the right thing by default, but the user has ultimate control by setting SYSTEMD_PAGERSECURE. Fixes #5666. v2: - also check $PKEXEC_UID v3: - use 'sd_pid_get_owner_uid() != geteuid()' as the condition
2020-10-07 17:15:05 +08:00
<term><varname>$SYSTEMD_PAGERSECURE</varname></term>
<listitem><para>Takes a boolean argument. When true, the "secure" mode of the pager is enabled; if
false, disabled. If <varname>$SYSTEMD_PAGERSECURE</varname> is not set at all, secure mode is enabled
man: fix links to various pages nss-dns doesn't have any man page that I could find.
2021-02-19 16:10:15 +08:00
if the effective UID is not the same as the owner of the login session, see
<citerefentry project='man-pages'><refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
and <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
pager: make pager secure when under euid is changed or explicitly requested The variable is renamed to SYSTEMD_PAGERSECURE (because it's not just about less now), and we automatically enable secure mode in certain cases, but not otherwise. This approach is more nuanced, but should provide a better experience for users: - Previusly we would set LESSSECURE=1 and trust the pager to make use of it. But this has an effect only on less. We need to not start pagers which are insecure when in secure mode. In particular more is like that and is a very popular pager. - We don't enable secure mode always, which means that those other pagers can reasonably used. - We do the right thing by default, but the user has ultimate control by setting SYSTEMD_PAGERSECURE. Fixes #5666. v2: - also check $PKEXEC_UID v3: - use 'sd_pid_get_owner_uid() != geteuid()' as the condition
2020-10-07 17:15:05 +08:00
In secure mode, <option>LESSSECURE=1</option> will be set when invoking the pager, and the pager shall
disable commands that open or create new files or start new subprocesses. When
<varname>$SYSTEMD_PAGERSECURE</varname> is not set at all, pagers which are not known to implement
secure mode will not be used. (Currently only
man: fix links to various pages nss-dns doesn't have any man page that I could find.
2021-02-19 16:10:15 +08:00
<citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
implements secure mode.)</para>
pager: make pager secure when under euid is changed or explicitly requested The variable is renamed to SYSTEMD_PAGERSECURE (because it's not just about less now), and we automatically enable secure mode in certain cases, but not otherwise. This approach is more nuanced, but should provide a better experience for users: - Previusly we would set LESSSECURE=1 and trust the pager to make use of it. But this has an effect only on less. We need to not start pagers which are insecure when in secure mode. In particular more is like that and is a very popular pager. - We don't enable secure mode always, which means that those other pagers can reasonably used. - We do the right thing by default, but the user has ultimate control by setting SYSTEMD_PAGERSECURE. Fixes #5666. v2: - also check $PKEXEC_UID v3: - use 'sd_pid_get_owner_uid() != geteuid()' as the condition
2020-10-07 17:15:05 +08:00
<para>Note: when commands are invoked with elevated privileges, for example under <citerefentry
project='man-pages'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry> or
<citerefentry
project='die-net'><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>, 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 <varname>SYSTEMD_PAGERSECURE=0</varname>
or not removing it from the inherited environment allows the user to invoke arbitrary commands. Note
that if the <varname>$SYSTEMD_PAGER</varname> or <varname>$PAGER</varname> variables are to be
tree-wide: fix typos found by Fossies codespell report
2020-10-24 11:07:19 +08:00
honoured, <varname>$SYSTEMD_PAGERSECURE</varname> must be set too. It might be reasonable to completely
pager: make pager secure when under euid is changed or explicitly requested The variable is renamed to SYSTEMD_PAGERSECURE (because it's not just about less now), and we automatically enable secure mode in certain cases, but not otherwise. This approach is more nuanced, but should provide a better experience for users: - Previusly we would set LESSSECURE=1 and trust the pager to make use of it. But this has an effect only on less. We need to not start pagers which are insecure when in secure mode. In particular more is like that and is a very popular pager. - We don't enable secure mode always, which means that those other pagers can reasonably used. - We do the right thing by default, but the user has ultimate control by setting SYSTEMD_PAGERSECURE. Fixes #5666. v2: - also check $PKEXEC_UID v3: - use 'sd_pid_get_owner_uid() != geteuid()' as the condition
2020-10-07 17:15:05 +08:00
disable the pager using <option>--no-pager</option> instead.</para></listitem>
pager: set $LESSSECURE whenver we invoke a pager Some extra safety when invoked via "sudo". With this we address a genuine design flaw of sudo, and we shouldn't need to deal with this. But it's still a good idea to disable this surface given how exotic it is. Prompted by #5666
2020-09-01 01:37:13 +08:00
</varlistentry>
man: share description of $SYSTEMD_COLORS in other tools It was only described in systemd(1), making it hard to discover. Fixes #13561. The same for $SYSTEMD_URLIFY. I think all the tools whose man pages include less-variables.xml support those variables.
2019-11-15 18:59:34 +08:00
<varlistentry id='colors'>
<term><varname>$SYSTEMD_COLORS</varname></term>
basic/term-util: extend $SYSTEMD_COLORS This commit extends $SYSTEMD_COLORS to an enum variable (compared to a simple boolean) which specifies the "colors mode". This means that, in addition to disabling colors altogether, it's now possible to restrict the console output to 16 or 256 colors only.
2020-11-22 09:37:27 +08:00
<listitem><para>Takes a boolean argument. When true, <command>systemd</command> 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: <literal>16</literal>, <literal>256</literal> 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 <varname>$TERM</varname> and what the console is connected to.</para></listitem>
man: share description of $SYSTEMD_COLORS in other tools It was only described in systemd(1), making it hard to discover. Fixes #13561. The same for $SYSTEMD_URLIFY. I think all the tools whose man pages include less-variables.xml support those variables.
2019-11-15 18:59:34 +08:00
</varlistentry>
basic/terminal-util: add support for $NO_COLOR See inline comments. Fixes #13752.
2019-11-24 20:59:22 +08:00
<!-- This is not documented on purpose, because it is not clear if $NO_COLOR will become supported
widely enough. So let's provide support, but without advertising this.
<varlistentry id='no-color'>
<term><varname>$NO_COLOR</varname></term>
<listitem><para>If set (to any value), and <varname>$SYSTEMD_COLORS</varname> is not set, equivalent to
<option>SYSTEMD_COLORS=0</option>. See <ulink url="https://no-color.org/">no-color.org</ulink>.</para>
</listitem>
</varlistentry>
-->
man: share description of $SYSTEMD_COLORS in other tools It was only described in systemd(1), making it hard to discover. Fixes #13561. The same for $SYSTEMD_URLIFY. I think all the tools whose man pages include less-variables.xml support those variables.
2019-11-15 18:59:34 +08:00
<varlistentry id='urlify'>
<term><varname>$SYSTEMD_URLIFY</varname></term>
<listitem><para>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
<command>systemd</command> makes based on <varname>$TERM</varname> and other conditions.</para>
</listitem>
</varlistentry>
</variablelist>
man: use xinclude to de-deduplicate common text I only tested with python-lxml. I'm not sure if xml.etree should be deprecated.
2014-02-12 13:55:38 +08:00
</refsect1>
Reference in New Issue Copy Permalink