[Docs] Clarification needed and/or Update Required to Network= documentation for Containers under Systemd

[armouredking]

Issue Description

Per current version documentation (emphasis mine):

---

Network=

Specify a custom network for the container. This has the same format as the --network option to podman run. For example, use host to use the host network in the container, or none to not set up networking in the container.

As a special case, if the name of the network ends with .network, a Podman network called systemd-$name is used, and the generated systemd service contains a dependency on the $name-network.service. Such a network can be automatically created by using a $name.network Quadlet file.

Another special case is that if the name ends with .container, the container will reuse the network stack of another container created by $name.container. The generated systemd service contains a dependency on $name.service.

This key can be listed multiple times.

---

The way I read this, is that in my $name.container file, for the Network= entry, if I want to use $vpn.container's stack for $othercontainer.container, I should write Network=$vpn.container in $othercontainer.container (where $vpn.container is the filename of the generation in /etc/containers/systemd).

So if one uses

Network=vpn.container

In $othercontainer.container, after doing a systemctl daemon-reload and systemctl start $othercontainer.service, you will receive

Error: unable to find network with name or ID vpn.container: network not found

Just for complete-ness sake, I've tested using Network=vpn, Network=systemd-vpn, Network=vpn.container, Network=vpn.service, all resulting in the same break point. And yes, I did daemon-reload every time.

So, per manual since this entry "Network=" is supposed to be like using the command line podman run --network and I know that works, I tried configuring it like that instead.

Network=container:vpn

No dice. Then again, since I didn't name $vpn.container, it runs with the default systemd-$name instead, so:

Network=container:systemd-vpn

Success! $othercontainer.container will start with this configuration, and I can curl against $vpn.container's address with $othercontainer.container's port number and get $othercontainer.container expected response just as if I had done this with Docker Compose or Podman cmd line.

Okay, so something isn't right somewhere. I suspect the documentation is wrong and requires an update; that or the intent was what the documentation said to do (use Network=$vpn.container) and that functionality is broken. That, or the documentation seems like it covers this use case and doesn't and if so I'd maybe still ask for it to be updated to be clearer about how $name.container is supposed to be used.

Steps to reproduce the issue

Steps to reproduce the issue

1. RTFM
2. Attempt to do what manual states
3. Error

Describe the results you received

Describe the results you received
See Above

Describe the results you expected

Describe the results you expected
Manual instructions are correct and functionality is similar to other things (ie. using Network=$name.network works exactly like the manual claims)

podman info output

No issues with podman.

Podman in a container

No

Privileged Or Rootless

Privileged

Upstream Latest Release

No

Additional environment details

Rocky Linux 9.5 w/ Mainline Kernel (to better support Intel Discrete Graphics)

Additional information

Additional information like issue happens only occasionally or issue happens with a particular architecture or on a particular setting
Not sure if I should pick priv/rootless for that option; I am using rootful containers with uid/gid mapping ala:

UIDMap=0:$specific user to container:1
UIDMap=1:$specific user to container's /etc/subuid starting:65536
GIDMap=0:$specific user to container:1
GIDMap=1:$specific user to container's /etc/subuid starting:65536

Where every container gets its own user (so $vpn.container and $othercontainer.container do not have the same namespace) so maybe that is part of this? Still, $name.network works regardless, it's just $name.container that's failing for me.

[Luap99]

Please file out the template, i.e. podman info. You did not state the podman version you are using.

The docs are for the latest version if you are on Rocky you most likely do not use the latest version and thus the docs do not apply to your version. The feature was added in podman 5.3 #23814

[armouredking]

I noted in the comment that I was looking at the "stable" docs, but now that I'm reviewing things I don't see a difference between :stable and :latest in the docs. Is stable to be taken as the most recent release version (ie 5.3.1) and latest then something more like _nightly or _master? Github shows 5.3.1 as latest, hence my confusion.

[Luap99]

latest is the main branch yes, stable is the newest tagged release.