Configuring DSS Agent from CLI - DSS 6 | Data Source Solutions Documentation

Documentation: Configuring DSS Agent from CLI - DSS 6 | Data Source Solutions Documentation

Configuring DSS Agent From CLI

This section describes the steps to configure the DSS Agent service from the Command Line Interface (CLI). For steps to configure the agent service from a browser, see Configuring DSS Agent from Browser.

You can configure the agent either by directly accessing the CLI (referred to as Direct CLI in this documentation) on the agent machine or using the CLI on a remote machine (referred to as Remote CLI in this documentation). To configure the agent using the CLI on a remote machine, either the agent setup mode must be initiated or the AgentAdmin user must be used.

To configure the agent service, the DSS Agent must be installed and running.

If the configuration for an existing agent service is modified/updated, ensure to reflect those changes in all locations that use this agent service. For example, if the password of an agent user is updated, then that user's password must be updated in all locations that use this agent service.

Configuring Agent Service

Perform the following steps to configure the agent service:

Limit Agent Access

By default, the agent can be accessed by all hub system(s). However, you can also choose to allow only certain hub system(s) to access the agent service by using the client public certificate of the hub system. For this, add the client public certificate (stored in the repository property Agent_Client_Public_Certificate) of a specific hub system to the list of allowed client certificates (stored in the agent property Only_From_Client_Public_Certificates). This will enable anonymous connections from the specified hub system(s) to the agent i.e. the hub system can connect to the agent without using the agent user credentials instead the client public certificate of the hub system is used for authentication (see step 2 - agent authentication mode).

This step is optional.

To add a hub to the allowed list:

Create a public certificate file of the hub system. Execute the command dssreposconfig on the hub machine that needs to be added to the allowed list:

{% tabs %}

{% tab label="Linux" %}
```
dssreposconfig 'Agent_Client_Public_Certificate>@file_name.pub_cert'
```
{% /tab %}

{% tab label="Windows" %}
```
dssreposconfig "Agent_Client_Public_Certificate>@file_name.pub_cert"
```
{% /tab %}

{% /tabs %}
Copy the public certificate file (file_name**.pub_cert**) to the agent machine.

Add the public certificate file of the hub system to the allowed list. Execute the command dssagentconfig on the agent machine:

{% tabs %}

{% tab label="Direct CLI" %}

dssagentconfig Only_From_Client_Public_Certificates.<em>identifier</em>=@<em>file_name</em>.pub_cert

{% /tab %}

{% tab label="Remote CLI" %}

dssagentconfig -R<em>url</em> -h<em>hub</em> -r<em>agent_host:port -</em>L<em>agent_username</em>/<em>password</em> Only_From_Client_Public_Certificates.<em>identifier</em>=@<em>file_name</em>.pub_cert

{% /tab %}

{% /tabs %}

identifier may be replaced with the actual name of the hub (e.g. myhub1) or any name/text to easily identify the allowed hub.

To verify that the public certificate file of the hub system is added to the allowed list, execute the command dssagentconfig on the hub machine:
```
dssagentconfig -hhub -ragent_host:port -Lagent_username/password Only_From_Client_Public_Certificates
```

If the public certificate file of the hub system is successfully added to the allowed list, the command output will display the name and the certificate.

Set Agent Authentication Mode

Define the agent authentication mode for connecting a hub to the agent. For more information about agent connection authentication mode, see Agent Connection Modes.

Following are the agent connection authentication modes:

All connections require an agent user: In this authentication mode, agent user name and password is required for connecting a hub to the agent.
This is the default agent authentication mode for a newly installed agent.
- This authentication mode requires at least one agent user to be defined (see step 3 - Add Agent User) for the agent.

Allow both anonymous connections and agent user: In this authentication mode, the agent is configured to accept anonymous connections as well as have agent users (with/without AgentAdmin privilege). To connect a hub to the agent anonymously, the client public certificate of the hub must be added to the allowed list of hubs. To add client public certificate of hub, see Limit agent access in step 1.

To enable anonymous access to the agent, use the command dssagentconfig:

{% tabs %}

{% tab label="Direct CLI" %}
```
dssagentconfig Anonymous_Access.allow=true
```
{% /tab %}

{% tab label="Remote CLI" %}
```
dssagentconfig -Rurl -hhub -ragent_host:port -Lagent_username/password Anonymous_Access.allow=true
```
{% /tab %}

{% /tabs %}

Executing this command (without configuring Limit agent access in step 1) will automatically limit agent access to specific hubs. In this case, run the commands mentioned in step 1 Limit agent access to allow specific hubs to access the agent.

When anonymous access to the agent is disabled, the agent authentication mode automatically reverts to the default mode - **All connections require an agent user**.

<details><summary>Disable Anonymous Authentication</summary>

To disable the anonymous access to the agent, use the command [**dssagentconfig**](/docs/dss6-command-line-interface-command-reference-dssagentconfig):

{% tabs %}

{% tab label="Direct CLI" %}
  
```plaintext
dssagentconfig Anonymous_Access.allow=
```

{% /tab %}
  
{% tab label="Remote CLI" %}
```shell
dssagentconfig -R<em>url</em> -h<em>hub</em> -r<em>agent_host:port -</em>L<em>agent_username</em>/<em>password</em> Anonymous_Access.allow=
```

{% /tab %}

{% /tabs %}  
  
</details>

Add Agent User

An agent user is required for authenticating the connection from the hub to the agent. And, also the agent user is required for configuring the agent service from a browser (without initiating the setup mode). For more information about agent users, see Agent Users.

Create an agent user by using the command dssagentuserconfig:
```
dssagentuserconfig -c user_name
```
Supply a password for the agent user when prompted.

The authentication method for the agent user can be defined using the option -A in command dssagentuserconfig. If option -A is not supplied, the agent user will be created with the local authentication method.

The available authentication methods are:

Kerberos
Local
PAM
Plugin
Windows

Command syntax for defining the user authentication method

To create an agent user with Kerberos authentication:

dssagentuserconfig -c -A kerberos <em>kerberos_client_principal</em>

The Kerberos server principal name (Agent_Server_Kerberos_Principal) must be set using the command dssagentconfig:
```
dssagentconfig Agent_Server_Kerberos_Principal=kafka/cloudera510.local@datasourcesolutions.LOCAL
```

For the advanced Kerberos authentication options, see step 4 - Set Advanced Authentication Options.

To create an agent user with Local authentication:
```
dssagentuserconfig -c -A local user_name
```
Supply a password for the agent user when prompted.

The minimum password length for Local user must be 10 characters.

To create an agent user with PAM authentication:

dssagentuserconfig -c -A pam <em>user_name</em>

For the advanced PAM authentication options, see step 4 - Set Advanced Authentication Options.

To create an agent user with Plugin authentication:

dssagentuserconfig -c -A plugin <em>user_name</em>

To create an agent user with Windows authentication:

dssagentuserconfig -c -A windows <em>user_name</em>

Agent Administrator

Optionally, the agent user can be granted agent administration permissions. The AgentAdmin permissions allows an agent user to configure the agent service remotely (e.g. using browser) without initiating the agent setup mode.

To grant the AgentAdmin permission to an agent user, use the command dssagentconfig:
```
dssagentconfig User_Access.agent_user.level=AgentAdmin
```

Set Advanced Authentication Options

This section describes the advanced authentication options/settings available for the agent (used when connecting hub to the agent service). These options affect agent's authentication system only when agent users configured with PAM or Kerberos authentication is involved in the connection.

This step is optional.

Set the required advanced authentication options.

Advanced Authentication Options for PAM

The following options are applicable only when the agent authentication involves an agent user whose Authentication is set to PAM.

PAM Service: By default, DSS Agent uses the PAM service login for authentication. To change this to a user specified PAM service, use the command dssagentconfig:
```
dssagentconfig PAM_Service=PAM_service_name
```

Execute PAM authenticator as different user: To run the PAM authenticator as the specified user instead of the operating system user under which the DSS Agent is running, use the command dssagentconfig:
```
dssagentconfig PAM_Sudo_User=user_name
```

The specified user must have privilege to run the following command: shell $ sudo -n -u PAM_Sudo_User -- $DSS_HOME/lib/dssauthpam PAM_Service

Advanced Authentication Options for Kerberos

The following options are applicable only when the agent authentication involves an agent user whose Authentication is set to Kerberos principal.

The Kerberos authentication is not supported on Windows. So these options are not applicable for the DSS Hub or Agent installed on Windows.

Kerberos server principal: By default, for authentication, DSS Agent uses the default Kerberos server principal of the operating system user under which the DSS Agent is running. To use a user specified Kerberos server principal for authentication instead of the default server principal, use the command dssagentconfig and set value (name of the user specified Kerberos server principal) for the agent property Agent_Server_Kerberos_Principal:
```
dssagentconfig Agent_Server_Kerberos_Principal=kerberos_server_principal
```
Kerberos configuration for agent machine: By default, for authentication, DSS Agent uses the default Kerberos ticket of the operating system user under which the DSS Agent is running. To use a user specified Keytab file for authentication instead of the default Kerberos ticket, use the command dssagentconfig and set value (directory path to the user specified keytab file) for the agent property Agent_Server_Kerberos_Keytab:
```
dssagentconfig Agent_Server_Kerberos_Keytab=keytab_file_path
```