Installing on a host

One binary installs everything. On an Ubuntu 22.04 or 24.04 host (amd64 or arm64) with systemd:

sudo ./logline install

It looks at the host, prints what it will do, asks once, and ends with the URL and a one-time admin password. --yes skips the question; --name logs.example.com adds names to the certificate; --addr 0.0.0.0:8443, --hec-port and --syslog-port move the listeners; --profile small|medium|large overrides the memory sizing; --backup-keep 14 changes how many nightly backups are kept (default 7). Everything it does is logged to /var/log/logline/install.log with the exact commands it ran.

The installer is idempotent. Run it again after a failure, after changing flags, or after adding RAM: it keeps the CA, the ClickHouse password and the accounts, rewrites configuration, repairs ownership and permissions, and restarts what changed. A newer logline binary re-run the same way upgrades the engine and, when the pinned versions moved, ClickHouse and Vector.

What it does#

1. Preflight: root, OS, architecture, systemd, RAM (2 GiB minimum, 4 GiB practical), free disk under /var/lib/logline (5 GiB minimum), the ports it needs, clock synchronization, an existing install. A failure stops before anything changes and says what to fix.
2. System users logline, logline-vector, logline-clickhouse, no shell, no home.
3. Binaries: the engine to /usr/local/bin/logline; ClickHouse and Vector to /opt/logline/bin, downloaded from the projects' GitHub releases and verified against SHA-512 and SHA-256 sums pinned in the engine. A download that does not match is deleted and the install stops.
4. TLS: a local CA (/etc/logline/tls/ca.crt, ten years) and a server certificate (two years) for the host name, FQDN, --name values, localhost and the host's addresses. The CA key is root-only.
5. ClickHouse: config.xml (loopback only, data under /var/lib/logline/clickhouse, memory limits from the profile, query and part logs kept 30 days, no crash reports, a backups disk at /var/lib/logline/clickhouse-backups as the only allowed backup destination) and users.xml with two accounts, passwords hashed, loopback only: logline for ingest, the schema, backups and health, and logline_search, which runs searches under a read-only profile whose time, memory, scan, result and thread limits no query can raise (see SEARCH-LIMITS.md). Both keep input_format_try_infer_datetimes=0 so JSON fields keep their strings.
6. Engine: /etc/logline/engine.env holds the data directory, the ClickHouse DSN and the search account, the listen address, the certificate paths, the Vector paths and the search limits. The unit loads it; every logline subcommand reads it too, so logline inputs list on an installed host needs no flags.
7. Ingestion: three default inputs (HEC on 8088 with a generated token, syslog udp and tcp on 514) and four self-monitoring inputs (the engine, helper and Vector journals and the ClickHouse logs into index=_internal, the audit log into index=_audit; see SELF-LOGGING.md) rendered to /var/lib/logline/engine/vector/ and validated with the installed Vector before being written.
8. systemd units logline-clickhouse, logline-vector, logline, unprivileged, with ProtectSystem=strict, NoNewPrivileges, PrivateTmp, PrivateDevices and the rest of the sandbox; only the directories each service writes are writable. Vector and the engine get CAP_NET_BIND_SERVICE for 514 and 443; Vector also joins systemd-journal to read the platform's own journal. A fourth unit, logline-helper, is the one root process: the service-control helper behind the Health page (see HEALTH.md). And logline-backup.timer with logline-backup.service: the nightly backup (BACKUP.md).
9. Start ClickHouse, wait for it, create the logline database and the events table.
10. Admin account admin with a generated password that is printed once and must be changed at first login (--admin-password-stdin with --yes sets one instead).
11. Start Vector and the engine, wait until both answer; enable the backup timer.
12. Doctor, then the summary.

Where things are#

/usr/local/bin/logline                 the engine and CLI
/opt/logline/bin/{clickhouse,vector}   pinned components, versions.json
/etc/logline/engine.env                engine settings (root:logline 0640), rewritten by every install
/etc/logline/engine.local.env          the operator's search-limit overrides; written once, never rewritten
/etc/logline/install.json              what was installed, the choices to keep (root 0600)
/etc/logline/clickhouse/{config,users}.xml
/etc/logline/tls/{ca,server}.{crt,key}
/var/lib/logline/engine/               inputs, sourcetypes, users, sessions, tokens, dashboards
/var/lib/logline/engine/history/       each account's search history
/var/lib/logline/engine/audit/         audit.jsonl (logline:logline-vector, Vector tails it)
/var/lib/logline/engine/vector/        generated vector.yaml and secrets.json (logline:logline-vector)
/var/lib/logline/vector/               Vector disk buffers and file positions
/var/lib/logline/clickhouse/           ClickHouse data
/var/lib/logline/backups/              backup archives (root 0700; they hold secrets, see BACKUP.md)
/var/lib/logline/clickhouse-backups/   ClickHouse's backups disk (logline-clickhouse 0700)
/var/lib/logline/backup-status.json    the last backup's outcome, for doctor and the Health page
/run/logline/helper.sock               the helper's socket (root:logline 0660)
/var/log/logline/install.log           every install run
/var/log/logline/clickhouse/           ClickHouse logs (rotated at 100 MB x 5; group logline-vector, tailed)
/var/cache/logline/                    downloaded release tarballs

Everything under /var/lib/logline is the data root; mounting a bigger volume there before installing is the simplest way to size storage. Engine, helper and Vector logs go to the journal as JSON lines: logline service logs or journalctl -u logline -u logline-vector -u logline-helper. All of them, and the ClickHouse logs, are also searchable as index=_internal (SELF-LOGGING.md).

Sizing#

The profile is chosen from RAM and can be forced with --profile.

Mark and uncompressed caches are an eighth and a sixteenth of the ClickHouse limit. The rest of the host is left to the OS page cache, Vector and the engine. Re-run the installer after changing RAM.

Day two#

logline doctor                       # every check, exit 1 on a failure; --json for scripts
sudo logline backup                  # a backup now; the timer takes one nightly (BACKUP.md)
logline service status               # the four units
logline service restart vector       # engine | vector | clickhouse | helper
logline service logs engine
sudo -u logline logline inputs add --type tcp --id app --port 5515 --index app --sourcetype json
sudo -u logline logline vector apply # re-render and validate; Vector reloads on its own
sudo logline users list              # accounts; the running engine picks up changes at once

Commands that write under /var/lib/logline/engine are best run as the logline user. Run as root they still work: files written by root take the directory's owner, so the engine can read them afterwards.

Settings are in /etc/logline/engine.env; change and systemctl restart logline. A re-run of the installer rewrites that file, so search limits are overridden in /etc/logline/engine.local.env instead, followed by sudo logline install, which applies them to the engine and to ClickHouse's search profile alike; logline doctor shows the limits in effect (SEARCH-LIMITS.md).

Trusting the certificate#

The UI serves a certificate signed by the CA at /etc/logline/tls/ca.crt. Install that file where the browsers are:

• Ubuntu or Debian: sudo cp ca.crt /usr/local/share/ca-certificates/logline.crt && sudo update-ca-certificates
• macOS: sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt
• Windows: certutil -addstore -f Root ca.crt
• Firefox keeps its own store: Settings, Privacy and Security, Certificates, Import.

For a public host with a real certificate, point LOGLINE_TLS_CERT and LOGLINE_TLS_KEY in engine.env at it. ACME is not built in yet.

Offline hosts#

Put the two tarballs the installer wants into /var/cache/logline (or the directory given with --cache-dir) before running it; a cached file with the right checksum is used without any network access. logline install --artifacts prints the file names, URLs and checksums this version wants for both architectures.

Rehearsing without a host#

logline install --root /tmp/rehearsal --yes writes every file under that directory and creates no users, downloads nothing and starts nothing, on any operating system. It is how the installer's own tests run, and a way to read the generated units and configs before touching a real host.

--no-start on a real host writes everything, including users and binaries, but does not enable or start the units: for images baked ahead of time and for containers without systemd.

Removing#

sudo logline uninstall          # stops and removes services, binaries and the download cache
sudo logline uninstall --purge  # also configuration (the CA, passwords), data, backups, logs and the users

--purge deletes the backups with the rest of /var/lib/logline; copy them off the host first if you want to keep them.

Without --purge, running logline install again restores the install with the same CA, password and accounts.

Not yet#

• A separate logline upgrade with a pre-upgrade backup; today a re-run with a newer binary upgrades in place (take sudo logline backup first).
• The master key and LoadCredential for encrypting stored secrets; HEC tokens and the ClickHouse password sit in root-readable files.
• TLS on HEC and syslog listeners.
• ACME, a .deb, and storage add-disk.