# Historical upgrades and complete removal

SysWarden v4.10.3 was published on 8 October 2026 after protected Patch IVV and independent verification of all twelve public files. Read the [dated publication record](https://github.com/duggytuxy/syswarden/blob/7620582037f537df9960dc8f0da1f6bc7d313199/docs/releases/v4.10.3/README.md) for exact identities and evidence limits.

This guide covers recognized historical SysWarden installations on Debian 13. Recovery preserves administrator configuration and unrelated protection while retiring proven product state. A path, service name or firewall comment alone does not prove ownership.

## Choose the intended outcome

| Situation | Recovery path |
| --- | --- |
| An older upgrade is refused before unpacking | Keep the older package intact, inspect the reported historical state, then retry the verified upgrade. |
| v4.10.2 is already half-configured | Use the authenticated v4.10.3 recovery executable separately from the installed package. Resolve the reported state before continuing installation or removal. |
| Historical `wg0` coexists with generated `wg-syswarden` files without a manifest | Review retirement and migration separately. Preserve the current client and keys. |
| Removal is interrupted by historical service, firewall or configuration evidence | Keep the removal barrier and original evidence. Complete the specific reviewed recovery before repeating the native removal command. |
| Removal succeeds but a private archive remains | Distinguish deliberate recovery backups from active configuration. Verify that they cannot recreate product state. |

Use a recoverable test system first. Keep a private snapshot, original configuration and relevant evidence. Confirm an administrative connection or console independent of the VPN before stopping it. Decide whether each VPN should be preserved or retired.

Plans contain operational metadata even when they omit secret values. Keep their output, configurations, archives and raw diagnostics private.

## Inspect package state

These commands read package registration and executable presence. Run them separately:

```sh
dpkg-query -W -f='${Status} ${Version}\n' syswarden
```

```sh
if sudo test -x /opt/syswarden/bin/syswarden-cli; then printf 'CLI executable present\n'; else printf 'CLI executable missing\n'; fi
```

Neither result proves that services or VPN traffic work. Do not infer success from an older updater's exit status alone: the historical updater can print a failure while returning zero.

## Obtain a separate authenticated recovery executable

When an older installation cannot upgrade or remove, obtain the official v4.10.3 AMD64 DEB and authenticate it using the [release verification procedure](https://syswarden.io/docs/getting-started/). Verify its provenance and detached native signature with independently trusted material. A checksum alone does not authenticate a download.

Do not overwrite the installed executable, clear the removal barrier or edit dpkg records. Extract the already authenticated package into a new root-private directory. The following command additionally checks the exact package bytes and metadata. Replace the final argument with its actual absolute path:

```sh
sudo sh -eu -c 'umask 077; test -f "$1"; test ! -L "$1"; recovery_stage=$(mktemp -d /root/syswarden-recovery.XXXXXXXX); install -m 600 -- "$1" "$recovery_stage/package.deb"; printf "%s  %s\n" 4c7d280a0a58470b341fcdee55f591025a452c7abb2e536e3f5a2b5c04624689 "$recovery_stage/package.deb" | sha256sum -c --status; test "$(dpkg-deb --field "$recovery_stage/package.deb" Package)" = syswarden; test "$(dpkg-deb --field "$recovery_stage/package.deb" Version)" = 4.10.3; test "$(dpkg-deb --field "$recovery_stage/package.deb" Architecture)" = amd64; mkdir -m 700 "$recovery_stage/root"; dpkg-deb --extract "$recovery_stage/package.deb" "$recovery_stage/root"; chmod 700 "$recovery_stage/root"; test -x "$recovery_stage/root/opt/syswarden/bin/syswarden-cli"; printf "Recovery executable: %s/root/opt/syswarden/bin/syswarden-cli\n" "$recovery_stage"' sh /absolute/path/to/verified/syswarden_4.10.3_amd64.deb
```

This extraction does not install the package or execute its maintainer scripts. For an older installed version, substitute the printed absolute executable path for `syswarden` in every recovery command below, including apply examples printed by a plan. Continue to use the real host configuration and evidence.

## Retire an unwanted historical WireGuard namespace claim

Inspect the old VPN without applying changes:

```sh
sudo syswarden recover-wireguard --retire-legacy-wg0
```

The plan identifies exact supported state and runtime blockers. Missing ownership manifests are supported only when the complete historical generated installation is recognized, including the server, client, forwarding file and their key relationships. Partial or customized configurations remain unresolved.

If the operator has decided to retire `wg0` and independent administration works, stop and disable only the VPN services identified by the plan. The recovery command does not stop them automatically. Do not stop an unrelated administrator VPN.

Repeat the inspection after any service or firewall change. Historical shutdown hooks may remove the private NAT table; the recovery route supports its absence and exact residual forwarding rules. Additional manual firewall deletion is unnecessary.

When the fresh plan reports that it is safe to apply, review its effects and authorize only its exact digest:

```sh
sudo syswarden recover-wireguard --retire-legacy-wg0 --apply --plan-sha256 REVIEWED_LOWERCASE_SHA256
```

The command archives the recognized old configuration privately and retires only proven historical runtime state. It preserves the three unmanifested current VPN files. Their ownership migration is a separate operation.

## Migrate and preserve the generated current VPN

Inspect the remaining historical generated VPN:

```sh
sudo syswarden recover-wireguard --migrate-legacy-wg-syswarden
```

This plan requires that VPN to be inactive and disabled, with its interface absent. It verifies the complete generated templates, permissions, keys, addresses and file identities. Foreign rules, duplicate rules, unsupported topology and changed evidence cause refusal.

After reviewing the fresh plan:

```sh
sudo syswarden recover-wireguard --migrate-legacy-wg-syswarden --apply --plan-sha256 REVIEWED_LOWERCASE_SHA256
```

Migration preserves the server key, client keys, preshared key, addresses, port and complete client configuration. It replaces historical server hooks with manifest-bound hooks and retains private originals before changing active configuration.

The supported historical forwarding allowances use the existing `inet filter forward` base chain. Its administrator policy and unrelated rules remain in place. Other administrator chains can still deny traffic, so service activation is not enough: verify actual VPN traffic to the intended destinations.

If interrupted, preserve the journal, originals and backups. Repeat the same migration inspection, review the new digest and resume with that digest. Do not delete evidence to restart the operation.

## Continue installation or removal

Migration does not start the VPN. Its new hooks require v4.10.3.

For an older installed version, including half-configured v4.10.2, install the authenticated v4.10.3 package after the required recovery:

```sh
sudo apt-get install /absolute/path/to/verified/syswarden_4.10.3_amd64.deb
```

If v4.10.3 is already unpacked, resume its package-specific configuration:

```sh
sudo dpkg --configure syswarden
```

Do not run v4.10.2 configuration against newly migrated v4.10.3 hooks. If removal was the intended operation and its barrier remains, continue the native removal path instead of trying to activate the product.

The old updater uses a fixed temporary download path. On a hardened host, a stale download owned by `_apt` can make a retry fail before installation. Keep temporary-file protections enabled and use the authenticated package from its separate staging path. Do not perform broad temporary-directory cleanup.

## Remove the correct installation type

| Installation | Command |
| --- | --- |
| Standalone installation without native package registration | `sudo syswarden uninstall` |
| Debian native package, remove | `sudo apt-get remove syswarden` |
| Debian native package, purge | `sudo apt-get purge syswarden` |
| RPM native package | `sudo dnf remove syswarden` |
| Alpine native package | `sudo apk del syswarden` |

Standalone uninstall refuses native package registration before deleting product files. Native hooks must complete verified preparation before the package manager erases the executable.

Uninstall, remove and purge are separate paths. Each must remove proven SysWarden components while retaining administrator configuration and effective unrelated protection. A later purge must also preserve an administrator edit made after remove.

Removal is not a full rollback of the host. An unresolved ownership ambiguity means incomplete recovery. Do not flush shared tables, stop the entire Fail2ban service, remove custom administrator configuration or delete the durable removal barrier to force completion.

## Resolve the reported removal boundary

Use the command's actual error and the corresponding detailed reference. Do not run every recovery option as a generic cleanup sequence.

| Reported boundary | Required review |
| --- | --- |
| Historical systemd units or WAF rsyslog bridge | Recognize the exact historical generator, package authority and loaded state. Customized files remain protected. |
| Shared nftables persistence | Review original inputs, loader and include graph. Retire proven product entries and preserve administrator bytes. A persistent-source edit is distinct from live rule removal. |
| Former Fail2ban integration | Retire proven historical jails, actions and persistent entries while preserving independent jails, bans and the shared service. |
| Historical IPv4 compatibility rules | Use independently retained original generation captures. Current rules or matching names cannot manufacture missing ownership evidence. |
| Administrator IPv4 rules after a reboot or reload | A fresh explicit preservation decision may be required. It grants no deletion authority. |
| Customized modular configuration | Review `recover-removal --retain-operator-config` once removal is in progress and managed services are stopped. Preserve approved files at their original paths. |
| Administrator ingress policy inside a product table | Export, review and install an independent persistent receiver before product removal. Verify the actual loader, repeated reloads and traffic. |
| Legacy lists, logs or UI state without modern receipts | Use the bounded private-retention route only after confirming the listed files have no other producer. |

The detailed [removal boundaries](https://github.com/duggytuxy/syswarden/blob/2bbb1df10f0b6957a8393dec71f7135af3e098ca/docs/technical/VERIFIED_PRODUCT_REMOVAL.md) specify supported inputs, confirmation flags and interruption handling. The [historical package-removal reference](https://github.com/duggytuxy/syswarden/blob/2bbb1df10f0b6957a8393dec71f7135af3e098ca/docs/technical/HISTORICAL_PACKAGE_REMOVAL.md) describes exact service recognition and staged preparation for the half-configured historical package. These source references preserve their original candidate context; the current release acceptance is established separately by the verified publication record.

An administrator preservation decision is appropriate only after independently establishing that the remaining state belongs to the administrator or another application. It must not relabel unresolved product state. Any changed rules, reboot or changed relevant identity require the review specified by that route.

## Verify completion

After the selected operation, verify package registration, intended services, actual firewall rules and intended VPN traffic. For removal, verify both product absence and continued administrator protection after shared-service reloads and a real reboot.

Check separately that:

- Product services, active configuration and proven persistent or runtime rules are gone.
- Historical producers cannot recreate retired state.
- Independent SSH access, administrator firewall policy and unrelated Fail2ban protection still work.
- Retained administrator files remain at their intended paths and later edits survive a deferred purge.
- Private recovery backups remain private and cannot be loaded as active configuration.

Retain those backups until the operator has verified the outcome and applied the organization's retention policy. A successful package-manager exit code alone does not establish complete removal.

## Understand an optional OSINT warning

Two individually valid OSINT sources can have fewer than four common entries. Installation can then omit the optional supplement with an explicit warning while retaining independently validated primary feeds and existing snapshots. It publishes no uncorroborated union.

Explicit and hourly refresh still report insufficient intersection. Malformed, empty, individually undersized or unauthenticated source responses remain blocking. This change does not make every feed failure optional. See the [OSINT behavior reference](https://github.com/duggytuxy/syswarden/blob/2bbb1df10f0b6957a8393dec71f7135af3e098ca/docs/technical/OSINT_INSTALL_AVAILABILITY.md).