CLI cookbook: locating and updating the value of tdeKeyIdentifier

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

This process is currently supported only via CLI.

Procedure

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

   ACTIONSCRIPT3

   $ ssh admin@YOUR_ENGINE

2. Move to the database.

   ACTIONSCRIPT3

   delphix> sourcedelphix source> "VCDO_1JL"

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

   ACTIONSCRIPT3

   delphix source "VCDO_1JL" *> lsProperties    type: OracleVirtualPdbSource    name: VCDO_1JL    allowAutoVDBRestartOnHostReboot: false    archivelogMode: true    config: VCDO_1JL    configParams:        _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: trueOperationsupdateenabledisablestartstopupgrade

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

   ACTIONSCRIPT3

   SQL> alter session set container=VCDO_1JL;Session altered.SQL> select key_id, tag from v$encryption_keys;KEY_ID------------------------------------------------------------------------------TAG--------------------------------------------------------------------------------AbSP7gninU+Gv1YQ/iEcJAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAdlpx_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.

   ACTIONSCRIPT3

   delphix source 'VCDO_1JL'> update delphix source 'VCDO_1JL' update *> unset tdeKeyIdentifierdelphix source 'VCDO_1JL' update *> lsProperties    type: OracleVirtualPdbSource    name: VCDO_1JL    allowAutoVDBRestartOnHostReboot: 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.

   ACTIONSCRIPT3

   delphix source 'VCDO_1JL'> lsProperties    type: OracleVirtualPdbSource    name: VCDO_1JL    allowAutoVDBRestartOnHostReboot: false    archivelogMode: true    config: VCDO_1JL    configParams:        _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. 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.

   ACTIONSCRIPT3

   ATE 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 vPDB and will be used for all future Delphix operations. View all the settings using the "ls" command.

   CODE

   delphix source 'VCDO_1JL'> lsProperties    type: OracleVirtualPdbSource    name: VCDO_1JL    allowAutoVDBRestartOnHostReboot: false    archivelogMode: true    config: VCDO_1JL    configParams:        _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