Manage KPS using the kpsadmin tool

The kpsadmin command-line tool provides KPS managment functions, independent of data source. For example, this includes KPS data backup, restore, and encryption. This topic explains how to use the kpsadmin tool in interactive and scriptable command modes.

The kpsadmin tool is especially useful in a development environment. In a production environment, you should also use data source-specific tools and administration procedures for data backup, restore, security, optimization, monitoring and so on.

Caution   You must use kpsadmin operations with caution. Ensure that you have a verified backup before you run destructive operations such as clear, restore, and re-encrypt. You should always try out these options in a development environment first.

For an example of using Cassandra storage, see Perform essential Cassandra operations in the API Gateway Installation Guide.

Start kpsadmin

From a command prompt, enter kpsadmin. For example:

Windows

UNIX

If you do not specify a command operation (for example, kpsadmin backup or restore), kpsadmin enters its default interactive menu mode. For details on available operations in scriptable command mode, see Run kpsadmin operations in scriptable command mode.

In default interactive mode, you are first prompted to enter your admin credentials to authenticate to the Admin Node Manager. These are the credentials that you supplied when installing API Gateway. For more details, see the API Gateway Installation Guide.

Start in verbose mode

To run kpsadmin in verbose mode, use the -v option. kpsadmin will then show all REST messages that are exchanged with the API Gateway. This is useful for debugging. For example:

For details on available options, enter kpsadmin -h, or see kpsadmin command options.

Select kpsadmin operations in interactive mode

This section describes the kpsadmin operations that are available in default interactive mode. When you first select an operation in interactive mode, you must enter the following:

  • API Gateway group to use
  • KPS Admin API Gateway in that group that handles KPS requests.
Note   kpsadmin requires you to specify an API Gateway in a group. This is known as the KPS Admin API Gateway, which fields KPS requests only. Any API Gateway in the group can be used. For example, you might change this if you want to check that data is available from any API Gateway in the group.
  • KPS collection to use in the group
  • KPS table to use in the collection

You can change this selection at any time.

KPS table operations

The kpsadmin table operations are as follows:

KPS table administration operations

The kpsadmin operations for table administration are as follows:

KPS collection administration operations

The kpsadmin operations for collection administration are as follows:

API Gateway group administration operations

The kpsadmin operations for API Gateway group administration are as follows:

Cassandra administration operations

The kpsadmin operations for Cassandra administration are as follows:

General administration operations

The kpsadmin operations for general administration are as follows:

Example of switching a data source in interactive mode

This example shows how to switch from Cassandra storage to file storage.

Step 1: Backup collection data using kpsadmin

To copy the current data in the collection to the new data source, back up the collection data using kpsadmin option 21) Backup All.

The backup UUID is highlighted in the following example:

kpsadmin Backup All operation

Step 2: Create a new data source

To create the new data source, perform the following steps:

  1. In the Policy Studio tree, select Key Property StoresSamples.
  2. Select  the collection Data Sources tab.
  3. Click Add > Add File at the bottom right.

KPS collection Data Sources tab

  1. Enter a file data source Name and Description.
  2. Enter a Directory Path (for example, ${VINSTDIR/kps/samples).
Tip   You can include ${VINSTDIR} or ${VDISTDIR} to indicate the API Gateway instance directory or install directory respectively. Make sure to use \ on Windows or / on UNIX. If the directory does not exist, it is automatically created.
  1. Select  the collection Properties tab.
  2. Change the collection Default data source to use the new data source:

Step 3: Deploy the configuration

Click the Deploy button in the Policy Studio toolbar.

Step 4: Restore collection data using kpsadmin

If you made a backup in step 1, to restore the collection data, perform the following steps:

  1. Using kpsadmin, select option 22) Restore All.
  2. Enter the backup UUID noted in step 1. For example:

Run kpsadmin operations in scriptable command mode

You can also control kpsadmin directly from the command line or from a script by specifying command operations (for example, kpsadmin backup or restore). If an operation is not specified, kpsadmin enters its default interactive menu mode. You must also specify a username/password, and an API Gateway group, KPS collection, or KPS table. For example:

kpsadmin command operations

The available kpsadmin command operations in this mode are:

If this kind of kpsadmin command invocation succeeds, 0 is returned. If it fails, 1 is returned. This can be captured on Linux bash shell and Windows powershell using $? (for example, echo $? will work on both platforms). On Linux, 0 means success, 1 means error. On Windows, True means success, False means error.

Note   Username and password can be specified on the command line or using a secure script.

For details on how to script username and password input for API Gateway scripts, see the managedomain command reference in the API Gateway Administrator Guide.

kpsadmin command options

The full kpsadmin command options are:

Example kpsadmin scriptable commands

This section shows some example kpsadmin operations in scriptable command mode.

Back up and restore

To back up and restore an API Gateway group from a staging environment to a production environment, perform the following steps:

  1. Specify the kpsadmin backup command:
  2. You must copy the files from the staging backup directory to the production backup directory and note the UUID. This is output by kpsadmin and is also a prefix on the exported filenames.
  3. Specify the kpsadmin clear command:
  4. Specify the kpsadmin restore command with the UUID noted earlier:

Re-encrypt KPS data

After an encryption passphrase change and deployment, you must re-encrypt the KPS data. To re-encrypt at the group level:

You are prompted to enter the passphrase. For more details, see Re-encrypt KPS data.

Show KPS table details

To show table details:

Show KPS collection details

To show collection details:

Show Apache Cassandra configuration

To show Cassandra configuration:

Re-encrypt KPS data

You can use the kpsadmin re-encrypt option to re-encrypt previously encrypted KPS data. When you use this option, a backup of the data is first made in the following directory:

The data is decrypted with the old encryption passphrase, which you must supply. The data is then re-encrypted with the current encryption passphrase, which the API Gateway already knows.

Caution   You must use the re-encrypt option only when:
  • The encryption passphrase has been changed for an API Gateway group configuration.
  • This change has been deployed to all API Gateways in the group.
  • You see INFO messages in all API Gateway trace logs as follows:
Note   You should re-encrypt the data using the group-level 28) Re-encrypt All interactive option, or the kpsadmin --group reencrypt scriptable command. Do not use the table or collection level re-encrypt options. These should only be used if group level encryption fails. You will then need to re-encrypt at collection and/or table level.

After re-encryption, you must restart all API Gateways in the group.

Related Links