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.

    Copy 
    $ ssh admin@YOUR_ENGINE

  2. Move to the database.

    Copy 
    delphix> source
    delphix source> "VCDO_1JL"

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

    Copy 
    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>.

    Copy 
    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.

    Copy 
    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.

    Copy 
    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.

    Copy 
    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.

    Copy 
    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