Your first hour with DBSheriff

This picks up exactly where installation guide (inside the package) leaves off: the installer has finished, and you have a running stack with nothing registered yet. Six steps take you from that to real data flowing through the Reporting Console, with the database accounts DBSheriff needs created and its secrets kept safe.

Step	What you do	Time
1	Sign in to the Admin Console	2 minutes
2	Secure the secrets the installer made	5 minutes
3	Create DBSheriff's accounts on the database you want to watch	10 minutes
4	Let DBSheriff reach the database over the network	5 minutes
5	Register the server in the Admin Console	5 minutes
6	Watch the data arrive, then decide about kill and lock	later, deliberately

The installer printed your console URLs and login at the end of the run. A password it generated is shown only there, once, and a password you typed is not printed again. Neither is kept in /opt/dbsheriff/state/.env (only the user name is), so note them now. The console URLs are:

Internal access mode: http://<host>:8502/ (Admin Console) and http://<host>:8501/ (Reporting Console)
Caddy access mode: your HTTPS address, Admin Console at /admin/, Reporting Console at /

Start with the Admin Console. It is where every server, credential, and response setting gets configured. The Reporting Console is where you watch the results; there is nothing to set up there.

The user name is the same for both consoles, but the passwords are not. The Admin Console password is what you typed at install time (or the installer generated, if you left it blank). The Reporting Console has its own generated password, shown once at the end of the install; the Admin Console password does not sign in there. If you lost a password, put INITIAL_ADMIN_PASSWORD (and INITIAL_REPORT_PASSWORD) back in /opt/dbsheriff/state/.env and run /opt/dbsheriff/current/deploy/onprem/stack.sh seed-users --reset. Change the password after this first login if you did not set a memorable one already.

2. Secure the secrets the installer made

The installer generated every secret DBSheriff needs and put almost all of them in one file. Two minutes now saves a bad day later:

Copy /opt/dbsheriff/state/.env to a password manager or your secrets vault, and keep it apart from the data backups. It holds the three encryption keys (SERVER_CREDENTIALS_KEY, which encrypts the passwords you are about to enter for your databases; CONSOLE_SECRETS_KEY, for the consoles' own secrets such as the single sign-on secret; and SCOPE_CREDENTIALS_KEY, for cloud-scope credentials) and the audit keys. If the file is lost, the stored database passwords can no longer be opened and you would enter them all again. Copy /opt/dbsheriff/state/installation_id with it.
Do not change a key by editing it. Everything already stored under the old value becomes unreadable. Ordinary settings are changed by editing .env and running stack.sh up; keys are rotated with a procedure (the installation guide's section "How secrets are handled after the install").
Nothing you type later is kept in plain text. The passwords of the databases you register in step 5 are stored encrypted in DBSheriff's registry, are not shown again, and are sent only to the server they were entered for.

3. Create DBSheriff's accounts on the database

DBSheriff connects with its own accounts, never your application's login. Which ones you need depends on what you want it to do:

Account	Needed for	Required?
monitor	Reading statements, sessions and locks. Writes nothing	Required for every server
kill	Ending a session or statement	Only if you want DBSheriff to kill
lock	Locking an account and the graduated response	Only if you want DBSheriff to lock
posture	Security-configuration checks and the hourly governance read	Optional; the monitor account is used when absent
classify	Reading column values to find sensitive data	Only to classify; there is no fallback to monitor
plan	`EXPLAIN` of captured statements with SELECT-only rights (PostgreSQL, MySQL, Redshift)	Recommended

Start with monitor alone. You can add kill, lock and the rest later, one at a time, when you decide to use them (step 6). Every account, with its exact permissions and create statements for each of the twelve engines, is on one page: database users by engine. Each engine's own setup guide (pre installation database users links them) explains why each permission is needed.

You can let the tool create the accounts. It connects as your database administrator, runs exactly the statements on that page, and stores the new credential for you when the server is already registered. Look first with --dry-run, which prints every statement and connects to nothing:

sudo /opt/dbsheriff/current/deploy/onprem/stack.sh tool create_reset_dbuser postgresql db1.acme.internal --dry-run
sudo /opt/dbsheriff/current/deploy/onprem/stack.sh tool create_reset_dbuser postgresql db1.acme.internal

(Run it from a directory of your own, not /. In a source checkout the command is python3 scripts/create_reset_dbuser.py ....) The engine is one of postgresql, mysql, mssql, oracle, hana, redshift, snowflake, mongodb, synapse; BigQuery, Spanner and Databricks use cloud identities and have no such tool, so follow their setup guide.

Or run the statements yourself. This is the PostgreSQL monitor account, as the page above gives it (<password> is a strong password you choose):

CREATE ROLE dbsheriff_monitor LOGIN PASSWORD '<password>';
GRANT pg_monitor, pg_read_all_stats TO dbsheriff_monitor;
\c <database>
GRANT CONNECT ON DATABASE <database> TO dbsheriff_monitor;
GRANT USAGE ON SCHEMA <schema> TO dbsheriff_monitor;                              -- one per schema
GRANT REFERENCES ON ALL TABLES IN SCHEMA <schema> TO dbsheriff_monitor;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT REFERENCES ON TABLES TO dbsheriff_monitor;

Keep the user name and password: step 5 asks for them. Some engines also need a one-time server setting before statements are visible (PostgreSQL's pg_stat_statements, MySQL's performance_schema consumers, MongoDB's profiling); the engine's setup guide lists it as "required", and install_prereqs can apply it.

Monitoring a database on AWS, GCP, or Azure? Steps 3 to 5 collapse into one command; see onboard target (inside the package). It finds the instance for you (with --detect, for PostgreSQL, MySQL, Oracle, SQL Server and Redshift; or, with --manual, for the same five engines, it takes the host you type, which is how a database on a virtual machine or on-premises is added), runs this step, and registers the server, all at once. Any other engine is set up from its own setup guide and registered in step 5, except Azure Synapse: the Monitored Servers form has no choice for it yet, so its setup guide (Setup guide) registers it through the Admin Console API instead.

4. Let DBSheriff reach the database

The DBSheriff host must be able to open a connection to the database's port (5432 PostgreSQL, 3306 MySQL, 1433 SQL Server and Synapse, 1521 Oracle, 39015 SAP HANA, 5439 Redshift, 27017 MongoDB; Snowflake, BigQuery, Databricks and Spanner are reached over HTTPS). Allow the DBSheriff host's address in the database's firewall, security group or network rule. Two things trip people up:

MySQL accounts are tied to an address. The tool creates them for the address it connects from, which is the DBSheriff host only when you run it there. Pass --client-host if you ran it from somewhere else.
Encrypted connections. DBSheriff verifies the database's certificate. A database with a certificate from your own CA needs that CA delivered to DBSheriff (installation guide, section 4.8), or the server registered with the SSL mode require (encrypted, certificate not checked).

5. Register the server

Monitored Servers tab → + Add / Update. The minimum you need:

Field	What to enter
Server name	Your own label for it, not its hostname
Engine	The database engine
Host, port, database	Where the database is. Snowflake and Databricks still use Host (the Snowflake account identifier, the Databricks workspace URL). MongoDB takes a connection URI instead, BigQuery a project and a service-account key, and Spanner three identifiers and a key
Monitor user and password	The account from step 3 (MongoDB, BigQuery and Spanner have no user and password fields: the URI or the key stands in for them; Databricks takes the OAuth client ID and secret here)
Environment tier	`prod` for production. A non-production tier lowers the severity of its alerts, and automatic kill and lock stay off by default for it
SSL mode	Where the engine has one; keep the verifying default unless you know why not

Everything else (kill and lock credentials, burst thresholds, poll intervals, per-engine options) has a sensible default and can wait.

There is no separate "start monitoring" step. Once you save a server whose engine you chose at install (or added later with install.sh --reconfigure --engines ...), it is picked up automatically within about five minutes (DBSheriff's producers re-read the registered-server list on that cycle), with no restart and no redeploy. An engine that was not in the installer's engine list has no producer running until you re-run the installer with it. Saving also checks your licence: an engine your licence does not name, or a server over its limit, is refused with a message.

6. Watch the data arrive, then decide about kill and lock

Switch to the Reporting Console → Live Feed. Your newly registered server shows up in the Engine/Server filters immediately, even before its first query has been scored; that is deliberate, so you can confirm the filter picked it up before waiting for real traffic. Once queries start arriving, they appear here as DBSheriff scores them; History has the same data with date-range filtering once you want to look back further than what is currently on screen.

If nothing arrives after a few minutes, the most common causes are: the monitor account is missing a grant the engine's setup guide calls "required" (not just "recommended"), the host and port DBSheriff has on file cannot actually reach the database, or a firewall is blocking it. sudo /opt/dbsheriff/current/deploy/onprem/stack.sh health shows what is unhealthy, and stack.sh logs <service> shows why (the engine's producer, for PostgreSQL producer-pg-pool, logs its connection errors). docs/troubleshooting-and-logs.md in your release package has the rest.

Kill and lock are off by default on a server you register in the Admin Console (the Monitored Servers form), on purpose. The one-command onboard_target path from step 3 asks "Enable kill (terminate malicious sessions)?" and its default answer is yes ([Y/n]), so answer n there unless you want automatic kill from day one; its lock-on-burst question defaults to no. Watch the Alerts and Live Feed tabs for a day or two first, get a feel for what your normal traffic looks like, and only then turn on response actions for servers where you are confident DBSheriff will not act on anything you would regret. To turn them on:

Create the kill and lock accounts (step 3 and database users by engine).
In the server's Advanced: Kill & Lock credentials section, enter their user names and passwords, and tick the enable toggles.

If you leave those fields empty, DBSheriff tries the monitor account instead, which holds no right to end a session, so the action fails and is recorded as an error. Use dedicated accounts with only the kill and lock grants; that is the safe default for a production server.

What's next

There is no in-product tour or setup wizard beyond what is described here; this page and the ones below are that tour, written down instead of clicked through:

database users by engine: every account, its permissions and its create statements, per engine.
feature overview: everything DBSheriff can do, what is on or off at install, and how to turn it on.
ui tour (inside the package): a short walk through every tab in both consoles, so you know what each one is for before you need it.
console reference manual (inside the package): the full reference: every field, every setting, exactly who can change what.

Questions, or something in this guide doesn't match what you see: SECURITY.md in your release package, or support@dbsheriff.ai.