Set up Podman discovery

Scanopy daemons discover Podman containers by connecting to the Podman API. On the daemon's own host that happens automatically; reaching a restricted API, or one on another machine, needs a proxy.

What gets discovered

• Running containers, with their names and metadata
• Container networks and published port bindings, including automatically created bridge subnets
• Containerized services, identified from the API rather than from a port scan — so containers that publish nothing to the host are still detected

Containers appear as Podman Container services on their host. Pods are modeled as generic containers with each container in the pod attributed individually. The container-to-host relationship shows up in the Workloads perspective.

Discovery is local to one host: the daemon sees the containers on its own machine, or on the single host a proxy credential points at.

Prerequisites

• Podman running on the host whose containers you want to discover

• The API socket enabled — it isn't always running by default:

  # Rootless (per-user socket at $XDG_RUNTIME_DIR/podman/podman.sock)
  systemctl --user start podman.socket
  
  # Rootful (system socket at /run/podman/podman.sock)
  sudo systemctl start podman.socket

• For proxied access, a TCP endpoint in front of that socket, reachable from the daemon

Choosing a credential type

Podman Proxy

A proxy in front of the socket lets you restrict which API operations are allowed, and lets a daemon reach Podman on a machine it isn't running on.

Any reverse proxy that forwards to the socket works — for example an nginx proxy mapping a TCP port onto /run/podman/podman.sock, optionally terminating TLS. To discover containers on a machine that runs no daemon: expose the endpoint there, create a Podman Proxy credential with its port, and assign it to the remote host. Containers are then reported as services on the remote host rather than on the daemon's host.

The TLS fields apply to HTTPS endpoints only. Each can be entered inline or as a file path readable by the daemon.

Required API operations

Podman exposes a Docker-compatible API, and Scanopy uses that compatibility layer. Restrict the proxy to these endpoints:

Why exec? Scanopy uses exec to probe HTTP endpoints from inside containers that don't publish ports to the host. Without exec access, containers are still discovered but service detection is less accurate.

Podman Socket

The daemon connects directly to the Podman socket on its own host, automatically, whenever it's accessible. It looks in this order:

1. The CONTAINER_HOST environment variable, when it points at a unix:// socket path
2. The rootful socket: /run/podman/podman.sock
3. The rootless socket: $XDG_RUNTIME_DIR/podman/podman.sock

Create a Podman Socket credential only when your socket is somewhere else — its path overrides the auto-detection above.

Because the socket is reachable only over the daemon's own loopback, this credential type can be assigned to a daemon host and nowhere else.

Verifying it works

1. Go to Discover > Scan > Scheduled and run a discovery, or wait for the next scheduled run
2. Open the host running Podman and go to its Services tab
3. Look for Podman Container services, each with its published ports
4. Open the Workloads perspective and confirm the containers appear nested under their host

Troubleshooting

No containers discovered

1. Confirm the API socket is running: systemctl --user status podman.socket (rootless) or sudo systemctl status podman.socket (rootful)
2. Confirm the daemon can see the socket path — check CONTAINER_HOST, /run/podman/podman.sock, and $XDG_RUNTIME_DIR/podman/podman.sock
3. If the daemon and the containers run under different users, the rootless socket won't expose them — run both as the same user, or use the rootful socket

"Connection refused" to a proxy

1. Verify the proxy is running and listening on the expected port
2. Ensure the daemon can reach it — same network, or an exposed port
3. Check the proxy forwards to a valid Podman socket path

SSL certificate errors

1. Verify certificate paths are correct and mounted
2. Check the certificate is valid: openssl x509 -in /certs/client-cert.pem -text -noout
3. Include the CA chain if using self-signed certs
4. Check that the cert and key aren't swapped

For diagnosing credential loading and file read or PEM errors from daemon logs, see Credential troubleshooting.