Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 ma-
       chine must be used to manage MacOS and Windows machines,	but can	be op-
       tionally	used on	Linux.

       podman machine init initializes a new Linux virtual machine where  con-
       tainers	are  run.   SSH	keys are automatically generated to access the
       VM, and system connections to the root account and a user  account  in-
       side 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  be-
       tween  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 Fe-
       dora CoreOS documentation about auto-updates and	update strategies.

       Fedora  CoreOS upgrades come out	every 14 days and are detected and in-
       stalled 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.

       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.

   --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)  con-
       tainer  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  lo-
       cal  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,  by-
       passing 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  Win-
       dows/WSL	 backend  defaults to false, and follows the standard WSL net-
       work setup.  Changing this setting to true on Windows/WSL informs  Pod-
       man  to	replace	 the WSL networking setup on start of this machine in-
       stance 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.	Recog-
       nized  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/Documenta-
       tion/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 interoper-
       ability 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 in-
       ternet.

       $ 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 in-
       ternet defaulting to rootful mode. The default is rootless.

       $ podman	machine	init --rootful

       Initialize the default Podman machine overriding	its  disk  size	 over-
       ride, 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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=podman-machine-init&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help