diff --git a/content/includes/waf/dockerfiles/alpine-plus.md b/content/includes/waf/dockerfiles/alpine-plus.md index 07551a6cd..2c9276820 100644 --- a/content/includes/waf/dockerfiles/alpine-plus.md +++ b/content/includes/waf/dockerfiles/alpine-plus.md @@ -27,6 +27,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/apk/cert.pem,mode=0644 \ && ln -sf /dev/stderr /var/log/nginx/error.log \ && rm -rf /var/cache/apk/* +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Expose port EXPOSE 80 diff --git a/content/includes/waf/dockerfiles/amazon-plus.md b/content/includes/waf/dockerfiles/amazon-plus.md index d4ec7bba2..d943b33f1 100644 --- a/content/includes/waf/dockerfiles/amazon-plus.md +++ b/content/includes/waf/dockerfiles/amazon-plus.md @@ -28,6 +28,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Expose port EXPOSE 80 diff --git a/content/includes/waf/dockerfiles/debian-plus.md b/content/includes/waf/dockerfiles/debian-plus.md index 204dfa633..7c8581d11 100644 --- a/content/includes/waf/dockerfiles/debian-plus.md +++ b/content/includes/waf/dockerfiles/debian-plus.md @@ -41,6 +41,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && apt-get clean \ && rm -rf /var/lib/apt/lists/* +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Expose port EXPOSE 80 diff --git a/content/includes/waf/dockerfiles/oracle-plus.md b/content/includes/waf/dockerfiles/oracle-plus.md index 98bd1e15b..c62d33bb1 100644 --- a/content/includes/waf/dockerfiles/oracle-plus.md +++ b/content/includes/waf/dockerfiles/oracle-plus.md @@ -29,6 +29,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Expose port EXPOSE 80 diff --git a/content/includes/waf/dockerfiles/rhel8-plus.md b/content/includes/waf/dockerfiles/rhel8-plus.md index 9f05ce79f..ac00cc4e3 100644 --- a/content/includes/waf/dockerfiles/rhel8-plus.md +++ b/content/includes/waf/dockerfiles/rhel8-plus.md @@ -45,6 +45,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Expose port EXPOSE 80 diff --git a/content/includes/waf/dockerfiles/rhel9-plus.md b/content/includes/waf/dockerfiles/rhel9-plus.md index 464ba150e..6f6c96a53 100644 --- a/content/includes/waf/dockerfiles/rhel9-plus.md +++ b/content/includes/waf/dockerfiles/rhel9-plus.md @@ -30,6 +30,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Expose port EXPOSE 80 diff --git a/content/includes/waf/dockerfiles/rocky9-plus.md b/content/includes/waf/dockerfiles/rocky9-plus.md index 464ba150e..6f6c96a53 100644 --- a/content/includes/waf/dockerfiles/rocky9-plus.md +++ b/content/includes/waf/dockerfiles/rocky9-plus.md @@ -30,6 +30,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Expose port EXPOSE 80 diff --git a/content/includes/waf/dockerfiles/ubuntu-plus.md b/content/includes/waf/dockerfiles/ubuntu-plus.md index 89a2e7d8b..7333f22d5 100644 --- a/content/includes/waf/dockerfiles/ubuntu-plus.md +++ b/content/includes/waf/dockerfiles/ubuntu-plus.md @@ -41,6 +41,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 && apt-get clean \ && rm -rf /var/lib/apt/lists/* +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Expose port EXPOSE 80 diff --git a/content/includes/waf/install-build-image.md b/content/includes/waf/install-build-image.md index 45ccc3068..86a729c98 100644 --- a/content/includes/waf/install-build-image.md +++ b/content/includes/waf/install-build-image.md @@ -7,12 +7,24 @@ Your folder should contain the following files: - _nginx-repo.crt_ - _nginx-repo.key_ +- _license.jwt_ (Only necessary when using NGINX Plus) - _nginx.conf_ - _entrypoint.sh_ - _Dockerfile_ - _custom_log_format.json_ (Optional) -To build an image, use the following command, replacing `` as appropriate: +To build an image for NGINX Plus, use the following command, replacing `` as appropriate: + +```shell +sudo docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key --secret id=license-jwt,src=license.jwt -t . +``` + +A RHEL-based system would use the following command instead: + +```shell +podman build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key --secret id=license-jwt,src=license.jwt -t . +``` +To build an image for NGINX Open Source, use the following command, replacing `` as appropriate: ```shell sudo docker build --no-cache --platform linux/amd64 --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t . diff --git a/content/includes/waf/install-services-registry.md b/content/includes/waf/install-services-registry.md index c9f686e8d..2389912d7 100644 --- a/content/includes/waf/install-services-registry.md +++ b/content/includes/waf/install-services-registry.md @@ -5,6 +5,8 @@ nd-files: - content/waf/install/kubernetes.md --- +Docker registry credentials are needed to access private-registry.nginx.com + Create a directory and copy your certificate and key to this directory: ```shell diff --git a/content/includes/waf/install-update-configuration.md b/content/includes/waf/install-update-configuration.md index 23b1c63ae..3577367cf 100644 --- a/content/includes/waf/install-update-configuration.md +++ b/content/includes/waf/install-update-configuration.md @@ -121,8 +121,3 @@ server { {{% /tab %}} {{< /tabs >}} - -Once you have updated your configuration files, you can reload NGINX to apply the changes. You have two options depending on your environment: - -- `nginx -s reload` -- `sudo systemctl reload nginx` \ No newline at end of file diff --git a/content/waf/install/disconnected-environment.md b/content/waf/install/disconnected-environment.md index 88e1a8bc9..60794d2ee 100644 --- a/content/waf/install/disconnected-environment.md +++ b/content/waf/install/disconnected-environment.md @@ -22,7 +22,7 @@ To complete this guide, you will need the following prerequisites: - [Virtual machine or bare metal]({{< ref "/waf/install/virtual-environment.md#before-you-begin" >}}) - [Docker]({{< ref "/waf/install/docker.md#before-you-begin" >}}) - [Kubernetes]({{< ref "/waf/install/kubernetes.md#before-you-begin" >}}) -- An active F5 WAF for NGINX subscription (Purchased or trial). +- Active F5 NGINX App Protect WAF subscription in [MyF5](https://my.f5.com/manage/s/) (purchased or trial) - A connected environment with similar architecture - A method to transfer files between two environments diff --git a/content/waf/install/docker.md b/content/waf/install/docker.md index bbd372b61..b420dbbda 100644 --- a/content/waf/install/docker.md +++ b/content/waf/install/docker.md @@ -16,8 +16,9 @@ This page describes how to install F5 WAF for NGINX using Docker. To complete this guide, you will need the following prerequisites: -- An active F5 WAF for NGINX subscription (Purchased or trial) -- [Docker](https://docs.docker.com/get-started/get-docker/) +- Active F5 NGINX App Protect WAF subscription in [MyF5](https://my.f5.com/manage/s/) (purchased or trial) +- [Docker](https://docs.docker.com/engine/install/) (with Docker compose) installed and running. +- Docker registry credentials are needed to access private-registry.nginx.com (For Multi-container and Hybrid configuration) You should read the [IP intelligence]({{< ref "/waf/policies/ip-intelligence.md" >}}) and [Secure traffic using mTLS]({{< ref "/waf/configure/secure-mtls.md" >}}) topics for additional set-up configuration if you want to use them immediately. @@ -42,9 +43,13 @@ The single container configuration only supports NGINX Plus and requires a build The steps you should follow on this page are dependent on your configuration type: after the shared steps, links will guide you to the next appropriate section. ## Download your subscription credentials +### Shared Requirements {{< include "licensing-and-reporting/download-certificates-from-myf5.md" >}} +### Additional Requirement for NGINX Plus Users +{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} + ## Configure Docker for the F5 Container Registry {{< include "waf/install-services-registry.md" >}} @@ -143,7 +148,7 @@ http { ### Create a Dockerfile -In the same folder as your credential and configuration files, create a _Dockerfile_ based on your desired operating system image using an example from the following sections. +In the same folder as your credential and configuration files, create a _Dockerfile_ based on your [desired operating system]({{< ref "/waf/fundamentals/technical-specifications.md#supported-operating-systems" >}}) image using an example from the following sections. Alternatively, you may want make your own image based on a Dockerfile using the official NGINX image: @@ -438,7 +443,7 @@ Once you have updated your configuration files, you can reload NGINX to apply th {{< include "waf/install-services-docker.md" >}} #### Download Docker images - +[Access to NGINX repo private-registry.nginx.com]({{< ref "/waf/install/docker.md#Configure Docker for the F5 Container Registry" >}}) is needed to pull the following container images {{< include "waf/install-services-images.md" >}} #### Create and run a Docker Compose file @@ -814,7 +819,7 @@ sudo dnf install app-protect-module-plus {{< include "waf/install-services-docker.md" >}} #### Download Docker images - +[Access to NGINX repo private-registry.nginx.com]({{< ref "/waf/install/docker.md#Configure Docker for the F5 Container Registry" >}}) is needed to pull the following container images {{< include "waf/install-services-images.md" >}} #### Create and run a Docker Compose file @@ -913,7 +918,7 @@ http { Copy or move your subscription files into a new folder. -In the same folder as the subscription files, create a _Dockerfile_ based on your desired operating system image using an example from the following sections. +In the same folder as the subscription files, create a _Dockerfile_ based on your [desired operating system]({{< ref "/waf/fundamentals/technical-specifications.md#supported-operating-systems" >}}) image using an example from the following sections. {{< call-out "note" >}} @@ -949,6 +954,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/apk/cert.pem,mode=0644 \ --mount=type=secret,id=nginx-key,dst=/etc/apk/cert.key,mode=0644 \ apk update && apk add app-protect-ip-intelligence +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -991,6 +1000,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ dnf -y install app-protect-ip-intelligence +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1046,6 +1059,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ apt-get install -y app-protect-ip-intelligence +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1092,6 +1109,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ dnf install -y app-protect-ip-intelligence +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1135,6 +1156,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ dnf install -y app-protect-ip-intelligence +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1181,6 +1206,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Copy configuration files: COPY nginx.conf custom_log_format.json /etc/nginx/ COPY entrypoint.sh /root/ @@ -1219,6 +1248,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ dnf install -y app-protect-ip-intelligence +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1274,6 +1307,10 @@ RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \ apt-get install -y app-protect-ip-intelligence +# Securely copy the JWT license: +RUN --mount=type=secret,id=license-jwt,dst=license.jwt \ + cp license.jwt /etc/nginx/license.jwt + # Forward request logs to Docker log collector: RUN ln -sf /dev/stdout /var/log/nginx/access.log \ && ln -sf /dev/stderr /var/log/nginx/error.log @@ -1293,6 +1330,11 @@ CMD ["sh", "/root/entrypoint.sh"] {{< include "waf/install-update-configuration.md" >}} +Once you have updated your configuration files, you can reload NGINX to apply the changes. You have two options depending on your environment: + +- `nginx -s reload` +- `sudo systemctl reload nginx` + F5 WAF for NGINX should now be operational, and you can move onto [Post-installation checks](#post-installation-checks). ## Post-installation checks @@ -1302,3 +1344,10 @@ F5 WAF for NGINX should now be operational, and you can move onto [Post-installa ## Next steps {{< include "waf/install-next-steps.md" >}} + +## Remove NGINX docker image +Before removing any Docker image, it’s important to ensure that the image is no longer needed and is not in use. + +[docker image rm](https://docs.docker.com/reference/cli/docker/image/rm/) tool + +TODO diff --git a/content/waf/install/kubernetes-plm.md b/content/waf/install/kubernetes-plm.md index 7407e9af8..f8a059a1c 100644 --- a/content/waf/install/kubernetes-plm.md +++ b/content/waf/install/kubernetes-plm.md @@ -36,11 +36,12 @@ These enhancements are only available for Helm-based deployments. To complete this guide, you will need the following prerequisites: -- [A functional Kubernetes cluster]({{< ref "/waf/install/kubernetes.md" >}}) +- [A functional Kubernetes cluster](https://kubernetes.io/docs/setup/) +- [kubectl CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl/) configured and connected to your cluster - [Helm](https://helm.sh/docs/intro/install/) -- [Docker](https://docs.docker.com/get-started/get-docker/) -- An active F5 WAF for NGINX subscription (Purchased or trial) -- Credentials to the [MyF5 Customer Portal](https://account.f5.com/myf5), provided by email from F5, Inc. +- [Docker](https://docs.docker.com/engine/install/) (with Docker compose) installed and running. +- Docker registry credentials are needed to access private-registry.nginx.com +- Active F5 NGINX App Protect WAF subscription in [MyF5](https://my.f5.com/manage/s/) (purchased or trial) ## Download your subscription credentials diff --git a/content/waf/install/kubernetes.md b/content/waf/install/kubernetes.md index fa484c842..555944053 100644 --- a/content/waf/install/kubernetes.md +++ b/content/waf/install/kubernetes.md @@ -18,9 +18,11 @@ It explains the common steps necessary for any Kubernetes-based deployment, then To complete this guide, you will need the following pre-requisites: -- A functional Kubernetes cluster -- An active F5 WAF for NGINX subscription (Purchased or trial) -- [Docker](https://docs.docker.com/get-started/get-docker/) +- [A functional Kubernetes cluster](https://kubernetes.io/docs/setup/) +- [kubectl CLI](https://kubernetes.io/docs/tasks/tools/install-kubectl/) configured and connected to your cluster +- Active F5 NGINX App Protect WAF subscription in [MyF5](https://my.f5.com/manage/s/) (purchased or trial) +- [Docker](https://docs.docker.com/engine/install/) (with Docker compose) installed and running. +- Docker registry credentials are needed to access private-registry.nginx.com You will need [Helm](https://helm.sh/docs/intro/install/) installed for a Helm-based deployment. @@ -34,9 +36,15 @@ To review supported operating systems, read the [Technical specifications]({{< r {{< include "licensing-and-reporting/download-certificates-from-myf5.md" >}} +### Download your JSON web token + +To use NGINX Plus, you will need to download the the JWT license file associated with your NGINX Plus subscription from the MyF5 Customer Portal: + +{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} + ## Create a Dockerfile -In the same folder as your credential files, create a _Dockerfile_ based on your desired operating system image using an example from the following sections. +In the same folder as your credential files, create a _Dockerfile_ based on your [desired operating system]({{< ref "/waf/fundamentals/technical-specifications.md#supported-operating-systems" >}}) image using an example from the following sections. Alternatively, you may want make your own image based on a Dockerfile using the official NGINX image: @@ -204,9 +212,20 @@ Your folder should contain the following files: - _nginx-repo.crt_ - _nginx-repo.key_ +- _license.jwt_ (Only necessary when using NGINX Plus) - _Dockerfile_ -To build an image, use the following command, replacing `` as appropriate: +To build an image for NGINX Pluse, use the following command, replacing `` as appropriate: + +```shell +sudo docker build --no-cache --platform linux/amd64 \ + --secret id=nginx-crt,src=nginx-repo.crt \ + --secret id=nginx-key,src=nginx-repo.key \ + --secret id=license-jwt,src=license.jwt \ + -t . +``` + +To build an image for NGINX Open Source, use the following command, replacing `` as appropriate: ```shell sudo docker build --no-cache --platform linux/amd64 \ @@ -224,10 +243,6 @@ From this point, the steps change based on your installation method: ## Use Helm to install F5 WAF for NGINX -### Download your JSON web token - -{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}} - ### Get the Helm chart To get the Helm chart, first configure Docker for the F5 Container Registry. diff --git a/content/waf/install/virtual-environment.md b/content/waf/install/virtual-environment.md index 4b01e1634..3488841c6 100644 --- a/content/waf/install/virtual-environment.md +++ b/content/waf/install/virtual-environment.md @@ -23,13 +23,11 @@ This page describes how to install F5 WAF for NGINX in a virtual machine or bare To complete this guide, you will need the following prerequisites: - A [supported operating system]({{< ref "/waf/fundamentals/technical-specifications.md#supported-operating-systems" >}}). -- A working [NGINX Open Source]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-open-source.md" >}}) or [NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}) instance. -- An active F5 WAF for NGINX subscription (Purchased or trial). +- Active F5 NGINX App Protect WAF subscription in [MyF5](https://my.f5.com/manage/s/) (purchased or trial) +- A working [NGINX Plus]({{< ref "/nginx/admin-guide/installing-nginx/installing-nginx-plus.md" >}}) optional if not yet installed (NGINX will be installed automatically during App Protect installation) Depending on your deployment type, you may have additional requirements: -- [Docker](https://docs.docker.com/get-started/get-docker/) is required for NGINX Open Source or NGINX Plus type deployments. - You should read the [IP intelligence]({{< ref "/waf/policies/ip-intelligence.md" >}}) and [Secure traffic using mTLS]({{< ref "/waf/configure/secure-mtls.md" >}}) topics for additional set-up configuration if you want to use them immediately. {{< include "waf/install-selinux-warning.md" >}}