11. Wipe-and-reinstall and changing product

Back to overview · Full table of contents · Download full PDF

This chapter: when you need to delete an existing deployment and install again, when you do not, and when a wipe is required how to preview first, then confirm, and where to continue after an error. Changing product (full edition and Zentrix Gateway swapping) can only take this path and is in the last section of this chapter. The readers are the implementation engineer and the customer system administrator. Before any write command in this chapter, obtain the customer's written consent and schedule a downtime window.

11.1 Three different entries

Applies to: an install already exists, and before you "install it again", first decide which of the three you actually want.

In the large majority of cases you want the first two: a new version is an upgrade; a wrong value filled in at install is refill configuration. Both keep data. Use delete-and-reinstall only when you have decided to discard all data and start from zero.

Procedure

1. To change version only: run sudo zenova upgrade <package.zpkg> with the new-version installer, or upload the upgrade package on console System maintenance › System Updates.
2. To change the access URL, notification channel, resource capacity, and similar: first see whether console System maintenance › Deployment configuration or zenova config set can change it online. Use --reconfigure only for items that cannot be changed online.
3. If neither solves it, and the customer agrees to discard all data: continue to section 11.2.

What you will see

• Running an ordinary install command again on a host that has already completed install, the installer stops and reports that this host has already completed installation (diagnostic code SVC_ALREADY_INSTALLED), and gives three destinations: upgrade with sudo zenova upgrade <package.zpkg>, change configuration with sudo zenova install --reconfigure, wipe-and-reinstall with --fresh. An ordinary install command does not overwrite an existing install.

Note: --fresh and --reconfigure are mutually exclusive and cannot be used together. --adopt-existing (takeover install onto existing platform data) also cannot be used with either of them.

11.2 Conditions

Prerequisite: all three of the following must hold. Missing any one, the installer refuses the wipe.

The following environments do not support wipe-and-reinstall:

• The platform database or analytics database uses an existing service;
• Object storage uses existing S3-compatible storage;
• Multi-host deployment;
• Kubernetes Helm deployment;
• A remote gateway-node host (zenova install node does not use --fresh; changing the control plane or the token uses --reenroll, see Chapter 9).

Note: when an environment that uses an existing database or existing S3 truly needs a reinstall, the customer's database administrator and storage administrator first handle the original databases and buckets themselves, then install as a first install. That part is not run by the installer and is out of scope for this manual. Gateway nodes on this host (including office-primary on the same host as the control plane) are cleaned with the wipe. If a node on this host was registered to another remote control plane, that node goes offline on that control plane and must be retired in its console.

11.3 Preview, then confirm

Applies to: the first step of every wipe-and-reinstall.

Prerequisite: the installer, offline package, answers file, and secrets file already sit in a directory outside the old install root and business directories (for example /root/zenova-install); see section 11.4.

Procedure

1. Run a read-only preview.

# Install host · root · read-only (preview the cleanup scope; does not stop services, delete data, or start install)
cd /root/zenova-install
sudo ./zenova install "$ZPKG" --fresh --dry-run

2. Check the preview output line by line and confirm that what is listed is the deployment on this host that you intend to delete.
3. When the preview has leftovers marked "ownership unproven" or carrying a risk hint, handle them in one of the three ways below. Do not clean up by hand:

# Install host · root · read-only (export a cleanup plan file for review)
sudo ./zenova install "$ZPKG" --fresh --dry-run --plan ./reinstall-plan.toml

# Install host · root · delete (wipe the old deployment per the reviewed plan and install again)
sudo ./zenova install "$ZPKG" --fresh --plan ./reinstall-plan.toml --confirm-data-loss DELETE_EXISTING_DATA

What you will see

• The preview summarizes every item to clean and every refused item in one pass: identity, version, and form of the old deployment, and the cleanup scope of services, business paths, exclusive containers, volumes, and networks.
• In the following cases the preview names the object and stops. Handle the listed object, then preview again:

Note: never clean leftovers of an old install with hand-written rm -rf, docker rm, systemctl, or similar. On-site operations and remote support always go through --fresh --dry-run, interactive confirmation, or a plan file. Hand deletion makes the installer unable to prove resource ownership. Later previews are refused, and the problem only gets harder.

Note: a plan file is valid only for the site at the time it was generated. After services are stopped, the installer checks the old deployment identity again. If it does not match the plan, it stops with FRESH_STATE_CHANGED. Then rerun --fresh --dry-run to generate a new plan file.

11.4 Execute and resume after interruption

Prerequisite: the preview and check in section 11.3 are done; the customer has agreed in writing to discard all data; a downtime window is scheduled. When old data must be kept, first run zenova backup and zenova backup export, and move the exported archive outside the cleanup scope. Wipe-and-reinstall does not back up automatically and deletes every local backup.

Procedure

1. Prepare the artifact directory. Use a standalone ./zenova of the same version as the new offline package. Do not use the zenova inside the install root that is about to be deleted (/usr/local/bin/zenova points at the old install). The installer, .zpkg, --answers answers file, and --secret-file secrets file must all sit outside the old install root (default /opt/zenova) and business directories. When they sit inside a directory about to be cleaned, the installer states that and stops.

# Install host · root · read-only (confirm artifact location and version)
cd /root/zenova-install
ls -l ./zenova "$ZPKG"
sha256sum "$ZPKG"

2. Run wipe-and-reinstall. The confirmation word must be filled in in full as DELETE_EXISTING_DATA.

# Install host · root · delete (wipe the old deployment, then install again)
sudo ./zenova install "$ZPKG" --fresh --confirm-data-loss DELETE_EXISTING_DATA

3. After install finishes, complete first sign-in and initialization again per Chapter 6, apply for and import a license again (section 6.4), then back up key material off-host again and take the first platform backup — the old key archive and backups are invalid for the new deployment.

What you will see

• Before deleting anything, the installer first checks: sha256 and size of every component in the new package, installer and offline-package version and platform, install answers, and whether selected capabilities are complete. If any item fails, deletion does not start, and the old deployment stays as it is. Component digests detect download corruption; they are not signature verification.
• After those pass, it runs in order: stop old services and containers and check the old deployment identity again → clean services, data paths, containers, exclusive volumes, and networks that belong to that install (Docker images and system accounts are kept) → install the new package as a first install and finish post-install acceptance.
• Completion output is the same as a first install: a new root initial password, access URL, and Next.

Where to continue after an interruption

Note: running --fresh again and confirming deletion, while the old deployment has been cleaned and the new install is not finished, means wiping local data once more. It is not continuing the previous install.

Note: wipe-and-reinstall generates a new deployment identity. The previous license, previous root password, previous two-factor binding, previous key material, and backups all become invalid. Existing tenants, members, model providers, and API keys must be created again. Callers need new API keys.

11.5 Changing product

Applies to: Zentrix Gateway is already installed and you will switch to the full edition, or the other way around.

Prerequisite: both products use the same install commands, but the product is locked at install time and cannot be changed in place after install. Swapping them can only be wipe-and-reinstall. The conditions in section 11.2 still apply.

Procedure

1. Explain the consequences to the customer and obtain written consent: all existing data is deleted; the previous license becomes invalid; you must export a license request on the new product and apply for a license again.
2. On the download site, choose the target product again and download the target product installer and offline package (Chapter 2). The product field in the offline-package file name must match the target product.
3. With the target-product installer, preview per section 11.3 and execute wipe-and-reinstall per section 11.4.
4. Complete initialization and license import again per Chapter 6, and accept again per Chapter 7.

What you will see

• Without a wipe, running an ordinary install with the other product's installer, the installer stops and reports "this host has already installed <installed-product>; this installer is the <other-product> edition; use an <installed-product> edition package". That means the product is locked: either switch back to a package of the installed product, or wipe-and-reinstall per this section.
• Output carrying diagnostic code ANS_EDITION_LOCKED (edition form is locked) means the same thing. The remedy is to run zenova install <package> --fresh and choose again.
• When the installer and offline package belong to different products, it reports "the package and the installer do not belong to the same version: the installer is the … edition, the package is the … edition". Switch to an installer and offline package of the same product.

Note: to enable or disable a capability (such as knowledge base) you do not need to change product and you do not need wipe-and-reinstall: enable a capability that already came with the offline package on the console System Updates page, or reselect capabilities with --reconfigure. Consider changing product only when the target capability is not in this product (the installer reports "… does not include the "…" capability; remove it from --with").

Capability notes

Previous: 10. Backup, restore, and upgrade · Next: 12. Troubleshooting and submitting support