255 lines
14 KiB
XML
255 lines
14 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE refsect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<variablelist class='environment-variables'>
|
|
<varlistentry id='log-level'>
|
|
<term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
|
|
|
|
<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). Takes a comma-separated list of values. A
|
|
value may be either one of (in order of decreasing importance) <constant>emerg</constant>,
|
|
<constant>alert</constant>, <constant>crit</constant>, <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. Each value may optionally be prefixed with one of <constant>console</constant>,
|
|
<constant>syslog</constant>, <constant>kmsg</constant> or <constant>journal</constant> followed by a
|
|
colon to set the maximum log level for that specific log target (e.g.
|
|
<constant>SYSTEMD_LOG_LEVEL=debug,console:info</constant> 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.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id='log-color'>
|
|
<term><varname>$SYSTEMD_LOG_COLOR</varname></term>
|
|
|
|
<listitem><para id='log-color-body'>A boolean. If true, messages written to the tty will be colored
|
|
according to priority.</para>
|
|
|
|
<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>
|
|
|
|
<listitem><para id='log-time-body'>A boolean. If true, console log messages will be prefixed with a
|
|
timestamp.</para>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
<listitem><para id='log-tid-body'>A boolean. If true, messages will be prefixed with the current
|
|
numerical thread ID (TID).</para>
|
|
|
|
<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>
|
|
|
|
<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
|
|
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
|
|
otherwise), <constant>auto</constant> (determine the appropriate log target automatically, the default),
|
|
<constant>null</constant> (disable log output).</para>
|
|
<!-- <constant>syslog</constant>, <constant>syslog-or-kmsg</constant> are deprecated -->
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<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>
|
|
|
|
<varlistentry id='pager'>
|
|
<term><varname>$SYSTEMD_PAGER</varname></term>
|
|
<term><varname>$PAGER</varname></term>
|
|
|
|
<listitem><para>Pager to use when <option>--no-pager</option> is not given.
|
|
<varname>$SYSTEMD_PAGER</varname> is used if set; otherwise <varname>$PAGER</varname> is used.
|
|
If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a set of well-known
|
|
pager implementations is tried in turn, including
|
|
<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 no pager implementation is discovered, no pager is invoked. Setting those
|
|
environment variables to an empty string 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>
|
|
and <varname>$PAGER</varname> can only be used to disable the pager (with <literal>cat</literal> or
|
|
<literal></literal>), and are otherwise ignored.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id='less'>
|
|
<term><varname>$SYSTEMD_LESS</varname></term>
|
|
|
|
<listitem><para>Override the options passed to <command>less</command> (by default
|
|
<literal>FRSXMK</literal>).</para>
|
|
|
|
<para>Users might want to change two options in particular:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><option>K</option></term>
|
|
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>X</option></term>
|
|
|
|
<listitem>
|
|
<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>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>Note that setting the regular <varname>$LESS</varname> environment variable has no effect
|
|
for <command>less</command> invocations by systemd tools.</para>
|
|
|
|
<para>See
|
|
<citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
|
for more discussion.</para></listitem>
|
|
</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>
|
|
|
|
<para>Note that setting the regular <varname>$LESSCHARSET</varname> environment variable has no effect
|
|
for <command>less</command> invocations by systemd tools.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id='lesssecure'>
|
|
<term><varname>$SYSTEMD_PAGERSECURE</varname></term>
|
|
|
|
<listitem>
|
|
<para>Common pager commands like <citerefentry
|
|
project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>, in
|
|
addition to "paging", i.e. scrolling through the output, support opening of or writing to other files
|
|
and running arbitrary shell commands. 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>, the
|
|
pager becomes a security boundary. Care must be taken that only programs with strictly limited
|
|
functionality are used as pagers, and unintended interactive features like opening or creation of new
|
|
files or starting of subprocesses are not allowed. "Secure mode" for the pager may be enabled as
|
|
described below, <emphasis>if the pager supports that</emphasis> (most pagers are not written in a way
|
|
that takes this into consideration). It is recommended to either explicitly enable "secure mode" or to
|
|
completely disable the pager using <option>--no-pager</option> or <varname>PAGER=cat</varname> when
|
|
allowing untrusted users to execute commands with elevated privileges.</para>
|
|
|
|
<para>This option takes a boolean argument. When set to true, the "secure mode" of the pager is
|
|
enabled. In "secure mode", <option>LESSSECURE=1</option> will be set when invoking the pager, which
|
|
instructs the pager to disable commands that open or create new files or start new subprocesses.
|
|
Currently only <citerefentry
|
|
project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> is known
|
|
to understand this variable and implement "secure mode".</para>
|
|
|
|
<para>When set to false, no limitation is placed on the pager. Setting
|
|
<varname>SYSTEMD_PAGERSECURE=0</varname> or not removing it from the inherited environment may allow
|
|
the user to invoke arbitrary commands.</para>
|
|
|
|
<para>When <varname>$SYSTEMD_PAGERSECURE</varname> is not set, systemd tools attempt to automatically
|
|
figure out if "secure mode" should be enabled and whether the pager supports it. "Secure mode" is
|
|
enabled 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>,
|
|
or when running under
|
|
<citerefentry><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry> or similar
|
|
tools (<varname>$SUDO_UID</varname> is set <footnote>
|
|
<para>It is recommended for other tools to set and check <varname>$SUDO_UID</varname> as appropriate,
|
|
treating it is a common interface.</para></footnote>). In those cases,
|
|
<varname>SYSTEMD_PAGERSECURE=1</varname> will be set and pagers which are not known to implement
|
|
"secure mode" will not be used at all. Note that this autodetection only covers the most common
|
|
mechanisms to elevate privileges and is intended as convenience. It is recommended to explicitly set
|
|
<varname>$SYSTEMD_PAGERSECURE</varname> or disable the pager.</para>
|
|
|
|
<para>Note that if the <varname>$SYSTEMD_PAGER</varname> or <varname>$PAGER</varname> variables are to
|
|
be honoured, other than to disable the pager, <varname>$SYSTEMD_PAGERSECURE</varname> must be set
|
|
too.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id='colors'>
|
|
<term><varname>$SYSTEMD_COLORS</varname></term>
|
|
|
|
<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>
|
|
</varlistentry>
|
|
|
|
<!-- 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>
|
|
-->
|
|
|
|
<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>
|
|
</refsect1>
|