% 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 a custom [Fedora CoreOS](https://getfedora.org/en/coreos?stream=stable)
based image pushed to quay.io/podman/machine-os (build in https://github.com/containers/podman-machine-os).
WSL is an exception and is based on a custom Fedora image.

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.

The above mechanism is only used to update patch (Z) versions of podman. For updates to new major and minor
version (X.Y) use the **[podman machine os apply](podman-machine-os-apply.1.md)** command, see the docs there for
more information.

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.

To update the WSL image you must run dnf update inside, use the following command:
```
$ podman machine ssh dnf update
```

Default Podman machine settings can be set via the [machine] section in the containers.conf(5) file.

## 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`.

Note: Only images provided by podman will be supported.

#### **--memory**, **-m**=*number*

Memory (in MiB). Note: 1024MiB = 1GiB.

#### **--now**

Start the virtual machine immediately after it has been initialized.

#### **--playbook**

Add the provided Ansible playbook to the machine and execute it after the first boot.

Note: The playbook will be executed with the same privileges given to the user in the virtual machine. The playbook provided cannot include other files from the host system, as they will not be copied.
Use of the `--playbook` flag will require the image to include Ansible. The default image provided will have Ansible included.

#### **--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.

#### **--swap**, **-s**=*number*

Swap (in MiB). Note: 1024MiB = 1GiB.

Renders a `zram-generator.conf` file with zram-size set to the value passed to --swap

#### **--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.

@@option tls-verify

#### **--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)

Note: The following destinations are forbidden for volumes: `/bin`, `/boot`, `/dev`, `/etc`,
`/home`, `/proc`, `/root`, `/run`, `/sbin`, `/sys`, `/tmp`, `/usr`, and `/var`. Subdirectories
of these destinations are allowed but users should be careful to not mount to important directories
as unexpected results may occur.


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`.

**Note on Windows Subsystem for Linux (WSL)**
Since all drives are mounted at `/mnt` on startup by default in WSL, passing
`--volume` is redundant and has no effect. The host home directory for a `C:`
drive will be mounted at `/mnt/c/Users/<my username>`.

## 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 and start a new Podman machine in one step.

```
podman machine init --now
```

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 `/Users`.
```
$ podman machine init -v /Users:/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)**, **containers.conf(5)**

## HISTORY
March 2021, Originally compiled by Ashley Cui <acui@redhat.com>
