1podman-machine-init(1) General Commands Manual podman-machine-init(1)
2
6 podman-machine-init - Initialize a new virtual machine
7
10 podman machine init [options] [name]
11
14 Initialize a new virtual machine for Podman.
15 The default machine name is podman-machine-default. If a machine name
18 is not specified as an argument, then the new machine will be named
19 podman-machine-default.
20 Rootless only.
23 Podman on MacOS and Windows requires a virtual machine. This is because
26 containers are Linux - containers do not run on any other OS because
27 containers' core functionality are tied to the Linux kernel. Podman ma‐
28 chine must be used to manage MacOS and Windows machines, but can be op‐
29 tionally used on Linux.
30 podman machine init initializes a new Linux virtual machine where con‐
33 tainers are run. SSH keys are automatically generated to access the
34 VM, and system connections to the root account and a user account in‐
35 side the VM are added.
36 By default, the VM distribution is Fedora CoreOS except for WSL which
39 is based on a custom Fedora image. While Fedora CoreOS upgrades come
40 out every 14 days, the automatic update mechanism Zincata is disabled
41 by Podman machine.
42 To check if there is an upgrade available for your machine os, you can
45 run the following command:
46 $ podman machine ssh 'sudo rpm-ostree upgrade --check'
48 If an update is available, you can rerun the above command and remove
53 the --check and your operating system will be updated. After updating,
54 you must stop and start your machine with podman machine stop && podman
55 machine start for it to take effect.
56 Note: Updating as described above can result in version mismatches be‐
59 tween Podman on the host and Podman in the machine. Executing podman
60 info should reveal versions of both. A configuration where the Podman
61 host and machine mismatch are unsupported.
62 For more information on updates and advanced configuration, see the Fe‐
65 dora CoreOS documentation about auto-updates and update strategies.
66 Fedora CoreOS upgrades come out every 14 days and are detected and in‐
69 stalled automatically. The VM is rebooted during the upgrade. For more
70 information on updates and advanced configuration, see the Fedora
71 CoreOS documentation about auto-updates and update strategies.
72
75 --cpus=number
76 Number of CPUs.
77 --disk-size=number
80 Size of the disk for the guest VM in GiB.
81 --help
84 Print usage statement.
85 --ignition-path
88 Fully qualified path of the ignition file.
89 If an ignition file is provided, the file is copied into the user's
92 CONF_DIR and renamed. Additionally, no SSH keys are generated, nor are
93 any system connections made. It is assumed that the user does these
94 things manually or handled otherwise.
95 --image-path
98 Fully qualified path or URL to the VM image. Can also be set to test‐
99 ing, next, or stable to pull down default image. Defaults to testing.
100 --memory, -m=number
103 Memory (in MiB). Note: 1024MiB = 1GiB.
104 --now
107 Start the virtual machine immediately after it has been initialized.
108 --rootful
111 Whether this machine prefers rootful (true) or rootless (false) con‐
112 tainer execution. This option determines the remote connection default
113 if there is no existing remote connection configurations.
114 API forwarding, if available, follows this setting.
117 --timezone
120 Set the timezone for the machine and containers. Valid values are lo‐
121 cal or a timezone such as America/Chicago. A value of local, which is
122 the default, means to use the timezone of the machine host.
123 The timezone setting is not used with WSL. WSL automatically sets the
126 timezone to the same as the host Windows operating system.
127 --usb=bus=number,devnum=number or vendor=hexadecimal,product=hexadecimal
130 Assign a USB device from the host to the VM via USB passthrough. Only
131 supported for QEMU Machines.
132 The device needs to have proper permissions in order to be passed to
135 the machine. This means the device needs to be under your user group.
136 Note that using bus and device number are simpler but the values can
139 change every boot or when the device is unplugged.
140 When specifying a USB using vendor and product ID's, if more than one
143 device has the same vendor and product ID, the first available device
144 is assigned.
145 --user-mode-networking
148 Indicates that this machine relays traffic from the guest through a
149 user-space process running on the host. In some VPN configurations the
150 VPN may drop traffic from alternate network interfaces, including VM
151 network devices. By enabling user-mode networking (a setting of true),
152 VPNs observe all podman machine traffic as coming from the host, by‐
153 passing the problem.
154 When the qemu backend is used (Linux, Mac), user-mode networking is
157 mandatory and the only allowed value is true. In contrast, The Win‐
158 dows/WSL backend defaults to false, and follows the standard WSL net‐
159 work setup. Changing this setting to true on Windows/WSL informs Pod‐
160 man to replace the WSL networking setup on start of this machine in‐
161 stance with a user-mode networking distribution. Since WSL shares the
162 same kernel across distributions, all other running distributions
163 reuses this network. Likewise, when the last machine instance with a
164 true setting stops, the original networking setup is restored.
165 --username
168 Username to use for executing commands in remote VM. Default value is
169 core for FCOS and user for Fedora (default on Windows hosts). Should
170 match the one used inside the resulting VM image.
171 --volume, -v=source:target[:options]
174 Mounts a volume from source to target.
175 Create a mount. If /host-dir:/machine-dir is specified as the
178 *source:target*, Podman mounts host-dir in the host to machine-dir in
179 the Podman machine.
180 Additional options may be specified as a comma-separated string. Recog‐
183 nized options are: * ro: mount volume read-only * rw: mount volume
184 read/write (default) * security_model=[model]: specify 9p security
185 model (see below)
186 The 9p security model [determines] https://wiki.qemu.org/Documenta‐
189 tion/9psetup#Starting_the_Guest_directly if and how the 9p filesystem
190 translates some filesystem operations before actual storage on the
191 host.
192 In order to allow symlinks to work, on MacOS the default security model
195 is
196 none.
197 The value of mapped-xattr specifies that 9p store symlinks and some
200 file attributes as extended attributes on the host. This is suitable
201 when the host and the guest do not need to interoperate on the shared
202 filesystem, but has caveats for actual shared access; notably, symlinks
203 on the host are not usable on the guest and vice versa. If interoper‐
204 ability is required, then choose none instead, but keep in mind that
205 the guest is not able to do things that the user running the virtual
206 machine cannot do, e.g. create files owned by another user. Using none
207 is almost certainly the best choice for read-only volumes.
208 Example: -v "$HOME/git:$HOME/git:ro,security_model=none"
211 Default volume mounts are defined in containers.conf. Unless changed,
214 the default values is $HOME:$HOME.
215 --volume-driver
218 Driver to use for mounting volumes from the host, such as virtfs.
219
222 $ podman machine init
223 $ podman machine init myvm
224 $ podman machine init --rootful
225 $ podman machine init --disk-size 50
226 $ podman machine init --memory=1024 myvm
227 $ podman machine init -v /Users:/mnt/Users
228 $ podman machine init --usb vendor=13d3,product=5406
229 $ podman machine init --usb bus=1,devnum=3
230
234 podman(1), podman-machine(1)
235
238 March 2021, Originally compiled by Ashley Cui acui@redhat.com
239 ⟨mailto:acui@redhat.com⟩
240 podman-machine-init(1)