1MACHINECTL(1) machinectl MACHINECTL(1)
2
6 machinectl - Control the systemd machine manager
7
9 machinectl [OPTIONS...] {COMMAND} [NAME...]
10
12 machinectl may be used to introspect and control the state of the
13 systemd(1) virtual machine and container registration manager systemd-
14 machined.service(8).
15
17 The following options are understood:
18 -p, --property=
20 When showing machine or image properties, limit the output to
21 certain properties as specified by the argument. If not specified,
22 all set properties are shown. The argument should be a property
23 name, such as "Name". If specified more than once, all properties
24 with the specified names are shown.
25 -a, --all
27 When showing machine or image properties, show all properties
28 regardless of whether they are set or not.
29 When listing VM or container images, do not suppress images
31 beginning in a dot character (".").
32 -l, --full
34 Do not ellipsize process tree entries.
35 --no-ask-password
37 Do not query the user for authentication for privileged operations.
38 --kill-who=
40 When used with kill, choose which processes to kill. Must be one of
41 leader, or all to select whether to kill only the leader process of
42 the machine or all processes of the machine. If omitted, defaults
43 to all.
44 -s, --signal=
46 When used with kill, choose which signal to send to selected
47 processes. Must be one of the well-known signal specifiers, such as
48 SIGTERM, SIGINT or SIGSTOP. If omitted, defaults to SIGTERM.
49 --mkdir
51 When used with bind creates the destination directory before
52 applying the bind mount.
53 --read-only
55 When used with bind applies a read-only bind mount.
56 -n, --lines=
58 When used with status, controls the number of journal lines to
59 show, counting from the most recent ones. Takes a positive integer
60 argument. Defaults to 10.
61 -o, --output=
63 When used with status, controls the formatting of the journal
64 entries that are shown. For the available choices, see
65 journalctl(1). Defaults to "short".
66 --verify=
68 When downloading a container or VM image, specify whether the image
69 shall be verified before it is made available. Takes one of "no",
70 "checksum" and "signature". If "no" no verification is done. If
71 "checksum" is specified the download is checked for integrity after
72 transfer is complete, but no signatures are verified. If
73 "signature" is specified, the checksum is verified and the images's
74 signature is checked against a local keyring of trustable vendors.
75 It is strongly recommended to set this option to "signature" if the
76 server and protocol support this. Defaults to "signature".
77 --force
79 When downloading a container or VM image, and a local copy by the
80 specified local machine name already exists, delete it first and
81 replace it by the newly downloaded image.
82 -H, --host=
84 Execute the operation remotely. Specify a hostname, or a username
85 and hostname separated by "@", to connect to. The hostname may
86 optionally be suffixed by a container name, separated by ":", which
87 connects directly to a specific container on the specified host.
88 This will use SSH to talk to the remote machine manager instance.
89 Container names may be enumerated with machinectl -H HOST.
90 -M, --machine=
92 Execute operation on a local container. Specify a container name to
93 connect to.
94 --no-pager
96 Do not pipe output into a pager.
97 --no-legend
99 Do not print the legend, i.e. column headers and the footer with
100 hints.
101 -h, --help
103 Print a short help text and exit.
104 --version
106 Print a short version string and exit.
107
109 The following commands are understood:
110 Machine Commands
112 list
113 List currently running (online) virtual machines and containers. To
114 enumerate container images that can be started, use list-images
115 (see below).
116 status NAME...
118 Show terse runtime status information about one or more virtual
119 machines and containers, followed by the most recent log data from
120 the journal. This function is intended to generate human-readable
121 output. If you are looking for computer-parsable output, use show
122 instead. Note that the log data shown is reported by the virtual
123 machine or container manager, and frequently contains console
124 output of the machine, but not necessarily journal contents of the
125 machine itself.
126 show NAME...
128 Show properties of one or more registered virtual machines or
129 containers or the manager itself. If no argument is specified,
130 properties of the manager will be shown. If an NAME is specified,
131 properties of this virtual machine or container are shown. By
132 default, empty properties are suppressed. Use --all to show those
133 too. To select specific properties to show, use --property=. This
134 command is intended to be used whenever computer-parsable output is
135 required. Use status if you are looking for formatted
136 human-readable output.
137 start NAME...
139 Start a container as a system service, using systemd-nspawn(1).
140 This starts systemd-nspawn@.service, instantiated for the specified
141 machine name, similar to the effect of systemctl start on the
142 service name. systemd-nspawn looks for a container image by the
143 specified name in /var/lib/machines/ (and other search paths, see
144 below) and runs it. Use list-images (see below), for listing
145 available container images to start.
146 Note that systemd-machined.service(8) also interfaces with a
148 variety of other container and VM managers, systemd-nspawn is just
149 one implementation of it. Most of the commands available in
150 machinectl may be used on containers or VMs controlled by other
151 managers, not just systemd-nspawn. Starting VMs and container
152 images on those managers requires manager-specific tools.
153 To interactively start a container on the command line with full
155 access to the container's console, please invoke systemd-nspawn
156 directly. To stop a running container use machinectl poweroff, see
157 below.
158 login NAME
160 Open an interactive terminal login session to a container. This
161 will create a TTY connection to a specific container and asks for
162 the execution of a getty on it. Note that this is only supported
163 for containers running systemd(1) as init system.
164 This command will open a full login prompt on the container, which
166 then asks for username and password. Use systemd-run(1) with the
167 --machine= switch to invoke a single command, either interactively
168 or in the background within a local container.
169 enable NAME..., disable NAME...
171 Enable or disable a container as a system service to start at
172 system boot, using systemd-nspawn(1). This enables or disables
173 systemd-nspawn@.service, instantiated for the specified machine
174 name, similar to the effect of systemctl enable or systemctl
175 disable on the service name.
176 poweroff NAME...
178 Power off one or more containers. This will trigger a reboot by
179 sending SIGRTMIN+4 to the container's init process, which causes
180 systemd-compatible init systems to shut down cleanly. This
181 operation does not work on containers that do not run a
182 systemd(1)-compatible init system, such as sysvinit. Use terminate
183 (see below) to immediately terminate a container or VM, without
184 cleanly shutting it down.
185 reboot NAME...
187 Reboot one or more containers. This will trigger a reboot by
188 sending SIGINT to the container's init process, which is roughly
189 equivalent to pressing Ctrl+Alt+Del on a non-containerized system,
190 and is compatible with containers running any system manager.
191 terminate NAME...
193 Immediately terminates a virtual machine or container, without
194 cleanly shutting it down. This kills all processes of the virtual
195 machine or container and deallocates all resources attached to that
196 instance. Use poweroff to issue a clean shutdown request.
197 kill NAME...
199 Send a signal to one or more processes of the virtual machine or
200 container. This means processes as seen by the host, not the
201 processes inside the virtual machine or container. Use --kill-who=
202 to select which process to kill. Use --signal= to select the signal
203 to send.
204 bind NAME PATH [PATH]
206 Bind mounts a directory from the host into the specified container.
207 The first directory argument is the source directory on the host,
208 the second directory argument the source directory on the host.
209 When the latter is omitted the destination path in the container is
210 the same as the source path on the host. When combined with the
211 --read-only switch a ready-only bind mount is created. When
212 combined with the --mkdir switch the destination path is first
213 created before the mount is applied. Note that this option is
214 currently only supported for systemd-nspawn(1) containers.
215 copy-to NAME PATH [PATH]
217 Copies files or directories from the host system into a running
218 container. Takes a container name, followed by the source path on
219 the host and the destination path in the container. If the
220 destination path is omitted the same as the source path is used.
221 copy-from NAME PATH [PATH]
223 Copies files or directories from a container into the host system.
224 Takes a container name, followed by the source path in the
225 container the destination path on the host. If the destination path
226 is omitted the same as the source path is used.
227 Image Commands
229 list-images
230 Show a list of locally installed container and VM images. This
231 enumerates all raw disk images and container directories and
232 subvolumes in /var/lib/machines/ (and other search paths, see
233 below). Use start (see above) to run a container off one of the
234 listed images. Note that by default containers whose name begins
235 with a dot (".") are not shown. To show these too, specify --all.
236 Note that a special image ".host" always implicitly exists and
237 refers to the image the host itself is booted from.
238 image-status NAME...
240 Show terse status information about one or more container or VM
241 images. This function is intended to generate human-readable
242 output. Use show-image (see below) to generate computer-parsable
243 output instead.
244 show-image NAME...
246 Show properties of one or more registered virtual machine or
247 container images, or the manager itself. If no argument is
248 specified, properties of the manager will be shown. If an NAME is
249 specified, properties of this virtual machine or container image
250 are shown. By default, empty properties are suppressed. Use --all
251 to show those too. To select specific properties to show, use
252 --property=. This command is intended to be used whenever
253 computer-parsable output is required. Use image-status if you are
254 looking for formatted human-readable output.
255 clone NAME NAME
257 Clones a container or disk image. The arguments specify the name of
258 the image to clone and the name of the newly cloned image. Note
259 that plain directory container images are cloned into subvolume
260 images with this command. Note that cloning a container or VM image
261 is optimized for btrfs file systems, and might not be efficient on
262 others, due to file system limitations.
263 rename NAME NAME
265 Renames a container or disk image. The arguments specify the name
266 of the image to rename and the new name of the image.
267 read-only NAME [BOOL]
269 Marks or (unmarks) a container or disk image read-only. Takes a VM
270 or container image name, followed by a boolean as arguments. If the
271 boolean is omitted, positive is implied, i.e. the image is marked
272 read-only.
273 remove NAME...
275 Removes one or more container or disk images. The special image
276 ".host", which refers to the host's own directory tree may not be
277 removed.
278 Image Transfer Commands
280 pull-tar URL [NAME]
281 Downloads a .tar container image from the specified URL, and makes
282 it available under the specified local machine name. The URL must
283 be of type "http://" or "https://", and must refer to a .tar,
284 .tar.gz, .tar.xz or .tar.bz2 archive file. If the local machine
285 name is omitted the name it is automatically derived from the last
286 component of the URL, with its suffix removed.
287 The image is verified before it is made available, unless
289 --verify=no is specified. Verification is done via SHA256SUMS and
290 SHA256SUMS.gpg files, that need to be made available on the same
291 web server, under the same URL as the .tar file, but with the last
292 component (the filename) of the URL replaced. With
293 --verify=checksum only the SHA256 checksum for the file is
294 verified, based on the SHA256SUMS file. With --verify=signature the
295 SHA256SUMS file is first verified with detached GPG signature file
296 SHA256SUMS.gpg. The public key for this verification step needs to
297 be available in /usr/lib/systemd/import-pubring.gpg or
298 /etc/systemd/import-pubring.gpg.
299 The container image will be downloaded and stored in a read-only
301 subvolume in /var/lib/machines/, that is named after the specified
302 URL and its HTTP etag. A writable snapshot is then taken from this
303 subvolume, and named after the specified local name. This behaviour
304 ensures that creating multiple container instances of the same URL
305 is efficient, as multiple downloads are not necessary. In order to
306 create only the read-only image, and avoid creating its writable
307 snapshot, specify "-" as local machine name.
308 Note that the read-only subvolume is prefixed with .tar-, and is
310 thus now shown by list-images, unless --all is passed.
311 Note that pressing C-c during execution of this command will not
313 abort the download. Use cancel-transfer, described below.
314 pull-raw URL [NAME]
316 Downloads a .raw container or VM disk image from the specified URL,
317 and makes it available under the specified local machine name. The
318 URL must be of type "http://" or "https://". The container image
319 must either be a .qcow2 or raw disk image, optionally compressed as
320 .gz, .xz, or .bz2. If the local machine name is omitted the name it
321 is automatically derived from the last component of the URL, with
322 its suffix removed.
323 Image verification is identical for raw and tar images (see above).
325 If the the downloaded image is in .qcow2 format it es converted
327 into a raw image file before it is made available.
328 Downloaded images of this type will be placed as read-only .raw
330 file in /var/lib/machines/. A local, writable (reflinked) copy is
331 then made under the specified local machine name. To omit creation
332 of the local, writable copy pass "-" as local machine name.
333 Similar to the behaviour of pull-tar, the read-only image is
335 prefixed with .raw-, and thus now shown by list-images, unless
336 --all is passed.
337 Note that pressing C-c during execution of this command will not
339 abort the download. Use cancel-transfer, described below.
340 list-transfers
342 Shows a list of container or VM image downloads that are currently
343 in progress.
344 cancel-transfers ID...
346 Aborts download of the container or VM image with the specified ID.
347 To list ongoing transfers and their IDs, use list-transfers.
348
350 Machine images are preferably stored in /var/lib/machines/, but are
351 also searched for in /usr/local/lib/machines/ and /usr/lib/machines/.
352 For compatibility reasons the directory /var/lib/container/ is
353 searched, too. Note that images stored below /usr are always considered
354 read-only. It is possible to symlink machines images from other
355 directories into /var/lib/machines/ to make them available for control
356 with machinectl.
357 Disk images are understood by systemd-nspawn(1) and machinectl in three
359 formats:
360 · A simple directory tree, containing the files and directories of
362 the container to boot.
363 · A subvolume (on btrfs file systems), which are similar to the
365 simple directories, described above. However, they have additional
366 benefits, such as efficient cloning and quota reporting.
367 · "Raw" disk images, i.e. binary images of disks with a GPT or MBR
369 partition table. Images of this type are regular files with the
370 suffix ".raw".
371 See systemd-nspawn(1) for more information on image formats, in
373 particular it's --directory= and --image= options.
374
376 Example 1. Download an Ubuntu image and open a shell in it
377 # machinectl pull-tar https://cloud-images.ubuntu.com/trusty/current/trusty-server-cloudimg-amd64-root.tar.gz
379 # systemd-nspawn -M trusty-server-cloudimg-amd64-root
380 This downloads and verifies the specified .tar image, and then uses
382 systemd-nspawn(1) to open a shell in it.
383 Example 2. Download a Fedora image, set a root password in it, start it
385 as service
386 # machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz
388 # systemd-nspawn -M Fedora-Cloud-Base-20141203-21
389 # passwd
390 # exit
391 # machinectl start Fedora-Cloud-Base-20141203-21
392 # machinectl login Fedora-Cloud-Base-20141203-21
393 This downloads the specified .raw image with verification disabled.
395 Then a shell is opened in it and a root password is set. Afterwards the
396 shell is left, and the machine started as system service. With the last
397 command a login prompt into the container is requested.
398
400 On success, 0 is returned, a non-zero failure code otherwise.
401
403 $SYSTEMD_PAGER
404 Pager to use when --no-pager is not given; overrides $PAGER.
405 Setting this to an empty string or the value "cat" is equivalent to
406 passing --no-pager.
407 $SYSTEMD_LESS
409 Override the default options passed to less ("FRSXMK").
410
412 systemd-machined.service(8), systemd-nspawn(1), systemd.special(7)
413systemd 219 MACHINECTL(1)