Set up Podman discovery
How Scanopy discovers Podman containers and pods through the local socket with a Podman Socket credential, or through a remote Podman API proxy.
Scanopy daemons discover Podman containers by connecting to the Podman API. On the daemon's own host, a Podman Socket credential connects it to the local socket. Reaching a restricted API, or one on another machine, needs a Podman Proxy credential.
Before you start
Podman credentials are created under Assets > Credentials and can be pointed at Daemon hostRemote hosts.
Creating a credential, assigning it, and overriding it on an individual host work the same way for every integration — see Creating a credential, Where a credential applies, and Auto-assignment. This guide covers only what is specific to Podman.
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 on macvlan or ipvlan networks, each as its own host
- The container serving the Podman API on a proxy credential's port, as a Podman API Proxy service under Podman
Bridge-networked containers appear as Podman Container services on their host. A container on a macvlan or ipvlan network has its own address on the LAN, so it becomes its own host, tagged macvlan or ipvlan and linked to the Podman service on the Podman 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.
With a proxy credential, the container that publishes the credential's port is the proxy in front of Podman. It is recorded as a Podman API Proxy service under the Podman service and holds that port, whatever port you set. A proxy running with host networking is identified only when its image declares the port as exposed.
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 -
On Windows, the Podman machine running (
podman machine start), which serves the\\.\pipe\podman-machine-defaultnamed pipe -
For proxied access, a TCP endpoint in front of that socket, reachable from the daemon
Rootless vs rootful. A rootless socket only sees that user's containers, and rootless networking may not expose a bridge subnet. Run the daemon (or the proxy) as the same user that owns the containers you want to discover, or use the rootful socket for host-wide visibility.
Choosing a credential type
| Credential type | How it connects | Can be targeted at | Requires daemon |
|---|---|---|---|
| Podman Proxy | Connects over TCP, optionally with TLS. | Daemon hostRemote hosts | Newer than 0.17.1 |
| Podman Socket | Connects via the daemon's local socket. | Daemon host | Newer than 0.17.1 |
| Situation | Use |
|---|---|
| Daemon runs on the Podman host and the socket is in a standard location | Podman Socket, with Socket Path left blank |
| Daemon runs on the Podman host, but the socket is elsewhere | Podman Socket, with that path in Socket Path |
| You want to restrict which API operations the daemon can call | Podman Proxy, with the proxy on the same host |
| Podman runs on a machine with no daemon | Podman Proxy, with the proxy on that machine |
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.
| Field | Required | Default | Description |
|---|---|---|---|
| Connection | |||
| Podman API Port | Optional | 2375 | Podman API port. Point at a TCP-exposed Podman service (e.g. `podman system service tcp:`) directly or behind a TLS proxy. |
| URL Path Prefix | Optional | None | Optional URL path prefix appended after the port |
| TLS | |||
| SSL Certificate | Optional | None | PEM-encoded client certificate. All three TLS fields (cert, key, CA chain) must be provided together. |
| SSL Private KeySecret | Optional | None | PEM private key. All three TLS fields must be provided together. |
| SSL CA Chain | Optional | None | PEM-encoded CA certificate chain. All three TLS fields must be provided together. |
The TLS fields apply to HTTPS endpoints only. Each takes the PEM text with Enter value, or a path with File on daemon host. A path must be absolute for the credential's Daemon OS, and ~ is not expanded.
Required API operations
Podman exposes a Docker-compatible API, and Scanopy uses that compatibility layer. Restrict the proxy to these endpoints:
| Endpoint | Method | Purpose |
|---|---|---|
/containers/json | GET | List running containers |
/containers/{id}/json | GET | Get container details (ports, networks, config) |
/networks | GET | List networks for subnet discovery |
/exec/{id}/json | GET | Check exec instance status |
/containers/{id}/exec | POST | Create exec instance for endpoint probing |
/exec/{id}/start | POST | Start exec to probe HTTP endpoints inside containers |
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
A Podman Socket credential connects the daemon directly to the Podman socket on its own host. The default Podman Socket credential is added on the Integration Setup step when you create a daemon; remove it there to skip the local socket. You can also add it to a scan in the Discovery modal. The daemon doesn't read the local socket without one.
With Socket Path left blank, the daemon uses the first of these that exists:
- The socket or pipe the
CONTAINER_HOSTenvironment variable names withunix://ornpipe:// - On Linux, macOS and BSD, the rootful socket
/run/podman/podman.sock, then the rootless socket$XDG_RUNTIME_DIR/podman/podman.sock - On Windows, the Podman machine's named pipe
\\.\pipe\podman-machine-default
On Windows the daemon does not try \\.\pipe\docker_engine for Podman. If your Podman machine serves that pipe, enter it in Socket Path.
Enter a Socket Path only when your socket or pipe is somewhere else. It replaces the detection above.
| Field | Required | Default | Description |
|---|---|---|---|
| Socket Path | Optional | None | The Podman socket on Unix, or Podman machine's named pipe on Windows. Leave blank to auto-detect (CONTAINER_HOST, then the rootful and rootless sockets on Unix or the podman-machine-default pipe on Windows). |
Socket Path takes the form the credential's Daemon OS uses. The form shows Daemon OS once Socket Path is set, and a daemon on another OS skips the credential.
| Daemon OS | Socket Path |
|---|---|
| Linux, macOS, BSD | An absolute socket path, such as /run/podman/podman.sock, with or without unix:// |
| Windows | A named pipe, such as \\.\pipe\podman-machine-default, or the same pipe as npipe:////./pipe/podman-machine-default |
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
- Go to Discover > Scans and run a discovery, or wait for the next scheduled run
- Open the host running Podman and go to its Services tab
- Look for Podman Container services, each with its published ports
- Open the Workloads perspective and confirm the containers appear nested under their host
Troubleshooting
No containers discovered
- Confirm the API socket is running:
systemctl --user status podman.socket(rootless) orsudo systemctl status podman.socket(rootful) - Confirm the daemon can see the socket path — check
CONTAINER_HOST,/run/podman/podman.sock, and$XDG_RUNTIME_DIR/podman/podman.sock - 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
- On Windows, confirm
podman machine listshows the machine running
"Connection refused" to a proxy
- Verify the proxy is running and listening on the expected port
- Ensure the daemon can reach it — same network, or an exposed port
- Check the proxy forwards to a valid Podman socket path
SSL certificate errors
- Verify certificate paths are correct and mounted
- Check the certificate is valid:
openssl x509 -in /certs/client-cert.pem -text -noout - Include the CA chain if using self-signed certs
- 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.
Product names and logos are trademarks of their respective owners. See credits.
Set up Instant On discovery
Connect an HPE Networking Instant On site so Scanopy can discover the switches and access points it manages, along with their ports and the links between them.
Set up Proxmox VE discovery
Connect a Proxmox VE cluster so Scanopy discovers its nodes and the VMs and LXC containers on each, with their addresses and the node they run on.