Installing DSS Agent on Unix - DSS 6 | Data Source Solutions Documentation

Documentation: Installing DSS Agent on Unix - DSS 6 | Data Source Solutions Documentation

Installing DSS Agent on Unix

This section describes the requirements, step-by-step instructions on how to install the DSS Agent on Unix (Solaris, AIX) and the initial system configuration.

For installing the DSS Agent on Linux, see Installing DSS Agent on Linux.

Requirements

Following are the prerequisites for installing the DSS Agent on Unix:

Sufficient disk space
Ensure sufficient disk space is available on the machine where this installation will be performed. For more information, see Agent Disk Requirements.
Compatibility
Check whether the DSS Agent version is compatible with the operating system and DBMS. Refer to the relevant Supported Platforms section or read the COMPATIBILITY section in the release notes (available under the Downloads tab in the Data Source Solutions dashboard).
Installation file
DSS Agent installation file for Unix (e.g. datasourcesolutions-6.1.0_21-agent_only-solaris_10-sparcv9-64bit_ga_patch.tar.gz). This file can be downloaded from the Downloads tab in the Data Source Solutions dashboard. For more information, see Downloading DSS.
Access to source and target locations
For the DSS Agent to access a source or target database directly, the database connectivity (e.g. ODBC drivers) must be installed on the agent machine. For more information, see Source and Target Requirements.
- If DSS Agent must perform log-based capture from an Oracle source database, then the operating system user that DSS Agent uses must be able to read the redo files and archive files that Oracle generates. It can be done by adding the operating system user to the oinstall or dba group in /etc/group. The permission to read these files can also be given by creating special Access Control Lists (ACLs). For more information, see Oracle Requirements.
System root permission
This permission is typically needed to configure autostart of the DSS Agent process using inetd or SMF to listen on a TCP/IP port. Alternatively, you can manually start the DSS Agent as daemon process using dssagentlistener, which does not require root permission.

It is recommended to create a non-root account for installing and operating DSS Agent. We suggest creating a separate user account (e.g, datasourcesolutions) for this purpose.

Install Steps

Perform the following steps as the user that will be used for operating the DSS Agent:

The commands to set the environment variables depend on the shell you use to interface with the operating system. This procedure lists examples that can be used in Bourne Shell (sh) and KornShell (ksh).

Configure the environment variables DSS_HOME, DSS_CONFIG, and DSS_TMP for your operating system. Each of these environment variables should be pointed to the DSS Agent installation directories - dss_home, dss_config, and dss_tmp.
```
export DSS_HOME=/home/datasourcesolutions/dss_home
```
```
export DSS_CONFIG=/home/datasourcesolutions/dss_config
```
```
export DSS_TMP=/home/datasourcesolutions/dss_tmp
```
Also, add the executable directory path to the environment variable PATH.
```
export PATH=$PATH:$DSS_HOME/bin
```

Add the environment variables and the executable directory path into the startup file (e.g. .profile).

export DSS_HOME=/home/datasourcesolutions/dss_home
export DSS_CONFIG=/home/datasourcesolutions/dss_config
export DSS_TMP=/home/datasourcesolutions/dss_tmp
export PATH=$PATH:$DSS_HOME/bin

Create the installation directory - dss_home:
```
umask 022
```
```
mkdir $DSS_HOME
```

umask 022 is used so that the files and directories created in the following commands are readable by everyone (other Unix users and groups), but only writable by the owner.
- other directories (dss_config and dss_tmp) will be automatically created as needed.
- dss_home is regarded a read-only directory. The user files saved in this directory will be moved to a backup directory when executing the DSS Agent for the first time or after an upgrade.

Uncompress the installation file (e.g. datasourcesolutions-6.1.0_21-agent_only-solaris_10-sparcv9-64bit_ga_patch.tar.gz) into the dss_home directory:
```
cd $DSS_HOME
```
```
gzip -dc /tmp/datasourcesolutions-6.1.0_21-agent_only-solaris_10-sparcv9-64bit_ga_patch.tar.gz | tar xf -
```
Configure the system for DSS Agent. After the agent install steps are completed, it is necessary to configure the DSS Agent process.

There are different ways for configuring the DSS Agent to listen on a TCP/IP port:
- Unix inetd
  Standard on older Unix distributions. Requires root privilege.
  inetd configuration steps
  
  The following steps should be performed as user root to configure the inetd service:
  1. In the /etc/services file, add the following line specifying the name (e.g. mydss) and the TCP/IP port number of the DSS Agent:
```
mydss 4343/tcp    #Port for DSS Agent Listener
```
  2. Add the following line to /etc/inetd.conf file:
```
mydss stream tcp nowait datasourcesolutions /home/datasourcesolutions/dss_home/bin/dssagent dssagent -EDSS_HOME=/home/datasourcesolutions/dss_home -EDSS_CONFIG=/home/datasourcesolutions/dss_config -EDSS_TMP=/home/datasourcesolutions/dss_tmp
```

The user must be set to the user (e.g. datasourcesolutions) under which the DSS Agent is installed/running. - The service name (e.g. mydss) specified in this inetd.conf file must match with the name specified (step #1) in the /etc/services file. - The above configuration should be defined in a single line (without manual line break).

        <div class="callout callout-note">

Option <b>-E</b> defines the environment variables.

    3.  Reload or restart the **inetd** service to apply the changes. For information about restarting the **inetd** service, refer to the operating system documentation.

    </details>

-   Solaris Service Management Facility (SMF)  
    Used on Solaris (versions 10 and higher) distributions. Requires **root** privilege.

    <details><summary>SMF configuration steps</summary>

    In Solaris 10 and higher, the **/etc/inetd.conf** file has been replaced by SMF manifests. All **inetd** services are now configured/controlled under the SMF. The following steps should be performed as user **root** to configure the SMF service:

    1.  In the **/etc/services** file, add the following line specifying the name (e.g. **mydss**) and the TCP/IP port number of the DSS Agent:

        ```plaintext
        mydss 4343/tcp    #Port for DSS Agent Listener
        ```

    2.  Create a temporary file (e.g. **/tmp/inet.dss**) containing the following inetd.conf-style entry for DSS Agent:

        ```plaintext
        mydss stream tcp nowait datasourcesolutions /home/datasourcesolutions/dss_home/bin/dssagent dssagent -EDSS_HOME=/home/datasourcesolutions/dss_home -EDSS_CONFIG=/home/datasourcesolutions/dss_config -EDSS_TMP=/home/datasourcesolutions/dss_tmp
        ```

        <div class="callout callout-important">

The user must be set to the user (e.g. datasourcesolutions) under which DSS Agent is installed/running. - The service name (e.g. mydss) specified in this temporary file must match with the name specified (step #1) in the /etc/services file. - The above configuration should be defined in a single line (without manual line break).

        <div class="callout callout-note">

Option <b>-E</b> defines the environment variables.

    3.  Import the temporary file (e.g. **/tmp/inet.dss**) into System Management Facility (SMF) using the command **<a href="https://docs.oracle.com/cd/E36784_01/html/E36871/inetconv-1m.html" rel="nofollow">inetconv</a>**.  
        For example:

        ```plaintext
        inetconv -i /tmp/inet.dss
        ```

    4.  Enable the service using the command **<a href="https://docs.oracle.com/cd/E36784_01/html/E36871/inetadm-1m.html" rel="nofollow">inetadm</a>**.  
        For example:

        ```plaintext
        inetadm -e svc:/network/dss/tcp:default
        ```

    5.  Refresh the service using the command <a href="https://docs.oracle.com/cd/E36784_01/html/E36871/svcadm-1m.html" rel="nofollow"><strong>svcadm</strong></a>:

        ```plaintext
        svcadm refresh inetd
        ```

    </details>

-   DSS Agent Listener  
    Our own daemon [**dssagentlistener**](/docs/dss6-command-line-interface-command-reference-dssagentlistener). Does not require **root** privilege.

    <details><summary>Start DSS Agent Listener as daemon process</summary>

    The command [**dssagentlistener**](/docs/dss6-command-line-interface-command-reference-dssagentlistener) should be executed with option `<b>-d</b>` to start the DSS Agent Listener service as a daemon process on the required port:

    ```plaintext
    dssagentlistener -d 4343
    ```

    </details>

To test the connection to the DSS Agent, execute the command [**dssagenttest**](/docs/dss6-command-line-interface-command-reference-dssagenttest) on the machine from which you are connecting to the agent. You can also check whether [**dssagentlistener**](/docs/dss6-command-line-interface-command-reference-dssagentlistener) is running by executing the command [**dssagenttest**](/docs/dss6-command-line-interface-command-reference-dssagenttest) directly on the DSS Agent machine.

<details><summary>Examples for testing the connection to a DSS Agent</summary>

##### Example 1: Check connection to a DSS Agent

You can check the connection to the DSS Agent installed/running on a remote machine with username and password authentication enabled. Execute the following command on the hub machine or on the machine from which you are connecting to the DSS Agent:

```plaintext
dssagenttest -L myuser/mypassword mynode 4343
```

Sample output in Linux with successful authentication and also indicating that the DSS Agent Listener is running:

```plaintext
dssagenttest: Data Source Solutions 6.1.0/21 (linux_glibc2.17-x64-64bit)
dssagenttest: Agent version 6.1.0/21.
dssagenttest: Authentication with username and password enabled.
dssagenttest: Authentication successful.
dssagenttest: Finished. (elapsed=0.34s)
```

##### Example 2: Check whether dssagentlistener is running

After installing and starting the DSS Agent Listener service, you can verify whether the [**dssagentlistener**](/docs/dss6-command-line-interface-command-reference-dssagentlistener) is running on the agent machine. Execute the following command on the agent machine:

```plaintext
dssagenttest mynode 4343
```

Sample output in Unix with successful authentication indicating that the DSS Agent Listener is running:

```plaintext
dssagenttest: Data Source Solutions 6.1.0/21 
dssagenttest: Agent version 6.1.0/21.
dssagenttest: Authentication with username and password enabled.
dssagenttest: Authentication successful.
dssagenttest: Finished. (elapsed=0.18s)
```

</details>

Configure the DSS Agent, which requires setting its network security and authentication properties. This is normally done from a browser while creating a location (provided the agent is in 'setup mode'). Alternatively, you can also perform this agent configuration from the command-line.
- For configuring the DSS Agent from browser, see Configuring DSS Agent from Browser.
- For configuring the DSS Agent from CLI, see Configuring DSS Agent from CLI.

By default, after starting the DSS Agent for the first time, it will be available in 'setup mode' for the next 60 minutes. In 'setup mode', you can configure the DSS Agent remotely from the hub machine using browser or CLI. When the 'setup mode' expires after 60 minutes, the agent can not be configured remotely. If you want to re-initiate the DSS Agent 'setup mode' later, use the command dssagentconfig directly on the agent machine. For example, to enable 'setup mode' for the next 1 hour, execute:

```plaintext
dssagentconfig Setup_Mode_Timed_Until=now+1h
```