Filesystems/{filesystemName}/filesets/{filesetName}/afmctl: POST

Sets the control values for Active File Management (AFM).

Availability

Available on all IBM Storage Scale editions.

Description

The POST filesystems/{filesystemName}/filesets/{filesetName}/afmctl request defines the attributes that control the AFM function of a specific fileset. For more information about the fields in the request data structures, see the topics mmafmctl command, mmafmconfig command, and mmafmlocal command.

Request URL

https://<IP address or host name of API server>:<port>/scalemgmt/v2/filesystems/{filesystemName}/filesets/{filesetName}/afmctl
where
filesystem/filessystemName
Specifies the file system in which the fileset is present. Required.
filesets/filesetName/afmctl
Specifies the fileset for which the AFM controls are to be defined. Required.

Request headers

Accept: application/json

Request parameters

The following parameters can be used in the request URL to customize the request:
Table 1. List of request parameters
Parameter name Description and applicable keywords Required/optional
filesystemName The file system name. You can also use keywords such as :all:, :all_local:, or :all_remote: Required.
filesetName The fileset name. This is the path of the fileset. Required.
body Body of the request that contains the required parameters to be passed on to the IBM Storage Scale system to perform the requested operation. Required.

Request data

 {
          "failback": 
          {
          "action": "Start | Stop",
          "failoverTime": "Failover time",
          },
        "failoverToSecondary": .,
          {
          "restore": "Restore type",
          }, 
          "failover": {
    "newTarget": "Target URL ",
    "targetOnly": true | false
          },
        "convertToPrimary": 
          {
          "afmtarget": "Target fileset",
          "inband": "Inband",
          "secondarySnapName": "Secondary snap name",
          "noCheckMetadata": "Yes | No",
          "rpo": "RPO interval",
          },
"convertToSecondary": 
          {
          "primaryid": "ID",
          "force": "Yes | No",
          },
"changeSecondary": 
          {
          "newTarget": "New target fileset",
          "inband": "Inband",
          "targetOnly": "Target-only",
          },
"replacePrimary": "Replace primary fileset",
"failbackToPrimary": 
          {
          "action": "Start | Stop",
          "force": "Yes | No",
          },
 "applyUpdates": "Apply updates",
 "prefetch": { 
  "policy": True | False,
  "gatewayNode":"Name of the Node",
  "getnThreads":Integer value,
  "force ":True |False,
  "enableFailedFileList":True | False,
  "metaDataOnly":True |False,
  "listFile": "File path location",
  "dirListFile": "File path location",
  "homeFileSystemPath": "File path location
  },
  "evict": {
  ""evictOptions"":{
   "fileName": "The name of the file",
   "minFileSize": "file size",
   "maxFileSize": "file size",
   } ,
    "safeLimit": "The safe limit",
    "logFile ": " Eviction Log file name,
    "listfile": "File name"
 }      
 }
Details of the parameters are given in the following list:
"failback":
"action": "Start | Stop"
The failback action to be performed.
"failoverTime": "Failover time"
Specifies the failover time.
"failoverToSecondary":
"restore": "Restore type"
Specifies the restore type.
"failover"
newTarget : "Target URL"
Specifies the name and path of the new home server. This path replaces the server details that were originally defined in the afmtarget parameter of the mmcrfileset command.
"targetOnly" : true | false
Specifies whether the mount path or IP address of the target path is changed. Do not use this option to change the target location or the protocol. The new NFS server must be in the same home cluster and must display the same architecture as the existing NFS server in the target path.
"convertToPrimary":
"afmtarget": "Target fileset"
Target fileset for the AFM operation.
"inband": "Inband"
Used for inband trucking. Inband trucking is the process of copying the data while the primary-secondary relationship from GPFS fileset is set up, where the primary site has contents and the secondary site is empty.
"secondarySnapName": "Secondary snap name"
Used while a new primary is established for an existing secondary or acting as the primary during failback.
"noCheckMetadata": "Yes | No"
Used if one needs to proceed with conversion without checking for append-only or immutable files.
"rpo": "RPO interval"
Specifies the RPO interval in minutes for the primary fileset.
"convertToSecondary":
"primaryid": "ID",
Specifies the ID of the primary with which the secondary is associated.
"force": "Yes | No",
If convertToSecondary failed or got interrupted, it does not create afmctl file at the secondary. In such scenarios, rerun the command with the --force option.
"changeSecondary":
"newTarget": "New target fileset"
Specifies a new home server and path, replacing the home server and path that is originally set.
"inband": "Inband"
Used for inband trucking. Inband trucking is the process of copying the data while a primary-secondary relationship from GPFS fileset is defined, where the primary site has contents and the secondary site is empty.
"targetOnly": "Target-only"
Used when you want to change the IP address or NFS server name for the same target path. The new NFS server must be in the same home cluster and must be of the same architecture (power or x86) as the existing NFS server in the target path. This option can be used to move from NFS to a mapping target.
"replacePrimary": "Replace primary fileset"
Replace the primary fileset in the AFM relationship.
"failbackToPrimary":
"action": "Start | Stop",
The failback action to be carried out.
"force": "Yes | No",
Used if stop or start does not complete successfully due to any errors, and if it does not allow failbackToPrimary action to stop or start again.
"applyUpdates": "Apply updates",
Whether to apply updates.
"prefetch"
Prefetch the list of files from the home cluster.
"policy":True | False
Specifies whether a GPFS policy is used to generate the list file. The policy helps sequences like '\' or '\n' to be escaped as '\' and '\n' .
"gatewayNode":"Node name"
Specifies the gateway node that can be used to run the prefetch operation on a fileset.
"getnThreads": Integer value
Specifies the number of threads that is to be used for the prefetch operation. The valid values are 1-255 and the default is 4.
"force":True | False
Enables the option to forcefully fetch data from the home cluster during the migration process.
"enableFailedFileList":True | False
Enables the creation of a list of files that failed during the prefetch operation at the gateway node.
"metaDataOnly":True | False
Enables prefetching of only the metadata and not the actual data. This option is useful in migration scenarios. It must be combined with the listFile option.
"listFile': File name and location
Specifies the name and location of the file that comprises the list of files that must be pre-populated. The files are listed one file per line.
"dirListFile":File name and location
Specifies the individual directories under the AFM fileset that must be prefetched.
"homeFileSystemPath":File path location
Specifies the location of the home cluster.
"evict"
The parameters for starting the deallocation of data blocks.
"evictOptions":{
The evict filters.
"fileName": "Name of the file"
The fully qualified name of the file that needs to be evicted.
"minFileSize": Name of the file
Sets the minimum size of a file that can be evicted from the cache.
"maxFileSize": Name of the file
Sets the maximum size of a file that can be evicted from the cache.
"safeLimit": Number of files to be evicted
The list of files that you want to evict. The soft limit creates the benchmark for the target quota limit, which cannot exceed this limit. Each line contains one file. All files must have fully qualified domain names (FQDN).
"logFile":"File name and location"
Specifies the file, which stores the eviction log. By default, an eviction log file is not generated.
"listfile":"File name and location"
Specifies the name and location of the file that comprises the list of files that must be evicted. The files are listed on separate lines and must have fully qualified domain names (FQDN). You need not specify the file system quotas. If the list includes files, which have special characters in their names then you can use a policy to generate the listfile parameter.

Response data

{
   "status": {
      "code":ReturnCode",
      "message":"ReturnMessage"
   },
   "jobs": [
      {
         "result":"", 
           { 
             "commands":"String",
             "progress":"String,
             "exitCode":"Exit code",
             "stderr":"Error",
             "stdout":"String",
           },
         "request":" ",
           {
             "type":"{GET | POST | PUT | DELETE}",
             "url":"URL",
             "data":"",
           }
         "jobId":"ID",
         "submitted":"Time",
         "completed":"Time",
         "status":"Job status",
         }
   ],
  }
For more information about the fields in the following data structures, see the links at the end of the topic.
"jobs":
An array of elements that describe jobs. Each element describes one job.
"status":
Return status.
"message": "ReturnMessage",
The return message.
"code": ReturnCode
The return code.
"result"
"commands":"String"
Array of commands that are run in this job.
"progress":"String"
Progress information for the request.
"exitCode":"Exit code"
Exit code of command. Zero denotes success and any value other than zero denotes failure.
"stderr":"Error"
CLI messages from stderr.
"stdout":"String"
CLI messages from stdout.
"request"
"type":"{GET | POST | PUT | DELETE}"
HTTP request type.
"url":"URL"
The URL through which the job is submitted.
"data":" "
Optional.
"jobId":"ID",
The unique ID of the job.
"submitted":"Time"
The time at which the job was submitted.
"completed":Time"
The time at which the job was completed.
"status":"RUNNING | COMPLETED | FAILED"
Status of the job.

Examples

The following example creates and links a fileset cos1 in file system fs1.

Request data: 
curl -k -u admin:admin001 -X POST --header 'content-type:application/json' 
--header 'accept:application/json' -d '{ \ 
  "failback": {
    "action": "start",
    "failoverTime": "10"
  },
  "failoverToSecondary": {
    "restore": true
  },
  "failover": {
    "newTarget": "gpfs:///afmr/remote_homeFS/gpfs_home_iw_0",
    "targetOnly": true
  },
  "convertToPrimary": {
    "afmtarget": "nfs://9.11.102.209/gpfs/fs0/nfs-ganesha1",
    "inband": true,
    "secondarySnapName": "Snap1",
    "noCheckMetadata": true,
    "rpo": "true"
  },
  "convertToSecondary": {
    "primaryid": "88888888",
    "force": true
  },
  "changeSecondary": {
    "newTarget": "nfs://9.11.102.209/gpfs/fs0/nfs-ganesha1",
    "inband": true,
    "targetOnly": true
  },
  "replacePrimary": {},
  "failbackToPrimary": {
    "action": "start",
    "force": true
  },
  "applyUpdates": {},
  "prefetch": {
    "policy": true,
    "gatewayNode": "Node2",
    "force": true,
    "enableFailedFileList": true,
    "metaDataOnly": true,
    "listFile": "/tmp/file1",
    "dirListFile": "/tmp/file1",
    "homeFileSystemPath": "/gpfs/remotefs1",
    "threadsCount": 4
  },
  "evict": {
    "evictOptions": {
      "fileName": " /gpfs/fs1/ro2/file10M_1",
      "minFileSize": " ",
      "maxFileSize": "string"
    },
    "safeLimit": 1,
    "logFile": "/gpfs/fs1/log",
    "listfile": "/tmp/file-list"
  },
} ' 'https://198.51.100.1:443/scalemgmt/v2/filesystems/fs1/filesets/cos1/afmctl'
Response data: 
{
  "jobs": [
    {
      "jobId": 1000000000001,
      "status": "COMPLETED",
      "submitted": "2022-04-01 09:14:03,035",
      "completed": "2022-04-01 09:14:04,262",
      "runtime": 1227,
      "request": {
        "type": "POST",
        "url": "/scalemgmt/v2/filesystems/fs1/filesets/cos1/afmctl"
      },
      "result": {
        "progress": [],
        "commands": [
          "mmafmctl 'fs1' evict -j 'cos1' --safe-limit 1 --filter 'FILENAME=file1' "
        ],
        "stdout": [
          "mmafmctl: 0.0000 soft-limit should be > 0",
          "info: "
        ],
        "stderr": [],
        "exitCode": 0
      },
      "pids": []
    }
  ],
  "status": {
    "code": 200,
    "message": "The request finished successfully."
  }
}