Crate systemd_transient

Expand description

§systemd-transient

Start transient systemd services using dbus, just like systemd-run.

§Usage

use systemd_transient::{ExecCommand, ServiceType, SystemdTransientManager, UnitExit, UnitProperty};

async fn example() -> Result<(), systemd_transient::Error> {
  let manager = SystemdTransientManager::session().await?;

  let unit = manager
    .start(
      "my-job", // becomes my-job.service
      [
        UnitProperty::Description("example job".into()),
        UnitProperty::Type(ServiceType::Exec),
        UnitProperty::ExecStart(vec![ExecCommand::new("/usr/bin/sleep", ["10"])]),
      ],
    )
    .await?;

  match unit.wait_for_exit().await? {
    UnitExit::Inactive => println!("exited cleanly"),
    UnitExit::Failed => println!("failed"),
  }
  Ok(())
}

A name without a unit type suffix becomes a service. Other transient types keep their suffix, e.g. start("vm.slice", []). Start a transient slice before any unit names it in Slice=: a slice that is only referenced is created implicitly and is not transient. Use escape_unit_name for user-supplied parts of a name; in slice names - means nesting.

ExecCommand::new uses the path as argv[0]; build an ExecCommand by hand for a different argv[0] or ignore_failure.

start returns once the start job has finished, i.e. when systemd considers the unit started; for Type=oneshot that is after the command has run. Dropping or releasing the handle does not stop the unit.

start and stop have no client-side timeout. systemd applies the unit’s TimeoutStartUSec, TimeoutStopUSec and JobTimeoutUSec and fails the job with JobWaitFailed { reason: "timeout", .. }. A Type=oneshot unit has no start timeout unless you set one. If you wrap start in your own timeout and drop the future, the job keeps running and you lose the handle.

start reuses the name of a unit that is loaded but failed or inactive, and fails with UnitAlreadyRunning if the unit is running.

The handle starts the unit with AddRef=true, so systemd keeps it loaded after it exits and wait_for_exit and stop can report its final state at any time. Release the reference with handle.release().await or by dropping the handle (released in a background task). Until then, start with the same name fails with UnitStillLoaded. With Restart= and the default RestartMode=normal, the unit passes through failed or inactive between runs, so wait_for_exit returns after the first run.

stop only stops the run the handle started. If someone else started the unit again (systemctl start), it returns UnitRestarted and leaves the new run alone.

Properties not covered by UnitProperty can be passed as UnitProperty::Custom(name, value).

§Reusing a name

ReusableTransientUnit (from manager.new_reusable(name, props)) starts the same unit again and again. status() reads the last run’s state from the exit watch without a D-Bus call, release() drops the reference without stopping the unit, and stop() stops it and releases it.

§Taking over units

A handle’s reference ends with its bus connection, so units outlive the process that started them. manager.adopt(name), or ReusableTransientUnit::adopt(), takes over such a unit with a new reference and reports its exit as start would. A failed unit stays loaded until it is reset and can be adopted later; a unit that exited cleanly is collected once nothing references it, and adopt then returns None.

manager.list_units(&["prefix-*"]) lists loaded units by pattern, e.g. to find units no handle claims, and manager.stop_unit(name) stops any unit by its full name.

§License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports§

pub use zbus;

Structs§

BindPath
BpfProgram
Condition
DeviceAllow
DeviceValue: Device path plus weight, bandwidth, IOPS or latency, depending on the key.
DirectoryQuota: {State,Cache,Logs}DirectoryQuota=. Encoded as (tus); enforce travels as “yes”/“no”.
DirectorySymlink
EnvironmentFile
ExecCommand
ExecCommandEx
ExitStatusSet
ExtensionImage
FilterList: SystemCallFilter, SystemCallLog, RestrictAddressFamilies, RestrictFileSystems, RestrictNetworkInterfaces.
ImportCredential
IpPrefix: Encoded as (iayu): address family, address bytes, prefix length.
ListedUnit: A unit as SystemdTransientManager::list_units reports it.
LoadCredential
LogFilterPattern
MountImage
MountOption
NftSet
OpenFile
ProtectHostnameEx
RefreshOnReload
ReusableTransientUnit
SecurityLabel
SetCredential
SocketBind
SystemdTransientManager
TmpFs
TransientUnitHandle: Holds a reference on the unit (AddRef=true), so systemd keeps it loaded after it exits. Release it with release or by dropping the handle; until then, starting a unit of the same name fails with UnitStillLoaded.
Usec: Microseconds. Usec::INFINITY disables the timeout.

Enums§

CgroupDevicePolicy: Non-exhaustive: new systemd releases add values.
CgroupPressureWatch: Non-exhaustive: new systemd releases add values.
CollectMode: Non-exhaustive: new systemd releases add values.
CpusetPartition: Non-exhaustive: new systemd releases add values.
EmergencyAction: Non-exhaustive: new systemd releases add values.
Error
ExecCommandFlag: Non-exhaustive: new systemd releases add values.
ExecKeyringMode: Non-exhaustive: new systemd releases add values.
ExecMemoryThp: Non-exhaustive: new systemd releases add values.
ExecPreserveMode: Non-exhaustive: new systemd releases add values.
ExecUtmpMode: Non-exhaustive: new systemd releases add values.
JobMode: Non-exhaustive: new systemd releases add values.
KillMode: Non-exhaustive: new systemd releases add values.
ManagedOomMode: Non-exhaustive: new systemd releases add values.
ManagedOomPreference: Non-exhaustive: new systemd releases add values.
NotifyAccess: Non-exhaustive: new systemd releases add values.
OomPolicy: Non-exhaustive: new systemd releases add values.
PrivateBpf: Non-exhaustive: new systemd releases add values.
PrivatePids: Non-exhaustive: new systemd releases add values.
PrivateTmp: Non-exhaustive: new systemd releases add values.
PrivateUsers: Non-exhaustive: new systemd releases add values.
ProcSubset: Non-exhaustive: new systemd releases add values.
ProtectControlGroups: Non-exhaustive: new systemd releases add values.
ProtectHome: Non-exhaustive: new systemd releases add values.
ProtectHostname: Non-exhaustive: new systemd releases add values.
ProtectProc: Non-exhaustive: new systemd releases add values.
ProtectSystem: Non-exhaustive: new systemd releases add values.
ServiceExitType: Non-exhaustive: new systemd releases add values.
ServiceRestart: Non-exhaustive: new systemd releases add values.
ServiceRestartMode: Non-exhaustive: new systemd releases add values.
ServiceTimeoutFailureMode: Non-exhaustive: new systemd releases add values.
ServiceType: Non-exhaustive: new systemd releases add values.
UnitExit: The state a unit ended in. These are systemd’s only two inactive states.
UnitProperty: Every key StartTransientUnit accepts for a .service unit.
UnitStatus

Constants§

MS_REC

Functions§

escape_unit_name: Escapes s for use as part of a unit name, like systemd-escape without --path: / becomes -, and every byte other than ASCII letters, digits, :, _ and a non-leading . becomes \xNN.