bsh configuration reference

bsh accepts command-line flags, environment variables, and a YAML configuration file. Permission variables become environment variables in the Access Broker process that runs the script.

Commands

For checkout, checkin, and probe, a positional protocol precedes the flags. doctor accepts the protocol through --protocol, not as a positional argument. The method reference lists valid protocol and method combinations.

Configuration precedence

Values resolve in this order, from highest to lowest priority:

1. Command-line flags.
2. Nonempty BSH_* environment variables.
3. Recognized Bridge host variables, for the settings listed under Bridge settings.
4. The YAML file, with params taking precedence over the corresponding structured field.
5. Defaults.

An empty environment variable is treated as absent. Bare names such as TARGET_HOST are not read automatically. An external reference can read a differently named variable or a value in a cloud store.

Flags use hyphens, environment variables use the BSH_ prefix and uppercase underscores, and YAML params keys use lowercase underscores:

Method-specific parameters also accept flag form. Boolean parameters accept true or false. Explicit boolean values work with =, for example --transport-sudo=false.

Literal credentials are rejected in flags. Credential flags accept references such as --transport-password 'env://DATABASE_PASSWORD'. Environment variables, files, and external references can supply the credential itself.

Value types

YAML file

The default path is /etc/britive/bsh.yml. --config overrides BSH_CONFIG, which overrides the default path. The following file uses a local CA bundle and external references for database connection values:

protocol: postgres
method: temp-user
timeout: 25s
transport:
  host: env://DATABASE_HOST
  user: aws-sm://prod/database?key=username&region=us-east-1
  tls_mode: verify-full
  ca_cert_path: /etc/britive/database-ca.pem
params:
  target_database: reporting
  roles: report_reader
  transport_password: aws-sm://prod/database?key=password&region=us-east-1

The permission supplies the requesting user’s identity separately. The database role must already exist. The setup guide describes identity mappings and matching checkout and checkin scripts.

Structured YAML fields are:

bridge.url is the broker API address. bridge.public_url is the user-facing address. A transport password belongs in params.transport_password, usually as a reference. There is no structured transport.password field.

Core and identity settings

Without BSH_USERNAME, the account name comes from the email local part, with non-alphanumeric characters removed and letters converted to lowercase. For example, jane.doe@example.com becomes janedoe. The prefix and length limit then apply.

BSH_USERNAME also accepts a Jinja expression. Its context includes email, domain, local_part, username, session_id, protocol, method, and non-secret params. The rendered name is sanitized and truncated. Credential values are not rendered as templates.

Execution and access duration

Transport settings

The transport performs administrative operations on the target. BSH_TRANSPORT selects it. A method with one supported transport selects that transport automatically. Methods that support local and SSH execution default to local; remote execution requires BSH_TRANSPORT=ssh.

For a VNC service on 5900 managed over SSH, the ports are BSH_TARGET_PORT=5900 and BSH_TRANSPORT_PORT=22. Telnet and NETCONF account management over SSH also need an explicit SSH transport port when the target service uses another port.

SSH

SSH requires an administrative user, a private key or password, and host verification.

WinRM

WinRM requires BSH_TRANSPORT_USER and BSH_TRANSPORT_PASSWORD. BSH_WINRM_HTTPS defaults to true. BSH_WINRM_AUTH accepts ntlm, the default, or basic. BSH_WINRM_CA_CERT_PATH and BSH_WINRM_CA_CERT supply the listener’s trusted CA. BSH_WINRM_INSECURE_SKIP_VERIFY disables certificate verification and defaults to false.

Databases

SQL protocols select the database engine automatically. BSH_ADMIN_DATABASE names the administrative connection database. BSH_TARGET_DATABASE names the grant scope and the database returned to the user. When no administrative database is set, the target database also supplies the connection database. BSH_DB_TLS_MODE overrides BSH_TLS_MODE.

Oracle uses BSH_TARGET_DATABASE as its service name or SID. BSH_ORACLE_CONNECT_TYPE defaults to service_name and also accepts sid.

For NoSQL, BSH_DATABASE is MongoDB’s authentication database or Cassandra’s keyspace. Redis can use an unnamed default administrative user. Database credentials and CA settings otherwise follow the common transport settings.

Kubernetes and directory services

Directory connections use LDAPS on port 636. Other ports use StartTLS unless BSH_TLS_MODE=disable. The default directory port is 389.

Bridge settings

Bridge mode requires Britive Bridge 3.0.0 or later. The Bridge setup guide describes the permission scripts and platform mappings.

Connection addresses and authentication

Bridge supplies these host fallbacks to its colocated broker. On an external broker, set the API URL to Bridge’s HTTPS endpoint. Supply the checkout token through BSH_BRIDGE_BROKER_API_TOKEN or its token-file alternative. This requires Bridge 3.0.2 or later with server.checkout_api_tokens.enabled. See external broker setup.

The public URL receives an https:// prefix when only a hostname is supplied. Trailing slashes are removed.

BSH_BRIDGE_BROKER_API_TOKEN can supply the token directly or through an external reference. BSH_BRIDGE_CA_CERT supplies PEM content instead of a path. BSH_BRIDGE_NATIVE_PORT changes the native connection port returned to the user, independently of the target and transport ports.

Session and login settings

The Bridge login identity resolves from --bridge-username, then BSH_BRIDGE_USERNAME, YAML params.bridge_username, YAML bridge.username, and finally BSH_USER_EMAIL. An empty environment value falls through to the file settings and then the email. Explicit Bridge username overrides require bsh version 0.2.0 or later.

BSH_BRIDGE_USERNAME selects the Bridge login. BSH_USERNAME selects the target account. Setting a Bridge username does not change BSH_USER_EMAIL or the target account name.

Kubernetes exec uses browser access. HTTP, WinRM, and NETCONF use native access. A connection control cannot enable a path that the protocol does not support.

Target connection and session controls

Bridge connects to the target separately from the bsh administrative connection. BSH_TARGET_TLS, BSH_TARGET_CA_CERT, and BSH_TARGET_TLS_SKIP_VERIFY configure that connection. Administrative transport TLS settings do not replace them.

Output and logs

In standard mode, JSON output contains the target username, credential when issued, and connection metadata. --format raw returns only the primary credential, without a trailing newline. Raw output fails for methods that do not issue a credential, such as group membership and role grants.

Bridge output contains the transaction ID and connection details. Target credentials are sent to Bridge. Telnet also returns the target password for the target’s login prompt. A generated Bridge login password is a separate value.

Checkin produces no stdout payload. Diagnostics go to stderr. Combining stderr with stdout corrupts the credential payload.

BSH_LOG_LEVEL accepts debug, info, warn, warning, or error, with info as the default. BSH_LOG_FORMAT accepts text or json, with text as the default. Exit codes and recovery procedures are listed in Troubleshoot bsh.