Installing Lawliet

STEP 1

Before you begin

Lawliet runs as a set of containers on one server. Prepare that server and decide how people will reach it; the installer asks about both.

You need	Details
A Linux server	Any current 64-bit distribution: Ubuntu, Debian, RHEL, Rocky, Alma. Intel/AMD or ARM - the bundle carries native code for both.
Hardware	Starts at 4 CPU cores, 8 GB RAM and 40 GB free disk. It scales with the number of monitored hosts and, above all, with how much log history you keep - see Sizing the server below.
Docker	Docker Engine 24 or newer with the Compose plugin (`docker compose`), running, and usable by the account you install with. The installer checks for both and stops if either is missing.
Tools	`bash`, `curl`, `tar`. `openssl` only if you want the installer to create a self-signed certificate.
An address	The DNS name or IP address operators and monitored hosts will use to reach the server.
A certificate	Recommended: a TLS certificate and private key (PEM) for that name, from your own certificate authority. Otherwise the installer can generate a self-signed one.
Accurate time	NTP on the server and on every monitored host. Instructions older than 10 minutes are refused, so a drifting clock silently stops a host from acting.

Sizing the server

One server runs the whole stack in containers (PostgreSQL, Redis, the ClickHouse log store, the API and the console). CPU and RAM track the number of agents reporting and how many scans run at once; disk is driven mostly by log/SIEM retention and stored evidence. The installer warns and asks before continuing with less than 10 GB free. Treat the figures below as starting points and grow disk as your retention window grows.

Estate	CPU	RAM	Free disk
Evaluation / up to 10 hosts	4 cores	8 GB	40 GB
Up to 50 hosts	8 cores	16 GB	100 GB
Up to 200 hosts	8-16 cores	32 GB	250 GB
200+ hosts	16+ cores	64 GB	500 GB+

If you collect a lot of syslog or keep long log history, size disk for the log store first: a busy estate can generate tens of GB of logs per week. SSD storage is recommended for the database and log store.

Docker is installed and docker info works for my account
At least 40 GB is free where I will unpack the bundle
I know the address people will use, and have its certificate and key (or will use self-signed)
The server's clock is synchronised by NTP

STEP 2

Open the network

Monitored hosts connect out to the server; the server never connects in to them. Nothing needs to be opened on the hosts you monitor.

From	To	Port	Why
Operators' browsers	Lawliet server	`443/tcp`	The console, over HTTPS
Operators' browsers	Lawliet server	`80/tcp`	Optional: redirects to 443
Monitored hosts	Lawliet server	`443/tcp`	Agents report and fetch instructions
Server and hosts	Your NTP servers	`123/udp`	Clock synchronisation
Devices sending syslog	Lawliet server	`5514/udp` `5514/tcp`	Only if you collect logs

Keep the database private. PostgreSQL and Redis stay inside Docker and are never published. Do not open 5432 or 6379.

Using the lab mode (plain HTTP) instead

The installer offers plain HTTP on ports 3000 and 8000 for a laptop or a lab. It sends passwords and enrolment tokens in clear text, so do not use it on a real network. If you do: operators need both 3000/tcp and 8000/tcp (the page loads from 3000 and talks to 8000), and monitored hosts need 8000/tcp.

Optional features that need more

Network discovery probes the ranges you give it (TCP, plus UDP 137, 161, 1900, 5353 and ICMP). Firewall import reaches devices over SSH (22) or HTTPS (443). Emailed reports use SMTP (587). Single sign-on reaches your identity provider on 443. Open these only if you use the feature.

STEP 3

Install

Copy the bundle to the server, unpack it and run the installer. It checks the machine, asks five questions, generates every secret and starts the platform.

$ tar xzf lawliet-docker-*.tar.gz
$ cd lawliet-*/
$ ./lawliet install

What the installer asks

Address
The DNS name or IP address from step 1. It suggests the one it detects.
How to serve it
Choose 1, HTTPS on 443. Option 2 is the lab mode described above.
Certificate
Give the paths to your certificate (full chain, PEM) and private key, or let it generate a self-signed certificate. You can replace it later with ./lawliet tls.
Administrator username
admin unless you prefer another.
Administrator password
Let it generate a strong one, or type your own (at least 12 characters). This is a one-time password: you replace it at first sign-in.

It then shows a summary, asks for confirmation and starts. The first start builds the containers and takes several minutes. When it finishes it prints:

Console https://your-server Username admin Password shown once Save that password now. It is stored in .env and not shown again. Activate your licence Installation fingerprint 3f9a...c21e

Copy the password now. You need it for the first sign-in. The folder you installed from is now your deployment: keep it, and run every later ./lawliet command from it.

The installer finished and printed the console address
I saved the one-time administrator password
I sent the installation fingerprint to Lawliet (see step 5)

STEP 4

First sign-in

Open the console address in a browser. The first sign-in has two short, required steps. Nothing else in the platform opens until both are done.

Sign in with the one-time password
If you used a self-signed certificate, the browser warns once. That is expected.
Choose your own password
At least 12 characters. Common and well-known passwords are refused. The one-time password stops working.
Set up two-factor authentication
Scan the QR code with an authenticator app (Google Authenticator, Microsoft Authenticator, 1Password or any TOTP app), or type the key shown under it.
Save the recovery codes
Ten single-use codes that sign you in if you lose your phone. Copy or download them and keep them somewhere safe, such as your password manager. They are shown only once.
Enter the 6-digit code from the app
From now on every sign-in asks for a code. Next comes the activation screen, step 5.

I set my own password
Two-factor is set up and my recovery codes are stored safely

STEP 5

Activate your licence

Your licence is issued for this installation and works on it alone. We need one thing from you to issue it: the installation fingerprint.

Send us the fingerprint
The installer printed it at the end. The activation screen you reach after the first sign-in shows it too, with Copy and Email it buttons, and the server shows it at any time:
```
$ ./lawliet licence
```
It is 32 characters, like 3f9a51c0d6e84b27a1f0c9d3e5b7c21e, and identifies this installation only: no host name, address or data. You can send it as soon as the installer finishes.
Receive your licence key
We reply with a key file. The key starts with LAWLIET-.
Install it
Paste the key on the activation screen and press Activate licence, or on the server:
```
$ ./lawliet licence key-file
```
The key is checked on the server before anything changes; nothing is sent anywhere. The platform opens straight away.

It stays with this installation. The licence survives restarts, updates and backup restores. A new server, or a reinstall that removes the data (./lawliet uninstall), is a new installation with a new fingerprint and needs a new licence: send us the new fingerprint.

If your bundle was delivered with a licence already inside it, there is no activation screen and you can skip this step.

The licence is installed and ./lawliet licence shows it

STEP 6

Connect your hosts

A small agent on each server or workstation reports to Lawliet. The server prints ready-to-run install commands, with its own address and enrolment token filled in.

On the Lawliet server

$ ./lawliet token

Copy the command for each platform from its output and run it on the host you want to monitor. They look like this:

Linux (as root)

curl -sSL https://your-server/api/v1/agents/download/linux | sudo bash -s -- \
     --server https://your-server --token enrolment-token

Windows (PowerShell as Administrator)

Invoke-WebRequest https://your-server/api/v1/agents/download/windows -OutFile install.ps1
.\install.ps1 -Server https://your-server -Token enrolment-token

macOS

curl -sSL https://your-server/api/v1/agents/download/macos | sudo bash -s -- \
     --server https://your-server --token enrolment-token

Within a minute the host appears under Environment in the console. The same commands are available there from the Install agent button.

Using a self-signed certificate?

Each host has to trust it. Export it on the server and copy it to the host:

$ ./lawliet tls --export

This writes lawliet-server.pem. ./lawliet token then prints commands that include it (--cacert and --ca-cert on Linux and macOS, -CaCert on Windows).

Collecting logs from firewalls and servers (syslog)

Under Logs, Sources, add a syslog source on port 5514 (UDP or TCP), then point your devices at the server on that port. It is the port the server listens on; others are not reachable. Syslog carries no authentication, so restrict each source to the networks your devices are on.

Keep the enrolment token private

Anyone holding it can enrol a host. If it leaks, replace it with ./lawliet token --rotate. Hosts already connected are not affected.

STEP 7

Add your team

Create an account for each person under Settings, Users, and give each a role. Each new user goes through the same first sign-in: their own password, then two-factor.

Roles

Give people only what they need

Built-in roles cover administrators, analysts, auditors and viewers. Create your own under Settings, Access control, and adjust individual users if needed.

Dual control

Two people for critical actions

Assign the Left and Right Security Officer roles, and their critical actions (changing users, containment, remediation, firewall pushes) wait for the other officer to approve.

Requests waiting for a signature appear under Approvals. Which actions need one, and who approves whom, is set under Settings, Access control, Dual control.

STEP 8

Day-to-day care

Everything is done with ./lawliet from the deployment folder. ./lawliet help lists it all.

Command	What it does
`./lawliet status`	Health, licence, version and how many hosts are connected
`./lawliet backup`	A database backup into `./backups`. The HTTPS setup also takes one daily on its own.
`./lawliet restore file`	Restore a backup, then restart. Asks before replacing anything.
`./lawliet update new-bundle`	Upgrade to a newer bundle: takes a backup, installs beside the current one, verifies it
`./lawliet restart`	Restart and wait until healthy. `stop` and `start` also exist; data is never touched.
`./lawliet logs backend -f`	Follow a service's logs
`./lawliet passwd`	Reset the administrator password, for example if you are locked out
`./lawliet tls`	Show or replace the certificate
`./lawliet licence`	Show the licence and this installation's fingerprint. With a key: install a new licence.
`./lawliet doctor`	Collect a diagnostics file for support. It holds no passwords and no data.

Updating

When you receive a new bundle, copy it to the server and run this from your current deployment folder:

$ ./lawliet update lawliet-docker-new-version.tar.gz

It backs up first and refuses to continue without a backup. It installs the new version in a folder next to the current one and brings your configuration across. From then on, run ./lawliet from the new folder. The old one is kept so you can go back.

Take a copy off the server. Copy ./backups and the .env file somewhere safe from time to time. .env holds the keys that protect stored data, and a backup cannot be restored without it.

STEP 9

Troubleshooting

Start with ./lawliet status, then ./lawliet logs backend -n 200.

The installer says a deployment already exists

Lawliet is already installed on this server under the same name. To add a second one beside it, install under its own name, and use the same variable for every later command in that folder:

$ COMPOSE_PROJECT_NAME=lawliet-staging ./lawliet install

The console does not load, or sign-in does nothing

Check 443/tcp is open from your desk to the server, and that you use the address given to the installer. In lab mode both 3000 and 8000 must be reachable. The platform's own health check:

$ curl -k https://your-server/health

It should answer with "status": "healthy".

A host never appears after installing the agent

In order of likelihood: the enrolment token is wrong (compare with ./lawliet token); the host does not trust a self-signed certificate (see step 6); the host cannot reach the server on 443; the host's clock is wrong. On Linux, journalctl -u lawliet-agent -f shows what the agent is doing.

A host is connected but commands never run

Almost always the clock. Instructions more than 10 minutes old are refused. Make sure NTP is running on the host and on the server.

I lost my phone

On the code screen choose Lost your phone? Use a recovery code and enter one of the codes you saved. Each works once. Then ask an administrator to reset your two-factor under Settings, Users; you set it up again on the new phone at your next sign-in. If the only administrator has neither phone nor codes, run ./lawliet passwd on the server: it sets a new password and can turn that account's two-factor off so it can be set up again.

The licence key is refused

"Bound to another installation": the key was issued for a different fingerprint. The message shows this installation's fingerprint; send us that one. "Issued before the licence in use": a newer licence is already installed, and nothing changed. Paste the whole key, starting with LAWLIET-, with no line breaks.

Moving to a new server

Install on the new server, restore your latest backup there (./lawliet restore file) and send us the new installation's fingerprint for a licence issued to it.

A module says it is not included in your licence

The screen shows what the module does. Contact us to add it. You will receive a new licence key; install it in either of two ways, and nothing needs reinstalling:

In the console, under Settings, Platform, Enter a new licence key. Or on the server, which checks the key before changing anything:

$ ./lawliet licence new-key-or-file

Asking for help

Run ./lawliet doctor and send us the file it writes, together with the build id shown by ./lawliet status. Both identify your installation exactly and contain no passwords or data.

From the bundle to a running platform in one command.