]>
Commit | Line | Data |
---|---|---|
3031660c ZJS |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > | |
4 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> | |
5 | ||
6 | <refentry id="org.freedesktop.systemd1" xmlns:xi="http://www.w3.org/2001/XInclude"> | |
7 | <refentryinfo> | |
8 | <title>org.freedesktop.systemd1</title> | |
9 | <productname>systemd</productname> | |
10 | </refentryinfo> | |
11 | ||
12 | <refmeta> | |
13 | <refentrytitle>org.freedesktop.systemd1</refentrytitle> | |
14 | <manvolnum>5</manvolnum> | |
15 | </refmeta> | |
16 | ||
17 | <refnamediv> | |
18 | <refname>org.freedesktop.systemd1</refname> | |
19 | <refpurpose>The D-Bus interface of systemd-systemdd</refpurpose> | |
20 | </refnamediv> | |
21 | ||
22 | <refsect1> | |
23 | <title>Introduction</title> | |
24 | ||
25 | <para> | |
26 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> and its | |
27 | auxiliary daemons expose a number of APIs over D-Bus. This page describes the various APIs exposed by the | |
28 | system and service manager itself, and does not cover the auxiliary daemons. | |
29 | </para> | |
30 | ||
31 | <para>The service manager exposes a number of objects on the bus: one | |
32 | <interfacename>Manager</interfacename> object as central entry point for clients, and individual objects | |
33 | for each unit and for each queued job. The unit objects each implement a generic | |
34 | <interfacename>Unit</interfacename> interface plus a type-specific interface. For example, service units | |
35 | implement <interfacename>org.freedesktop.systemd1.Unit</interfacename> as well as | |
36 | <interfacename>org.freedesktop.system1.Service</interfacename>. The manager object can be used to list | |
37 | unit and job objects, or to directly convert a unit name or job id into a bus path of the corresponding | |
38 | D-Bus object.</para> | |
39 | ||
40 | <para>Properties exposing time values are usually encoded in microseconds (usec) on the bus, even if | |
41 | their corresponding settings in the unit files are in seconds.</para> | |
42 | ||
43 | <para>In contrast to most of the other services of the systemd suite PID 1 does not use PolicyKit for | |
44 | controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy | |
45 | language. (This is done in order to avoid a cyclic dependency between PolicyKit and systemd/PID 1.) This | |
46 | means that sensitive operations exposed by PID 1 on the bus are generally not available to unprivileged | |
47 | processes directly. However some (such as shutdown/reboot/suspend) are made available through the D-Bus | |
48 | API of logind, see | |
49 | <citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>5</manvolnum></citerefentry>. | |
50 | </para> | |
51 | </refsect1> | |
52 | ||
53 | <refsect1> | |
54 | <title>The Manager Object</title> | |
55 | ||
56 | <para>The main entry point object is available on the fixed | |
57 | <constant>/org/freedesktop/systemd1</constant> object path:</para> | |
58 | ||
59 | <programlisting> | |
60 | $ gdbus introspect --system \ | |
61 | --dest org.freedesktop.systemd1 \ | |
62 | --object-path /org/freedesktop/systemd1 | |
63 | ||
64 | node /org/freedesktop/systemd1 { | |
65 | interface org.freedesktop.systemd1.Manager { | |
66 | methods: | |
67 | GetUnit(in s name, | |
68 | out o unit); | |
69 | GetUnitByPID(in u pid, | |
70 | out o unit); | |
71 | LoadUnit(in s name, | |
72 | out o unit); | |
73 | StartUnit(in s name, | |
74 | in s mode, | |
75 | out o job); | |
76 | StartUnitReplace(in s old_unit, | |
77 | in s new_unit, | |
78 | in s mode, | |
79 | out o job); | |
80 | StopUnit(in s name, | |
81 | in s mode, | |
82 | out o job); | |
83 | ReloadUnit(in s name, | |
84 | in s mode, | |
85 | out o job); | |
86 | RestartUnit(in s name, | |
87 | in s mode, | |
88 | out o job); | |
89 | TryRestartUnit(in s name, | |
90 | in s mode, | |
91 | out o job); | |
92 | ReloadOrRestartUnit(in s name, | |
93 | in s mode, | |
94 | out o job); | |
95 | ReloadOrTryRestartUnit(in s name, | |
96 | in s mode, | |
97 | out o job); | |
98 | KillUnit(in s name, | |
99 | in s who, | |
100 | in i signal); | |
101 | ResetFailedUnit(in s name); | |
102 | GetJob(in u id, | |
103 | out o job); | |
104 | CancelJob(in u id); | |
105 | ClearJobs(); | |
106 | ResetFailed(); | |
107 | ListUnits(out a(ssssssouso) units); | |
108 | ListJobs(out a(usssoo) jobs); | |
109 | Subscribe(); | |
110 | Unsubscribe(); | |
111 | Reload(); | |
112 | Reexecute(); | |
113 | Exit(); | |
114 | Reboot(); | |
115 | PowerOff(); | |
116 | Halt(); | |
117 | KExec(); | |
118 | SwitchRoot(in s new_root, | |
119 | in s init); | |
120 | SetEnvironment(in as names); | |
121 | UnsetEnvironment(in as names); | |
122 | UnsetAndSetEnvironment(in as unset, | |
123 | in as set); | |
124 | ListUnitFiles(out a(ss) files); | |
125 | GetUnitFileState(in s file, | |
126 | out s state); | |
127 | EnableUnitFiles(in as files, | |
128 | in b runtime, | |
129 | in b force, | |
130 | out b carries_install_info, | |
131 | out a(sss) changes); | |
132 | DisableUnitFiles(in as files, | |
133 | in b runtime, | |
134 | out a(sss) changes); | |
135 | ReenableUnitFiles(in as files, | |
136 | in b runtime, | |
137 | in b force, | |
138 | out b carries_install_info, | |
139 | out a(sss) changes); | |
140 | LinkUnitFiles(in as files, | |
141 | in b runtime, | |
142 | in b force, | |
143 | out a(sss) changes); | |
144 | PresetUnitFiles(in as files, | |
145 | in b runtime, | |
146 | in b force, | |
147 | out b carries_install_info, | |
148 | out a(sss) changes); | |
149 | MaskUnitFiles(in as files, | |
150 | in b runtime, | |
151 | in b force, | |
152 | out a(sss) changes); | |
153 | UnmaskUnitFiles(in as files, | |
154 | in b runtime, | |
155 | out a(sss) changes); | |
156 | SetDefaultTarget(in as files, | |
157 | out a(sss) changes); | |
158 | GetDefaultTarget(out s name); | |
159 | SetUnitProperties(in s name, | |
160 | in b runtime, | |
161 | in a(sv) properties); | |
162 | StartTransientUnit(in s name, | |
163 | in s mode, | |
164 | in a(sv) properties, | |
165 | in a(sa(sv)) aux, | |
166 | out o job); | |
167 | signals: | |
168 | UnitNew(s id, | |
169 | o unit); | |
170 | UnitRemoved(s id, | |
171 | o unit); | |
172 | JobNew(u id, | |
173 | o job, | |
174 | s unit); | |
175 | JobRemoved(u id, | |
176 | o job, | |
177 | s unit, | |
178 | s result); | |
179 | StartupFinished(t firmware, | |
180 | t loader, | |
181 | t kernel, | |
182 | t initrd, | |
183 | t userspace, | |
184 | t total); | |
185 | UnitFilesChanged(); | |
186 | Reloading(b active); | |
187 | properties: | |
188 | readonly s Version = 'systemd 205'; | |
189 | readonly s Features = '+PAM +LIBWRAP +AUDIT +SELINUX +IMA +SYSVINIT +LIBCRYPTSETUP +GCRYPT +ACL +XZ'; | |
190 | readonly s Tainted = ''; | |
191 | readonly t FirmwareTimestamp = 0; | |
192 | readonly t FirmwareTimestampMonotonic = 0; | |
193 | readonly t LoaderTimestamp = 0; | |
194 | readonly t LoaderTimestampMonotonic = 0; | |
195 | readonly t KernelTimestamp = 0; | |
196 | readonly t KernelTimestampMonotonic = 0; | |
197 | readonly t InitRDTimestamp = 0; | |
198 | readonly t InitRDTimestampMonotonic = 0; | |
199 | readonly t UserspaceTimestamp = 1373892700771932; | |
200 | readonly t UserspaceTimestampMonotonic = 347348267507; | |
201 | readonly t FinishTimestamp = 1373892717621078; | |
202 | readonly t FinishTimestampMonotonic = 347365116654; | |
203 | readonly t GeneratorsStartTimestamp = 1374345509428734; | |
204 | readonly t GeneratorsStartTimestampMonotonic = 500549330609; | |
205 | readonly t GeneratorsFinishTimestamp = 1374345509562375; | |
206 | readonly t GeneratorsFinishTimestampMonotonic = 500549464250; | |
207 | readonly t UnitsLoadStartTimestamp = 1374345509562782; | |
208 | readonly t UnitsLoadStartTimestampMonotonic = 500549464657; | |
209 | readonly t UnitsLoadFinishTimestamp = 1374345509652212; | |
210 | readonly t UnitsLoadFinishTimestampMonotonic = 500549554088; | |
211 | readonly t SecurityStartTimestamp = 1374345509562782; | |
212 | readonly t SecurityStartTimestampMonotonic = 500549464657; | |
213 | readonly t SecurityFinishTimestamp = 1374345509652212; | |
214 | readonly t SecurityFinishTimestampMonotonic = 500549554088; | |
215 | readwrite s LogLevel = 'info'; | |
216 | readwrite s LogTarget = 'journal'; | |
217 | readonly u NNames = 100; | |
218 | readonly u NJobs = 0; | |
219 | readonly u NInstalledJobs = 266; | |
220 | readonly u NFailedJobs = 4; | |
221 | readonly d Progress = 1.0; | |
222 | readonly as Environment = ['PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin', 'LANG=C']; | |
223 | readonly b ConfirmSpawn = false; | |
224 | readonly b ShowStatus = true; | |
225 | readonly as UnitPath = ['/etc/systemd/system', '/run/systemd/system', '/run/systemd/generator', '/usr/local/lib/systemd/system', '/usr/lib/systemd/system']; | |
226 | readonly s DefaultStandardOutput = 'journal'; | |
227 | readonly s DefaultStandardError = 'inherit'; | |
228 | readwrite t RuntimeWatchdogUSec = 0; | |
229 | readwrite t ShutdownWatchdogUSec = 600000000; | |
230 | readonly s Virtualization = ''; | |
231 | readonly s Architecture = 'x86-64'; | |
232 | }; | |
233 | interface org.freedesktop.DBus.Properties { | |
234 | ... | |
235 | }; | |
236 | interface org.freedesktop.DBus.Peer { | |
237 | ... | |
238 | }; | |
239 | interface org.freedesktop.DBus.Introspectable { | |
240 | ... | |
241 | }; | |
242 | }; | |
243 | </programlisting> | |
244 | ||
3031660c ZJS |
245 | <refsect2> |
246 | <title>Methods</title> | |
247 | ||
248 | <para>Note that many of the calls exist twice: once on the <interfacename>Manager</interfacename> | |
249 | object, and once on the respective unit objects. This is to optimize access times so that methods that | |
250 | belong to unit objects do not have to be called with a resolved unit path, but can be called with only | |
251 | the unit id, too.</para> | |
252 | ||
253 | <para><function>GetUnit()</function> may be used to get the unit object path for a unit name. It takes | |
254 | the unit name and returns the object path. If a unit has not been loaded yet by this name this call | |
255 | will fail.</para> | |
256 | ||
257 | <para><function>GetUnitByPID()</function> may be used to get the unit object path of the unit a process | |
258 | ID belongs to. Takes a UNIX PID and returns the object path. The PID must refer to an existing process | |
259 | of the system.</para> | |
260 | ||
261 | <para><function>LoadUnit()</function> is similar to <function>GetUnit()</function> but will load the | |
262 | unit from disk if possible.</para> | |
263 | ||
264 | <para><function>StartUnit()</function> enqeues a start job, and possibly depending jobs. Takes the unit | |
265 | to activate, plus a mode string. The mode needs to be one of <literal>replace</literal>, | |
266 | <literal>fail</literal>, <literal>isolate</literal>, <literal>ignore-dependencies</literal>, | |
267 | <literal>ignore-requirements</literal>. If <literal>replace</literal> the call will start the unit and | |
268 | its dependencies, possibly replacing already queued jobs that conflict with this. If | |
269 | <literal>fail</literal> the call will start the unit and its dependencies, but will fail if this would | |
270 | change an already queued job. If <literal>isolate</literal> the call will start the unit in question | |
271 | and terminate all units that aren't dependencies of it. If <literal>ignore-dependencies</literal> it | |
272 | will start a unit but ignore all its dependencies. If <literal>ignore-requirements</literal> it will | |
273 | start a unit but only ignore the requirement dependencies. It is not recommended to make use of the | |
274 | latter two options. Returns the newly created job object.</para> | |
275 | ||
276 | <para><function>StartUnitReplace()</function> is similar to <function>StartUnit()</function> but | |
277 | replaces a job that is queued for one unit by a job for another.</para> | |
278 | ||
279 | <para><function>StopUnit()</function> is similar to <function>StartUnit()</function> but stops the | |
280 | specified unit rather than starting it. Note that <literal>isolate</literal> mode is invalid for this | |
281 | call.</para> | |
282 | ||
283 | <para><function>ReloadUnit()</function>, <function>RestartUnit()</function>, | |
284 | <function>TryRestartUnit()</function>, <function>ReloadOrRestartUnit()</function>, | |
285 | <function>ReloadOrTryRestartUnit()</function> may be used to restart and/or reload a unit, and takes | |
286 | similar arguments as <function>StartUnit()</function>. Reloading is done only if the unit is already | |
287 | running and fails otherwise. If a service is restarted that isn't running it will be started, unless | |
288 | the "Try" flavor is used in which case a service that isn't running is not affected by the restart. The | |
289 | "ReloadOrRestart" flavors attempt a reload if the unit supports it and use a restart otherwise.</para> | |
290 | ||
291 | <para><function>KillUnit()</function> may be used to kill (i.e. send a signal to) all processes of a | |
292 | unit. Takes the unit <varname>name</varname>, an enum <varname>who</varname> and a UNIX | |
293 | <varname>signal</varname> number to send. The <varname>who</varname> enum is one of | |
294 | <literal>main</literal>, <literal>control</literal> or <literal>all</literal>. If | |
295 | <literal>main</literal>, only the main process of a unit is killed. If <literal>control</literal> only | |
296 | the control process of the unit is killed, if <literal>all</literal> all processes are killed. A | |
297 | <literal>control</literal> process is for example a process that is configured via | |
298 | <varname>ExecStop=</varname> and is spawned in parallel to the main daemon process, in order to shut it | |
299 | down.</para> | |
300 | ||
301 | <para><function>GetJob()</function> returns the job object path for a specific job, identified by its | |
302 | id.</para> | |
303 | ||
304 | <para><function>CancelJob()</function> cancels a specific job identified by its numer ID. This | |
305 | operation is also available in the <function>Cancel()</function> method of Job objects (see below), and | |
306 | exists primarily to reduce the necessary round trips to execute this operation. Note that this will not | |
307 | have any effect on jobs whose execution has already begun.</para> | |
308 | ||
309 | <para><function>ClearJobs()</function> flushes the job queue, removing all jobs that are still | |
310 | queued. Note that this does not have any effect on jobs whose execution has already begun, it only | |
311 | flushes jobs that are queued and have not yet begun execution.</para> | |
312 | ||
313 | <para><function>ResetFailedUnit()</function> resets the "failed" state of a specific unit.</para> | |
314 | ||
315 | <para><function>ResetFailed()</function> resets the "failed" state of all units.</para> | |
316 | ||
317 | <para><function>ListUnits()</function> returns an array with all currently loaded units. Note that | |
318 | units may be known by multiple names at the same name, and hence there might be more unit names loaded | |
319 | than actual units behind them. The array consists of structures with the following elements: | |
320 | <itemizedlist> | |
321 | <listitem><para>The primary unit name as string</para></listitem> | |
322 | ||
323 | <listitem><para>The human readable description string</para></listitem> | |
324 | ||
325 | <listitem><para>The load state (i.e. whether the unit file has been loaded | |
326 | successfully)</para></listitem> | |
327 | ||
328 | <listitem><para>The active state (i.e. whether the unit is currently started or | |
329 | not)</para></listitem> | |
330 | ||
331 | <listitem><para>The sub state (a more fine-grained version of the active state that is specific to | |
332 | the unit type, which the active state is not)</para></listitem> | |
333 | ||
334 | <listitem><para>A unit that is being followed in its state by this unit, if there is any, otherwise | |
335 | the empty string.</para></listitem> | |
336 | ||
337 | <listitem><para>The unit object path</para></listitem> | |
338 | ||
339 | <listitem><para>If there is a job queued for the job unit the numeric job id, 0 | |
340 | otherwise</para></listitem> | |
341 | ||
342 | <listitem><para>The job type as string</para></listitem> | |
343 | ||
344 | <listitem><para>The job object path</para></listitem> | |
345 | </itemizedlist></para> | |
346 | ||
347 | <para><function>ListJobs()</function> returns an array with all currently queued jobs. Returns an array | |
348 | consisting of structures with the following elements: | |
349 | <itemizedlist> | |
350 | <listitem><para>The numeric job id</para></listitem> | |
351 | ||
352 | <listitem><para>The primary unit name for this job</para></listitem> | |
353 | ||
354 | <listitem><para>The job type as string</para></listitem> | |
355 | ||
356 | <listitem><para>The job state as string</para></listitem> | |
357 | ||
358 | <listitem><para>The job object path</para></listitem> | |
359 | ||
360 | <listitem><para>The unit object path</para></listitem> | |
361 | </itemizedlist></para> | |
362 | ||
363 | <para><function>Subscribe()</function> enables most bus signals to be sent out. Clients which are | |
364 | interested in signals need to call this function. Signals are only sent out if at least one client | |
365 | invoked this function. <function>Unsubscribe()</function> undoes the signal subscription that | |
366 | <function>Subscribe()</function> implements. It is not necessary to invoke | |
367 | <function>Unsubscribe()</function> as clients are tracked. Signals are no longer sent out as soon as | |
368 | all clients which previously asked for <function>Subscribe()</function> either closed the bus | |
369 | connection or invoked <function>Unsubscribe()</function>.</para> | |
370 | ||
371 | <para><function>Reload()</function> may be invoked to reload all unit files.</para> | |
372 | ||
373 | <para><function>Reexecute()</function> may be invoked to reexecute the main manager process. It will | |
374 | serialize its state, reexecute, and deserizalize the state again. This is useful for upgrades and is a | |
375 | more comprehensive version of <function>Reload()</function>.</para> | |
376 | ||
377 | <para><function>Exit()</function> may be invoked to ask the manager to exit. This is not available for | |
378 | the system manager and is useful only for user session managers.</para> | |
379 | ||
380 | <para><function>Reboot()</function>, <function>PowerOff()</function>, <function>Halt()</function>, | |
381 | <function>KExec()</function> may be used to ask for immediate reboot, powering down, halt or kexec | |
382 | based reboot of the system. Note that this does not shut down any services and immediately transitions | |
383 | into the reboot process. These functions are normally only called as last step of shutdown, and should | |
384 | not be called directly. To shut down the machine it is a much better choice generally to invoke | |
385 | <function>Reboot()</function> and <function>PoweOff()</function> on the | |
386 | <filename>systemd-logind</filename> manager object; see | |
387 | <citerefentry><refentrytitle>org.freedesktop.login1</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
388 | for more information.</para> | |
389 | ||
390 | <para><function>SwitchRoot()</function> may be used to transition to a new root directory. This is | |
391 | intended to be used by initial RAM disks. The call takes two arguments: the new root directory (which | |
392 | needs to be specified), plus an init binary path (which may be left empty, in which case it is | |
393 | automatically searched for). The state of the system manager will be serialized before the | |
394 | transition. After the transition the manager binary on the main system is invoked and replaces the old | |
395 | PID 1. All state will then be deserialized.</para> | |
396 | ||
397 | <para><function>SetEnvironment()</function> may be used to alter the environment block that is passed | |
398 | to all spawned processes. Takes a string array with environment variable assignments. Settings passed | |
399 | will override previously set variables.</para> | |
400 | ||
401 | <para><function>UnsetEnvironment()</function> may be used to unset environment variables. Takes a | |
402 | string array with environment variable names. All variables specified will be unset (if they have been | |
403 | set previously) and no longer be passed to all spawned processes. This call has no effect for variables | |
404 | that were previously not set, but will not fail in that case.</para> | |
405 | ||
406 | <para><function>UnsetAndSetEnvironment()</function> is a combination of | |
407 | <function>UnsetEnvironment()</function> and <function>SetEnvironment()</function>. It takes two | |
408 | lists. The first one is a list of variables to unset, the second one of assignments to set. If a | |
409 | variable is listed in both, the variable is set after this call, i.e. the set list overrides the unset | |
410 | list.</para> | |
411 | ||
412 | <para><function>ListUnitFiles()</function> returns an array of unit names plus their enablement | |
413 | status. Note that <function>ListUnit()</function> returns a list of units currently loaded into memory, | |
414 | while <function>ListUnitFiles()</function> returns a list of unit <emphasis>files</emphasis> that could | |
415 | be found on disk. Note that while most units are read directly from a unit file with the same name some | |
416 | units are not backed by files, and some files (templates) cannot directly be loaded as units but need | |
417 | to be instantiated.</para> | |
418 | ||
419 | <para><function>GetUnitFileState()</function> returns the current enablement status of specific unit | |
420 | file.</para> | |
421 | ||
422 | <para><function>EnableUnitFiles()</function> may be used to enable one or more units in the system (by | |
423 | creating symlinks to them in <filename>/etc</filename> or <filename>/run</filename>). It takes a list | |
424 | of unit files to enable (either just file names or full absolute paths if the unit files are residing | |
425 | outside the usual unit search paths), and two booleans: the first controls whether the unit shall be | |
426 | enabled for runtime only (true, <filename>/run</filename>), or persistently (false, | |
427 | <filename>/etc</filename>). The second one controls whether symlinks pointing to other units shall be | |
428 | replaced if necessary. This call returns one boolean and an array with the changes made. The boolean | |
429 | signals whether the unit files contained any enablement information (i.e. an [Install]) section. The | |
430 | changes list consists of structures with three strings: the type of the change (one of | |
431 | <literal>symlink</literal> or <literal>unlink</literal>), the file name of the symlink and the | |
432 | destination of the symlink. Note that most of the following calls return a changes list in the same | |
433 | format.</para> | |
434 | ||
435 | <para>Similarly, <function>DisableUnitFiles()</function> disables one or more units in the system, | |
436 | i.e. removes all symlinks to them in <filename>/etc</filename> and <filename>/run</filename>.</para> | |
437 | ||
438 | <para>Similarly, <function>ReenableUnitFiles()</function> applies the changes to one or more units that | |
439 | would result from disabling and enabling the unit quickly one after the other in an atomic | |
440 | fashion. This is useful to apply updated [Install] information contained in unit files.</para> | |
441 | ||
442 | <para>Similarly, <function>LinkUnitFiles()</function> links unit files (that are located outside of the | |
443 | usual unit search paths) into the unit search path.</para> | |
444 | ||
445 | <para>Similarly, <function>PresetUnitFiles()</function> enables/disables one or more units file | |
446 | according to the preset policy. See | |
447 | <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>7</manvolnum></citerefentry> for more | |
448 | information.</para> | |
449 | ||
450 | <para>Similarly, <function>MaskUnitFiles()</function> masks unit files, and | |
451 | <function>UnmaskUnitFiles()</function> unmasks them again.</para> | |
452 | ||
453 | <para><function>SetDefaultTarget()</function> changes the <filename>default.target</filename> link. See | |
454 | <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> for more | |
455 | information</para> | |
456 | ||
457 | <para><function>GetDefaultTarget()</function> retrieves the name of the unit to which | |
458 | <filename>default.target</filename> is aliased</para> | |
459 | ||
460 | <para><function>SetUnitProperties()</function> may be used to modify certain unit properties at | |
461 | runtime. Not all properties may be changed at runtime, but many resource management settings (primarily | |
462 | those listed in | |
463 | <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>) | |
464 | may. The changes are applied instantly, and stored on disk for future boots, unless | |
465 | <varname>runtime</varname> is true, in which case the settings only apply until the next | |
466 | reboot. <varname>name</varname> is the name of the unit to modify. <varname>properties</varname> are | |
467 | the settings to set, encoded as an array of property name and value pairs. Note that this is not a | |
468 | dictionary! Note that when setting array properties with this call this usually results in appending to | |
469 | the pre-configured array. To reset the configured arrays set the property to an empty array first, then | |
470 | append to it.</para> | |
471 | ||
472 | <para><function>StartTransientUnit()</function> may be used to create and start a transient unit, which | |
473 | will be released as soon as it is not running or referenced anymore or the system is | |
474 | rebooted. <varname>name</varname> is the unit name including suffix, and must be | |
475 | unique. <varname>mode</varname> is the same as in <function>StartUnit()</function>, | |
476 | <varname>properties</varname> contains properties of the unit, specified like in | |
477 | <function>SetUnitProperties()</function>. <varname>aux</varname> is currently unused and should be | |
478 | passed as empty array. See the <ulink | |
479 | url="http://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group | |
480 | Interface</ulink> for more information how to make use of this functionality for resource control | |
481 | purposes.</para> | |
3031660c ZJS |
482 | </refsect2> |
483 | ||
484 | <refsect2> | |
485 | <title>Signals</title> | |
486 | ||
487 | <para>Note that most signals are sent out only after <function>Subscribe()</function> has been invoked | |
488 | by at least one client. Make sure to invoke this call when subscribing to these signals!</para> | |
489 | ||
490 | <para><function>UnitNew()</function> and <function>UnitRemoved()</function> are sent out each time a | |
491 | new unit is loaded or unloaded. Note that this has little to do with whether a unit is available on | |
492 | disk or not, and simply reflects the units that are currently loaded into memory. The signals take two | |
493 | parameters: the primary unit name and the object path.</para> | |
494 | ||
495 | <para><function>JobNew()</function> and <function>JobRemoved()</function> are sent out each time a new | |
496 | job is queued or dequeued. Both signals take the numeric job ID, the bus path and the primary unit name | |
497 | for this job as argument. <function>JobRemoved()</function> also includes a result string, being one of | |
498 | <literal>done</literal>, <literal>canceled</literal>, <literal>timeout</literal>, | |
499 | <literal>failed</literal>, <literal>dependency</literal>, | |
500 | <literal>skipped</literal>. <literal>done</literal> indicates successful execution of a | |
501 | job. <literal>canceled</literal> indicates that a job has been canceled (via | |
502 | <function>CancelJob()</function> above) before it finished execution (this doesn't necessarily mean | |
503 | though that the job operation is actually cancelled too, see above). <literal>timeout</literal> | |
504 | indicates that the job timeout was reached. <literal>failed</literal> indicates that the job | |
505 | failed. <literal>dependency</literal> indicates that a job this job has been depending on failed and | |
506 | the job hence has been removed too. <literal>skipped</literal> indicates that a job was skipped because | |
507 | it didn't apply to the units current state.</para> | |
508 | ||
509 | <para><function>StartupFinished()</function> is sent out when startup finished. It carries six | |
510 | microsecond timespan values each indicating how much boot time has been spent in the firmware (if | |
511 | known), in the boot loader (if known), in the kernel initialization phase, in the initrd (if known), in | |
512 | userspace and in total. These values may also be calculated from the | |
513 | <varname>FirmwareTimestampMonotonic</varname>, <varname>LoaderTimestampMonotonic</varname>, | |
514 | <varname>InitRDTimestampMonotonic</varname>, <varname>UserspaceTimestampMonotonic</varname>, | |
515 | <varname>FinishTimestampMonotonic</varname> properties (see below).</para> | |
516 | ||
517 | <para><function>UnitFilesChanged()</function> is sent out each time the list of enabled or masked unit | |
518 | files on disk have changed.</para> | |
519 | ||
520 | <para><function>Reloading()</function> is sent out immediately before a daemon reload is done (with the | |
521 | boolean parameter set to True) and after a daemon reload is completed (with the boolean parameter set | |
522 | to False). This may be used by UIs to optimize UI updates</para> | |
523 | </refsect2> | |
524 | ||
525 | <refsect2> | |
526 | <title>Properties</title> | |
527 | ||
528 | <para>Most properties simply reflect the respective options in | |
529 | <filename>/etc/systemd/system.conf</filename> and the kernel command line.</para> | |
530 | ||
531 | <para>The others:</para> | |
532 | ||
533 | <para><varname>Version</varname> encodes the version string of the running systemd instance. Note that | |
534 | the version string is purely informational, it should not be parsed, one may not assume the version to | |
535 | be formatted in any particular way. We take the liberty to change the versioning scheme at any time and | |
536 | it is not part of the API.</para> | |
537 | ||
538 | <para><varname>Features</varname> encodes the features that have been enabled and disabled for this | |
539 | build. Enabled options are prefixed with +, disabled options with -.</para> | |
540 | ||
541 | <para><varname>Tainted</varname> encodes a couple of taint flags, as a colon-separated list. When | |
542 | systemd detects it is run on a system with certain problems it will set an appropriate taint | |
543 | flag. Taints may be used to lower the chance of bogus bug reports. The following taints are currently | |
544 | known: <literal>split-usr</literal>, <literal>mtab-not-symlink</literal>, | |
545 | <literal>cgroups-missing</literal>, <literal>local-hwclock</literal>. <literal>split-usr</literal> is | |
546 | set if <filename>/usr</filename> is not pre-mounted when systemd is first invoked. See | |
547 | <ulink url="http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken"> | |
548 | Booting Without /usr is Broken</ulink> | |
549 | for details why this is bad. <literal>mtab-not-symlink</literal> indicates that | |
550 | <filename>/etc/mtab</filename> is not a symlink to <filename>/proc/self/mounts</filename> as | |
551 | required. <literal>cgroups-missing</literal> indicates that control groups have not been enabled in the | |
552 | kernel. <literal>local-hwclock</literal> indicates that the local RTC is configured to be in local time | |
553 | rather than UTC.</para> | |
554 | ||
555 | <para><varname>FirmwareTimestamp</varname>, <varname>FirmwareTimestampMonotonic</varname>, | |
556 | <varname>LoaderTimestamp</varname>, <varname>LoaderTimestampMonotonic</varname>, | |
557 | <varname>KernelTimestamp</varname>, <varname>KernelTimestampMonotonic</varname>, | |
558 | <varname>InitRDTimestamp</varname>, <varname>InitRDTimestampMonotonic</varname>, | |
559 | <varname>UserspaceTimestamp</varname>, <varname>UserspaceTimestampMonotonic</varname>, | |
560 | <varname>FinishTimestamp</varname>, <varname>FinishTimestampMonotonic</varname> encode | |
561 | <constant>CLOCK_REALTIME</constant> and <constant>CLOCK_MONOTONIC</constant> microsecond timestamps | |
562 | taken when the firmware first began execution, when the boot loader first began execution, when the | |
563 | kernel first began execution, when the initrd first began execution, when the main systemd instance | |
564 | began execution and finally, when all queued startup jobs finished execution. These values are useful | |
565 | for determining boot-time performance. Note that as monotonic time begins with the kernel startup the | |
566 | KernelTimestampMonotonic timestamp will always be 0, and FirmwareTimestampMonotonic and | |
567 | LoaderTimestampMonotonic are to be read as negative values. Also, not all fields are available, | |
568 | depending on the used firmware, boot loader or initrd implementation. In these cases the respective | |
569 | pairs of timestamps are both 0, indicating that no data is available.</para> | |
570 | ||
571 | <para>Similarly, the <varname>SecurityStartTimestamp</varname>, | |
572 | <varname>GeneratorsStartTimestamp</varname> and <varname>LoadUnitTimestamp</varname> (plus their | |
573 | monotonic and stop counterparts) expose performance data for uploading the security policies to the | |
574 | kernel (such as the SELinux, IMA, or SMACK policies), for running the generator tools and for loading | |
575 | the unit files</para> | |
576 | ||
577 | <para><varname>NNames</varname> encodes how many unit names are currently known. This only includes | |
578 | names of units that are currently loaded and can be more than actually loaded units since units may | |
579 | have more than one name.</para> | |
580 | ||
581 | <para><varname>NJobs</varname> encodes how many jobs are currently queued.</para> | |
582 | ||
583 | <para><varname>NInstalledJobs</varname> encodes how many jobs have ever been queued in total.</para> | |
584 | ||
585 | <para><varname>NFailedJobs</varname> encodes how many jobs have ever failed in total.</para> | |
586 | ||
587 | <para><varname>Progress</varname> encodes boot progress as floating point value between 0.0 and | |
588 | 1.0. This value begins at 0.0 at early-boot and ends at 1.0 when boot is finished and is based on the | |
589 | number of executed and queued jobs. After startup this field is always 1.0 indicating a finished | |
590 | boot.</para> | |
591 | ||
592 | <para><varname>Environment</varname> encodes the environment block passed to all executed services. It | |
593 | may be altered with bus calls such as <function>SetEnvironment()</function> (see above).</para> | |
594 | ||
595 | <para><varname>UnitPath</varname> encodes the currently active unit file search path. It is an array of | |
596 | strings, each being one file system path</para> | |
597 | ||
598 | <para><varname>Virtualization</varname> contains a short ID string describing the virtualization | |
599 | technology the system runs in. On bare-metal hardware this is the empty string, otherwise an identifier | |
600 | such as <literal>kvm</literal>, <literal>vmware</literal> and so on. For a full list of IDs see | |
601 | <citerefentry><refentrytitle>systemd-detect-virt</refentrytitle><manvolnum>1</manvolnum></citerefentry>. | |
602 | Note that only the "innermost" virtualization technology is exported here. This detects both | |
603 | full-machine virtualizations (VMs) and shared-kernel virtualization (containers).</para> | |
604 | ||
605 | <para><varname>Architecture</varname> contains a short ID string describing the architecture the | |
606 | systemd instance is running on. This follows the same vocabulary as | |
607 | <varname>ConditionArchitectures=</varname>.</para> | |
608 | ||
609 | <para><varname>ControlGroup</varname> contains the root control group path of this system manager. Note | |
610 | that the root path is encoded as empty string here (not as <literal>/</literal>!), so that it can be | |
611 | appended to <filename>/sys/fs/cgroup/systemd</filename> easily. This value will be set to the empty | |
612 | string for the host instance, and some other string for container instances</para> | |
613 | </refsect2> | |
ae53ea52 ZJS |
614 | |
615 | <refsect2> | |
616 | <title>Security</title> | |
617 | ||
618 | <para>Read access is generally granted to all clients. Additionally, for unprivileged clients, some | |
619 | operations are allowed through the PolicyKit privilege system. Operations which modify unit state | |
620 | (<function>StartUnit()</function>, <function>StopUnit()</function>, <function>KillUnit()</function>, | |
621 | <function>RestartUnit()</function> and similar, <function>SetProperty</function>) require | |
622 | <interfacename>org.freedesktop.systemd1.manage-units</interfacename>. Operations which modify unit file | |
623 | enablement state (<function>EnableUnitFiles()</function>, <function>DisableUnitFiles()</function>, | |
624 | <function>ReenableUnitFiles()</function>, <function>LinkUnitFiles()</function>, | |
625 | <function>PresetUnitFiles</function>, <function>MaskUnitFiles</function>, and similar) require | |
626 | <interfacename>org.freedesktop.systemd1.manage-unit-files</interfacename>). Operations which modify the | |
627 | exported environment ( <function>SetEnvironment()</function>, <function>UnsetEnvironment()</function>, | |
628 | <function>UnsetAndSetEnvironment()</function>) require | |
629 | <interfacename>org.freedesktop.systemd1.set-environment</interfacename>. <function>Reload()</function> | |
630 | and <function>Reexecute()</function> require | |
631 | <interfacename>org.freedesktop.systemd1.reload-daemon</interfacename>. | |
632 | </para> | |
633 | </refsect2> | |
3031660c ZJS |
634 | </refsect1> |
635 | ||
636 | <refsect1> | |
637 | <title>Unit Objects</title> | |
638 | ||
08fe1b6c | 639 | <programlisting interface="org.freedesktop.systemd1.Unit"> |
3031660c ZJS |
640 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
641 | --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice | |
642 | ||
643 | node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { | |
644 | interface org.freedesktop.systemd1.Unit { | |
645 | methods: | |
646 | Start(in s mode, | |
647 | out o job); | |
648 | Stop(in s mode, | |
649 | out o job); | |
650 | Reload(in s mode, | |
651 | out o job); | |
652 | Restart(in s mode, | |
653 | out o job); | |
654 | TryRestart(in s mode, | |
655 | out o job); | |
656 | ReloadOrRestart(in s mode, | |
657 | out o job); | |
658 | ReloadOrTryRestart(in s mode, | |
659 | out o job); | |
660 | Kill(in s who, | |
661 | in i signal); | |
662 | ResetFailed(); | |
663 | SetProperties(in b runtime, | |
664 | in a(sv) properties); | |
665 | signals: | |
666 | properties: | |
667 | readonly s Id = 'avahi-daemon.service'; | |
668 | readonly as Names = ['avahi-daemon.service']; | |
669 | readonly s Following = ''; | |
670 | readonly as Requires = ['avahi-daemon.socket', 'dbus.socket', 'basic.target']; | |
671 | readonly as RequiresOverridable = []; | |
672 | readonly as Requisite = []; | |
673 | readonly as RequisiteOverridable = []; | |
674 | readonly as Wants = []; | |
675 | readonly as BindsTo = []; | |
676 | readonly as PartOf = []; | |
677 | readonly as RequiredBy = []; | |
678 | readonly as RequiredByOverridable = []; | |
679 | readonly as WantedBy = ['multi-user.target']; | |
680 | readonly as BoundBy = []; | |
681 | readonly as ConsistsOf = []; | |
682 | readonly as Conflicts = ['shutdown.target']; | |
683 | readonly as ConflictedBy = []; | |
684 | readonly as Before = ['shutdown.target', 'multi-user.target']; | |
685 | readonly as After = ['avahi-daemon.socket', 'systemd-journald.socket', 'dbus.socket', 'basic.target']; | |
686 | readonly as OnFailure = []; | |
687 | readonly as Triggers = []; | |
688 | readonly as TriggeredBy = ['avahi-daemon.socket']; | |
689 | readonly as PropagatesReloadTo = []; | |
690 | readonly as ReloadPropagatedFrom = []; | |
691 | readonly as RequiresMountsFor = []; | |
692 | readonly s Description = 'Avahi mDNS/DNS-SD Stack'; | |
693 | readonly s SourcePath = ''; | |
694 | readonly as DropInPaths = []; | |
695 | readonly as Documentation = []; | |
696 | readonly s LoadState = 'loaded'; | |
697 | readonly s ActiveState = 'active'; | |
698 | readonly s SubState = 'running'; | |
699 | readonly s FragmentPath = '/usr/lib/systemd/system/avahi-daemon.service'; | |
700 | readonly s UnitFileState = 'enabled'; | |
701 | readonly t InactiveExitTimestamp = 1368576738559539; | |
702 | readonly t InactiveExitTimestampMonotonic = 22561234; | |
703 | readonly t ActiveEnterTimestamp = 1368576738648314; | |
704 | readonly t ActiveEnterTimestampMonotonic = 22650009; | |
705 | readonly t ActiveExitTimestamp = 0; | |
706 | readonly t ActiveExitTimestampMonotonic = 0; | |
707 | readonly t InactiveEnterTimestamp = 0; | |
708 | readonly t InactiveEnterTimestampMonotonic = 0; | |
709 | readonly b CanStart = true; | |
710 | readonly b CanStop = true; | |
711 | readonly b CanReload = true; | |
712 | readonly b CanIsolate = false; | |
713 | readonly (uo) Job = (0, '/org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice'); | |
714 | readonly b StopWhenUnneeded = false; | |
715 | readonly b RefuseManualStart = false; | |
716 | readonly b RefuseManualStop = false; | |
717 | readonly b AllowIsolate = false; | |
718 | readonly b DefaultDependencies = true; | |
719 | readonly b OnFailureIsolate = false; | |
720 | readonly b IgnoreOnIsolate = false; | |
721 | readonly b IgnoreOnSnapshot = false; | |
722 | readonly b NeedDaemonReload = false; | |
723 | readonly t JobTimeoutUSec = 0; | |
724 | readonly t ConditionTimestamp = 1368576738557978; | |
725 | readonly t ConditionTimestampMonotonic = 22559674; | |
726 | readonly b ConditionResult = true; | |
727 | readonly a(sbbsi) Conditions = [('ConditionVirtualization, false, false, 'no', 1)]; | |
728 | readonly (ss) LoadError = ('', ''); | |
729 | readonly b Transient = false; | |
730 | }; | |
731 | interface org.freedesktop.systemd1.Service { | |
732 | ... | |
733 | }; | |
734 | interface org.freedesktop.DBus.Properties { | |
735 | ... | |
736 | }; | |
737 | interface org.freedesktop.DBus.Peer { | |
738 | ... | |
739 | }; | |
740 | interface org.freedesktop.DBus.Introspectable { | |
741 | ... | |
742 | }; | |
743 | }; | |
744 | </programlisting> | |
745 | ||
746 | <refsect2> | |
747 | <title>Methods</title> | |
748 | ||
749 | <para><function>Start()</function>, <function>Stop()</function>, <function>Reload()</function>, | |
750 | <function>Restart()</function>, <function>TryRestart()</function>, | |
751 | <function>ReloadOrRestart()</function>, <function>ReloadOrTryRestart()</function>, | |
752 | <function>Kill()</function>, <function>ResetFailed()</function>, and | |
753 | <function>SetProperties()</function> implement the same operation as the respective method calls on the | |
754 | <interfacename>Manager</interfacename> object (see above), however operate on the unit object and hence | |
755 | do not take a unit name parameter. Invoking the methods directly on the Manager object has the | |
756 | advantage of not requiring a <function>GetUnit()</function> call to get the unit object for a specific | |
757 | unit name. Calling the methods on the Manager object is hence a round trip optimization.</para> | |
758 | </refsect2> | |
759 | ||
760 | <refsect2> | |
761 | <title>Properties</title> | |
762 | ||
763 | <para><varname>Id</varname> contains the primary name of the unit.</para> | |
764 | ||
765 | <para><varname>Names</varname> contains all names of the unit, including the primary name that is also | |
766 | exposed in <varname>Id</varname>.</para> | |
767 | ||
768 | <para><varname>Following</varname> either contains the empty string or contains the name of another | |
769 | unit that this unit follows in state. This is used for some device units which reflect the unit state | |
770 | machine of another unit, and which other unit this is might possibly change.</para> | |
771 | ||
772 | <para><varname>Requires</varname>, <varname>RequiresOverridable</varname>, | |
773 | <varname>Requisite</varname>, <varname>RequisiteOverridable</varname>, <varname>Wants</varname>, | |
774 | <varname>BindsTo</varname>, <varname>RequiredBy</varname>, <varname>RequiredByOverridable</varname>, | |
775 | <varname>WantedBy</varname>, <varname>BoundBy</varname>, <varname>Conflicts</varname>, | |
776 | <varname>ConflictedBy</varname>, <varname>Before</varname>, <varname>After</varname>, | |
777 | <varname>OnFailure</varname>, <varname>Triggers</varname>, <varname>TriggeredBy</varname>, | |
778 | <varname>PropagatesReloadTo</varname>, <varname>RequiresMountsFor</varname> contain arrays which encode | |
779 | the dependencies and their inverse dependencies (where this applies), as configured in the unit file or | |
780 | determined automatically. </para> | |
781 | ||
782 | <para><varname>Description</varname> contains the human readable description string for the | |
783 | unit.</para> | |
784 | ||
785 | <para><varname>SourcePath</varname> contains the path to a configuration file this unit is | |
786 | automatically generated from in case it is not a native unit (in which case it contains the empty | |
787 | string). For example, all mount units generated from <filename>/etc/fstab</filename> have this field | |
788 | set to this value.</para> | |
789 | ||
790 | <para><varname>Documentation</varname> contains a string array with URLs of documentation for this | |
791 | unit.</para> | |
792 | ||
793 | <para><varname>LoadState</varname> contains a state value that reflects whether the configuration file | |
794 | of this unit has been loaded. The following states are currently defined: <literal>loaded</literal>, | |
795 | <literal>error</literal>, <literal>masked</literal>. <literal>loaded</literal> indicates that the | |
796 | configuration was successfully loaded. <literal>error</literal> indicates that the configuration failed | |
797 | to load, the <varname>LoadError</varname> field (see below) contains information about the cause of | |
798 | this failure. <literal>masked</literal> indicates that the unit is currently masked out (i.e. symlinked | |
799 | to <filename>/dev/null</filename> or empty). Note that the <varname>LoadState</varname> is fully | |
800 | orthogonal to the <varname>ActiveState</varname> (see below) as units without valid loaded | |
801 | configuration might be active (because configuration might have been reloaded at a time where a unit | |
802 | was already active).</para> | |
803 | ||
804 | <para><varname>ActiveState</varname> contains a state value that reflects whether the unit is currently | |
805 | active or not. The following states are currently defined: <literal>active</literal>, | |
806 | <literal>reloading</literal>, <literal>inactive</literal>, <literal>failed</literal>, | |
807 | <literal>activating</literal>, <literal>deactivating</literal>. <literal>active</literal> indicates | |
808 | that unit is active (obviously...). <literal>reloading</literal> indicates that the unit is active and | |
809 | currently reloading its configuration. <literal>inactive</literal> indicates that it is inactive and | |
810 | the previous run was successful or no previous run has taken place yet. <literal>failed</literal> | |
811 | indicates that it is inactive and the previous run was not successful (more information about the | |
812 | reason for this is available on the unit type specific interfaces, for example for services in the | |
813 | <varname>Result</varname> property, see below). <literal>activating</literal> indicates that the unit | |
814 | has previously been inactive but is currently in the process of entering an active state. Conversely | |
815 | <literal>deactivating</literal> indicates that the unit is currently in the process of | |
816 | deactivation.</para> | |
817 | ||
818 | <para><varname>SubState</varname> encodes states of the same state machine that | |
819 | <varname>ActiveState</varname> covers, but knows more fine-grained states that are | |
820 | unit-type-specific. Where <varname>ActiveState</varname> only covers six high-level states, | |
821 | <varname>SubState</varname> covers possibly many more low-level unit-type-specific states that are | |
822 | mapped to the six high-level states. Note that multiple low-level states might map to the same | |
823 | high-level state, but not vice versa. Not all high-level states have low-level counterparts on all unit | |
824 | types. At this point the low-level states are not documented here, and are more likely to be extended | |
825 | later on than the common high-level states explained above.</para> | |
826 | ||
827 | <para><varname>FragmentPath</varname> contains the unit file path this unit was read from, if there is | |
828 | any (if not this contains the empty string).</para> | |
829 | ||
830 | <para><varname>UnitFileState</varname> encodes the install state of the unit file of | |
831 | <varname>FragmentPath</varname>. It currently knows the following states: <literal>enabled</literal>, | |
832 | <literal>enabled-runtime</literal>, <literal>linked</literal>, <literal>linked-runtime</literal>, | |
833 | <literal>masked</literal>, <literal>masked-runtime</literal>, <literal>static</literal>, | |
834 | <literal>disabled</literal>, <literal>invalid</literal>. <literal>enabled</literal> indicates that a | |
835 | unit file is permanently enabled. <literal>enable-runtime</literal> indicates the unit file is only | |
836 | temporarily enabled, and will no longer be enabled after a reboot (that means, it is enabled via | |
837 | <filename>/run</filename> symlinks, rather than <filename>/etc</filename>). <literal>linked</literal> | |
838 | indicates that a unit is linked into <filename>/etc</filename> permanently, <literal>linked</literal> | |
839 | indicates that a unit is linked into <filename>/run</filename> temporarily (until the next | |
840 | reboot). <literal>masked</literal> indicates that the unit file is masked permanently, | |
841 | <literal>masked-runtime</literal> indicates that it is only temporarily masked in | |
842 | <filename>/run</filename>, until the next reboot. <literal>static</literal> indicates that the unit is | |
843 | statically enabled, i.e. always enabled and doesn't need to be enabled | |
844 | explicitly. <literal>invalid</literal> indicates that it could not be determined whether the unit file | |
845 | is enabled.</para> | |
846 | ||
847 | <para><varname>InactiveExitTimestamp</varname>, <varname>InactiveExitTimestampMonotonic</varname>, | |
848 | <varname>ActiveEnterTimestamp</varname>, <varname>ActiveEnterTimestampMonotonic</varname>, | |
849 | <varname>ActiveExitTimestamp</varname>, <varname>ActiveExitTimestampMonotonic</varname>, | |
850 | <varname>InactiveEnterTimestamp</varname>, <varname>InactiveEnterTimestampMonotonic</varname> contain | |
851 | <constant>CLOCK_REALTIME</constant> and <constant>CLOCK_MONOTONIC</constant> 64-bit microsecond | |
852 | timestamps of the last time a unit left the inactive state, entered the active state, exited the active | |
853 | state, or entered an inactive state. These are the points in time where the unit transitioned | |
854 | <literal>inactive</literal>/<literal>failed</literal> → <literal>activating</literal>, | |
855 | <literal>activating</literal> → <literal>active</literal>, <literal>active</literal> → | |
856 | <literal>deactivating</literal>, and finally <literal>deactivating</literal> → | |
857 | <literal>inactive</literal>/<literal>failed</literal>. The fields are 0 in case such a transition has | |
858 | not been recording on this boot yet.</para> | |
859 | ||
860 | <para><varname>CanStart</varname>, <varname>CanStop</varname>, <varname>CanReload</varname> encodes as | |
861 | booleans whether the unit supports the start, stop or reload operations. Even if a unit supports such | |
862 | an operation the client might not necessary have the right privileges to execute them.</para> | |
863 | ||
864 | <para><varname>CanIsolate</varname> encodes as boolean whether the unit may be started in isolation | |
865 | mode.</para> | |
866 | ||
867 | <para><varname>Job</varname> encodes the job ID and job object path of the job currently scheduled or | |
868 | executed for this unit, if there is any. If no job is scheduled or executed the job id field will be | |
869 | 0.</para> | |
870 | ||
871 | <para><varname>StopWhenUnneeded</varname>, <varname>RefuseManualStart</varname>, | |
872 | <varname>RefuseManualStop</varname>, <varname>AllowIsolate</varname>, | |
873 | <varname>DefaultDependencies</varname>, <varname>OnFailureIsolate</varname>, | |
874 | <varname>IgnoreOnIsolate</varname>, <varname>IgnoreOnSnapshot</varname> map directly to the | |
875 | corresponding configuration booleans in the unit file.</para> | |
876 | ||
877 | <para><varname>DefaultControlGroup</varname> contains the main control group of this unit as a | |
878 | string. This refers to a group in systemd's own <literal>name=systemd</literal> hierarchy, which | |
879 | systemd uses to watch and manipulate the unit and all its processes.</para> | |
880 | ||
881 | <para><varname>NeedDaemonReload</varname> is a boolean that indicates whether the configuration file | |
882 | this unit is loaded from (i.e. <varname>FragmentPath</varname> or <varname>SourcePath</varname>) has | |
883 | changed since the configuration was read and hence whether a configuration reload is | |
884 | recommended.</para> | |
885 | ||
886 | <para><varname>JobTimeoutUSec</varname> maps directly to the corresponding configuration setting in the | |
887 | unit file.</para> | |
888 | ||
889 | <para><varname>ConditionTimestamp</varname> and <varname>ConditionTimestampMonotonic</varname> contain | |
890 | the <constant>CLOCK_REALTIME</constant>/<constant>CLOCK_MONOTONIC</constant> microsecond timestamps of | |
891 | the last time the configured conditions of the unit have been checked, or 0 if they have never been | |
892 | checked. Conditions are checked when a unit is requested to start.</para> | |
893 | ||
894 | <para><varname>ConditionResult</varname> contains the condition result of the last time the configured | |
895 | conditions of this unit were checked. </para> | |
896 | ||
897 | <para><varname>Conditions</varname> contains all configured conditions of the unit. For each condition | |
898 | five fields are given: condition type (e.g. <varname>ConditionPathExists</varname>), whether the | |
899 | condition is a trigger condition, whether the condition is reversed, the right hand side of the | |
ae53ea52 | 900 | condition (e.g. the path in case of <varname>ConditionPathExists</varname>), and the status. The status |
3031660c ZJS |
901 | can be 0, in which case the condition hasn't been checked yet, a positive value, in which case the |
902 | condition passed, or a negative value, in which case the condition failed. Currently only 0, +1, and -1 | |
903 | are used, but additional values may be used in the future, retaining the meaning of | |
904 | zero/positive/negative values</para> | |
905 | ||
906 | <para><varname>LoadError</varname> contains a pair of strings. If the unit failed to load (as encoded | |
907 | in <varname>LoadState</varname>, see above), then this will include a D-Bus error pair consisting of | |
908 | the error ID and an explanatory human readable string of what happened. If it succeeded to load this | |
909 | will be a pair of empty strings.</para> | |
910 | ||
911 | <para><varname>Transient</varname> contains a boolean that indicates whether the unit was created as | |
912 | transient unit (i.e. via <function>CreateTransientUnit()</function> on the manager object)</para> | |
913 | </refsect2> | |
ae53ea52 ZJS |
914 | |
915 | <refsect2> | |
916 | <title>Security</title> | |
917 | ||
918 | <para>Similarly to methods on the <interfacename>Manager</interfacename> object, read-only access is | |
919 | allowed for everyone. All operations are allowed for clients with the | |
920 | <constant>CAP_SYS_ADMIN</constant> capability or when the | |
921 | <interfacename>org.freedesktop.systemd1.manage-units</interfacename> privilege is granted by | |
922 | PolicyKit.</para> | |
923 | </refsect2> | |
3031660c ZJS |
924 | </refsect1> |
925 | ||
926 | <refsect1> | |
927 | <title>Service Unit Objects</title> | |
928 | ||
929 | <para>All service unit objects implement the | |
930 | <interfacename>org.freedesktop.systemd1.Service</interfacename> interface (described here) in addition to | |
931 | the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para> | |
932 | ||
08fe1b6c | 933 | <programlisting interface="org.freedesktop.systemd1.Service"> |
3031660c ZJS |
934 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
935 | --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice | |
936 | ||
937 | interface org.freedesktop.systemd1.Unit { | |
938 | ... | |
939 | }; | |
940 | interface org.freedesktop.systemd1.Service { | |
941 | methods: | |
942 | signals: | |
943 | properties: | |
944 | readonly s Type = 'dbus'; | |
945 | readonly s Restart = 'no'; | |
946 | readonly s PIDFile = ''; | |
947 | readonly s NotifyAccess = 'main'; | |
948 | readonly t RestartUSec = 100000; | |
949 | readonly t TimeoutUSec = 90000000; | |
950 | readonly t WatchdogUSec = 0; | |
951 | readonly t WatchdogTimestamp = 0; | |
952 | readonly t WatchdogTimestampMonotonic = 0; | |
953 | readonly t StartLimitInterval = 10000000; | |
954 | readonly u StartLimitBurst = 5; | |
955 | readwrite s StartLimitAction = 'none | |
956 | readonly s Slice = 'system.slice'; | |
957 | readonly s ControlGroup = '/system.slice/avahi-daemon.service'; | |
958 | readonly a(sasbttuii) ExecStartPre = []; | |
959 | readonly a(sasbttuii) ExecStart = [('/usr/sbin/avahi-daemon', ['/usr/sbin/avahi-daemon', '-s'], false, 0, 0, 0, 0, 0, 0, 0)]; | |
960 | readonly a(sasbttuii) ExecStartPost = []; | |
961 | readonly a(sasbttuii) ExecReload = [('/usr/sbin/avahi-daemon', ['/usr/sbin/avahi-daemon', '-r'], false, 0, 0, 0, 0, 0, 0, 0)]; | |
962 | readonly a(sasbttuii) ExecStop = []; | |
963 | readonly a(sasbttuii) ExecStopPost = []; | |
964 | readonly as Environment = []; | |
965 | readonly a(sb) EnvironmentFiles = []; | |
966 | readonly u UMask = 18; | |
967 | readonly t LimitCPU = 18446744073709551615; | |
968 | readonly t LimitFSIZE = 18446744073709551615; | |
969 | readonly t LimitDATA = 18446744073709551615; | |
970 | readonly t LimitSTACK = 18446744073709551615; | |
971 | readonly t LimitCORE = 18446744073709551615; | |
972 | readonly t LimitRSS = 18446744073709551615; | |
973 | readonly t LimitNOFILE = 4096; | |
974 | readonly t LimitAS = 18446744073709551615; | |
975 | readonly t LimitNPROC = 256963; | |
976 | readonly t LimitMEMLOCK = 65536; | |
977 | readonly t LimitLOCKS = 18446744073709551615; | |
978 | readonly t LimitSIGPENDING = 256963; | |
979 | readonly t LimitMSGQUEUE = 819200; | |
980 | readonly t LimitNICE = 0; | |
981 | readonly t LimitRTPRIO = 0; | |
982 | readonly t LimitRTTIME = 18446744073709551615; | |
983 | readonly s WorkingDirectory = ''; | |
984 | readonly s RootDirectory = ''; | |
985 | readonly i OOMScoreAdjust = 0; | |
986 | readonly i Nice = 0; | |
987 | readonly i IOScheduling = 0; | |
988 | readonly i CPUSchedulingPolicy = 0; | |
989 | readonly i CPUSchedulingPriority = 0; | |
990 | readonly ay CPUAffinity = []; | |
991 | readonly t TimerSlackNSec = 50000; | |
992 | readonly b CPUSchedulingResetOnFork = false; | |
993 | readonly b NonBlocking = false; | |
994 | readonly s StandardInput = 'null'; | |
995 | readonly s StandardOutput = 'journal'; | |
996 | readonly s StandardError = 'inherit'; | |
997 | readonly s TTYPath = ''; | |
998 | readonly b TTYReset = false; | |
999 | readonly b TTYVHangup = false; | |
1000 | readonly b TTYVTDisallocate = false; | |
1001 | readonly i SyslogPriority = 30; | |
1002 | readonly s SyslogIdentifier = ''; | |
1003 | readonly b SyslogLevelPrefix = true; | |
1004 | readonly s Capabilities = ''; | |
1005 | readonly i SecureBits = 0; | |
1006 | readonly t CapabilityBoundingSet = 18446744073709551615; | |
1007 | readonly s User = ''; | |
1008 | readonly s Group = ''; | |
1009 | readonly as SupplementaryGroups = []; | |
1010 | readonly s TCPWrapName = ''; | |
1011 | readonly s PAMName = ''; | |
1012 | readonly as ReadWriteDirectories = []; | |
1013 | readonly as ReadOnlyDirectories = []; | |
1014 | readonly as InaccessibleDirectories = []; | |
1015 | readonly t MountFlags = 0; | |
1016 | readonly b PrivateTmp = false; | |
1017 | readonly b PrivateNetwork = false; | |
1018 | readonly b SameProcessGroup = false; | |
1019 | readonly s UtmpIdentifier = ''; | |
1020 | readonly b IgnoreSIGPIPE = true; | |
1021 | readonly b NoNewPrivileges = false; | |
1022 | readonly au SystemCallFilter = []; | |
1023 | readonly s KillMode = 'control-group'; | |
1024 | readonly i KillSignal = 15; | |
1025 | readonly b SendSIGKILL = true; | |
1026 | readonly b SendSIGHUP = false; | |
1027 | readonly b CPUAccounting = false; | |
1028 | readonly t CPUShares = 1024; | |
1029 | readonly b BlockIOAccounting = false; | |
1030 | readonly t BlockIOWeight = 1000; | |
1031 | readonly a(st) BlockIODeviceWeight = []; | |
1032 | readonly a(st) BlockIOReadBandwidth=; | |
1033 | readonly a(st) BlockIOWriteBandwidth=; | |
1034 | readonly b MemoryAccounting = false; | |
1035 | readonly t MemoryLimit = 18446744073709551615; | |
1036 | readonly s DevicePolicy = 'auto'; | |
1037 | readonly a(ss) DeviceAllow = []; | |
1038 | readonly b PermissionsStartOnly = false; | |
1039 | readonly b RootDirectoryStartOnly = false; | |
1040 | readonly b RemainAfterExit = false; | |
1041 | readonly t ExecMainStartTimestamp = 1368576738559537; | |
1042 | readonly t ExecMainStartTimestampMonotonic = 22561233; | |
1043 | readonly t ExecMainExitTimestamp = 1368576738559537; | |
1044 | readonly t ExecMainExitTimestampMonotonic = 22561233; | |
1045 | readonly u ExecMainPID = 666; | |
1046 | readonly i ExecMainCode = 0; | |
1047 | readonly i ExecMainStatus = 0; | |
1048 | readonly u MainPID = 666; | |
1049 | readonly u ControlPID = 0; | |
1050 | readonly s BusName = 'org.freedesktop.Avahi'; | |
1051 | readonly s StatusText = 'Server startup complete. Host name is fedora.local. Local service cookie is 2431121142.'; | |
1052 | readonly s Result = 'success'; | |
1053 | }; | |
1054 | interface org.freedesktop.DBus.Properties { | |
1055 | ... | |
1056 | }; | |
1057 | interface org.freedesktop.DBus.Peer { | |
1058 | ... | |
1059 | }; | |
1060 | interface org.freedesktop.DBus.Introspectable { | |
1061 | ... | |
1062 | }; | |
1063 | }; | |
1064 | </programlisting> | |
1065 | ||
1066 | <refsect2> | |
1067 | <title>Properties</title> | |
1068 | ||
1069 | <para>Most properties of the Service interface map directly to the corresponding settings in service | |
1070 | unit files. For the sake of brevity, here's a list of all exceptions only:</para> | |
1071 | ||
1072 | <para><varname>WatchdogTimestamp</varname> and <varname>WatchdogTimestampMonotonic</varname> contain | |
1073 | <constant>CLOCK_REALTIME</constant>/<constant>CLOCK_MONOTONIC</constant> microsecond timestamps of the | |
1074 | last watchdog ping received from the service, or 0 if none was ever received.</para> | |
1075 | ||
1076 | <para><varname>ExecStartPre</varname>, <varname>ExecStart</varname>, <varname>ExecStartPost</varname>, | |
1077 | <varname>ExecReload</varname>, <varname>ExecStop</varname>, <varname>ExecStop</varname> each are arrays | |
1078 | of structures each containing: the binary path to execute; an array with all arguments to pass to the | |
1079 | executed command, starting with argument 0; a boolean whether it should be considered a failure if the | |
1080 | process exits uncleanly; two pairs of | |
1081 | <constant>CLOCK_REALTIME</constant>/<constant>CLOCK_MONOTONIC</constant> microsecond timestamps when | |
1082 | the process began and finished running the last time, or 0 if it never ran or never finished running; | |
1083 | the PID of the process, or 0 if it has not run yet; the exit code and status of the last run. This | |
1084 | field hence maps more or less to the corresponding setting in the service unit file but is augmented | |
1085 | with runtime data.</para> | |
1086 | ||
1087 | <para><varname>LimitCPU</varname> (and related properties) map more or less directly to the | |
1088 | corresponding settings in the service unit files, however are set to 18446744073709551615 (i.e. -1) if | |
1089 | they aren't set.</para> | |
1090 | ||
1091 | <para><varname>Capabilities</varname> contains the configured capabilities, as formatted with | |
1092 | <citerefentry project='man-pages'><refentrytitle>cap_to_text</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
1093 | </para> | |
1094 | ||
1095 | <para><varname>SecureBits</varname>, <varname>CapabilityBoundingSet</varname>, | |
1096 | <varname>MountFlags</varname> also correspond to the configured settings of the unit files, but are | |
1097 | encoded as the actual binary flag fields they are, rather than formatted as string.</para> | |
1098 | ||
1099 | <para><varname>ExecMainStartTimestamp</varname>, <varname>ExecMainStartTimestampMonotonic</varname>, | |
1100 | <varname>ExecMainExitTimestamp</varname>, <varname>ExecMainExitTimestampMonotonic</varname>, | |
1101 | <varname>ExecMainPID</varname>, <varname>ExecMainCode</varname>, <varname>ExecMainStatus</varname> | |
1102 | contain information about the main process of the service as far as it is known. This is often the same | |
1103 | runtime information that is stored in <varname>ExecStart</varname>. However, it deviates for | |
1104 | <varname>Type=forking</varname> services where the main process of the service is not forked off | |
1105 | systemd directly. These fields either contain information of the last run of the process or of the | |
1106 | current running process.</para> | |
1107 | ||
1108 | <para><varname>MainPID</varname> and <varname>ControlPID</varname> contain the main and control PID of | |
1109 | the service. The main PID is the current main PID of the service and is 0 when the service currently | |
1110 | has no main PID. The control PID is the PID of the current start/stop/reload process running and is 0 | |
1111 | if no such process is currently running. That means that <varname>ExecMainPID</varname> and | |
1112 | <varname>MainPID</varname> differ in the way that the latter immediately reflects whether a main | |
1113 | process is currently running while the latter possible contains information collected from the last run | |
1114 | even if the process is no longer around.</para> | |
1115 | ||
1116 | <para><varname>StatusText</varname> contains the status text passed to the service manager via a call | |
1117 | to | |
1118 | <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
1119 | This may be used by services to inform the service manager about its internal state with a nice | |
1120 | explanatory string.</para> | |
1121 | ||
1122 | <para><varname>Result</varname> encodes the execution result of the last run of the service. It is | |
1123 | useful to determine the reason a service failed if it is in <literal>failed</literal> state (see | |
1124 | <varname>ActiveState</varname> above). The following values are currently known: | |
1125 | <literal>success</literal> is set if the unit didn't fail. <literal>resources</literal> indicates that | |
1126 | not enough resources have been available to fork off and execute the service | |
1127 | processes. <literal>timeout</literal> indicates that a time-out occurred while executing a service | |
1128 | operation. <literal>exit-code</literal> indicates that a service process exited with an unclean exit | |
1129 | code. <literal>signal</literal> indicates that a service process exited with an uncaught | |
1130 | signal. <literal>core-dump</literal> indicates that a service process exited uncleanly and dumped | |
1131 | core. <literal>watchdog</literal> indicates that a service did not send out watchdog ping messages | |
1132 | often enough. <literal>start-limit</literal> indicates that a service has been started too frequently | |
1133 | in a time frame (as configured in <varname>StartLimitInterval</varname>, | |
1134 | <varname>StartLimitBurst</varname>).</para> | |
1135 | ||
1136 | <para><varname>ControlGroup</varname> indicates the control group path the processes of this service | |
1137 | unit are placed in.</para> | |
1138 | </refsect2> | |
1139 | </refsect1> | |
1140 | ||
1141 | <refsect1> | |
1142 | <title>Socket Unit Objects</title> | |
1143 | ||
08fe1b6c | 1144 | <programlisting interface="org.freedesktop.systemd1.Socket"> |
3031660c ZJS |
1145 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1146 | --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket | |
1147 | ||
1148 | node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { | |
1149 | interface org.freedesktop.systemd1.Unit { | |
1150 | ... | |
1151 | }; | |
1152 | interface org.freedesktop.systemd1.Socket { | |
1153 | methods: | |
1154 | signals: | |
1155 | properties: | |
1156 | readonly b BindIPv6Only = 'default'; | |
1157 | readonly u Backlog = 128; | |
1158 | readonly t TimeoutUSec = 90000000; | |
1159 | readonly s Slice = 'system.slice'; | |
1160 | readonly s ControlGroup = '/system.slice/avahi-daemon.socket'; | |
1161 | readonly a(sasbttuii) ExecStartPre = []; | |
1162 | readonly a(sasbttuii) ExecStartPost = []; | |
1163 | readonly a(sasbttuii) ExecStopPre = []; | |
1164 | readonly a(sasbttuii) ExecStopPost = []; | |
1165 | readonly as Environment = []; | |
1166 | readonly a(sb) EnvironmentFiles = []; | |
1167 | readonly u UMask = 18; | |
1168 | readonly t LimitCPU = 18446744073709551615; | |
1169 | readonly t LimitFSIZE = 18446744073709551615; | |
1170 | readonly t LimitDATA = 18446744073709551615; | |
1171 | readonly t LimitSTACK = 18446744073709551615; | |
1172 | readonly t LimitCORE = 18446744073709551615; | |
1173 | readonly t LimitRSS = 18446744073709551615; | |
1174 | readonly t LimitNOFILE = 4096; | |
1175 | readonly t LimitAS = 18446744073709551615; | |
1176 | readonly t LimitNPROC = 61434; | |
1177 | readonly t LimitMEMLOCK = 65536; | |
1178 | readonly t LimitLOCKS = 18446744073709551615; | |
1179 | readonly t LimitSIGPENDING = 61434; | |
1180 | readonly t LimitMSGQUEUE = 819200; | |
1181 | readonly t LimitNICE = 0; | |
1182 | readonly t LimitRTPRIO = 0; | |
1183 | readonly t LimitRTTIME = 18446744073709551615; | |
1184 | readonly s WorkingDirectory = ''; | |
1185 | readonly s RootDirectory = ''; | |
1186 | readonly i OOMScoreAdjust = 0; | |
1187 | readonly i Nice = 0; | |
1188 | readonly i IOScheduling = 0; | |
1189 | readonly i CPUSchedulingPolicy = 0; | |
1190 | readonly i CPUSchedulingPriority = 0; | |
1191 | readonly ay CPUAffinity = []; | |
1192 | readonly t TimerSlackNSec = 50000; | |
1193 | readonly b CPUSchedulingResetOnFork = false; | |
1194 | readonly b NonBlocking = false; | |
1195 | readonly s StandardInput = 'null'; | |
1196 | readonly s StandardOutput = 'journal'; | |
1197 | readonly s StandardError = 'inherit'; | |
1198 | readonly s TTYPath = ''; | |
1199 | readonly b TTYReset = false; | |
1200 | readonly b TTYVHangup = false; | |
1201 | readonly b TTYVTDisallocate = false; | |
1202 | readonly i SyslogPriority = 30; | |
1203 | readonly s SyslogIdentifier = ''; | |
1204 | readonly b SyslogLevelPrefix = true; | |
1205 | readonly s Capabilities = ''; | |
1206 | readonly i SecureBits = 0; | |
1207 | readonly t CapabilityBoundingSet = 18446744073709551615; | |
1208 | readonly s User = ''; | |
1209 | readonly s Group = ''; | |
1210 | readonly as SupplementaryGroups = []; | |
1211 | readonly s TCPWrapName = ''; | |
1212 | readonly s PAMName = ''; | |
1213 | readonly as ReadWriteDirectories = []; | |
1214 | readonly as ReadOnlyDirectories = []; | |
1215 | readonly as InaccessibleDirectories = []; | |
1216 | readonly t MountFlags = 0; | |
1217 | readonly b PrivateTmp = false; | |
1218 | readonly b PrivateNetwork = false; | |
1219 | readonly b SameProcessGroup = false; | |
1220 | readonly s UtmpIdentifier = ''; | |
1221 | readonly b IgnoreSIGPIPE = true; | |
1222 | readonly b NoNewPrivileges = false; | |
1223 | readonly au SystemCallFilter = []; | |
1224 | readonly s KillMode = 'control-group'; | |
1225 | readonly i KillSignal = 15; | |
1226 | readonly b SendSIGKILL = true; | |
1227 | readonly b SendSIGHUP = false; | |
1228 | readonly b CPUAccounting = false; | |
1229 | readonly t CPUShares = 1024; | |
1230 | readonly b BlockIOAccounting = false; | |
1231 | readonly t BlockIOWeight = 1000; | |
1232 | readonly a(st) BlockIODeviceWeight = []; | |
1233 | readonly a(st) BlockIOReadBandwidth=; | |
1234 | readonly a(st) BlockIOWriteBandwidth=; | |
1235 | readonly b MemoryAccounting = false; | |
1236 | readonly t MemoryLimit = 18446744073709551615; | |
1237 | readonly s DevicePolicy = 'auto'; | |
1238 | readonly a(ss) DeviceAllow = []; | |
1239 | readonly u ControlPID = 0; | |
1240 | readonly s BindToDevice = ''; | |
1241 | readonly u DirectoryMode = 493; | |
1242 | readonly u SocketMode = 438; | |
1243 | readonly b Accept = false; | |
1244 | readonly b KeepAlive = false; | |
1245 | readonly i Priority = -1; | |
1246 | readonly t ReceiveBuffer = 0; | |
1247 | readonly t SendBuffer = 0; | |
1248 | readonly i IPTOS = -1; | |
1249 | readonly i IPTTL = -1; | |
1250 | readonly t PipeSize = 0; | |
1251 | readonly b FreeBind = false; | |
1252 | readonly b Transparent = false; | |
1253 | readonly b Broadcast = false; | |
1254 | readonly b PassCredentials = false; | |
1255 | readonly b PassSecurity = false; | |
1256 | readonly i Mark = -1; | |
1257 | readonly u MaxConnections = 64; | |
1258 | readonly u NAccepted = 0; | |
1259 | readonly u NConnections = 0; | |
1260 | readonly x MessageQueueMaxMessages = 0; | |
1261 | readonly x MessageQueueMessageSize = 0; | |
1262 | readonly a(ss) Listen = [('Stream', '/var/run/avahi-daemon/socket')]; | |
1263 | readonly s Result = 'success'; | |
1264 | readonly b ReusePort = false; | |
1265 | readonly s SmackLabel = ''; | |
1266 | readonly s SmackLabelIPIn = ''; | |
1267 | readonly s SmackLabelIPOut = ''; | |
1268 | }; | |
1269 | interface org.freedesktop.DBus.Properties { | |
1270 | ... | |
1271 | }; | |
1272 | interface org.freedesktop.DBus.Peer { | |
1273 | ... | |
1274 | }; | |
1275 | interface org.freedesktop.DBus.Introspectable { | |
1276 | ... | |
1277 | }; | |
1278 | }; | |
1279 | </programlisting> | |
1280 | ||
1281 | <refsect2> | |
1282 | <title>Properties</title> | |
1283 | ||
1284 | <para>Most of the properties map directly to the corresponding settings in socket unit files. As socket | |
1285 | units can include <varname>ExecStartPre</varname> (and similar) fields which contain information about | |
1286 | processes to execute. They also share most of the fields related to the execution context that Service | |
1287 | objects expose (see above).</para> | |
1288 | ||
1289 | <para>In addition to these properties there are the following:</para> | |
1290 | ||
1291 | <para><varname>NAccepted</varname> contains the accumulated number of connections ever accepted on this | |
1292 | socket. This only applies to sockets with <varname>Accept</varname> set to <literal>true</literal>, | |
1293 | i.e. those where systemd is responsible for accepted connections. </para> | |
1294 | ||
1295 | <para>Similarly <varname>NConnections</varname> contains the number of currently open connections on | |
1296 | this socket, and also applies only to socket with <varname>Accept</varname> set to | |
1297 | <literal>true</literal>.</para> | |
1298 | ||
1299 | <para><varname>Result</varname> encodes the reason why a socket unit failed if it is in | |
1300 | <literal>failed</literal> state (see <varname>ActiveState</varname> above). The values | |
1301 | <literal>success</literal>, <literal>resources</literal>, <literal>timeout</literal>, | |
1302 | <literal>exit-code</literal>, <literal>signal</literal> and <literal>core-dump</literal> have the same | |
1303 | meaning as they have for the corresponding field of service units (see above). In addition to that the | |
1304 | value <literal>service-failed-permanent</literal> indicates that the service of this socket failed | |
1305 | continuously.</para> | |
1306 | </refsect2> | |
1307 | </refsect1> | |
1308 | ||
1309 | <refsect1> | |
1310 | <title>Target Unit Objects</title> | |
1311 | ||
08fe1b6c | 1312 | <programlisting interface="org.freedesktop.systemd1.Target"> |
3031660c ZJS |
1313 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1314 | --object-path /org/freedesktop/systemd1/unit/basic_2etarget | |
1315 | ||
1316 | node /org/freedesktop/systemd1/unit/basic_2etarget { | |
1317 | interface org.freedesktop.systemd1.Unit { | |
1318 | ... | |
1319 | }; | |
1320 | interface org.freedesktop.systemd1.Target { | |
1321 | methods: | |
1322 | signals: | |
1323 | properties: | |
1324 | }; | |
1325 | interface org.freedesktop.DBus.Properties { | |
1326 | ... | |
1327 | }; | |
1328 | interface org.freedesktop.DBus.Peer { | |
1329 | ... | |
1330 | }; | |
1331 | interface org.freedesktop.DBus.Introspectable { | |
1332 | ... | |
1333 | }; | |
1334 | }; | |
1335 | </programlisting> | |
1336 | ||
1337 | <para>Target units have neither type-specific methods nor properties.</para> | |
1338 | </refsect1> | |
1339 | ||
1340 | ||
1341 | <refsect1> | |
1342 | <title>Device Unit Objects</title> | |
1343 | ||
1344 | <para>All device unit objects implement the <interfacename>org.freedesktop.systemd1.Device</interfacename> interface (described here) | |
1345 | in addition to the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para> | |
1346 | ||
08fe1b6c | 1347 | <programlisting interface="org.freedesktop.systemd1.Device"> |
3031660c | 1348 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
08fe1b6c | 1349 | --object-path /org/freedesktop/systemd1/unit/dev_2dfoo_2edevice |
3031660c | 1350 | |
08fe1b6c | 1351 | node /org/freedesktop/systemd1/unit/dev_2d_foo_2edevice { |
3031660c ZJS |
1352 | interface org.freedesktop.systemd1.Unit { |
1353 | ... | |
1354 | }; | |
1355 | interface org.freedesktop.systemd1.Device { | |
1356 | methods: | |
1357 | signals: | |
1358 | properties: | |
1359 | readonly s SysFSPath = '/sys/devices/pci0000:00/0000:00:1f.2/ata2/host1/target1:0:0/1:0:0:0/block/sdb'; | |
1360 | }; | |
1361 | interface org.freedesktop.DBus.Properties { | |
1362 | ... | |
1363 | }; | |
1364 | interface org.freedesktop.DBus.Peer { | |
1365 | ... | |
1366 | }; | |
1367 | interface org.freedesktop.DBus.Introspectable { | |
1368 | ... | |
1369 | }; | |
1370 | }; | |
1371 | </programlisting> | |
1372 | ||
1373 | <refsect2> | |
1374 | <title>Properties</title> | |
1375 | ||
1376 | <para>Device units only expose a single type-specific property:</para> | |
1377 | ||
1378 | <para><varname>SysFSPath</varname> contains the sysfs path of the kernel device this object corresponds | |
1379 | to.</para> | |
1380 | </refsect2> | |
1381 | </refsect1> | |
1382 | ||
1383 | ||
1384 | <refsect1> | |
1385 | <title>Mount Unit Objects</title> | |
1386 | ||
1387 | <para>All mount unit objects implement the <interfacename>org.freedesktop.systemd1.Mount</interfacename> | |
1388 | interface (described here) in addition to the generic | |
1389 | <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above)</para> | |
1390 | ||
08fe1b6c | 1391 | <programlisting interface="org.freedesktop.systemd1.Mount"> |
3031660c ZJS |
1392 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1393 | --object-path /org/freedesktop/systemd1/unit/home_2emount | |
1394 | ||
1395 | node /org/freedesktop/systemd1/unit/home_2emount { | |
1396 | interface org.freedesktop.systemd1.Unit { | |
1397 | ... | |
1398 | }; | |
1399 | interface org.freedesktop.systemd1.Mount { | |
1400 | methods: | |
1401 | signals: | |
1402 | properties: | |
1403 | readonly s Where = '/home'; | |
1404 | readonly s What = '/dev/mapper/home'; | |
1405 | readonly s Options = 'rw,relatime,rw,seclabel,data=ordered'; | |
1406 | readonly s Type = 'ext4'; | |
1407 | readonly t TimeoutUSec = 90000000; | |
1408 | readonly s Slice = 'system.slice'; | |
1409 | readonly s ControlGroup = '/system.slice/home.mount'; | |
1410 | readonly a(sasbttuii) ExecMount = [('/bin/mount', ['/bin/mount', '/dev/disk/by-uuid/59a54df8-d070-4907-a4a7-2e0ce05d5c2a', '/home', '-t', 'ext4'], false, 1357656124168977, 11158027, 1357656124274805, 11263855, 608, 1, 0)]; | |
1411 | readonly a(sasbttuii) ExecUnmount = []; | |
1412 | readonly a(sasbttuii) ExecRemount = []; | |
1413 | readonly as Environment = []; | |
1414 | readonly a(sb) EnvironmentFiles = []; | |
1415 | readonly u UMask = 18; | |
1416 | readonly t LimitCPU = 18446744073709551615; | |
1417 | readonly t LimitFSIZE = 18446744073709551615; | |
1418 | readonly t LimitDATA = 18446744073709551615; | |
1419 | readonly t LimitSTACK = 18446744073709551615; | |
1420 | readonly t LimitCORE = 18446744073709551615; | |
1421 | readonly t LimitRSS = 18446744073709551615; | |
1422 | readonly t LimitNOFILE = 4096; | |
1423 | readonly t LimitAS = 18446744073709551615; | |
1424 | readonly t LimitNPROC = 61434; | |
1425 | readonly t LimitMEMLOCK = 65536; | |
1426 | readonly t LimitLOCKS = 18446744073709551615; | |
1427 | readonly t LimitSIGPENDING = 61434; | |
1428 | readonly t LimitMSGQUEUE = 819200; | |
1429 | readonly t LimitNICE = 0; | |
1430 | readonly t LimitRTPRIO = 0; | |
1431 | readonly t LimitRTTIME = 18446744073709551615; | |
1432 | readonly s WorkingDirectory = ''; | |
1433 | readonly s RootDirectory = ''; | |
1434 | readonly i OOMScoreAdjust = 0; | |
1435 | readonly i Nice = 0; | |
1436 | readonly i IOScheduling = 0; | |
1437 | readonly i CPUSchedulingPolicy = 0; | |
1438 | readonly i CPUSchedulingPriority = 0; | |
1439 | readonly ay CPUAffinity = []; | |
1440 | readonly t TimerSlackNSec = 50000; | |
1441 | readonly b CPUSchedulingResetOnFork = false; | |
1442 | readonly b NonBlocking = false; | |
1443 | readonly s StandardInput = 'null'; | |
1444 | readonly s StandardOutput = 'journal'; | |
1445 | readonly s StandardError = 'inherit'; | |
1446 | readonly s TTYPath = ''; | |
1447 | readonly b TTYReset = false; | |
1448 | readonly b TTYVHangup = false; | |
1449 | readonly b TTYVTDisallocate = false; | |
1450 | readonly i SyslogPriority = 30; | |
1451 | readonly s SyslogIdentifier = ''; | |
1452 | readonly b SyslogLevelPrefix = true; | |
1453 | readonly s Capabilities = ''; | |
1454 | readonly i SecureBits = 0; | |
1455 | readonly t CapabilityBoundingSet = 18446744073709551615; | |
1456 | readonly s User = ''; | |
1457 | readonly s Group = ''; | |
1458 | readonly as SupplementaryGroups = []; | |
1459 | readonly s TCPWrapName = ''; | |
1460 | readonly s PAMName = ''; | |
1461 | readonly as ReadWriteDirectories = []; | |
1462 | readonly as ReadOnlyDirectories = []; | |
1463 | readonly as InaccessibleDirectories = []; | |
1464 | readonly t MountFlags = 0; | |
1465 | readonly b PrivateTmp = false; | |
1466 | readonly b PrivateNetwork = false; | |
1467 | readonly b SameProcessGroup = true; | |
1468 | readonly s UtmpIdentifier = ''; | |
1469 | readonly b IgnoreSIGPIPE = true; | |
1470 | readonly b NoNewPrivileges = false; | |
1471 | readonly au SystemCallFilter = []; | |
1472 | readonly s KillMode = 'control-group'; | |
1473 | readonly i KillSignal = 15; | |
1474 | readonly b SendSIGKILL = true; | |
1475 | readonly b SendSIGHUP = false; | |
1476 | readonly b CPUAccounting = false; | |
1477 | readonly t CPUShares = 1024; | |
1478 | readonly b BlockIOAccounting = false; | |
1479 | readonly t BlockIOWeight = 1000; | |
1480 | readonly a(st) BlockIODeviceWeight = []; | |
1481 | readonly a(st) BlockIOReadBandwidth=; | |
1482 | readonly a(st) BlockIOWriteBandwidth=; | |
1483 | readonly b MemoryAccounting = false; | |
1484 | readonly t MemoryLimit = 18446744073709551615; | |
1485 | readonly s DevicePolicy = 'auto'; | |
1486 | readonly a(ss) DeviceAllow = []; | |
1487 | readonly u ControlPID = 0; | |
1488 | readonly u DirectoryMode = 493; | |
1489 | readonly s Result = 'success'; | |
1490 | }; | |
1491 | interface org.freedesktop.DBus.Properties { | |
1492 | ... | |
1493 | }; | |
1494 | interface org.freedesktop.DBus.Peer { | |
1495 | ... | |
1496 | }; | |
1497 | interface org.freedesktop.DBus.Introspectable { | |
1498 | ... | |
1499 | }; | |
1500 | }; | |
1501 | </programlisting> | |
1502 | ||
1503 | <refsect2> | |
1504 | <title>Properties</title> | |
1505 | ||
1506 | <para>Most of the properties map directly to the corresponding settings in mount unit files. As mount | |
1507 | units invoke the <filename>/usr/bin/mount</filename> command their bus objects include implicit | |
1508 | <varname>ExecMount</varname> (and similar) fields which contain information about processes to | |
1509 | execute. They also share most of the fields related to the execution context that Service objects | |
1510 | expose (see above). In addition to these properties there are the following:</para> | |
1511 | ||
1512 | <para><varname>ControlPID</varname> contains the PID of the currently running | |
1513 | <filename>/usr/bin/mount</filename> or <filename>/usr/bin/umount</filename> command if there is one | |
1514 | running, otherwise 0.</para> | |
1515 | ||
1516 | <para><varname>Result</varname> contains a value explaining why a mount unit failed if it failed. It | |
1517 | can take the values <literal>success</literal>, <literal>resources</literal>, | |
1518 | <literal>timeout</literal>, <literal>exit-code</literal>, <literal>signal</literal>, | |
1519 | <literal>core-dump</literal> which have the identical meaning as the corresponding values of the | |
1520 | corresponding field of service unit objects (see above).</para> | |
1521 | </refsect2> | |
1522 | </refsect1> | |
1523 | ||
1524 | <refsect1> | |
1525 | <title>Automount Unit Objects</title> | |
1526 | ||
1527 | <para>All automount unit objects implement the | |
1528 | <interfacename>org.freedesktop.systemd1.Automount</interfacename> interface (described here) in addition | |
1529 | to the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para> | |
1530 | ||
08fe1b6c | 1531 | <programlisting interface="org.freedesktop.systemd1.Automount"> |
3031660c ZJS |
1532 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1533 | --object-path /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount | |
1534 | ||
1535 | node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount { | |
1536 | interface org.freedesktop.systemd1.Unit { | |
1537 | ... | |
1538 | }; | |
1539 | interface org.freedesktop.systemd1.Automount { | |
1540 | methods: | |
1541 | signals: | |
1542 | properties: | |
1543 | readonly s Where = '/proc/sys/fs/binfmt_misc'; | |
1544 | readonly u DirectoryMode = 493; | |
1545 | readonly s Result = 'success'; | |
1546 | }; | |
1547 | interface org.freedesktop.DBus.Properties { | |
1548 | ... | |
1549 | }; | |
1550 | interface org.freedesktop.DBus.Peer { | |
1551 | ... | |
1552 | }; | |
1553 | interface org.freedesktop.DBus.Introspectable { | |
1554 | ... | |
1555 | }; | |
1556 | }; | |
1557 | </programlisting> | |
1558 | ||
1559 | <refsect2> | |
1560 | <title>Properties</title> | |
1561 | ||
1562 | <para>Most of the properties map directly to the corresponding settings in the automount unit | |
1563 | files.</para> | |
1564 | ||
1565 | <para><varname>Result</varname> knows the values <literal>success</literal> and | |
1566 | <literal>resources</literal>, at this time. They have the same meanings as the corresponding values of | |
1567 | the corresponding field of the Service object.</para> | |
1568 | </refsect2> | |
1569 | </refsect1> | |
1570 | ||
1571 | ||
1572 | <refsect1> | |
1573 | <title>Timer Unit Objects</title> | |
1574 | ||
1575 | <para>All timer unit objects implement the <interfacename>org.freedesktop.systemd1.Timer</interfacename> | |
1576 | interface (described here) in addition to the generic | |
1577 | <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para> | |
1578 | ||
08fe1b6c | 1579 | <programlisting interface="org.freedesktop.systemd1.Timer"> |
3031660c ZJS |
1580 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1581 | --object-path /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer | |
1582 | ||
1583 | node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer { | |
1584 | interface org.freedesktop.systemd1.Unit { | |
1585 | ... | |
1586 | }; | |
1587 | interface org.freedesktop.systemd1.Timer { | |
1588 | readonly s Unit = 'systemd-tmpfiles-clean.service'; | |
1589 | readonly a(stt) TimersMonotonic = [('OnUnitActiveUSec', 86400000000, 173700033104), ('OnBootUSec', 900000000, 900000000)]; | |
1590 | readonly a(sst) TimersCalendar = []; | |
1591 | readonly t NextElapseUSecRealtime = 0; | |
1592 | readonly t NextElapseUSecMonotonic = 173700033104; | |
1593 | readonly s Result = 'success'; | |
1594 | }; | |
1595 | interface org.freedesktop.DBus.Properties { | |
1596 | ... | |
1597 | }; | |
1598 | interface org.freedesktop.DBus.Peer { | |
1599 | ... | |
1600 | }; | |
1601 | interface org.freedesktop.DBus.Introspectable { | |
1602 | ... | |
1603 | }; | |
1604 | }; | |
1605 | </programlisting> | |
1606 | ||
1607 | <refsect2> | |
1608 | <title>Properties</title> | |
1609 | ||
1610 | <para><varname>Unit</varname> contains the name of the unit to activate when the timer elapses.</para> | |
1611 | ||
1612 | <para><varname>TimersMonotonic</varname> contains an array of structs that contain information about | |
1613 | all monotonic timers of this timer unit. The structs contain a string identifying the timer base, which | |
1614 | is one of <literal>OnActiveUSec</literal>, <literal>OnBootUSec</literal>, | |
1615 | <literal>OnStartupUSec</literal>, <literal>OnUnitActiveUSec</literal>, | |
1616 | <literal>OnUnitInactiveUSec</literal>, which correspond to the settings of the same names in the timer | |
1617 | unit files; the microsecond offset from this timer base in monotonic time; the next elapsation point on | |
1618 | the <constant>CLOCK_MONOTONIC</constant> clock, relative its epoch.</para> | |
1619 | ||
1620 | <para><varname>TimersCalendar</varname> contains an array of structs that contain information about all | |
1621 | realtime/calendar timers of this timer unit. The structs contain a string identifying the timer base, | |
1622 | which may only be <literal>OnCalendar</literal> for now; the calendar specification string; the next | |
1623 | elapsation point on the <constant>CLOCK_REALTIME</constant> clock, relative to its epoch.</para> | |
1624 | ||
1625 | <para><varname>NextElapseUSecRealtime</varname> contains the next elapsation point on the | |
1626 | <constant>CLOCK_REALTIME</constant> clock in miscroseconds since the epoch, or 0 if this timer event | |
1627 | does not include at least one calendar event.</para> | |
1628 | ||
1629 | <para>Similarly, <varname>NextElapseUSecMonotonic</varname> contains the next elapsation point on the | |
1630 | <constant>CLOCK_MONOTONIC</constant> clock in microseconds since the epoch, or 0 if this timer event | |
1631 | does not include at least one monotonic event.</para> | |
1632 | ||
1633 | <para><varname>Result</varname> knows the values <literal>success</literal> and | |
1634 | <literal>resources</literal> with the same meanings as the matching values of the corresponding | |
1635 | property of the service interface.</para> | |
1636 | </refsect2> | |
1637 | </refsect1> | |
1638 | ||
1639 | <refsect1> | |
1640 | <title>Swap Unit Objects</title> | |
1641 | ||
1642 | <para>All swap unit objects implement the <interfacename>org.freedesktop.systemd1.Swap</interfacename> | |
1643 | interface (described here) in addition to the generic | |
1644 | <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para> | |
1645 | ||
08fe1b6c | 1646 | <programlisting interface="org.freedesktop.systemd1.Swap"> |
3031660c ZJS |
1647 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1648 | --object-path /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap | |
1649 | ||
1650 | node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { | |
1651 | interface org.freedesktop.systemd1.Unit { | |
1652 | ... | |
1653 | }; | |
1654 | interface org.freedesktop.systemd1.Swap { | |
1655 | methods: | |
1656 | signals: | |
1657 | properties: | |
1658 | readonly s What = '/dev/sda3'; | |
1659 | readonly i Priority = -1; | |
1660 | readonly t TimeoutUSec = 90000000; | |
1661 | readonly s Slice = 'system.slice'; | |
1662 | readonly s ControlGroup = ''; | |
1663 | readonly a(sasbttuii) ExecActivate = []; | |
1664 | readonly a(sasbttuii) ExecDeactivate = []; | |
1665 | readonly as Environment = []; | |
1666 | readonly a(sb) EnvironmentFiles = []; | |
1667 | readonly u UMask = 18; | |
1668 | readonly t LimitCPU = 18446744073709551615; | |
1669 | readonly t LimitFSIZE = 18446744073709551615; | |
1670 | readonly t LimitDATA = 18446744073709551615; | |
1671 | readonly t LimitSTACK = 18446744073709551615; | |
1672 | readonly t LimitCORE = 18446744073709551615; | |
1673 | readonly t LimitRSS = 18446744073709551615; | |
1674 | readonly t LimitNOFILE = 4096; | |
1675 | readonly t LimitAS = 18446744073709551615; | |
1676 | readonly t LimitNPROC = 61434; | |
1677 | readonly t LimitMEMLOCK = 65536; | |
1678 | readonly t LimitLOCKS = 18446744073709551615; | |
1679 | readonly t LimitSIGPENDING = 61434; | |
1680 | readonly t LimitMSGQUEUE = 819200; | |
1681 | readonly t LimitNICE = 0; | |
1682 | readonly t LimitRTPRIO = 0; | |
1683 | readonly t LimitRTTIME = 18446744073709551615; | |
1684 | readonly s WorkingDirectory = ''; | |
1685 | readonly s RootDirectory = ''; | |
1686 | readonly i OOMScoreAdjust = 0; | |
1687 | readonly i Nice = 0; | |
1688 | readonly i IOScheduling = 0; | |
1689 | readonly i CPUSchedulingPolicy = 0; | |
1690 | readonly i CPUSchedulingPriority = 0; | |
1691 | readonly ay CPUAffinity = []; | |
1692 | readonly t TimerSlackNS = 50000; | |
1693 | readonly b CPUSchedulingResetOnFork = false; | |
1694 | readonly b NonBlocking = false; | |
1695 | readonly s StandardInput = 'null'; | |
1696 | readonly s StandardOutput = 'journal'; | |
1697 | readonly s StandardError = 'inherit'; | |
1698 | readonly s TTYPath = ''; | |
1699 | readonly b TTYReset = false; | |
1700 | readonly b TTYVHangup = false; | |
1701 | readonly b TTYVTDisallocate = false; | |
1702 | readonly i SyslogPriority = 30; | |
1703 | readonly s SyslogIdentifier = ''; | |
1704 | readonly b SyslogLevelPrefix = true; | |
1705 | readonly s Capabilities = ''; | |
1706 | readonly i SecureBits = 0; | |
1707 | readonly t CapabilityBoundingSet = 18446744073709551615; | |
1708 | readonly s User = ''; | |
1709 | readonly s Group = ''; | |
1710 | readonly as SupplementaryGroups = []; | |
1711 | readonly s TCPWrapName = ''; | |
1712 | readonly s PAMName = ''; | |
1713 | readonly as ReadWriteDirectories = []; | |
1714 | readonly as ReadOnlyDirectories = []; | |
1715 | readonly as InaccessibleDirectories = []; | |
1716 | readonly t MountFlags = 0; | |
1717 | readonly b PrivateTmp = false; | |
1718 | readonly b PrivateNetwork = false; | |
1719 | readonly b SameProcessGroup = false; | |
1720 | readonly s KillMode = 'control-group'; | |
1721 | readonly i KillSignal = 15; | |
1722 | readonly s UtmpIdentifier = ''; | |
1723 | readonly b IgnoreSIGPIPE = true; | |
1724 | readonly b NoNewPrivileges = false; | |
1725 | readonly au SystemCallFilter = []; | |
1726 | readonly s KillMode = 'control-group'; | |
1727 | readonly i KillSignal = 15; | |
1728 | readonly b SendSIGKILL = true; | |
1729 | readonly b SendSIGHUP = false; | |
1730 | readonly b CPUAccounting = false; | |
1731 | readonly t CPUShares = 1024; | |
1732 | readonly b BlockIOAccounting = false; | |
1733 | readonly t BlockIOWeight = 1000; | |
1734 | readonly a(st) BlockIODeviceWeight = []; | |
1735 | readonly a(st) BlockIOReadBandwidth=; | |
1736 | readonly a(st) BlockIOWriteBandwidth=; | |
1737 | readonly b MemoryAccounting = false; | |
1738 | readonly t MemoryLimit = 18446744073709551615; | |
1739 | readonly s DevicePolicy = 'auto'; | |
1740 | readonly a(ss) DeviceAllow = []; | |
1741 | readonly u ControlPID = 0; | |
1742 | readonly s Result = 'success'; | |
1743 | }; | |
1744 | interface org.freedesktop.DBus.Properties { | |
1745 | ... | |
1746 | }; | |
1747 | interface org.freedesktop.DBus.Peer { | |
1748 | ... | |
1749 | }; | |
1750 | interface org.freedesktop.DBus.Introspectable { | |
1751 | ... | |
1752 | }; | |
1753 | }; | |
1754 | </programlisting> | |
1755 | ||
1756 | <refsect2> | |
1757 | <title>Properties</title> | |
1758 | ||
1759 | <para>Most of the properties map directly to the corresponding settings in swap unit files. As mount | |
1760 | units invoke the | |
1761 | <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> command | |
1762 | their bus objects include implicit <varname>ExecActivate</varname> (and similar) fields which contain | |
1763 | information about processes to execute. They also share most of the fields related to the execution | |
1764 | context that Service objects expose (see above). In addition to these properties there are the | |
1765 | following:</para> | |
1766 | ||
1767 | <para><varname>ControlPID</varname> contains the PID of the currently running | |
1768 | <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> or | |
1769 | <citerefentry><refentrytitle>swapoff</refentrytitle><manvolnum>8</manvolnum></citerefentry> command if | |
1770 | there is one running, otherwise 0.</para> | |
1771 | ||
1772 | <para><varname>Result</varname> contains a value explaining why a mount unit failed if it failed. It | |
1773 | can take the values <literal>success</literal>, <literal>resources</literal>, | |
1774 | <literal>timeout</literal>, <literal>exit-code</literal>, <literal>signal</literal>, | |
1775 | <literal>core-dump</literal> which have the identical meanings as the corresponding values of the | |
1776 | corresponding field of service unit objects (see above).</para> | |
1777 | </refsect2> | |
1778 | </refsect1> | |
1779 | ||
1780 | ||
1781 | <refsect1> | |
1782 | <title>Path Unit Objects</title> | |
1783 | ||
08fe1b6c | 1784 | <programlisting interface="org.freedesktop.systemd1.Path"> |
3031660c ZJS |
1785 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1786 | --object-path /org/freedesktop/systemd1/unit/cups_2epath | |
1787 | ||
1788 | node /org/freedesktop/systemd1/unit/cups_2epath { | |
1789 | interface org.freedesktop.systemd1.Unit { | |
1790 | ... | |
1791 | }; | |
1792 | interface org.freedesktop.systemd1.Path { | |
1793 | methods: | |
1794 | signals: | |
1795 | properties: | |
1796 | readonly s Unit = 'cups.service'; | |
1797 | readonly a(ss) Paths = [('PathExistsGlob', '/var/spool/cups/d*')]; | |
1798 | readonly b MakeDirectory = false; | |
1799 | readonly u DirectoryMode = 493; | |
1800 | readonly s Result = 'success'; | |
1801 | }; | |
1802 | interface org.freedesktop.DBus.Properties { | |
1803 | ... | |
1804 | }; | |
1805 | interface org.freedesktop.DBus.Peer { | |
1806 | ... | |
1807 | }; | |
1808 | interface org.freedesktop.DBus.Introspectable { | |
1809 | ... | |
1810 | }; | |
1811 | }; | |
1812 | </programlisting> | |
1813 | ||
1814 | <refsect2> | |
1815 | <title>Properties</title> | |
1816 | ||
1817 | <para>Most properties correspond directly with the matching settings in path unit files.</para> | |
1818 | ||
1819 | <para>The others:</para> | |
1820 | ||
1821 | <para><varname>Paths</varname> contains an array of structs. Each struct contains the condition to | |
1822 | watch, which can be one of <literal>PathExists</literal>, <literal>PathExistsGlob</literal>, | |
1823 | <literal>PathChanged</literal>, <literal>PathModified</literal>, <literal>DirectoryNotEmpty</literal> | |
1824 | which correspond directly to the matching settings in the path unit files; and the path to watch, | |
1825 | possibly including glob expressions.</para> | |
1826 | ||
1827 | <para><varname>Result</varname> contains a result value which can be <literal>success</literal> or | |
1828 | <literal>resources</literal>, which have the same meaning as the corresponding field of the service | |
1829 | interface.</para> | |
1830 | </refsect2> | |
1831 | </refsect1> | |
1832 | ||
1833 | <refsect1> | |
1834 | <title>Slice Unit Objects</title> | |
1835 | ||
1836 | <para>All slice unit objects implement the <interfacename>org.freedesktop.systemd1.Slice</interfacename> | |
1837 | interface (described here) in addition to the generic | |
1838 | <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para> | |
1839 | ||
08fe1b6c | 1840 | <programlisting interface="org.freedesktop.systemd1.Slice"> |
3031660c ZJS |
1841 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1842 | --object-path /org/freedesktop/systemd1/unit/system_2eslice | |
1843 | ||
1844 | node /org/freedesktop/systemd1/unit/system_2eslice { | |
1845 | interface org.freedesktop.systemd1.Unit { | |
1846 | ... | |
1847 | }; | |
1848 | interface org.freedesktop.systemd1.Slice { | |
1849 | methods: | |
1850 | signals: | |
1851 | properties: | |
1852 | readonly s Slice = '-.slice'; | |
1853 | readonly s ControlGroup = '/system.slice'; | |
1854 | readonly b CPUAccounting = false; | |
1855 | readonly t CPUShares = 1024; | |
1856 | readonly b BlockIOAccounting = false; | |
1857 | readonly t BlockIOWeight = 1000; | |
1858 | readonly a(st) BlockIODeviceWeight = []; | |
1859 | readonly a(st) BlockIOReadBandwidth=; | |
1860 | readonly a(st) BlockIOWriteBandwidth=; | |
1861 | readonly b MemoryAccounting = false; | |
1862 | readonly t MemoryLimit = 18446744073709551615; | |
1863 | readonly s DevicePolicy = 'auto'; | |
1864 | readonly a(ss) DeviceAllow = []; | |
1865 | }; | |
1866 | interface org.freedesktop.DBus.Properties { | |
1867 | ... | |
1868 | }; | |
1869 | interface org.freedesktop.DBus.Peer { | |
1870 | ... | |
1871 | }; | |
1872 | interface org.freedesktop.DBus.Introspectable { | |
1873 | ... | |
1874 | }; | |
1875 | }; | |
1876 | </programlisting> | |
1877 | ||
1878 | <refsect2> | |
1879 | <title>Properties</title> | |
1880 | ||
1881 | <para>Most properties correspond directly with the matching settings in slice unit files.</para> | |
1882 | </refsect2> | |
1883 | </refsect1> | |
1884 | ||
1885 | <refsect1> | |
1886 | <title>Scope Unit Objects</title> | |
1887 | ||
1888 | <para>All slice unit objects implement the <interfacename>org.freedesktop.systemd1.Scope</interfacename> | |
1889 | interface (described here) in addition to the generic | |
1890 | <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para> | |
1891 | ||
08fe1b6c | 1892 | <programlisting interface="org.freedesktop.systemd1.Scope"> |
3031660c ZJS |
1893 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ |
1894 | --object-path /org/freedesktop/systemd1/unit/session_2d1_2escope | |
1895 | ||
1896 | node /org/freedesktop/systemd1/unit/session_2d1_2escope { | |
1897 | interface org.freedesktop.systemd1.Unit { | |
1898 | ... | |
1899 | }; | |
1900 | interface org.freedesktop.systemd1.Scope { | |
1901 | methods: | |
1902 | Abandon(); | |
1903 | signals: | |
1904 | RequestStop(); | |
1905 | properties: | |
1906 | readonly s Slice = 'user-1000.slice'; | |
1907 | readonly s ControlGroup = '/user.slice/user-1000.slice/session-1.scope'; | |
1908 | readonly t TimeoutStopUSec = 500000; | |
1909 | readonly s KillMode = 'none'; | |
1910 | readonly i KillSignal = 15; | |
1911 | readonly b SendSIGKILL = true; | |
1912 | readonly b SendSIGHUP = true; | |
1913 | readonly b CPUAccounting = false; | |
1914 | readonly t CPUShares = 1024; | |
1915 | readonly b BlockIOAccounting = false; | |
1916 | readonly t BlockIOWeight = 1000; | |
1917 | readonly a(st) BlockIODeviceWeight = []; | |
1918 | readonly a(st) BlockIOReadBandwidth=; | |
1919 | readonly a(st) BlockIOWriteBandwidth=; | |
1920 | readonly b MemoryAccounting = false; | |
1921 | readonly t MemoryLimit = 18446744073709551615; | |
1922 | readonly s DevicePolicy = 'auto'; | |
1923 | readonly a(ss) DeviceAllow = []; | |
1924 | readonly s Result = 'success'; | |
1925 | readonly s Controller = ''; | |
1926 | ||
1927 | ||
1928 | }; | |
1929 | interface org.freedesktop.DBus.Properties { | |
1930 | ... | |
1931 | }; | |
1932 | interface org.freedesktop.DBus.Peer { | |
1933 | ... | |
1934 | }; | |
1935 | interface org.freedesktop.DBus.Introspectable { | |
1936 | ... | |
1937 | }; | |
1938 | }; | |
1939 | </programlisting> | |
1940 | ||
1941 | <refsect2> | |
1942 | <title>Methods</title> | |
1943 | ||
1944 | <para><function>Abandon()</function> may be used to place a scope unit in the "abandoned" state. This | |
1945 | may be used to inform the system manager that the manager that created the scope lost interest in the | |
1946 | scope (for example, because it is terminating), without wanting to shut down the scope entirely</para> | |
1947 | </refsect2> | |
1948 | ||
1949 | <refsect2> | |
1950 | <title>Signals</title> | |
1951 | ||
1952 | <para><function>RequestStop</function> is sent to the peer that is configured in the | |
1953 | <varname>Controller</varname> property when systemd is requested to terminate the scope unit. A program | |
1954 | registering a scope can use this to cleanly shut down the processes it added to the scope, instead of | |
1955 | letting systemd do it with the usual <constant>SIGTERM</constant> logic.</para> | |
1956 | </refsect2> | |
1957 | ||
1958 | <refsect2> | |
1959 | <title>Properties</title> | |
1960 | ||
1961 | <para>All properties correspond directly with the matching properties of service units</para> | |
1962 | ||
1963 | <para><varname>Controller</varname> contains the bus name (unique or well-known) that is notified when | |
1964 | the scope unit is to be shut down via a <function>RequestStop</function> signal (see below). This is | |
1965 | set when the scope is created. If not set the scope's processes will terminated with | |
1966 | <constant>SIGTERM</constant> directly.</para> | |
1967 | </refsect2> | |
1968 | </refsect1> | |
1969 | ||
1970 | ||
1971 | <refsect1> | |
1972 | <title>Job Objects</title> | |
1973 | ||
1974 | <para>Job objects encapsulate scheduled or running jobs. Each unit can have none or one jobs in the | |
1975 | execution queue. Each job is attached to exactly one unit.</para> | |
1976 | ||
1977 | <programlisting> | |
1978 | $ gdbus introspect --system --dest org.freedesktop.systemd1 \ | |
1979 | --object-path /org/freedesktop/systemd1/job/1292 | |
1980 | ||
1981 | node /org/freedesktop/systemd1/job/1292 { | |
1982 | interface org.freedesktop.systemd1.Job { | |
1983 | methods: | |
1984 | Cancel(); | |
1985 | signals: | |
1986 | properties: | |
1987 | readonly u Id = 1292; | |
1988 | readonly (so) Unit = ('slow.service', '/org/freedesktop/systemd1/unit/slow_2eservice'); | |
1989 | readonly s JobType = 'start'; | |
1990 | readonly s State = 'running'; | |
1991 | }; | |
1992 | interface org.freedesktop.DBus.Properties { | |
1993 | ... | |
1994 | }; | |
1995 | interface org.freedesktop.DBus.Peer { | |
1996 | ... | |
1997 | }; | |
1998 | interface org.freedesktop.DBus.Introspectable { | |
1999 | ... | |
2000 | }; | |
2001 | }; | |
2002 | </programlisting> | |
2003 | ||
2004 | <refsect2> | |
2005 | <title>Methods</title> | |
2006 | ||
2007 | <para><function>Cancel()</function> cancels the job. Note that this will remove a job from the queue if | |
2008 | it is not yet executed but generally will not cause a job that is already in the process of being | |
2009 | executed to be aborted. This operation may also be requested via the <function>CancelJob()</function> | |
2010 | method of the Manager object (see above), which is sometimes useful to reduce roundtrips.</para> | |
2011 | </refsect2> | |
2012 | ||
2013 | <refsect2> | |
2014 | <title>Properties</title> | |
2015 | ||
2016 | <para><varname>Id</varname> is the numeric Id of the job. During the runtime of a systemd instance each | |
2017 | numeric ID is only assigned once.</para> | |
2018 | ||
2019 | <para><varname>Unit</varname> refers to the unit this job belongs two. It is a structure consisting of | |
2020 | the name of the unit and a bus path to the unit's object.</para> | |
2021 | ||
2022 | <para><varname>JobType</varname> refers to the job's type and is one of <literal>start</literal>, | |
2023 | <literal>verify-active</literal>, <literal>stop</literal>, <literal>reload</literal>, | |
2024 | <literal>restart</literal>, <literal>try-restart</literal>, <literal>reload-or-start</literal>. Note | |
2025 | that later versions might define additional values.</para> | |
2026 | ||
2027 | <para><varname>State</varname> refers to the job's state and is one of <literal>waiting</literal> and | |
2028 | <literal>running</literal>. The former indicates that a job is currently queued but has not begun to | |
2029 | execute yet, the latter indicates that a job is currently being executed.</para> | |
2030 | </refsect2> | |
2031 | </refsect1> | |
2032 | ||
2033 | <refsect1> | |
2034 | <title>Versioning</title> | |
2035 | ||
2036 | <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> | |
2037 | the usual interface versioning guidelines</ulink>.</para> | |
2038 | </refsect1> | |
2039 | </refentry> |