Security
Who can reach an instance, and who can read its data.
Unix socket
The recommended setup: TamarackDB runs on the application’s host, on its unix socket, the default.
Nothing goes over the network. The socket’s permissions decide who may connect.
With the default
socketModeof"0600", only the server’s own user can connect.If the application runs as another user, set
socketMode = "0660"and add that user to the server’s group. For an application running aswww-data:sudo usermod -aG tamarackdb www-dataThe application picks up its new group once it restarts.
Another host
The server speaks plain HTTP only. A client on another host, application or backup, goes through a reverse proxy that handles TLS, in front of the socket.
With Caddy, which gets and renews its certificates by itself:
tamarackdb.example.com {
reverse_proxy unix//run/tamarackdb/tamarackdb.sock
}With nginx:
server {
listen 443 ssl;
server_name tamarackdb.example.com;
ssl_certificate /etc/ssl/tamarackdb.example.com/fullchain.pem;
ssl_certificate_key /etc/ssl/tamarackdb.example.com/privkey.pem;
client_max_body_size 8m;
location / {
proxy_pass http://unix:/run/tamarackdb/tamarackdb.sock:;
}
}- Set nginx’s
client_max_body_sizeto the server’smaxRequestBodySize. nginx refuses bodies over 1 MiB by default. - The proxy’s user must be allowed by
socketMode, like the application’s. - Set
authTokenFile: the proxy opens the API to the network. The proxy passes theAuthorizationheader through. - In Docker, the server listens over TCP: keep its port private (see Install).
Bearer token
Setting authTokenFile turns authentication on. The file holds the token alone, in plain text. To create one:
sudo install -o tamarackdb -g tamarackdb -m 600 /dev/null /etc/tamarackdb/token
openssl rand -hex 32 | sudo tee /etc/tamarackdb/token > /dev/null- Every route then needs
Authorization: Bearer <token>,/healthand/statsincluded. - A request without the right token gets
401 Unauthorized. - The server removes spaces and line breaks at the start and end of the file.
- The server refuses to start when the file is missing, unreadable, or empty.
- There is one token. The server reads it at startup: changing it means restarting the server.
- Without
authTokenFile, the default, no request is checked. - The server refuses to start without
authTokenFilewhen it listens over TCP on an address other than loopback, such as0.0.0.0. SetallowNoAuthtotrueto start it anyway, when something else keeps the port private.devModeimplies it. - On the unix socket,
allowNoAuthhas no effect:socketModedecides who can connect.
Files
Anyone who can read the database file reads every event and projection, whatever the token and socketMode say.
tamarackdb-initandtamarackdb-backupcreate a data directory as0700and a database file as0600.- An existing directory or file keeps its permissions: the server never changes them. Give a directory you create
yourself
0700. - The token file must be readable by the server’s user only:
chmod 600. With systemd’sLoadCredential=, it can be owned by root instead (see Install). devModestays off in production: it exposesDELETE /events, which deletes every event.