Bind Paths and Mounts

If enabled by the system administrator, Singularity allows you to map directories on your host system to directories within your container using bind mounts. This allows you to read and write data on the host system with ease.

Overview

When Singularity ‘swaps’ the host operating system for the one inside your container, the host file systems becomes inaccessible. But you may want to read and write files on the host system from within the container. To enable this functionality, Singularity will bind directories back into the container via two primary methods: system-defined bind paths and user-defined bind paths.

System-defined bind paths

The system administrator has the ability to define what bind paths will be included automatically inside each container. Some bind paths are automatically derived (e.g. a user’s home directory) and some are statically defined (e.g. bind paths in the Singularity configuration file). In the default configuration, the system default bind points are $HOME , /sys:/sys , /proc:/proc, /tmp:/tmp, /var/tmp:/var/tmp, /etc/resolv.conf:/etc/resolv.conf, /etc/passwd:/etc/passwd, and $PWD. Where the first path before : is the path from the host and the second path is the path in the container.

User-defined bind paths

If the system administrator has enabled user control of binds, 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.

Specifying bind paths

Here’s an example of using the --bind option and binding /data on the host to /mnt in the container (/mnt does not need to already exist in the container):

$ ls /data
bar  foo

$ singularity exec --bind /data:/mnt my_container.sif ls /mnt
bar  foo

You can bind multiple directories in a single command with this syntax:

$ singularity shell --bind /opt,/data:/mnt my_container.sif

This will bind /opt on the host to /opt in the container and /data on the host to /mnt in the container.

Using the environment variable instead of the command line argument, this would be:

$ export SINGULARITY_BIND="/opt,/data:/mnt"

$ singularity shell my_container.sif

Using the environment variable $SINGULARITY_BIND, you can bind paths even when you are running your container as an executable file with a runscript. If you bind many directories into your Singularity containers and they don’t change, you could even benefit by setting this variable in your .bashrc file.

A note on using --bind with the --writable flag

To mount a bind path inside the container, a bind point must be defined within the container. The bind point is a directory within the container that Singularity can use as a destination to bind a directory on the host system.

Starting in version 3.0, Singularity will do its best to bind mount requested paths into a container regardless of whether the appropriate bind point exists within the container. Singularity can often carry out this operation even in the absence of the “overlay fs” feature.

However, binding paths to non-existent points within the container can result in unexpected behavior when used in conjuction with the --writable flag, and is therefore disallowed. If you need to specify bind paths in combination with the --writable flag, please ensure that the appropriate bind points exist within the container. If they do not already exist, it will be necessary to modify the container and create them.

Using --no-home and --containall flags

--no-home

When shelling into your container image, Singularity allows you to mount your current working directory (CWD) without mounting your host $HOME directory with the --no-home flag.

$ singularity shell --no-home my_container.sif

Note

Beware that if it is the case that your CWD is your $HOME directory, it will still mount your $HOME directory.

--containall

Using the --containall (or -C for short) flag, $HOME is not mounted and a dummy bind mount is created at the $HOME point. You cannot use -B` (or --bind) to bind your $HOME directory because it creates an empty mount. So if you have files located in the image at /home/user, the --containall flag will hide them all.

$ singularity shell --containall my_container.sif

FUSE mounts

Filesystem in Userspace (FUSE) is an interface to allow filesystems to be mounted using code that runs in userspace, rather than in the Linux Kernel. Unprivileged (non-root) users can mount filesystems that have FUSE drivers. For example, the fuse-sshfs package allows you to mount a remote computer’s filesystem to your local host, over ssh:

$ mount.fuse sshfs#ythel:/home/dave other_host/

# Now mounted to my local machine:
$ ythel:/home/dave on /home/dave/other_host type fuse.sshfs (rw,nosuid,nodev,relatime,user_id=1000,group_id=1000)

Singularity 3.6 introduces the --fusemount option, which allows you directly expose FUSE filesystems inside a container. The FUSE command / driver that mounts a particular type of filesystem can be located on the host, or in the container.

The FUSE command must be based on libfuse3 to work correctly with Singularity --fusemount. If you are using an older distribution that provides FUSE commands such as sshfs based on FUSE 2 then you can install FUSE 3 versions of the commands you need inside your container.

Note

--fusemount functionality was present in a hidden preview state from Singularity 3.4. The behavior has changed for the final supported version introduced in Singularity 3.6.

FUSE mount definitions

A fusemount definition for Singularity consists of 3 parts:

--fusemount <type>:<fuse command> <container mountpoint>

  • type specifies how and where the FUSE mount will be run. The options are:

    • container - use a FUSE command on the host, to mount a filesystem into the container, with the fuse process attached.

    • host - use a FUSE command inside the container, to mount a filesystem into the container, with the fuse process attached.

    • container-daemon - use a FUSE command on the host, to mount a filesystem into the container, with the fuse process detached.

    • host-daemon - use a FUSE command inside the container, to mount a filesystem into the container, with the fuse process detached.

  • fuse command specifies the name of the executable that implements the FUSE mount, and any arguments. E.g. sshfs server:over-there/ for mounting a remote filesystem over SSH, where the remote source is over-there/ in my home directory on the machine called server.

  • container mountpoint is an absolute path at which the FUSE filesystem will be mounted in the container.

FUSE mount with a host executable

To use a FUSE sshfs mount in a container, where the fuse-sshfs package has been installed on my host, I run with the host mount type:

$ singularity run --fusemount "host:sshfs server:/ /server" docker://ubuntu
Singularity> cat /etc/hostname
localhost.localdomain
Singularity> cat /server/etc/hostname
server

FUSE mount with a container executable

If the FUSE driver / command that you want to use for the mount has been added to your container, you can use the container mount type:

$ singularity run --fusemount "container:sshfs server:/ /server" sshfs.sif
Singularity> cat /etc/hostname
localhost.localdomain
Singularity> cat /server/etc/hostname
server