Skip to content

Managing Connectors

This section describes how you can create and manage your connectors.

As a reminder, connectors are the way users define the data sources to which the Masking Engine should connect. Connectors are grouped within environments. In order to navigate to the connectors screen, click on an environment and then click the Connector tab.

The connectors screen contains the following information and actions:

  • Connector ID — The numeric ID of the connector used to refer to the connector from the Masking API.

  • Connector — The name of the connector.

  • Meta Data Source — The type of connector. One of Database, File, or Mainframe.

  • Type — The specific type of connector.

  • Edit — Edit the connector. See more details below.

  • Delete — Delete the connector. See more details below.

The connectors on the screen can be sorted by the various informational fields by clicking on the respective field.

Creating a Connector

To create a new connector:

  1. In the upper right-hand corner of the Connector tab, click Create Connection. The Create Connection window appears, prompting you for connection information for the data source you would like to connect to. The required information will change depending on the Type of data source you select. For more details on what info is needed to connect to different types (Oracle, AWS RDS, etc) see sections below.

  2. Several of our connector types offer two different modes of connecting, Basic and Advanced Mode. Advanced Mode gives you the ability to specify the exact JDBC URL and add parameters that may not be available in Basic Mode.

    The fields that appear on the Connector screen are specific to the selected Connector Type (see Connector Types below).

  3. Click Save.

Editing a Connector

To edit a connector:

  1. In the Connector tab, click the Edit icon for the connector you want to edit.

  2. Change any information necessary. To change the password:

    1. Select the checkbox next to Change Password.

    2. In the field that appears, enter the new password.

  3. Click Save.

Deleting a Connector

To delete a connector, click the Delete icon to the far right of the connector name.

Warning: When you delete a connector, you also delete its rule sets and inventory data.

Connector Types

Database Connectors

The fields that appear are specific to the DBMS Type you select. If you need assistance determining these values, please contact your database administrator.

You can only create connectors for the databases and/or files listed. If your database or file type is not listed here, you cannot create a connector for it.

  • Connection Type — (Oracle, MS SQL Server, and Sybase only) Choose a connection type:

    • Basic — Basic connection information.

    • Advanced — The full JDBC connect string including any database parameters.

  • Connection Name — The name of the database connector (specific for your Delphix application).

  • Schema Name — The schema that contains the tables that this connector will access.

  • Database Name — The name of the database to which you are connecting.

    Note: The database name field is case-sensitive. It must match exactly with the name of the current database as known to the instance.

  • Host Name/ IP — The network hostname or IP address of the database server.

  • Use Kerberos Authentication - (Oracle only, optional) Whether to use Kerberos to authenticate to the database. This box is clear by default. Before Kerberos may be used, the appliance must be properly configured - refer to these instructions (link to appliance Kerberos configuration instructions[1]). If this box is checked, the application authenticates with the Kerberos KDC before connecting to the database, then uses its Kerberos credentials to authenticate to the database instead of a login/password. When Kerberos is enabled, the "Login ID" field is treated as the Kerberos user principal name. The password, if supplied, is used to authenticate the user principal with the KDC. The password field may be left blank if the keytab set during appliance configuration contains keys for the user principal.

  • Login ID — The user login this connector will use to connect to the database (not applicable for Kerberos Authentication).

  • Password — The password associated with the Login ID or Username. (This password is stored encrypted.)

  • Principal Name - (Kerberos Authentication only) The name of the Kerberos user principal to use when authenticating with the KDC. The realm portion of the principal may be omitted if it matches the configured default realm.

  • Service Principal - (Sybase with Use Kerberos Authentication only) The name of the Sybase service instance.

  • Port — The TCP port of the server.

  • SID — (Oracle only) Oracle System ID (SID).

  • Instance Name — (MS SQL Server only) The name of the instance. This is optional. If the instance name is specified, the connector ignores the specified "Port" and attempts to connect to the "SQL Server Browser Service" on port 1434 to retrieve the connection information for the SQL Server instance. If the instance name is provided, be sure to make exceptions in the firewall for port 1434 as well as the particular port that the SQL Server instance listens to.

  • Custom Driver Name — (Generic only) The name of the JDBC driver class, including Java package name.

  • JDBC URL — (Generic and Advanced connector mode for Oracle, MS SQL Server, and Sybase only) The custom JDBC URL, typically including hostname/IP and port number.

  • Connection Properties File - A Java properties file to specify configurations for the JDBC connection. See Database Connection Properties for more information.

All database types have a Test Connection button at the bottom left of the New Connector window. We highly recommend that you test your connection before you save it. Do so before you leave this window. When you click Test Connection, Delphix uses the information in the form to attempt a database connection. When finished, a status message appears indicating success or failure.

File Connectors

The following values appear when any of the file connector types are selected:

  • Connector Name — The name of the file connector (specific to your Delphix application and unrelated to the file itself).

  • Connection Mode — Filesystem Mount Point, SFTP and FTP

The rest of the values appear based on the selected Connection Mode value. For Filesystem Mount Point connection mode, refer to the corresponding section in the Managing Remote Mounts page. For other connection modes, the following values appear:

  • Path — The path to the directory where the file(s) are located.

  • Server Name — The name of the server used to connect to the file.

  • Port — The port used to connect to the server.

  • User Name — The user name to connect to the server.

  • Password — (non-Public Key Authentication only) The associated password for the server.

  • Public Key Authentication — (Optional) (Only appears for SFTP.) Check this box to specify a public key. When you check this box, the Available Keys drop-down appears. Choose a key from the drop-down. See Delphix Masking APIs for information on uploading public keys to the Masking Engine.

    Note: If you plan to do on-the-fly masking then you will need to create a separate environment and connector to be the source for the files to be masked. The masked files will get put into the directory pointed to by the connector you created previously (the target). However, the file path specified in the connector of the target rule set must point to an existing file the target directory. It does not have to be a copy of the file, just an entry in the directory with the same name. It will be replaced by the masked file.

Database Connection Properties

Getting Properties

To retrieve all properties set on the connector, make a request to the GET database-connector/{id}/properties endpoint. This endpoint will respond with all default properties set by the driver, superimposed by any properties specified by an uploaded connection properties file. If a properties file is uploaded for a connector, this list can also be viewed through the UI on the database connector form, where you can sort by Property, Value, or Modified. The Modified field signifies whether the property value is the default or modified by the uploaded properties file.

Note

The database name field is case-sensitive. It must match exactly with the name of the current database as known to the instance.

Note

Only a valid JDBC URL is required to retrieve properties of a connector; a valid connection to the database server is not necessarily required.

Example of properties on the built-in MSSQL database connector

Setting Properties

Properties can sometimes be set through the JDBC URL or through a connection properties file. Customizing the JDBC URL is limited to Advanced, Generic, and Extended Connectors, while uploading a properties file is supported by all database connectors. All properties files must have the extension .properties and must adhere to Java properties file syntax. Even if a property specified in the properties file is not technically supported by the JDBC driver, it will still be passed along to the driver when building the JDBC Connection. All provided and unsupported properties will be logged whenever the properties file is loaded.

Note

The properties file is assumed to be written using ISO 8859-1 character encoding.

Note

Certain JDBC drivers do not allow specific supported properties to be set through the JDBC URL. For example, Caché DB does not support setting the schema property through the JDBC URL, so it must either be set through the extended connector's Schema form field or through a connection properties file. Please defer to specific Driver documentation to see how a property must be set.

Note

When a property can be duplicated among a form field, the JDBC URL, and the properties file, the property value will most likely be used in the following hierarchy of specification.

  1. Connector form fields (where applicable) for username, password, and schema
  2. Properties file 3a. Connector form fields (where applicable) for database name, host, port, SID, and instance name 3b. JDBC URL

Though this hierarchy is convention, it is up to the JDBC driver to implement the precendence for duplicate properties specified among the URL, Properties object, and JDBC Connection API. Please defer to the specific JDBC Driver documentation to verify which method of specification precedes the other. A Delphix Masking connectors form will either have the fields listed in 3a or 3b, but not both. Therefore, it is not possible to duplicate a property between 3a and 3b.

Security Considerations

The property key or value provided in a database connector's properties file will not be regulated and is subject to any user with CREATE or UPDATE connector privileges. This means that even supported sensitive properties such as user, password, hostname, etc... will be available in plain text to anyone with the VIEW connector privilege.

If possible, specify sensitive properties through relevant form fields which will be obfuscated in all places or through the JDBC URL which will still be visible in plain text to any user with the VIEW connector privilege but will be redacted in support bundles.