Agent and ProxySQL

The database agent and ProxySQL run together on a Linux host in your network. The installer sets up both.

Prerequisites

Host

• Debian-based Linux (Ubuntu 22.04 or 24.04), with root or sudo
• 2 vCPU, 4 GB RAM, 20 GB free disk. ProxySQL is built from source during installation, which takes several minutes
• For an on-premises deployment, install it on the same server as the AuthNull stack. ProxySQL then calls authn-service on 127.0.0.1:2882, so nothing needs to change if the server's IP address changes

Database

• An account on the database that can create roles and change their passwords

Network

From	To	Port
Agent host	AuthNull API (the API address in db.env)	443, or 80 for an HTTP on-premises install
Agent host	The database	5432 (PostgreSQL) or 3306 (MySQL)
Users' machines	Agent host (ProxySQL)	6133 (PostgreSQL) or 6033 (MySQL)

Step 1: Set the Connection Mode

Go to Settings → Tenant Configuration → Connectivity & recording → Connection and set Connection Mode to Authnull Proxy, or Direct and Authnull Proxy. MFA is enforced on connections made through the Authnull Proxy (ProxySQL).

Tenant connection mode configuration

Step 2: Install the Agent

1. Go to Agents and click Install Database Agent. Choose Linux and the database type (PostgreSQL or MySQL).
2. Download the generated db.env file. It contains your organization ID, tenant ID, the API address, and the agent's keys.
3. On the host, run the commands shown on screen:

sudo curl -L -o run_agent.sh <script URL shown on screen>
sudo chmod +x run_agent.sh
sudo ./run_agent.sh install

4. When prompted for the db.env content, paste the whole file and finish with an empty line.
5. Enter the database server's host, port, user, and password when prompted.
6. When asked whether to install ProxySQL, answer Y.

Install Database Agent screen

warning

If you reinstall, delete the old /opt/authnull-db-agent/db.env first - the installer appends to it, which leaves duplicate settings.

Step 3: Verify the Installation

Both services must be active:

sudo systemctl is-active db-agent proxysql

ProxySQL's configuration file must be owned by root:proxysql with mode -rw-r-----, and its authnull section must hold your organization ID, tenant ID, and the authn-service address:

ls -l /etc/proxysql.cnf
sudo grep -n -A4 -E '^\s*authnull\s*=' /etc/proxysql.cnf

On an on-premises install, api_url is http://127.0.0.1:2882/authnull0/api/v1/authn/v3/do-authenticationV4.

Check ProxySQL's runtime settings through its admin interface:

mysql -u 'admin,x' -padmin -h 127.0.0.1 -P 6032 --ssl-mode=DISABLED -e "SELECT variable_value AS auth_method FROM runtime_global_variables WHERE variable_name='pgsql-authentication_method'; SELECT hostgroup_id, hostname, port, status FROM runtime_pgsql_servers;"

• auth_method must be 1 (clear text) - the MFA check only runs on clear-text logins.
• Your database server must be listed with status ONLINE.

note

This ProxySQL build closes any connection whose username has no comma, including the admin login - hence admin,x. The part after the comma is ignored for admin.

Step 4: Verify Discovery

The agent syncs every minute. Within a minute or two, it appears on the Agents screen, and its databases appear on the Databases screen.

Agent discovery on the Agents screen

Databases discovered by the agent

The agent's log is at /var/log/authnull-db-agent.log.

Managing Databases

Task	Command
Add another database to the agent	sudo ./run_agent.sh add
Change a database's connection details	sudo ./run_agent.sh modify
Remove a database from the agent	sudo ./run_agent.sh delete
Update the agent	sudo ./run_agent.sh update
Remove the agent	sudo ./run_agent.sh uninstall
Restart the agent	sudo systemctl restart db-agent
Restart ProxySQL	sudo systemctl restart proxysql

warning

Never start ProxySQL by hand or with --initial. Always use sudo systemctl restart proxysql. Running it with --initial rebuilds its database from the configuration file and deletes the users the agent has provisioned.

Next Steps

Continue to Policies to grant access.