KERNOVIQ runs on your own Linux machine or server. With internet access, one command installs it; servers without internet access use the offline bundle instead (airgap.md). On a Windows server or PC, a setup program installs it in WSL 2 (see Windows below). All three install the same product: without a licence key it runs as the restricted trial edition, and a key entered in Settings → Licence lifts every restriction in place (licensing.md).
| Package | For | What you get |
|---|---|---|
| Demo (default) | trying KERNOVIQ | HTTPS on the network, at this machine's name and at its IP addresses (internal CA); the services a trial uses; a one-time link to create the first administrator in the browser |
| Full | a server for the organization, with a licence | the full edition: HTTPS on the internal network, at the server's name and at its IP addresses (internal CA or your certificate), every service including the scan runner, start at boot and daily encrypted backups (as root) |
Both reach the other devices on the network: colleagues open the server's
name or its address (https://192.168.1.20). --local keeps an installation
to the machine itself instead (http://127.0.0.1:8280, nothing on the
network).
The demo package is the trial build and is free to download. The full package is the full build: the installer fetches it from the licence server with your licence key (licensing.md).
Requirements
- Linux on x86-64, 4 GB of memory (8 GB for the full package with many users), 10 GB of free disk space
- Docker Engine with the Compose plugin, or Podman 4+ with
docker-compose(rootless Podman:systemctl --user enable --now podman.socket) bash4.4+,curl,tar,sha256sum,ssh-keygen(OpenSSH 8.1+) — present on current distributions- outbound HTTPS to
kernoviq.organd to the image registry named in the release
Demo
curl -fsSL https://kernoviq.org/install.sh | bash
The installer checks the machine, downloads the release, verifies it and
starts KERNOVIQ, then prints where it answers — this machine's name and its
addresses, e.g. https://192.168.1.20 — and a link like
https://<name>/setup#token=… (with the same link at the address, for a
device that does not know the name). Open it, create your organization and
the first administrator, and you are in. The link works once; keep it to
yourself until then.
The certificate comes from an internal CA the installation creates, so
browsers warn about it until they trust that CA: confirm the warning, or
import kernoviq-ca.crt from the installation directory on the devices you
use. The certificate names the machine's addresses; when the address changes
(DHCP), kernoviqctl start adds the new one, and kernoviqctl cert renew
does so at any time. If a firewall on the machine or the network filters
incoming connections, let TCP 443 (and 80, which redirects to HTTPS) through.
As a user with rootless Podman or in the docker group the installation goes
to ~/.local/share/kernoviq; with sudo to /opt/kernoviq. Rootless Podman
listens on 8443 and 8080 instead of 443 and 80; --https-port and
--http-port pick others, --server-name another name. With --local
KERNOVIQ answers at http://127.0.0.1:8280 on this machine only (--port 8380
picks another port).
Full package on a server
curl -fsSL https://kernoviq.org/install.sh | sudo bash -s -- --edition full --server-name kernoviq.example.internal \
--license-key-file /root/kernoviq-licence.txt
The licence file holds the key from the licence e-mail (KQL1…). The
installer sends it with the version to the licence server
(https://license.kernoviq.org, or --license-server URL), which answers with
the full kit and a credential for its images that expires within hours; the
kit is checked against the licence server's checksum and against the signed
list of the release, and the key is activated once KERNOVIQ runs. A key the
licence server refuses (not accepted, revoked, ended, outside its period of
updates) stops the installation before anything changes, also with
--dry-run.
It asks for the organization and the first administrator (or pass --org,
--admin-email, --admin-name, --admin-password-file, or --web-setup
for a browser link), creates an internal CA and a server certificate (or uses
yours: --cert FILE --key FILE [--ca FILE]), and enables the kernoviq
systemd service and the nightly encrypted backup. Distribute
/opt/kernoviq/kernoviq-ca.crt to the users' computers when you use the
internal CA. Users reach the server at its name or, where DNS does not know
it yet, at its address. Day-to-day operation — certificates, backups, upgrades,
runners, internal systems — is the same as for the offline bundle
(airgap.md, from section 4).
Windows
On Windows 10 22H2, Windows 11 and Windows Server 2022 or newer (64-bit), download KERNOVIQ-Setup.exe from the KERNOVIQ site and run it as an administrator. It needs hardware virtualization, 6 GB of memory (8 GB recommended) and 20 GB of free disk; domain controllers are not supported.
The wizard turns on WSL 2 if needed (after a restart it continues by itself),
creates KERNOVIQ's own Ubuntu distribution with Docker Engine, and serves
KERNOVIQ to the network over HTTPS under the DNS name you give, with an
internal CA or your organization's certificate. It ends with a one-time link
for the first administrator. KERNOVIQ starts with Windows, without anyone
signed in, and is operated with the kernoviq command (kernoviq status,
doctor, backup, upgrade). Upgrade by running a newer setup program;
uninstall in Settings → Apps (the backups stay).
Unattended:
KERNOVIQ-Setup-<version>.exe /S /ACCEPT_EULA /SERVERNAME=kernoviq.example.internal
Everything else — what it sets up on Windows, users and certificates, backups, troubleshooting — is in the Windows guide.
Read before you run
The installer is a single bash script. To read it first, and to check the release yourself:
curl -fsSLO https://kernoviq.org/install.sh
less install.sh
version=$(curl -fsSL https://kernoviq.org/releases/latest)
for file in SHA256SUMS SHA256SUMS.sig release-signer.pub; do curl -fsSLO "https://kernoviq.org/releases/$version/$file"; done
printf 'kernoviq-release namespaces="kernoviq-bundle" %s\n' "$(cat release-signer.pub)" > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I kernoviq-release -n kernoviq-bundle -s SHA256SUMS.sig < SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS # install.sh: OK
ssh-keygen -l -f release-signer.pub # compare with the fingerprint on kernoviq.org
bash install.sh
What it does, in this order: checks the machine (operating system, tools,
container engine, memory, disk, the port); downloads the release's checksum
list and verifies its signature against the KERNOVIQ release key written
into the script; downloads the kit (compose files, kernoviqctl,
documentation — a few hundred kilobytes; the full package's from the licence
server, for the licence key) and checks it against the verified list; runs kernoviqctl install, which pulls the images by the digests the
signed kit names (the container engine checks every layer against them),
creates settings, keys and certificates and starts the services; prints the
setup link.
What it never does: send anything about you or the machine anywhere (the full
package sends the licence key and the version to the licence server), set a
password of its own, open ports to the network (unless you ask for HTTPS
with --server-name), or start a scan. --dry-run stops after the checks
and the verification.
Options
| Option | Meaning |
|---|---|
--edition demo|full |
the package (default demo) |
--version VERSION |
a specific release instead of the latest |
--port N |
demo: the local port (default 8280) |
--server-name NAME |
HTTPS on the internal network under this DNS name (required for full) |
--license-key-file FILE |
the full package: your licence key (required for full) |
--license-server URL |
another licence server (default https://license.kernoviq.org) |
--home DIR |
installation directory |
--upgrade |
upgrade an existing installation (backup first, rollback when the new release does not start); it keeps the build: the full edition is fetched with the licence key the installation has activated (kernoviqctl upgrade --from-license-server VERSION) |
--uninstall [--purge] |
remove the containers; --purge also deletes every piece of data, the images and the directory |
--dry-run |
check and verify only |
--yes |
never ask |
Every other option goes to kernoviqctl install (kernoviqctl install --help).
After the installation, kernoviqctl is on the path (/usr/local/bin, or
~/.local/bin for a user installation): kernoviqctl status, stop,
start, logs, backup, uninstall.
From the demo to the licensed product
Write to sales@kernoviq.org (Settings → Licence prepares the e-mail with what a quote needs). After payment the licence key arrives by e-mail; paste it into Settings → Licence: the limits are gone at once, and Move to the full edition installs the full build in place — backup first, your data stays (licensing.md, "Moving to the full edition"). For production use, install the full package on a server with the key instead.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
rootless Podman needs its API socket |
systemctl --user enable --now podman.socket |
something already listens on 127.0.0.1:8280 |
another service has the port: --port 8380 |
something already listens on port 443 (or 80) |
another web server on the machine: --https-port 8443 --http-port 8080, or --local |
| the browser warns about the certificate | it does not trust the installation's internal CA yet: import kernoviq-ca.crt from the installation directory (or your organization's certificate: kernoviqctl cert install) |
| other devices cannot connect | a firewall filters TCP 443/80, or the installation was made with --local (kernoviqctl status shows the addresses) |
the name 'kernoviq' is already in use on this machine |
another installation or a development stack holds the name, and sharing it would share its data: KQ_PROJECT=kernoviq2, set for this command and for every later kernoviqctl run |
could not pull … |
the machine cannot reach the image registry (proxy: configure it for Docker or Podman, not only for curl) or the disk is full |
the licence server did not hand out the full edition: … |
the reason follows: a key it does not know (a key issued by hand must be recorded there first), a revoked or ended licence, a release outside the licence's period of updates, or too many downloads today |
the release signature does not verify |
the download was changed on the way, or the script and the release do not belong together: download install.sh again from kernoviq.org |
| the setup link says the token is invalid | the first administrator already exists: sign in on /login |