In the previous article, we examined the context around OneFS changelists and the ChangelistCreate job. Next, let’s step through an example of creating and managing a simple changelist via the OneFS CLI.
Here’s a basic procedure:
- First, create a directory (ifs/data/test1) and add couple of files:
# mkdir -p -v /ifs/data/test1 # echo f1 > /ifs/data/test1/f1 # echo f2 > /ifs/data/test1/f2
- Next, take a snapshot of the directory:
# isi snap snaps create /ifs/data/test1
- Modify the data (edit f1, remove f2, add f3):
# echo f1 >> /ifs/data/test1/f1 # rm /ifs/data/test1/f2 # echo f3 > /ifs/data/test1/f3
- Take a second snapshot:
# isi snap snaps create /ifs/data/test1
- View the snapshot ID’s:
# isi snap snaps ls ID Name Path ------------------------ 3 s3 /ifs/data/test1 5 s5 /ifs/data/test1 ------------------------ Total: 2
- Start a ChangelistCreate job using the two snapshot IDs above, and allow it to run to completion. Once the job no longer appears in the ‘isi job jobs ls’ command output, you know it’s done:
# isi job jobs start ChangelistCreate --older-snapid 3 --newer-snapid 5 Started job [3] # isi job jobs ls ID Type State Impact Pri Phase Running Time --------------------------------------------------------------- 3 ChangelistCreate Running Low 5 2/4 9s --------------------------------------------------------------- Total: 1
Once the job no longer appears in the ‘isi job jobs ls’ command output, you know it’s done:
# isi job jobs ls ID Type State Impact Pri Phase Running Time ------------------------------------------- ------------------------------------------- Total: 0
- List all the cluster’s changelists:
# isi_changelist_mod -l 3_5
- Describe all the changelists:
# isi_changelist_mod -i –all name=3_5 num_entries=4 owner=3 path=/ifs/data/test1
- Display all the entries in the new changelist (in this case, 3_5):
# isi_changelist_mod -a 3_5 st_ino=4297195572 st_mode=040755 st_size=40 st_atime=1429572712 st_mtime=1429572712 st_ctime=1429572712 st_flags=224 cl_flags=00 path=/ifs/data/test1 st_ino=4297261063 st_mode=0100644 st_size=6 st_atime=1429572699 st_mtime=1429572699 st_ctime=1429572699 st_flags=224 cl_flags=00 path=/ifs/data/test1/f1 st_ino=4297261065 st_mode=0100644 st_size=3 st_atime=1429572712 st_mtime=1429572712 st_ctime=1429572712 st_flags=224 cl_flags=01 path=/ifs/data/test1/f3 st_ino=4297261064 st_mode=0100644 st_size=3 st_atime=1429572687 st_mtime=1429572687 st_ctime=1429572687 st_flags=224 cl_flags=02 path=/ifs/data/test1/f2
- Display all the entries with by path only & with added and removed prefixes (+/-):
# isi_changelist_mod -a 3_5 --p --v /ifs/data/test1 /ifs/data/test1/f1 +/ifs/data/test1/f3 -/ifs/data/test1/f2
- Delete (or kill, -k) the new changelist:
# isi_changelist_mod -k 3_5
In addition to the CLI, the OneFS PlatformAPI (pAPI) can also be used to programmatically interact with changelists. Here are the associated API methods available.
| pAPI Changelist Method | Description |
| /snapshot/changelists | List all changelists. |
| /snapshot/changelists/<CHANGELIST> | Retrieve basic information on a changelist. |
| /snapshot/changelists/<CHANGELIST>/diff-regions/<LIN> | Get snap diff regions of a file. |
| /snapshot/changelists/<CHANGELIST>/entries | Get entries from a changelist. |
| /snapshot/changelists/<CHANGELIST>/entries/<ID> | Get a single entry from the changelist by ID. |
| /snapshot/changelists/<CHANGELIST>/lins | Get entries from a changelist. |
| /snapshot/changelists/<CHANGELIST>/lins/<LIN> | Get a single entry from the changelist by LIN. |
For example, to retrieve all changelists on the local node:
# curl -k -v -X GET --header "Content-Type:application/json" -u <username>:<password> https://localhost:8080/platform/1/snapshot/changelists
Additionally, the Job Engine API methods can be used to interface with the ChangelistCreate job.
| pAPI Job Method | Description |
| /job/events | List job events. |
| /job/job-summary | View job engine status. |
| /job/jobs | List running and paused jobs.Queue a new instance of a job type. |
| /job/jobs/<JID> | View a single job instance.Modify a running or paused job instance. |
| /job/policies | List job impact policies.Create a new job impact policy. |
| /job/policies/<NAME> | View a single job impact policy.Modify/delete a job impact policy. |
| /job/recent | List recently completed jobs. |
| /job/reports | List job reports. |
| /job/statistics | View job engine statistics. |
| /job/types | List job types. |
| /job/types/<NAME> | Retrieve job type information.Modify the job type. |
For example, to start a job:
# curl https://localhost:8080/platform/1/job/jobs -k -u <username>:<password> -v --data '{"type": "ChangelistCreate", "changelistcreate_params" : {"older_snapid" : 2, "newer_snapid" : 6}}'
Here’s an example of the PlatformAPI XML changelist output for an added file (file1).
{
"atime": {
"nsec": 0,
"sec": 1612177389
},
"btime": {
"nsec": 0,
"sec": 1612177389
},
"change_types": [
"ENTRY_ADDED"
],
"ctime": {
"nsec": 0,
"sec": 1612177389
},
"data_pool": -3,
"file_type": "regular",
"gid": 0,
"id": "68723787424",
"lin": 4295236714,
"metadata_pool": -3,
"mtime": {
"nsec": 0,
"sec": 1612177389
},
"parent_lin": 4295163972,
"path": "/ifs/data/test1/file1",
"physical_size": 512,
"size": 0,
"uid": 0,
"user_flags": [
"uarch",
"inherit",
"writecache",
"wcinherit",
"shasntfsacl"
]
}
Changelist data is stored in an STF system B-Tree (SBT), where the key to the SBT is the ID field. The keys are stored in ascending order, and iteration of an SBT occurs in ascending key order. Changelist entries are returned in ascending order by ID in the different clients. Changelists are indexed in ascending order by ID field. The ID field is based partially on LIN and operation (plus some additional bits to allow for operations on the N links of a file).
The correlation between ID field and LIN in the XML output above is as follows:
Decimal Hexadecimal "id": "68723787424", 100041C6A0 "lin": 4295236714, 100041C6A
In each instance, the difference between ID and LIN in hexadecimal notation is the addition of a trailing 0 to the 9-digit LIN value to make a 10-digit ID.
So in older pAPI output (ie. OneFS 8.x), where only the ID is displayed, the LIN can be calculated from the ID.
Unlink operations will appear at the end of a changelist based on sort order.
Be aware that the platformAPI call /platform/*/snapshot/changelists/<CHANGELIST>/lins has been deprecated and is replaced by /platform/*/snapshot/changelists/<CHANGELIST>/entries.
Logging for changelist creation (Job Engine) can be found in /var/log/isi_job_d.log.