Skip to main content
Skip table of contents

DCT Toolkit

Introduction

DCT Toolkit (dct-toolkit) is the command line application specifically designed to interact with a particular DCT instance. It aims to simplify and ease out interacting with DCT instances while making the process intuitive, with minimal configuration and setup. dct-toolkit abstracts all of the API level implementation complexities and provides a user friendly LINUX-like interface, which can be run from any terminal. 

Compatibility

dct-toolkit is designed to be compatible with any DCT product version, but is fully supported from DCT version 8.0.0 onwards. While dct-toolkit can be used in testing or development environments against any DCT versions, Delphix highly recommends at least DCT version 8.0.0 for using it in the production environment. Some of the value added features are only supported from DCT 8.0.0 version onwards. 

dct-toolkit does not need to be upgraded with every new version of DCT. All of the new APIs that are part of the newer DCT releases will automatically be available in dct-toolkit. This is possible because dct-toolkit reads the api specification from the DCT instance (configurable) it is configured to connect to and dynamically generates the list of commands and their respective options. 

Installation

Currently dct-toolkit is supported on Linux, Windows and macOS platforms. There are no special system requirements for running dct-toolkit.

Installing dct-toolkit is as simple as downloading the executable binaries from the downloads URL and extracting it to the machine from where it needs to run. Once the executable binary is extracted, grant the execute permission to the binary file. 

On Linux and macOS this can be done from Terminal via:

CODE
chmod 777 ./dct-toolkit

For Windows this can be done from cmd via:

CODE
CACLS files /e /p <username>:F

Where <username> is the user to whom the permission must be granted, F is the Full Control permission that needs to be granted. 

For macOS currently the binary is not verified hence macOS will give warning that the binary is untrusted. To get around this issue for now you will need to open this binary and explicitly whitelist it. One easy way to achieve this is to press CTRL key and click on the binary file and then select Open. On the resulting warning message dialog box select Open. Now the binary is allowed to be executed from the terminal.

Setup

A plain text configuration file is needed to get started. The recommended way to create this configuration file is via the create_config command, available in dct-toolkit. 

For creating a typical configuration with only the required properties, the following command can be used:

CODE
dct-toolkit create_config dctUrl=<URL of DCT instance> apiKey=<api key value>

This will create the configuration file in the default location under the user's home directory. The full path for configuration file will be: <users home directory>/.dct-toolkit/dct-toolkit.properties 

create_config command takes in below mentioned options:

Option name

Required/Optional

Description

dctUrl

Required

HTTP/S URL of the DCT instance.

apiKey

Required

API key of the account used to connect to the DCT instance pointed by the dctUrl option.

configFileOutputLocation

Optional

Fully qualified path of the properties file. If this option is not specified, the properties file will be created in the .dct-toolkit folder under the user's home directory. If this option is specified, the DCT_TOOLKIT_CONFIG_FILE environment variable needs to be exported to point to the config file, in order for the config file to be effective.

apiVersion

Optional

API version to be used for DCT APIs. If this is not set then the latest API version from the DCT instance.

apiYamlLocation

Optional

Location of the local api.yaml file. If this is not set, the latest api.yaml file will be downloaded from the DCT instance that is configured.

--insecureSSL

Optional

Whether to use insecure SSL connection to the DCT instance. By default this will be set to false.

--unsafeHostnameCheck

Optional

Whether to disable hostname verifier checks for SSL connection to the DCT instance. By default this will be set to false.

sslCertificate

Optional

PEM format SSL certificate path to be used for SSL connection to DCT instance.

logLevel

Optional

Log level to set. Can be one of OFF, ERROR, WARN, INFO, DEBUG, TRACE, ALL. By default log level will be INFO.

logDir

Optional

Directory where the logs should be written. By default, logs will be written to the logs directory created under the .dct-toolkit folder in the user's home directory.

All of these options and help can also be requested via:

CODE
./dct-toolkit create_config -h

All of the above properties can also be individually specified using environment variables. Environment variable mappings for each of the above properties is as follows:

Property Name

Environment Variable Name

dctUrl

DCT_TOOLKIT_DCT_URL

apiKey

DCT_TOOLKIT_API_KEY

apiVersion

DCT_TOOLKIT_API_VERSION

apiYamlLocation

DCT_TOOLKIT_API_YAML_LOCATION

--insecureSSL

DCT_TOOLKIT_SSL_INSECURE

--unsafeHostnameCheck

DCT_TOOLKIT_SSL_UNSAFE_HOSTNAME_CHECK

sslCertificate

DCT_TOOLKIT_SSL_CERT

logLevel

DCT_TOOLKIT_LOG_LEVEL

logDir

DCT_TOOLKIT_LOG_DIR

It’s acceptable to configure non-sensitive properties in a properties file and sensitive properties (like apiKey) via an environment variable. Properties set via environment variable will take precedence over the ones specified in the properties file.

Once the required properties are available via either the properties file or via the environment variable, dct-toolkit is ready for use. 

Usage guide

All of the DCT APIs are available as commands in dct-toolkit. To find the list of all commands which are available, use the command:

CODE
./dct-toolkit -h

This will print the list of all commands grouped by the appropriate entity names. 

Examples

  1. The list of available options for a particular command can be requested via: 

CODE
./dct-toolkit <command_name> -h
  1. There are currently a lot of options for provisioning a VDB, some options are only valid for a particular DB type. For example, the unique_name option is only applicable to Oracle DBs. For better ease of use, dct-toolkit has subcommands created under the provisioning command, with options that are relevant to that particular subcommand. For example, these are the subcommands under the provision_vdb_by_snapshot command:

CODE
oracle
sybase
mssql
appdata
postgres

For provisioning an Oracle VDB, the following command can be used: 

CODE
dct-toolkit provision_vdb_by_snapshot oracle source_data_id=<dsourceId> --auto_select_repository unique_name=<uniqueName>

For provisioning a Sybase-ASE VDB, the following command can be used: 

CODE
dct-toolkit provision_vdb_by_snapshot sybase source_data_id=<dsourceId> --auto_select_repository --truncate_log_on_checkpoint
  1. For getting the list of registered engines, the following command can be used: 

CODE
dct-toolkit get_registered_engines

The above command will only print important fields in the response. For printing all of the fields in the response, use: 

CODE
-A/--all-columns

Option:

CODE
dct-toolkit get_registered_engines -A

There is also an option to list only the selected columns that are useful to the user:

CODE
--columns/-c 

Option:

CODE
dct-toolkit get_registered_engines --columns=id,name,cpu_core_count...

For advanced use cases, dct-toolkit also provides an option to specify a jsonpath expression to extract required objects from the JSON response. This can be requested with:

CODE
--jsonpath/-jp

Option:

CODE
dct-toolkit get_registered_engines --jsonpath=<json path expression starting with $>

Note, these options are available for all of the commands available in dct-toolkit

  1. For commands that use a request body, dct-toolkit provides -body, which can be used to specify a JSON body (instead of using individual options).

CODE
dct-toolkit token_info --body=<JSON body to POST to DCT>

Help regarding the exact structure of JSON request and response body can be requested for all of the commands via:

CODE
-jh/--jsonhelp

Option:

CODE
dct-toolkit token_info -jh
  1. dct-toolkit provides an easy to use and understand format for specifying tags. Example, this command to add two tags: {key=purpose, value=testing} and {key=key1, value=value1}

CODE
dct-toolkit create_environment_tags environmentId=<envId> tags purpose=testing key1=value1
  1. Some of the DCT APIs trigger an asynchronous job and return a jobId in response. dct-toolkit, by default, will wait for the asynchronous job to get completed and will report the end state of the job. There is an option to NOT wait for the completion of an asynchronous job. For example, to NOT wait, use the --no-wait option: 

CODE
dct-toolkit refresh_environment environmentId=<envId> --no-wait

Logging

dct-toolkit has inbuilt logging support which will export all of the logs to a default location which is under the user's home directory. The full path will be <user home directory>/.dct-toolkit/logs. dct-toolkit creates a separate log file for every date.

Log level and log directory are both configurable and can be specified in the configuration file or via the environment variable. Please refer to the Setup section above for more information.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.