networking: document --netns-path

Add documentation for --netns-path network namespace joins.

While we are here, start a fresh new in 4.2 page.

Fixes #246

Author: dtrudg

index.rst

@@ -19,7 +19,7 @@ Getting Started & Background Information
 .. toctree::
    :maxdepth: 2
 
-   What's New in {Singularity} 4.1 <new>
+   What's New in {Singularity} 4.2 <new>
 
    Introduction to {Singularity} <introduction>
    Quick Start <quick_start>

networking.rst

@@ -6,19 +6,19 @@ Network virtualization
 
 .. _sec:networking:
 
-{Singularity} provides full integration with `cni
-<https://github.com/containernetworking/cni>`_ , to make network
-virtualization easy. The following options can be used with the the
-action commands (``exec``, ``run``, and ``shell``) to create and
-configure a virtualized network for a container.
+{Singularity}'s native mode provides full integration with `CNI
+<https://github.com/containernetworking/cni>`_ , and the ability to join an
+existing network namespace, to make network virtualization easy. The following
+options can be used with the the action commands (``exec``, ``run``, and
+``shell``) to create and configure a virtualized network for a container.
 
 .. note::
 
    Many of these options are available only to the ``root`` user by
    default. Unrestricted ability to configure networking for containers
    would allow users to affect networking on the host, or in a cluster.
 
-   {Singularity} 3.8 allows the administrator to permit a list of
+   {Singularity} allows the administrator to permit a list of
    unprivileged users and/or groups to use specified network
    configurations. This is accomplished through settings in
    ``singularity.conf``. See the administrator guide for details.
@@ -56,6 +56,52 @@ hostname within the container.
    $ sudo singularity exec --hostname hal-9000 my_container.sif hostname
    hal-9000
 
+.. _sec:netns-path:
+
+****************
+``--netns-path``
+****************
+
+*New in {Singularity} 4.2*
+
+Passing the ``--netns-path`` flag with a path to an existing network namespace
+will cause the container to join that namespace.
+
+For example, a network namespace can be created with the ``ip`` command on the
+host, and then a container started that will run within this namespace:
+
+.. example::
+
+   # Create an example named network namespace
+   $ sudo ip netns add my-net
+
+   # Add a dummy network interface to the network namespace
+   $ sudo ip netns exec my-net ip link add dummy0 type dummy
+
+   # Run a container in the network namespace
+   $ sudo singularity run --netns-path /run/netns/my-net library://alpine
+   INFO:    Using cached image
+   Singularity> ip a
+   1: lo: <LOOPBACK> mtu 65536 qdisc noop state DOWN qlen 1000
+      link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+   2: dummy0: <BROADCAST,NOARP> mtu 1500 qdisc noop state DOWN qlen 1000
+      link/ether 92:5c:ab:ab:d3:d0 brd ff:ff:ff:ff:ff:ff
+   Singularity>
+
+Note that the ``ip a`` command run inside the container shows the ``dummy0``
+interface we added to the ``my-net`` network namespace.
+
+The root user can join any network namespace with ``--netns-path``.
+
+A non-root user can only join a network namespace if the following are true:
+
+* The path of the network namespace is listed in the ``allow netns paths``
+  directive in ``singularity.conf``, which is typically managed by the system
+  administrator.
+* The user is listed in the ``allow net users`` directive in ``singularity.conf``,
+  or the user is a member of a group listed in the ``allow net groups`` directive
+  in ``singularity.conf``.
+
 *********
 ``--net``
 *********

new.rst

@@ -1,74 +1,24 @@
 .. _whats_new:
 
 ###############################
-What's New in {Singularity} 4.1
+What's New in {Singularity} 4.2
 ###############################
 
-This section highlights important changes and new features in {Singularity} 4.1
+This section highlights important changes and new features in {Singularity} 4.2
 that are of note to users. See also the "What's New" section in the Admin Guide
 for administrator-facing changes.
 
 If you are upgrading from a 3.x version of {Singularity} we recommend also
 reviewing the `"What's New" section for 4.0
 <https://docs.sylabs.io/guides/4.0/user-guide/new.html>`__.
 
-********
-OCI-mode
-********
+*******
+Runtime
+*******
 
-- Singularity will now :ref:`build OCI-SIF images from Dockerfiles
-  <dockerfile>`, if the ``--oci`` flag is used with the ``build`` command.
-  Provide a Dockerfile as the final argument to ``build``, instead of a
-  Singularity definition (.def) file. Supports ``--build-arg`` /
-  ``--build-arg-file`` options, ``--arch`` for cross-architecture builds,
-  `--authfile` and other authentication options, and more. Dockerfile builds are
-  not available on EL7 / SLES12 distributions.
-- `Docker-style SCIF containers <https://sci-f.github.io/tutorial-preview-install>`__
-  are now supported. If the entrypoint of an OCI container is the ``scif``
-  executable, then the ``run`` / ``exec`` / ``shell`` commands in ``--oci`` mode
-  can be given the ``--app <appname>`` flag, and will automatically invoke the
-  relevant SCIF command.
-- `Multi layer OCI-SIF images <sec:multi_layer_oci_sif>` can now be created
-  using a new ``--keep-layers`` flag, for the ``pull`` and ``run/shell/exec``
-  commands. This allows individual layers to be preserved when an OCI-SIF image
-  is created from an OCI source. Multi layer OCI-SIF images can be run with
-  SingularityCE 4.1 and later.
-
-***********
-CLI Changes
-***********
-
-- The ``registry login`` and ``registry logout`` commands now support an
-  ``--authfile <path>`` flag, which causes the OCI credentials to be written to
-  / removed from a custom file located at ``<path>`` instead of the default
-  location (``$HOME/.singularity/docker-config.json``). The commands ``pull``,
-  ``push``, ``run``, ``exec``, ``shell``, and ``instance start`` can now also be
-  passed a ``--authfile <path>`` option, to read OCI registry credentials from
-  this custom file.
-- A new `--tmp-sandbox` flag has been added to the `run / shell / exec /
-  instance start` commands. This will force Singularity to extract a container
-  to a temporary sandbox before running it, when it would otherwise perform a
-  kernel or FUSE mount.
-
-************************
-Runtime Behavior Changes
-************************
-
-- In native mode, SIF/SquashFS container images will now be mounted with
-  squashfuse when kernel mounts are disabled in ``singularity.conf``, or cannot
-  be used (non-setuid / user namespace workflow). If the FUSE mount fails,
-  Singularity will fall back to extracting the container to a temporary sandbox
-  in order to run it.
-- In native mode, bare extfs container images will now be mounted with
-  ``fuse2fs`` when kernel mounts are disabled in ``singularity.conf``, or cannot
-  be used (non-setuid / user namespace workflow).
-
-************
-Deprecations
-************
-
-- The experimental ``--sif-fuse`` flag, and ``sif fuse`` directive in
-  ``singularity.conf`` are deprecated. The flag and directive were used to
-  enable experimental mounting of SIF/SquashFS container images with FUSE in
-  prior versions of Singularity. From 4.1, FUSE mounts are used automatically
-  when kernel mounts are disabled / not available.
+- The new ``--netns-path`` flag takes a path to a network namespace to join when
+  starting a container. The root user may join any network namespace. An
+  unprivileged user can only join a network namespace specified in the new
+  allowed ``netns paths directive`` in ``singularity.conf``, if they are also
+  listed in ``allow net users`` / ``allow net groups``. Not currently supported
+  with ``--fakeroot``, or in ``--oci`` mode. See :ref:`sec:netns-path`.