Configuring HVR Agent From CLI

This section describes the steps to configure the HVR Agent service from the Command Line Interface (CLI). For steps to configure the agent service from a browser, see Configuring HVR 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 HVR 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 hvrreposconfig on the hub machine that needs to be added to the allowed list:
```
hvrreposconfig 'Agent_Client_Public_Certificate>@file_name.pub_cert'
```
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 hvragentconfig on the agent machine:
```
hvragentconfig Only_From_Client_Public_Certificates.identifier=@file_name.pub_cert
```
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 hvragentconfig on the hub machine:
```
hvragentconfig -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 hvragentconfig:
```
hvragentconfig Anonymous_Access.allow=true
```
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.
Disable Anonymous Authentication
To disable the anonymous access to the agent, use the command hvragentconfig:
```
hvragentconfig Anonymous_Access.allow=
```

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 hvragentuserconfig:
```
hvragentuserconfig -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 hvragentuserconfig. 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:
```
hvragentuserconfig -c -A kerberos kerberos_client_principal
```
- The Kerberos server principal name (Agent_Server_Kerberos_Principal) must be set using the command hvragentconfig:
```
hvragentconfig Agent_Server_Kerberos_Principal=kafka/cloudera510.local@fivetran.LOCAL
```
For the advanced Kerberos authentication options, see step 4 - Set Advanced Authentication Options.
To create an agent user with Local authentication:
```
hvragentuserconfig -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:
```
hvragentuserconfig -c -A pam user_name
```
For the advanced PAM authentication options, see step 4 - Set Advanced Authentication Options.
To create an agent user with Plugin authentication:
```
hvragentuserconfig -c -A plugin user_name
```

To create an agent user with Windows authentication:
```
hvragentuserconfig -c -A windows user_name
```

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 hvragentconfig:
```
hvragentconfig 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, HVR Agent uses the PAM service login for authentication. To change this to a user specified PAM service, use the command hvragentconfig:
```
hvragentconfig 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 HVR Agent is running, use the command hvragentconfig:
```
hvragentconfig PAM_Sudo_User=user_name
```
The specified user must have privilege to run the following command:
$ sudo -n -u PAM_Sudo_User -- $HVR_HOME/lib/hvrauthpam 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 HVR Hub or Agent installed on Windows.

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