Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication modes

When you register a database, you pick one of four execution modes that decides how KnoxCall actually talks to it. The right pick depends on where the database lives and how you want credentials to flow.

​
Quick decision guide

Is the DB publicly reachable on the internet?
├─ Yes → "Direct"
└─ No
   ├─ Is it AWS RDS / Aurora with IAM auth enabled?
   │   └─ Yes → "IAM"  (no admin password needed, 15-min tokens)
   ├─ Do you have a KnoxCall agent running in the same VPC/network?
   │   └─ Yes → "Agent tunnel"  (DSN never leaves your network)
   └─ Do you have an SSH host that can reach the DB?
       └─ Yes → "SSH tunnel"

​
Direct

KnoxCall opens a TCP connection straight from the control plane to your database, authenticates with the admin credential you registered, and runs CREATE USER / DROP USER SQL against the DB. Use it when:
  • Your DB is publicly reachable (or KnoxCall’s IP is allow-listed in your DB firewall).
  • TLS is already in place (default sslmode=require).
  • You’re OK with the admin credential leaving the customer network on each issue/revoke.
Required fields: host, port, admin username, admin password.

​
Agent tunnel

You install a small KnoxCall agent inside your VPC. The agent maintains an outbound WebSocket to the control plane. When credentials need minting, KnoxCall pushes a db_run_sql command through that WebSocket; the agent runs the SQL inside your network and reports back. The DSN and admin password are pushed just-in-time on each mint — they don’t sit on the agent. Use it when:
  • Your DB isn’t publicly reachable and you don’t want to open an inbound firewall hole.
  • You want the strongest “DSN never leaves my VPC” story (this is the structural advantage over self-hosted Vault, which has to reach to the database).
  • You already run a KnoxCall agent for other features.
Required fields: host, port, admin username, admin password, agent_id.

​
SSH tunnel

KnoxCall opens an SSH connection to a customer-supplied SSH host (a jump server, bastion, or any reachable Linux box that can see the DB), uses forwardOut to tunnel a TCP connection to your DB, and then runs SQL through that tunnel. The SSH private key is encrypted with your tenant master key and stored alongside the connection. The matching public key lives on the SSH host in ~/.ssh/authorized_keys — KnoxCall is the client, just like any developer’s laptop. Use it when:
  • Your DB isn’t publicly reachable, you don’t (yet) run a KnoxCall agent, but you have a bastion or jump host.
  • You’d rather manage authorized_keys than another moving part.
Required fields: SSH host, SSH username, SSH private key (PEM), DB host (resolved from inside the SSH host’s network), admin username, admin password. Optional: SSH port (default 22), key passphrase. Engine support: Postgres, MySQL, and MongoDB.

​
IAM (AWS RDS / Aurora)

For RDS Postgres or RDS / Aurora MySQL clusters with IAM database authentication enabled. KnoxCall uses the AWS RDS Signer SDK to mint a 15-minute auth token for an existing IAM-enabled DB user — no admin password is stored, no dynamic CREATE USER runs. The DB user is one you’ve already provisioned and granted IAM auth on: 
-- Postgres
GRANT rds_iam TO app_user;

-- MySQL (Aurora / RDS)
CREATE USER 'app_user' IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';
KnoxCall’s control-plane needs an AWS role with rds-db:connect on the cluster’s user ARN. Use it when:
  • You’re on RDS and want to skip storing admin passwords entirely.
  • Your application already supports IAM auth.
Required fields: RDS endpoint host, AWS region, IAM-enabled DB user. No admin password, no port (defaults to engine default). Lease ceiling: AWS pins auth tokens to 15 minutes regardless of the lease TTL you ask for. KnoxCall caps the lease at that ceiling.

​
Comparison

DirectAgent tunnelSSH tunnelIAM
DB needs public address?YesNoNo (only the SSH host does)Yes (RDS endpoint)
Admin password stored?✅ encrypted✅ encrypted✅ encrypted❌ none
Extra infra to run?NoneKnoxCall agentAn SSH host you controlAn AWS IAM role
DSN leaves your network?Yes (during mint)NoYes (over SSH-encrypted tunnel)No (token signed in AWS)
Enginespg / mysql / mongopg / mysql / mongopostgres (more soon)postgres / mysql
Lease TTL ceilingCustomer-setCustomer-setCustomer-set15 min (AWS-pinned)

​
Testing before you save

Every New Database page has a Test button that runs the smallest possible probe for the selected mode:
  • Direct / SSH tunnel — opens a real connection and runs SELECT 1 (or ping for Mongo).
  • Agent tunnel — dispatches SELECT 1 through the agent’s control-WS.
  • IAM — calls RDS Signer once and confirms a token was minted.
Create is gated on a successful test. Any field change after a successful test invalidates it — you have to re-test before saving.