Your Ubuntu server.
Your ZenShield appliance.

Before you begin

Download this manual for offline use

Requirement	Supported configuration
Operating system	Ubuntu Server 24.04 LTS, amd64 / x86-64, running systemd on a server or full virtual machine.
Compute	4 logical CPUs and approximately 16 GiB RAM recommended. The native installer warns about lower resources and continues automatically. Size production deployments for event volume and retention.
Storage	100 GiB system filesystem with 30 GiB free recommended. The native installer has no CPU, memory or storage minimum gate; no override flag is needed. Actual out-of-memory or disk-full errors can still prevent installation or service startup. Add dedicated data disks for larger log stores.
Access	A sudo administrator and an interactive terminal. Keep VM console or out-of-band access available.
Connectivity	DNS, accurate time, and outbound HTTPS to Zentryc, Ubuntu repositories, and the container registry. TCP 80/443 and UDP 514 must be available locally.

Use a clean, dedicated server. The installer does not upgrade Ubuntu, format extra disks, or migrate another application. It checks for an existing appliance, conflicting ports, and existing Docker workloads. Your current IP configuration and existing Ubuntu administrator access are retained.

1. Install with one command

Current fresh-install baseline: ZenShield 0.4.4 · 16 September 2026. New installations use this signed OTA release directly. No intermediate upgrade or support helper is needed.

Run this command in your Ubuntu terminal. The downloaded launcher verifies the signed bootstrap and the OTA package before installing the application.

curl -fsS -A zenshield-installer/1 https://zentryc.com/downloads/zenshield/install.sh | sudo bash

If curl is missing, install it first:

sudo apt-get update && sudo apt-get install -y curl ca-certificates

To inspect the launcher and run compatibility checks before installation:

curl -fsS -A zenshield-installer/1 https://zentryc.com/downloads/zenshield/install.sh -o zenshield-install.sh
less zenshield-install.sh
sudo bash zenshield-install.sh --check
sudo bash zenshield-install.sh

The installer downloads the released application image, loads it locally, and pulls the database, cache, and proxy images by fixed digest. It configures the management shell, service supervision, update client, firewall rules, bounded container logs, SSH protection for the ZenShield account, and unattended Ubuntu security maintenance without automatic reboot.

2. Complete first-time setup

1. Choose the appliance hostname and timezone.
2. Set a unique GUI administrator password and a separate console password. The native installer uses ZenShield 0.4.4. Each password must contain at least 5 characters and at most 72 UTF-8 bytes, with no uppercase, number or symbol required; apostrophes, backslashes, NUL and line breaks are not accepted. Input is hidden: no characters or asterisks appear. Spaces are allowed. Enter the same value at Confirm password:; the wizard explains rejected entries.
3. Wait for all six services to become healthy.
4. The appliance automatically registers with Zentryc and receives a 30-day unrestricted trial. If offline, registration retries automatically after connectivity returns.
5. Open the displayed HTTPS management address and sign in as admin.

The instance creates its own database secrets and TLS certificate. Verify the certificate fingerprint shown in the console before trusting it. Replace it with a certificate issued by your organization for your deployment.

There is no shared default password. If the initial setup is interrupted, resume it with:

sudo zenshield-setup

After setup, this command reports that the appliance is already configured. Manage it from the GUI or the ZenShield shell. Rerunning the installer does not reset your data or passwords.

Verify your new appliance

Run sudo zenshield, then show version, show services, show ip interface brief, show storage and show updates. Confirm version 0.4.4, healthy services, the expected IP address and storage capacity. Check registration under System → Licences, then verify a fresh event from an approved log source. Read the 0.4.4 release notes.

3. Use the ZenShield command line

From the existing Ubuntu administrator account:

sudo zenshield

Or sign in at the VM console as zenadmin using the console password chosen during setup. Its login shell is the ZenShield CLI.

Command	Purpose
help	Display the available appliance commands.
show version	Check the installed appliance version.
show ip interface brief	List interfaces and addresses.
show ip route	Inspect routing.
show dns	Check DNS configuration.
show services	Check application, collection, database, cache, and proxy health.
show storage	Inspect disks, data volumes, and capacity.
show updates	Inspect registration, eligible releases, and installation status.
ping 192.0.2.1	Test connectivity; replace the example with your destination.
setup	Open guided appliance configuration.
password gui	Change the GUI administrator password.
password console	Change the ZenShield console password.
expert	Enter Linux maintenance after console-password authentication.

Change the management network

Use System → Network, or stage a change in the CLI:

configure terminal
network
commit
confirm <token-shown-after-commit>
end

Follow the prompts for interface, DHCP or static address, gateway, and DNS. Confirm reachability within 120 seconds; otherwise the watchdog restores the previous network. Use rollback to restore it immediately. A remote session may disconnect when the address changes.

4. Connect a log source

1. Point a supported firewall or syslog source at the appliance management address on UDP port 514.
2. Open Devices in the GUI and review the discovered source.
3. Approve the intended device. Events from pending devices are discarded; they are not retained for later approval.
4. Send fresh events and verify them under Logs. Check source address, timestamp, and parsed fields.

Keep UDP syslog on a trusted collection network. The appliance databases and cache are not exposed publicly. If immediate application of device approval is needed, run service restart syslog from the ZenShield shell.

5. Add and extend storage

The native installation starts with Docker-managed data volumes on the system filesystem. In System → Storage, select a new blank disk, review the plan and exact confirmation phrase, and initialize the data pool. Migration pauses services, verifies the copy, and retains the original volumes for recovery.

You can add another blank disk, rescan an expanded virtual disk, and grow the ClickHouse or application volume. No disk is formatted by the one-command installer. Keep every disk belonging to the pool attached. Shrinking or removing allocated disks requires a separate offline migration; LVM pooling does not provide redundancy.

If the system disk is larger than its filesystem, choose Rescan attached and expanded disks, then Grow system filesystem for a supported layout. The system disk stays protected from blank-disk initialization. Read the storage and expansion manual for supported layouts, commands and recovery guidance.

6. Licences and registration

New ZenShield 0.4.4 installations automatically register after setup. Open System → Licences to see the registration ID, trial or subscription, plan, allowance, expiry, and last synchronization. The default trial lasts 30 days and includes all features with unlimited devices and events. Existing registered installations retain their assigned subscription when upgraded.

Registration uses a unique device key, a single-use signed challenge, and an appliance-bound signed licence. Repeating registration with the same identity preserves the original trial expiry. Keep the appliance identity in backups; deleting it does not issue a fresh trial for the same virtual hardware. A separate clone needs its own virtual hardware identity.

In the fleet Appliances tab, find the appliance by registration ID or management address. In Subscriptions, open its subscription and choose Edit Subscription. Set Extend by days, change Trial to Subscription, select a plan, or adjust the unlimited allowance. Save Changes. The appliance synchronizes every five minutes; Refresh licence applies changes immediately.

An administrator can reassign the appliance in fleet, or issue a single-use registration code from another ZenShield subscription. Enter that code under System → Licences to transfer the appliance. Codes must belong to an active subscription with an available appliance slot. Publisher passwords are never entered on an appliance.

Trial expiry or suspension is visibly reported; this release keeps collection and existing data available. Offline appliances retain their verified licence, calculate expiry locally, and show a stale synchronization notice after 24 hours. Restore outbound HTTPS access to zentryc.com, working DNS and accurate time to synchronize again.

7. Install future updates

The tested upgrade baseline for 0.4.4 is 0.4.3. Older appliances receive 0.4.3 as an intermediate release first. Fresh installations start directly on 0.4.4. Use the signed support instructions below if an older updater stops before installing its bridge release.

Registration is automatic after first-time setup. Use System → Updates or the commands below. An older unregistered appliance can use update register with a dedicated token from its Zentryc administrator before upgrading.

update check
show updates
update install

In the GUI, choose Install update, review the offered version, and choose Install now or Cancel. The 0.4.4 GUI does not require a typed phrase. The CLI still requires INSTALL X.Y.Z for the offered version. Updates verify product, compatibility, signature, and checksums, then back up the datastores before switching images. Keep sufficient free space for a complete backup and keep the appliance powered on.

Automatic installation defaults to off. The GUI can enable installation within a UTC maintenance window. A registration does not guarantee an offer: the server also checks release scope and rollout eligibility.

Existing appliance stopped by its older updater

If an existing 0.3.4 appliance reports du failed (exit 1) before installing 0.4.3, follow the signed support upgrade instructions. The helper loads the corrected updater before retrying, retains existing backups, and pauses services during installation. It accepts versions 0.3.3, 0.3.4, 0.4.0, 0.4.1 and 0.4.2; it is not needed for a fresh 0.4.4 installation. Do not reinstall or delete data to resolve this error.

After upgrading an appliance with existing events, historical analytics can continue in the background. View System → Storage Monitor → Historical analytics processing. A fresh installation has no previous history to process.

Legacy VMware download · 0.3.1

This is the unchanged older image, not the 0.4.4 fresh-install baseline. For a new VM, install Ubuntu Server 24.04 LTS and use the native installer above. For existing deployment workflows, download the ZenShield 0.3.1 OVF package. It includes the descriptor, compressed virtual disk, manifest, checksums, and offline manuals. Allocate 4 vCPUs, 16 GB RAM and a 100 GiB system disk. This 0.3.1 OVF retains its original 16-byte setup minimum; the current native installer uses the 5-character minimum. This package uses EFI, LSI Logic SCSI, VMXNET3 and VMware virtual hardware 19.

Download legacy 0.3.1 OVF · 1.94 GB SHA256 checksum

553958461d24ad28841384bcb3ddbb8265735cfe0dc2c453ad534431a74c0718

1. Verify the ZIP checksum and extract every file into the same folder.
2. In VMware Workstation, choose File → Open and select ZenShield-0.3.1.ovf. Keep the referenced .vmdk.gz file beside it; do not extract that file separately.
3. Choose a new VM directory, review resources and map the nat network to your intended management network.
4. Power on and open the VM console. Complete the network, reachability confirmation, hostname, timezone, GUI password, console password and SSH management CIDR prompts.
5. Wait for setup to complete, then open https://<appliance-address>/system/ and sign in as admin.

The image contains no shared passwords, test accounts, SSH keys, TLS private keys, collected data or OTA registration. Each import creates its own identity. SSH is key-only; add your own authorized key through authenticated console maintenance if needed. The imported appliance is already installed, so continue with the command, device, storage and update sections below.

This OVF is validated with VMware Workstation. KVM conversion and other hypervisors require separate validation. The native Ubuntu installer above is the recommended path for a new 0.4.4 deployment.

Troubleshooting and recovery

If an older password prompt repeats a generic message, press Ctrl+C and rerun the public installer command. It refreshes the wizard when setup is unfinished, preserving existing data. Use a unique password of at least 5 characters and repeat it at confirmation. Running sudo zenshield-setup alone uses the already installed wizard. Never include your password in support messages.

Ubuntu package installation may restart network and DNS services. The OTA release download retries temporary DNS, connection, timeout and transient HTTP failures up to six attempts, waiting 5, 10, 20, 30 and 30 seconds. If DNS remains unavailable, run getent hosts zentryc.com and resolvectl status, verify DNS and outbound HTTPS, then rerun the same installer. Complete checksum-verified downloads are reused; partial downloads are discarded. Your configured DNS servers are preserved, and TLS, signatures and checksums remain enforced.

sudo systemctl status zenshield-agent zensheild
sudo journalctl -u zensheild -u zenshield-agent --since "15 minutes ago"
sudo zenshield-setup
sudo zenshield-update check

If setup pauses, correct the reported problem and rerun it. Instance secrets are retained after initialization. For a failed update, inspect System → Updates and the service journal; the updater attempts verified rollback. Do not delete its backups while an installation or recovery is active.

Back up the entire appliance, including every attached data disk. Test restoration before relying on it. Allow for a maintenance window: installation and updates briefly pause GUI access and log collection.

Contact Zentryc for deployment support and registration tokens · Back to ZenShield