CLI cookbook: Locating and updating the value of tdeKeyIdentifier

This topic describes how to manage the tdeKeyIdentifier field that is associated with the vPDB or the vCDB source object using the command-line interface.

This process is currently supported only via the CLI.

The following example lists the procedure for a vPDB source object. For a vCDB source object, similar steps need to be followed.

Procedure

1. Log into the Delphix command-line interface using the admin user or a user with admin privileges.

   CODE

   $ ssh admin@YOUR_ENGINE

2. Move to the database.

   CODE

   delphix> source
   delphix source> "VCDO_1JL"

3. View all the settings using the "ls" command.

   CODE

   delphix source "VCDO_1JL" *> ls
   Properties
       type: OracleVirtualPdbSource
       name: VCDO_1JL
       allowAutoVDBRestartOnHostReboot: false
       allowRefreshRewindPostV2P: false
       archivelogMode: true
       config: VCDO_1JL
       configParams:
           _bct_public_dba_buffer_size: 1826784
           _cdb_disable_pdb_limit: TRUE
           audit_file_dest: '/u01/app/oracle/admin/CDOMLOSR197/adump'
           audit_trail: 'DB'
           compatible: '19.0.0'
           core_dump_dest: '/u01/app/oracle/diag/rdbms/cdomlosr197/CDOMLOSR197/cdump'
           diagnostic_dest: '/u01/app/oracle'
           dispatchers: '(PROTOCOL=TCP) (SERVICE=CDOMLOSRCA1DXDB)'
           enable_pluggable_database: TRUE
           log_archive_format: '%t_%s_%r.dbf'
           max_pdbs: 4098
           memory_max_target: 1342177280
           memory_target: 1342177280
           nls_language: 'AMERICAN'
           nls_territory: 'AMERICA'
           open_cursors: 300
           processes: 300
           remote_login_passwordfile: 'EXCLUSIVE'
       configTemplate: (unset)
       container: VCDO_1JL
       customEnvVars: (empty)
       linked: false
       logCollectionEnabled: false
       mountBase: /mnt/provision
       newDBID: false
       nodeListeners: (empty)
       operations:
           type: VirtualSourceOperations
           configureClone: (empty)
           postRefresh: (empty)
           postRollback: (empty)
           postSnapshot: (empty)
           postStart: (empty)
           postStop: (empty)
           preRefresh: (empty)
           preRollback: (empty)
           preSnapshot: (empty)
           preStart: (empty)
           preStop: (empty)
       parentTdeKeystorePassword: ********
       parentTdeKeystorePath: /u01/app/oracle/keystores/CDOMLOSR197/wallet
       redoLogGroups: 3
       redoLogSizeInMB: 50
       reference: ORACLE_VIRTUAL_PDB_SOURCE-2
       runtime:
           type: OraclePDBSourceRuntime
           accessible: true
           accessibleTimestamp: 2021-10-06T22:02:15.718Z
           activeInstances:
               0:
                   type: OracleActiveInstance
                   hostName: ip-10-110-234-67.delphix.com
                   instanceName: CDOMLOSR197
                   instanceNumber: 1
           databaseMode: READ_WRITE
           databaseRole: PRIMARY
           databaseSize: 913.4MB
           databaseStats: [ ... ]
           enabled: ENABLED
           lastNonLoggedLocation: 0
           status: RUNNING
       runtimeMountInformation:
           type: UnixRuntimeMountInformation
           name: (unset)
           nfsVersion: 4
           nfsVersionReason: DEFAULT
       staging: false
       status: DEFAULT
       tdeExportedKeyFileSecret: ********
       tdeKeyIdentifier: AbSP7gninU+Gv1YQ/iEcJAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
       tdeUUID: a3f26971-1df6-4c81-994f-4b2c582ded87
       virtual: true
   Operations
   update
   enable
   disable
   start
   stop
   upgrade

4. Note that tdeKeyIdentifier is one of the last fields listed above. If we query the vPDB via sqlplus on the target host, we can see the matching key_id.
   Note that any key generated by Delphix will include a tag with the format dlpx_key_<tdeUUID>.

   CODE

   SQL> alter session set container=VCDO_1JL;
   Session altered.
   SQL> select key_id, tag from v$encryption_keys;
   KEY_ID
   ------------------------------------------------------------------------------
   TAG
   --------------------------------------------------------------------------------
   AbSP7gninU+Gv1YQ/iEcJAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
   dlpx_key_a3f26971-1df6-4c81-994f-4b2c582ded87

5. To generate a new unique encryption key, unset the value of tdeKeyIdentifier before a refresh or rewind operation.

   CODE

   delphix source 'VCDO_1JL'> update 
   delphix source 'VCDO_1JL' update *> unset tdeKeyIdentifier
   delphix source 'VCDO_1JL' update *> ls
   Properties
       type: OracleVirtualPdbSource
       name: VCDO_1JL 
       allowAutoVDBRestartOnHostReboot: false
       allowRefreshRewindPostV2P: false
       customEnvVars: (empty)
       logCollectionEnabled: false
       newDBID: false
       operations:
           type: VirtualSourceOperations
           configureClone: (empty)
           postRefresh: (empty)
           postRollback: (empty)
           postSnapshot: (empty)
           postStart: (empty)
           postStop: (empty)
           preRefresh: (empty)
           preRollback: (empty)
           preSnapshot: (empty)
           preStart: (empty)
           preStop: (empty)
       parentTdeKeystorePassword: ********
       parentTdeKeystorePath: /u01/app/oracle/keystores/CDOMLOSR197/wallet
       tdeKeyIdentifier: (unset) (*)
   delphix source 'VCDO_1JL' update *> commit
       Dispatched job JOB-18
       SOURCE_UPDATE job started for "VCDO_1JL".
       SOURCE_UPDATE job for "VCDO_1JL" completed successfully.

6. After the refresh or rewind, the new key identifier is now associated with vPDB that can be used for all future Delphix operations. View all the settings using the "ls" command.

   CODE

   delphix source 'VCDO_1JL'> ls
   Properties
       type: OracleVirtualPdbSource
       name: VCDO_1JL
       allowAutoVDBRestartOnHostReboot: false
       allowRefreshRewindPostV2P: false
       archivelogMode: true
       config: VCDO_1JL
       configParams:
           _bct_public_dba_buffer_size: 1826784
           _cdb_disable_pdb_limit: TRUE
           audit_file_dest: '/u01/app/oracle/admin/CDOMLOSR197/adump'
           audit_trail: 'DB'
           compatible: '19.0.0'
           core_dump_dest: '/u01/app/oracle/diag/rdbms/cdomlosr197/CDOMLOSR197/cdump'
           diagnostic_dest: '/u01/app/oracle'
           dispatchers: '(PROTOCOL=TCP) (SERVICE=CDOMLOSRCA1DXDB)'
           enable_pluggable_database: TRUE
           log_archive_format: '%t_%s_%r.dbf'
           max_pdbs: 4098
           memory_max_target: 1342177280
           memory_target: 1342177280
           nls_language: 'AMERICAN'
           nls_territory: 'AMERICA'
           open_cursors: 300
           processes: 300
           remote_login_passwordfile: 'EXCLUSIVE'
       configTemplate: (unset)
       container: VCDO_1JL
       customEnvVars: (empty)
       linked: false
       logCollectionEnabled: false
       mountBase: /mnt/provision
       newDBID: false
       nodeListeners: (empty)
       operations: 
          type: VirtualSourceOperations
           configureClone: (empty)
           postRefresh: (empty)
           postRollback: (empty)
           postSnapshot: (empty)
           postStart: (empty)
           postStop: (empty)
           preRefresh: (empty)
           preRollback: (empty)
           preSnapshot: (empty)
           preStart: (empty)
           preStop: (empty)
       parentTdeKeystorePassword: ********
       parentTdeKeystorePath: /u01/app/oracle/keystores/CDOMLOSR197/wallet
       redoLogGroups: 3
       redoLogSizeInMB: 50
       reference: ORACLE_VIRTUAL_PDB_SOURCE-2
       runtime:
           type: OraclePDBSourceRuntime
           accessible: true
           accessibleTimestamp: 2021-10-06T22:17:15.907Z
           activeInstances:
               0:
                   type: OracleActiveInstance
                   hostName: ip-10-110-234-67.delphix.com
                   instanceName: CDOMLOSR197
                   instanceNumber: 1
           databaseMode: READ_WRITE
           databaseRole: PRIMARY
           databaseSize: 913.4MB
           databaseStats: [ ... ]
           enabled: ENABLED
           lastNonLoggedLocation: 0
           status: RUNNING
       runtimeMountInformation:
           type: UnixRuntimeMountInformation
           name: (unset)
           nfsVersion: 4
           nfsVersionReason: DEFAULT
       staging: false
       status: DEFAULT
       tdeExportedKeyFileSecret: ********
       tdeKeyIdentifier: AVEhXrBvmU+Cv+lK6ghT6oMAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
       tdeUUID: a3f26971-1df6-4c81-994f-4b2c582ded87
       virtual: true

7. To specify a user-defined encryption key to be used for future Delphix operations, set tdeKeyIdentifier to the value of a valid key_id in the CDB's keystore. This user-defined encryption key must be activated before updating it from Delphix CLI, otherwise subsequent Delphix operations may fail. Note that if an invalid key_id is provided, refresh or rewind will fail and it will be necessary to unset or update the tdeKeyIdentifier parameter with a valid key_id. Note that this key_id will not have a corresponding dlpx tag unless it is a key previously generated by Delphix.

   CODE

   delphix source 'VCDO_1JL'> update 
   delphix source 'VCDO_1JL' update *> set tdeKeyIdentifier="AbSP7gninU+Gv1YQ/iEcJAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
   delphix source 'VCDO_1JL' update *> ls
   Properties
       type: OracleVirtualPdbSource
       name: VCDO_1JL
       allowAutoVDBRestartOnHostReboot: false
       allowRefreshRewindPostV2P: false
       customEnvVars: (empty)
       logCollectionEnabled: false
       newDBID: false
       operations:
           type: VirtualSourceOperations
           configureClone: (empty)
           postRefresh: (empty)
           postRollback: (empty)
           postSnapshot: (empty)
           postStart: (empty)
           postStop: (empty)
           preRefresh: (empty)
           preRollback: (empty)
           preSnapshot: (empty)
           preStart: (empty)
           preStop: (empty)
       parentTdeKeystorePassword: ********
       parentTdeKeystorePath: /u01/app/oracle/keystores/CDOMLOSR197/wallet
       tdeKeyIdentifier: AbSP7gninU+Gv1YQ/iEcJAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
   delphix source 'VCDO_1JL' update *> commit
       Dispatched job JOB-22
       SOURCE_UPDATE job started for "VCDO_1JL".
       SOURCE_UPDATE job for "VCDO_1JL" completed successfully.

8. After a refresh or rewind, this key identifier will be associated with the vPDB and will be used for all future Delphix operations. View all the settings using the "ls" command.

   CODE

   delphix source 'VCDO_1JL'> ls
   Properties
       type: OracleVirtualPdbSource
       name: VCDO_1JL
       allowAutoVDBRestartOnHostReboot: false
       allowRefreshRewindPostV2P: false
       archivelogMode: true
       config: VCDO_1JL
       configParams:
           _bct_public_dba_buffer_size: 1826784
           _cdb_disable_pdb_limit: TRUE
           audit_file_dest: '/u01/app/oracle/admin/CDOMLOSR197/adump'
           audit_trail: 'DB'
           compatible: '19.0.0'
           core_dump_dest: '/u01/app/oracle/diag/rdbms/cdomlosr197/CDOMLOSR197/cdump'
           diagnostic_dest: '/u01/app/oracle'
           dispatchers: '(PROTOCOL=TCP) (SERVICE=CDOMLOSRCA1DXDB)'
           enable_pluggable_database: TRUE
           log_archive_format: '%t_%s_%r.dbf'
           max_pdbs: 4098
           memory_max_target: 1342177280
           memory_target: 1342177280
           nls_language: 'AMERICAN'
           nls_territory: 'AMERICA'
           open_cursors: 300
           processes: 300
           remote_login_passwordfile: 'EXCLUSIVE'
       configTemplate: (unset)
       container: VCDO_1JL
       customEnvVars: (empty)
       linked: false
       logCollectionEnabled: false
       mountBase: /mnt/provision
       newDBID: false
       nodeListeners: (empty)
       operations:
           type: VirtualSourceOperations
           configureClone: (empty)
           postRefresh: (empty)
           postRollback: (empty)
           postSnapshot: (empty)
           postStart: (empty)
           postStop: (empty)
           preRefresh: (empty)
           preRollback: (empty)
           preSnapshot: (empty)
           preStart: (empty)
           preStop: (empty)
       parentTdeKeystorePassword: ********
       parentTdeKeystorePath: /u01/app/oracle/keystores/CDOMLOSR197/wallet
       redoLogGroups: 3
       redoLogSizeInMB: 50
       reference: ORACLE_VIRTUAL_PDB_SOURCE-2
       runtime:
           type: OraclePDBSourceRuntime
           accessible: true
           accessibleTimestamp: 2021-10-06T22:17:15.907Z
           activeInstances:
               0:
                   type: OracleActiveInstance
                   hostName: ip-10-110-234-67.delphix.com
                   instanceName: CDOMLOSR197
                   instanceNumber: 1
           databaseMode: READ_WRITE
           databaseRole: PRIMARY
           databaseSize: 913.4MB
           databaseStats: [ ... ]
           enabled: ENABLED
           lastNonLoggedLocation: 0
           status: RUNNING
       runtimeMountInformation:
           type: UnixRuntimeMountInformation
           name: (unset)
           nfsVersion: 4
           nfsVersionReason: DEFAULT
       staging: false
       status: DEFAULT
       tdeExportedKeyFileSecret: ********
       tdeKeyIdentifier: AbSP7gninU+Gv1YQ/iEcJAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
       tdeUUID: a3f26971-1df6-4c81-994f-4b2c582ded87
       virtual: true