README.md

DEPRECATED

Podman v3.3 now has a podman machine included, different from podman-machine:

https://podman.io/community/meeting/notes/2021-04-06/#podman-on-mac-preview

That is a new feature based on QEMU and CoreOS, unlike the old one (described here)
which is based on Docker Machine and Boot2Docker, as was available in Docker Toolbox...

See also: https://boot2podman.github.io/2020/11/03/boot2podman-project.html

Podman Machine (old) is now deprecated. Users should try using Vagrant instead.
You can create a similar VM, running Fedora (for podman) or Ubuntu (for docker)

Details: https://boot2podman.github.io/2020/07/22/machine-replacement.html

Podman itself is only available for Linux systems, not Mac or Windows.

Podman Machine

Machine lets you create Podman hosts on your computer. It creates servers with Podman on them, then configures the Podman client to talk to them.

❗ Only works with Podman v1, due to breaking changes in Podman v2
For details see https://podman.io/blogs/2020/06/29/podman-v2-announce.html

For Podman version 2, 3 and 4 please see the documentation at https://podman.io/

Download

Binaries can be found in: https://github.com/boot2podman/machine/releases

Get the version for your operating system and architecture, and put it in your path, adding executable permissions if needed.

Linux (GNU)

mv podman-machine.linux-amd64 <your-bin-dir>/podman-machine
chmod +x podman-machine

Darwin (OS X)

mv podman-machine.darwin-amd64 <your-bin-dir>/podman-machine
chmod +x podman-machine

Windows

podman-machine.windows-amd64.exe -> podman-machine.exe

You also need a supported Virtual Machine environment, such as VirtualBox or QEMU.

You will also need an SSH client installed for the varlink bridge on windows, such as SSH for Windows

Additional VM environments are possible too, after installing third party machine drivers.

ISO image

The default is to use the latest version of boot2podman.iso:

https://github.com/boot2podman/boot2podman/releases/latest/download/boot2podman.iso

108M boot2podman.iso

But it is also possible to use a version based on Fedora instead:

https://github.com/boot2podman/boot2podman-fedora-iso/releases/latest/download/boot2podman-fedora.iso

367M boot2podman-fedora.iso

The tool will automatically download, optionally with parameter:

--virtualbox-boot2podman-url

If the above URLs do not work, you can also download the file...

Then you can use a file:// URL to choose the ISO image to use.

Getting Started

$ podman-machine create box
Running pre-create checks...
Creating machine...
(box) Creating VirtualBox VM...
(box) Creating SSH key...
(box) Starting the VM...
(box) Check network to re-create if needed...
(box) Waiting for an IP...
Waiting for machine to be running, this may take a few minutes...
Detecting operating system of created instance...
Waiting for SSH to be available...
Detecting the provisioner...
Provisioning with boot2podman...
Copying certs to the local machine directory...
Copying certs to the remote machine...
Checking connection to Podman...
Podman is up and running!

$ podman-machine ssh box
        .---.        b o o t 2                 mm             https://podman.io
       /o   o\                                 ##                              
    __(=  "  =)__    ##m###m    m####m    m###m##  ####m##m   m#####m  ##m####m
     //\'-=-'/\\     ##"  "##  ##"  "##  ##"  "##  ## ## ##   " mmm##  ##"   ##
        )   (        ##    ##  ##    ##  ##    ##  ## ## ##  m##"""##  ##    ##
       /     \       ###mm##"  "##mm##"  "##mm###  ## ## ##  ##mmm###  ##    ##
  ____/  / \  \____  ## """      """"      """ ""  "" "" ""   """" ""  ""    ""
 `------'`"`'------' ##                                                art: jgs
tc@box:~$ sudo podman run busybox echo hello world
Trying to pull docker.io/busybox:latest...Getting image source signatures
Copying blob sha256:90e01955edcd85dac7985b72a8374545eac617ccdddcc992b732e43cd42534af
 710.92 KB / 710.92 KB [====================================================] 0s
Copying config sha256:59788edf1f3e78cd0ebe6ce1446e9d10788225db3dedcfd1a59f764bad2b2690
 1.46 KB / 1.46 KB [========================================================] 0s
Writing manifest to image destination
Storing signatures
hello world
tc@box:~$ exit

Connecting

podman

You can run the podman command over ssh:

$ podman-machine ssh box -- sudo podman version

Show the available commands using the help:

$ podman-machine ssh box -- sudo podman --help

If you don't have ssh installed, you can run:

podman-machine --native-ssh ssh

podman-remote

Set up the $PODMAN_VARLINK_BRIDGE variable:

Bash

$ podman-machine env box --varlink
$ eval $(podman-machine env box --varlink)

Powershell

> podman-machine env box --varlink
> & podman-machine env box --varlink | Invoke-Expression

Then the commands will run remotely over ssh:

$ podman-remote version
$ podman-remote --help

See https://github.com/containers/libpod/blob/master/docs/source/markdown/podman-remote.1.md

Binaries can be found in: https://github.com/boot2podman/libpod/releases

Get the version for your operating system and architecture, and put it in your path:

Linux (GNU)

podman-remote-linux -> podman-remote (or maybe just podman)

Darwin (OS X)

podman-remote-darwin -> podman

Windows

podman-remote-windows.exe -> podman.exe

pypodman

Or you can use the pypodman tool remotely:

$ eval $(podman-machine env box)
$ pypodman version
$ pypodman --help

This will use environment variables to connect.

See https://github.com/containers/python-podman/tree/master

varlink

Connect directly with varlink over the bridge:

$ eval $(podman-machine env box --varlink)
$ varlink call io.podman.GetVersion
$ varlink help io.podman

You might need --bridge="$PODMAN_VARLINK_BRIDGE".

See https://github.com/varlink/libvarlink/tree/master/tool

Accessing files

Only files on the virtual machine are seen by containers.

$ ls /tmp/foo
bar
$ podman-machine ssh box -- sudo podman run -v /tmp/foo:/foo busybox ls /foo
error checking path "/tmp/foo": stat /tmp/foo: no such file or directory

This means that files to be used must be located there.

There is currently no access to any network filesystems.

In order to copy files, you can use the command scp:

podman-machine scp [machine:][path] [machine:][path]

To mount files locally using SSHFS, you can use mount:

podman-machine mount [machine:][path] [mountpoint]

In order to make files persist, they need to be on a disk.

The default mountpoint (for /dev/sda1) is: /mnt/sda1

Accessing ports

Depending on the driver, the machine might get its own IP.

$ podman-machine ip
192.168.99.101

If you don't get a machine IP, then you can use SSH tunneling.

$ podman-machine ip
127.0.0.1

Then you can forward local ports, over to the virtual machine.

From there, they can access any ports published by containers.

This is done by starting a ssh command, as a background process.

$ podman-machine ssh box -L 8080:localhost:8080 -N &
[1] 4229
$ podman-machine ssh box -- sudo podman run -d -p 8080:80 nginx
18fde6761ea5df5c5170bc5c8d6709401b70957175ab8f6269e6024d9e577110

To stop the tunnel, just end the process (4229 above) using kill.

$ kill 4229
[1]+  Terminated              podman-machine ssh box -L 8080:localhost:8080 -N
$ podman-machine ssh box -- sudo podman stop 18fde6761ea5
18fde6761ea5df5c5170bc5c8d6709401b70957175ab8f6269e6024d9e577110

Installing tools

If you need to install e.g. git, you can download and install it:

$ tce-load -wi git
git.tcz.dep OK
...
git.tcz: OK
$ git --version
git version 2.18.0

This was for the default tinycore distro, other ISO might differ...

Driver Plugins

These core driver plugins are bundled:

• Generic
• VirtualBox
• QEMU (KVM)

It is possible to add standalone drivers.

Cloud Drivers

Cloud drivers are explicitly not supported.

Please use Kubernetes for that, instead.

Inspiration

Podman Machine is inspired by Docker Machine, which is a similar solution but for another popular container runtime.

Docker Machine is Copyright 2014 Docker, Inc.

Licensed under the Apache License, Version 2.0