# Broker CLI reference


The Amazon DCV Session Manager broker is a command-line interface (CLI) tool that provides administrative control over the Session Manager. This reference covers the complete set of CLI commands available for managing sessions, users, resources, and other aspects of the Session Manager. Administrators can automate routine management tasks, troubleshoot issues, and optimize the performance of their Amazon DCV infrastructure.

Use the following commands if you use an external authentication server to generate OAuth 2.0 access tokens:
+ [register-auth-server](register-auth-server.md)
+ [list-auth-servers](list-auth-servers.md)
+ [unregister-auth-server](unregister-auth-server.md)

Use the following commands if you use the Session Manager broker as the OAuth 2.0 authentication server. 
+ [register-api-client](register-api-client.md)
+ [describe-api-clients](describe-api-clients.md)
+ [unregister-api-client](unregister-api-client.md)
+ [renew-auth-server-api-key](renew-auth-server-api-key.md)

Use the following commands to manage the Session Manager agent.
+ [generate-software-statement](generate-software-statement.md)
+ [describe-software-statements](describe-software-statements.md)
+ [deactivate-software-statement](deactivate-software-statement.md)
+ [describe-agent-clients](describe-agent-clients.md)
+ [unregister-agent-client](unregister-agent-client.md)

Use the following commands to manage the DCV server - DNS names mapping file.
+ [register-server-dns-mappings](register-server-dns-mappings.md)
+ [describe-server-dns-mappings](describe-server-dns-mappings.md)

# register-auth-server


Registers an external authentication server for use with the broker.

By default, Session Manager uses the broker as the authentication server to generate OAuth 2.0 access tokens. If you use the broker as the authentication server, no additional configuration is required.

However, if you choose to use an external authentication server, such as Active Directory or Amazon Cognito, you must use this command to register the external authentication server.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Options
](#options)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker register-auth-server --url  server_url.well-known/jwks.json
```

## Options


**`--url`**  
The URL of the external authentication server to be used. You must append `.well-known/jwks.json` to the authentication server URL.  
Type: String  
Required: Yes

## Example


The following example registers an external authentication server with a URL of `https://my-auth-server.com/`.

**Command**

```
sudo -u root dcv-session-manager-broker register-auth-server --url https://my-auth-server.com/.well-known/jwks.json
```

**Output**

```
Jwk url registered.
```

# list-auth-servers


Lists the external authentication servers that have been registered.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Output
](#output)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker list-auth-servers
```

## Output


**`Urls`**  
The URLs of the registered external authentication servers.

## Example


The following example lists all external authentication servers that have been registered.

**Command**

```
sudo -u root dcv-session-manager-broker list-auth-servers
```

**Output**

```
Urls: [ "https://my-auth-server.com/.well-known/jwks.json" ]
```

# unregister-auth-server


Unregisters an external authentication server. After you unregister an external authentication server, it can no longer be used to generate OAuth 2.0 access tokens.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Options
](#options)
+ [

## Output
](#output)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker unregister-auth-server --url  server_url.well-known/jwks.json
```

## Options


**`--url`**  
The URL of the external authentication server to unregister. You must append `.well-known/jwks.json` to the authentication server URL.  
Type: String  
Required: Yes

## Output


**`Url`**  
The URL of the unregistered external authentication server.

## Example


The following example registers an external authentication server with a URL of `https://my-auth-server.com/`.

**Command**

```
sudo -u root dcv-session-manager-broker unregister-auth-server --url https://my-auth-server.com/.well-known/jwks.json
```

**Output**

```
Jwk urlhttps://my-auth-server.com/.well-known/jwks.json unregistered
```

# register-api-client


Registers a Session Manager client with the broker and generates client credentials that can be used by the client to retrieve an OAuth 2.0 access token, which is needed to make API requests.

**Important**  
Ensure that you store the credentials in a safe place. They can't be recovered later.

This command is used only if the broker is used as the OAuth 2.0 authentication server.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Options
](#options)
+ [

## Output
](#output)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker register-api-client --client-name client_name
```

## Options


**`--name`**  
A unique name used to identify the Session Manager client.  
Type: String  
Required: Yes

## Output


**`client-id`**  
The unique client ID to be used by the Session Manager client to retrieve an OAuth 2.0 access token.

**`client-password`**  
The password to be used by the Session Manager client to retrieve an OAuth 2.0 access token.

## Example


The following example registers a client named `my-sm-client`.

**Command**

```
sudo -u root dcv-session-manager-broker register-api-client --client-name my-sm-client
```

**Output**

```
client-id: 21cfe9cf-61d7-4c53-b1b6-cf248EXAMPLE
client-password: NjVmZDRlN2ItNjNmYS00M2QxLWFlZmMtZmNmMDNkMEXAMPLE
```

# describe-api-clients


Lists the Session Manager clients that have been registered with the broker.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Output
](#output)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker describe-api-clients
```

## Output


**`name`**  
The unique name of the Session Manager client.

**`id`**  
The unique ID of the Session Manager client.

**`active`**  
Indicates the status of the Session Manager client. If the client is active, the value is `true`; otherwise, it's `false`.

## Example


The following example lists the registered Session Manager clients.

**Command**

```
sudo -u root dcv-session-manager-broker describe-api-clients
```

**Output**

```
Api clients
[ {
"name" : "client-abc",
"id" : "f855b54b-40d4-4769-b792-b727bEXAMPLE",
"active" : false
}, {
"name" : "client-xyz",
"id" : "21cfe9cf-61d7-4c53-b1b6-cf248EXAMPLE",
"active" : true
}]
```

# unregister-api-client


Deactivates a registered Session Manager client. A deactivated Session Manager client can no longer use its credentials to retrieve OAuth 2.0 access tokens.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Options
](#options)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker unregister-api-client --client-id client_id
```

## Options


**`--client -id`**  
The client ID of the Session Manager client to deactivate.  
Type: String  
Required: Yes

## Example


The following example deactivates a Session Manager client with a client ID of `f855b54b-40d4-4769-b792-b727bEXAMPLE`.

**Command**

```
sudo -u root dcv-session-manager-broker unregister-api-client --client-id f855b54b-40d4-4769-b792-b727bEXAMPLE
```

**Output**

```
Client f855b54b-40d4-4769-b792-b727bEXAMPLE unregistered.
```

# renew-auth-server-api-key


Renews the public and private keys used by the broker to sign the OAuth 2.0 access tokens that are vended to the Session Manager client. If you renew the keys, then you must provide the new private key to the developer, as it is needed to make API requests.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker renew-auth-server-api-key
```

## Example


The following example renews the public and private keys.

**Command**

```
sudo -u root dcv-session-manager-broker renew-auth-server-api-key
```

**Output**

```
Keys renewed.
```

# generate-software-statement


Generates a software statement.

Agents must be registered with the broker to enable communication. Agents need a software statement in order to register with the broker. After the agent has a software statement, it can automatically register itself with the broker by using the [OAuth 2.0 Dynamic Client Registration Protocol](https://tools.ietf.org/html/rfc7591). After the agent has registered with the broker, it receives a client ID and client secret that it uses to authenticate with the broker.

The broker and agent receive and use a default software statement when they're first installed. You can continue to use the default software statement, or you can choose to generate a new one. If you generate a new software statement, you must place the software statement into a new file on the agent, and then add the file path to the `agent.software_statement_path` parameter in the `agent.conf` file. After you have done this, stop and restart the agent so that it can use the new software statement to register with the broker.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Output
](#output)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker generate-software-statement
```

## Output


**`software-statement`**  
The software statement.

## Example


The following example generates a software statement.

**Command**

```
sudo -u root dcv-session-manager-broker generate-software-statement
```

**Output**

```
software-statement: ewogICJpZCIgOiAiYjc1NTVhN2QtNWI0MC00OTJhLWJjOTUtNmUzOWNhYzkxMDcxIiwKICAiYWN0aXZlIiA6IHRydWUsCiAgImlzc3VlZEF0IiA6IDE1OTY3OTU4ODEuMDYxMDAwMDAwLAogICJicm9rZXJWZXJzaW9uIiA6ICIxLjAuMCIKfQ==
```

# describe-software-statements


Describes the existing software statements.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Output
](#output)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker describe-software-statements
```

## Output


**`software-statement`**  
The software statement.

**`issued-at`**  
The date and time the software was generated.

**`is-active`**  
The current state of the software statement. `true` if the software statement is active; otherwise it's `false`.

## Example


The following example generates a software statement.

**Command**

```
sudo -u root dcv-session-manager-broker describe-software-statements
```

**Output**

```
Software Statements
[ {
"software-statement" : "ewogICJpZCIgOiAiYmEEXAMPLEYtNzUwNy00YmFhLTliZWItYTA1MmJjZTE3NDJjIiwKICAiaXNzdWVkQXQiIDogMTU5NjY0MTkxMiEXAMPLEDAwMDAsCiAgImJyb2tlclZlcnNpb24iIDogIjEuMC4wIiwKICAiYWN0aXZlEXAMPLEydWUKfQ==",
"issued-at" : "2020.08.05 15:38:32 +0000",
"is-active" : "true"
}, {
"software-statement" : "EXAMPLEpZCIgOiAiYjc1NTVhN2QtNWI0MC00OTJhLWJjOTUtNmUzOWNhYzkxMDcxIiwKICAiaXNzdWEXAMPLEDogMTU5Njc5NTg4MS4wNjEwMDAwMDAsCiAgImJyb2tlclZlcnNpb24iIDogIjEuMC4wIiwKICAiYWN0aXZlIiA6IHRydEXAMPLE",
"issued-at" : "2020.08.07 10:24:41 +0000",
"is-active" : "true"
} ]
```

# deactivate-software-statement


Deactivates a software statement. When you deactivate a software statement, it can no longer be used for agent registrations.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Options
](#options)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker deactivate-software-statement --software-statement software_statement
```

## Options


**`--software-statement`**  
The software statement to deactivate.  
Type: String  
Required: Yes

## Example


The following example deactivates a software statement.

**Command**

```
sudo -u root dcv-session-manager-broker deactivate-software-statement --software-statement EXAMPLEpZCIgOiAiYjc1NTVhN2QtNWI0MC00OTJhLWJjOTUtNmUzOWNhYzkxMDcxIiwKICAiaXNEXAMPLEQiIDogMTU5Njc5NTg4MS4wNjEwMDAwMDAsCiAgImJyb2tlclZlEXAMPLEiIDogIjEuMC4wIiwKICAiYWN0aXZlIiA6IHRydEXAMPLE
```

**Output**

```
Software statement EXAMPLEpZCIgOiAiYjc1NTVhN2QtNWI0MC00OTJhLWJjOTUtNmUzOWNhYzkxMDcxIiwKICAiaXNEXAMPLEQiIDogMTU5Njc5NTg4MS4wNjEwMDAwMDAsCiAgImJyb2tlclZlEXAMPLEiIDogIjEuMC4wIiwKICAiYWN0aXZlIiA6IHRydEXAMPLE deactivated
```

# describe-agent-clients


Describes the agents that are registered with the broker.

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Output
](#output)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker describe-agent-clients
```

## Output


**`name`**  
The name of the agent.

**`id`**  
The unique ID of the agent.

**`active`**  
The state of the agent. `true` if the agent is active; otherwise it's `false`.

## Example


The following example describes the agents.

**Command**

```
sudo -u root dcv-session-manager-broker describe-agent-clients
```

**Output**

```
Session manager agent clients
[ {
"name" : "test",
"id" : "6bc05632-70cb-4410-9e54-eaf9bEXAMPLE",
"active" : true
}, {
"name" : "test",
"id" : "27131cc2-4c71-4157-a4ca-bde38EXAMPLE",
"active" : true
}, {
"name" : "test",
"id" : "308dd275-2b66-443f-95af-33f63EXAMPLE",
"active" : false
}, {
"name" : "test",
"id" : "ce412d1b-d75c-4510-a11b-9d9a3EXAMPLE",
"active" : true
} ]
```

# unregister-agent-client


Unregister an agent from the broker. 

**Topics**
+ [

## Syntax
](#sytnax)
+ [

## Options
](#options)
+ [

## Example
](#example)

## Syntax


```
sudo -u root dcv-session-manager-broker unregister-agent-client --client-id client_id
```

## Options


**`--client-id`**  
The ID of the agent to unregister.  
Type: String  
Required: Yes

## Example


The following example unregisters an agent.

**Command**

```
sudo -u root dcv-session-manager-broker unregister-agent-client --client-id 3b0d7b1d-78c7-4e79-b2e1-b976dEXAMPLE
```

**Output**

```
agent client 3b0d7b1d-78c7-4e79-b2e1-b976dEXAMPLE unregistered
```

# register-server-dns-mappings


Register the DCV Servers - DNS names mappings coming from a JSON file.

## Syntax


```
sudo -u root dcv-session-manager-broker register-server-dns-mappings --file-path file_path
```

## Options


**`--file-path`**  
The path of the file containing the DCV Servers - DNS names mappings.  
Type: String  
Required: Yes

## Example


The following example registers the DCV Servers - DNS names mappings from file /tmp/mappings.json.

**Command**

```
sudo -u root dcv-session-manager-broker register-server-dns-mappings --file-path /tmp/mappings.json
```

**Output**

```
 Successfully loaded 2 server id - dns name mappings from file /tmp/mappings.json
```

# describe-server-dns-mappings


Describe the currently available DCV Servers - DNS names mappings.

## Syntax


```
sudo -u root dcv-session-manager-broker describe-server-dns-mappings
```

## Output


**`serverIdType`**  
The type of the server Id.

**`serverId`**  
The unique ID of the Server.

**`dnsNames`**  
The internal and external dns names    
**`internalDnsNames`**  
The internal dns names  
**`externalDnsNames`**  
The external dns names

## Example


The following example lists the registered DCV Servers - DNS names mappings.

**Command**

```
sudo -u root dcv-session-manager-broker describe-server-dns-mappings
```

**Output**

```
 [ 
	{
		"serverIdType" : "Id",
		"serverId" : "192.168.0.1",
		"dnsNames" : {
			"internalDnsName" : "internal1",
			"externalDnsName" : "external1"
		}
	}, 
	{
		"serverIdType" : "Host.Aws.Ec2InstanceId",
		"serverId" : "i-0648aee30bc78bdff",
		"dnsNames" : {
			"internalDnsName" : "internal2",
			"externalDnsName" : "external2"
		}
	} 
 ]
```