podman-machine-init

podman-machine-init(1) General Commands Manual 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 ac‐
   count and a user account inside the VM are added.

   By default, the VM distribution is Fedora CoreOS 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 con
   figuration 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 and update strategies.

   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 con
   figuration, see the Fedora CoreOS documentation about auto-updates and update strategies.

   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.

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

--user-mode-networking

   Indicates  that this machine relays traffic from the guest through a user-space process running on the host. In some VPN configurations the VPN may drop traffic from alternate network
   interfaces, including VM network devices. By enabling user-mode networking (a setting of true), VPNs observe all podman machine traffic as coming from the host, bypassing the problem.

   When the qemu backend is used (Linux, Mac), user-mode networking is mandatory and the only allowed value is true. In contrast, The Windows/WSL backend defaults to false,  and  follows
   the  standard  WSL  network  setup.  Changing this setting to true on Windows/WSL informs Podman to replace the WSL networking setup on start of this machine instance with a user-mode
   networking distribution. Since WSL shares the same kernel across distributions, all other running distributions reuses this network.  Likewise, when the last machine instance  with  a
   true setting stops, the original networking setup is restored.

--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 in
   teroperate  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 re
   quired, 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 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-machine(1), containers.conf(5)

HISTORY

   March 2021, Originally compiled by Ashley Cui acui@redhat.com mailto:acui@redhat.com

                                                                                                                                                                    podman-machine-init(1)