Chapter 8. File and directory layouts

As a storage administrator, you can control how file or directory data is mapped to objects.

This section describes how to:

8.1. Prerequisites

  • A running, and healthy Red Hat Ceph Storage cluster.
  • Deployment of a Ceph File System.
  • The installation of the attr package.

8.2. Overview of file and directory layouts

This section explains what file and directory layouts are in the context for the Ceph File System.

A layout of a file or directory controls how its content is mapped to Ceph RADOS objects. The directory layouts serve primarily for setting an inherited layout for new files in that directory.

To view and set a file or directory layout, use virtual extended attributes or extended file attributes (xattrs). The name of the layout attributes depends on whether a file is a regular file or a directory:

  • Regular files layout attributes are called ceph.file.layout.
  • Directories layout attributes are called ceph.dir.layout.

Layouts Inheritance

Files inherit the layout of their parent directory when you create them. However, subsequent changes to the parent directory layout do not affect children. If a directory does not have any layouts set, files inherit the layout from the closest directory to the layout in the directory structure.

8.3. Setting file and directory layout fields

Use the setfattr command to set layout fields on a file or directory.

Important

When you modify the layout fields of a file, the file must be empty, otherwise an error occurs.

Prerequisites

  • Root-level access to the node.

Procedure

  • To modify layout fields on a file or directory:

    Syntax

    setfattr -n ceph.TYPE.layout.FIELD -v VALUE PATH

    Replace:

    • TYPE with file or dir.
    • FIELD with the name of the field.
    • VALUE with the new value of the field.
    • PATH with the path to the file or directory.

    Example

    [root@mon ~]# setfattr -n ceph.file.layout.stripe_unit -v 1048576 test

Additional Resources

8.4. Viewing file and directory layout fields

To use the getfattr command to view layout fields on a file or directory.

Prerequisites

  • A running Red Hat Ceph Storage cluster.
  • Root-level access to all nodes in the storage cluster.

Procedure

  • To view layout fields on a file or directory as a single string:

    Syntax

    getfattr -n ceph.TYPE.layout PATH

    Replace
    • PATH with the path to the file or directory.
    • TYPE with file or dir.

    Example

    [root@mon ~]# getfattr -n ceph.dir.layout /home/test
ceph.dir.layout="stripe_unit=4194304 stripe_count=2 object_size=4194304 pool=cephfs_data"

Note

A directory does not have an explicit layout until you set it. Consequently, attempting to view the layout without first setting it fails because there are no changes to display.

Additional Resources

8.5. Viewing individual layout fields

Use the getfattr command to view individual layout fields for a file or directory.

Prerequisites

  • A running Red Hat Ceph Storage cluster.
  • Root-level access to all nodes in the storage cluster.

Procedure

  • To view individual layout fields on a file or directory:

    Syntax

    getfattr -n ceph.TYPE.layout.FIELD _PATH

    Replace
    • TYPE with file or dir.
    • FIELD with the name of the field.
    • PATH with the path to the file or directory.

    Example

    [root@mon ~]# getfattr -n ceph.file.layout.pool test
ceph.file.layout.pool="cephfs_data"

    Note

    Pools in the pool field are indicated by name. However, newly created pools can be indicated by ID.

Additional Resources

  • The getfattr(1) manual page.
  • For more information, see File and directory layouts section in the Red Hat Ceph Storage File System Guide.

8.6. Removing directory layouts

Use the setfattr command to remove layouts from a directory.

Note

When you set a file layout, you cannot change or remove it.

Prerequisites

  • A directory with a layout.

Procedure

  1. To remove a layout from a directory:

    Syntax

    setfattr -x ceph.dir.layout DIRECTORY_PATH

    Example

    [user@client ~]$ setfattr -x ceph.dir.layout /home/cephfs

  2. To remove the pool_namespace field:

    Syntax

    setfattr -x ceph.dir.layout.pool_namespace DIRECTORY_PATH

    Example

    [user@client ~]$ setfattr -x ceph.dir.layout.pool_namespace /home/cephfs

    Note

    The pool_namespace field is the only field you can remove separately.

Additional Resources

  • The setfattr(1) manual page

8.7. Additional Resources

  • See the Deployment of the Ceph File System section in the Red Hat Ceph Storage File System Guide.
  • See the getfattr(1) manual page for more information.
  • See the setfattr(1) manual page for more information.