systemd

Operations for managing systemd services, journal, daemon configuration, and system-level settings like hostname, timezone, and locale.

import {
  getServiceInfo,
  enableService,
  disableService,
  startService,
  stopService,
  restartService,
  reloadService,
  daemonReload,
  journalRead,
  journalVacuum,
  setHostname,
  setTimezone,
  setLocale,
  getUnitPath,
  getSystemdConfigPath,
  getSystemdConfigDropInPath,
} from '@sysopkit/linux/systemd';

Service Options

Most service operations accept ServiceOptions with the following fields:

{ name: string | readonly string[]; scope?: 'system' | 'user'; user?: string }

• name — Single unit or list of units. Multiple units are queued in a single systemctl call (systemd v262 EnqueueUnitJobMany).
• scope — Defaults to "system". Use "user" for user-scoped units.
• user — Username for user-scope (determines home directory paths).

getServiceInfo()

Retrieves service state information from systemctl show.

const info = await getServiceInfo({ name: 'nginx.service' });
// { LoadState: 'loaded', ActiveState: 'active', SubState: 'running',
//   UnitFileState: 'enabled', MainPID: 1234 }

enableService()

IDEMPOTENT

Enables a service to start at boot. Skips if already enabled.

await enableService({ name: 'nginx.service' });

disableService()

IDEMPOTENT

Disables a service from starting at boot. Skips if already disabled.

await disableService({ name: 'nginx.service' });

startService()

IDEMPOTENT

Starts a service. Returns true if the service was started, false if already running. Pass an array to start several units with one systemctl call — returns one boolean per unit, in input order.

await startService({ name: 'nginx.service' });
await startService({ name: ['a.service', 'b.service'] });
// [true, false]

stopService()

IDEMPOTENT

Stops a running service. No-op if already stopped.

await stopService({ name: 'nginx.service' });

restartService()

Restarts a loaded service (systemctl restart; starts it if not running).

await restartService({ name: 'nginx.service' });

reloadService()

Reloads a loaded service’s configuration (systemctl reload).

await reloadService({ name: 'nginx.service' });

daemonReload()

Reloads systemd manager configuration. Required after creating, modifying, or deleting unit files.

await daemonReload();
await daemonReload({ scope: 'user' });

journalRead()

Reads journal entries. Supports cursor-based incremental reading. Output includes a trailing -- cursor: ... footer from --show-cursor.

const output = await journalRead({ afterCursor: '...', lines: 50 });

journalVacuum()

Cleans up old journal entries by size, time, or file count. Throws if no option is given.

await journalVacuum({ size: '500M', time: '7d' });

setHostname()

IDEMPOTENT

Sets the system hostname using hostnamectl hostname. No-op if already set to the desired value.

await setHostname({ name: 'web-01' });

setTimezone()

IDEMPOTENT

Sets the system timezone using timedatectl set-timezone. No-op if already set.

await setTimezone({ name: 'America/New_York' });

setLocale()

IDEMPOTENT

Sets a locale variable using localectl set-locale.

await setLocale({ name: 'LANG', value: 'en_US.UTF-8' });
// bare form sets LANG:
await setLocale({ locale: 'C.UTF-8' });

Utility Functions

getUnitPath(name, options?)

Returns the path to a systemd unit file. Absolute for system scope and for user scope when user is given (assumes /home/${user}); otherwise relative to the target user’s home directory.

const path = getUnitPath('nginx.service');
// '/etc/systemd/system/nginx.service'

const userPath = getUnitPath('foo.service', { scope: 'user', user: 'alice' });
// '/home/alice/.config/systemd/user/foo.service'

getSystemdConfigPath(configName, options?)

Returns the absolute path to a systemd daemon configuration file.

const path = getSystemdConfigPath('journald.conf');
// '/etc/systemd/journald.conf'

getSystemdConfigDropInPath(configName, dropInName)

Returns the absolute path to a daemon drop-in file (e.g., journald.conf.d/; not unit foo.service.d/ drop-ins under /etc/systemd/system/).

const path = getSystemdConfigDropInPath('journald.conf', 'sysops');
// '/etc/systemd/journald.conf.d/sysops.conf'

Configuration Types

The systemd module also exports TypeScript types for configuration files. See the following pages for details:

• journald — journald.conf(5) types
• logind — logind.conf(5) types
• resolved — resolved.conf(5) types
• timesyncd — timesyncd.conf(5) types
• sleep — systemd-sleep.conf(5) types
• system-conf — systemd-system.conf(5) types (system.conf/user.conf)
• coredump — coredump.conf(5) types
• zram-generator — zram-generator.conf(5) types
• sysusers — sysusers.d(5) parsing/serialization
• tmpfiles — tmpfiles.d(5) parsing/serialization
• networkd — systemd-networkd .link/.network/.netdev types