Upgrade KernelCare agent and ePortal in the right order

KernelCare upgrades are uneventful when you do them in the right order. They are a Saturday-afternoon outage when you don't. The rule is simple: ePortal first, agents second. Older agents speak to newer ePortals fine; the reverse is not guaranteed and breaks outright above the 2.66 agent cutoff.

This walks through the upgrade for a typical 50-500 server fleet, including the snapshot you should take before touching anything and the rollback path if a patch regression slips through.

Pre-flight

Before anything else, snapshot the ePortal state. The DB is the only thing you cannot easily reconstruct — keys, server registrations, feed configuration all live there.

systemctl stop eportal
cp /var/lib/eportal/db.sqlite3 /var/lib/eportal/db.sqlite3.$(date +%F)
cp /etc/eportal/config.yml /etc/eportal/config.yml.$(date +%F)
systemctl start eportal

For PostgreSQL-backed deployments, pg_dump eportal > eportal-$(date +%F).sql instead. If you don't have an ePortal yet, the air-gapped install guide is the starting point.

Then record the current versions so you have a known-good to roll back to:

eportal-cli version
rpm -q kcare-eportal

On a representative agent:

kcarectl --version
rpm -q kernelcare

Upgrade the ePortal

ePortal ships in the TuxCare RPM repo configured by the original installer. The upgrade is a yum update plus a restart:

yum -y update kcare-eportal
systemctl restart eportal
eportal-cli version

Wait for the systemd unit to come up cleanly (systemctl status eportal) before moving on. The first request after restart triggers Django migrations against the DB — that's why the snapshot above matters.

Verify the UI loads, log in, and check that Feeds → Status shows a recent successful sync. If anything looks wrong, restore the DB and downgrade:

systemctl stop eportal
dnf history undo <id>            # last yum transaction
cp /var/lib/eportal/db.sqlite3.<date> /var/lib/eportal/db.sqlite3
systemctl start eportal

Upgrade agents

Validate the new ePortal for 24 hours under normal traffic before touching agents. Then push the agent upgrade through whatever config management you use — Ansible, Salt, Puppet — across the same staged rings described in the production rollout playbook.

The per-host commands are:

yum -y update kernelcare
kcarectl --update
kcarectl --info

kcarectl --update re-fetches the patchset from the ePortal and loads it. --info should report the new agent version and the latest patch_level for the feed the server belongs to.

Confirm the version cutoff

The current ePortal release requires agents at ≥ 2.66. Older agents will fail registration with a TLS or protocol mismatch error in /var/log/kcare/kcare.log. Check the fleet before the push:

ansible all -m shell -a 'kcarectl --version' | awk '/kcarectl/ {print $3}' | sort | uniq -c

Anything below 2.66 needs a one-shot yum -y install kernelcare-2.66 first, then the standard update.

Rollback

KernelCare's rollback story is one of its better features. Two layers exist:

1. In-memory patches: kcarectl --unload removes the patchset without rebooting. The kernel reverts to its on-disk state instantly. Use this when a specific patchset triggers a regression — for example, a NIC driver patch that causes packet loss.
2. Agent RPM: dnf history undo <id> reverts to the previous agent RPM. Pair with kcarectl --update afterwards to re-apply patches with the older client.

For the ePortal, dnf history undo plus the DB snapshot is the full rollback. The TuxCare repo keeps the previous two minor releases available; older builds need a support ticket.

Health checks after the upgrade

Two checks catch the common post-upgrade issues:

# Agents reporting the expected patch_level
ansible all -m shell -a 'kcarectl --patch-info | grep ^kernel_id'

# ePortal showing all agents checked in within the last 6 hours
eportal-cli servers list --inactive 21600

Anything in the --inactive output is either offline or stuck on an older agent that can't talk to the new ePortal. Reach the box, downgrade the agent if needed, and re-register.

Next steps

• New to ePortal? Start with install KernelCare ePortal air-gapped.
• Buying or renewing seats: see the KernelCare license page.
• Volume upgrades or migration help: contact sales.