Profile Command

Setup and initialization of the Keeper Secrets Manager device profile

Description: Initialize and manage device profiles. Use profiles to support multiple Keeper Secrets Manager environments on the same device.

Parameters:

Sub-command and options to run

format: ksm profile <sub-command>

Sub-Commands:

Sub-Command	Description
init	Initialize a new client device profile
setup	Set up a new profile from a third-party external secrets manager such as AWS.
list	List all profiles and identify the active profile.
export	Export a configuration profile
import	Create a new configuration from an exported encrypted profile
active	Set the active configuration profile.
delete	Delete a profile

init

Initialize a client device profile.

ksm profile init

When the CLI is installed with the keyring extra, ksm profile init stores the new profile in the operating system's native secure storage (macOS Keychain, Windows Credential Manager, or Linux Secret Service). The CLI does not create a keeper.ini file.

To store the profile in a keeper.ini file instead, pass the --ini-file <FILENAME> option. If the keyring extra is not installed, the CLI prints a warning and falls back to a keeper.ini file, created in your current working directory (or in your home directory for the Windows and macOS binary applications).

Locked keyring (SSH and headless sessions): If the keyring extra is installed but the OS keyring is locked and cannot be unlocked without an interactive session (for example, when connecting over SSH without a display server available, such as a locked GNOME Keyring), the CLI exits with an error instead of silently returning no profiles. Pass --ini-file <PATH> to read from a keeper.ini file, or set the KSM_CONFIG environment variable to a base64-encoded configuration string.

When a keeper.ini file is used, the CLI searches these locations in order and uses the first one it finds:

• The current directory
• The path defined by the environmental variable KSM_INI_DIR
• The user's home directory

  • ${HOME}
  • ${HOME}/.config/ksm
  • ${HOME}/.keeper
  • $env:USERPROFILE
• Various system directories

  • /etc
  • /etc/ksm
  • /etc/keeper
  • $env:APPDATA/Keeper
  • $env:ProgramData/Keeper
  • $env:ProgramFiles/Keeper

A keeper.ini in the current directory takes precedence over KSM_INI_DIR. If a keeper.ini file exists in the current directory, the CLI uses it even when KSM_INI_DIR points elsewhere, and prints a warning naming both paths. Pass --ini-file with the full path to force the intended file, or set KSM_INI_DIR_SKIP_CONFLICT_WARNING=TRUE to silence the warning without changing this behavior.

Parameters:

• -t, --token <token> one-time access token
• -h, --hostname <XX> destination region

  Defaults to US region. Customers hosted in other regions must set this value:

  • US (United States)
  • EU (Europe)
  • AU (Australia)
  • JP (Japan)
  • CA (Canada)
  • US_GOV (GovCloud)
• --ini-file <FILENAME> save the new profile to this file
• -p, --profile-name <NAME> set profile name If not provided, the profile will be set as "_default"

Typically, you will initialize the KSM CLI with a token created in the Keeper Vault or in Keeper Commander. For example:

ksm profile init --token XX:XXXXXXXX

To prevent the token from appearing on the command line, use the KSM_CLI_TOKEN environment variable. For example:

ksm profile init --ini-file=/tmp/custom.ini --profile-name=non_default

The KSM_CLI_TOKEN environment variable lets you select a custom INI file and profile name (to create/overwrite). The --token option overrides it.

You can create a token from the Commander CLI or from the Keeper Vault interface, as described in the Quick Start Guide. For example:

My Vault> secrets-manager client add --app MyApplicationName

setup

Set up a new profile that loads from external storage such as AWS Secrets Manager. This is ideal when you run the Keeper Secrets Manager CLI from a cloud instance. This authentication method adds extra security.

You can integrate with external storage providers such as AWS in three ways:

• EC2 instance role (recommended)
• AWS profile credentials
• AWS custom keys

Method 1: EC2 instance role

For this method, install Keeper Secrets Manager CLI on an EC2 instance that is configured with a role that has permission to read specific AWS Secrets Manager secrets. Create an EC2 role policy with the least permission needed to read only specific keys. Learn more about AWS Secrets Manager access controls.

To initialize the KSM CLI profile on an EC2 instance using the AWS EC2 instance role:

ksm profile setup --type=aws

This creates a keeper.ini file that defines the secret key in AWS. For example:

....

[_default]
storage = aws
provider = ec2instance
secret = ksm-config

The CLI assumes the secret key is named ksm-config by default. To use a different key, edit the keeper.ini file or use the --secret option. For example:

ksm profile setup --type=aws --secret my-ksm-config

Method 2: AWS profile credentials

The KSM CLI can be configured to use a specific AWS profile that has been previously initialized on this device with the aws configure command.

For this method, assign the AWS profile credentials to a role that can only read specific keys from AWS Secrets Manager. Learn more about AWS Secrets Manager access controls.

For example:

ksm profile setup --type=aws --secret=ksm-config --credentials=profile --credentials-profile=default

Method 3: AWS custom keys

The KSM CLI can use a specific AWS Access Key / Secret Key pair. The CLI stores the Access Key and Secret Key locally in the keeper.ini file.

For example:

ksm profile setup --type=aws --secret=ksm-config --credentials=keys --aws-access-key-id XXX --aws-secret-access-key XXX --region XXX

The --fallback flag lets you fall back to the default profile (from the AWS local configuration) if the initial credentials fail.

Finishing the KSM CLI setup

To complete the setup, generate a base64 KSM configuration value from the Keeper Vault interface or the Keeper Commander CLI, as described in the Quick Start Guide.

For example, use the following Commander CLI command:

My Vault> secrets-manager client add --app "My KSM App" --config-init b64

Successfully generated Client Device
====================================

Initialized Config: [Base64 Config....]

Copy the configuration for the next step.

To allow this KSM device to authenticate against Keeper Secrets Manager, upload the base64 configuration value to AWS Secrets Manager. For example, using the AWS CLI:

aws secretsmanager create-secret --name ksm-config --secret-string '[Base64 Config]'

Verify that the KSM CLI can access secrets from your vault:

ksm secret list

 UID                     Record Type          Title
 ----------------------- -------------------- --------------------------
 n9SdOX1cEyMj9Ttj3lsjYQ  pamUser              IAM Account: demouser
 WfxgS6E_bY_tzdIChYIsAA  login                Amazon AWS - john
 toAfybW5SsbhRT9LtZ7oyg  serverCredentials    QA Server

Additional setup options

--ini-file <FILENAME> save the new profile to this file instead of keeper.ini. -p, --profile-name <NAME> set profile name. If not provided, the profile will be set as "_default"

list

List all available profiles for the current Client Device.

ksm profile list

Example:

$ ksm profile list

  Active   Profile
 ======== ===============
           Production
  *        Test Server 1
           Test Server 2
           Local Dev

export

Export the current profile as a base64-encoded string.

ksm profile export [--plain] [--file-format] [PROFILE NAME]

Optional parameters:

• --plain Export the profile without base64-encoding.
• --file-format Export a profile to a specific file format. Available formats are:

  • ini - To be used by another instance of the CLI.
  • json - Can be used by the CLI and other Developer SDKs.

Example

$ ksm profile export my_profile

If the KSM configuration uses an external storage provider, the profile cannot be exported.

import

Import a client device profile from an encrypted base64-encoded string.

ksm profile import [--output-file "INI filename"] <BASE64 CONFIG>

Optional parameters:

• --output-file <INI filename> Path to the INI configuration file. If not set, the CLI creates the file in the current directory.

$ ksm profile import --output-file=my_profile BASE64_ENC_CONFIG

active

Set the currently active profile for this client device.

ksm profile active <PROFILE NAME>

Example:

$ ksm profile active production

production is now the active profile.

delete

Delete a profile from the current Client Device. The CLI removes the profile from whichever storage holds it (OS keyring or keeper.ini). If the deleted profile was the active profile, the CLI clears the active-profile pointer.

ksm profile delete <PROFILE NAME>

Example:

$ ksm profile delete "Test Server 1"

Profile Test Server 1 has been deleted.

Profiles within Containers

If you run the CLI in a container, you may not be able to initialize a profile. If the CLI finds no INI config file and KSM_TOKEN is set, it generates a default profile. The CLI creates the INI config file in the current working directory. Set KSM_INI_DIR to use a different directory.

Default INI Filename

The default INI filename is keeper.ini. Set KSM_INI_FILE to use a different name. Use KSM_INI_DIR and KSM_INI_FILE together to set a custom directory and filename for the INI configuration file.