From d2f36a4258682a52f4ac26c6587d963772186e80 Mon Sep 17 00:00:00 2001
From: Alan Dooley <a.dooley@f5.com>
Date: Wed, 17 Dec 2025 16:18:21 +0000
Subject: [PATCH] feat: Add version instructions for WAF virtual environments

This commit adds instructions to each platform in the F5 WAF for NGINX
virtual environment installation document to explain how to find and
install specific package versions.

As the information is optional, it is hidden by default using a details
element, and introduced at the point where the user would install a
package, as all other steps in the process are identical.
---
 content/waf/install/virtual-environment.md | 86 ++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/content/waf/install/virtual-environment.md b/content/waf/install/virtual-environment.md
index 30317ce7f..91b9619ff 100644
--- a/content/waf/install/virtual-environment.md
+++ b/content/waf/install/virtual-environment.md
@@ -54,6 +54,17 @@ sudo apk update
 sudo apk add openssl ca-certificates app-protect
 ```
 
+{{< details summary="Installing a specific version of F5 WAF for NGINX" >}}
+
+If you need to install a specific version of F5 WAF for NGINX, you can use `apk info` to list available versions, then append it to the package name:
+
+```shell
+sudo apk info app-protect
+sudo apk add openssl ca-certificates app-protect=<desired-version>
+```
+
+{{< /details >}}
+
 ### Amazon Linux
 
 Add the F5 WAF for NGINX repository:
@@ -74,6 +85,17 @@ Install the F5 WAF for NGINX package and its dependencies:
 sudo dnf install app-protect
 ```
 
+{{< details summary="Installing a specific version of F5 WAF for NGINX" >}}
+
+If you need to install a specific version of F5 WAF for NGINX, you can use `--showduplicates list` to list available versions, then append it to the package name:
+
+```shell
+sudo dnf --showduplicates list app-protect
+sudo dnf install app-protect-=<desired-version>
+```
+
+{{< /details >}}
+
 ### Debian
 
 Add the F5 WAF for NGINX signing key:
@@ -102,6 +124,27 @@ sudo apt-get update
 sudo apt-get install app-protect
 ```
 
+{{< details summary="Installing a specific version of F5 WAF for NGINX" >}}
+
+If you need to install a specific version of F5 WAF for NGINX, you can use `apt-cache` to list available versions, then append it to the package name:
+
+```shell
+sudo apt-get update
+sudo apt-cache policy app-protect
+sudo apt-get install app-protect=<desired-version>
+```
+
+When installing a specific version of F5 WAF for NGINX, you will also need to manually install its package dependencies. 
+
+You can use the following script to get the dependent packages:
+
+```shell
+findDeps () { local pkgs=$(apt show $1 2>/dev/null | grep Depends: | grep -oE "(nginx-plus-module|app-protect)-[a-z]+ *\(= *[0-9\+\.-]+~`lsb_release -cs`\)" | tr -d ' ()'); for p in ${pkgs[@]}; do echo $p; findDeps $p; done; }
+findDeps app-protect=<desired-version>
+```
+
+{{< /details >}}
+
 ### Oracle Linux / RHEL / Rocky Linux 8
 
 {{< call-out "important" >}}
@@ -140,6 +183,17 @@ Install the F5 WAF for NGINX package and its dependencies:
 sudo dnf install app-protect
 ```
 
+{{< details summary="Installing a specific version of F5 WAF for NGINX" >}}
+
+If you need to install a specific version of F5 WAF for NGINX, you can use `--showduplicates list` to list available versions, then append it to the package name:
+
+```shell
+sudo dnf --showduplicates list app-protect
+sudo dnf install app-protect-=<desired-version>
+```
+
+{{< /details >}}
+
 ### RHEL / Rocky Linux 9
 
 Add the F5 WAF for NGINX repository:
@@ -166,6 +220,17 @@ Install the F5 WAF for NGINX package and its dependencies:
 sudo dnf install app-protect
 ```
 
+{{< details summary="Installing a specific version of F5 WAF for NGINX" >}}
+
+If you need to install a specific version of F5 WAF for NGINX, you can use `--showduplicates list` to list available versions, then append it to the package name:
+
+```shell
+sudo dnf --showduplicates list app-protect
+sudo dnf install app-protect-=<desired-version>
+```
+
+{{< /details >}}
+
 ### Ubuntu
 
 Add the F5 WAF for NGINX signing key:
@@ -194,6 +259,27 @@ sudo apt-get update
 sudo apt-get install app-protect
 ```
 
+{{< details summary="Installing a specific version of F5 WAF for NGINX" >}}
+
+If you need to install a specific version of F5 WAF for NGINX, you can use `apt-cache` to list available versions, then append it to the package name:
+
+```shell
+sudo apt-get update
+sudo apt-cache policy app-protect
+sudo apt-get install app-protect=<desired-version>
+```
+
+When installing a specific version of F5 WAF for NGINX, you will also need to manually install its package dependencies.
+
+You can use the following script to get the dependent packages:
+
+```shell
+findDeps () { local pkgs=$(apt show $1 2>/dev/null | grep Depends: | grep -oE "(nginx-plus-module|app-protect)-[a-z]+ *\(= *[0-9\+\.-]+~`lsb_release -cs`\)" | tr -d ' ()'); for p in ${pkgs[@]}; do echo $p; findDeps $p; done; }
+findDeps app-protect=<desired-version>
+```
+
+{{< /details >}}
+
 ## Update configuration files
 
 Once you have installed F5 WAF for NGINX, you must load it as a module in the main context of your NGINX configuration.