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. Fedora CoreOS up‐
39 grades come out every 14 days and are detected and installed automati‐
40 cally. The VM is rebooted during the upgrade. For more information on
41 updates and advanced configuration, see the Fedora CoreOS documentation
42 about auto-updates and update strategies.
43
46 --cpus=number
47 Number of CPUs.
48 --disk-size=number
51 Size of the disk for the guest VM in GiB.
52 --help
55 Print usage statement.
56 --ignition-path
59 Fully qualified path of the ignition file.
60 If an ignition file is provided, the file is copied into the user's
63 CONF_DIR and renamed. Additionally, no SSH keys are generated, nor are
64 any system connections made. It is assumed that the user does these
65 things manually or handled otherwise.
66 --image-path
69 Fully qualified path or URL to the VM image. Can also be set to test‐
70 ing, next, or stable to pull down default image. Defaults to testing.
71 --memory, -m=number
74 Memory (in MiB). Note: 1024MiB = 1GiB.
75 --now
78 Start the virtual machine immediately after it has been initialized.
79 --rootful
82 Whether this machine prefers rootful (true) or rootless (false) con‐
83 tainer execution. This option determines the remote connection default
84 if there is no existing remote connection configurations.
85 API forwarding, if available, follows this setting.
88 --timezone
91 Set the timezone for the machine and containers. Valid values are lo‐
92 cal or a timezone such as America/Chicago. A value of local, which is
93 the default, means to use the timezone of the machine host.
94 --user-mode-networking
97 Indicates that this machine relays traffic from the guest through a
98 user-space process running on the host. In some VPN configurations the
99 VPN may drop traffic from alternate network interfaces, including VM
100 network devices. By enabling user-mode networking (a setting of true),
101 VPNs observe all podman machine traffic as coming from the host, by‐
102 passing the problem.
103 When the qemu backend is used (Linux, Mac), user-mode networking is
106 mandatory and the only allowed value is true. In contrast, The Win‐
107 dows/WSL backend defaults to false, and follows the standard WSL net‐
108 work setup. Changing this setting to true on Windows/WSL informs Pod‐
109 man to replace the WSL networking setup on start of this machine in‐
110 stance with a user-mode networking distribution. Since WSL shares the
111 same kernel across distributions, all other running distributions
112 reuses this network. Likewise, when the last machine instance with a
113 true setting stops, the original networking setup is restored.
114 --username
117 Username to use for executing commands in remote VM. Default value is
118 core for FCOS and user for Fedora (default on Windows hosts). Should
119 match the one used inside the resulting VM image.
120 --volume, -v=source:target[:options]
123 Mounts a volume from source to target.
124 Create a mount. If /host-dir:/machine-dir is specified as the
127 *source:target*, Podman mounts host-dir in the host to machine-dir in
128 the Podman machine.
129 Additional options may be specified as a comma-separated string. Recog‐
132 nized options are: * ro: mount volume read-only * rw: mount volume
133 read/write (default) * security_model=[model]: specify 9p security
134 model (see below)
135 The 9p security model [determines] https://wiki.qemu.org/Documenta‐
138 tion/9psetup#Starting_the_Guest_directly if and how the 9p filesystem
139 translates some filesystem operations before actual storage on the
140 host.
141 In order to allow symlinks to work, on MacOS the default security model
144 is
145 none.
146 The value of mapped-xattr specifies that 9p store symlinks and some
149 file attributes as extended attributes on the host. This is suitable
150 when the host and the guest do not need to interoperate on the shared
151 filesystem, but has caveats for actual shared access; notably, symlinks
152 on the host are not usable on the guest and vice versa. If interoper‐
153 ability is required, then choose none instead, but keep in mind that
154 the guest is not able to do things that the user running the virtual
155 machine cannot do, e.g. create files owned by another user. Using none
156 is almost certainly the best choice for read-only volumes.
157 Example: -v "$HOME/git:$HOME/git:ro,security_model=none"
160 Default volume mounts are defined in containers.conf. Unless changed,
163 the default values is $HOME:$HOME.
164 --volume-driver
167 Driver to use for mounting volumes from the host, such as virtfs.
168
171 $ podman machine init
172 $ podman machine init myvm
173 $ podman machine init --rootful
174 $ podman machine init --disk-size 50
175 $ podman machine init --memory=1024 myvm
176 $ podman machine init -v /Users:/mnt/Users
177
181 podman(1), podman-machine(1)
182
185 March 2021, Originally compiled by Ashley Cui acui@redhat.com
186 ⟨mailto:acui@redhat.com⟩
187 podman-machine-init(1)