io.systemd.Machine¶

Property	Value
Go package	`github.com/rossedman/sdvarlink/systemd/latest/machine`
Socket	`/run/systemd/machine/io.systemd.Machine`
Available since	systemd v257
Methods · types · errors	12 · 5 · 12

Methods¶

Register¶

func (c *Client) Register(ctx context.Context, in RegisterIn) error

Parameters

Field	Type	Description
`name`	`string`
`id`	`?string`
`service`	`?string`
`class`	`string`
`leader`	`?int`	The leader PID as simple positive integer.
`leaderProcessId`	`?ProcessId`	The leader PID as ProcessId structure. If both the leader and leaderProcessId parameters are specified they must reference the same process. Typically one would only specify one or the other however. It's generally recommended to specify leaderProcessId as it references a process in a robust way without risk of identifier recycling.
`supervisor`	`?int`	The supervisor PID as simple positive integer.
`supervisorProcessId`	`?ProcessId`	The supervisor PID as ProcessId structure. If both the supervisor and supervisorProcessId parameters are specified they must reference the same process. Typically only one or the other would be specified. It's generally recommended to specify supervisorProcessId as it references a process in a robust way without risk of identifier recycling.
`rootDirectory`	`?string`
`ifIndices`	`?[]int`
`vSockCid`	`?int`
`sshAddress`	`?string`
`sshPrivateKeyPath`	`?string`
`allocateUnit`	`?bool`	Controls whether to allocate a scope unit for the machine to register. If false, the client already took care of that and registered a service/scope specific to the machine.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.

Unregister¶

func (c *Client) Unregister(ctx context.Context, in UnregisterIn) error

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.

Terminate¶

Terminate machine, killing its processes

func (c *Client) Terminate(ctx context.Context, in TerminateIn) error

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.

Kill¶

Send a UNIX signal to the machine's processes

func (c *Client) Kill(ctx context.Context, in KillIn) error

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.
`whom`	`?string`	Identifier that specifies what precisely to send the signal to (either 'leader', 'supervisor', or 'all').
`signal`	`int`	Numeric UNIX signal integer.

List¶

streaming optional

List running machines

func (c *Client) List(ctx context.Context, in ListIn) (*ListOut, error)
func (c *Client) ListMore(ctx context.Context, in ListIn) iter.Seq2[*ListOut, error]

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.
`acquireMetadata`	`?AcquireMetadata`	If 'yes' the output will include machine metadata fields such as 'Addresses', 'OSRelease', and 'UIDShift'. If 'graceful' it's equal to true but gracefully eats up errors

Reply

Field	Type	Description
`name`	`string`	Name of the machine
`id`	`?string`	128bit ID identifying this machine, formatted in hexadecimal
`service`	`?string`	Name of the software that registered this machine
`class`	`string`	The class of this machine
`leader`	`?ProcessId`	Leader process PID of this machine
`supervisor`	`?ProcessId`	Supervisor process PID of this machine
`rootDirectory`	`?string`	Root directory of this machine, if known, relative to host file system
`unit`	`?string`	The service manager unit this machine resides in
`timestamp`	`?Timestamp`	Timestamp when the machine was activated
`vSockCid`	`?int`	AF_VSOCK CID of the machine if known and applicable
`sshAddress`	`?string`	SSH address to connect to
`sshPrivateKeyPath`	`?string`	Path to private SSH key
`addresses`	`?[]Address`	List of addresses of the machine
`OSRelease`	`?[]string`	OS release information of the machine. It contains an array of key value pairs read from the os-release(5) file in the image.
`UIDShift`	`?int`	Return the base UID/GID of the machine
`subgroup`	`?string`	Subcgroup path of the machine, relative to the unit's cgroup path
`UID`	`?int`	Numeric UNIX UID of the user who registered the machine

Open¶

passes file descriptors

Allocates a pseudo TTY in the container in various modes

func (c *Client) Open(ctx context.Context, in OpenIn) (*OpenOut, error)

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.
`mode`	`MachineOpenMode`	There are three possible values: 'tty', 'login', and 'shell'. Please see description for each of the modes.
`user`	`?string`	See description of mode='shell'. Valid only when mode='shell'
`path`	`?string`	See description of mode='shell'. Valid only when mode='shell'
`args`	`?[]string`	See description of mode='shell'. Valid only when mode='shell'
`environment`	`?[]string`	See description of mode='shell'. Valid only when mode='shell'

Reply

Field	Type	Description
`ptyFileDescriptor`	`int`	File descriptor of the allocated pseudo TTY
`ptyPath`	`string`	Path to the allocated pseudo TTY

MapFrom¶

since v258

Maps given machine's UID/GID to host's UID/GID

func (c *Client) MapFrom(ctx context.Context, in MapFromIn) (*MapFromOut, error)

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.
`uid`	`?int`	UID in the machine to map to host UID
`gid`	`?int`	GID in the machine to map to host GID

Reply

Field	Type	Description
`uid`	`?int`	Mapped UID
`gid`	`?int`	Mapped GID

MapTo¶

since v258

Maps given host's UID/GID to a machine and corresponding UID/GID

func (c *Client) MapTo(ctx context.Context, in MapToIn) (*MapToOut, error)

Parameters

Field	Type	Description
`uid`	`?int`	Host UID to map to machine UID
`gid`	`?int`	Host GID to map to machine GID

Reply

Field	Type	Description
`uid`	`?int`	Mapped UID
`gid`	`?int`	Mapped GID
`machineName`	`?string`	Machine's name which owns mapped UID/GID

BindMount¶

since v258

Bind mounts a file or directory from the host into the container

func (c *Client) BindMount(ctx context.Context, in BindMountIn) error

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.
`source`	`string`	The source directory/file on the host. The path must be absolute.
`destination`	`?string`	The destination directory/file in the container. The path must be absolute. If null, it's equal to 'source'
`readOnly`	`?bool`	If true, the bind mount shall be read-only
`mkdir`	`?bool`	The destination mount point shall be created first, if it is missing

CopyFrom¶

since v258

Copy files or directories from a container into the host

func (c *Client) CopyFrom(ctx context.Context, in CopyFromIn) error

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.
`source`	`string`	The absolute path to source directory/file in the container
`destination`	`?string`	The absolute path to destination directory/file on the host. If null, it's equal to 'source'.
`replace`	`?bool`	If true the destination will be replaced

CopyTo¶

since v258

Copy files or directories from the host into a container

func (c *Client) CopyTo(ctx context.Context, in CopyToIn) error

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.
`source`	`string`	The absolute path to source directory/file on the host
`destination`	`?string`	The absolute path to destination directory/file in the container. If null, it's equal to 'source'
`replace`	`?bool`	If true the destination will be replaced

OpenRootDirectory¶

since v258 · passes file descriptors

Opens machine's root directory

func (c *Client) OpenRootDirectory(ctx context.Context, in OpenRootDirectoryIn) (*OpenRootDirectoryOut, error)

Parameters

Field	Type	Description
`name`	`?string`	If non-null the name of a machine.
`pid`	`?ProcessId`	If non-null the PID of a machine. Special value 0 means to take pid of the machine the caller is part of.
`allowInteractiveAuthentication`	`?bool`	Controls whether interactive authentication (via polkit) shall be allowed. If unspecified defaults to false.

Reply

Field	Type	Description
`fileDescriptor`	`int`	File descriptor of opened root directory

Types¶

AcquireMetadata¶

A enum field allowing to gracefully get metadata

Value	Description
`no`	Do not include metadata in the output
`yes`	Include metadata in the output
`graceful`	Include metadata in the output, but gracefully eat up errors

MachineOpenMode¶

A enum field which defines way to open TTY for a machine

Value	Description
`tty`	This mode allocates a pseudo TTY in the container and returns a file descriptor and its path. This is equivalent to transitioning into the container and invoking posix_openpt(3).
`login`	This mode allocates a pseudo TTY in the container and ensures that a getty login prompt of the container is running on the other end. It returns the file descriptor of the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the container.
`shell`	This mode allocates a pseudo TTY in the container, as the specified user, and invokes the executable at the specified path with a list of arguments (starting from argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY path.

ProcessId¶

An object for referencing UNIX processes

Field	Type	Description
`pid`	`int`	Numeric UNIX PID value
`pidfdId`	`?int`	64bit inode number of pidfd if known
`bootId`	`?string`	Boot ID of the system the inode number belongs to

Timestamp¶

A timestamp object consisting of both CLOCK_REALTIME and CLOCK_MONOTONIC timestamps

Field	Type	Description
`realtime`	`?int`	Timestamp in µs in the CLOCK_REALTIME clock (wallclock)
`monotonic`	`?int`	Timestamp in µs in the CLOCK_MONOTONIC clock

Address¶

An address object

Field	Type	Description
`ifindex`	`?int`
`family`	`int`
`address`	`[]int`

Errors¶

Error	Go type	Description
`NoSuchMachine`	`NoSuchMachineError`	No matching machine currently running
`MachineExists`	`MachineExistsError`
`NoPrivateNetworking`	`NoPrivateNetworkingError`	Machine does not use private networking
`NoOSReleaseInformation`	`NoOSReleaseInformationError`	Machine does not contain OS release information
`NoUIDShift`	`NoUIDShiftError`	Machine uses a complex UID/GID mapping, cannot determine shift
`NotAvailable`	`NotAvailableError`	Requested information is not available
`NotSupported`	`NotSupportedError`	Requested operation is not supported
`NoIPC`	`NoIPCError`	There is no IPC service (such as system bus or varlink) in the container
`NoSuchUser`	`NoSuchUserError`	No such user
`NoSuchGroup`	`NoSuchGroupError`	No such group
`UserInHostRange`	`UserInHostRangeError`	User belongs to host UID range
`GroupInHostRange`	`GroupInHostRangeError`	Group belongs to host GID range