Product Documentation

Appearance

keystore ​

Set up and manage the keystore for the encrypted drives.

keystore backup
keystore backup list 
keystore lock
keystore restore <filename>
keystore rotate
keystore setup [ force ]
keystore status
keystore unlock
keystore backup

Back up the keystore to the /tmp directory. After backing up the keystore, move the backup file from the manager node to a safe and secure external storage server. Do not copy it to another location on the appliance. Any keys left on the manager node under /tmp for more than 10 days will be automatically deleted.

The keystore restore command, if you need to use it, expects the file to be in its original location, so you will need to secure-copy the backup file back to /tmp at that time. Keystore backup files are very small and have a timestamped name.

For example:

YBCLI (PRIMARY)> keystore backup

Are you sure you want to back up the keystore to: /tmp/ ?
NOTE: During the backup, the database remains online and users can run queries.
After the backup, you have to unlock the keystore before you can run any encryption commands.

Type yes to continue: yes

Stopping the keystore service before backup. Standby...  Done
Backing up keystore. Standby... Done
Starting the keystore service after backup. Standby...  Done

The keystore has been backed up successfully to:
	/tmp/ybd-ks-08-09-2019-19-41-23.tar.gz
Please copy the backup to another machine. The backup is located on this system at:
	yb00-mgr0.yellowbrick.io:/tmp/ybd-ks-08-09-2019-19-41-23.tar.gz
	MD5: 4d56f07d6dcba20c6bceb0495448f842


Do you want to unlock the keystore (not required)?

Type yes to continue: no
Keystore will not be unlocked

Note: Whenever the keystore is modified in response to encryption enable and encryption rotate operations, a keystore backup happens automatically.

keystore backup list

List all the keystore backups that exist on the system:

YBCLI(26168) (PRIMARY - yb100-mgr1)> keystore backup list

The following Yellowbrick keystore backups exist on this system:
	Yellowbrick keystore backup: /tmp/ybd-ks-08-06-2019-17-36-50.tar.gz
	Yellowbrick keystore backup: /tmp/ybd-ks-08-05-2019-19-08-15.tar.gz
	Yellowbrick keystore backup: /tmp/ybd-ks-08-05-2019-16-40-01.tar.gz
	Yellowbrick keystore backup: /tmp/ybd-ks-08-06-2019-11-21-02.tar.gz
keystore lock

Lock the keystore. Locking the keystore prevents encryption commands from being run until it has been unlocked; however, locking the keystore does not change the encryption status on the system. If encryption was enabled when you locked the keystore, encryption remains enabled.

YBCLI (PRIMARY)> keystore lock

Authenticating to the keystore for this YBCLI session. Standby...
Please enter keystore authentication key: 
Key -> 

Key accepted. This session is authenticated for the next 10 minutes or until YBCLI exits.
Successfully locked the keystore
keystore restore <filename>

Restore the keystore from a backup. Before running the command, secure-copy the backup file from its external location to the /tmp directory on the active manager node. Enter the name of the backup file to be restored. You can display a list by running the keystore backup list command.

Do not specify a path in the command, just the filename, and do not use quotes around the filename. The expected path to the backup file is /tmp on the manager node. After restoring, you have to unlock the keystore. For example:

YBCLI (PRIMARY)> keystore restore ybd-ks-08-09-2019-19-41-23.tar.gz

Are you sure you want to restore the keystore using:
	/tmp/ybd-ks-08-09-2019-19-41-23.tar.gz

NOTE: During the restore, the database remains online and users can run queries.

Type yes to continue: yes

Stopping the keystore service before restore. Standby...  Done
Verifying backup. Standby... Done
Restoring. Standby... Done
Starting the keystore service after restore. Standby...  Done

The keystore has been restored successfully using:
	/tmp/ybd-ks-08-09-2019-19-41-23.tar.gz

Do you want to unlock the keystore again (not required)?

Type yes to continue: no
Not unlocking keystore after restore
keystore rotate

Generate new unlock keys and a new authentication key for the keystore. You cannot generate unlock keys or the authentication key separately. For example:

YBCLI(63867) (PRIMARY - yb00-mgr0)> keystore rotate
 
Rotating the keystore will generate new authentication and unlock keys.
Note: A backup of the current keystore will be performed prior to rotating the keystore.
Keystore rotation requires both the authentication and unlock keys to be present.
 
Do you want to rotate the keystore?
Response (yes/no): yes
 
Stopping the keystore service before backup. Standby...  Done
Backing up keystore. Standby... Done
Starting the keystore service after backup. Standby...  Done
 
The keystore has been backed up successfully to:
       /tmp/ybd-ks-01-02-2020-08-26-14.tar.gz
Please copy the backup to another machine. The backup is located on this system at:
       yb00-mgr0.yellowbrick.io:/tmp/ybd-ks-01-02-2020-08-26-14.tar.gz
       MD5: 31724b6a57a4a788f47b5541b6012345
 
Please enter an unlock key to begin unlocking the keystore: 
Key -> 
 
Keystore was successfully unlocked
 
Authenticating to the keystore for key rotation. Standby... 
Please enter keystore authentication key: 
Key -> 
 
Rotating the keystore. Standby... 
 
Note: You can request up to 5 keystore unlock keys. In this way, multiple administrators can unlock the keystore
using a combination of keys. No single key has to be distributed to a single administrator.
 
How many unlock keys should be generated for the keystore? (1 to 5): 1
1 key will be required to unlock the keystore
 
The following unlock key(s) were generated. A total of 1 key(s) is required to unlock the keystore:
New keystore unlock key 1: 86fdbd9599bb83c732e3c4eeab2d47a1c6325c85d1c72547c4f61a13da212345
 
Rotating new authentication key. Standby... 
New authentication key: c5e9efb6-401a-1da1-43f3-00aba2e12345
 
Keys have been generated. Please store them in a safe place.
 
Do you want to create a backup of the keystore?
Response (yes/no): yes
 
Stopping the keystore service before backup. Standby...  Done
Backing up keystore. Standby... Done
Starting the keystore service after backup. Standby...  Done
 
The keystore has been backed up successfully to:
       /tmp/ybd-ks-01-02-2020-08-32-23.tar.gz
Please copy the backup to another machine. The backup is located on this system at:
       yb00-mgr0.yellowbrick.io:/tmp/ybd-ks-01-02-2020-08-32-23.tar.gz
       MD5: 4ab76751319fc490ad8c5104a9aa41ac
 
 
Do you want to unlock the keystore (not required)?
Response (yes/no): no
Keystore will not be unlocked
 
Keystore rotation successfully completed

For an example with three unlock keys, see Example: Rotate the Keystore with Multiple Unlock Keys.

This command does not generate new encryption keys for the drives; see the encryption rotate command.

keystore setup

Set up a new keystore on a system that will use encrypted drives. You cannot enable encryption until the keystore is created. The keystore setup command generates a set of keys:

  • A single 36-byte authentication key, which is a required "password" that you have to enter before you can run any encryption commands.
  • One or more 64-byte keys to unlock the keystore

At least one of each type of key is required.

Note: You can request up to 5 unlock keys. In this way, multiple administrators can unlock the keystore at different times using a combination of keys. No single key has to be distributed to a single administrator.

During the setup, you will be prompted to run a backup of the keystore; this is a recommended part of the procedure.

For detailed examples, see Example: Set Up the Keystore and Enable Encryption and Example: Use Multiple Unlock Keys.

keystore setup force

CAUTION:

This command erases all of the drive keys in the keystore, then re-creates it. Read the command output on the screen carefully before proceeding.

If encryption is not enabled on any of the drives, you are safe to proceed. If encryption is enabled, all data on the encrypted drives will be lost unless you can restore the keystore from a backup. If you cannot restore the keystore, each encrypted drive will have to be manually unlocked by using the key printed on its label. All data will be lost. See Example: Force Keystore Setup.

keystore status

Show whether the keystore is locked or unlocked. For example:

YBCLI (PRIMARY)> keystore status

keystore status
Locked: NO
keystore unlock

Unlock the keystore. You must enter one or more 64-byte unlock keys, depending on the number of keys that were specified when the keystore was set up.

YBCLI (PRIMARY)> system keystore unlock

Please enter the first key to unlock the keystore: 
Key -> 

Verifying keystore status. Standby...
Keystore locked: NO

Keystore was successfully unlocked

Parent topic:ybcli Reference