Troubleshoot bsh

Run diagnostic commands as the same operating-system user and in the same container or host environment as the Access Broker permission script. Differences in environment variables, mounted files, cloud identity, and network access can explain a command that works in an interactive shell but fails in the broker.

Identify the failing operation

command -v bsh
bsh version
bsh probe

bsh probe ssh --method ephemeral-key

bsh doctor --protocol ssh --method ephemeral-key

Resolve a configuration error

Check the highest-priority value first. Flags override BSH_* environment variables, which override the YAML file. Recognized Bridge host variables sit between the BSH_* values and YAML.

For an unexpected username, inspect BSH_USERNAME, BSH_USER_EMAIL, and the username prefix and length settings. For a boolean error, use an accepted value such as true or false. For a timeout error, use duration units such as 25s.

If a remote SSH permission selects local, set BSH_TRANSPORT=ssh. Methods with both local and SSH support default to local execution.

If a credential flag is rejected, replace its literal value with an environment variable, _FILE setting, or external reference:

bsh probe postgres --method temp-user \
	--transport-password 'env://DATABASE_PASSWORD'

The command still needs the permission’s other database and identity settings.

Resolve an external value error

1. Check that the reference uses ://, such as env://DATABASE_HOST.
2. Confirm that the variable, file, secret, and requested version exist in the broker’s environment.
3. Confirm that the broker identity can read the source. For AWS, also confirm the region. For Vault, confirm VAULT_ADDR and token availability.
4. If the reference uses ?key=, confirm that the value is a JSON object with that top-level field.
5. Check that the fetched value matches the setting’s type. A port needs an integer. A list needs a delimited string.

Do not expect a fetched value that contains another reference to resolve again. See External value references for each provider’s syntax and authentication requirements.

Resolve a target connection failure

Check BSH_TARGET_HOST, the target service port, and BSH_TRANSPORT_PORT. For RDP provisioning, the administrative connection uses WinRM. For VNC provisioning over SSH, the administrative connection normally uses port 22, independently of VNC’s service port.

For an SSH host-key mismatch, verify the target’s key through your approved inventory or management channel, then update the configured pin. For a certificate error, verify the CA bundle and the hostname in the certificate.

If authentication succeeds but provisioning fails, check the administrative account’s privileges. SSH methods that manage users need the relevant operating-system permissions. A non-root account using BSH_TRANSPORT_SUDO=true needs passwordless sudo. Database and directory methods need permission to create accounts, change passwords, or alter memberships for the chosen method.

Resolve a Bridge failure

Confirm that the deployment runs Bridge 3.0.0 or later. Check the broker API address and token separately from the public URL:

• BSH_BRIDGE_BROKER_API_URL or BRIDGE_BROKER_API_URL must be reachable by the broker.
• The broker token file must be readable by the broker’s operating-system user.
• BSH_BRIDGE_URL or BRIDGE_SERVER_TELEMETRY_REVIEW_BASE_URL must identify the origin that users can reach.
• BSH_TRANSACTION_ID must receive the platform transaction ID during both checkout and checkin.

If a returned connection address is wrong, inspect --bridge-url before the environment values. That flag has the highest priority. The host fallback applies only when the broker receives BRIDGE_SERVER_TELEMETRY_REVIEW_BASE_URL from its Bridge deployment.

If Bridge receives an email when the user needs a different login, check BSH_BRIDGE_USERNAME and the identity line in bsh doctor output. For BSH_BRIDGE_USERNAME=will, that line must report identity: will. The target account is controlled separately by BSH_USERNAME.

If the override still reports the email, run bsh version inside the broker’s container. The fix requires bsh version 0.2.0 or later. Update the broker image and redeploy it if the installed version is older. Updating an executable on the host does not update a copy inside a container.

If Bridge rejects authentication settings, check BSH_NATIVE_AUTH, BSH_BRIDGE_AUTH_PASSWORD, and BSH_LDAP_AUTH_PASSTHROUGH. Bridge credentials and LDAP password passthrough conflict. For a disabled connection path, confirm that at least one path supported by the protocol remains enabled.

Recover from checkin or rollback failure

Use the same protocol, method, mode, target, identity, and session values as the original checkout. Correct the reported connection or permission error, then retry checkin through the platform.

In Bridge mode, checkin ends the Bridge checkout before revoking target access. If Bridge cannot be reached, restore that connection before retrying. If Bridge rejects checkout after bsh has provisioned target access, bsh attempts to revoke the access. A rollback error means that an operator must verify and remove any remaining target access.

Check the method’s revocation behavior before changing cleanup settings. Shared-password rotation affects other users of that account. SSH key cleanup affects overlapping checkouts for the same email on the same target account.

Interpret the exit status

Use the logged category and remediation with the exit status:

Verify

Repeat the diagnostic that failed. Then use a test permission to complete checkout and checkin. Confirm that checkout returns the intended credential or connection details and that checkin revokes access as described for the method. For Bridge permissions, also confirm that the session ends.

If the failure persists, provide support with bsh version, the protocol and method, the error code and category, the timestamp, and sanitized diagnostic output.