Filesystem Namespace

Filesystem namespace

Every filesystem on the appliance must be given a unique mountpoint which
serves as the access point for the filesystem data. Projects can
be given mountpoints, but these serve only as a tool to manage
the namespace using inherited properties. Projects are never mounted, and do
not export data over any protocol.

All shares must be mounted under /export. While it is possible
to create a filesystem mounted at /export, it is not required.
If such a share doesn't exist, any directories will be created dynamically
as necessary underneath this portion of the hierarchy. Each mountpoint must
be unique within a cluster.

Nested mountpoints

It is possible to create filesystems with mountpoints beneath that of other
filesystems. In this scenario, the parent filesystems are mounted before
children and vice versa. The following cases should be considered when
using nested mountpoints:

If the mountpoint doesn't exist, one will be created, owned by root and mode 0755. This mountpoint may or may not be torn down when the filesystem is renamed, destroyed, or moved, depending on circumstances. To be safe, mountpoints should be created within the parent share before creating the child filesystem.

If the parent directory is read-only, and the mountpoint doesn't exist, the filesystem mount will fail. This can happen synchronously when creating a filesystem, but can also happen asynchronously when making a large-scale change, such as renaming filesystems with inherited mountpoints.

When renaming a filesystem or changing its mountpoint, all children beneath the current mountpoint as well as the new mountpoint (if different) will be unmounted and remounted after applying the change. This will interrupt any data services currently accessing the share.

Support for automatically traversing nested mountpoints depends on protocol, as outlined below.

Protocol access to mountpoints

Regardless of protocol settings, every filesystem must have a mountpoint. However,
the way in which these mountpoints are used depends on protocol.

NFSv2 / NFSv3

Under NFS, each filesystem is a unique export made visible via the
MOUNT protocol. NFSv2 and NFSv3 have no way to traverse nested
filesystems, and each filesystem must be accessed by its full path.
While nested mountpoints are still functional, attempts to cross a nested mountpoint
will result in an empty directory on the client. While this
can be mitigated through the use of automount mounts, transparent support of
nested mountpoints in a dynamic environment requires NFSv4.

NFSv4

NFSv4 has several improvements over NFSv3 when dealing with mountpoints. First
is that parent directories can be mounted, even if there is no
share available at that point in the hierarchy. For example, if
/export/home was shared, it is possible to mount /export on the client
and traverse into the actual exports transparently. More significantly, some NFSv4
clients (including Linux) support automatic client-side mounts, sometimes referred to as "mirror
mounts". With such a client, when a user traverses a mountpoint,
the child filesystem is automatically mounted at the appropriate local mountpoint, and
torn down when the filesystem is unmounted on the client. From
the server's perspective, these are separate mount requests, but they are stitched
together onto the client to form a seamless filesystem namespace.

SMB

The SMB protocol does not use mountpoints, as each share is made
available by resource name. However, each filesystem must still have a
unique mountpoint. Nested mountpoints (multiple filesystems within one resource) are not
currently supported, and any attempt to traverse a mountpoint will result in
an empty directory.

FTP / FTPS / SFTP

Filesystems are exported using their standard mountpoint. Nested mountpoints are fully
supported and are transparent to the user. However, it is not
possible to not share a nested filesystem when its parent is shared.
If a parent mountpoint is shared, then all children will be
shared as well.

HTTP / HTTPS

Filesystems are exported under the /shares directory, so a filesystem at /export/home
will appear at /shares/export/home over HTTP/HTTPS. Nested mountpoints are fully
supported and are transparent to the user. The same behavior regarding
conflicting share options described in the FTP protocol section also applies to
HTTP.