[PATCH iproute2 1/2] man: add ip-netns(8) as generation target

[PATCH iproute2 1/2] man: add ip-netns(8) as generation target

[Brian Norris]

Prepare for adding new variable substitutions. Unify the sed rules while
we're at it, since there's no need to write this out 4 times.

Signed-off-by: Brian Norris <briannorris@chromium.org>
---
 man/man8/.gitignore                    |  1 +
 man/man8/Makefile                      | 10 ++--------
 man/man8/{ip-netns.8 => ip-netns.8.in} |  0
 3 files changed, 3 insertions(+), 8 deletions(-)
 rename man/man8/{ip-netns.8 => ip-netns.8.in} (100%)

diff --git a/man/man8/.gitignore b/man/man8/.gitignore
index 0c3d15047fde..7b08e9114455 100644
--- a/man/man8/.gitignore
+++ b/man/man8/.gitignore
@@ -1,4 +1,5 @@
 # these pages are built
 ip-address.8
 ip-link.8
+ip-netns.8
 ip-route.8
diff --git a/man/man8/Makefile b/man/man8/Makefile
index 0269e17406b7..9c62312396a2 100644
--- a/man/man8/Makefile
+++ b/man/man8/Makefile
@@ -1,17 +1,11 @@
 # SPDX-License-Identifier: GPL-2.0
-TARGETS = ip-address.8 ip-link.8 ip-route.8
+TARGETS = ip-address.8 ip-link.8 ip-netns.8 ip-route.8
 
 MAN8PAGES = $(TARGETS) $(filter-out $(TARGETS),$(wildcard *.8))
 
 all: $(TARGETS)
 
-ip-address.8: ip-address.8.in
-	sed "s|@SYSCONFDIR@|$(CONFDIR)|g" $< > $@
-
-ip-link.8: ip-link.8.in
-	sed "s|@SYSCONFDIR@|$(CONFDIR)|g" $< > $@
-
-ip-route.8: ip-route.8.in
+%: %.in
 	sed "s|@SYSCONFDIR@|$(CONFDIR)|g" $< > $@
 
 distclean: clean
diff --git a/man/man8/ip-netns.8 b/man/man8/ip-netns.8.in
similarity index 100%
rename from man/man8/ip-netns.8
rename to man/man8/ip-netns.8.in
-- 
2.26.0.292.g33ef6b2f38-goog

[PATCH iproute2 2/2] man: replace $(NETNS_ETC_DIR) and $(NETNS_RUN_DIR) in ip-netns(8)

[Brian Norris]

These can be configured to different paths. Reflect that in the
generated documentation.

Signed-off-by: Brian Norris <briannorris@chromium.org>
---
 man/man8/Makefile      |  6 +++++-
 man/man8/ip-netns.8.in | 20 ++++++++++----------
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/man/man8/Makefile b/man/man8/Makefile
index 9c62312396a2..b1fd87bdeff0 100644
--- a/man/man8/Makefile
+++ b/man/man8/Makefile
@@ -6,7 +6,11 @@ MAN8PAGES = $(TARGETS) $(filter-out $(TARGETS),$(wildcard *.8))
 all: $(TARGETS)
 
 %: %.in
-	sed "s|@SYSCONFDIR@|$(CONFDIR)|g" $< > $@
+	sed \
+		-e "s|@NETNS_ETC_DIR@|$(NETNS_ETC_DIR)|g" \
+		-e "s|@NETNS_RUN_DIR@|$(NETNS_RUN_DIR)|g" \
+		-e "s|@SYSCONFDIR@|$(CONFDIR)|g" \
+		$< > $@
 
 distclean: clean
 
diff --git a/man/man8/ip-netns.8.in b/man/man8/ip-netns.8.in
index c75917dac8b1..2911bdd36575 100644
--- a/man/man8/ip-netns.8.in
+++ b/man/man8/ip-netns.8.in
@@ -61,9 +61,9 @@ By default a process inherits its network namespace from its parent. Initially a
 the processes share the same default network namespace from the init process.
 
 By convention a named network namespace is an object at
-.BR "/var/run/netns/" NAME
+.BR "@NETNS_RUN_DIR@/" NAME
 that can be opened. The file descriptor resulting from opening
-.BR "/var/run/netns/" NAME
+.BR "@NETNS_RUN_DIR@/" NAME
 refers to the specified network namespace. Holding that file
 descriptor open keeps the network namespace alive. The file
 descriptor can be used with the
@@ -72,13 +72,13 @@ system call to change the network namespace associated with a task.
 
 For applications that are aware of network namespaces, the convention
 is to look for global network configuration files first in
-.BR "/etc/netns/" NAME "/"
+.BR "@NETNS_ETC_DIR@/" NAME "/"
 then in
 .BR "/etc/".
 For example, if you want a different version of
 .BR /etc/resolv.conf
 for a network namespace used to isolate your vpn you would name it
-.BR /etc/netns/myvpn/resolv.conf.
+.BR @NETNS_ETC_DIR@/myvpn/resolv.conf.
 
 .B ip netns exec
 automates handling of this configuration, file convention for network
@@ -89,24 +89,24 @@ their traditional location in /etc.
 .TP
 .B ip netns list - show all of the named network namespaces
 .sp
-This command displays all of the network namespaces in /var/run/netns
+This command displays all of the network namespaces in @NETNS_RUN_DIR@
 
 .TP
 .B ip netns add NAME - create a new named network namespace
 .sp
-If NAME is available in /var/run/netns/ this command creates a new
+If NAME is available in @NETNS_RUN_DIR@ this command creates a new
 network namespace and assigns NAME.
 
 .TP
 .B ip netns attach NAME PID - create a new named network namespace
 .sp
-If NAME is available in /var/run/netns/ this command attaches the network
+If NAME is available in @NETNS_RUN_DIR@ this command attaches the network
 namespace of the process PID to NAME as if it were created with ip netns.
 
 .TP
 .B ip [-all] netns delete [ NAME ] - delete the name of a network namespace(s)
 .sp
-If NAME is present in /var/run/netns it is umounted and the mount
+If NAME is present in @NETNS_RUN_DIR@ it is umounted and the mount
 point is removed. If this is the last user of the network namespace the
 network namespace will be freed and all physical devices will be moved to the
 default one, otherwise the network namespace persists until it has no more
@@ -160,7 +160,7 @@ Once it is assigned, it's not possible to change it.
 .TP
 .B ip netns identify [PID] - Report network namespaces names for process
 .sp
-This command walks through /var/run/netns and finds all the network
+This command walks through @NETNS_RUN_DIR@ and finds all the network
 namespace names for network namespace of the specified process, if PID is
 not specified then the current process will be used.
 
@@ -201,7 +201,7 @@ and prints a line for each event it sees.
 .sp
 Network namespace ids are used to identify a peer network namespace. This
 command displays nsids of the current network namespace and provides the
-corresponding iproute2 netns name (from /var/run/netns) if any.
+corresponding iproute2 netns name (from @NETNS_RUN_DIR@) if any.
 
 The
 .B target-nsid
-- 
2.26.0.292.g33ef6b2f38-goog

Re: [PATCH iproute2 1/2] man: add ip-netns(8) as generation target

[Stephen Hemminger]

On Tue,  7 Apr 2020 10:43:05 -0700
Brian Norris <briannorris@chromium.org> wrote:

> Prepare for adding new variable substitutions. Unify the sed rules while
> we're at it, since there's no need to write this out 4 times.
> 
> Signed-off-by: Brian Norris <briannorris@chromium.org>

Why is this needed?

Re: [PATCH iproute2 1/2] man: add ip-netns(8) as generation target

[Brian Norris]

On Tue, Apr 7, 2020 at 11:24 AM Stephen Hemminger
<stephen@networkplumber.org> wrote:
>
> On Tue,  7 Apr 2020 10:43:05 -0700
> Brian Norris <briannorris@chromium.org> wrote:
>
> > Prepare for adding new variable substitutions. Unify the sed rules while
> > we're at it, since there's no need to write this out 4 times.
> >
> > Signed-off-by: Brian Norris <briannorris@chromium.org>
>
> Why is this needed?

For patch 1: it's only for the sake of patch 2.
If you're implying that patch 2 doesn't describe the "why?" well
enough: I'll try again:

> man: replace $(NETNS_ETC_DIR) and $(NETNS_RUN_DIR) in ip-netns(8)
>
> These can be configured to different paths. Reflect that in the
> generated documentation.

This is needed because Chrom{ium,e} OS patches iproute2 to use /run
directly instead of /var/run [1]. We also build the man pages, so we'd
like the man-pages to match.

Incidentally, we were already manually patching this out (in both
source and man-page) before this upstream patch existed:
e2f5ceccdab5 Allow to configure /var/run/netns directory
It would be nice if we could just use the Makefile variable instead.

I can resubmit if you'd like a more verbose description in the patch
submission itself.

Brian

[1] Longer answer: because the latter traverses a symlink on a
read/write partition, whereas the former is a direct-mounted tmpfs. We
can provide better guarantees for programs that avoid symlinks like
this.

Re: [PATCH iproute2 1/2] man: add ip-netns(8) as generation target

[Stephen Hemminger]

On Tue,  7 Apr 2020 10:43:05 -0700
Brian Norris <briannorris@chromium.org> wrote:

> Prepare for adding new variable substitutions. Unify the sed rules while
> we're at it, since there's no need to write this out 4 times.
> 
> Signed-off-by: Brian Norris <briannorris@chromium.org>
> ---
>  man/man8/.gitignore                    |  1 +
>  man/man8/Makefile                      | 10 ++--------
>  man/man8/{ip-netns.8 => ip-netns.8.in} |  0
>  3 files changed, 3 insertions(+), 8 deletions(-)
>  rename man/man8/{ip-netns.8 => ip-netns.8.in} (100%)

Sure, applied both patches