Recording patches in the Platform System Manager patches database

When a patch is applied to any component in Cloud Pak System Software (for example, to the PSM, IWD, Storwize® V7000, etc), a new record in the Platform System Manager (PSM) patches database should be created from the command line. These commands must be run only from the leader Platform System Manager.

The psmpatches.json file

The information is stored in the psmpatches.json file, which is stored in /data/system/config/psmpatches/<v.r.m.f>/psmpatches.json.

Note: <v.r.m.f> is Version number, Release number, Modification number, and Fix Pack number. For example, 2.3.4.0.

The psmpatches.json file is structured like a tree:

The top level is a list of components (iwd, psm, etc). The names of the components can be any value the installer chooses.
Within each component is a list of APARs.
- Underneath each APAR is the installer who applied the patch, the date the patch was applied, and a comment on why the patch was applied.

The following example shows a psmpatches.json file with 3 entries:

{
"iwd": {
  "IT23382": {
    "installer": "johndoe@ibm.com",
    "comment": "List of Virtual System Instances is empty",
    "date": "2018-02-20,21:08:42"
    },
  "IT23104": {
    "installer": "johndoe@ibm.com",
    "comment": "Fix for cloning of VMs with added NICs",
    "date": "2018-02-23,20:57:37"
    }
  },
"psm": {
  "IT22278": {
    "installer": "janeroe@ibm.com",
    "date": "2018-01-15,11:06:43",
    "comment": "Disk Add-On failure"
    }
  }
}

Required permissions

To run the list, add and delete commands that use the CLI option require PSM shell access. A user with Hardware administration role with permission to View hardware resources (Read-only) can issue a GET REST API to list the records. Only the IBM_CE (ibmeng) user is allowed to create a psmpatches record by using the REST API channel. The delete record is not available by using the REST API command.

CLI definition

Add a record

Format:

psmpatches add -c component -i installer [-a apar] [-x (comment|@/fullpath/filename)]

This method submits a request to create a new PSM patches record. This method accepts the following parameters:

component: Required. Specify the component where the patch is installed. Component names can be any string chosen by the installer. For example, pureapp, iwd, or v7k.
installer: Required. Specify the user who installed the patch. This value will typically be SWAT Engineer's name@ibm.com.
apar: Optional. Specify the APAR that is associated with the patch. If no APAR value is specified, a placeholder APAR number is generated with the format: "APAR"+new Date().format("yyyyMMddHHmmss"). For example, APAR20171228141327
comment: Optional. Specify a comment about the patch, if needed. If you specify a comment, it must be the last option on the command. If it is specified as @/fullpath/filename, the contents of the file are used for the text of the comment, with all newlines concatenated into one string.

Notes:

The date is automatically added to the JSON file and is stored in the file in the format: yyyy-MM-dd,HH:mm:ss.
If you add a new patch for a (component, apar) pair that is already in the patches file, the existing record is deleted.

Delete a record

Format:

psmpatches delete -c component -a apar

This method submits a request to delete a PSM patches record, based on the specified component and APAR. This method accepts the following parameters:

component: Required. Specify the component where the patch is installed.
apar: Required. Specify the APAR that is associated with the patch.

List PSM patches records

Format:

psmpatches list [-c component] [-a apar]

This method submits a request to return the contents of the specified PSM patches records, based on the specified component and APAR. This method accepts the following parameters:

component: If specified, the patches that are returned are for only this component.
apar: If specified, only the patches that are associated with this APAR are returned.

REST API commands

Return the set of all patches that are applied to the specified PSM:

GET https://<ip address of the PSM>/admin/resources/psmpatches

Return the complete record of the patch, filtered by component=X and apar=Y, if specified:

GET
    https://<ip address of the PSM>/admin/resources/psmpatches?[component=X][&apar=Y]

Create a new patch record. If no APAR is specified, a placeholder APAR number is generated with the format: "APAR"+new Date().format("yyyyMMddHHmmss"). It returns the body that was generated to create the record.

POST https://<ip address of the PSM>/admin/resources/psmpatches

A sample request representation is provided in the following example.

{"component": "vmware",
"apar": "IT12346",
"installer": "user@in.ibm.com",
"comment": "Fix cloning of VMs with manually added NICs"
}

Command line examples

Initially there is no patch file:

[root@localhost cli]# ls /data/config/psmpatches
ls: cannot access /data/config/psmpatches: No such file or directory

Asking for a list of patches returns a message:

[root@localhost cli]# psmpatches list
GET http://localhost:5001/admin/resources/psmpatches
Response: rc: 200 body: "No patch file exists at location /data/system/config/psmpatches/<v.r.m.f>/psmpatches.json."

Add a patch using the command line:

[root@localhost cli]# psmpatches add -c iwd -a IT20697 -i johndoe@ibm.com -x Fix cloning of VMs with manually added NICs
POST [component:iwd, installer:johndoe@ibm.com, apar:IT20697, comment:Fix cloning of VMs with manually added NICs]
Response: rc: 201 body: {
   "component": "iwd",
   "installer": "johndoe@ibm.com",
   "apar": "IT20697",
   "comment": "Fix cloning of VMs with manually added NICs",
   "date": "2018-02-23,21:31:28"
}

List the patches that are installed on the system using the command line (one patch exists):

[root@localhost cli]# psmpatches list
GET http://localhost:5001/admin/resources/psmpatches
Response: rc: 200 body: {
   "iwd": {
      "IT20697": {
         "installer": "johndoe@ibm.com",
         "comment": "Fix cloning of VMs with manually added NICs",
         "date": "2018-02-23,21:31:28"
      }
   }
}

After you add a patch, you will see that the psmpatches.json file was created:

[root@localhost cli]# ls /data/config/psmpatches/*
/data/system/config/psmpatches/<v.r.m.f>/psmpatches.json

Add another patch to a different component, without an APAR number:

[root@localhost cli]# psmpatches add -c psm -i janeroe@ibm.com -x New TLS libraries applied
POST [component:psm, installer:janeroe@ibm.com, comment:New TLS libraries applied]
Response: rc: 201 body: {
   "component": "psm",
   "installer": "janeroe@ibm.com",
   "apar": "APAR20180223213635",
   "comment": "New TLS libraries applied",
   "date": "2018-02-23,21:36:35"
}

List the patches that are installed on the system using the command line. Now there are 2 entries for 2 different components:

[root@localhost cli]# psmpatches list
GET http://localhost:5001/admin/resources/psmpatches
Response: rc: 200 body: {
   "iwd": {
      "IT20697": {
         "installer": "johndoe@ibm.com",
         "date": "2018-02-23,21:31:28",
         "comment": "Fix cloning of VMs with manually added NICs"
      }
   },
   "psm": {
      "APAR20180223213635": {
         "installer": "janeroe@ibm.com",
         "comment": "New TLS libraries applied",
         "date": "2018-02-23,21:36:35"
      }
   }
}

Delete a patch that is installed on the system using the command line::

[root@localhost cli]# psmpatches delete -c psm -a APAR20180223213635
DELETE http://localhost:5001/admin/resources/psmpatches/xxx?component=psm&apar=APAR20180223213635
Response: rc: 200 body: {
   "component": "psm",
   "installer": "janeroe@ibm.com",
   "comment": "New TLS libraries applied",
   "date": "2018-02-23,21:36:35",
   "apar": "APAR20180223213635"
}

The patch record is now gone:

[root@localhost cli]# psmpatches list
GET http://localhost:5001/admin/resources/psmpatches
Response: rc: 200 body: {
   "iwd": {
      "IT20697": {
         "installer": "johndoe@ibm.com",
         "comment": "Fix cloning of VMs with manually added NICs",
         "date": "2018-02-23,21:31:28"
      }
   },
   "psm": {
   }
}