Automatically update the WAF compiler

After you manually install at least one version of the F5 WAF for NGINX compiler, F5 NGINX Instance Manager can automatically download and install newer versions as needed.

Automatic updates occur when:

• A managed instance is upgraded to a newer version of F5 WAF for NGINX.
• You add a new instance running a different version of F5 WAF for NGINX.

To enable this feature, upload your F5 WAF for NGINX certificate and key to NGINX Instance Manager. This lets NGINX Instance Manager securely connect to the NGINX package repository and download the required compiler files.

You only need to upload the certificate and key once.

Upload the F5 WAF for NGINX certificate and key

Follow these steps to get and upload the certificate and key:

1. Log in to MyF5.

2. Go to My Products and Plans > Subscriptions.

3. Download these files from your F5 WAF for NGINX subscription:

   • nginx-repo.crt (certificate)
   • nginx-repo.key (private key)

4. Create a JSON file that contains both files. Replace each newline (\n) in the certificate and key with a literal \n so the formatting is correct inside the JSON file.

   Example request:

   Copy

   {
     "name": "nginx-repo",
     "nginxResourceType": "NginxRepo",
     "certPEMDetails": {
       "caCerts": [],
       "password": "",
       "privateKey": "-----BEGIN PRIVATE KEY-----\n[content snipped]\n-----END PRIVATE KEY-----\n",
       "publicCert": "-----BEGIN CERTIFICATE-----\n[content snipped]\n-----END CERTIFICATE-----",
       "type": "PEM"
     }
   }

5. Upload the file to NGINX Instance Manager using the REST API:

   Copy

   curl -X POST 'https://<NIM_FQDN>/api/platform/v1/certs'    --header "Authorization: Bearer <access token>"    --header "Content-Type: application/json"    -d @nginx-repo-certs.json

6. If successful, you’ll see a response similar to this:

   Example response:

   Copy

   {
     "certAssignmentDetails": [],
     "certMetadata": [
       {
         "authorityKeyIdentifier": "<fingerprint>",
         "commonName": "<subscription name>",
         "expired": false,
         "expiry": 59789838,
         "issuer": "C=US, ST=Washington, L=Seattle, Inc., O=F5 Networks\\, OU=Certificate Authority, CN=F5 PRD Issuing Certificate Authority TEEM V1",
         "publicKeyType": "RSA (2048 bit)",
         "serialNumber": "<serial number>",
         "signatureAlgorithm": "SHA256-RSA",
         "subject": "CN=<subscription name>",
         "subjectAlternativeName": "",
         "subjectKeyIdentifier": "<fingerprint>",
         "thumbprint": "<thumbprint>",
         "thumbprintAlgorithm": "SHA256-RSA",
         "validFrom": "2021-12-21T16:57:55Z",
         "validTo": "2024-12-20T00:00:00Z",
         "version": 3
       }
     ],
     "certPEMDetails": {
       "caCerts": [],
       "password": "**********",
       "privateKey": "**********",
       "publicCert": "[content snipped]",
       "type": "PEM"
     },
     "created": "2023-01-27T23:42:41.587760092Z",
     "modified": "2023-01-27T23:42:41.587760092Z",
     "name": "nginx-repo",
     "serialNumber": "<serial number>",
     "uid": "d08d9f54-58dd-447a-a71d-6fa5aa0d880c",
     "validFrom": "2021-12-21T16:57:55Z",
     "validTo": "2024-12-20T00:00:00Z"
   }

Troubleshooting automatic updates

If NGINX Instance Manager can’t connect to the repository, or the certificate is missing or invalid, you’ll see an error like:

missing the specific compiler, please install it and try again.

This means the certificate or key might be missing, invalid, or expired, or that NGINX Instance Manager can’t reach the NGINX repository.

Check for related errors in the log file:

/var/log/nms/nms.log

If you see a message like this, the certificate or key is likely invalid or expired:

error when creating the nginx repo retriever - NGINX repo certificates not found

Known Issue for auto-downloaded nms-nap-compiler-v5.690.0

If you see following error messages in UI:

Copy

<instance_name>: failed building config payload: policy compilation failed for deployment <deployment_id> due to integrations service error: compiler controller error: exit status 1

AND

If you see any of the following error message in nms log

debian/ubuntu based system:

Copy

/usr/bin/perl: symbol lookup error: /opt/nms-nap-compiler/app_protect-5.690.0/bin/../lib/perl/auto/F5/PatternMatching/PatternMatching.so: undefined symbol: _ZN3re23RE2C1ESt17basic_string_viewIcSt11char_traitsIcEERKNS0_7OptionsE

OR

RHEL based system:

Copy

Can't load '/opt/nms-nap-compiler/app_protect-5.690.0/bin/../lib/perl/auto/F5/PatternMatching/PatternMatching.so' for module F5::PatternMatching: libre2.so.11: cannot open shared object file: No such file or directory at /usr/lib64/perl5/DynaLoader.pm

Workaround: Execute below command

Copy

sudo bash -c '
cd /opt/nms-nap-compiler/app_protect-5.690.0/lib && \
ln -sfn libre2.so.11.0.0 libre2.so.11 && \
ln -sfn libprotobuf.so.3.21.12.0 libprotobuf.so.32 && \
ln -sfn libprotobuf.so.32 libprotobuf.so
'

If needed, you can install the WAF compiler manually.