NAME="instance.start"
GROUP="instance"
SUMMARY="Start a new container instance"
USAGE="singularity [...] instance.start [...] <container path> <instance name>"

print_help() {
cat<<EOF

Start a named instance of the given container image.


START OPTIONS:
    -B|--bind <spec>    A user-bind path specification.  spec has the format
                        src[:dest[:opts]], where src and dest are outside and
                        inside paths.  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). This option can be called multiple times.
    -c|--contain        Use minimal /dev and empty other directories (e.g. /tmp
                        and $HOME) instead of sharing filesystems on your host
    -H|--home <spec>    A home directory specification.  spec can either be a
                        src path or src:dest pair.  src is the source path
                        of the home directory outside the container and dest
                        overrides the home directory within the container
    -n|--net            Run container in a new network namespace (loopback is
                        only network device active)
    --nv                Enable experimental Nvidia support
    -o|--overlay        Use a persistent overlayFS via a writable image
    -S|--scratch <path> Include a scratch directory within the container that
                        is linked to a temporary dir (use -W to force location)
    -W|--workdir        Working directory to be used for /tmp, /var/tmp and
                        $HOME (if -c/--contain was also used)
    -w|--writable       By default all Singularity containers are available as
                        read only. This option makes the file system accessible
                        as read/write.


CONTAINER FORMATS SUPPORTED:
    *.img               This is the native Singularity image format for all
                        Singularity versions 2.x.
    *.sqsh              SquashFS format, note the suffix is required!
    *.tar*              Tar archives are exploded to a temporary directory and
                        run within that directory (and cleaned up after). The
                        contents of the archive is a root file system with root
                        being in the current directory. Compression suffixes as
                        '.gz' and '.bz2' are supported.
    directory/          Container directories that contain a valid root file
                        system.


EXAMPLES:

    $ singularity instance.start /tmp/my-sql.img mysql

    $ singularity shell instance://mysql
    Singularity my-sql.img> pwd
    /home/mibauer/mysql
    Singularity my-sql.img> ps
    PID TTY          TIME CMD
      1 pts/0    00:00:00 sinit
      2 pts/0    00:00:00 bash
      3 pts/0    00:00:00 ps
    Singularity my-sql.img> 
    
    $ singularity instance.stop /tmp/my-sql.img mysql
    Stopping /tmp/my-sql.img mysql


For additional help, please visit our public documentation pages which are
found at:

    http://singularity.lbl.gov/
EOF
}
