Document singularity instance run

`singularity instance run` to start an instance executing the runscript.

Add 'new in' bullet, and update references to flag support of instances.

Fixes #244

bind_paths_and_mounts.rst

@@ -102,17 +102,17 @@ Unless the system administrator has `disabled user control of binds
 <https://singularity-admindoc.readthedocs.io/en/latest/the_singularity_config_file.html#user-bind-control-boolean-default-yes>`_,
 you will be able to request your own bind paths within your container.
 
-The {Singularity} action commands (``run``, ``exec``, ``shell``, and
-``instance start``) will accept the ``--bind/-B`` command-line option to
-specify bind paths, and will also honor the ``$SINGULARITY_BIND`` (or
-``$SINGULARITY_BINDPATH``) environment variable. The argument for this
-option is a comma-delimited string of bind path specifications in the
-format ``src[:dest[:opts]]``, where ``src`` and ``dest`` are paths
-outside and inside of the container respectively. If ``dest`` is not
-given, it is set equal to ``src``. Mount options (``opts``) may be
-specified as ``ro`` (read-only) or ``rw`` (read/write, which is the
-default). The ``--bind/-B`` option can be specified multiple times, or a
-comma-delimited string of bind path specifications can be used.
+The {Singularity} action commands (``run``, ``exec``, ``shell``, ``instance
+start`` and ``instance run``) will accept the ``--bind/-B`` command-line
+option to specify bind paths, and will also honor the ``$SINGULARITY_BIND`` (or
+``$SINGULARITY_BINDPATH``) environment variable. The argument for this option is
+a comma-delimited string of bind path specifications in the format
+``src[:dest[:opts]]``, where ``src`` and ``dest`` are paths outside and inside
+of the container respectively. If ``dest`` is not given, it is set equal to
+``src``. Mount options (``opts``) may be specified as ``ro`` (read-only) or
+``rw`` (read/write, which is the default). The ``--bind/-B`` option can be
+specified multiple times, or a comma-delimited string of bind path
+specifications can be used.
 
 {Singularity} 3.9 adds an additional ``--mount`` flag, which provides a
 longer-form method of specifying binds in ``--mount

definition_files.rst

@@ -665,13 +665,13 @@ the port indicated by the ``$LISTEN_PORT`` variable (set in the
 %runscript
 ==========
 
-The contents of the ``%runscript`` section are written to a dedicated
-file within the container that is executed when the container image is
-run (either via the ``singularity run`` command or by :ref:`executing
-the container directly <runcontainer>` as a command). When the container
-is invoked, arguments following the container name are passed to the
-runscript. This means that you can (and should) process arguments within
-your runscript.
+The contents of the ``%runscript`` section are written to a dedicated file
+within the container that is executed when the container image is run (either
+via the ``singularity run`` command or by :ref:`executing the container directly
+<runcontainer>` as a command, or when an instance is started with ``singularity
+instance run``). When the container is invoked, arguments following the
+container name are passed to the runscript. This means that you can (and should)
+process arguments within your runscript.
 
 Consider the ``%runscript`` section from the example definition file
 above:

fakeroot.rst

@@ -121,6 +121,7 @@ commands:
    -  ``exec``
    -  ``run``
    -  ``instance start``
+   -  ``instance run``
    -  ``build``
 
 Build

new.rst

@@ -31,4 +31,7 @@ Runtime
   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`.
+- Instances can now be started via the new subcommand ``singularity instance
+  run``, which will cause the instance to execute its ``%runscript`` rather than
+  the ``%startscript``.
 

persistent_overlays.rst

@@ -39,6 +39,7 @@ You can use persistent overlays with the following commands:
 -  ``exec``
 -  ``shell``
 -  ``instance start``
+-  ``instance run``
 
 *****
 Usage

registry.rst

@@ -73,6 +73,8 @@ hostname used, whenever one of the following commands is used with a
 `run
 <https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_run.html>`__,
 `instance start
+<https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_instance.html>`__,
+`instance run
 <https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_instance.html>`__
 
 .. note::
@@ -127,6 +129,8 @@ commands discussed above (`pull
 `run
 <https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_run.html>`__,
 `instance start
+<https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_instance.html>`__,
+`instance run
 <https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_instance.html>`__),
 by passing them the same ``--authfile <path>`` flag:
 
@@ -205,5 +209,7 @@ both for the ``registry login`` / ``registry logout`` commands and for the `pull
 <https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_run.html>`__
 / `instance start
 <https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_instance.html>`__
+/ `instance run
+<https://www.sylabs.io/guides/{version}/user-guide/cli/singularity_instance.html>`__
 set of commands.
 

running_services.rst

@@ -66,7 +66,24 @@ as ``alpine_latest.sif``.
 Starting Instances
 ==================
 
-To start an instance, you should follow this procedure :
+There are two ways to start an instance, using either ``singularity instance
+start``, or ``singularity instance run``. These commands differ in what script
+is executed in the container that is created.
+
+``singularity instance start`` is the standard way to start an instance. A
+container will be created, and the ``%startscript`` in the container's
+:ref:`definition file <definition-files>` will be executed. The use of the
+``%startscript`` allows container images to have different behaviour compared to
+when they are run interactively via ``singularity run``, which will execute the
+``%runscript``. If there is no ``%startscript`` defined, then ``instance start``
+will create a container that is idle.
+
+From {Singularity} 4.2 an instance can be started that executes the
+``%runscript``, using ``singularity instance run``. This is useful where you
+wish to run a container as an instance, but it was not built anticipating this
+scenario. ``instance run`` takes the same arguments and flags as ``instance start``.
+
+The syntax of the ``instance start`` command is as follows:
 
 .. code::
 
@@ -123,14 +140,10 @@ You can filter the instance list by supplying a pattern:
    INSTANCE NAME    PID      IP              IMAGE
    instance2        22443                    /home/dave/instances/alpine_latest.s
 
-When an instance is started, it will begin to run the ``%startscript`` from the
-container's :ref:`definition file <definition-files>` in the background. If
-there is no ``%startscript`` the container will stay idle in the background.
-
 Interacting With Instances
 ==========================
 
-Although an instance runs its ``%startscript`` (if there is one) in the
+Although an instance executes its ``%startscript`` or ``%runscript`` in the
 background, you can also interact with it in the foreground, by referring to it
 with an ``instance://<name>`` URI, where ``<name>`` is replaced with the
 instance name.