openapi: 3.1.0
info:
title: systemd Manager (org.freedesktop.systemd1)
version: '1.0'
summary: D-Bus API of PID 1 (the systemd Manager) modeled as REST operations.
description: |
This OpenAPI document models the well-known systemd D-Bus interface set at bus name
`org.freedesktop.systemd1` (system bus). It is a documentation/contract artifact: callers do not actually
issue HTTPS requests against a server, they invoke D-Bus methods against PID 1. Paths here mirror the
canonical object path layout (`/org/freedesktop/systemd1/...`) and the operationId names match the
documented D-Bus method names.
Bus name: `org.freedesktop.systemd1`. Root object path: `/org/freedesktop/systemd1`. The Manager
interface enumerates units, manages jobs, loads/reloads configuration, and emits lifecycle signals.
Per-unit objects implement the `Unit` interface plus a type-specific interface (`Service`, `Socket`,
`Mount`, `Slice`, `Scope`, `Path`, `Swap`, `Timer`, `Target`).
contact:
name: systemd developers
url: https://lists.freedesktop.org/mailman/listinfo/systemd-devel
license:
name: LGPL-2.1-or-later
url: https://github.com/systemd/systemd/blob/main/LICENSES/LGPL-2.1-or-later.txt
servers:
- url: dbus://system/org.freedesktop.systemd1
description: System D-Bus (PID 1)
tags:
- name: Manager
description: Top-level Manager object methods.
- name: Units
description: Unit lifecycle and enumeration.
- name: Jobs
description: Pending and active jobs scheduled by the Manager.
- name: Configuration
description: Loading, reloading, and reexecuting the manager.
- name: Cgroups
description: Transient unit creation and cgroup-backed resource control.
- name: Snapshots
description: System state introspection.
paths:
/units:
get:
tags: [Units]
operationId: ListUnits
summary: List All Loaded Units
description: Returns an array of all currently loaded units. Mirrors `ListUnits()` on the Manager.
responses:
'200':
description: Array of units (name, description, load state, active state, sub state, follower, object path, job id, job type, job object path).
content:
application/json:
schema:
type: array
items: { $ref: '#/components/schemas/Unit' }
/units/{name}:
parameters:
- { name: name, in: path, required: true, schema: { type: string }, description: Unit name (e.g. `nginx.service`). }
get:
tags: [Units]
operationId: GetUnit
summary: Get A Loaded Unit By Name
description: Returns the D-Bus object path of an already-loaded unit. Mirrors `GetUnit(name)`.
responses:
'200': { description: Object path of the unit., content: { application/json: { schema: { $ref: '#/components/schemas/UnitPath' } } } }
'404': { description: Unit not loaded. }
/units/{name}/load:
parameters:
- { name: name, in: path, required: true, schema: { type: string } }
post:
tags: [Units]
operationId: LoadUnit
summary: Load A Unit From Disk
description: Forces the Manager to load the named unit and returns its object path. Mirrors `LoadUnit(name)`.
responses:
'200': { description: Loaded unit object path., content: { application/json: { schema: { $ref: '#/components/schemas/UnitPath' } } } }
/units/{name}/start:
parameters:
- { name: name, in: path, required: true, schema: { type: string } }
post:
tags: [Units]
operationId: StartUnit
summary: Start A Unit
description: Enqueues a start job for the unit. Mirrors `StartUnit(name, mode)`. Mode is one of `replace`, `fail`, `isolate`, `ignore-dependencies`, `ignore-requirements`.
requestBody:
content: { application/json: { schema: { $ref: '#/components/schemas/JobModeRequest' } } }
responses:
'202': { description: Job enqueued; returns job object path., content: { application/json: { schema: { $ref: '#/components/schemas/JobPath' } } } }
/units/{name}/stop:
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
post:
tags: [Units]
operationId: StopUnit
summary: Stop A Unit
description: Enqueues a stop job. Mirrors `StopUnit(name, mode)`.
requestBody: { content: { application/json: { schema: { $ref: '#/components/schemas/JobModeRequest' } } } }
responses: { '202': { description: Job enqueued., content: { application/json: { schema: { $ref: '#/components/schemas/JobPath' } } } } }
/units/{name}/restart:
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
post:
tags: [Units]
operationId: RestartUnit
summary: Restart A Unit
description: Stops then starts. Mirrors `RestartUnit(name, mode)`.
requestBody: { content: { application/json: { schema: { $ref: '#/components/schemas/JobModeRequest' } } } }
responses: { '202': { description: Job enqueued., content: { application/json: { schema: { $ref: '#/components/schemas/JobPath' } } } } }
/units/{name}/reload:
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
post:
tags: [Units]
operationId: ReloadUnit
summary: Reload A Unit
description: Asks a unit to reload its configuration (e.g. SIGHUP for services). Mirrors `ReloadUnit(name, mode)`.
requestBody: { content: { application/json: { schema: { $ref: '#/components/schemas/JobModeRequest' } } } }
responses: { '202': { description: Job enqueued., content: { application/json: { schema: { $ref: '#/components/schemas/JobPath' } } } } }
/units/{name}/reload-or-restart:
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
post:
tags: [Units]
operationId: ReloadOrRestartUnit
summary: Reload Or Restart A Unit
description: Reloads if supported, otherwise restarts. Mirrors `ReloadOrRestartUnit(name, mode)`.
requestBody: { content: { application/json: { schema: { $ref: '#/components/schemas/JobModeRequest' } } } }
responses: { '202': { description: Job enqueued., content: { application/json: { schema: { $ref: '#/components/schemas/JobPath' } } } } }
/units/{name}/kill:
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
post:
tags: [Units]
operationId: KillUnit
summary: Send A Signal To A Unit
description: Sends a UNIX signal to the unit's main, control, or all processes. Mirrors `KillUnit(name, who, signal)`.
requestBody:
content:
application/json:
schema:
type: object
required: [who, signal]
properties:
who: { type: string, enum: [main, control, all] }
signal: { type: integer, description: UNIX signal number (e.g. 15 = SIGTERM, 9 = SIGKILL). }
responses: { '204': { description: Signal sent. } }
/units/{name}/freeze:
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
post:
tags: [Units]
operationId: FreezeUnit
summary: Freeze A Unit's Cgroup
description: Suspends all processes in the unit's cgroup using the cgroup v2 freezer. Mirrors `FreezeUnit(name)`.
responses: { '204': { description: Frozen. } }
/units/{name}/thaw:
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
post:
tags: [Units]
operationId: ThawUnit
summary: Thaw A Unit's Cgroup
description: Resumes a frozen cgroup. Mirrors `ThawUnit(name)`.
responses: { '204': { description: Thawed. } }
/units/{name}/properties:
parameters: [{ name: name, in: path, required: true, schema: { type: string } }]
get:
tags: [Units]
operationId: GetAllUnitProperties
summary: Get All Properties Of A Unit
description: Returns the full property bag for a unit. Equivalent to `org.freedesktop.DBus.Properties.GetAll`.
responses: { '200': { description: Unit property map., content: { application/json: { schema: { type: object, additionalProperties: true } } } } }
patch:
tags: [Units]
operationId: SetUnitProperties
summary: Set Runtime Properties On A Unit
description: Sets one or more properties at runtime. Mirrors `SetUnitProperties(name, runtime, properties)`. Used for live cgroup resource changes (CPUWeight, MemoryMax, etc.).
requestBody:
content:
application/json:
schema:
type: object
properties:
runtime: { type: boolean, description: If true, changes apply only until reboot. }
properties: { type: object, additionalProperties: true }
responses: { '204': { description: Properties updated. } }
/units/transient:
post:
tags: [Cgroups, Units]
operationId: StartTransientUnit
summary: Start A Transient Unit
description: Creates and starts a new transient unit (typically a scope or service) with the supplied properties. Mirrors `StartTransientUnit(name, mode, properties, aux)`.
requestBody:
content:
application/json:
schema:
type: object
required: [name, mode]
properties:
name: { type: string }
mode: { type: string, enum: [replace, fail, isolate, ignore-dependencies, ignore-requirements] }
properties: { type: object, additionalProperties: true }
aux: { type: array, items: { type: object } }
responses: { '202': { description: Job enqueued., content: { application/json: { schema: { $ref: '#/components/schemas/JobPath' } } } } }
/jobs:
get:
tags: [Jobs]
operationId: ListJobs
summary: List Pending And Running Jobs
description: Mirrors `ListJobs()`.
responses: { '200': { description: Array of jobs., content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/Job' } } } } } }
/jobs/{id}/cancel:
parameters: [{ name: id, in: path, required: true, schema: { type: integer } }]
post:
tags: [Jobs]
operationId: CancelJob
summary: Cancel A Pending Job
description: Mirrors `CancelJob(id)`.
responses: { '204': { description: Job cancelled. } }
/manager/reload:
post:
tags: [Configuration, Manager]
operationId: Reload
summary: Reload Manager Configuration
description: Reloads all unit files from disk without restarting services. Mirrors `Reload()`.
responses: { '204': { description: Reloaded. } }
/manager/reexecute:
post:
tags: [Configuration, Manager]
operationId: Reexecute
summary: Reexecute The Manager
description: Re-executes the systemd binary in-place, preserving state. Mirrors `Reexecute()`.
responses: { '204': { description: Reexecuted. } }
/manager/enable:
post:
tags: [Configuration, Manager]
operationId: EnableUnitFiles
summary: Enable Unit Files
description: Creates the symlinks that make units start at boot. Mirrors `EnableUnitFiles(files, runtime, force)`.
requestBody: { content: { application/json: { schema: { type: object, properties: { files: { type: array, items: { type: string } }, runtime: { type: boolean }, force: { type: boolean } } } } } }
responses: { '200': { description: Carries-install info and change set., content: { application/json: { schema: { type: object, additionalProperties: true } } } } }
/manager/disable:
post:
tags: [Configuration, Manager]
operationId: DisableUnitFiles
summary: Disable Unit Files
description: Removes the symlinks that make units start at boot. Mirrors `DisableUnitFiles(files, runtime)`.
requestBody: { content: { application/json: { schema: { type: object, properties: { files: { type: array, items: { type: string } }, runtime: { type: boolean } } } } } }
responses: { '200': { description: Change set., content: { application/json: { schema: { type: object, additionalProperties: true } } } } }
/manager/mask:
post:
tags: [Configuration, Manager]
operationId: MaskUnitFiles
summary: Mask Unit Files
description: Symlinks units to /dev/null so they cannot be started. Mirrors `MaskUnitFiles(files, runtime, force)`.
requestBody: { content: { application/json: { schema: { type: object, properties: { files: { type: array, items: { type: string } }, runtime: { type: boolean }, force: { type: boolean } } } } } }
responses: { '200': { description: Change set., content: { application/json: { schema: { type: object, additionalProperties: true } } } } }
/manager/unmask:
post:
tags: [Configuration, Manager]
operationId: UnmaskUnitFiles
summary: Unmask Unit Files
description: Reverses MaskUnitFiles. Mirrors `UnmaskUnitFiles(files, runtime)`.
responses: { '200': { description: Change set., content: { application/json: { schema: { type: object, additionalProperties: true } } } } }
/manager/set-default-target:
post:
tags: [Configuration, Manager]
operationId: SetDefaultTarget
summary: Set The Default Boot Target
description: Mirrors `SetDefaultTarget(target, force)`.
requestBody: { content: { application/json: { schema: { type: object, properties: { target: { type: string }, force: { type: boolean } } } } } }
responses: { '200': { description: Change set., content: { application/json: { schema: { type: object, additionalProperties: true } } } } }
/manager/default-target:
get:
tags: [Configuration, Manager]
operationId: GetDefaultTarget
summary: Get The Default Boot Target
description: Mirrors `GetDefaultTarget()`.
responses: { '200': { description: Target unit name., content: { application/json: { schema: { type: object, properties: { target: { type: string } } } } } } }
/manager/snapshot:
get:
tags: [Snapshots, Manager]
operationId: GetManagerProperties
summary: Get Manager Properties
description: Returns the full property map of the Manager (Version, Features, Virtualization, Architecture, Tainted, FirmwareTimestamp, etc.).
responses: { '200': { description: Property map., content: { application/json: { schema: { type: object, additionalProperties: true } } } } }
components:
schemas:
UnitPath:
type: object
properties: { path: { type: string, description: D-Bus object path. } }
JobPath:
type: object
properties: { path: { type: string, description: D-Bus object path of the job. } }
JobModeRequest:
type: object
properties:
mode: { type: string, enum: [replace, fail, isolate, ignore-dependencies, ignore-requirements], default: replace }
Unit:
type: object
properties:
name: { type: string }
description: { type: string }
load_state: { type: string, enum: [stub, loaded, not-found, bad-setting, error, merged, masked] }
active_state: { type: string, enum: [active, reloading, inactive, failed, activating, deactivating] }
sub_state: { type: string }
follower: { type: string, nullable: true }
object_path: { type: string }
job_id: { type: integer }
job_type: { type: string }
job_object_path: { type: string }
Job:
type: object
properties:
id: { type: integer }
unit: { type: string }
type: { type: string, enum: [start, verify-active, stop, reload, restart, try-restart, reload-or-start] }
state: { type: string, enum: [waiting, running] }
object_path: { type: string }
unit_object_path: { type: string }