even better documentation

[newns] / newns

diff --git a/newns b/newns
index d60c0bcec3c43cccab802fcf2c5faca3492ffed6..d6a1b08eb6bc7805cb5d3fadcc7f50b591b29ef2 100755 (executable)
--- a/newns
+++ b/newns
@@ -37,41 +37,52 @@ fi
 
 usage() {
     cat <<EOF
-usage: ${0##*/} [OPTS] start|stop NETNS_NAME
+usage: ${0##*/} [OPTS] start|stop NS_NAME
+Setup new or systemd created network namespace with nat and mount namespace
 
 -c, --create    Create network namespace. For running outside systemd private net.
 -h, --help      Show this help and exit.
 
-From within systemd network namespace, nat it to the outside.  If given
+From within systemd network namespace, nat it to the outside. If given
 -c, or if in the default network namespace, create a named network
 namepace natted to the current netns.
 
+Uses /24 network, finding the first locally unused one starting at
+10.173.0.
+
 Also create a named mount namespace under /root/mount_namespaces, so we
 can alter some system config for this namespace. Subsequent systemd
 command lines would be prefixed with:
 
-/usr/bin/nsenter --mount=/root/mount_namespaces/NETNS_NAME
-
-
-"ip netns new ..." also does a mount namespace, then bind mounts each
-thing in /etc/netns/NETNS_NAME to /etc/NETNS_NAME. Note, for openvpn having it's own
-resolv.conf, this doesn't help much. What we actually want to do is copy
-/run/resolvconf somehwere, then bind mount it on top of /run/resolvconf.
+/usr/bin/nsenter --mount=/root/mount_namespaces/NS_NAME
 
-Once systemd 233 comes out, it will have a bind mount option from within
-unit files, so the mount namespace won't be needed for this use case.
+Note, this means that they can't run as unpriveledged users, but once
+systemd 233 comes out, it will have a bind mount option from within unit
+files, so the mount namespace won't be needed for most use cases, and I
+will update the script to that the mount namespace not created unless a
+flag is passed in. Patch welcome to add that flag before then.
 
-Recommmended dependency of errhandle to print stack trace on error:
+A recommmended dependency of this script is my other repo named "errhandle",
+which prints stack trace on error, and calls a cleanup function:
 https://iankelling.org/git/?p=errhandle, set ERRHANDLE_PATH, or put it
 in a directory adjacent to the absolute, resolved directory this file is
 in.
 
+Background: "ip netns new ..." also does a mount namespace, then bind
+mounts each file/dir in /etc/netns/NS_NAME to /etc/NS_NAME. Note,
+for openvpn having it's own resolv.conf by using it's user script which
+calls resolvconf, this doesn't help much. What we actually want to do is
+copy /run/resolvconf somehwere then bind mount it on top of
+/run/resolvconf.
+
+Please email me if you have a patches, bugs, feedback, or republish this
+somewhere else: Ian Kelling <ian@iankelling.org>.
 EOF
     exit ${1:-0}
 }
 
 
-## begin arg parsing ##
+#### begin arg parsing ####
 create=false
 temp=$(getopt -l help,create hc "$@") || usage 1
 eval set -- "$temp"
@@ -88,11 +99,10 @@ if (( $# != 2 )); then
 fi
 
 action=$1
-nn=$2 # network namespace / namespace name
-## end arg parsing ##
-
-## begin sanity checking ##
+nn=$2 # namespace name
+#### end arg parsing ####
 
+#### begin sanity checking ####
 install_error=false
 if ! type -p ip &>/dev/null; then
     echo "please install the iproute2 package"
@@ -105,8 +115,7 @@ fi
 if $install_error; then
     exit 1
 fi
-
-##   end sanity checking ##
+####   end sanity checking ####
 
 
 v0=veth0-$nn
@@ -117,10 +126,10 @@ if ! $create && [[ $(readlink /proc/self/ns/net) == "$(readlink /proc/1/ns/net)"
     create=true
 fi
 
+# make the default network namespace be named
 target=/run/netns/default
 if [[ ! -e $target && ! -L $target ]]; then
     mkdir -p /run/netns
-    # make the default network namespace be named
     ln -s /proc/1/ns/net $target
 fi
 
@@ -135,7 +144,7 @@ fi
 dexec() { ip netns exec default "$@"; }
 
 
-# head -n1 is defensive. Not sure if there is some weird feature
+# background: head -n1 is defensive. Not sure if there is some weird feature
 # for 2 routes to be 0/0.
 gateway_if=$(ipd route list exact 0/0 | head -n1| sed -r 's/.*\s(\S+)\s*$/\1/')
 nat() { dexec iptables -t nat $1 POSTROUTING -o $gateway_if -j MASQUERADE \
@@ -157,13 +166,13 @@ find_network() {
 }
 
 start() {
-
     find_network
     if ! $found; then
         echo "$0: error: no open network found"
         exit 1
     fi
 
+    #### begin mount namespace setup ####
     mkdir -p /root/mount_namespaces
     if ! mountpoint /root/mount_namespaces >/dev/null; then
         mount --bind /root/mount_namespaces /root/mount_namespaces
@@ -175,6 +184,7 @@ start() {
     if ! mountpoint /root/mount_namespaces/$nn >/dev/null; then
         unshare --mount=/root/mount_namespaces/$nn
     fi
+    ####   end mount namespace setup ####
 
 
     if $create; then
@@ -182,8 +192,6 @@ start() {
         ip -n $nn link set dev lo up
     fi
 
-
-
     echo 1 | dexec dd of=/proc/sys/net/ipv4/ip_forward 2>/dev/null
 
     _errcatch_cleanup=stop
@@ -210,6 +218,9 @@ stop() {
     if $create; then
         ip netns del $nn
     fi
+    if mountpoint /root/mount_namespaces/$nn >/dev/null; then
+        umount /root/mount_namespaces/$nn
+    fi
 }
 
 case $action in