Appendix F — Version Pinning and Update Control

F.1 Why pin versions at all

Throughout this course you will capture screenshots, record rule IDs, and compare command output against printed expected results. Every one of those artifacts is tied to a specific software version. If the Wazuh manager upgrades itself midway through Lab 5, the dashboard chrome changes, field names may shift, and the output you are told to expect stops matching the output you see. You will spend an hour debugging a lab that was never broken.

Version pinning is not about avoiding updates forever. Wazuh 4.14.7 may well be better than 4.14.5. It is about controlling when change happens, so that change is an event you plan for rather than an accident you discover.

Lab version authority. Wazuh Manager, Indexer, and Dashboard: 4.14.5-1 · Suricata: 1:8.0.6-0ubuntu3 · Ubuntu: 26.04 · Amazon Linux: AL2023. These are the versions the labs were validated against. Do not change them mid-course.

Note. This appendix is referenced from three points in the course. Apply it once during Lab 0 setup, confirm it before each lab run, and reverse it only when a version upgrade is planned work. Appendix A.12 covers the Suricata service override on UB2604 and assumes the hold described here is already in place.

F.2 The two-layer model

Package managers can be stopped at two different points, and the distinction matters because the two layers fail in different ways.

A visibility lock hides the source. The package manager never learns that a newer version exists, so it cannot offer one. On Amazon Linux this is enabled=0 in the repository file; on Ubuntu it is a commented-out or disabled source entry.

An action lock permits the package manager to see the newer version but forbids it from acting. On Amazon Linux this is an exclude= directive; on Ubuntu it is apt-mark hold.

Use both. A visibility lock alone is fragile because ordinary events re-enable repositories: a reinstall that rewrites the repository file, a copied-and-pasted command from vendor documentation, a colleague running dnf config-manager. An action lock alone is fragile in a different way, because the package manager keeps advertising the upgrade and eventually somebody accepts it. Together they cover each other.

F.3 Before you touch anything: back up and verify

Every step in this guide edits a configuration file in place. Make a copy first, and then prove the copy is good. A copy you have not verified is not a backup; cp can produce a zero-byte file if the filesystem is full, and you will not find out until you need to restore.

sudo cp -p /etc/yum.repos.d/wazuh.repo /etc/yum.repos.d/wazuh.repo.bak-$(date +%F)
sudo cp -p /etc/dnf/dnf.conf /etc/dnf/dnf.conf.bak-$(date +%F)
sha256sum /etc/yum.repos.d/wazuh.repo /etc/yum.repos.d/wazuh.repo.bak-$(date +%F)
sha256sum /etc/dnf/dnf.conf /etc/dnf/dnf.conf.bak-$(date +%F)

Each pair of hashes must match, and no backup may be zero bytes. The -p flag preserves permissions, ownership, and timestamps, which matters when you restore. If the hashes do not match, stop and find out why before editing anything.

Note. Naming matters in /etc/yum.repos.d/. The dnf tool reads only files ending in .repo, so wazuh.repo.bak-2026-08-23 is safely ignored. A backup named wazuh-old.repo would be parsed as a second, fully enabled repository and would silently undo the freeze you are about to apply.

F.4 Freezing WAZUH-SRV (Amazon Linux 2023, dnf)

rpm -qa | grep -Ei 'wazuh|filebeat' | sort
grep -n 'enabled' /etc/yum.repos.d/wazuh.repo

sed 's/^enabled=1/enabled=0/' /etc/yum.repos.d/wazuh.repo | diff /etc/yum.repos.d/wazuh.repo -

4c4
< enabled=1
---
> enabled=0

sudo sed -i 's/^enabled=1/enabled=0/' /etc/yum.repos.d/wazuh.repo
grep -n 'enabled' /etc/yum.repos.d/wazuh.repo

cat -n /etc/dnf/dnf.conf

sed '/^\[main\]/a exclude=wazuh-*' /etc/dnf/dnf.conf | diff /etc/dnf/dnf.conf -

sudo sed -i '/^\[main\]/a exclude=wazuh-*' /etc/dnf/dnf.conf
cat -n /etc/dnf/dnf.conf

sudo dnf clean expire-cache
sudo dnf check-update 'wazuh*' 2>&1 | grep -Ei '^wazuh|Error|skip'; echo "exit=${PIPESTATUS[0]}"

sudo dnf --enablerepo=wazuh check-update 'wazuh*' 2>&1 | grep -Ei '^wazuh|Error|skip'; echo "exit=${PIPESTATUS[0]}"

sudo dnf --enablerepo=wazuh --disableexcludes=all check-update 'wazuh*' 2>&1 | grep -Ei '^wazuh|Error|skip'; echo "exit=${PIPESTATUS[0]}"

wazuh-dashboard.x86_64    4.14.7-1    wazuh
wazuh-indexer.x86_64      4.14.7-1    wazuh
wazuh-manager.x86_64      4.14.7-1    wazuh
exit=100

F.5 Freezing UB2604 (Ubuntu 26.04, apt)

sudo apt-mark showhold
sudo apt-mark hold wazuh-agent
sudo apt-mark showhold

ls -l /etc/apt/sources.list.d/
grep -ril wazuh /etc/apt/ 2>/dev/null; echo "matches=$?"
apt-cache policy wazuh-agent

wazuh-agent:
  Installed: 4.14.5-1
  Candidate: 4.14.5-1
  Version table:
 *** 4.14.5-1 100
        100 /var/lib/dpkg/status

apt-cache policy suricata

suricata:
  Installed: 1:8.0.6-0ubuntu3
  Candidate: 1:8.0.6-0ubuntu3
  Version table:
 *** 1:8.0.6-0ubuntu3 500
        500 https://ppa.launchpadcontent.net/oisf/suricata-stable/ubuntu resolute/main amd64 Packages
        100 /var/lib/dpkg/status
     1:8.0.3-1 500
        500 http://archive.ubuntu.com/ubuntu resolute/universe amd64 Packages

# one-line format: /etc/apt/sources.list.d/wazuh.list
sudo cp -p /etc/apt/sources.list.d/wazuh.list /etc/apt/sources.list.d/wazuh.list.bak-$(date +%F)
sudo sed -i 's/^deb /#deb /' /etc/apt/sources.list.d/wazuh.list
sudo apt update

# deb822 format: /etc/apt/sources.list.d/wazuh.sources
sudo cp -p /etc/apt/sources.list.d/wazuh.sources /etc/apt/sources.list.d/wazuh.sources.bak-$(date +%F)
# add this line inside the stanza:
#   Enabled: no
sudo apt update

F.6 The false pass: when a clean result means nothing

During validation of this procedure the lab lost DNS resolution. The verification command produced this:

Error encountered while trying to retrieve release update information:
Unable to retrieve release info data. Curl error (6): Could not resolve
hostname for https://cdn.amazonlinux.com/al2023/core/releasemd.xml
exit=0

Exit code zero. No packages listed. By the letter of the test, a pass. In reality dnf had reached nothing at all, and skip_if_unavailable=True suppressed the failure into a warning. A frozen host and a host with no network connection produce identical output here.

Always confirm name resolution and reachability before trusting a package-manager result.

getent hosts packages.wazuh.com
curl -sS -o /dev/null -w '%{http_code} %{remote_ip}\n' https://packages.wazuh.com/

A 403 response from that URL is expected and healthy: the content delivery network refuses a directory listing at the bucket root. What matters is that an HTTP status and a remote address came back at all. If getent returns only IPv6 addresses, check the remote_ip field to see which protocol the connection actually used before concluding that IPv6 is required.

F.7 Windows agents

WIN11 needs no freeze. The Windows agent has no self-update mechanism; it changes only when someone runs the installer or when the manager pushes an upgrade package. Both are deliberate acts, so the control here is procedural rather than technical: do not run agent_upgrade, and do not issue a PUT to the API upgrade endpoint, until the version bump is a planned piece of work with its own verification.

F.8 Unfreezing

Reverse the layers in the opposite order to the one you applied them. Take the action lock off last, so that the moment you make upgrades possible is a moment you have chosen.

sudo sed -i '/^exclude=wazuh-\*/d' /etc/dnf/dnf.conf
sudo sed -i 's/^enabled=0/enabled=1/' /etc/yum.repos.d/wazuh.repo
cat -n /etc/dnf/dnf.conf
grep -n 'enabled' /etc/yum.repos.d/wazuh.repo

sudo dnf clean expire-cache
sudo dnf repolist | grep -i wazuh
sudo dnf check-update 'wazuh*' 2>&1 | grep -Ei '^wazuh|Error|skip'; echo "exit=${PIPESTATUS[0]}"

Verify the unfreeze, not just the freeze. Because skip_if_unavailable=True hides unreachable repositories, an unfreeze that silently failed looks exactly like an unfreeze that worked. Confirm that Wazuh actually appears in dnf repolist output. Expect exit=100 and the newer packages listed: here, exit code 100 is the success condition.

sudo apt-mark unhold wazuh-agent
sudo apt-mark showhold
apt-cache policy wazuh-agent

If you disabled an apt source, restore it from the verified backup rather than editing it back by hand.

sudo cp -p /etc/apt/sources.list.d/wazuh.list.bak-YYYY-MM-DD /etc/apt/sources.list.d/wazuh.list
sudo apt update
apt-cache policy wazuh-agent

Note. An upgrade is more than a package change. Dashboard chrome, agent user interface elements, and version strings printed in command output all shift, which means every screenshot showing version information must be recaptured and every pinned version string in your notes updated. Plan the upgrade as a project, not as a command.

F.9 Troubleshooting: errors seen during validation

Every error below occurred while this procedure was being validated on the live lab. They are ordinary and worth recognising on sight.

F.10 Checkpoints

Record each result. A checkpoint you did not write down is a checkpoint you did not perform.

F.11 Quick reference

Two habits are worth taking from this guide into everything else you do. Always read the file back from disk rather than trusting a tool report of its own success. And before you rely on any control, prove that it is capable of failing.