Debian Codegraph @

upstream/debian-unstable/man8/systemd-machined.service.8

raw
1 '\" t
2 .TH "SYSTEMD\-MACHINED\&.SERVICE" "8" "" "systemd 261~rc3" "systemd-machined.service"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-machined.service, systemd-machined \- Virtual machine and container registration manager
24 .SH "SYNOPSIS"
25 .PP
26 systemd\-machined\&.service
27 .PP
28 /usr/lib/systemd/systemd\-machined
29 .SH "DESCRIPTION"
30 .PP
31 \fBsystemd\-machined\fR
32 is a system service that keeps track of locally running virtual machines and containers\&.
33 .PP
34 \fBsystemd\-machined\fR
35 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)\&.
36 .PP
37 \fBsystemd\-machined\fR
38 should
39 \fInot\fR
40 be used for registering/keeping track of application sandbox containers\&. A
41 \fImachine\fR
42 in the context of
43 \fBsystemd\-machined\fR
44 is supposed to be an abstract term covering both OS containers and full virtual machines, but not application sandboxes\&.
45 .PP
46 Machines registered with machined are exposed in various ways in the system\&. For example:
47 .sp
48 .RS 4
49 .ie n \{\
50 \h'-04'\(bu\h'+03'\c
51 .\}
52 .el \{\
53 .sp -1
54 .IP \(bu 2.3
55 .\}
56 Tools like
57 \fBps\fR(1)
58 will show to which machine a specific process belongs in a column of its own, and so will
59 \m[blue]\fBgnome\-system\-monitor\fR\m[]\&\s-2\u[1]\d\s+2
60 or
61 \fBsystemd-cgls\fR(1)\&.
62 .RE
63 .sp
64 .RS 4
65 .ie n \{\
66 \h'-04'\(bu\h'+03'\c
67 .\}
68 .el \{\
69 .sp -1
70 .IP \(bu 2.3
71 .\}
72 systemd\*(Aqs various tools (\fBsystemctl\fR(1),
73 \fBjournalctl\fR(1),
74 \fBloginctl\fR(1),
75 \fBhostnamectl\fR(1),
76 \fBtimedatectl\fR(1),
77 \fBlocalectl\fR(1),
78 \fBmachinectl\fR(1), \&.\&.\&.) support the
79 \fB\-M\fR
80 switch to operate on local containers instead of the host system\&.
81 .RE
82 .sp
83 .RS 4
84 .ie n \{\
85 \h'-04'\(bu\h'+03'\c
86 .\}
87 .el \{\
88 .sp -1
89 .IP \(bu 2.3
90 .\}
91 \fBsystemctl list\-machines\fR
92 will show the system state of all local containers, connecting to the container\*(Aqs init system for that\&.
93 .RE
94 .sp
95 .RS 4
96 .ie n \{\
97 \h'-04'\(bu\h'+03'\c
98 .\}
99 .el \{\
100 .sp -1
101 .IP \(bu 2.3
102 .\}
103 systemctl\*(Aqs
104 \fB\-\-recursive\fR
105 switch has the effect of not only showing the locally running services, but recursively showing the services of all registered containers\&.
106 .RE
107 .sp
108 .RS 4
109 .ie n \{\
110 \h'-04'\(bu\h'+03'\c
111 .\}
112 .el \{\
113 .sp -1
114 .IP \(bu 2.3
115 .\}
116 The
117 \fBmachinectl\fR
118 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\&.
119 .RE
120 .sp
121 .RS 4
122 .ie n \{\
123 \h'-04'\(bu\h'+03'\c
124 .\}
125 .el \{\
126 .sp -1
127 .IP \(bu 2.3
128 .\}
129 The
130 \fBsd-bus\fR(3)
131 library exposes the
132 \fBsd_bus_open_system_machine\fR(3)
133 call to connect to the system bus of any registered container\&.
134 .RE
135 .sp
136 .RS 4
137 .ie n \{\
138 \h'-04'\(bu\h'+03'\c
139 .\}
140 .el \{\
141 .sp -1
142 .IP \(bu 2.3
143 .\}
144 The
145 \fBnss-mymachines\fR(8)
146 module makes sure all registered containers can be resolved via normal glibc
147 \fBgethostbyname\fR(3)
148 or
149 \fBgetaddrinfo\fR(3)
150 calls\&.
151 .RE
152 .PP
153 See
154 \fBsystemd-nspawn\fR(1)
155 for some examples on how to run containers with OS tools\&.
156 .PP
157 If you are interested in writing a VM or container manager that makes use of machined, please have look at
158 \m[blue]\fBWriting Virtual Machine or Container Managers\fR\m[]\&\s-2\u[2]\d\s+2\&. Also see the
159 \m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[3]\d\s+2\&.
160 .PP
161 The daemon provides both a C library interface (which is shared with
162 \fBsystemd-logind.service\fR(8)) as well as a D\-Bus interface and a Varlink 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\&. The Varlink interface may be used to register machines with optional extensions, e\&.g\&. with an SSH key / address; it can be queried with
163 \fBvarlinkctl introspect /run/systemd/machine/io\&.systemd\&.Machine io\&.systemd\&.Machine\fR\&. For more information please consult
164 \fBsd-login\fR(3)
165 and
166 \fBorg.freedesktop.machine1\fR(5)
167 and
168 \fBorg.freedesktop.LogControl1\fR(5)\&.
169 .PP
170 A small companion daemon
171 \fBsystemd-importd.service\fR(8)
172 is also available, which implements importing, exporting, and downloading of container and VM images\&.
173 .PP
174 For each container registered with
175 systemd\-machined\&.service
176 that employs user namespacing, users/groups are synthesized for the used UIDs/GIDs\&. These are made available to the system using the
177 \m[blue]\fBUser/Group Record Lookup API via Varlink\fR\m[]\&\s-2\u[4]\d\s+2, and thus may be resolved with
178 \fBuserdbctl\fR(1)
179 or the usual glibc NSS calls\&.
180 .SH "SEE ALSO"
181 .PP
182 \fBsystemd\fR(1), \fBmachinectl\fR(1), \fBsystemd-nspawn\fR(1), \fBnss-mymachines\fR(8), \fBsystemd.special\fR(7), \fBorg.freedesktop.machine1\fR(5), \fBssh\fR(1)
183 .SH "NOTES"
184 .IP " 1." 4
185 gnome-system-monitor
186 .RS 4
187 \%https://help.gnome.org/users/gnome-system-monitor/
188 .RE
189 .IP " 2." 4
190 Writing Virtual Machine or Container Managers
191 .RS 4
192 \%https://systemd.io/WRITING_VM_AND_CONTAINER_MANAGERS
193 .RE
194 .IP " 3." 4
195 New Control Group Interfaces
196 .RS 4
197 \%https://systemd.io/CONTROL_GROUP_INTERFACE
198 .RE
199 .IP " 4." 4
200 User/Group Record Lookup API via Varlink
201 .RS 4
202 \%https://systemd.io/USER_GROUP_API
203 .RE