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