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
attrpackage.
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.
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
fileordir. - 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
-
TYPE with
Additional Resources
- See the table in the Overview of file and directory layouts section of the Red Hat Ceph Storage File System Guide for more details.
-
See the
setfattr(1)manual page.
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
fileordir.
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"
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
-
The
getfattr(1)manual page. - For more information, see Setting file and directory layout fields section in the Red Hat Ceph Storage File System Guide.
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
fileordir. - FIELD with the name of the field.
- PATH with the path to the file or directory.
-
TYPE with
Example
[root@mon ~]# getfattr -n ceph.file.layout.pool test ceph.file.layout.pool="cephfs_data"
NotePools in the
poolfield 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.
When you set a file layout, you cannot change or remove it.
Prerequisites
- A directory with a layout.
Procedure
To remove a layout from a directory:
Syntax
setfattr -x ceph.dir.layout DIRECTORY_PATHExample
[user@client ~]$ setfattr -x ceph.dir.layout /home/cephfs
To remove the
pool_namespacefield:Syntax
setfattr -x ceph.dir.layout.pool_namespace DIRECTORY_PATHExample
[user@client ~]$ setfattr -x ceph.dir.layout.pool_namespace /home/cephfs
NoteThe
pool_namespacefield 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.
