Running recursive prefetch on the AFM cache RO-mode fileset system (new system)

Migrate all the data to the AFM RO-mode file system to the new system.
```
mmafmctl Device prefetch
```
After the cache is ready, prepare the AFM RO-mode cache file system for prefetch.
Prefetch of data is performed recursively, until all data is prefetched and cached on the cache site.
You can prefetch the data by using options such as --directory, --dir-list-file, --list-file, --home-list-file, --home-inode-file with the mmafmctl command. For more information, see mmafmctl command.
To simplify the migration process, it is recommended to use the --directory and --list-file options with the mmafmctl prefetch command recursively to generate a list and queue them to the gateway node to migrate the data to the new system.
Migration of whole data might be outlined for directories, subdirectories, and files, then they can be prefetched recursively so that most of the data is migrated from the home to the cache. To prefetch data from the home to the cache, issue the mmafmctl command by using the --directory and --list-file options.
Note: When you are generating a list file, remove any occurrence of root directory such as “.” or “..” from the generated list file. This special file entry must not be prefetched and must be removed from the list file. Otherwise, the prefetch marks this file as a failed file and logs an error in the /var/adm/ras/mmfs.log file.
To find all the subdirectories and files in the specified directory recursively, use the --directory option. When this option is used, all the subdirectories and files belong to the directory are queued to the gateway node to migrate to the cache.
Prefetch of data needs to be planned as per the priority, which data to be pulled first in the cache (the new system).
- If there are some unchanged or cold data directories on the home, then those directories can be pulled before rest of the data.
```
mmafmctl fs1 prefetch -j ro1 --directory /gpfs/fs1/ro1/cold1 --prefetch-threads=8
```
  A sample output is as follows:
```
mmafmctl: Performing prefetching of fileset: ro1
mmafmctl(2024-11-13 04:15:55): Listing all files of directory /gpfs/fs1/ro1/cold1
Queued ( Processed) Failed TotalData
(approx in Bytes)
0 ( 202) 0 0
0 ( 303) 0 0
0 ( 606) 0 0
0 ( 1111) 0 0
0 ( 2121) 0 0
0 ( 4141) 0 0
1408 ( 5385) 0 0
prefetch successfully queued at the gateway.
mmafmctl(2024-11-13 04:17:23): Listed all files of directory /gpfs/fs1/ro1/cold1
```
  Note: Here, the directory path is determined beforehand so that prefetch will be performed on the unchanged data first. This will reduce the number of iterations to pull the data. Also, the prefetch-threads can be determined based on the resources available on the gateway node.
To specify a list of files, use the --list-file option. The list of files can be generated at the old system or the new system by running a find command or GPFS mmapplypolicy command. By running either command on the new system, AFM sends a readdir operation to the old system and migrates the directory tree structure to the new system, however, it does not migrate data. When the list file is available, run the following command:
```
mmafmctl FileSystem prefetch -j fileset --enable-failed-file-list --list-file List-file-path
```
A sample output is as follows:
```
mmafmctl: Performing prefetching of fileset: <fileset>
Queued (Total) Failed TotalData (approx in Bytes)
0 (56324) 0 0
5 (56324) 2 1353559
56322 (56324) 2 14119335
```
These stats/counters are shown while the command is running. The command exits after the prefetch statistics is shown.
Specify the --enable-failed-file-list option to generate a list of all files that failed and are not prefetched at the new system during this operation. This option helps in case any of the files was not prefetched because of an error such as network disconnect or intermittent failure. You can retry to prefetch only the failed files by using a failed-file list, which is generated internally.
The files from an old system are prefetched in the following two phases:
- Phase 1: AFM first collects the information of all files that needs to be prefetched and queues them on the gateway node.
- Phase 2: When the files are queued on the gateway node, the gateway node runs the prefetch from the old system to the new system.
The failed-file list is generated only if any file that was successfully queued to the gateway node but failed during the prefetch to the new system, that is, Phase 2. The failed file is not generated during the queuing phase 2. AFM collects the failed file list under /tmp and prints the new path when the remaining files are queued.
Example:
```
mmafmctl fs1 prefetch -j ro1 --list-file /home/list-file --enable-failed-file-list
```
```
mmafmctl fs1 prefetch -j ro1 --directory /gpfs/fs1/ro1/dir1 --enable-failed-file-list
```
Prefetch the failed files by using the --retry-failed-file-list option.
During the prefetch operation, if any of the files failed to prefetch from the old system, then this the failed file entry is added to a special file. This special file is created under the AFM RO-1 fileset, for example, /gpfs/fs1/ro1/.afm/.prefetchedfailed. You can retry prefetch operation to prefetch only the failed files by using the following command:
```
mmafmctl fs1 prefetch -j ro1 --retry-failed-file-list
```
If the list file is generated by running a GPFS mmapplypolicy command, then you can specify the --policy option to the mmafmctl command so that the sequences such as '\' is converted into '\\' or '\n' is converted into '\\n'. If this option is specified, it is assumed that the input file list contains already escaped path names. The path of each file is unescaped before the file is queued to the gateway node for the prefetch operation.
```
mmafmctl fs1 prefetch -j RO-1 --list-file List-file-path --enable-failed-file-list --policy
```

Checking the status of a prefetch task

Check the progress of data that is pulled to the AFM cache file system by running the following commands:

Check whether the prefetch task is completed.

mmafmctl fs1 prefetch -j ro1

A sample output is as follows:

mmafmctl: Statistics of last or currently running prefetch are as follows
Fileset  Async          Async            Async                 Async         Async 
Name     Read (Pending) Read (Failed)   Read (Already Cached)  Read (Total)  Read (Data in Bytes)
------- --------------- -------------- ----------------------- ------------- -------------------------
ro1     0               0               723                     1844         1147904

where, the pending data is showing ‘0’, which means the prefetch task is complete.

Add a callback to check the prefetch status.
Create a file that will be executed after the prefetch task is completed.
```
/usr/lpp/mmfs/bin/mmaddcallback prefetchEnd --command /root/prefetch_callback.sh 
--event afmPrepopEnd --parms '%eventName %fsName %filesetName %prepopCompletedReads %prepopData'
```
where, the /root/prefetch_callbach.sh file created with the execution permission.

Checking the data status on the AFM cache fileset (the new system)

After the prefetch is completed, you can run a simple check to find whether the specified file is prefetched or uncached.

mmafmctl fs1 checkUncached -j ro1

A sample output is as follows:

mmchfileset(2024-11-11 09:40:54): Listing all uncached files of directory /gpfs/fs1/ro1
Verifying if all the data is cached. This may take a while...
mmchfileset: [E] Uncached files present, run prefetch first
Orphans list file: /var/mmfs/tmp/cmdTmpDir.mmchfileset.451980/orphan-file.mmchfileset.451980

Run the prefetch command recursively to pull uncached directories or file list to migrate it to the AFM fileset (new system).
Note:
- After every prefetch, wait until the file data is flushed to the disk. The data flushing to the disk might take a few seconds.
- Before running the final cutover, ensure that all data is prefetched to the cache after the last modification of data by the application on the home or source side.
- If required, AFM can still provide one last prefetch to pull selected data after the cutover by setting the afmRefreshOnce and afmReaddirOnce parameter on the RO fileset to pull data but one last time.
- After the last prefetch, AFM disconnects the link between AFM RO-mode fileset and the source or home export by converting the RO-mode fileset to the LU-mode fileset.
- Applications can be moved to the AFM cache (new system).