doc/dbus-update-activation-environment.1.xml.in

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
   3 <refentry id="dbus-update-activation-environment.1">
   4   <refentryinfo>
   5     <copyright>
   6       <year>2015</year>
   7       <holder>Collabora Ltd.</holder>
   8     </copyright>
   9     <legalnotice>
  10       <para>This man page is distributed under the same terms as
  11         dbus-update-activation-environment (MIT/X11). There is NO WARRANTY,
  12         to the extent permitted by law.</para>
  13     </legalnotice>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>dbus-update-activation-environment</refentrytitle>
  18     <manvolnum>1</manvolnum>
  19     <refmiscinfo class="manual">User Commands</refmiscinfo>
  20     <refmiscinfo class="source">D-Bus</refmiscinfo>
  21     <refmiscinfo class="version">@DBUS_VERSION@</refmiscinfo>
  22   </refmeta>
  23   <refnamediv>
  24     <refname>dbus-update-activation-environment</refname>
  25     <refpurpose>update environment used for D-Bus session services</refpurpose>
  26   </refnamediv>
  27
  28   <refsynopsisdiv id="synopsis">
  29     <cmdsynopsis>
  30       <command>dbus-update-activation-environment</command>
  31       <arg choice="opt">--systemd</arg>
  32       <arg choice="opt">--verbose</arg>
  33       <group choice="plain">
  34         <arg choice="plain">--all</arg>
  35         <arg choice="plain" rep="repeat"><replaceable>VAR</replaceable></arg>
  36         <arg choice="plain" rep="repeat"><replaceable>VAR</replaceable>=<replaceable>VAL</replaceable></arg>
  37       </group>
  38     </cmdsynopsis>
  39   </refsynopsisdiv>
  40
  41   <refsect1 id="description">
  42     <title>DESCRIPTION</title>
  43     <para><command>dbus-update-activation-environment</command>
  44       updates the list of environment variables used by
  45       <command>dbus-daemon --session</command>
  46       when it activates session services without using
  47       <command>systemd</command>.</para>
  48
  49     <para>With the <option>--systemd</option> option,
  50       if an instance of <command>systemd --user</command> is
  51       available on D-Bus, it also updates the list of environment variables
  52       used by <command>systemd --user</command>
  53       when it activates user services, including D-Bus session services
  54       for which <command>dbus-daemon</command> has been configured to
  55       delegate activation to <command>systemd</command>.
  56       This is very similar to the <option>import-environment</option>
  57       command provided by
  58       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
  59
  60     <para>Variables that are special to <command>dbus-daemon</command>
  61       or <command>systemd</command> may be set, but their values will
  62       be overridden when a service is started. For instance, it is
  63       not useful to add <envar>DBUS_SESSION_BUS_ADDRESS</envar> to
  64       <command>dbus-daemon</command>'s activation environment,
  65       although it might still be useful to add it to
  66       <command>systemd</command>'s activation environment.</para>
  67   </refsect1>
  68
  69   <refsect1 id="options">
  70     <title>OPTIONS</title>
  71     <variablelist remap="TP">
  72
  73       <varlistentry>
  74         <term><option>--all</option></term>
  75         <listitem>
  76           <para>Set all environment variables present in
  77             the environment used by
  78             <command>dbus-update-activation-environment</command>.
  79           </para>
  80         </listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term><option>--systemd</option></term>
  85         <listitem>
  86           <para>Set environment variables for systemd user services as well as
  87             for traditional D-Bus session services.</para>
  88         </listitem>
  89       </varlistentry>
  90
  91       <varlistentry>
  92         <term><option>--verbose</option></term>
  93         <listitem>
  94           <para>Output messages to standard error explaining what
  95             dbus-update-activation-environment is doing.</para>
  96         </listitem>
  97       </varlistentry>
  98
  99       <varlistentry>
 100         <term><replaceable>VAR</replaceable></term>
 101         <listitem>
 102           <para>If <replaceable>VAR</replaceable> is present in the
 103             environment of <command>dbus-update-activation-environment</command>,
 104             set it to the same value for D-Bus services. Its value must be
 105             UTF-8 (if not, it is skipped with a warning). If
 106             <replaceable>VAR</replaceable> is not present
 107             in the environment, this argument is silently ignored.
 108           </para>
 109         </listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term><replaceable>VAR</replaceable>=<replaceable>VAL</replaceable></term>
 114         <listitem>
 115           <para>Set <replaceable>VAR</replaceable> to <replaceable>VAL</replaceable>,
 116             which must be UTF-8.</para>
 117         </listitem>
 118       </varlistentry>
 119
 120     </variablelist>
 121   </refsect1>
 122
 123   <refsect1 id="examples">
 124     <title>EXAMPLES</title>
 125     <para>
 126       <command>dbus-update-activation-environment</command> is
 127       primarily designed to be used in Linux distributions' X11 session
 128       startup scripts, in conjunction with the "user bus" design.
 129     </para>
 130
 131     <para>To propagate <envar>DISPLAY</envar> and <envar>XAUTHORITY</envar>
 132       to <command>dbus-daemon</command>
 133       and, if present, <command>systemd</command>,
 134       and propagate <envar>DBUS_SESSION_BUS_ADDRESS</envar> to
 135       <command>systemd</command>:
 136       <programlisting language="sh">
 137         dbus-update-activation-environment --systemd \
 138             DBUS_SESSION_BUS_ADDRESS DISPLAY XAUTHORITY
 139       </programlisting>
 140     </para>
 141
 142     <para>To propagate all environment variables except
 143       <envar>XDG_SEAT</envar>, <envar>XDG_SESSION_ID</envar>
 144       and <envar>XDG_VTNR</envar> to <command>dbus-daemon</command>
 145       (and, if present, <command>systemd</command>) for compatibility
 146       with legacy X11 session startup scripts:
 147       <programlisting language="sh">
 148         # in a subshell so the variables remain set in the
 149         # parent script
 150         (
 151           unset XDG_SEAT
 152           unset XDG_SESSION_ID
 153           unset XDG_VTNR
 154
 155           dbus-update-activation-environment --systemd --all
 156         )
 157       </programlisting>
 158     </para>
 159   </refsect1>
 160
 161   <refsect1 id="exit_status">
 162     <title>EXIT STATUS</title>
 163     <para>
 164       <command>dbus-update-activation-environment</command>
 165       exits with status 0 on success, EX_USAGE (64) on invalid
 166       command-line options, EX_OSERR (71) if unable to connect
 167       to the session bus, or EX_UNAVAILABLE (69) if unable to
 168       set the environment variables. Other nonzero exit codes might be
 169       added in future versions.</para>
 170   </refsect1>
 171
 172   <refsect1 id="environment">
 173     <title>ENVIRONMENT</title>
 174       <para><envar>DBUS_SESSION_BUS_ADDRESS</envar>,
 175         <envar>XDG_RUNTIME_DIR</envar> and/or <envar>DISPLAY</envar>
 176         are used to find the address of the session bus.</para>
 177   </refsect1>
 178
 179   <refsect1 id="limitations">
 180     <title>LIMITATIONS</title>
 181     <para>
 182       <command>dbus-daemon</command> does not provide a way to unset
 183       environment variables after they have been set (although
 184       <command>systemd</command> does), so
 185       <command>dbus-update-activation-environment</command> does not
 186       offer this functionality either.
 187     </para>
 188
 189     <para>
 190       POSIX does not specify the encoding of non-ASCII environment variable
 191       names or values and allows them to contain any non-zero byte, but
 192       neither <command>dbus-daemon</command> nor <command>systemd</command>
 193       supports environment variables with non-UTF-8 names or values.
 194       Accordingly, <command>dbus-update-activation-environment</command>
 195       assumes that any name or value that appears to be valid UTF-8 is
 196       intended to be UTF-8, and ignores other names or values with a warning.
 197     </para>
 198   </refsect1>
 199
 200   <refsect1 id="bugs">
 201     <title>BUGS</title>
 202       <para>Please send bug reports to the D-Bus bug tracker or mailing list.
 203         See <ulink url="http://www.freedesktop.org/software/dbus/">http://www.freedesktop.org/software/dbus/</ulink>.</para>
 204   </refsect1>
 205
 206   <refsect1 id="see_also">
 207     <title>SEE ALSO</title>
 208     <para><citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 209       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 210       the <option>import-environment</option> command of
 211       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
 212   </refsect1>
 213 </refentry>