Virtual appliance (OVA / QCOW2)

The virtual appliance is the shortest path to a running Taranac. Instead of preparing a host, installing Docker and pulling images, you import one file, power it on, and answer a short wizard on the console. The stack then installs offline, from container images already baked into the disk — the appliance never contacts a registry, which is what makes it usable in closed segments.

It is not a different product, or even a different install: inside the appliance is the same deployment bundle in /opt/taranac. Once the wizard finishes you are looking at an ordinary Taranac install, and everything else in these docs — ./taranac commands, TLS certificates, upgrades, backups — applies unchanged.

Both are exported from the same golden image, so they behave identically. The OVA is built at hardware version vmx-13 (ESXi 6.5 and newer; verified on 6.7), and the image ships qemu-guest-agent alongside open-vm-tools so it is at home on either hypervisor.

Get the images from the download page.

Give the VM these before first boot — the wizard will not resize anything for you:

The disk is thin: it occupies a few GB after import and grows as TACACS+ and RADIUS accounting accumulate.

In the ESXi Host Client (or vSphere), start Create / Register VM and choose Deploy a virtual machine from an OVF or OVA file. Name the VM, then drop taranac-1.1.1.ova into the file box:

The rest of the wizard is defaults, with two choices that matter:

Leave the hardware alone — in particular the disk controller, which is pinned to LSI Logic so the image imports on ESXi 6.5. Finish the wizard, wait for the upload to complete, and power the VM on.

On Workstation or Fusion the equivalent is File → Open on the same .ova.

Skip ahead to First boot.

Proxmox has no OVF importer in the web UI, so the flow is: create a VM with no disk, then attach the downloaded QCOW2 to it from the shell. The settings below are not suggestions — the image boots with these and fails with some of the alternatives.

General — give it a name and note the VM ID; you need the ID in step 2.

OS — select Do not use any media. There is no installer to boot; the disk you attach later already contains the system.

System — the tab that decides whether the appliance boots at all:

Disks — remove every disk. The VM is created empty on purpose.

CPU — 4 vCPU, type host.

Memory — 8192 MiB.

Network — model VirtIO (paravirtualized), on the bridge that reaches your network devices.

Confirm — check the summary, leave Start after created off, and finish.

Copy the image to the Proxmox node and import it into the VM you just created. Throughout, 200 is your VM ID and local-lvm your target storage:

scp taranac-1.1.1.qcow2 root@proxmox:/root/
ssh root@proxmox
qm importdisk 200 /root/taranac-1.1.1.qcow2 local-lvm

On Proxmox 8 and newer the command is qm disk import with the same arguments; older releases keep importdisk. It prints the resulting volume, something like Successfully imported disk as 'unused0:local-lvm:vm-200-disk-0' — note that volume name.

The disk is now attached to the VM but unused, so two things remain: bind it to scsi0 and make it the boot device. From the same shell that is one command:

qm set 200 --scsi0 local-lvm:vm-200-disk-0 --boot order=scsi0

Or, in the web UI: Hardware → Unused Disk 0 → Edit, set the bus to SCSI device 0 and add it, then Options → Boot Order, tick scsi0 and drag it to the top.

Start the VM. If it drops into the BIOS or reports no bootable device, the boot order did not take — that is the step to re-check, along with BIOS being SeaBIOS rather than OVMF.

The setup wizard runs by itself on the console the first time the appliance boots — there is nothing to log into yet. Move with Tab and the arrow keys, and confirm with Enter.

Every step offers Skip, which keeps the current value. That is convenient for the hostname and unwise for the password.

Hostname — the appliance’s own name; the default is taranac.

Network — DHCP, or a static configuration entered as four short prompts in a row: IPv4 address, subnet prefix length, default gateway, and DNS servers.

A NAC box wants a fixed address. Whatever you choose here has to match what your switches will point their TACACS+ and RADIUS configuration at.

Timezone — pick a region, then a city, from the full tzdata list. This is worth getting right: it is the timestamp on every accounting and audit record.

Password for the taranac user — this is the SSH and console login for the operating system, not the Taranac admin account. Set it.

With the OS configured, the wizard offers to install the product. Install Taranac is the path you want; Manual installation just drops you into a shell in /opt/taranac with the bundle, for anyone who wants to run ./install.sh themselves.

It then asks the same three questions the bundle installer asks — the address users will open the admin UI at (defaulting to this appliance’s IP), the initial admin username, and its email address.

From there it runs unattended: generating every secret fresh for this installation, writing /opt/taranac/.env, and bringing the container stack up from the preloaded images.

Nothing is downloaded. The secrets are generated per install, not carried in the image, so two appliances deployed from the same file share no credentials.

The last screen shows the admin URL, the username, and a generated password.

Copy the password now. It is also written to /opt/taranac/.env as INITIAL_ADMIN_PASSWORD, and if it is lost entirely you can set a new one from the console:

cd /opt/taranac
./taranac reset-password admin

Give the stack a minute to finish starting, then open the URL. The certificate is self-signed until you install your own — see Installation → TLS certificate.

Log in on the console or over SSH as taranac and the banner reminds you where everything is:

sudo taranac-setup                             # re-run the setup wizard
cd /opt/taranac && ./taranac ps                # what's running
cd /opt/taranac && ./taranac logs -f api       # follow the API log
cd /opt/taranac && ./taranac reset-password admin

From here the appliance is an ordinary install:

• Quick start — first device, first policy, first successful authentication.
• Backups & upgrades — ./taranac update works exactly as documented. The appliance is not self-updating; OS and product patching stay on your schedule.

The wizard installs a core node only. Collector, witness and captive-portal roles are not part of it — deploy those as documented in their own pages.