Document changes to FUSE / temporary sandbox behaviour

Remove `--sif-fuse` mentions (deprecated experimental functionality).

FUSE attempted before temp sandbox extraction.

`--tmp-sandbox` flag to force extraction.

Fixes #228
Fixes #227
Fixes #225

appendix.rst

@@ -352,8 +352,8 @@ below with their respective functionality.
 
 #. **SINGULARITY_NO_TMP_SANDBOX**: Set to true to disable fall-back approach of
    extracting a container to a temporary sandbox when SIF / OCI-SIF mounts
-   cannot be used. Default is false. Also configurable via ``tmp sandbox`` in
-   ``singularity.conf``.
+   cannot be used. Default is false. Temporary sandboxes may also be disabled
+   permanently by setting ``tmp sandbox = no`` in ``singularity.conf``.
 
 ``O``
 =====
@@ -428,9 +428,9 @@ below with their respective functionality.
 #. **SINGULARITY_SHELL**: The path to the program to be used as an
    interactive shell.
 
-#. **SINGULARITY_SIF_FUSE**: (experimental) Set to true to attempt to
+#. **SINGULARITY_SIF_FUSE**: (deprecated) Set to true to attempt to
    mount SIF images with ``squashfuse`` in unprivileged user namespace
-   workflows.
+   workflows. This is now the default behaviour from {Singularity} 4.1.
 
 #. **SINGULARITY_SIGNAL**: Specifies the signal to send to an instance with
    ``singularity instance stop``.
@@ -444,6 +444,10 @@ below with their respective functionality.
 ``T``
 =====
 
+#. **SINGULARITY_TMP_SANDBOX**: Set to true to force fall-back approach of
+   extracting a container to a temporary sandbox, even direct when SIF / OCI-SIF
+   mounts could be used. Default is false.
+
 #. **SINGULARITY_TEST**: Specifies the test script for the image.
 
 #. **SINGULARITY_TMPDIR**: Specify a location for temporary files to be used

security.rst

@@ -110,26 +110,21 @@ In this mode *all* operations run as the user who starts the
 ``singularity`` program. However, there are some disadvantages to this
 approach:
 
--  SIF and other single-file container images cannot be mounted
-   directly. The container image must be extracted to a directory on
-   disk to run. This impacts the speed of execution. As a result,
-   workloads accessing large numbers of small files (as is the case with
-   python application startup, for example) do not benefit from the
-   reduced metadata load on the filesystem an image file provides.
-
-   {Singularity} 3.10 introduces experimental functionality to avoid
-   this image-extraction by mounting the SIF container using
-   ``squashfuse``, if available on your system. You can enable this with
-   the ``--sif-fuse`` flag, or by setting ``sif fuse`` in
-   ``singularity.conf``.
-
--  Replacing direct kernel mounts with a FUSE approach is likely to
-   cause a significant reduction in performance.
-
--  The effectiveness of signing and verifying container images is
-   reduced as, when extracted to a directory, modification of files is
-   possible and verification of the image's original signature cannot be
-   performed.
+-  SIF and other single-file container images cannot be mounted using kernel
+   mounts. {Singularity} will attempt to mount them in user space, using FUSE.
+   If this is not possible, the container image must be extracted to a directory
+   on disk to run. This impacts the speed of execution. As a result, workloads
+   accessing large numbers of small files (as is the case with python
+   application startup, for example) do not benefit from the reduced metadata
+   load on the filesystem an image file provides. To force extraction to disk,
+   instead of FUSE mount, use the ``--tmp-sandbox`` flag. To ensure containers
+   are not extracted to disk, even when FUSE mounts fail,  use the
+   ``--no-tmp-sandbox`` flag.
+
+-  The effectiveness of signing and verifying container images is reduced. With
+   both FUSE mounts, and sandbox directories, the content of the container can
+   easily be modified at runtime and verification against the image's original
+   signature cannot be performed.
 
 -  Encryption is not supported. {Singularity} leverages kernel LUKS2
    mounts to run encrypted containers without writing a decrypted

singularity_and_docker.rst

@@ -1051,11 +1051,13 @@ enable some of the extra namespaces that Docker uses, with flags:
    container networking from the host.
 
 -  ``--userns / -u`` runs the container unprivileged, inside a user namespace
-   and avoiding {Singularity}'s setuid setup code. By default, SIF container
-   images will be extracted to disk, as mounting the container filesystem from
-   the SIF requires privilege. An experimental ``--sif-fuse`` flag can be used
-   to perform a mount with ``squashfuse`` instead, if it is available on your
-   system.
+   and avoiding {Singularity}'s setuid setup code. By default, container images
+   will be mounted in user space using FUSE. If this is not possible, they will
+   be extracted to disk, as mounting the container filesystem from the image
+   using kernel mounts requires privilege. To force extraction to disk, instead
+   of FUSE mount, use the ``--tmp-sandbox`` flag. To ensure containers are not
+   extracted to disk, even when FUSE mounts fail,  use the ``--no-tmp-sandbox``
+   flag.
 
 -  ``--uts`` creates a new UTS namespace, which allows a different
    hostname and/or NIS domain for the container.