1. Podman User's Guide
  2. Configuring Networking for Podman

5 Configuring Networking for Podman

The networking information in this chapter enable you to understand how to configure the different networking requirements for containers that run within Podman or when working with images and temporary containers within Buildah.

Podman handles the networking of containers differently depending on whether the containers are run by the root or privileged user or by a standard user on the host system. The root user has considerably more power to change network infrastructure on the host, but the standard user has limited ability to alter network infrastructure.

In a network setup for Podman, containers that are running within a pod or a group share the same networking namespace and therefore have access to the same IP and MAC addresses and port mappings. The shared namespace eases network communication between different containers or between the host and the containers running on it. For more information about pods, see Creating and Managing Pods.

Unless indicated otherwise, all the networking procedures in the sections that follow can be performed only by the root or privileged user.

Configuring Proxy Server Settings

Podman automatically uses the system proxy settings for commands that you run and for any containers that you provision.

You can apply proxy settings on a system-wide basis by adding these to /etc/profile: 

HTTP_PROXY=proxy_URL:port
HTTPS_PROXY=proxy_URL:port

Some services, such as the Cockpit web console, use the Podman API Systemd service to interact with Podman. To set the system proxy environment variables for services that use the Podman API, you can create a Systemd service drop-in.

  1. Create the /etc/systemd/system/podman.service.d directory, if it doesn't already exist, to host Systemd service drop-in configuration specific to the Podman API service.
    sudo mkdir -p /etc/systemd/system/podman.service.d
  2. Create or edit /etc/systemd/system/podman.service.d/http-proxy.conf to contain contents similar to:
    [Service]
Environment="HTTP_PROXY=proxy_URL:port"
Environment="HTTPS_PROXY=proxy_URL:port"

    Replace proxy_URL:port with the URL and port number for the proxy server that you need to use.

  3. Reload the Systemd configuration changes and restart the Podman API service:
    sudo systemctl daemon-reload
sudo systemctl restart podman

Note:

The Podman API service isn't required to use Podman. Only run this service if you use applications that use the API to interact with Podman, such as the Cockpit web console.

Configuring Port Mapping for Containers

Defining port mappings can be performed by both the root user and the standard user.

For containers that are run by the standard user, Podman relies on port mapping to use the existing network infrastructure that's available on the host system. Thus, a standard user can't and doesn't need to configure specific network settings such as assigning IP addresses for such containers. Podman handles the networking functionality for these containers automatically by performing port forwarding to container-based services.

Port publishing for a non-root user is limited to port numbers that are outside the range of the privileged port numbers, whose limit is port 1024. Therefore, when creating containers that are using a specific port mapping, ensure that the port number is set to a value greater than 1024. For example, to map port 8080 on the host to the container port 80, type: 

podman run -d -p 8080:80/tcp nginx:alpine

You can also use the -P option when running the container to enable Podman to automatically configure port mappings. However, the resulting configuration might be less predictable than you intend.

After a port mapping is established, you can access the port directly from the host where the container is running. From the previous example, the host can access port 80 on the container by opening a web browser to http://localhost:8080.

You can view a container's port mappings directly by using the following command: 

podman port container_id
80/tcp -> 0.0.0.0:8080

You can also see port mappings when you inspect a container. Use the podman port -a command to view all port mappings for all the containers running on the host.

Because the containers and the host share the same network namespace, a container can communicate directly with another container by using the IP address and the port mapping that the parent host uses. The easiest way for one container to connect to a port on another container is to connect to the host IP address and port mapping.

Extending the previous example, you can run a second container by using the following command, where 198.51.100.10 is the IP address of the host system: 

podman run -it --rm oraclelinux curl http://198.51.100.10:8080

External hosts can also connect to the container port mapping by using the host's IP address and the mapped port. However, if the host has firewall software running, you might need to open the firewall port for the container to be externally accessible.

Regardless of whether port mapping is performed by the root user or a standard user, the functionality operates in the same way for their respective containers.

Networking for containers that are run by standard users is understandably limited. Similar constraints apply to users who are setting up applications on a host within userspace. For more complex networking, containers must be run as the root user.

Configuring Advanced Networking for Containers

Advanced Podman network configuration can only be performed by the root user, and therefore applies only to containers that are run by the root user.

Advanced networking, which might require assigning IP addresses, enables containers to take advantage of particular features within the network stack to communicate with other containers in a pod. In this case, Podman implements a bridged network stack that can handle IP address assignment and full network access for each container.

For containers that are run by the root user, network management is achieved by using one of two backend network stacks:

  • Container Network Interface (CNI): A deprecated networking stack written in Golang and designed around the concept of plugins that can be used to implement different networking functions for a wide range of container related projects. See https://github.com/containernetworking/cni for more information.
  • Netavark: A network stack designed specifically for Podman, but compatible with other OCI container management applications. See https://github.com/containers/netavark

Podman selects which network stack to use automatically depending on which network stacks are available on a system. You can identify which network stack a system is using by running:

sudo podman info | grep networkBackend

Attention:

The podman network commands that are described in this section only work for containers that are run with root permissions. Running these commands with standard user containers returns an error code.

About CNI Networks

Note:

The CNI network stack is now deprecated and might be removed in future releases of Podman. Consider using Netavark instead. To change network stack, see Changing Network Backend. Although CNI is deprecated, Netavark doesn't support plugins available in CNI, such as the ability to connect to Kubernetes networks created using Flannel. You can continue to use CNI networking to take advantage of this facility, if required.

CNI is a broadly used set of network tooling that caters to container-based network requirements. CNI uses a plugin development model to accommodate different network functions and requirements. Podman can use many of these plugins directly to easily set up basic networking for individual containers or for containers running within a pod.

You can opt to use CNI as the default network backend to maintain consistent configuration with older Podman deployments.

To use CNI, you must install the containernetworking-plugins package.

For each network that you create within Podman, a new configuration file in JSON format is generated in the /etc/cni/net.d/ directory. In most instances, you don't need to edit or manage the files in this directory, as Podman can handle the files on your behalf.

A typical network configuration file might appear as follows:

{
   "cniVersion": "0.4.0",
   "name": "mynetwork",
   "plugins": [
      {
         "type": "bridge",
         "bridge": "cni-podman1",
         "isGateway": true,
         "ipMasq": true,
         "hairpinMode": true,
         "ipam": {
            "type": "host-local",
            "routes": [
               {
                  "dst": "0.0.0.0/0"
               }
            ],
            "ranges": [
               [
                  {
                     "subnet": "10.89.0.0/24",
                     "gateway": "10.89.0.1"
                  }
               ]
            ]
         },
         "capabilities": {
            "ips": true
         }
      },
      {
         "type": "portmap",
         "capabilities": {
            "portMappings": true
         }
      },
      {
         "type": "firewall",
         "backend": ""
      },
      {
         "type": "tuning"
      }
   ]
}

About Netavark Networks

Netavark is a high-performance network stack that can be used to configure network bridges, firewall rules, and system settings for containers. Netavark doesn't use plugins to perform configuration setup. All network set up actions are performed directly by the tool itself, which reduces overhead, and improves network setup performance when you run a container. Netavark provides improved handling of IPv6, particularly around Network Address Translation (NAT) and port forwarding. DNS is also automatically configured across networks so that containers with several networks can connect to any other container on any other shared network by using the container name as a resolvable DNS reference.

Use the Netavark backend if all deployments are using Podman version 4.0 or later and you intend only to run containers within Podman. Netavark provides better performance and features that make containers easily integrate into existing network infrastructure and improved DNS resolution.

To use Netavark, you must install the netavark package.

For each network that you create within Podman, a new configuration file in JSON format is generated in the /etc/containers/networks/ directory. In most instances, you don't need to edit or manage the files within these directories, as Podman can handle the files on your behalf.

A typical network configuration file might appear as follows:

{
     "name": "mynetwork",
     "id": "3977b0c90383b8460b75547576dba6ebcf67e815f0ed0c4b614af5cb329ebb83",
     "driver": "bridge",
     "network_interface": "podman1",
     "created": "2022-09-06T12:08:12.853219229Z",
     "subnets": [
          {
               "subnet": "10.89.0.0/24",
               "gateway": "10.89.0.1"
          }
     ],
     "ipv6_enabled": false,
     "internal": false,
     "dns_enabled": true,
     "ipam_options": {
          "driver": "host-local"
     }
}

You can display the contents of a network configuration file with the following command:

sudo podman inspect network_name

Changing Network Backend

You can switch between using the CNI and Netavark network backend stacks and force Podman to select one over the other. Switching from one to the other assumes that you have the packages for both network backend stacks installed, namely containernetworking-plugins and netavark.

Important:

If you change from one network backend to another, you must reset the podman configuration. Switching network backends effectively removes all existing containers, images, networks, and pods from an environment.

To change and permanently set the network backend for a deployment, perform the following steps:

  1. Check whether /etc/containers/containers.conf exists. If not, copy the default configuration to this location so that you can customize it for the deployment.
    sudo cp /usr/share/containers/containers.conf /etc/containers/
  2. Edit /etc/containers/containers.conf and find the network_backend entry in the [network] section of the configuration file. Remove the entry's comment character if it exists. Change the value to match the network backend that you would prefer to use. For example, to use the CNI backend, change the entry to match: 
    network_backend = "cni"
  3. Reinitialize the Podman configuration to its pristine state:
    sudo podman system reset

    This command displays a warning and prompts you for confirmation.

    WARNING! This will remove:
        - all containers
        - all pods
        - all images
        - all networks
        - all build cache
        - all machines
Are you sure you want to continue? [y/N] y

    Note:

    If you have non-root podman instances, these also need to be reset individually if the network stack is changed.

  4. Reboot the system to ensure that the networking is running correctly for Podman to function.

Creating and Removing Networks

Use the podman network create command to generate a new network configuration: 

sudo podman network create network_name

Podman automatically defines network settings based on the default network and any other existing networks. However, options are available to set the network range, subnet size, and to enable IPv6. Use the podman help network create command to obtain more information about these options.

To remove a network that you have created, run:
sudo podman network rm network_name

Note:

To remove a network, you must first remove any container that's connected to the network. You can use the -f option to force the removal of any containers that are using the network.

You can remove all networks that are unused on the system by typing:

sudo podman network prune

Listing Networks

List all the Podman networks you have created: 

sudo podman network ls
NETWORK ID    NAME        DRIVER
2f259bab93aa  podman      bridge
47d141b0df17  podman1     bridge,portmap,firewall,tuning

Connecting and Disconnecting Container Networks

When you create containers, the network is automatically started and containers are assigned IP addresses within the range that's defined for a network. Likewise, when you delete a container, the network is also automatically stopped.

If you have created a new network, you can add any container to the network by running:

sudo podman network connect network_name container_id

You can disconnect a container from a network by running:

sudo podman network disconnect network_name container_id

Inspecting Container Networking

You can inspect the networking information for any container that you have created to obtain important information such as IP addressing, networks, or port mappings. Note that where a container is running under the root account, prefix the following commands with sudo, as appropriate.

To view IP addresses for a container, run: 

podman inspect --format='{{.NetworkSettings.IPAddress}}' container_id

To view networks that are attached to a container, run: 

podman inspect --format='{{.NetworkSettings.Networks}}' container_id

To view port mappings for a container, run: 

podman inspect --format='{{.NetworkSettings.Ports}}' container_id