Another feature debut in OneFS 9.3 is support for long filenames. Until now, the OneFS filename limit has been capped 255 bytes. However, depending on the encoding type, this could potentially be an impediment for certain languages such as Chinese, Hebrew, Japanese, Korean, and Thai, and can create issues for customers who work with international languages that use multi-byte UTF-8 characters.
Since some international languages use up to 4 bytes per character, a file name of 255 bytes could be limited to as few as 63 characters when using certain languages on a cluster.
To address this, the new long filenames feature provides support for names up to 255 Unicode characters, by increasing the maximum file name length from 255 bytes to 1024 bytes. In conjunction with this, the OneFS maximum path length is also increased from 1024 bytes to 4096 bytes.
Before creating a name length configuration, the cluster must be running OneFS 9.3. However, the long filename feature is not activated or enabled by default. You have to opt-in by creating a “name length” configuration. That said, the recommendation is to only enable long filename support if you are actually planning on using it. This is because, once enabled, OneFS does not track if, when, or where, a long file name or path is created.
The following procedure can be used to configure a PowerScale cluster for long filename support:
Step 1: Ensure cluster is running OneFS 9.3 or later.
The ‘uname’ CLI command output will display a cluster’s current OneFS version.
For example:
# uname -sr Isilon OneFS v9.3.0.0
The current OneFS version information is also displayed at the upper right of any of the OneFS WebUI pages. If the output from step 1 shows the cluster running an earlier release, an upgrade to OneFS 9.3 will be required. This can be accomplished either using the ‘isi upgrade cluster’ CLI command or from the OneFS WebUI, by going to Cluster Management > upgrade.
Once the upgrade has completed it will need to be committed, either by following the WebUI prompts, or using the ‘isi upgrade cluster commit’ CLI command.
Step 2. Verify Cluster’s Long Filename Support Configuration
- Viewing a Cluster’s Long Filename Support Settings
The ‘isi namelength list’ CLI command output will verify a cluster’s long filename support status. For example, the following cluster already has long filename support enabled on the /ifs/tst path:
# isi namelength list Path Policy Max Bytes Max Chars ----------------------------------------- /ifs/tst restricted 255 255 ----------------------------------------- Total: 1
Step 3. Configure Long Filename Support
The ‘isi namelength create <path>’ CLI command can be run on the cluster to enable long filename support.
# mkdir /ifs/lfn # isi namelength create --max-bytes 1024 --max-chars 1024 /ifs/lfn
By default, namelength support is created with default maximum values of 255 Bytes in length and 255 characters.
Step 4: Confirm Long Filename Support is Configured
The ‘isi namelength list’ CLI command output will confirm that the cluster’s /ifs/lfn directory path is now configured to support long filenames:
# isi namelength list Path Policy Max Bytes Max Chars ----------------------------------------- /ifs/lfn custom 1024 1024 /ifs/tst restricted 255 255 ----------------------------------------- Total: 2
Name length configuration is setup per directory and can be nested. Plus, cluster-wide configuration can be applied by configuring at the root /ifs level.
Filename length configurations have two defaults:
- “Full” – which is 1024 bytes, 255 characters.
- “Restricted” – which is 255 bytes, 255 characters, and the default if no long additional filename configuration is specified.
Note that removing the long name configuration for a directory will not affect its contents, including any previously created files and directories with long names. However, it will prevent any new long-named files or subdirectories from being created under that directory.
If a filename is too long for a particular protocol, OneFS will automatically truncate the name to around 249 bytes with a ‘hash’ appended to it, which can be used to consistently identify and access the file. This shortening process is referred to as ‘name mangling’. If, for example, a filename longer than 255 bytes is returned in a directory listing over NFSv3, the file’s mangled name will be presented. Any subsequent lookups of this mangled name will resolve to the same file with the original long name. Be aware that filename extensions will be lost when a name is mangled, which can have ramifications for Windows applications, etc.
If long filename support is enabled on a cluster with active SyncIQ policies, all source and target clusters must have OneFS 9.3 or later installed and committed, and long filename support enabled.
However, the long name configuration does not need to be identical between the source and target clusters; it only needs to be enabled. This can be done via the following sysctl:
# sysctl efs.bam.long_file_name_enabled=1
When the target cluster for a Sync policy does not support long file names for a SyncIQ policy and the source domain has long file names enabled, the replication job will fail. The subsequent SyncIQ job report will include the following error message:
Note that the OneFS checks are unable to identify a cascaded replication target running an earlier OneFS version and/or without long filenames configured.
So there are a couple of things to bear in mind when using long filenames:
- Restoring data from a 9.3 NDMP backup containing long filenames to a cluster running an earlier OneFS version will fail with an ‘ENAMETOOLONG’ error for each long-named file. However, all the files with regular length names will be successfully restored from the backup stream.
- OneFS ICAP does not support long filenames. However CAVA, ICAP’s replacement, is compatible.
- The ‘isi_vol_copy’ migration utility does not support long filenames.
- Neither does the OneFS WebDAV protocol implementation.
- Symbolic links created via SMB are limited to 1024 bytes due to the size limit on extended attributes.
- Any pathnames specified in long filename pAPI operations are limited to 4068 bytes.
- And finally, while an increase in long named files and directories could potentially reduce the number of names the OneFS metadata structures can hold, the overall performance impact of creating files with longer names is negligible.