Skip to content

Be more explicit about the port part of a certificate directory #369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Be more explicit about the port part of a certificate directory #369

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions image/docs/containers-certs.d.5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,12 @@ containers-certs.d - Directory for storing custom container-registry TLS configu

# DESCRIPTION
A custom TLS configuration for a container registry can be configured by creating a directory under `$HOME/.config/containers/certs.d` or `/etc/containers/certs.d`.
The name of the directory must correspond to the `host:port` of the registry (e.g., `my-registry.com:5000`).
The name of the directory must correspond to the `host`[`:port`] of the registry (e.g., `my-registry.com:5000`).
Copy link

@3nprob 3nprob Oct 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The name of the directory must correspond to the `host`[`:port`] of the registry (e.g., `my-registry.com:5000`).
The name of the directory must correspond to the `host`[`:port`] of the registry, where `:port` must be omitted in case of port `443` but is otherwise required (e.g., `my-registry.com:5000` or `registry.example.com`).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That’s not actually correct - if users pull registry.example.com:443/…, the directory must be named registry.example.com:443. 443/80 are not special for this purpose.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, right. I still find the proposal can cause confusion (one interpretation being that the :port is optional.

How about using "prefix", "registry" or "location" instead of "host[:port]" - which would reuse notation from containers-registries.conf docs and indicating that the following explanation is required reading?

(Aside: Elsewhere it seems that hostname:port is used more than host:port)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We typically use “prefix” to include registry.example/namespace1/namespace2. registry is not specific about having a port port. location is too vague (and used in registries.conf as a physical counterpart to prefix).

Either way, users ~need to read the second sentence. (And as a general rule, I don’t think it makes sense to try to structure reference documentation for users who might stop reading at any end of a sentence. Sure, tutorials or blog posts can be more concise, or laser-focused on a single use case. This is not a tutorial.)


The port part presence / absence must precisely match the port usage in image references,
e.g. to affect `podman pull registry.example/foo`,
use a directory named `registry.example`, not `registry.example:443`.
`registry.example:443` would affect `podman pull registry.example:443/foo`.

## Directory Structure
A certs directory can contain one or more files with the following extensions:
Expand All @@ -18,7 +23,7 @@ Note that the client certificate-key pair will be selected by the file name (e.g
An exemplary setup for a registry running at `my-registry.com:5000` may look as follows:
```
/etc/containers/certs.d/ <- Certificate directory
└── my-registry.com:5000 <- Hostname:port
└── my-registry.com:5000 <- Hostname[:port]
├── client.cert <- Client certificate
├── client.key <- Client key
└── ca.crt <- Certificate authority that signed the registry certificate
Expand Down