DSS Agent - DSS 6 | Data Source Solutions Documentation

Documentation: DSS Agent - DSS 6 | Data Source Solutions Documentation

DSS Agent

DSS Agent is an installation of Data Source Solutions DSS that typically resides on the same machine as a source or target data store (database or file system) to perform the task of capturing or integrating data. In the DSS distributed architecture, the agent acts as a child process for the hub server that entirely controls the replication process.

DSS Agent service configuration allows to establish a secure network connection to the agent and configure the agent properties. Every DSS Agent has its own set of agent properties that define various agent characteristics/attributes, including agent connection parameters, user access levels, authentication mode, etc. DSS Agent service can be configured both from the DSS user interface or using the command line.

Even though we recommend using the DSS Agent with the distributed setup, DSS can also support an agent-less architecture. DSS can connect directly (without using agent) to a remote database location using a DBMS protocol such as Oracle TNS.

Benefits of Using DSS Agents

Even though DSS fully supports agent-less operations, however, the distributed architecture with agents provides security benefits and multiple performance and scalability advantages.

DSS Agent reduces network cost, distributes CPU load, and allows capture of changes directly from DBMS logging system.
Standardized communication between remote agents enables consistent and secure connections using encryption and key-based authentication as needed.
DSS Agent offloads some resource-intensive processing work that would otherwise have to be performed by the hub. Distributing work through agents results in a scalable setup.
DSS Agent compresses data before sending it. Sending compressed data across the wire requires less bandwidth and/or fewer data packets. DSS commonly achieves 10x or higher compression ratios. Data is only decompressed when it reaches the target agent. Compressing data before sending it magnifies the available bandwidth. Always use an agent for communication over a Wide Area Network (WAN), for example, between on-premises and the cloud, to leverage compression.
DSS Agent is sometimes unavoidable in order for DSS to access database transaction logs with sufficient performance. High volume environments may generate such large volumes of transaction logs that access to a database stored procedure or function is simply not fast enough to read the logs over a database connection.
DSS Agent on a source machine filters data before sending it down the data pipeline. Databases always write more information to the transaction log than should be replicated, and in many cases, only a subset of the application tables is replicated to another system. Filtering data close to the source improves efficiency.

DSS Agent Connection

The DSS Agent listener service allows the hub server to communicate with the DSS Agent. The hub server connects to the agent using a specified TCP/IP port number.

The connection between the agent and the hub server is always secure. By default, the connection is established using TLS. In addition to this secure connection, DSS also allows you to configure certificate based authentication and user based authentication.

Separate configuration is not required for enabling the secure TLS connection.

On Unix and Linux, the DSS Agent listener runs as the system process (daemon). For more information, see System Configuration for DSS Agent on Linux.
On Windows, the DSS Agent listener is a Windows service. The service is started automatically after installing the DSS Agent on Windows using the installer. When installing the DSS Agent on Windows using zip file, the service must be created and started manually.

Command dssagentlistener can be used to start, stop, and manage the DSS Agent listener process/service.

DSS Agent Connection to Location

When the DSS Agent service is started for the first time, the agent server's public certificate and private key are created automatically and are stored in the DSS Agent properties Agent_Server_Public_Certificate and Agent_Server_Private_Key on the DSS Agent machine.

When a location first connects to the DSS Agent, it gets the agent server public certificate (DSS Agent property Agent_Server_Public_Certificate) and stores a copy of it (location property Agent_Server_Public_Certificate) in the repository database. The next time the location connects to the DSS Agent, the DSS Hub System verifies the certificate on the agent side to match the certificate on the location side to establish the connection.

DSS Agent Connection to Hub Server

The hub server's client public certificate and private key are generated when hub server repository tables are created and are used to verify all incoming connections to the agents. The public certificate and private key are stored in the repository properties Agent_Client_Public_Certificate and Agent_Client_Private_Key in the repository database. If the agent is configured to accept connections only from a specific hub server(s) (DSS Agent property Only_From_Client_Public_Certificates), the hub server's client public certificate and private key are verified to accept only those that are allowed. This provides an easy and secure way to accept anonymous connections to the agent from trusted hub servers.

DSS Agent Configuration

After installation, the DSS Agent must be configured to implement secure agent service authentication and authorization. DSS Agent service configuration can be done remotely from the user interface or the command line or directly on the agent machine using the command line. Configuration steps include creating DSS Agent users and defining the authentication and authorization policies for accessing the DSS Agent service.

The DSS Agent service can be configured using the following methods:

Enabling the setup mode for the agent. For more information, see DSS Agent Setup Mode.

By default, after the first start of the DSS Agent service, it will enter a 60-minute setup mode, during which the DSS Agent may be configured.

Using the command line on the agent machine. In this case, the setup mode is not required.
Using the DSS Agent user with the administrator (AgentAdmin) permissions that can remotely configure the DSS Agent service (e.g. from the user interface or command line). In this case, the setup mode is not required.

DSS Agent Setup Mode

Setup mode is a special state intended only for DSS Agent configuration, in which the agent does not accept any connections and is not available for any other activities, such as replication. In the setup mode, you can configure the DSS Agent remotely (using the user interface or command dssagentconfig with option <b>-R</b>). It is also possible to reinitiate the DSS Agent setup mode using the dssagentconfig command (see section Examples).

There are two types of DSS Agent setup mode:

Time-based setup mode: This is a timed setup mode that expires in a certain period of time, after which the DSS Agent becomes completely unavailable unless it is terminated by a user before the expiration. By default, after starting the DSS Agent for the first time after its installation, it will automatically go into the timed setup mode for the next 60 minutes for the DSS Agent to be configured within this time period. The time-based setup mode can be enabled using command dssagentconfig by setting up the DSS Agent property Setup_Mode_Timed_Until.
Token-based setup mode: This mode is protected with a token name and token value pair. To enable this setup mode, the user needs to define a token name and value (DSS Agent properties Setup_Mode_Token_Name and Setup_Mode_Token_Value). To configure the DSS Agent using the token-based setup mode, the user then needs to supply the token value.

DSS Agent Connection Modes

The following modes are available for connecting hub to DSS Agent service:

All connections require an agent user. This mode requires agent user's credentials to access the DSS Agent service. The DSS Agent user credentials are defined by location properties Agent_User and Agent_Password.
Anonymous connections only. This mode allows the DSS Agent service to accept anonymous connection (as opposed to connections with the agent's user credentials) provided that the DSS Agent access is limited to only hubs with specific hub certificates (the DSS Agent property Only_From_Client_Public_Certificate). No DSS Agent user account (username and password) is required for this type of authentication. This authentication mode is defined by the DSS Agent property Anonymous_Access.
Allow both anonymous connections and ones with an agent user. This mode allows anonymous connections from the trusted hubs and also to define a user with administrator permissions (AgentAdmin user) for the purpose of remote DSS Agent configuration.

DSS Agent Users

DSS Agent user is a special type of DSS user that can access the DSS Agent service. Just like the hub server user accounts are used to authenticate users on the DSS Hub System, the DSS Agent service has its own set of user accounts. DSS Agent users can also be assigned administrator (AgentAdmin) permissions. Only the DSS Agent users with this permission (access level) can configure the agent service remotely when the DSS Agent is not in the setup mode. The administrator can either access the Agent Service Configuration dialog in the UI or use CLI commands dssagentconfig and dssagentuserconfig for configuring the DSS Agent service.

DSS Agent users can access the DSS Agent service using different types of authentication mechanisms. For more information, see section User Authentication.