mirror of https://github.com/containers/podman.git
214 lines
7.8 KiB
Markdown
214 lines
7.8 KiB
Markdown
% podman-machine-init 1
|
|
|
|
## NAME
|
|
podman\-machine\-init - Initialize a new virtual machine
|
|
|
|
## SYNOPSIS
|
|
**podman machine init** [*options*] [*name*]
|
|
|
|
## DESCRIPTION
|
|
|
|
Initialize a new virtual machine for Podman.
|
|
|
|
The default machine name is `podman-machine-default`. If a machine name is not specified as an argument,
|
|
then the new machine will be named `podman-machine-default`.
|
|
|
|
Rootless only.
|
|
|
|
Podman on MacOS and Windows requires a virtual machine. This is because containers are Linux -
|
|
containers do not run on any other OS because containers' core functionality are
|
|
tied to the Linux kernel. Podman machine must be used to manage MacOS and Windows machines,
|
|
but can be optionally used on Linux.
|
|
|
|
**podman machine init** initializes a new Linux virtual machine where containers are run.
|
|
SSH keys are automatically generated to access the VM, and system connections to the root account
|
|
and a user account inside the VM are added.
|
|
|
|
By default, the VM distribution is [Fedora CoreOS](https://getfedora.org/en/coreos?stream=testing) except for
|
|
WSL which is based on a custom Fedora image. While Fedora CoreOS upgrades come out every 14 days, the automatic
|
|
update mechanism Zincata is disabled by Podman machine.
|
|
|
|
To check if there is an upgrade available for your machine os, you can run the following command:
|
|
|
|
```
|
|
$ podman machine ssh 'sudo rpm-ostree upgrade --check'
|
|
|
|
```
|
|
If an update is available, you can rerun the above command and remove the `--check` and your operating system will
|
|
be updated. After updating, you must stop and start your machine with `podman machine stop && podman machine start` for
|
|
it to take effect.
|
|
|
|
Note: Updating as described above can result in version mismatches between Podman on the host and Podman in the
|
|
machine. Executing `podman info` should reveal versions of both. A configuration where the Podman host and machine
|
|
mismatch are unsupported.
|
|
|
|
For more information on updates and advanced configuration,
|
|
see the Fedora CoreOS documentation about [auto-updates](https://docs.fedoraproject.org/en-US/fedora-coreos/auto-updates/) and [update strategies](https://coreos.github.io/zincati/usage/updates-strategy/).
|
|
|
|
|
|
|
|
|
|
Fedora CoreOS upgrades come out every 14 days and are detected and installed automatically. The VM is rebooted during the upgrade.
|
|
For more information on updates and advanced configuration,
|
|
see the Fedora CoreOS documentation about [auto-updates](https://docs.fedoraproject.org/en-US/fedora-coreos/auto-updates/) and [update strategies](https://coreos.github.io/zincati/usage/updates-strategy/).
|
|
|
|
## OPTIONS
|
|
|
|
#### **--cpus**=*number*
|
|
|
|
Number of CPUs.
|
|
|
|
#### **--disk-size**=*number*
|
|
|
|
Size of the disk for the guest VM in GiB.
|
|
|
|
#### **--help**
|
|
|
|
Print usage statement.
|
|
|
|
#### **--ignition-path**
|
|
|
|
Fully qualified path of the ignition file.
|
|
|
|
If an ignition file is provided, the file
|
|
is copied into the user's CONF_DIR and renamed. Additionally, no SSH keys are generated, nor are any system connections made. It is assumed that the user does these things manually or handled otherwise.
|
|
|
|
#### **--image**
|
|
|
|
Fully qualified registry, path, or URL to a VM image.
|
|
Registry target must be in the form of `docker://registry/repo/image:version`.
|
|
|
|
#### **--memory**, **-m**=*number*
|
|
|
|
Memory (in MiB). Note: 1024MiB = 1GiB.
|
|
|
|
#### **--now**
|
|
|
|
Start the virtual machine immediately after it has been initialized.
|
|
|
|
#### **--rootful**
|
|
|
|
Whether this machine prefers rootful (`true`) or rootless (`false`)
|
|
container execution. This option determines the remote connection default
|
|
if there is no existing remote connection configurations.
|
|
|
|
API forwarding, if available, follows this setting.
|
|
|
|
#### **--timezone**
|
|
|
|
Set the timezone for the machine and containers. Valid values are `local` or
|
|
a `timezone` such as `America/Chicago`. A value of `local`, which is the default,
|
|
means to use the timezone of the machine host.
|
|
|
|
The timezone setting is not used with WSL. WSL automatically sets the timezone to the same
|
|
as the host Windows operating system.
|
|
|
|
#### **--usb**=*bus=number,devnum=number* or *vendor=hexadecimal,product=hexadecimal*
|
|
|
|
Assign a USB device from the host to the VM via USB passthrough.
|
|
Only supported for QEMU Machines.
|
|
|
|
The device needs to have proper permissions in order to be passed to the machine. This
|
|
means the device needs to be under your user group.
|
|
|
|
Note that using bus and device number are simpler but the values can change every boot
|
|
or when the device is unplugged.
|
|
|
|
When specifying a USB using vendor and product ID's, if more than one device has the
|
|
same vendor and product ID, the first available device is assigned.
|
|
|
|
@@option user-mode-networking
|
|
|
|
#### **--username**
|
|
|
|
Username to use for executing commands in remote VM. Default value is `core`
|
|
for FCOS and `user` for Fedora (default on Windows hosts). Should match the one
|
|
used inside the resulting VM image.
|
|
|
|
#### **--volume**, **-v**=*source:target[:options]*
|
|
|
|
Mounts a volume from source to target.
|
|
|
|
Create a mount. If /host-dir:/machine-dir is specified as the `*source:target*`,
|
|
Podman mounts _host-dir_ in the host to _machine-dir_ in the Podman machine.
|
|
|
|
Additional options may be specified as a comma-separated string. Recognized
|
|
options are:
|
|
* **ro**: mount volume read-only
|
|
* **rw**: mount volume read/write (default)
|
|
* **security_model=[model]**: specify 9p security model (see below)
|
|
|
|
The 9p security model [determines] https://wiki.qemu.org/Documentation/9psetup#Starting_the_Guest_directly
|
|
if and how the 9p filesystem translates some filesystem operations before
|
|
actual storage on the host.
|
|
|
|
In order to allow symlinks to work, on MacOS the default security model is
|
|
*none*.
|
|
|
|
The value of *mapped-xattr* specifies that 9p store symlinks and some file
|
|
attributes as extended attributes on the host. This is suitable when the host
|
|
and the guest do not need to interoperate on the shared filesystem, but has
|
|
caveats for actual shared access; notably, symlinks on the host are not usable
|
|
on the guest and vice versa. If interoperability is required, then choose
|
|
*none* instead, but keep in mind that the guest is not able to do things
|
|
that the user running the virtual machine cannot do, e.g. create files owned by
|
|
another user. Using *none* is almost certainly the best choice for read-only
|
|
volumes.
|
|
|
|
Example: `-v "$HOME/git:$HOME/git:ro,security_model=none"`
|
|
|
|
Default volume mounts are defined in *containers.conf*. Unless changed, the default values
|
|
is `$HOME:$HOME`.
|
|
|
|
#### **--volume-driver**
|
|
|
|
Driver to use for mounting volumes from the host, such as `virtfs`.
|
|
|
|
## EXAMPLES
|
|
|
|
Initialize the default Podman machine, pulling the content from the internet.
|
|
```
|
|
$ podman machine init
|
|
```
|
|
|
|
Initialize a Podman machine for the specified name pulling the content from the internet.
|
|
```
|
|
$ podman machine init myvm
|
|
```
|
|
|
|
Initialize the default Podman machine pulling the content from the internet defaulting to rootful mode. The default is rootless.
|
|
```
|
|
$ podman machine init --rootful
|
|
```
|
|
|
|
Initialize the default Podman machine overriding its disk size override, pulling the content from the internet.
|
|
```
|
|
$ podman machine init --disk-size 50
|
|
```
|
|
|
|
Initialize the specified Podman machine overriding its memory size, pulling the content from the internet.
|
|
```
|
|
$ podman machine init --memory=1024 myvm
|
|
```
|
|
|
|
Initialize the default Podman machine with the host directory `/Users` mounted into the VM at `/mnt/Users`.
|
|
```
|
|
$ podman machine init -v /Users:/mnt/Users
|
|
```
|
|
|
|
Initialize the default Podman machine with a usb device passthrough specified with options. Only supported for QEMU Machines.
|
|
```
|
|
$ podman machine init --usb vendor=13d3,product=5406
|
|
```
|
|
|
|
Initialize the default Podman machine with a usb device passthrough with specified with options. Only supported for QEMU Machines.
|
|
```
|
|
$ podman machine init --usb bus=1,devnum=3
|
|
```
|
|
|
|
## SEE ALSO
|
|
**[podman(1)](podman.1.md)**, **[podman-machine(1)](podman-machine.1.md)**
|
|
|
|
## HISTORY
|
|
March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
|