1. Oracle ZFS Storage Appliance Administration Guide, Release OS8.8.x
  2. Shares and Projects
  3. Working with Filesystem Namespace

Working with Filesystem Namespace

Every filesystem on Oracle ZFS Storage 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 does not exist, any directories will be created dynamically as necessary underneath this portion of the hierarchy. Each mountpoint must be unique within a cluster.

  • Namespace 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 does not 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 does not 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 in the following.

  • Namespace NFSv2 / NFSv3 / NFSv4.0 / NFSv4.1 - 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.0 or NFSv4.1.

    NFSv4.0 and NFSv4.1 have several improvements over NFSv3 when managing 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.0 and NFSv4.1 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.

  • 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.

  • Namespace 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.

  • Namespace 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.