Creating OneFS Changelists

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:

  1. 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
  1. Next, take a snapshot of the directory:
# isi snap snaps create /ifs/data/test1
  1. 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
  1. Take a second snapshot:
# isi snap snaps create /ifs/data/test1
  1. View the snapshot ID’s:
# isi snap snaps ls

ID   Name  Path        


3    s3    /ifs/data/test1

5    s5    /ifs/data/test1


Total: 2
  1. 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
  1. List all the cluster’s changelists:
# isi_changelist_mod -l

  1. Describe all the changelists:
# isi_changelist_mod -i –all 

name=3_5 num_entries=4 owner=3 path=/ifs/data/test1
  1. 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

  1. Display all the entries with by path only & with added and removed prefixes (+/-):
# isi_changelist_mod -a 3_5 --p --v




  1. 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": [



            "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": [








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.

Leave a Reply

Your email address will not be published. Required fields are marked *