oracular (1) docker-machine-init.1.gz

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

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.

   --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 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-machine(1)

HISTORY

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

                                                                                          podman-machine-init(1)