интерфейс D-Bus системы systemd (The D-Bus interface of systemd)
Объект менеджера (The manager object)
The main entry point object is available on the fixed
/org/freedesktop/systemd1 object path:
node /org/freedesktop/systemd1 {
interface org.freedesktop.systemd1.Manager {
methods:
GetUnit(in s name,
out o unit);
GetUnitByPID(in u pid,
out o unit);
GetUnitByInvocationID(in ay invocation_id,
out o unit);
GetUnitByControlGroup(in s cgroup,
out o unit);
LoadUnit(in s name,
out o unit);
StartUnit(in s name,
in s mode,
out o job);
StartUnitReplace(in s old_unit,
in s new_unit,
in s mode,
out o job);
StopUnit(in s name,
in s mode,
out o job);
ReloadUnit(in s name,
in s mode,
out o job);
RestartUnit(in s name,
in s mode,
out o job);
TryRestartUnit(in s name,
in s mode,
out o job);
ReloadOrRestartUnit(in s name,
in s mode,
out o job);
ReloadOrTryRestartUnit(in s name,
in s mode,
out o job);
EnqueueUnitJob(in s name,
in s job_type,
in s job_mode,
out u job_id,
out o job_path,
out s unit_id,
out o unit_path,
out s job_type,
out a(uosos) affected_jobs);
KillUnit(in s name,
in s whom,
in i signal);
CleanUnit(in s name,
in as mask);
FreezeUnit(in s name);
ThawUnit(in s name);
ResetFailedUnit(in s name);
SetUnitProperties(in s name,
in b runtime,
in a(sv) properties);
BindMountUnit(in s name,
in s source,
in s destination,
in b read_only,
in b mkdir);
MountImageUnit(in s name,
in s source,
in s destination,
in b read_only,
in b mkdir,
in a(ss) options);
RefUnit(in s name);
UnrefUnit(in s name);
StartTransientUnit(in s name,
in s mode,
in a(sv) properties,
in a(sa(sv)) aux,
out o job);
GetUnitProcesses(in s name,
out a(sus) processes);
AttachProcessesToUnit(in s unit_name,
in s subcgroup,
in au pids);
AbandonScope(in s name);
GetJob(in u id,
out o job);
GetJobAfter(in u id,
out a(usssoo) jobs);
GetJobBefore(in u id,
out a(usssoo) jobs);
CancelJob(in u id);
ClearJobs();
ResetFailed();
SetShowStatus(in s mode);
ListUnits(out a(ssssssouso) units);
ListUnitsFiltered(in as states,
out a(ssssssouso) units);
ListUnitsByPatterns(in as states,
in as patterns,
out a(ssssssouso) units);
ListUnitsByNames(in as names,
out a(ssssssouso) units);
ListJobs(out a(usssoo) jobs);
Subscribe();
Unsubscribe();
Dump(out s output);
DumpByFileDescriptor(out h fd);
Reload();
Reexecute();
Exit();
Reboot();
PowerOff();
Halt();
KExec();
SwitchRoot(in s new_root,
in s init);
SetEnvironment(in as assignments);
UnsetEnvironment(in as names);
UnsetAndSetEnvironment(in as names,
in as assignments);
EnqueueMarkedJobs(out ao jobs);
ListUnitFiles(out a(ss) unit_files);
ListUnitFilesByPatterns(in as states,
in as patterns,
out a(ss) unit_files);
GetUnitFileState(in s file,
out s state);
EnableUnitFiles(in as files,
in b runtime,
in b force,
out b carries_install_info,
out a(sss) changes);
DisableUnitFiles(in as files,
in b runtime,
out a(sss) changes);
EnableUnitFilesWithFlags(in as files,
in t flags,
out b carries_install_info,
out a(sss) changes);
DisableUnitFilesWithFlags(in as files,
in t flags,
out a(sss) changes);
ReenableUnitFiles(in as files,
in b runtime,
in b force,
out b carries_install_info,
out a(sss) changes);
LinkUnitFiles(in as files,
in b runtime,
in b force,
out a(sss) changes);
PresetUnitFiles(in as files,
in b runtime,
in b force,
out b carries_install_info,
out a(sss) changes);
PresetUnitFilesWithMode(in as files,
in s mode,
in b runtime,
in b force,
out b carries_install_info,
out a(sss) changes);
MaskUnitFiles(in as files,
in b runtime,
in b force,
out a(sss) changes);
UnmaskUnitFiles(in as files,
in b runtime,
out a(sss) changes);
RevertUnitFiles(in as files,
out a(sss) changes);
SetDefaultTarget(in s name,
in b force,
out a(sss) changes);
GetDefaultTarget(out s name);
PresetAllUnitFiles(in s mode,
in b runtime,
in b force,
out a(sss) changes);
AddDependencyUnitFiles(in as files,
in s target,
in s type,
in b runtime,
in b force,
out a(sss) changes);
GetUnitFileLinks(in s name,
in b runtime,
out as links);
SetExitCode(in y number);
LookupDynamicUserByName(in s name,
out u uid);
LookupDynamicUserByUID(in u uid,
out s name);
GetDynamicUsers(out a(us) users);
signals:
UnitNew(s id,
o unit);
UnitRemoved(s id,
o unit);
JobNew(u id,
o job,
s unit);
JobRemoved(u id,
o job,
s unit,
s result);
StartupFinished(t firmware,
t loader,
t kernel,
t initrd,
t userspace,
t total);
UnitFilesChanged();
Reloading(b active);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Version = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Features = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Virtualization = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Architecture = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Tainted = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t FirmwareTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t FirmwareTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t LoaderTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t LoaderTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t KernelTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t KernelTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t UserspaceTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t UserspaceTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t FinishTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t FinishTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t SecurityStartTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t SecurityStartTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t SecurityFinishTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t SecurityFinishTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t GeneratorsStartTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t GeneratorsStartTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t GeneratorsFinishTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t GeneratorsFinishTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t UnitsLoadStartTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t UnitsLoadStartTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t UnitsLoadFinishTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t UnitsLoadFinishTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDSecurityStartTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDSecurityStartTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDSecurityFinishTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDSecurityFinishTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDGeneratorsStartTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDGeneratorsStartTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDGeneratorsFinishTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDGeneratorsFinishTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDUnitsLoadStartTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDUnitsLoadStartTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDUnitsLoadFinishTimestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t InitRDUnitsLoadFinishTimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
@org.freedesktop.systemd1.Privileged("true")
readwrite s LogLevel = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
@org.freedesktop.systemd1.Privileged("true")
readwrite s LogTarget = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly u NNames = ...;
readonly u NFailedUnits = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly u NJobs = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly u NInstalledJobs = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly u NFailedJobs = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly d Progress = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly as Environment = ['...', ...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly b ConfirmSpawn = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly b ShowStatus = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly as UnitPath = ['...', ...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s DefaultStandardOutput = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s DefaultStandardError = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
@org.freedesktop.systemd1.Privileged("true")
readwrite t RuntimeWatchdogUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
@org.freedesktop.systemd1.Privileged("true")
readwrite t RebootWatchdogUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
@org.freedesktop.systemd1.Privileged("true")
readwrite t KExecWatchdogUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
@org.freedesktop.systemd1.Privileged("true")
readwrite b ServiceWatchdogs = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s ControlGroup = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s SystemState = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly y ExitCode = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultTimerAccuracyUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultTimeoutStartUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultTimeoutStopUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t DefaultTimeoutAbortUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultRestartUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultStartLimitIntervalUSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u DefaultStartLimitBurst = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly b DefaultCPUAccounting = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly b DefaultBlockIOAccounting = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly b DefaultMemoryAccounting = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly b DefaultTasksAccounting = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitCPU = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitCPUSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitFSIZE = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitFSIZESoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitDATA = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitDATASoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitSTACK = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitSTACKSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitCORE = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitCORESoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitRSS = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitRSSSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitNOFILE = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitNOFILESoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitAS = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitASSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitNPROC = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitNPROCSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitMEMLOCK = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitMEMLOCKSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitLOCKS = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitLOCKSSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitSIGPENDING = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitSIGPENDINGSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitMSGQUEUE = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitMSGQUEUESoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitNICE = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitNICESoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitRTPRIO = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitRTPRIOSoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitRTTIME = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t DefaultLimitRTTIMESoft = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t DefaultTasksMax = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t TimerSlackNSec = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s DefaultOOMPolicy = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s CtrlAltDelBurstAction = '...';
};
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
};
Methods
Note that many of the methods exist twice: once on the Manager
object and once on the respective unit objects. This is to
optimize access times so that methods that belong to unit objects
do not have to be called with a resolved unit path, but can be
called with only the unit id, too.
GetUnit() may be used to get the unit object path for a unit
name. It takes the unit name and returns the object path. If a
unit has not been loaded yet by this name this method will fail.
GetUnitByPID() may be used to get the unit object path of the
unit a process ID belongs to. It takes a UNIX PID and returns the
object path. The PID must refer to an existing system process.
LoadUnit() is similar to GetUnit() but will load the unit from
disk if possible.
StartUnit() enqueues a start job and possibly depending jobs. It
takes the unit to activate and a mode string as arguments. The
mode needs to be one of "replace", "fail", "isolate",
"ignore-dependencies", or "ignore-requirements". If "replace",
the method will start the unit and its dependencies, possibly
replacing already queued jobs that conflict with it. If "fail",
the method will start the unit and its dependencies, but will
fail if this would change an already queued job. If "isolate",
the method will start the unit in question and terminate all
units that aren't dependencies of it. If "ignore-dependencies",
it will start a unit but ignore all its dependencies. If
"ignore-requirements", it will start a unit but only ignore the
requirement dependencies. It is not recommended to make use of
the latter two options. On completion, this method returns the
newly created job object.
StartUnitReplace() is similar to StartUnit() but replaces a job
that is queued for one unit by a job for another unit.
StopUnit() is similar to StartUnit() but stops the specified unit
rather than starting it. Note that the "isolate" mode is invalid
for this method.
ReloadUnit(), RestartUnit(), TryRestartUnit(),
ReloadOrRestartUnit(), or ReloadOrTryRestartUnit() may be used to
restart and/or reload a unit. These methods take similar
arguments as StartUnit(). Reloading is done only if the unit is
already running and fails otherwise. If a service is restarted
that isn't running, it will be started unless the "Try" flavor is
used in which case a service that isn't running is not affected
by the restart. The "ReloadOrRestart" flavors attempt a reload if
the unit supports it and use a restart otherwise.
EnqueueMarkedJobs() creates reload/restart jobs for units which
have been appropriately marked, see Marks property above. This is
equivalent to calling TryRestartUnit() or
ReloadOrTryRestartUnit() for the marked units.
BindMountUnit() can be used to bind mount new files or
directories into a running service mount namespace.
MountImageUnit() can be used to mount new images into a running
service mount namespace.
KillUnit() may be used to kill (i.e. send a signal to) all
processes of a unit. It takes the unit name, an enum who and a
UNIX signal number to send. The who enum is one of "main",
"control" or "all". If "main", only the main process of the unit
is killed. If "control", only the control process of the unit is
killed. If "all", all processes are killed. A "control" process
is for example a process that is configured via ExecStop= and is
spawned in parallel to the main daemon process in order to shut
it down.
GetJob() returns the job object path for a specific job,
identified by its id.
CancelJob() cancels a specific job identified by its numeric ID.
This operation is also available in the Cancel() method of Job
objects (see below) and exists primarily to reduce the necessary
round trips to execute this operation. Note that this will not
have any effect on jobs whose execution has already begun.
ClearJobs() flushes the job queue, removing all jobs that are
still queued. Note that this does not have any effect on jobs
whose execution has already begun. It only flushes jobs that are
queued and have not yet begun execution.
ResetFailedUnit() resets the "failed" state of a specific unit.
ResetFailed() resets the "failed" state of all units.
ListUnits() returns an array of all currently loaded units. Note
that units may be known by multiple names at the same name, and
hence there might be more unit names loaded than actual units
behind them. The array consists of structures with the following
elements:
• The primary unit name as string
• The human readable description string
• The load state (i.e. whether the unit file has been loaded
successfully)
• The active state (i.e. whether the unit is currently started
or not)
• The sub state (a more fine-grained version of the active
state that is specific to the unit type, which the active
state is not)
• A unit that is being followed in its state by this unit, if
there is any, otherwise the empty string.
• The unit object path
• If there is a job queued for the job unit, the numeric job
id, 0 otherwise
• The job type as string
• The job object path
ListJobs() returns an array with all currently queued jobs.
Returns an array consisting of structures with the following
elements:
• The numeric job id
• The primary unit name for this job
• The job type as string
• The job state as string
• The job object path
• The unit object path
Subscribe() enables most bus signals to be sent out. Clients
which are interested in signals need to call this method. Signals
are only sent out if at least one client invoked this method.
Unsubscribe() reverts the signal subscription that Subscribe()
implements. It is not necessary to invoke Unsubscribe() as
clients are tracked. Signals are no longer sent out as soon as
all clients which previously asked for Subscribe() either closed
their connection to the bus or invoked Unsubscribe().
Reload() may be invoked to reload all unit files.
Reexecute() may be invoked to reexecute the main manager process.
It will serialize its state, reexecute, and deserizalize the
state again. This is useful for upgrades and is a more
comprehensive version of Reload().
Exit() may be invoked to ask the manager to exit. This is not
available for the system manager and is useful only for user
session managers.
Reboot(), PowerOff(), Halt(), or KExec() may be used to ask for
immediate reboot, powering down, halt or kexec based reboot of
the system. Note that this does not shut down any services and
immediately transitions into the reboot process. These functions
are normally only called as the last step of shutdown and should
not be called directly. To shut down the machine, it is generally
a better idea to invoke Reboot() or PowerOff() on the
systemd-logind manager object; see org.freedesktop.login1(5) for
more information.
SwitchRoot() may be used to transition to a new root directory.
This is intended to be used by initial RAM disks. The method
takes two arguments: the new root directory (which needs to be
specified) and an init binary path (which may be left empty, in
which case it is automatically searched for). The state of the
system manager will be serialized before the transition. After
the transition, the manager binary on the main system is invoked
and replaces the old PID 1. All state will then be deserialized.
SetEnvironment() may be used to alter the environment block that
is passed to all spawned processes. It takes a string array of
environment variable assignments. Any previously set environment
variables will be overridden.
UnsetEnvironment() may be used to unset environment variables. It
takes a string array of environment variable names. All variables
specified will be unset (if they have been set previously) and no
longer be passed to all spawned processes. This method has no
effect for variables that were previously not set, but will not
fail in that case.
UnsetAndSetEnvironment() is a combination of UnsetEnvironment()
and SetEnvironment(). It takes two lists. The first list contains
variables to unset, the second one contains assignments to set.
If a variable is listed in both, the variable is set after this
method returns, i.e. the set list overrides the unset list.
ListUnitFiles() returns an array of unit names and their
enablement status. Note that ListUnit() returns a list of units
currently loaded into memory, while ListUnitFiles() returns a
list of unit files that were found on disk. Note that while most
units are read directly from a unit file with the same name, some
units are not backed by files and some files (templates) cannot
directly be loaded as units but need to be instantiated instead.
GetUnitFileState() returns the current enablement status of a
specific unit file.
EnableUnitFiles() may be used to enable one or more units in the
system (by creating symlinks to them in /etc/ or /run/). It takes
a list of unit files to enable (either just file names or full
absolute paths if the unit files are residing outside the usual
unit search paths) and two booleans: the first controls whether
the unit shall be enabled for runtime only (true, /run/), or
persistently (false, /etc/). The second one controls whether
symlinks pointing to other units shall be replaced if necessary.
This method returns one boolean and an array of the changes made.
The boolean signals whether the unit files contained any
enablement information (i.e. an [Install]) section. The changes
array consists of structures with three strings: the type of the
change (one of "symlink" or "unlink"), the file name of the
symlink and the destination of the symlink. Note that most of the
following calls return a changes list in the same format.
Similarly, DisableUnitFiles() disables one or more units in the
system, i.e. removes all symlinks to them in /etc/ and /run/.
The EnableUnitFilesWithFlags() and DisableUnitFilesWithFlags()
take in options as flags instead of booleans to allow for
extendability, defined as follows:
#define SD_SYSTEMD_UNIT_RUNTIME (UINT64_C(1) << 0)
#define SD_SYSTEMD_UNIT_FORCE (UINT64_C(1) << 1)
#define SD_SYSTEMD_UNIT_PORTABLE (UINT64_C(1) << 2)
SD_SYSTEMD_UNIT_RUNTIME will enable or disable the unit for
runtime only, SD_SYSTEMD_UNIT_FORCE controls whether symlinks
pointing to other units shall be replaced if necessary.
SD_SYSTEMD_UNIT_PORTABLE will add or remove the symlinks in
/etc/systemd/system.attached and /run/systemd/system.attached.
Similarly, ReenableUnitFiles() applies the changes to one or more
units that would result from disabling and enabling the unit
quickly one after the other in an atomic fashion. This is useful
to apply updated [Install] information contained in unit files.
Similarly, LinkUnitFiles() links unit files (that are located
outside of the usual unit search paths) into the unit search
path.
Similarly, PresetUnitFiles() enables/disables one or more unit
files according to the preset policy. See systemd.preset(7) for
more information.
Similarly, MaskUnitFiles() masks unit files and UnmaskUnitFiles()
unmasks them again.
SetDefaultTarget() changes the default.target link. See bootup(7)
for more information.
GetDefaultTarget() retrieves the name of the unit to which
default.target is aliased.
SetUnitProperties() may be used to modify certain unit properties
at runtime. Not all properties may be changed at runtime, but
many resource management settings (primarily those listed in
systemd.resource-control(5)) may. The changes are applied
instantly and stored on disk for future boots, unless runtime is
true, in which case the settings only apply until the next
reboot. name is the name of the unit to modify. properties are
the settings to set, encoded as an array of property name and
value pairs. Note that this is not a dictionary! Also note that
when setting array properties with this method usually results in
appending to the pre-configured array. To reset the configured
arrays, set the property to an empty array first and then append
to it.
StartTransientUnit() may be used to create and start a transient
unit which will be released as soon as it is not running or
referenced anymore or the system is rebooted. name is the unit
name including its suffix and must be unique. mode is the same
as in StartUnit(), properties contains properties of the unit,
specified like in SetUnitProperties(). aux is currently unused
and should be passed as an empty array. See the New Control Group
Interface
Signals
Note that most signals are sent out only after Subscribe() has
been invoked by at least one client. Make sure to invoke this
method when subscribing to these signals!
UnitNew() and UnitRemoved() are sent out each time a new unit is
loaded or unloaded. Note that this has little to do with whether
a unit is available on disk or not, and simply reflects the units
that are currently loaded into memory. The signals take two
parameters: the primary unit name and the object path.
JobNew() and JobRemoved() are sent out each time a new job is
queued or dequeued. Both signals take the numeric job ID, the bus
path and the primary unit name for this job as arguments.
JobRemoved() also includes a result string which is one of
"done", "canceled", "timeout", "failed", "dependency", or
"skipped". "done" indicates successful execution of a job.
"canceled" indicates that a job has been canceled (via
CancelJob() above) before it finished execution (this doesn't
necessarily mean though that the job operation is actually
cancelled too, see above). "timeout" indicates that the job
timeout was reached. "failed" indicates that the job failed.
"dependency" indicates that a job this job depended on failed and
the job hence was removed as well. "skipped" indicates that a
job was skipped because it didn't apply to the unit's current
state.
StartupFinished() is sent out when startup finishes. It carries
six microsecond timespan values, each indicating how much boot
time has been spent in the firmware (if known), in the boot
loader (if known), in the kernel initialization phase, in the
initrd (if known), in userspace and in total. These values may
also be calculated from the FirmwareTimestampMonotonic,
LoaderTimestampMonotonic, InitRDTimestampMonotonic,
UserspaceTimestampMonotonic, and FinishTimestampMonotonic
properties (see below).
UnitFilesChanged() is sent out each time the list of enabled or
masked unit files on disk have changed.
Reloading() is sent out immediately before a daemon reload is
done (with the boolean parameter set to True) and after a daemon
reload is completed (with the boolean parameter set to False).
This may be used by UIs to optimize UI updates.
Properties
Most properties simply reflect the respective options in
/etc/systemd/system.conf and the kernel command line.
The others:
Version encodes the version string of the running systemd
instance. Note that the version string is purely informational.
It should not be parsed and one may not assume the version to be
formatted in any particular way. We take the liberty to change
the versioning scheme at any time and it is not part of the
public API.
Features encodes the features that have been enabled and disabled
for this build. Enabled options are prefixed with +, disabled
options with -.
Tainted encodes a couple of taint flags as a colon-separated
list. When systemd detects it is running on a system with certain
problems, it will set an appropriate taint flag. Taints may be
used to lower the chance of bogus bug reports. The following
taints are currently known: "split-usr", "mtab-not-symlink",
"cgroups-missing", "local-hwclock". "split-usr" is set if /usr/
is not pre-mounted when systemd is first invoked. See Booting
Without /usr is Broken
FirmwareTimestamp, FirmwareTimestampMonotonic, LoaderTimestamp,
LoaderTimestampMonotonic, KernelTimestamp,
KernelTimestampMonotonic, InitRDTimestamp,
InitRDTimestampMonotonic, UserspaceTimestamp,
UserspaceTimestampMonotonic, FinishTimestamp, and
FinishTimestampMonotonic encode CLOCK_REALTIME and
CLOCK_MONOTONIC microsecond timestamps taken when the firmware
first began execution, when the boot loader first began
execution, when the kernel first began execution, when the initrd
first began execution, when the main systemd instance began
execution and finally, when all queued startup jobs finished
execution. These values are useful for determining boot-time
performance. Note that as monotonic time begins with the kernel
startup, the KernelTimestampMonotonic timestamp will always be 0
and FirmwareTimestampMonotonic and LoaderTimestampMonotonic are
to be read as negative values. Also, not all fields are always
available, depending on the used firmware, boot loader or initrd
implementation. In these cases the respective pairs of timestamps
are both 0, indicating that no data is available.
Similarly, the SecurityStartTimestamp, GeneratorsStartTimestamp
and LoadUnitTimestamp (as well as their monotonic and stop
counterparts) expose performance data for uploading the security
policies to the kernel (such as the SELinux, IMA, or SMACK
policies), for running the generator tools and for loading the
unit files.
NNames encodes how many unit names are currently known. This only
includes names of units that are currently loaded and can be more
than the amount of actually loaded units since units may have
more than one name.
NJobs encodes how many jobs are currently queued.
NInstalledJobs encodes how many jobs have ever been queued in
total.
NFailedJobs encodes how many jobs have ever failed in total.
Progress encodes boot progress as a floating point value between
0.0 and 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 number of executed
and queued jobs. After startup, this field is always 1.0
indicating a finished boot.
Environment encodes the environment block passed to all executed
services. It may be altered with bus calls such as
SetEnvironment() (see above).
UnitPath encodes the currently active unit file search path. It
is an array of file system paths encoded as strings.
Virtualization contains a short ID string describing the
virtualization technology the system runs in. On bare-metal
hardware this is the empty string. Otherwise, it contains an
identifier such as "kvm", "vmware" and so on. For a full list of
IDs see systemd-detect-virt(1). Note that only the "innermost"
virtualization technology is exported here. This detects both
full-machine virtualizations (VMs) and shared-kernel
virtualization (containers).
Architecture contains a short ID string describing the
architecture the systemd instance is running on. This follows the
same vocabulary as ConditionArchitectures=.
ControlGroup contains the root control group path of this system
manager. Note that the root path is encoded as the empty string
here (not as "/"!), so that it can be appended to
/sys/fs/cgroup/systemd easily. This value will be set to the
empty string for the host instance and some other string for
container instances.
Security
Read access is generally granted to all clients. Additionally,
for unprivileged clients, some operations are allowed through the
polkit privilege system. Operations which modify unit state
(StartUnit(), StopUnit(), KillUnit(), RestartUnit() and similar,
SetProperty()) require org.freedesktop.systemd1.manage-units.
Operations which modify unit file enablement state
(EnableUnitFiles(), DisableUnitFiles(),
EnableUnitFilesWithFlags(), DisableUnitFilesWithFlags(),
ReenableUnitFiles(), LinkUnitFiles(), PresetUnitFiles,
MaskUnitFiles, and similar) require
org.freedesktop.systemd1.manage-unit-files. Operations which
modify the exported environment (SetEnvironment(),
UnsetEnvironment(), UnsetAndSetEnvironment()) require
org.freedesktop.systemd1.set-environment. Reload() and
Reexecute() require org.freedesktop.systemd1.reload-daemon.
