scalectl afm command

Performs Active File Management (AFM) control operations for filesets through the scalectl interface.

Synopsis

scalectl afm checkdirty FileSystemName FilesetName [--dir-path Path] [--dirty-data] [--escaped-chars]

or

scalectl afm checkuncached FileSystemName FilesetName [--check-unmigrated] [--dir-path Path] [--escaped-chars]

or

scalectl afm flushqueue FileSystemName FilesetName

or

scalectl afm getfileset FileSystemName FilesetName

or

scalectl afm listfileset FileSystemName

or

scalectl afm resetlocal FileSystemName FilesetName --file-path FilePath

or

scalectl afm resumerequeued FileSystemName FilesetName

or

scalectl afm resync FileSystemName FilesetName

or

scalectl afm setlocal FileSystemName FilesetName --file-path FilePath

or

scalectl afm start FileSystemName FilesetName

or

scalectl afm stop FileSystemName FilesetName

Availability

Available on all IBM Storage Scale editions.

Description

The scalectl afm command provides AFM control operations through the scalectl interface. This command enables management of AFM filesets including checking fileset state, flushing queues, performing resync operations, and controlling replication.

AFM read-only mode is referred to as RO, single-writer mode as SW, independent-writer mode as IW, and local-update mode as LU.

For more information, see Active File Management.

Parameters

checkdirty FileSystemName FilesetName
Finds all dirty files and directories for an existing AFM fileset state. This option is available for AFM SW, IW, LU, and primary modes, and AFM to cloud object storage filesets. This option generates two separate files that contain a list of dirty files and dirty directories, which are not yet synchronized from the cache to the home or cloud object storage and are marked as dirty on the cache.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.
--dir-path Path
Specifies a path under the AFM cache fileset or AFM-enabled file system where the checkdirty command needs to be run. This parameter is optional.
--dirty-data
When used with the checkdirty option, it does not print the list of dirty files and directories. Instead, it prints the total amount of data (in bytes) inside the AFM fileset which is dirty and not yet synchronized with the home or cloud object storage. This parameter runs a query to find all the dirty data that exists inside the AFM fileset linked paths.
--escaped-chars
Handles escaped characters in the output file names. Use this option when file names contain special characters that need to be properly escaped in the output.
checkuncached FileSystemName FilesetName
Finds all uncached files and directories for an existing AFM fileset state. This option is available for AFM RO, SW, IW, and LU modes, and AFM to cloud object storage filesets. This option generates two separate files that contain a list of uncached files and uncached directories. The list contains data that is not brought to the cache from the home or cloud object storage.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.
--check-unmigrated
Checks the migration status of data from the source to the AFM-enabled fileset or file system. When used with the checkuncached option, AFM internally runs a policy to collect the data which is not fully migrated to the cache. When the policy run is completed, this command displays the list of non-migrated directories, files, and orphans list file, if it exists. This option is available for AFM RO and LU mode filesets.
--dir-path Path
Specifies a path under the AFM cache fileset or AFM-enabled file system where the checkuncached command needs to be run. This parameter is optional and used with the --check-unmigrated option.
--escaped-chars
Handles escaped characters in the output file names. Use this option when file names contain special characters that need to be properly escaped in the output.
flushqueue FileSystemName FilesetName
Flushes all pending queued operations for an existing AFM fileset. This operation forces the immediate processing of queued updates to the home or target, ensuring that all pending changes are synchronized.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.
getfileset FileSystemName FilesetName
Describes an existing AFM fileset state, displaying detailed status information including cache state, gateway node, queue length, and statistics.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.
listfileset FileSystemName
Lists the state of all existing AFM filesets in a file system.
FileSystemName
Specifies the file system name.
resetlocal FileSystemName FilesetName
Resets the local bit for a specified file path in an existing AFM fileset.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.
--file-path FilePath
Specifies a path under an AFM fileset on which reset or set pcache attrs needs to be performed.
resumerequeued FileSystemName FilesetName
Resumes all pending requeued operations for an existing AFM fileset.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.
resync FileSystemName FilesetName
Performs a resync operation for a single-writer mode AFM fileset.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.
setlocal FileSystemName FilesetName
Sets the local bit for a specified file path in an existing AFM fileset.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.
--file-path FilePath
Specifies a path under an AFM fileset on which reset or set pcache attrs needs to be performed.
start FileSystemName FilesetName
Starts operations for a stopped AFM fileset.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name. The fileset must be in stopped state.
stop FileSystemName FilesetName
Stops all operations for an existing AFM fileset.
FileSystemName
Specifies the file system name.
FilesetName
Specifies the AFM fileset name.

Global flags

Use the following global flags with any scalectl command and subcommand:
--bearer
If true, reads the OIDC_TOKEN from the environment and sends it as the authorization bearer header for the request. Use this flag with the --url option.
--user-cert {Certificate}
Specifies the path to the client certificate file for authentication.
--user-cacert {CA_Certificate}
Specifies the path to the certificate authority (CA) trust chain to validate a server certificate.
--debug {Filepath[="stderr"]}
Enables the debug logging for the current request. Accepts an absolute file path to store logs by using --debug=<file>. If no file path is specified, logs are sent to stderr.
-h or --help
Lists the help for scalectl commands.
--domain {DomainName}
Sets the domain for the request. The default value is StorageScaleDomain.
--insecure-skip-tls-verify
If true, skips to verify the server certificate for validity. This option makes HTTPS connections insecure.
--json
Displays output in JSON format.
Note: When you use the --json flag with an endpoint method that is a long-running operation (LRO), the LRO is submitted to the LRO manager, which handles its lifecycle. The lifecycle includes accepting, running, and monitoring operations. Although the command request returns quickly, you must ensure that the submitted operation reaches a Done state. Review any metadata that is associated with the request to ensure that it completed successfully. This step is especially important for endpoint methods that have follow-on methods. These follow-on methods are valid only if the initial method completed successfully. For more information about LRO, see Long-running operations.
--user-key {PrivateKeyFile}
Specifies the path to the client certificate private key file for authentication.
--url {ip_address}
Sends the request over HTTPS to the specified endpoint <FQDN/IP>:<port>. For IPv6 address, use square brackets. For example, [IPv6]:<port>. If no port specified, 46443 is used by default.
--version
Specifies the scalectl build information. The --version flag is valid only with the top-level scalectl command.

Exit status

0
Successful completion.
nonzero
A failure occurred.

Security

You must have root authority or be a member of the admin group to run the scalectl afm command.

Examples

  1. To flush all pending queued operations for an AFM fileset, issue the following command: 
    scalectl afm flushqueue fs1 primary-fset-sw
    A sample output is as follows:
    Running job 'MToxOTdjOTc1YS1mODhlLTQ4M2MtYTUzNC1kZDYyMjVjOTk4MTQ='
    Use the scalectl afm getfileset command to verify the fileset state and confirm that the queue length is reduced or cleared after the operation completes.
  2. To get detailed state of an AFM fileset, issue the following command: 
    scalectl afm getfileset fs1 primary-fset-iw
    A sample output is as follows:
    Fileset Name    Fileset Target                                Cache State          Gateway Node    Queue Length   Queue numExec
------------    --------------                                -------------        ------------    ------------   -------------
primary-fset-iw nfs://601-sanity1/gpfs/fs1/secondary1         Active               afm-sanity2     0              12
  3. To list all AFM filesets in a file system, issue the following command: 
    scalectl afm listfileset fs1
    A sample output is as follows:
    Fileset Name    Fileset Target                                Cache State          Gateway Node    Queue Length   Queue numExec 
------------    --------------                                -------------        ------------    ------------   ------------- 
hptTestPlan-021026220615-HPT-TC22-Writer https://scaleafm.blob.core.windows.net:443/cosbkt-tc22-021026220615 Inactive
hptTestPlan-021026220615-HPT-TC22-ro https://scaleafm.blob.core.windows.net:443/cosbkt-tc22-021026220615 Inactive
hptTestPlan-021026220615-HPT-TC22-mu https://scaleafm.blob.core.windows.net:443/cosbkt-tc22-021026220615 Inactive
hptTestPlan-021026220615-HPT-TC22-mu-ro https://scaleafm.blob.core.windows.net:443/cosbkt-tc22-021026220615 Inactive
hptTestPlan-021026220615-HPT-TC22-iw https://scaleafm.blob.core.windows.net:443/cosbkt-tc22-021026220615 Inactive
hptTestPlan-021026220615-HPT-TC22-iw-ro https://scaleafm.blob.core.windows.net:443/cosbkt-tc22-021026220615 Inactive
hptTestPlan-021026220615-HPT-TC22-sw https://scaleafm.blob.core.windows.net:443/cosbkt-tc22-021026220615 Inactive
hptTestPlan-021026220615-HPT-TC22-sw-ro https://scaleafm.blob.core.windows.net:443/cosbkt-tc22-021026220615 Inactive
fset-sw         https://scaleafm.blob.core.windows.net:443/test-mos-bucketnew Inactive
fset-mu         https://scaleafm.blob.core.windows.net:443/test-mos-bucketnew Inactive

hptBVT-260303-220333-HPT-TC9-RO https://scaleafm.blob.core.windows.net:443/cosbkt-tc9-030326224743 Inactive
primary-fset-iw nfs://601-sanity1/gpfs/fs1/secondary1         Active               afm-sanity2     0              12
  4. To reset local bit for a file to enable synchronization, issue the following command: 
    scalectl afm resetlocal fs1 primary-fset-sw --file-path /gpfs/fs1/primary-fset-sw/file5
    A sample output is as follows:
    local bit reset for the filepath '/gpfs/fs1/primary-fset-sw/file5'
    Verify the local bit is reset by issuing the following command:
    tspcacheutil /gpfs/fs1/primary-fset-sw/file5
    A sample output is as follows:
    
inode: ino=24194056 gen=790538442 uid=0 gid=0 size=2097152 mode=0200100644 nlink=1
       ctime=1768553825.816156227 mtime=1768553825.816156227
       cached 1  hasState 1  local 0  rename 0
       create 0  setattr  0  dirty 0 copy 0  link 0  append 0
pcache: parent ino=24117251 foldval=0xF8896B4E nlink=1
remote: ino=95422469 size=2097152 nlink=1 fhsize=48 version=0
        ctime=1773996439.893929743 mtime=1768553825.816156227name 0
  5. To resume requeued operations after resolving conflicts, issue the following command: 
    scalectl afm resumerequeued fs1 primary-fset-sw
    The command returns no output. Use the scalectl afm getfileset command to verify the fileset status.
  6. To perform resync operation for single-writer mode, issue the following command: 
    scalectl afm resync fs1 primary-fset-sw
    A sample output is as follows:
    Running job 'MTowNWMyOTIxNy04NzljLTQzZDItODg3ZC04NGJiYWEyOTdjYzQ='
Performing resync of fileset: primary-fset-sw
  7. To set local bit for a file to prevent synchronization, issue the following command: 
    scalectl afm setlocal fs1 primary-fset-sw --file-path /gpfs/fs1/primary-fset-sw/file5
    A sample output is as follows:
    local bit set for the filepath '/gpfs/fs1/primary-fset-sw/file5'
    Verify the local bit is reset by issuing the following command:
    tspcacheutil /gpfs/fs1/primary-fset-sw/file5
    A sample output is as follows:
    
inode: ino=24194056 gen=790538442 uid=0 gid=0 size=2097152 mode=0200100644 nlink=1
       ctime=1768553825.816156227 mtime=1768553825.816156227
       cached 1  hasState 1  local 1  rename 0
       create 0  setattr  0  dirty 0 copy 0  link 0  append 0
pcache: parent ino=24117251 foldval=0xF8896B4E nlink=1
remote: ino=95422469 size=2097152 nlink=1 fhsize=48 version=0
        ctime=1773996439.893929743 mtime=1768553825.816156227
  8. To start a stopped AFM fileset, issue the following command: 
    scalectl afm start fs1 primary-fset-sw
    The command returns no output. Use the scalectl afm getfileset command to verify the fileset status.
  9. To stop an AFM fileset for maintenance, issue the following command: 
    scalectl afm stop fs1 primary-fset-sw
    The command returns no output. Use the scalectl afm getfileset command to verify the fileset status.
  10. To check for dirty files in an AFM fileset, issue the following command: 
    scalectl afm checkdirty fs1 primary-fset-iw
    A sample output is as follows:
    Running job 'MTo3ZjU2YjRkMC0wMGYxLTQ1Y2YtOTBlYy01ZGVhZGVlZTQ1Nzg='
Checking dirty files/directories. This may take a while...
Dirty Files list : /var/mmfs/scaleadm/afm/fs1-primary-fset-iw/checkdirty/dirtyFiles
  11. To check for uncached files in an AFM fileset, issue the following command: 
    scalectl afm checkuncached fs1 fset-mu
    A sample output is as follows:
    Verifying whether all the data is cached. This may take a while...
Uncached Files list : '/var/mmfs/scaleadm/afm/fs1-fset-mu/checkuncached/uncachedFiles'
    View the list of uncached files by displaying the contents of the file that is specified in the command output. For example: 
    cat
/var/mmfs/scaleadm/afm/fs1-fset-mu/checkuncached/uncachedFiles
    A sample output is as follows:
    /gpfs/fs1/fset-mu/file1

See also

Location

/usr/lpp/mmfs/bin/scalectl