man/common-variables.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refsect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refsect1>
   7   <title>Environment</title>
   8
   9   <variablelist class='environment-variables'>
  10     <varlistentry id='log-level'>
  11       <term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
  12
  13       <listitem><para id='log-level-body'>The maximum log level of emitted messages (messages with a higher
  14       log level, i.e. less important ones, will be suppressed). Takes a comma-separated list of values. A
  15       value may be either one of (in order of decreasing importance) <constant>emerg</constant>,
  16       <constant>alert</constant>, <constant>crit</constant>, <constant>err</constant>,
  17       <constant>warning</constant>, <constant>notice</constant>, <constant>info</constant>,
  18       <constant>debug</constant>, or an integer in the range 0…7. See
  19       <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
  20       for more information. Each value may optionally be prefixed with one of <constant>console</constant>,
  21       <constant>syslog</constant>, <constant>kmsg</constant> or <constant>journal</constant> followed by a
  22       colon to set the maximum log level for that specific log target (e.g.
  23       <constant>SYSTEMD_LOG_LEVEL=debug,console:info</constant> specifies to log at debug level except when
  24       logging to the console which should be at info level). Note that the global maximum log level takes
  25       priority over any per target maximum log levels.</para></listitem>
  26     </varlistentry>
  27
  28     <varlistentry id='log-color'>
  29       <term><varname>$SYSTEMD_LOG_COLOR</varname></term>
  30
  31       <listitem><para id='log-color-body'>A boolean. If true, messages written to the tty will be colored
  32       according to priority.</para>
  33
  34       <para>This setting is only useful when messages are written directly to the terminal, because
  35       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
  36       other tools that display logs will color messages based on the log level on their own.</para>
  37       </listitem>
  38     </varlistentry>
  39
  40     <varlistentry id='log-time'>
  41       <term><varname>$SYSTEMD_LOG_TIME</varname></term>
  42
  43       <listitem><para id='log-time-body'>A boolean. If true, console log messages will be prefixed with a
  44       timestamp.</para>
  45
  46       <para>This setting is only useful when messages are written directly to the terminal or a file, because
  47       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
  48       other tools that display logs will attach timestamps based on the entry metadata on their own.</para>
  49       </listitem>
  50     </varlistentry>
  51
  52     <varlistentry id='log-location'>
  53       <term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
  54
  55       <listitem><para id='log-location-body'>A boolean. If true, messages will be prefixed with a filename
  56       and line number in the source code where the message originates.</para>
  57
  58       <para>Note that the log location is often attached as metadata to journal entries anyway. Including it
  59       directly in the message text can nevertheless be convenient when debugging programs.</para>
  60       </listitem>
  61     </varlistentry>
  62
  63     <varlistentry id='log-tid'>
  64       <term><varname>$SYSTEMD_LOG_TID</varname></term>
  65
  66       <listitem><para id='log-tid-body'>A boolean. If true, messages will be prefixed with the current
  67       numerical thread ID (TID).</para>
  68
  69       <para>Note that the this information is attached as metadata to journal entries anyway. Including it
  70       directly in the message text can nevertheless be convenient when debugging programs.</para>
  71       </listitem>
  72     </varlistentry>
  73
  74     <varlistentry id='log-target'>
  75       <term><varname>$SYSTEMD_LOG_TARGET</varname></term>
  76
  77       <listitem><para id='log-target-body'>The destination for log messages. One of
  78       <constant>console</constant> (log to the attached tty), <constant>console-prefixed</constant> (log to
  79       the attached tty but with prefixes encoding the log level and "facility", see <citerefentry
  80       project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
  81       <constant>kmsg</constant> (log to the kernel circular log buffer), <constant>journal</constant> (log to
  82       the journal), <constant>journal-or-kmsg</constant> (log to the journal if available, and to kmsg
  83       otherwise), <constant>auto</constant> (determine the appropriate log target automatically, the default),
  84       <constant>null</constant> (disable log output).</para>
  85       <!-- <constant>syslog</constant>, <constant>syslog-or-kmsg</constant> are deprecated -->
  86       </listitem>
  87     </varlistentry>
  88
  89     <varlistentry id='log-ratelimit-kmsg'>
  90       <term><varname>$SYSTEMD_LOG_RATELIMIT_KMSG</varname></term>
  91
  92       <listitem><para id='log-ratelimit-kmsg-body'> Whether to ratelimit kmsg or not. Takes a boolean.
  93       Defaults to <literal>true</literal>. If disabled, systemd will not ratelimit messages written to kmsg.
  94       </para></listitem>
  95     </varlistentry>
  96
  97     <varlistentry id='pager'>
  98       <term><varname>$SYSTEMD_PAGER</varname></term>
  99
 100       <listitem><para>Pager to use when <option>--no-pager</option> is not given; overrides
 101       <varname>$PAGER</varname>. If neither <varname>$SYSTEMD_PAGER</varname> nor <varname>$PAGER</varname> are set, a
 102       set of well-known pager implementations are tried in turn, including
 103       <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry> and
 104       <citerefentry project='man-pages'><refentrytitle>more</refentrytitle><manvolnum>1</manvolnum></citerefentry>, until one is found. If
 105       no pager implementation is discovered no pager is invoked. Setting this environment variable to an empty string
 106       or the value <literal>cat</literal> is equivalent to passing <option>--no-pager</option>.</para>
 107
 108       <para>Note: if <varname>$SYSTEMD_PAGERSECURE</varname> is not set, <varname>$SYSTEMD_PAGER</varname>
 109       (as well as <varname>$PAGER</varname>) will be silently ignored.</para></listitem>
 110     </varlistentry>
 111
 112     <varlistentry id='less'>
 113       <term><varname>$SYSTEMD_LESS</varname></term>
 114
 115       <listitem><para>Override the options passed to <command>less</command> (by default
 116       <literal>FRSXMK</literal>).</para>
 117
 118       <para>Users might want to change two options in particular:</para>
 119
 120       <variablelist>
 121         <varlistentry>
 122           <term><option>K</option></term>
 123
 124           <listitem>
 125             <para>This option instructs the pager to exit immediately when
 126             <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> is pressed. To allow
 127             <command>less</command> to handle <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
 128             itself to switch back to the pager command prompt, unset this option.</para>
 129
 130             <para>If the value of <varname>$SYSTEMD_LESS</varname> does not include <literal>K</literal>,
 131             and the pager that is invoked is <command>less</command>,
 132             <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> will be ignored by the
 133             executable, and needs to be handled by the pager.</para>
 134           </listitem>
 135         </varlistentry>
 136
 137         <varlistentry>
 138           <term><option>X</option></term>
 139
 140           <listitem>
 141             <para>This option instructs the pager to not send termcap initialization and deinitialization
 142             strings to the terminal. It is set by default to allow command output to remain visible in the
 143             terminal even after the pager exits. Nevertheless, this prevents some pager functionality from
 144             working, in particular paged output cannot be scrolled with the mouse.</para>
 145         </listitem>
 146         </varlistentry>
 147       </variablelist>
 148
 149       <para>See
 150       <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 151       for more discussion.</para></listitem>
 152     </varlistentry>
 153
 154     <varlistentry id='lesscharset'>
 155       <term><varname>$SYSTEMD_LESSCHARSET</varname></term>
 156
 157       <listitem><para>Override the charset passed to <command>less</command> (by default <literal>utf-8</literal>, if
 158       the invoking terminal is determined to be UTF-8 compatible).</para></listitem>
 159     </varlistentry>
 160
 161     <varlistentry id='lesssecure'>
 162       <term><varname>$SYSTEMD_PAGERSECURE</varname></term>
 163
 164       <listitem><para>Takes a boolean argument. When true, the "secure" mode of the pager is enabled; if
 165       false, disabled. If <varname>$SYSTEMD_PAGERSECURE</varname> is not set at all, secure mode is enabled
 166       if the effective UID is not the same as the owner of the login session, see
 167       <citerefentry project='man-pages'><refentrytitle>geteuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>
 168       and <citerefentry><refentrytitle>sd_pid_get_owner_uid</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 169       In secure mode, <option>LESSSECURE=1</option> will be set when invoking the pager, and the pager shall
 170       disable commands that open or create new files or start new subprocesses. When
 171       <varname>$SYSTEMD_PAGERSECURE</varname> is not set at all, pagers which are not known to implement
 172       secure mode will not be used. (Currently only
 173       <citerefentry project='man-pages'><refentrytitle>less</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 174       implements secure mode.)</para>
 175
 176       <para>Note: when commands are invoked with elevated privileges, for example under <citerefentry
 177       project='man-pages'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry> or
 178       <citerefentry
 179       project='die-net'><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry>, care
 180       must be taken to ensure that unintended interactive features are not enabled. "Secure" mode for the
 181       pager may be enabled automatically as describe above. Setting <varname>SYSTEMD_PAGERSECURE=0</varname>
 182       or not removing it from the inherited environment allows the user to invoke arbitrary commands. Note
 183       that if the <varname>$SYSTEMD_PAGER</varname> or <varname>$PAGER</varname> variables are to be
 184       honoured, <varname>$SYSTEMD_PAGERSECURE</varname> must be set too. It might be reasonable to completely
 185       disable the pager using <option>--no-pager</option> instead.</para></listitem>
 186     </varlistentry>
 187
 188     <varlistentry id='colors'>
 189       <term><varname>$SYSTEMD_COLORS</varname></term>
 190
 191       <listitem><para>Takes a boolean argument. When true, <command>systemd</command> and related utilities
 192       will use colors in their output, otherwise the output will be monochrome. Additionally, the variable can
 193       take one of the following special values: <literal>16</literal>, <literal>256</literal> to restrict the use
 194       of colors to the base 16 or 256 ANSI colors, respectively. This can be specified to override the automatic
 195       decision based on <varname>$TERM</varname> and what the console is connected to.</para></listitem>
 196     </varlistentry>
 197
 198     <!-- This is not documented on purpose, because it is not clear if $NO_COLOR will become supported
 199          widely enough. So let's provide support, but without advertising this.
 200     <varlistentry id='no-color'>
 201       <term><varname>$NO_COLOR</varname></term>
 202
 203       <listitem><para>If set (to any value), and <varname>$SYSTEMD_COLORS</varname> is not set, equivalent to
 204       <option>SYSTEMD_COLORS=0</option>. See <ulink url="https://no-color.org/">no-color.org</ulink>.</para>
 205       </listitem>
 206     </varlistentry>
 207     -->
 208
 209     <varlistentry id='urlify'>
 210       <term><varname>$SYSTEMD_URLIFY</varname></term>
 211
 212       <listitem><para>The value must be a boolean. Controls whether clickable links should be generated in
 213       the output for terminal emulators supporting this. This can be specified to override the decision that
 214       <command>systemd</command> makes based on <varname>$TERM</varname> and other conditions.</para>
 215       </listitem>
 216     </varlistentry>
 217
 218   </variablelist>
 219 </refsect1>