mirror of https://github.com/containers/podman.git
399 lines
12 KiB
Markdown
399 lines
12 KiB
Markdown
# libpod Installation Instructions
|
|
|
|
## Installing packaged versions of Podman
|
|
|
|
#### [Arch Linux](https://www.archlinux.org)
|
|
|
|
```bash
|
|
sudo pacman -S podman
|
|
```
|
|
|
|
If you have problems when running Podman in [rootless](README.md#rootless) mode follow the instructions [here](https://wiki.archlinux.org/index.php/Linux_Containers#Enable_support_to_run_unprivileged_containers_(optional))
|
|
|
|
#### [Fedora](https://www.fedoraproject.org), [CentOS](https://www.centos.org)
|
|
|
|
```bash
|
|
sudo yum -y install podman
|
|
```
|
|
|
|
#### [Fedora-CoreOS](https://coreos.fedoraproject.org), [Fedora SilverBlue](https://silverblue.fedoraproject.org)
|
|
|
|
Built-in, no need to install
|
|
|
|
#### [Gentoo](https://www.gentoo.org)
|
|
|
|
```bash
|
|
sudo emerge app-emulation/libpod
|
|
```
|
|
|
|
#### [openSUSE](https://www.opensuse.org)
|
|
|
|
```bash
|
|
sudo zypper install podman
|
|
```
|
|
|
|
#### [openSUSE Kubic](https://kubic.opensuse.org)
|
|
|
|
Built-in, no need to install
|
|
|
|
#### [RHEL7](https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux)
|
|
|
|
Subscribe, then enable Extras channel and install Podman.
|
|
|
|
```bash
|
|
sudo subscription-manager repos --enable=rhel-7-server-extras-rpms
|
|
sudo yum -y install podman
|
|
```
|
|
|
|
#### [RHEL8 Beta](https://www.redhat.com/en/blog/powering-its-future-while-preserving-present-introducing-red-hat-enterprise-linux-8-beta?intcmp=701f2000001Cz6OAAS)
|
|
|
|
```bash
|
|
sudo yum module enable -y container-tools:1.0
|
|
sudo yum module install -y container-tools:1.0
|
|
```
|
|
|
|
### Installing development versions of Podman
|
|
|
|
#### [Ubuntu](https://www.ubuntu.com)
|
|
|
|
The latest builds are available in a PPA. Take note of the [Build and Run Dependencies](#build-and-run-dependencies) listed below if you run into any issues.
|
|
|
|
```bash
|
|
sudo apt-get update -qq
|
|
sudo apt-get install -qq -y software-properties-common uidmap
|
|
sudo add-apt-repository -y ppa:projectatomic/ppa
|
|
sudo apt-get update -qq
|
|
sudo apt-get -qq -y install podman
|
|
```
|
|
|
|
#### Fedora
|
|
|
|
You can test the very latest Podman in Fedora's `updates-testing`
|
|
repository before it goes out to all Fedora users.
|
|
|
|
```console
|
|
sudo yum distro-sync --enablerepo=updates-testing podman
|
|
```
|
|
|
|
If you use a newer Podman package from Fedora's `updates-testing`, we would
|
|
appreciate your `+1` feedback in [Bodhi, Fedora's update management
|
|
system](https://bodhi.fedoraproject.org/updates/?packages=podman).
|
|
|
|
## Building from scratch
|
|
|
|
### Build and Run Dependencies
|
|
|
|
**Required**
|
|
|
|
Fedora, CentOS, RHEL, and related distributions:
|
|
|
|
```bash
|
|
sudo yum install -y \
|
|
atomic-registries \
|
|
btrfs-progs-devel \
|
|
containernetworking-cni \
|
|
device-mapper-devel \
|
|
git \
|
|
glib2-devel \
|
|
glibc-devel \
|
|
glibc-static \
|
|
go \
|
|
golang-github-cpuguy83-go-md2man \
|
|
gpgme-devel \
|
|
iptables \
|
|
libassuan-devel \
|
|
libgpg-error-devel \
|
|
libseccomp-devel \
|
|
libselinux-devel \
|
|
make \
|
|
ostree-devel \
|
|
pkgconfig \
|
|
runc \
|
|
containers-common
|
|
```
|
|
|
|
Debian, Ubuntu, and related distributions:
|
|
|
|
```bash
|
|
sudo apt-get install \
|
|
btrfs-tools \
|
|
git \
|
|
golang-go \
|
|
go-md2man \
|
|
iptables \
|
|
libassuan-dev \
|
|
libc6-dev \
|
|
libdevmapper-dev \
|
|
libglib2.0-dev \
|
|
libgpgme-dev \
|
|
libgpg-error-dev \
|
|
libostree-dev \
|
|
libprotobuf-dev \
|
|
libprotobuf-c0-dev \
|
|
libseccomp-dev \
|
|
libselinux1-dev \
|
|
libsystemd-dev \
|
|
pkg-config \
|
|
runc \
|
|
uidmap
|
|
```
|
|
|
|
### Building missing dependencies
|
|
|
|
If any dependencies cannot be installed or are not sufficiently current, they have to be built from source.
|
|
This will mainly affect Debian, Ubuntu, and related distributions, or RHEL where no subscription is active (e.g. Cloud VMs).
|
|
|
|
#### ostree
|
|
|
|
A copy of the development libraries for `ostree` is necessary, either in the form of the `libostree-dev` package
|
|
from the [flatpak](https://launchpad.net/~alexlarsson/+archive/ubuntu/flatpak) PPA,
|
|
or built [from source](https://github.com/ostreedev/ostree/blob/master/docs/contributing-tutorial.md)
|
|
(see also [here](https://ostree.readthedocs.io/en/latest/#building)). As of Ubuntu 18.04, `libostree-dev` is available in the main repositories,
|
|
and the PPA is no longer required.
|
|
|
|
To build, use the following (running `make` can take a while):
|
|
```bash
|
|
git clone https://github.com/ostreedev/ostree ~/ostree
|
|
cd ~/ostree
|
|
git submodule update --init
|
|
# for Fedora, CentOS, RHEL
|
|
sudo yum install -y automake bison e2fsprogs-devel fuse-devel libtool xz-devel zlib-devel
|
|
# for Debian, Ubuntu etc.
|
|
sudo apt-get install -y automake bison e2fsprogs e2fslibs-dev fuse libfuse-dev libgpgme-dev liblzma-dev libtool zlib1g
|
|
|
|
./autogen.sh --prefix=/usr --libdir=/usr/lib64 --sysconfdir=/etc
|
|
# remove --nonet option due to https:/github.com/ostreedev/ostree/issues/1374
|
|
sed -i '/.*--nonet.*/d' ./Makefile-man.am
|
|
make
|
|
sudo make install
|
|
```
|
|
|
|
#### golang
|
|
|
|
Be careful to double-check that the version of golang is new enough (i.e. `go version`), version 1.10.x or higher is required.
|
|
If needed, golang kits are available at https://golang.org/dl/. Alternatively, go can be built from source as follows
|
|
(it's helpful to leave the system-go installed, to avoid having to [bootstrap go](https://golang.org/doc/install/source):
|
|
|
|
```bash
|
|
export GOPATH=~/go
|
|
git clone https://go.googlesource.com/go $GOPATH
|
|
cd $GOPATH
|
|
git checkout tags/go1.10.8 # optional
|
|
cd src
|
|
./all.bash
|
|
export PATH=$GOPATH/bin:$PATH
|
|
```
|
|
|
|
#### conmon
|
|
|
|
The latest version of `conmon` is expected to be installed on the system. Conmon is used to monitor OCI Runtimes.
|
|
To build from source, use the following:
|
|
|
|
```bash
|
|
git clone https://github.com/containers/conmon
|
|
cd conmon
|
|
make
|
|
sudo make podman
|
|
```
|
|
|
|
#### runc
|
|
|
|
The latest version of `runc` is expected to be installed on the system. It is picked up as the default runtime by Podman.
|
|
Version 1.0.0-rc4 is the minimal requirement, which is available in Ubuntu 18.04 already.
|
|
To double-check, `runc --version` should produce at least `spec: 1.0.1`, otherwise build your own:
|
|
|
|
```bash
|
|
git clone https://github.com/opencontainers/runc.git $GOPATH/src/github.com/opencontainers/runc
|
|
cd $GOPATH/src/github.com/opencontainers/runc
|
|
make BUILDTAGS="selinux seccomp"
|
|
sudo cp runc /usr/bin/runc
|
|
```
|
|
|
|
#### CNI plugins
|
|
|
|
```bash
|
|
git clone https://github.com/containernetworking/plugins.git $GOPATH/src/github.com/containernetworking/plugins
|
|
cd $GOPATH/src/github.com/containernetworking/plugins
|
|
./build_linux.sh
|
|
sudo mkdir -p /usr/libexec/cni
|
|
sudo cp bin/* /usr/libexec/cni
|
|
```
|
|
|
|
#### Setup CNI networking
|
|
|
|
A proper description of setting up CNI networking is given in the [`cni` README](cni/README.md).
|
|
|
|
Using the CNI plugins from above, a more basic network config is achieved with:
|
|
|
|
```bash
|
|
mkdir -p /etc/cni/net.d
|
|
curl -qsSL https://raw.githubusercontent.com/containers/libpod/master/cni/87-podman-bridge.conflist | sudo tee /etc/cni/net.d/99-loopback.conf
|
|
```
|
|
|
|
|
|
#### Add configuration
|
|
|
|
```bash
|
|
sudo mkdir -p /etc/containers
|
|
sudo curl https://raw.githubusercontent.com/projectatomic/registries/master/registries.fedora -o /etc/containers/registries.conf
|
|
sudo curl https://raw.githubusercontent.com/containers/skopeo/master/default-policy.json -o /etc/containers/policy.json
|
|
```
|
|
|
|
|
|
#### Optional packages
|
|
|
|
Fedora, CentOS, RHEL, and related distributions:
|
|
|
|
(no optional packages)
|
|
|
|
Debian, Ubuntu, and related distributions:
|
|
|
|
```bash
|
|
apt-get install -y \
|
|
libapparmor-dev
|
|
```
|
|
|
|
### Get Source Code
|
|
|
|
As with other Go projects, Podman must be cloned into a directory structure like:
|
|
|
|
```
|
|
GOPATH
|
|
└── src
|
|
└── github.com
|
|
└── containers
|
|
└── libpod
|
|
```
|
|
|
|
First, ensure that the go version that is found first on the $PATH (in case you built your own; see [above](#golang)) is sufficiently recent -
|
|
`go version` must be higher than 1.10.x). Then we can finally build Podman (assuming we already have a `$GOPATH` and the corresponding folder,
|
|
`export GOPATH=~/go && mkdir -p $GOPATH`):
|
|
|
|
```bash
|
|
git clone https://github.com/containers/libpod/ $GOPATH/src/github.com/containers/libpod
|
|
cd $GOPATH/src/github.com/containers/libpod
|
|
make BUILDTAGS="selinux seccomp"
|
|
sudo make install PREFIX=/usr
|
|
```
|
|
|
|
#### Build Tags
|
|
|
|
Otherwise, if you do not want to build Podman with seccomp or selinux support you can add `BUILDTAGS=""` when running make.
|
|
|
|
```bash
|
|
make BUILDTAGS=""
|
|
sudo make install
|
|
```
|
|
|
|
Podman supports optional build tags for compiling support of various features.
|
|
To add build tags to the make option the `BUILDTAGS` variable must be set, for example:
|
|
|
|
```bash
|
|
make BUILDTAGS='seccomp apparmor'
|
|
```
|
|
|
|
| Build Tag | Feature | Dependency |
|
|
|-----------|------------------------------------|-------------|
|
|
| seccomp | syscall filtering | libseccomp |
|
|
| selinux | selinux process and mount labeling | libselinux |
|
|
| apparmor | apparmor profile support | libapparmor |
|
|
|
|
### Vendoring - Dependency Management
|
|
|
|
This project is using [go modules](https://github.com/golang/go/wiki/Modules) for dependency management. If the CI is complaining about a pull request leaving behind an unclean state, it is very likely right about it. After changing dependencies, make sure to run `make vendor` to synchronize the code with the go module and repopulate the `./vendor` directory.
|
|
|
|
## Configuration files
|
|
|
|
### [registries.conf](https://src.fedoraproject.org/rpms/skopeo/blob/master/f/registries.conf)
|
|
|
|
#### Man Page: [registries.conf.5](https://github.com/containers/image/blob/master/docs/registries.conf.5.md)
|
|
|
|
`/etc/containers/registries.conf`
|
|
|
|
registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion.
|
|
|
|
#### Example from the Fedora `containers-common` package
|
|
|
|
```
|
|
cat /etc/containers/registries.conf
|
|
# This is a system-wide configuration file used to
|
|
# keep track of registries for various container backends.
|
|
# It adheres to TOML format and does not support recursive
|
|
# lists of registries.
|
|
|
|
# The default location for this configuration file is /etc/containers/registries.conf.
|
|
|
|
# The only valid categories are: 'registries.search', 'registries.insecure',
|
|
# and 'registries.block'.
|
|
|
|
[registries.search]
|
|
registries = ['docker.io', 'registry.fedoraproject.org', 'quay.io', 'registry.access.redhat.com', 'registry.centos.org']
|
|
|
|
# If you need to access insecure registries, add the registry's fully-qualified name.
|
|
# An insecure registry is one that does not have a valid SSL certificate or only does HTTP.
|
|
[registries.insecure]
|
|
registries = []
|
|
|
|
|
|
# If you need to block pull access from a registry, uncomment the section below
|
|
# and add the registries fully-qualified name.
|
|
#
|
|
[registries.block]
|
|
registries = []
|
|
```
|
|
|
|
### [mounts.conf](https://src.fedoraproject.org/rpms/skopeo/blob/master/f/mounts.conf)
|
|
|
|
`/usr/share/containers/mounts.conf` and optionally `/etc/containers/mounts.conf`
|
|
|
|
The mounts.conf files specify volume mount directories that are automatically mounted inside containers when executing the `podman run` or `podman build` commands. Container process can then use this content. The volume mount content does not get committed to the final image.
|
|
|
|
Usually these directories are used for passing secrets or credentials required by the package software to access remote package repositories.
|
|
|
|
For example, a mounts.conf with the line "`/usr/share/rhel/secrets:/run/secrets`", the content of `/usr/share/rhel/secrets` directory is mounted on `/run/secrets` inside the container. This mountpoint allows Red Hat Enterprise Linux subscriptions from the host to be used within the container.
|
|
|
|
Note this is not a volume mount. The content of the volumes is copied into container storage, not bind mounted directly from the host.
|
|
|
|
#### Example from the Fedora `containers-common` package:
|
|
|
|
```
|
|
cat /usr/share/containers/mounts.conf
|
|
/usr/share/rhel/secrets:/run/secrets
|
|
```
|
|
|
|
### [seccomp.json](https://src.fedoraproject.org/rpms/skopeo/blob/master/f/seccomp.json)
|
|
|
|
`/usr/share/containers/seccomp.json`
|
|
|
|
seccomp.json contains the whitelist of seccomp rules to be allowed inside of
|
|
containers. This file is usually provided by the containers-common package.
|
|
|
|
The link above takes you to the seccomp.json
|
|
|
|
### [policy.json](https://github.com/containers/skopeo/blob/master/default-policy.json)
|
|
|
|
`/etc/containers/policy.json`
|
|
|
|
#### Man Page: [policy.json.5](https://github.com/containers/image/blob/master/docs/policy.json.md)
|
|
|
|
|
|
#### Example from the Fedora `containers-common` package:
|
|
|
|
```
|
|
cat /etc/containers/policy.json
|
|
{
|
|
"default": [
|
|
{
|
|
"type": "insecureAcceptAnything"
|
|
}
|
|
],
|
|
"transports":
|
|
{
|
|
"docker-daemon":
|
|
{
|
|
"": [{"type":"insecureAcceptAnything"}]
|
|
}
|
|
}
|
|
}
|
|
```
|