Understanding the Commander configuration file for automation and CLI usage
When you login to Commander for the first time, a config.json
file 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.
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,
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:
In this example, it will sync, and then download a report of the available files in the vault.
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:
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:
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 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.
Commands to enable persistent login on a device for 30 days (max):
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:
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.
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:
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.
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:
To run this file in a batch mode:
or
Handling Errors
The batch execution is aborted if some command returns failure. Use @
in front of the command to suppress the possible command error.
Batch Mode in Windows
Following example shows how to execute three commands using Windows command line:
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 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:
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:
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:
Protecting configuration with AWS Secrets Manager
Amazon AWS Secrets Manager can be utilized on an EC2 instance hosting Keeper Commander in order to protect and store the configuration data.
The AWS Secrets Manager protected storage resource URL format is as follows:
Example:
aws-sm://us-west-2/commander/config
The secret name should contain URL-safe characters and not start with forward slash /
Keeper Commander requires the following access permissions to the secret resource
secretsmanager:GetSecretValue
secretsmanager:PutSecretValue
Example AWS policy granting access to secret
Keeper Commander installed with pip
requires boto3
package to present in the virtual environment
pip install boto3
Protecting configuration with AWS Secrets Manager
Amazon AWS Key Management Service can be utilized on an EC2 instance hosting Keeper Commander in order to protect and store the configuration data.
The AWS Key Management Service protected storage resource URL format is as follows:
Example:
aws-kms://us-east-1/12345678-abcd-1234-dcba-123456789012
aws-kms://eu-west-1/alias/key
The secret name should contain URL-safe characters
Keeper Commander requires "key users policy" to be granted to AWS user or role.