path: root/upstream/fedora-rawhide/man8/systemd-machined.service.8

'\" t
.TH "SYSTEMD\-MACHINED\&.SERVICE" "8" "" "systemd 256~rc3" "systemd-machined.service"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-machined.service, systemd-machined \- Virtual machine and container registration manager
.SH "SYNOPSIS"
.PP
systemd\-machined\&.service
.PP
/usr/lib/systemd/systemd\-machined
.SH "DESCRIPTION"
.PP
\fBsystemd\-machined\fR
is a system service that keeps track of locally running virtual machines and containers\&.
.PP
\fBsystemd\-machined\fR
is useful for registering and keeping track of both OS containers (containers that share the host kernel but run a full init system of their own and behave in most regards like a full virtual operating system rather than just one virtualized app) and full virtual machines (virtualized hardware running normal operating systems and possibly different kernels)\&.
.PP
\fBsystemd\-machined\fR
should
\fInot\fR
be used for registering/keeping track of application sandbox containers\&. A
\fImachine\fR
in the context of
\fBsystemd\-machined\fR
is supposed to be an abstract term covering both OS containers and full virtual machines, but not application sandboxes\&.
.PP
Machines registered with machined are exposed in various ways in the system\&. For example:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Tools like
\fBps\fR(1)
will show to which machine a specific process belongs in a column of its own, and so will
\m[blue]\fBgnome\-system\-monitor\fR\m[]\&\s-2\u[1]\d\s+2
or
\fBsystemd-cgls\fR(1)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
systemd\*(Aqs various tools (\fBsystemctl\fR(1),
\fBjournalctl\fR(1),
\fBloginctl\fR(1),
\fBhostnamectl\fR(1),
\fBtimedatectl\fR(1),
\fBlocalectl\fR(1),
\fBmachinectl\fR(1), \&.\&.\&.) support the
\fB\-M\fR
switch to operate on local containers instead of the host system\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBsystemctl list\-machines\fR
will show the system state of all local containers, connecting to the container\*(Aqs init system for that\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
systemctl\*(Aqs
\fB\-\-recursive\fR
switch has the effect of not only showing the locally running services, but recursively showing the services of all registered containers\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fBmachinectl\fR
command provides access to a number of useful operations on registered containers, such as introspecting them, rebooting, shutting them down, and getting a login prompt on them\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fBsd-bus\fR(3)
library exposes the
\fBsd_bus_open_system_machine\fR(3)
call to connect to the system bus of any registered container\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fBnss-mymachines\fR(8)
module makes sure all registered containers can be resolved via normal glibc
\fBgethostbyname\fR(3)
or
\fBgetaddrinfo\fR(3)
calls\&.
.RE
.PP
See
\fBsystemd-nspawn\fR(1)
for some examples on how to run containers with OS tools\&.
.PP
If you are interested in writing a VM or container manager that makes use of machined, please have look at
\m[blue]\fBWriting Virtual Machine or Container Managers\fR\m[]\&\s-2\u[2]\d\s+2\&. Also see the
\m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[3]\d\s+2\&.
.PP
The daemon provides both a C library interface (which is shared with
\fBsystemd-logind.service\fR(8)) as well as a D\-Bus interface\&. The library interface may be used to introspect and watch the state of virtual machines/containers\&. The bus interface provides the same but in addition may also be used to register or terminate machines\&. For more information please consult
\fBsd-login\fR(3)
and
\fBorg.freedesktop.machine1\fR(5)
and
\fBorg.freedesktop.LogControl1\fR(5)\&.
.PP
A small companion daemon
\fBsystemd-importd.service\fR(8)
is also available, which implements importing, exporting, and downloading of container and VM images\&.
.PP
For each container registered with
systemd\-machined\&.service
that employs user namespacing, users/groups are synthesized for the used UIDs/GIDs\&. These are made available to the system using the
\m[blue]\fBUser/Group Record Lookup API via Varlink\fR\m[]\&\s-2\u[4]\d\s+2, and thus may be resolved with
\fBuserdbctl\fR(1)
or the usual glibc NSS calls\&.
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBmachinectl\fR(1), \fBsystemd-nspawn\fR(1), \fBnss-mymachines\fR(8), \fBsystemd.special\fR(7)
.SH "NOTES"
.IP " 1." 4
gnome-system-monitor
.RS 4
\%https://help.gnome.org/users/gnome-system-monitor/
.RE
.IP " 2." 4
Writing Virtual Machine or Container Managers
.RS 4
\%https://www.freedesktop.org/wiki/Software/systemd/writing-vm-managers
.RE
.IP " 3." 4
New Control Group Interfaces
.RS 4
\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface
.RE
.IP " 4." 4
User/Group Record Lookup API via Varlink
.RS 4
\%https://systemd.io/USER_GROUP_API
.RE