dssagentconfig - DSS 6 | Data Source Solutions Documentation

Documentation: dssagentconfig - DSS 6 | Data Source Solutions Documentation

dssagentconfig

Usage

dssagentconfig [-connectopts] [-ojsonfile] [property]... Print specific agent properties, or all if none are specified.
dssagentconfig [-connectopts] [-ijsonfile] [property=[value]]... Set or unset specific repository properties supplied in the jsonfile and/or directly on the command line.
dssagentconfig [-connectopts] -a [-ijsonfile] [property=value]... Replace all the existing agent properties with a new set of properties supplied in the jsonfile and/or directly set on the command line (property=value...).

Description

Command dssagentconfig allows you to configure the DSS Agent service by setting up agent properties including agent connection parameters, user access levels, authentication mode, etc. For a complete list of agent properties, see section Agent Properties. The properties of the agent service are stored in the JSON file dssagent.conf available in the DSS_CONFIG/etc/ directory.

The dssagentconfig command includes two types of options:

general options -a, -i, and -o that allow you to fetch, set, unset, or replace the specific properties of the agent service.
connection options (connectopts) -C, -h, -K, -k, -L, -l, -R, -r, -S, -s that allow you to access the agent service using different connection modes.

For more information, see Agent Connection Modes.

Options

This section describes the options available for command dssagentconfig.

Parameter	Description
`-a`	Replace (delete) all the existing agent properties with a new set of properties. The new set of properties may be supplied directly in the command line (`[property=[value]]...`) or from a file using option `-i` . The following syntaxes are applicable: The following command replaces the current agent properties with the properties supplied in `jsonfile`. `dssagentconfig -a -i jsonfile` The following command replaces the current agent properties with the properties supplied on the command line. `dssagentconfig -a property1=value1 property2=value2 property3=value3...` The following command replaces the current agent properties with the properties supplied in `jsonfile` and on the command line. `dssagentconfig -a -i jsonfile property1=value1 property2=value2 property3=value3...` The properties supplied directly on the command line will override the relevant properties in `jsonfile`. For specific examples, see Replace agent properties.
`-Cagent_pub_cert_fname`	The directory path where a PEM file containing the agent public certificate is located. This is required to verify the identity of the remote DSS Agent by verifying its public certificate. For more information, see the agent property Agent_Server_Public_Certificate.
`-Ex`	Override automatic encoding/decoding of string properties when reading a property from file using `property=@file_name` or when writing a property to file using `property>@file_name`. This option may be required only while setting the property whose argument is base64. When this option is not used, the `default` encoding is base64. Valid values of `x` are: none: no encoding/decoding will be applied. base64: encode a property in the base64 format.
`-hhub`	Hub that connects to the agent.
`-ijsonfile`	Read the agent properties from the JSON file `jsonfile`.
`-Kclient_pub_cert_fname`	The directory path where a PEM file containing the client public certificate is located. This is required to verify the public certificate and private key (option `-k`) of the hub that connects to the agent. For more information, see the repository property Agent_Client_Public_Certificate.
`-kclient_priv_key_fname`	The directory path where a PEM file containing the client private key is located. A password will be prompted for the client private key. For more information, see the repository properties Agent_Client_Private_Key and Agent_Client_Private_Key_Password.
`-Luser/pwd`	Authenticate with the user name (`user`) or user name and password (`user/pwd`) on the agent machine for connecting the hub to the agent. If you do not specify a password `pwd`, it will be prompted for. This option cannot be combined with options `-S` and `-s`. For more information, see the location properties Agent_User and Agent_Password. In the User Interface, this option corresponds to the Add User option in the Agent Service Configuration dialog.
`-lloc`	Location that connects to the agent.
`-ojsonfile`	Write the agent properties to the JSON file `jsonfile`. If no properties are specified on the command line, then all properties are fetched from the dssagent.conf file.
`-Rurl`	Remote hub server. Access the hub server running on a remote machine, via the REST interface. This option is required for remote CLI access. When using this option, command dsslogin should be run first, for authentication.
`-rhost:port`	Agent `host` and `port`. For more information, see the location properties Agent_Host and Agent_Port. In the User Interface, this option corresponds to the Agent Host and Agent Port fields in the Agent Service Configuration dialog.
`-S`	Authenticate using the time-based setup mode. This option cannot be combined with options `-L` and `-s`. For more information, see the agent property Setup_Mode_Timed_Until.
`-stoken`	Authenticate using the token-based setup mode. This option cannot be combined with options `-L` and `-S`. For more information, see the agent properties Setup_Mode_Token_Name and Setup_Mode_Token_Value.
`-Vaccessmeth`	Handle classified data. redact: Redact classified data. storage `default`: Save classified data as they are stored in the hub system. @outputfile: Apply transport encryption, save key to file outputfile. @print: Apply transport encryption using the transport encryption key and display the key in command terminal. @inputfile: Read transport encryption key stored in a inputfile. This can also be a path (relative or absolute) to this file. @prompt: Prompt a user to enter the transport key via keyboard.

Agent Connection Modes

DSS supports connection to a remote agent via the DSS hub (either from a hub machine or any client machine) or through direct network access (not via the DSS hub), which depends on your system configuration.

You can also connect to the agent directly from the machine where the agent is installed. In this case, no connection options are required.

Options -k and -K are required when direct network access is used to the agent with the anonymous authentication mode configured. The agent verifies the public certificate and private key pair of the incoming client (via the agent property Only_From_Client_Public_Certificates). When the anonymous authentication mode is configured, the client (hub server) must present a trusted public certificate and private key pair to the agent to be allowed to establish a connection. The hub server's public certificate and private key are automatically generated and stored in the hub server's repository (repository properties Agent_Client_Public_Certificate and Agent_Client_Private_Key) the first time the hub server repository is created.

Option -C is required to verify the connection is made to the correct agent.

Options -L, -S, and -s are used to authenticate to the agent, only one of them can be used at a time.

If the anonymous authentication mode is configured for the agent, a better practice would be to connect to it via the hub server system using options -R and -r that give access to the client public certificate and private key stored on the hub server (see section Access Via Hub Server System). In this case, options -k and -K are not required.

Direct Network Access

To access an agent via the direct network connection, the following set of connection options can be used.

dssagentconfig <b>-r</b><em>host</em><b>:</b><em>port</em> [<b>-C</b><em>agent_pub_cert_fname</em>] [<b>-k</b><em>client_priv_key_fname</em> <b>-K</b><em>client_pub_cert_fname</em>] [<b>-L</b><em>user</em>[<b>/</b><em>pwd</em>]] [<b>-S</b>] [<b>-s</b><em>token</em>]

Access Via Hub Server System

Omit option -Rurl when connecting to the agent from the hub server machine.

To access an agent configured on an existing location via a hub server system, the following set of connection options can be applied.

dssagentconfig [<b>-R</b><em>url</em>] <b>-h</b><em>hub</em> <b>-l</b><em>loc</em> [<b>-L</b><em>user</em>[<b>/</b><em>pwd</em>]] [<b>-S</b>] [<b>-s</b><em>token</em>]

To access an agent via a hub server system when creating a new location, the following set of connection options can be applied.

dssagentconfig [<b>-R</b><em>url</em>] <b>-h</b><em>hub</em> <b>-r</b><em>host</em><b>:</b><em>port</em> [<b>-C</b><em>agent_pub_cert_fname</em>] [<b>-L</b><em>user</em><b>/</b><em>pwd</em>] [<b>-S</b>] [<b>-s</b><em>token</em>]

Examples

This section provides examples of using the dssagentconfig command.

Example 1. Get agent properties

The following command prints all the properties of the agent configured on location myloc (when connecting to the agent from the hub server machine):
```
dssagentconfig -h dss_hub -l myloc -L admin/admin
```
The following command prints the values of properties Anonymous_Access and User_Access (when connecting to the agent directly on the agent machine):
```
dssagentconfig Anonymous_Access User_Access
```

Example 2. Set agent properties

The following command sets property Anonymous_Access to true:
```
dssagentconfig Anonymous_Access.allow=true
```
The following command sets the agent properties specified in the agent_props.json file:
```
dssagentconfig -i agent_props.json
```
The following command sets properties specified in the agent_props.json file as well as property Anonymous_Access specified on the command line.
```
dssagentconfig -i agent_props.json Anonymous_Access.allow=true
```

If the agent_props.json file contains properties that are already set for the agent, option -i will override these properties.

For example, the following properties are currently set for the agent: [**Agent_Server_Private_Key**](/docs/dss6-property-reference-agent-properties#agentserverprivatekey), [**Agent_Server_Private_Key_Password**](/docs/dss6-property-reference-agent-properties#agentserverprivatekeypassword), [**Anonymous_Access**](/docs/dss6-property-reference-agent-properties#anonymousaccess), and [**Only_From_Client_Public_Certificates**](/docs/dss6-property-reference-agent-properties#onlyfromclientpubliccertificates). And, if the **agent_props.json** file contains properties [**Anonymous_Access**](/docs/dss6-property-reference-agent-properties#anonymousaccess) and
[**Only_From_Client_Public_Certificates**](/docs/dss6-property-reference-agent-properties#onlyfromclientpubliccertificates). Then option `-<b>i</b>` will override the currently set values of properties [**Anonymous_Access**](/docs/dss6-property-reference-agent-properties#anonymousaccess) and [**Only_From_Client_Public_Certificates**](/docs/dss6-property-reference-agent-properties#onlyfromclientpubliccertificates).

Example 3. Unset agent properties

The following command unsets property Anonymous_Access:

dssagentconfig Anonymous_Access=

Example 4. Replace agent properties

The following command replaces the current agent properties with the properties supplied in the agent_props.json file.
```
dssagentconfig -a -i agent_props.json
```

The following command replaces the current agent properties with the Agent_Server_Public_Certificate and Agent_Server_Private_Key properties.

dssagentconfig -a Agent_Server_Public_Certificate=<em>agent_server_public_certificate</em> Agent_Server_Private_Key=<em>agent_server_private_key</em>

The following command replaces the current agent properties with the properties supplied in the agent_props.json file and property Setup_Mode_Timed_Until.
```
dssagentconfig -a -i agent_props.json Setup_Mode_Timed_Until=now+60m
```

The properties supplied directly on the command line will override the relevant properties in the agent_props.json file.

Examples for Starting and Terminating Setup Mode

Example 1. Start time-based setup mode

The following command enables the one-hour setup mode for configuring the agent service. For more information about the time that can be specified, see the agent property Setup_Mode_Timed_Until.

dssagentconfig Setup_Mode_Timed_Until=now+1h

Example 2. Terminate time-based setup mode

The following command disables the time-based setup mode for configuring the agent service. For more information about the time that can be specified, see the agent property Setup_Mode_Timed_Until.

dssagentconfig Setup_Mode_Timed_Until=

Example 3. Start token-based setup mode

The following command line enables the token-based setup mode for configuring the agent service.

dssagentconfig Setup_Mode_Token_Name=token_name Setup_Mode_Token_Value=token_value

Example 4. Terminate token-based setup mode

The following command disables the token-based setup mode for configuring the agent service.

dssagentconfig Setup_Mode_Token_Name= Setup_Mode_Token_Value=