scalectl fileset command

Availability

Available on all IBM Storage Scale editions.

Description

Use the scalectl fileset command to create and manage a fileset.

Parameters

create {FilesystemName}

Creates a new fileset. The fileset can be linked into the namespace when you specify a junction path. The operation attribute for this command is long-running operation (LRO). To run this command, you must have the RBAC permission for the create action on the /scalemgmt/v3/filesystems/{filesystem}/filesets resource.

--allow-permission-change {chmodAndSetAcl | chmodOnly | setAclOnly | chmodAndUpdateAcl}

Specifies the new permission change mode. The possible values are chmodAndSetAcl, chmodOnly, setAclOnly, and chmodAndUpdateAcl. The default value is chmodAndSetAcl.

--allow-permission-inherit {inheritAclOnly | inheritAclAndAddMode}

Specifies the new permission inherit mode. The possible values are inheritAclOnly and inheritAclAndAddMode. The default value is inheritAclOnly.

-t or --comment {Comment}

Specifies a comment for the fileset.

--iam-mode {off | advisory | noncompliant | compliant | compliant-plus}

Specifies the integrated archive manager (IAM) mode for the fileset. The possible values are off, advisory, noncompliant, compliant and compliant-plus. The default value is off.

--inode-limit {InodeLimit}

Specifies the inode limit for the inode space that is owned by a fileset.

--inode-space {new| ExistingFileset}

Specifies the type of fileset to create, which controls how inodes are allocated.

new

Creates an independent fileset and its own dedicated inode space.

ExistingFileset

Creates a dependent fileset that will share inode space with the specified ExistingFileset. The ExistingFileset can be root or any other independent fileset.

If --inode-space is not specified, a dependent fileset will be created in the root inode space.

-J or --junction-path {JunctionPath}

Specifies the name of the junction.

-n or --name {FilesetName}

Specifies the name of the fileset.

--pre-alloc-inodes {NumInodes}

Specifies the number of inodes to preallocate for the fileset. This flag is valid only when used with the --inode-limit.

delete {FilesystemName} {FilesetName}

Deletes an existing fileset. The operation attribute for this command is LRO. To run this command, you must have the RBAC permission for the delete action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{fileset_name} resource. When deleting a fileset, consider the following conditions:

• You can delete the root fileset
• A fileset that is not empty cannot be deleted unless you specify the -f flag.
  Note: If you use the -f flag, remove all NFS exports defined on or inside the fileset junction path before deleting it. Otherwise, you might encounter errors or issues when creating new filesets and exports.
• You cannot delete a fileset that is lined to a namespace until you unlink it using the unlink command.
• You can delete a dependent fileset at any time.
• You cannot delete an independent fileset if it has dependent filesets or snapshots.
• A deleted dependent fileset remains in the file system in a deleted state until the last snapshot that includes it is deleted.
• Deleting an independent fileset that is included in a global snapshot removes it from the active file system, but it remains part of the file system in a deleted state.
• The contents of a deleted fileset are still available in the snapshot through a path containing a .snapshots component because this data was saved when the snapshot was created.
• When the last snapshot that includes the fileset is deleted, the fileset is fully removed from the file system.

-f or --force

Forecefully deletes the fileset. Deletes all contents and unlinks any child filesets.

--pit-continues-on-error

Continues removing the remaining files, if errors are encountered in the parallel inode traverse (PIT) phase that does user file deletion.

get {FilesystemName} {FilesetName}

Retrieves information about an existing fileset. The operation attribute for this command is fields. To run this command, you must have the RBAC permission for the get action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{fileset_name} resource.

--view {full | basic | long | attributes}

Specifies the view for fileset contents. The possible values are full, basic, long, and attributes. The default value is basic.

• full: Displays a full view of the fileset
• basic: Displays name, status, path, and ID.
• long: Displays name, fs_name, id, root_inode, status, path, parent_id, create_time, comment, inode_space, is_inode_space_owner, max_inodes, alloc_inodes, inode_space_mask, iam_mode, fal_status, perm_inherit_flag, perm_change_flag, prevent_snapshot_restore, and inode_space_designation.
• attributes: Displays basic view of the fileset, root_inode, parent_id, create_time, comment, inode_space, max_inodes, alloc_inodes, perm_change_flag, iam_mode, perm_inherit_flag, and inode_space_designation.

link {FilesystemName} {FilesetName}

Links an existing IBM Storage Scale fileset. Creates a junction that references the root directory of afileset.

A junction is a special directory entry, similar to a POSIX hard link, that connects a name in a parent fileset directory to the root directory of a child fileset. From a user's perspective, a junction always appears as a directory. However, users cannot remove a junction using the unlink or rmdir commands. To remove a junction, use unlink. If you don’t specify a junction, it is created in the current directory with the name FilesetName. You can use the mv command to move the directory to a new location within the parent fileset. However, you cannot use mv to move the junction to a different fileset.

To run this command, you must have the RBAC permission for the link action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{fileset_name}:link resource.

-J or --junction-path <string>

Specifies the junction path that references the root directory of the fileset name. If not specified, the junction is created in current directory using fileset name.

list {FilesystemName}

Lists file sets in an IBM Storage Scale file system. The operation attributes for this command are LRO, fields and pagination operation. To run this command, you must have the RBAC permission for the get action on the /scalemgmt/v3/filesystems/{filesystem}/filesets resource.

--all-domains

Runs the list request against all possible domains that the user has access.

-n or --max-items {MaxItemNumber}

Specifies the maximum number of items to list at a time.

-x or --no-pagination

Disables subsequent pagination tokens on the client side.

-p or --page-size {PageSize}

Specifies the number of items to list per API request.

-t or --page-token {PageToken}

Specifies the page token that is received from previous file system list command. You can provide this page token to retrieve the next page.

--view {full | basic | long | attributes}

Specifies the view for fileset contents. The default value is basic.

• full: Displays a full view of the fileset
• basic: Displays name, status, path, and ID.
• long: Displays name, fs_name, id, root_inode, status, path, parent_id, create_time, comment, inode_space, is_inode_space_owner, max_inodes, alloc_inodes, inode_space_mask, iam_mode, fal_status, perm_inherit_flag, perm_change_flag, prevent_snapshot_restore, and inode_space_designation.
• attributes: Displays basic view of the fileset, root_inode, parent_id, create_time, comment, inode_space, max_inodes, alloc_inodes, perm_change_flag, iam_mode, perm_inherit_flag, and inode_space_designation.

snapshot

Creates and manages a fileset snapshot.

batchCreate {FilesystemName}

Creates one or more fileset snapshots. You can delete the fileset snapshots only by using scalectl fileset snapshot delete or scalectl fileset snapshot batchDelete command. The operation attribute for this command is LRO. To run this command, you must have the RBAC permission for the create action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/snapshots:batchCreate resource. For more information, see Fileset-level snapshots.

-I or --input {FilesetName:snapshot1[,FilesetName:snapshot2]}

Specifies the snapshots to create.

batchDelete {FilesystemName}

Specifies to batch delete one or more fileset snapshots. The operation attribute for this command is LRO. To run this command, you must have the RBAC permission for the delete action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/snapshots:batchDelete resource. For more information, see Fileset-level snapshots.

-I or --input {FilesetName:snapshot1[,FilesetName:snapshot2]}

Specifies the snapshots to be created.

--pit-continues-on-error

Continues removing the remaining files, if errors are encountered in the parallel inode traverse (PIT) phase that does the user file deletion.

-N or --target-nodes {Node[,Node...]}

Specifies a list of target IBM Storage Scale nodes. The value can include any combination of node numbers, node number ranges, node names, IP addresses, or node classes.

create

Creates a fileset snapshot at a single point of time. The snapshot does not copy system data or existing snapshots. This function enables backup or mirroring programs to run concurrently with user updates while ensuring a consistent copy of the fileset at the time of creation. Snapshots also serve as an online backup solution, allowing for easy recovery from common issues, such as accidental file deletion, and enabling comparisons with previous file versions.

A fileset snapshot is an exact copy of the changed data in the active files and directories of an independent fileset and all dependent filesets. Fileset snapshots are read only and appear in the .snapshots directory that is located in the root directory of the fileset. The files and attributes of the fileset can be modified only in the active copy.

To delete a fileset snapshot, use scalectl fileset snapshot delete or scalectl fileset snapshot batchDelete.

The operation attribute for this command is LRO. To run this command, you must have the RBAC permission for the create action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{filesets}/snapshots resource.

For more information, see Fileset-level snapshots.

--expiration-time {YYYY-MM-DDTHH:MM:SSZ}

Specifies the expiration time of the snapshot in RFC 3339 format [YYYY-MM-DDTHH:MM:SSZ].

-n or --name {SnapshotName}

Specifies the name of the snapshot.

delete {FilesystemName} {FilesetName} {SnapshotName}

Deletes a fileset snapshot. After deleting successfully, the snapshot is marked for deletion and cannot be recovered.

If the node from which delete is issued or the file system manager node fails, the snapshot might not be fully deleted. The list or get subcommand displays these snapshots with a status of DeleteRequired. To complete the deletion, reissue delete subcommand from another node, or allow the snapshot to be automatically removed by a later scalectl fileset snapshot delete command. A snapshot in this state cannot be accessed.

Any open files in the snapshot are forcibly closed. The user receives an ESTALE error on the next file access.

If a snapshot contains file clones, you must delete the file clones or split them from their clone parents before deleting the snapshot. Use the mmclone split or mmclone redirect command to split file clones. Use a regular delete (rm) command to delete a file clone. If a snapshot containing a clone parent is deleted, any attempt to read a block that references the missing snapshot returns an error. A policy file can be created to help determine whether a snapshot contains file clones.

The operation attribute for this command is LRO. To run this command, you must have the RBAC permission for the create action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{filesets}/snapshots/{snapshot_name} resource.

--pit-continues-on-error

Continues removing the remaining files, if errors are encountered in the PIT phase that does the user file deletion.

-N or --target-nodes {Node[,Node...]}

Specifies a list of target IBM Storage Scale nodes. The value can include any combination of node numbers, node number ranges, node names, IP addresses, or node classes.

get {FilesystemName} {FilesetName} {SnapshotName}

Retrieves information for a fileset snapshot. The operation attributes for this command are LRO and fields. To run this command, you must have the RBAC permission for the get action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{filesets}/snapshots/{snapshot_name} resource.

Note: For snapshots that are created without the retention period defined, the expiration time is the same as its creation time.

--fast

Enables a faster method to calculate the storage used by the snapshot, reducing system performance impact.

--pit-continues-on-error

Continues removing the remaining files, if errors are encountered in the parallel inode traverse (PIT) phase that does the user file deletion.

--view {basic | data}

specifies the view for snapshot contents. The possible values are basic and data. The default value is basic.

list {FilesystemName} {FilesetName}

Lists fileset in an IBM Storage Scale file system. The operation attributes for this command are LRO, fields and pagination. To run this command, you must have the RBAC permission for the get action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{filesets}/snapshots resource.

• full: Displays a full view of the fileset
• basic: Displays name, status, path, and ID.
• long: Displays name, fs_name, id, root_inode, status, path, parent_id, create_time, comment, inode_space, is_inode_space_owner, max_inodes, alloc_inodes, inode_space_mask, iam_mode, fal_status, perm_inherit_flag, perm_change_flag, prevent_snapshot_restore, and inode_space_designation.
• attributes: Displays basic view of the fileset, root_inode, parent_id, create_time, comment, inode_space, max_inodes, alloc_inodes, perm_change_flag, iam_mode, perm_inherit_flag, and inode_space_designation.

--all-domains

Runs the list request against all possible domains that the user has access.

--fast

Specifies to enable a faster way of calculating the amount of storage that is used by the snapshot, minimizing the impact on the performance of the system.

-n or --max-items {MaxItemNumber}

Specifies the maximum number of items to list at a time.

-x or --no-pagination

Disables pagination tokens on the client side.

-p or --page-size {PageSize}

Specifies the number of items to list per API request.

-t or --page-token {PageToken}

Specifies the page token that is received from previous file system list command. You can provide this page token to retrieve the next page.

--view

Specifies the view for fileset contents. The possible values are full, basic, long, and attributes. The default value is basic.

unlink {FilesystemName} {FilesetName}

Unlinks an existing fileset. Removes the junction to an IBM Storage Scale fileset. The operation attribute for this command is LRO. To run this command, you must have the RBAC permission for the unlink action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{fileset_name}:unlink resource.

-f

Forces unlinking even if files are open. Open files will be forcibly closed, causing an estale error on the next file access.

update {FilesystemName} {FilesetName}

Updates an existing fileset. The operation attributes for this command are LRO and update mask. To run this command, you must have the RBAC permission for the update action on the /scalemgmt/v3/filesystems/{filesystem}/filesets/{fileset_name} resource.

--allow-permission-change {chmodAndSetAcl | chmodOnly | setAclOnly | chmodAndUpdateAcl}

Specifies the new permission change mode. The possible values are nondetachable, chmodOnly, setAclOnly, and chmodAndUpdateAcl. The default value is chmodAndSetAcl.

--allow-permission-inherit {inheritAclOnly | inheritAclAndAddMode}

Specifies the new permission inherit mode. The possible values are inheritAclOnly and inheritAclAndAddMode\. The default value is "inheritAclOnly".

-t or --comment {Comment}

Specifies a comment for the fileset.

--iam-mode {off | advisory | noncompliant | compliant | compliant-plus}

Specifies the IAM mode for the fileset. The possible values are off, advisory, noncompliant, compliant and compliant-plus. The default value is off.

--inode-limit {InodeLimit}

Specifies the inode limit for the inode space that is owned by the fileset. The value must be an int character.

--inode-space {InodeSpace}

Specifies the inode space for the fileset.

-J or --junction-path {JunctionPath}

Specifies the name of the junction.

-n or --name {FilesetName}

Specifies the name of the fileset.

--pre-alloc-inodes {NumInodes}

Specifies the number of inodes to preallocate for the fileset. This flag is only valid when specified together with the --inode-limit.

usage {FilesystemName} {FilesetName}

Retrieves the fileset inode usage, data usage, or both.

--view {data-usage | inode-usage | full}

Specifies the view for displaying usage. The possible values are data-usage, inode-usage, and full. The default value is data-usage.

quota

Manages quota operations for a fileset, including listing quota information, setting quota limits, and checking inode and space usage for users and groups.

list {FilesystemName} {FilesetName}

Lists user and group quota information for a fileset. The operation attributes for this command are fields and pagination.

-d or --default

Lists default user and group quota limits.

--fields {FieldNames}

Restricts the output to the specified fields. Supported field names include type, id, name, block_usage_bytes, block_soft_limit_bytes, block_hard_limit_bytes, block_in_doubt_bytes, block_grace, file_usage, file_soft_limit, file_hard_limit, file_in_doubt, file_grace, entry_type, and fileset.

-n or --max-items {MaxItemNumber}

Specifies the maximum number of items to list at a time.

-x or --no-pagination

Disables pagination tokens on the client side.

-p or --page-size {PageSize}

Specifies the number of items to list per API request.

-t or --page-token {PageToken}

Specifies the page token that is received from a previous quota list command. Provide this token to retrieve the next page.

set {FilesystemName} {FilesetName}

Sets quota limits for a user, group, or fileset.

--block-hard-limit {BlockHardLimit}

Specifies the hard limit for block usage.

--block-soft-limit {BlockSoftLimit}

Specifies the soft limit for block usage.

-d or --default

Sets default quota limits for user and group quota types.

--file-hard-limit {FileHardLimit}

Specifies the hard limit for file usage.

--file-soft-limit {FileSoftLimit}

Specifies the soft limit for file usage.

-n or --name {Name}

Specifies the name of the user, group, or fileset, depending on the value of --quota-type.

check {FilesystemName} {FilesetName}

Counts inode and space usage for users and groups in a fileset and writes the collected data into quota files.

--qos-class {QoSClass}

Specifies the Quality of Service (QoS) class for I/O operations. If not specified, the command is assigned to the maintenance QoS class. This parameter has no effect unless the QoS service is enabled.

-v or --report-diff

Reports discrepancies between calculated and recorded disk quotas.

-N or --target-nodes {Node[,Node...]}

Specifies a list of target IBM Storage Scale nodes. The value can include node numbers, node number ranges, node names, IP addresses, or node classes.

--threads {ThreadCount}

Specifies the number of threads that are created to run the command. The default value is 16.

-V or --verbose

Displays additional information that can be used for debugging.

Global flags

Exit status

0

Successful completion.

nonzero

A failure occurred.

Security

You must have the specific role-based access control (RBAC) permission to run the command. For more information, see Role-based access control.

See also

Location

/usr/lpp/mmfs/bin