Back to the home page

KERNOVIQ on Windows

Installing KERNOVIQ on Windows 10 22H2, 11 or Server 2022+ with the setup program: requirements, network access, backups, upgrades and troubleshooting.

KERNOVIQ runs on a Windows server or PC in its own Linux distribution in the Windows Subsystem for Linux (WSL 2). The setup program puts everything in place; users on the network then reach KERNOVIQ through this computer over HTTPS, exactly as they would reach a Linux server. The product, its data and its backups are the same as on Linux (install.md, airgap.md).

In Turkish: Windows’ta KERNOVIQ.

users' browsers ──HTTPS :443──▶ Windows: KernoviqProxy service (Caddy)
                                   │ 127.0.0.1:8280 (WSL localhost forwarding)
                                   ▼
                                 WSL 2: distribution "KERNOVIQ" (Ubuntu 24.04, systemd)
                                   Docker Engine ─ KERNOVIQ (web, API, workers, PostgreSQL, Valkey)

1. Requirements

Minimum Recommended
Windows Windows 10 22H2, Windows 11, Windows Server 2022 or 2025; 64-bit (x64) Windows Server 2025
Memory 6 GB 8 GB or more
Disk 20 GB free on the data folder's drive 40 GB or more, plus room for backups
Processor hardware virtualization on (Intel VT-x / AMD-V; in a virtual machine: nested virtualization) 4 cores
Network TCP 443 (and 80 for the redirect) reachable from user networks; users browse to this computer's DNS name or to its IP address a DNS name for this computer that users can resolve
Internet at installation and upgrades: Microsoft (WSL), Ubuntu's archive, the KERNOVIQ site and its image registry

Not supported: Windows Server 2019 and older, 32-bit or Arm Windows, domain controllers (install on a member server). An administrator account is needed to install.

2. Install

  1. Download KERNOVIQ-Setup.exe from the KERNOVIQ site. Before running it, check Properties → Digital Signatures: the signer is the KERNOVIQ publisher. The SHA-256 of every setup program is in the release's signed SHA256SUMS (releases/<version>/).
  2. Run it as an administrator and accept the licence agreement.
  3. Settings:
    • Full edition (recommended): choose the licence file holding the key from the licence e-mail (KQL1…); the setup fetches the full edition from the licence server with it and activates it.
    • Trial: without a licence (the trial edition). A licence key entered later in Settings → Licence moves it to the full edition in place.
    • Either way users on the network connect over HTTPS, at the server name (default: this computer's DNS name) or at this computer's IP address (https://192.168.1.20). To keep KERNOVIQ to this computer instead (http://127.0.0.1:8280, nobody else can connect), install from the command line with kernoviq install --local.
    • Use my organization's certificate: a PEM certificate and its key from your CA (for example AD CS). Without it the setup creates an internal CA.
    • Data folder: where the distribution's virtual disk grows (default C:\ProgramData\KERNOVIQ\wsl; a local NTFS drive).
  4. The setup turns on WSL if needed. If Windows must restart for that, the wizard says so; after the restart, sign in with the same account and the installation continues by itself in a window.
  5. The first installation takes 10–20 minutes (Ubuntu, Docker Engine and the KERNOVIQ images are downloaded). At the end the wizard shows:
    • the address, e.g. https://kernoviq.example.internal;
    • a one-time link to create the organization and the first administrator in the browser; keep it to yourself until it is used, then retire it: kernoviq ctl config set SETUP_TOKEN= and kernoviq restart (kernoviq status reminds you while it is set);
    • with the internal CA: C:\ProgramData\KERNOVIQ\kernoviq-ca.crt, which users' computers must trust (section 4);
    • the backup key C:\ProgramData\KERNOVIQ\keys\backup.key: copy it to a safe place outside this computer; backups cannot be restored without it.

The Start menu gets a KERNOVIQ shortcut to the address, and the kernoviq command works in every new administrator's command prompt or PowerShell window.

Unattended installation

KERNOVIQ-Setup-<version>.exe /S /ACCEPT_EULA /SERVERNAME=kernoviq.example.internal /LICENSEKEYFILE=C:\licence.txt
Option
/S silent (upper case, on its own)
/ACCEPT_EULA required with /S: you accept the End-User Licence Agreement
/EDITION=full or demo the full edition (default) or the trial; both serve the network
/SERVERNAME=name the DNS name users browse to (they can also use the IP address)
/LICENSEKEYFILE=file the licence key (required for the full edition)
/CERT=file /KEY=file [/CA=file] your organization's certificate (PEM)
/DATADIR=folder the data folder

Exit codes: 0 installed, 3010 Windows must restart (the installation continues after the next sign-in of the same administrator), 1 failed (see the logs, section 9), 2 cancelled or /ACCEPT_EULA missing.

The setup program runs the installation engine, which administrators can also run directly: kernoviq help lists its options (ports, --local, --allowed-cidrs, --firewall-public, local copies of the WSL package and the Ubuntu image).

3. What the installation sets up

Part What it is
C:\Program Files\KERNOVIQ the program: kernoviq.ps1 (engine and commands), bin\kernoviq.cmd (on the system PATH), the proxy (proxy\caddy.exe), licence texts, uninstall.exe
C:\ProgramData\KERNOVIQ config.json, logs\, backups\, keys\backup.key, kernoviq-ca.crt, the proxy's configuration and certificate (proxy\), the distribution's disk (wsl\)
WSL distribution KERNOVIQ Ubuntu 24.04 (Canonical's image, checked against its pinned SHA-256) with systemd, Docker Engine and Compose v2 from Ubuntu's archive and automatic security updates. No access to Windows programs or Windows drives. KERNOVIQ lives in /opt/kernoviq and is operated with kernoviqctl as on Linux
account kernoviq-wsl a local account that owns the distribution. Its random password is known only to Task Scheduler and never expires; it may only run scheduled tasks — signing in locally, over Remote Desktop or over the network is denied — and it is hidden from the sign-in screen
task \KERNOVIQ\Distribution at Windows startup, without anyone signed in: keeps the distribution running and starts it again if it stops; copies new backups out once an hour
task \KERNOVIQ\Run carries out administrators' kernoviq commands inside the distribution
service KernoviqProxy Caddy as the virtual account NT SERVICE\KernoviqProxy: HTTPS on 443 (TLS 1.2 and 1.3), a redirect from 80, a "starting" page while KERNOVIQ starts after a restart; the server name and this computer's IP addresses are served, other host names are sent to the server name. It forwards to 127.0.0.1:8280, which only this computer can reach
firewall rules (group KERNOVIQ) inbound 443 and 80 for the proxy service only, on Domain and Private networks (--firewall-public adds Public)
WSL settings the service account's .wslconfig: memory for the WSL virtual machine (three quarters of the computer's, between 4 and 16 GB, leaving 2 GB to Windows; kernoviq memory GB changes it)
Application event log source KERNOVIQ: installation, upgrades, and a warning (event 1001) when the distribution keeps stopping

Installed with --local (this computer only), there is no proxy service and no firewall rule: KERNOVIQ answers at http://127.0.0.1:8280 on this computer. So do trial installations made before the trial served the network; they keep that on upgrades.

4. Users and the network

  • Name or address: users browse to the server name, which must resolve to this computer (an A record in your DNS), or to this computer's IP address. The certificate is issued for that name and for this computer's IPv4 addresses; other names are redirected to the server name. When the address changes (DHCP), kernoviq cert renew adds the new one.
  • Internal CA: distribute C:\ProgramData\KERNOVIQ\kernoviq-ca.crt to the users' computers, for example by group policy (Computer Configuration → Policies → Windows Settings → Security Settings → Public Key Policies → Trusted Root Certification Authorities). kernoviq ca --trust also trusts it on this computer.
  • Your own certificate later: kernoviq cert install --cert FILE --key FILE [--ca FILE] (PEM, leaf first). The internal CA's server certificate is renewed with kernoviq cert renew; kernoviq doctor warns 30 days before it expires.
  • Firewall: the rules apply to Domain and Private networks. On a network Windows treats as Public, users cannot connect: classify the network as Private, or install with --firewall-public.
  • Internal systems (directory, mail relay, webhooks, scan targets in private ranges): --allowed-cidrs at installation, or kernoviq ctl as in airgap.md section 8.

5. Daily operation

Run these in an administrator's command prompt or PowerShell window:

Command
kernoviq status what runs, and whether KERNOVIQ answers
kernoviq doctor checks Windows, WSL, the distribution, the proxy, the certificate, DNS, the firewall and the backups, with advice
kernoviq start, stop, restart the whole application; restart web (one service)
kernoviq logs [-f] [SERVICE] the application's logs
kernoviq backup an encrypted backup now
kernoviq restore FILE [--force] replace all data with a backup (a backup of the current state is made first)
kernoviq cert show, renew, install the server certificate
kernoviq ca [--trust | --untrust] the internal CA certificate
kernoviq proxy reload write the proxy's configuration again and restart it
kernoviq memory [GB] memory of the WSL virtual machine (restarts KERNOVIQ)
kernoviq ctl ARGS… kernoviqctl inside the distribution, for everything else (airgap.md)
kernoviq upgrade, uninstall, version, help

After Windows restarts, KERNOVIQ is back within a few minutes without anyone signing in; until then users see the "starting" page.

6. Backups

KERNOVIQ makes an encrypted backup every night inside the distribution, and before every upgrade. Once an hour new backups are copied to C:\ProgramData\KERNOVIQ\backups: include that folder in your Windows backup. Copies older than 45 days are removed while at least 7 newer ones remain.

The backups are encrypted with the backup key (C:\ProgramData\KERNOVIQ\keys\backup.key, readable by administrators only). Keep a copy of it outside this computer. To restore:

kernoviq restore C:\ProgramData\KERNOVIQ\backups\kernoviq-<date>-<label>.kqbak

Uninstalling keeps the backups and the key. A new installation on the same computer takes that key over before it makes a backup of its own, so the earlier backups can be restored into it. A different key found there is kept as backup-<date>.key, never deleted. To restore on another computer, copy the key to C:\ProgramData\KERNOVIQ\keys\backup.key there before installing KERNOVIQ, then restore the backup into the new installation.

7. Upgrades

Run the newer setup program. It makes a backup, upgrades the distribution and KERNOVIQ, and rolls back to the previous release by itself if the upgrade fails; settings, data and certificates stay. It keeps the build the installation runs: the full edition (also one moved there from the trial) is fetched from the licence server with the licence key it has activated, so the key must cover the new release (licensing.md, "Updates"). To move a trial installation to the full edition by hand: kernoviq ctl upgrade-edition. Running the same version again repairs the Windows side (account, tasks, proxy, PATH). Unattended: KERNOVIQ-Setup-<version>.exe /S /ACCEPT_EULA.

If WSL itself needs an update that requires a restart, the setup says so (exit code 3010): restart Windows and run the setup program again.

8. Uninstall

Settings → Apps → KERNOVIQ → Uninstall (or uninstall.exe in the program folder). It makes a final backup, then removes the proxy service, the firewall rules, the distribution and its disk, the tasks, the service account and its profile, and the program folder. The backups and the backup key stay in C:\ProgramData\KERNOVIQ; tick Also delete all data, the backups and the backup key to remove them too.

Unattended: "C:\Program Files\KERNOVIQ\uninstall.exe" /S (keeps the backups) or /S /PURGE (deletes everything). Exit codes: 0 removed, 1 failed, 2 cancelled. WSL itself stays installed: other software may use it.

9. Troubleshooting

Logs: C:\ProgramData\KERNOVIQ\logs — install-*.log, upgrade-*.log, uninstall-*.log, distribution.log (the keepalive task), run.log (the request task), proxy.log. Windows' Event Viewer → Applications shows the events of the source KERNOVIQ. kernoviq doctor points at most problems.

Symptom Cause and fix
hardware virtualization is off turn on Intel VT-x / AMD-V in the firmware; in a Hyper-V virtual machine: Set-VMProcessor -VMName NAME -ExposeVirtualizationExtensions $true (VMware: "Expose hardware assisted virtualization")
cannot run WSL 2 as KERNOVIQ needs it update Windows to 10 22H2, 11, or Server 2022 or newer
this computer is a domain controller install on a member server
TCP port 443 is already in use another web server (IIS) holds it: stop that site, or install with --https-port
users get a certificate warning their computers do not trust the internal CA yet (section 4), or they use a name the certificate does not carry: use the server name
curl.exe on Windows: CERT_TRUST_REVOCATION_STATUS_UNKNOWN the internal CA publishes no revocation list, and Windows' curl insists on one; browsers do not: add --ssl-no-revoke (scripts and monitoring)
users cannot connect at all DNS does not point to this computer, or the network is Public for Windows (section 4); kernoviq doctor checks both
the "starting" page stays the distribution does not come up: kernoviq doctor, distribution.log; event 1001 means it keeps stopping
the setup failed the reason is in the wizard's details and in install-*.log; fix it and run the setup program again: it continues with what is already done
PowerShell refuses the scripts group policy requires signed scripts (AllSigned): KERNOVIQ's scripts are signed, so add the publisher's certificate to the computer's Trusted Publishers

10. Security notes

  • The distribution cannot start Windows programs and sees no Windows drives; files move between Windows and it only through the request task, as the service account.
  • Only the proxy service listens on the network. KERNOVIQ's own port 8280 is bound to 127.0.0.1; PostgreSQL, Valkey and the API are not published outside the distribution.
  • The backup key, the proxy's private key and the configuration are readable by administrators and SYSTEM only; the service account can only change the folders it works in.
  • The setup program, the uninstaller and the PowerShell scripts are signed with the publisher's code-signing certificate; the downloads the installation makes (WSL, Ubuntu, Caddy, KERNOVIQ) are checked against pinned checksums or the release signature.
  • KERNOVIQ sends no telemetry from Windows either.

This page is generated from the Windows guide that ships with the product.