.nh
.TH podman-machine-init 1
.SH NAME
.PP
podman-machine-init - Initialize a new virtual machine

.SH SYNOPSIS
.PP
\fBpodman machine init\fP [\fIoptions\fP] [\fIname\fP]

.SH DESCRIPTION
.PP
Initialize a new virtual machine for Podman.

.PP
Rootless only.

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

.PP
\fBpodman machine init\fP 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.

.PP
By default, the VM distribution is Fedora CoreOS.
Fedora CoreOS upgrades come out every 14 days and are detected and installed automatically. The VM will be rebooted during the upgrade.
For more information on updates and advanced configuration, please see the FCOS update docs here and here.

.SH OPTIONS
.SS \fB--cpus\fP=\fInumber\fP
.PP
Number of CPUs.

.SS \fB--disk-size\fP=\fInumber\fP
.PP
Size of the disk for the guest VM in GB.

.SS \fB--help\fP
.PP
Print usage statement.

.SS \fB--ignition-path\fP
.PP
Fully qualified path of the ignition file.

.PP
If an ignition file is provided, the file
will be copied into the user's CONF_DIR and renamed.  Additionally, no SSH keys will
be generated nor will a system connection be made.  It is assumed that the user will
do these things manually or handle otherwise.

.SS \fB--image-path\fP
.PP
Fully qualified path or URL to the VM image.
Can also be set to \fB\fCtesting\fR, \fB\fCnext\fR, or \fB\fCstable\fR to pull down default image.
Defaults to \fB\fCtesting\fR\&.

.SS \fB--memory\fP, \fB-m\fP=\fInumber\fP
.PP
Memory (in MB).

.SS \fB--now\fP
.PP
Start the virtual machine immediately after it has been initialized.

.SS \fB--rootful\fP
.PP
Whether this machine should prefer rootful (\fB\fCtrue\fR) or rootless (\fB\fCfalse\fR)
container execution. This option will also determine the remote connection default
if there is no existing remote connection configurations.

.PP
API forwarding, if available, will follow this setting.

.SS \fB--timezone\fP
.PP
Set the timezone for the machine and containers.  Valid values are \fB\fClocal\fR or
a \fB\fCtimezone\fR such as \fB\fCAmerica/Chicago\fR\&.  A value of \fB\fClocal\fR, which is the default,
means to use the timezone of the machine host.

.SS \fB--username\fP
.PP
Username to use for executing commands in remote VM. Default value is \fB\fCcore\fR
for FCOS and \fB\fCuser\fR for Fedora (default on Windows hosts). Should match the one
used inside the resulting VM image.

.SS \fB--volume\fP, \fB-v\fP=\fIsource:target[:options]\fP
.PP
Mounts a volume from source to target.

.PP
Create a mount. If /host-dir:/machine-dir is specified as the \fB\fC*source:target*\fR,
Podman mounts \fIhost-dir\fP in the host to \fImachine-dir\fP in the Podman machine.

.PP
Additional options may be specified as a comma-separated string. Recognized
options are:
* \fBro\fP: mount volume read-only
* \fBrw\fP: mount volume read/write (default)
* \fBsecurity_model=[model]\fP: specify 9p security model (see below)

.PP
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. The
default value of \fImapped-xattr\fP 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
\fInone\fP instead, but keep in mind that the guest will not be able to do things
that the user running the virtual machine cannot do, e.g. create files owned by
another user. Using \fInone\fP is almost certainly the best choice for read-only
volumes.

.PP
Example: \fB\fC-v "$HOME/git:$HOME/git:ro,security_model=none"\fR

.PP
Default volume mounts are defined in \fIcontainers.conf\fP\&.  Unless changed, the default values
is \fB\fC$HOME:$HOME\fR\&.

.SS \fB--volume-driver\fP
.PP
Driver to use for mounting volumes from the host, such as \fB\fCvirtfs\fR\&.

.SH EXAMPLES
.PP
.RS

.nf
$ podman machine init
$ podman machine init myvm
$ podman machine init --rootful
$ podman machine init --disk-size 50
$ podman machine init --memory=1024 myvm
$ podman machine init -v /Users:/mnt/Users

.fi
.RE

.SH SEE ALSO
.PP
\fBpodman(1)\fP, \fBpodman-machine(1)\fP

.SH HISTORY
.PP
March 2021, Originally compiled by Ashley Cui acui@redhat.com
\[la]mailto:acui@redhat.com\[ra]