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">
7 <holder>Collabora Ltd.</holder>
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>
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>
24 <refname>dbus-update-activation-environment</refname>
25 <refpurpose>update environment used for D-Bus session services</refpurpose>
28 <refsynopsisdiv id="synopsis">
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>
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>
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>
58 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
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>
69 <refsect1 id="options">
70 <title>OPTIONS</title>
71 <variablelist remap="TP">
74 <term><option>--all</option></term>
76 <para>Set all environment variables present in
77 the environment used by
78 <command>dbus-update-activation-environment</command>.
84 <term><option>--systemd</option></term>
86 <para>Set environment variables for systemd user services as well as
87 for traditional D-Bus session services.</para>
92 <term><option>--verbose</option></term>
94 <para>Output messages to standard error explaining what
95 dbus-update-activation-environment is doing.</para>
100 <term><replaceable>VAR</replaceable></term>
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.
113 <term><replaceable>VAR</replaceable>=<replaceable>VAL</replaceable></term>
115 <para>Set <replaceable>VAR</replaceable> to <replaceable>VAL</replaceable>,
116 which must be UTF-8.</para>
123 <refsect1 id="examples">
124 <title>EXAMPLES</title>
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.
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
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
155 dbus-update-activation-environment --systemd --all
161 <refsect1 id="exit_status">
162 <title>EXIT STATUS</title>
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>
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>
179 <refsect1 id="limitations">
180 <title>LIMITATIONS</title>
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.
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.
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>
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>