Configuration and Usage

Understanding the Commander configuration file for automation and CLI usage

Commander Configuration File

When you login to Commander for the first time, a config.jsonfile is created, if one does not exist. When launching Commander as an application, the config file is created at ~/.keeper on MacOS and Linux, and at C:\Users\[USERNAME]\.keeper on Windows. When using Commander from the command line or terminal, the config.json file is created in the current directory, unless the --config option is passed a different location.

Config File Example

{
    "server": "keepersecurity.eu",
    "user": "[e-mail]",
    "password": "your_password_here",
    "private_key": "yaeK4jMeIGNkSR2pi4xf2XGmYM094YMUoE8-QEW9CAA",
    "device_token": "g6RDMxr1t-bcVdBeBpz-xQ",
    "mfa_duration": "forever",
    "proxy": "http://proxy_user:proxy_password@host:port",
    "sso_master_password": false,
    "skip_records": false,
    "debug": false,
    "plugins": [],
    "commands": [],
    "timedelay": 0
}

Config File Options

• server Keeper data center region

  Commander defaults to the US region, so customers hosted in other regions will need to specify a server in the config.

  Region	Property Setting for "server"
  US	https://keepersecurity.com
  EU	https://keepersecurity.eu
  AU	https://keepersecurity.com.au
  GOV	https://govcloud.keepersecurity.us
  CA	https://keepersecurity.ca
  JP	https://keepersecurity.jp

• debug enable or disable detailed crypto output and network logging

  • set to true or false

• plugins Set which password rotation plugin will be loaded.

  • Learn more about password rotation plugins for Commander.

• commands Comma-separated list of Keeper commands to run

• timedelay Run the specified commands every X seconds.

  • example: "timedelay":600 will run the commands every 10 minutes.

• private_key Device private key generated by Commander on a new device. This key is used to encrypt and decrypt vault data.

• device_token Device token generated by the backend for every new device. The device token is used to uniquely identify the device, and it controls the session behavior.

• proxy Proxy URL: schema://[user:password@]host:port where schema

  • http HTTP proxy

  • socks5 SOCKS5 proxy with local DNS

  • socks4 SOCKS4 proxy with local DNS

  • socks4a SOCKS4 proxy with remote DNS

  • socks5h SOCKS5 proxy with remote DNS

• sso_master_password Forces master password login for Enterprise SSO Accounts

• skip_records Prevents syncing of records if the value is set to true. For users with very large vaults, this allows you to login and perform commands without requiring a full sync of records. After login, to force sync records use sync-down --force Example line in config.json: "skip_records":true,

Running Commands from the Configuration File

Using the commands field allows for predetermined commands to be run on login.

Enter a comma-separated list of Keeper Commander commands to be run. Example:

config.json
{
 ...
 "commands": ["sync-down", "file-report -d"]
 ...
}

In this example, it will sync, and then download a report of the available files in the vault.

Configuration File Location

If you start Commander from the binary installer, the config file will be located in the user's home directory in a folder called ".keeper".

• On Mac environments, the configuration file is located in ~/.keeper/config.json

• In Windows environments, the configuration file is located in /Users/{Username}/Documents/.keeper/config.json

If you use Commander from a pip3 or source installation, the configuration file will be created in the current folder where the Commander executable is started from.

You can specify the config file to use when launching Commander, for example:

$ keeper shell --config /path/to/config.json

Authenticating on Multi-Server Environments

In an environment with multiple servers or dynamic servers, you can use the same config.json file for each instance as long as all of the fields are populated, and the device identifier has been "approved".

Example config.json file:

{
    "user": "[e-mail]",
    "password": "RANDOM_LONG_PASSWORD",
    "server": "https://keepersecurity.com",
    "private_key": "yaeK4jMeIGNkSR2pi4xf2XGmYM094YMUoE8-QEW9CAA",
    "device_token": "g6RDMxr1t-bcVdBeBpz-xQ"
}

As long as you have performed a device approval step at least one time, this configuration file can be loaded on any number of servers.

If you plan to distribute this file to multiple instances, we recommend protecting this file through secure storage facilities provided by your cloud infrastructure. We also recommend assigning the user account to a Role Enforcement policy on the Keeper Admin Console that is locked down based on IP range.

Persistent Login Sessions

Persistent Login allows a Commander device to authenticate to Keeper without having to populate the "password" in the configuration file. This is useful for automation scripts or calling Commander from other software.

In order to enable this feature, you need to register the device and turn on the persistent login setting. Once that's done the next time you login with the specified configuration file, the session will be resumed and the user will be automatically logged in. Several tokens are stored in the config.json file in order to resume a session automatically.

Creating a Persistent Login Config

Commands to enable persistent login on a device for 30 days (max):

My Vault> this-device register
My Vault> this-device persistent-login on
My Vault> this-device ip-auto-approve on
My Vault> this-device timeout 30d
My Vault> quit

You can use seconds as the value (e.g. 60 for 60 seconds) or numbers and letters (e.g. 1m for one minute, 5h for 5 hours, and 7d for 7 days).

Also note that typing "logout" will invalidate the session. Just "quit" the Commander session to exit.

Once persistent login is set up on a device, the config.json in the local folder will look something like this:

{
    "private_key": "8n0OqFi9o80xGh06bPzxTV1yLeKa5BdWc7f7CffZRQ",
    "device_token": "R2O5wkajo5UjVmbTmvWnwzf7DK1g_Yf-zZ3dWIbKPOng",
    "clone_code": "retObD9F0-WDABaUUGhP0Q",
    "user": "[e-mail]",
    "server": "keepersecurity.com"
}

The configuration file can be modified to include auto-execution of commands or other features. See the configuration documentation for more details.

You can create any number of persistent login sessions. However, the persistent session option is not intended for dynamic multi-server environments. If you share the exact configuration file on multiple servers, persistent login will fail when attempting to login to the second server.

For multi-server dynamic environments, please refer to the prior section of using a fully populated config file that is distributed to each instance.

Executing Commands with Persistent Login

If you would like to maintain different configurations, you can run Commander with a specified config file. For example, this will open the CLI without prompting for login:

$ keeper --config=my_config.json shell

To leave the CLI, make sure to type "quit" instead of "logout". Typing "logout" will expire the session and you'll need to create a new persistent session config.

Another example would be executing a particular command without prompting for login. In the below example, a new record is created automatically with a single line.

$ keeper --config=config_demo.json "add --login myuser -g --url https://google.com -t 'Google'"

Batch Mode through STDIN

You can batch execute a series of commands and pipe the file to STDIN of Commander. For example, create a text file called test.cmd with the following lines:

add --login=[e-mail] --pass=somemasterpass --url=https://google.com --force "Some Record Title"
upload-attachment --file="/path/to/some/file.txt" "Some Record Title"
share-record --email="[e-mail]" --write "Some Record Title"

To run this file in a batch mode:

cat test.cmd | keeper --batch-mode -

or

keeper test.cmd

Handling Errors

The batch execution is aborted if some command returns failure. Use @ in front of the command to suppress the possible command error.

add --login=[e-mail] --pass=somemasterpass --url=https://google.com --force "Some Record Title"
@upload-attachment --file="/path/to/some/file.txt" "Some Record Title"
share-record --email="[e-mail]" --write "Some Record Title"

Batch Mode in Windows

Following example shows how to execute three commands using Windows command line:

(echo ls -l && echo whoami && echo tree) | keeper --batch-mode -

Combining Batch Mode and Persistent Login

By setting up a persistent login configuration (as described in the previous section), you can execute a series of batch commands without any prompt for login. For example:

$ keeper --config=my_config.json bunch_of_commands.cmd

Batch Mode from the CLI

Keeper supports a batch mode from within the CLI which can conveniently execute commands sequentially.

The command is called "run-batch" and can be executed like below:

My Vault> run-batch -d 10 "C:\My Drive\Keeper\commands.txt"

In this example, each command is executed with a delay of 10 seconds in between.

On Linux environments, the path can also be specified such as:

My Vault> run-batch -d 5 "/path/to/file.txt"

Store Configuration to Protected storage

The sensitive configuration file parameters (user, password, server, device_token, private_key, clone_code) can be optionally stored in 3rd party secrets managers or hardware security modules.

To use protected storage, add config_storage property to your config file. config_storage value has URL format. Please reference the appropriate section below for storage URL format.

Commander supports the following protected storages:

• AWS Secrets Manager

• AWS Key Management Service