Skip to content

docs: update tarball extension from .tgz to tar.gz in markdown files #480

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions content/nim/admin-guide/maintenance/backup-and-recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ To back up configuration files, secrets, and databases:
sudo ./backup.sh
```

The backup will be saved as a tarball, similar to this example: `/tmp/nms-backup-<DATETIME>.tgz`.
The backup will be saved as a tarball, similar to this example: `/tmp/nms-backup-<DATETIME>.tar.gz`.

To restore NGINX Instance Manager:

Expand All @@ -70,7 +70,7 @@ To restore NGINX Instance Manager:

```shell
cd /etc/nms/scripts
sudo ./restore.sh /tmp/nms-backup-<DATETIME>.tgz
sudo ./restore.sh /tmp/nms-backup-<DATETIME>.tar.gz
```

---
Expand Down Expand Up @@ -122,7 +122,7 @@ To complete the steps in this guide, ensure the following:
helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
helm pull nginx-stable/nms
tar zxvf nms-<version>.tgz
tar zxvf nms-<version>.tar.gz
```

### Back up NGINX Instance Manager
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ Once you've set up your Docker containers, use the following command to back the
```shell
~$ docker exec nim-nim-1 nim-backup
...
Backup has been successfully created: /data/backup/nim-backup-<date>.tgz
Backup has been successfully created: /data/backup/nim-backup-<date>.tar.gz
```

If your system uses named volumes, inspect the `Mountpoint`. Alternatively, if you're using a shared NFS volume, then collect the data directly from the mount point.
Expand All @@ -149,7 +149,7 @@ If your system uses named volumes, inspect the `Mountpoint`. Alternatively, if y
~/compose$ docker inspect volume nim_nim-data | jq '.[0].Mountpoint'
"/var/lib/docker/volumes/nim_nim-data/_data"
ubuntu@ip-<address>:~/compose$ sudo ls -l /var/lib/docker/volumes/nim_nim-data/_data/backup
-rw-r--r-- 1 root root 5786953 Sep 27 02:03 nim-backup-<date>.tgz
-rw-r--r-- 1 root root 5786953 Sep 27 02:03 nim-backup-<date>.tar.gz
```

---
Expand All @@ -164,7 +164,7 @@ Before you can restore a backup, set your containers to maintenance mode in the
```

```shell
~$ docker exec nim-nim-1 nim-restore /data/backup/nim-backup-<date>.tgz
~$ docker exec nim-nim-1 nim-restore /data/backup/nim-backup-<date>.tar.gz
...
NGINX Instance Manager has been restored.
```
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -487,13 +487,13 @@ curl -X GET https://{{NIM_FQDN}}/api/platform/v1/security/policies/<policy-uid>/
-H "Authorization: Bearer <access token>"
```

The response includes a content field that contains the bundle in base64 format. To use it, you’ll need to decode the content and save it as a `.tgz` file.
The response includes a content field that contains the bundle in base64 format. To use it, you’ll need to decode the content and save it as a `.tar.gz` file.

Example:

```bash
curl -X GET "https://{{NIM_FQDN}}/api/platform/v1/security/policies/<policy-uid>/bundles/<bundle-uid>" \
-H "Authorization: Bearer <access token>" | jq -r '.content' | base64 -d > security-policy-bundle.tgz
-H "Authorization: Bearer <access token>" | jq -r '.content' | base64 -d > security-policy-bundle.tar.gz
```

<details open>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The **Security Monitoring** module shows real-time data from NGINX App Protect W

### Security bundle compilation {#security-bundle}

NGINX Instance Manager includes a compiler that packages your complete WAF configuration — security policies, attack signatures, threat campaigns, and log profiles — into a single `.tgz` file. It then pushes this bundle to the selected NGINX App Protect WAF instances.
NGINX Instance Manager includes a compiler that packages your complete WAF configuration — security policies, attack signatures, threat campaigns, and log profiles — into a single `.tar.gz` file. It then pushes this bundle to the selected NGINX App Protect WAF instances.

**Why precompile with NGINX Instance Manager?**

Expand All @@ -46,7 +46,7 @@ Example [`location`](https://nginx.org/en/docs/http/ngx_http_core_module.html#lo
```nginx
location / {
app_protect_enable on;
app_protect_policy_file /etc/app_protect/policies/policy_bundle.tgz;
app_protect_policy_file /etc/app_protect/policies/policy_bundle.tar.gz;
}
```

Expand All @@ -55,7 +55,7 @@ location / {
You can also configure NGINX Instance Manager to compile log profiles when you install a new version of the compiler. When publishing NGINX configs that include the [`app_protect_security_log`](https://docs.nginx.com/nginx-app-protect/logging-overview/security-log/#app_protect_security_log) directive, NGINX Instance Manager pushes the compiled log profile to your WAF instances (when precompiled publication is turned on).

{{<important>}}
NGINX Instance Manager and Security Monitoring both use log profiles, but their configurations are different. If you're using configuration management in NGINX Instance Manager, you must reference the log profile with the `.tgz` file extension, not `.json`.
NGINX Instance Manager and Security Monitoring both use log profiles, but their configurations are different. If you're using configuration management in NGINX Instance Manager, you must reference the log profile with the `.tar.gz` file extension, not `.json`.
{{</important>}}

## Security management APIs
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -213,20 +213,20 @@ Take the steps below to update your NGINX App Protect WAF configurations by usin
```nginx
app_protect_enable on;
app_protect_enable on;
app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz";
app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tar.gz";
app_protect_security_log_enable on;
app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514;
app_protect_security_log "/etc/nms/secops_dashboard.tar.gz" syslog:server=127.0.0.1:514;
```

- Add the `app_protect_policy_file` directive with a reference to a security policy.

The policy reference must use the `.tgz` file extension when using Instance Manager to perform precompiled publication of NGINX App Protect WAF policies and log profiles. The file path referenced must exist on the NGINX Instance Manager host, but it's ok if the policy file doesn't exist yet. If your Instance is not configured for precompiled publication, then use the `.json` file extension for polcies and log profiles. In this case, the file path referenced in the NGINX configuration must reside on the Instance.
The policy reference must use the `.tar.gz` file extension when using Instance Manager to perform precompiled publication of NGINX App Protect WAF policies and log profiles. The file path referenced must exist on the NGINX Instance Manager host, but it's ok if the policy file doesn't exist yet. If your Instance is not configured for precompiled publication, then use the `.json` file extension for polcies and log profiles. In this case, the file path referenced in the NGINX configuration must reside on the Instance.

If you are using custom security policies, at this stage, it's fine to use the default security policy shown in the example above. After completing the steps in this guide, refer to the instructions in [Set Up App Protect WAF Configuration Management]({{< ref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to add your custom security policy files to NGINX Instance Manager and update your NGINX configuration.

- Add the `app_protect_security_log_enable on` and the `app_protect_security_log` directive to any NGINX context where NGINX App Protect WAF is enabled and you want to be able to review attack data.

The logging configuration must reference `"/etc/nms/secops_dashboard.tgz"`, as shown in the example.
The logging configuration must reference `"/etc/nms/secops_dashboard.tar.gz"`, as shown in the example.

If the `app_protect_security_log_enable` setting is already present, just add the `app_protect_security_log` beneath it in the same context.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -30,11 +30,11 @@ F5 NGINX App Protect supports logging to multiple destinations. This allows user
2. **For an instance with Security Monitoring and NGINX Instance Manager:**

```nginx
app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz";
app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tar.gz";
app_protect_security_log_enable on;
app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514;
app_protect_security_log "/etc/nms/secops_dashboard.tgz" <Path to store log file>;
# Example: app_protect_security_log "/etc/nms/secops_dashboard.tgz" /var/log/app_protect/security.log;
app_protect_security_log "/etc/nms/secops_dashboard.tar.gz" syslog:server=127.0.0.1:514;
app_protect_security_log "/etc/nms/secops_dashboard.tar.gz" <Path to store log file>;
# Example: app_protect_security_log "/etc/nms/secops_dashboard.tar.gz" /var/log/app_protect/security.log;
```

---
Expand Down
42 changes: 21 additions & 21 deletions content/nim/nginx-app-protect/setup-waf-config-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -430,29 +430,29 @@ If you prefer not to enable automatic updates, you can manually update the Attac
- For Threat Campaigns: package starts with `app-protect-threat-campaigns`

4. Extract the following three files from the package:
- `signatures.bin.tgz` (or `threat_campaigns.bin.tgz`)
- `signatures.bin.tar.gz` (or `threat_campaigns.bin.tar.gz`)
- `signature_update.yaml` (or `threat_campaign_update.yaml`)
- `version`

Use tools like `rpm2cpio | cpio` or `ar` (for `.deb`) to extract the files.

5. Create a `.tgz` bundle that includes the three files. For example:
5. Create a `.tar.gz` bundle that includes the three files. For example:

```shell
tar -czvf attack-signatures.tgz signatures.bin.tgz signature_update.yaml version
tar -czvf attack-signatures.tar.gz signatures.bin.tar.gz signature_update.yaml version
```

#### Upload packages to NGINX Instance Manager

Use the NGINX Instance Manager REST API to upload the `.tgz` files.
Use the NGINX Instance Manager REST API to upload the `.tar.gz` files.

**Upload Attack Signatures:**

```shell
curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/attack-signatures' \
--header "Authorization: Bearer <access token>" \
--form 'revisionTimestamp="2022.11.16"' \
--form 'filename=@"/attack-signatures.tgz"'
--form 'filename=@"/attack-signatures.tar.gz"'
```

**Upload Threat Campaigns:**
Expand All @@ -461,10 +461,10 @@ curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/attack-signatures' \
curl -X POST 'https://{{NIM_FQDN}}/api/platform/v1/security/threat-campaigns' \
--header "Authorization: Bearer <access token>" \
--form 'revisionTimestamp="2022.11.15"' \
--form 'filename=@"/threat-campaigns.tgz"'
--form 'filename=@"/threat-campaigns.tar.gz"'
```

{{<important>}}The bundle you upload must match the OS of your NGINX Instance Manager host. For example, if the host is running Ubuntu 20.04, create the `.tgz` from the Ubuntu 20.04 package.{{</important>}}
{{<important>}}The bundle you upload must match the OS of your NGINX Instance Manager host. For example, if the host is running Ubuntu 20.04, create the `.tar.gz` from the Ubuntu 20.04 package.{{</important>}}

### Update the Security Monitoring signature database

Expand Down Expand Up @@ -798,10 +798,10 @@ You can use these default policies as-is or customize them for your app. Securit

Keep the following in mind when configuring NGINX App Protect WAF through NGINX Instance Manager:

- Instance Manager compiles JSON security policies into `.tgz` bundles.
- Instance Manager compiles JSON security policies into `.tar.gz` bundles.
- Use the `app_protect_policy_file` directive to reference custom policies.

If you're using precompiled publication with NGINX Agent, make sure to change the file extension from `.json` to `.tgz`. The filename remains the same. NGINX Instance Manager doesn't support referencing both `.json` and `.tgz` in the same NGINX configuration.
If you're using precompiled publication with NGINX Agent, make sure to change the file extension from `.json` to `.tar.gz`. The filename remains the same. NGINX Instance Manager doesn't support referencing both `.json` and `.tar.gz` in the same NGINX configuration.

- If you're using custom policies, make sure NGINX Agent has permission to access the directories where those policy files are stored. Update the `config_dirs` setting in the NGINX Agent's configuration file if needed.
- NGINX Instance Manager uses the default log profiles that come with NGINX App Protect WAF. You can reference them with the `app_protect_security_log` directive. Custom log profiles aren't supported.
Expand All @@ -821,13 +821,13 @@ server {
app_protect_enable on;

# Reference a custom security policy bundle
app_protect_policy_file /etc/nms/ignore-xss.tgz;
app_protect_policy_file /etc/nms/ignore-xss.tar.gz;

# Enable security logging
app_protect_security_log_enable on;

# Reference the log profile bundle
app_protect_security_log /etc/nms/log-default.tgz /var/log/nginx/security-violations.log;
app_protect_security_log /etc/nms/log-default.tar.gz /var/log/nginx/security-violations.log;

...
}
Expand All @@ -837,7 +837,7 @@ server {
If you’re using NGINX Instance Manager with Security Monitoring, your configuration may already include the following directive:

```nginx
app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514;
app_protect_security_log "/etc/nms/secops_dashboard.tar.gz" syslog:server=127.0.0.1:514;
```

**Don’t change this value.** See the [Security Monitoring setup guide]({{< ref "/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md" >}}) for more details.
Expand All @@ -860,7 +860,7 @@ If you’re using NGINX App Protect WAF v5:
1. {{< include "nim/webui-nim-login.md" >}}
2. In the left menu, select **Instances** or **Instance Groups**.
3. From the **Actions** menu (**...**), select **Edit Config** for the instance or group.
4. If you’re using precompiled publication, change any `.json` file extensions to `.tgz`.
4. If you’re using precompiled publication, change any `.json` file extensions to `.tar.gz`.
5. If you want to apply a default policy, select **Apply Security**, then copy the policy snippet and paste it into your configuration.
6. Add the directives inside an `http`, `server`, or `location` block.
7. Select **Publish** to push the configuration.
Expand Down Expand Up @@ -899,17 +899,17 @@ You can use the NGINX Instance Manager REST API to deploy your NGINX App Protect
app_protect_enable on;
```

- If precompiled publication is enabled, change any `.json` policy references to `.tgz`.
- If precompiled publication is enabled, change any `.json` policy references to `.tar.gz`.
- If you want to apply a default policy, you can use:

```nginx
app_protect_policy_file /etc/nms/NginxDefaultPolicy.tgz;
app_protect_policy_file /etc/nms/NginxDefaultPolicy.tar.gz;
```

or

```nginx
app_protect_policy_file /etc/nms/NginxStrictPolicy.tgz;
app_protect_policy_file /etc/nms/NginxStrictPolicy.tar.gz;
```

- Add the directives to an `http`, `server`, or `location` context.
Expand Down Expand Up @@ -1014,11 +1014,11 @@ USAGE:
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile <options>

Examples:
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -p /path/to/policy.json -o mypolicy.tgz
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -p policyA.json -g myglobal.json -o /path/to/policyA_bundle.tgz
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -g myglobalsettings.json --global-state-outfile /path/to/myglobalstate.tgz
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -b /path/to/policy_bundle.tgz --dump
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -l logprofA.json -o /path/to/logprofA_bundle.tgz
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -p /path/to/policy.json -o mypolicy.tar.gz
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -p policyA.json -g myglobal.json -o /path/to/policyA_bundle.tar.gz
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -g myglobalsettings.json --global-state-outfile /path/to/myglobalstate.tar.gz
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -b /path/to/policy_bundle.tar.gz --dump
/opt/nms-nap-compiler/app_protect-5.342.0/bin/apcompile -l logprofA.json -o /path/to/logprofA_bundle.tar.gz
```

### Confirm NGINX Agent configuration on the NGINX App Protect WAF instance
Expand Down
4 changes: 2 additions & 2 deletions content/nim/releases/known-issues.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ If there is an NGINX configuration error when pushing a template configuration,

---

### {{% icon-resolved %}} .tgz files are not accepted in templates {#45301}
### {{% icon-resolved %}} .tar.gz files are not accepted in templates {#45301}

{{<bootstrap-table "table table-striped table-bordered">}}
| Issue ID | Status |
Expand Down Expand Up @@ -390,7 +390,7 @@ In Instance Manager 2.13, a new configuration is published before the compile st
The initial failure message looks like this:

```text
Config push failed - err: failure from multiple instances. Affected placements: instance/70328a2c-699d-3a90-8548-b8fcec15dabd (instance-group: ig1) - err: failed building config payload: config: aux payload /etc/nms/NginxDefaultPolicy.tgz for instance:70328a2c-699d-3a90-8548-b8fcec15dabd not ready aux payload not ready, instance/2e637e08-64b3-36f9-8f47-b64517805e98 (instance-group: ig1) - err: failed building config payload: config: aux payload /etc/nms/NginxDefaultPolicy.tgz for instance:2e637e08-64b3-36f9-8f47-b64517805e98 not ready aux payload not ready
Config push failed - err: failure from multiple instances. Affected placements: instance/70328a2c-699d-3a90-8548-b8fcec15dabd (instance-group: ig1) - err: failed building config payload: config: aux payload /etc/nms/NginxDefaultPolicy.tar.gz for instance:70328a2c-699d-3a90-8548-b8fcec15dabd not ready aux payload not ready, instance/2e637e08-64b3-36f9-8f47-b64517805e98 (instance-group: ig1) - err: failed building config payload: config: aux payload /etc/nms/NginxDefaultPolicy.tar.gz for instance:2e637e08-64b3-36f9-8f47-b64517805e98 not ready aux payload not ready
```

#### Workaround
Expand Down
2 changes: 1 addition & 1 deletion content/nim/releases/release-notes.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ This release has the following changes in default behavior:
This release fixes the following issues. Check the [Known Issues]({{< ref "/nim/releases/known-issues.md" >}}) topic for more information on the latest resolved issues. Use your browser's search function to find the issue ID in the page.

- {{% icon-resolved %}} Error messages persist after fix (45024)
- {{% icon-resolved %}} .tgz files are not accepted in templates (45301)
- {{% icon-resolved %}} .tar.gz files are not accepted in templates (45301)
- {{% icon-resolved %}} The web interface can't display more than 100 certificates (45565)
- {{% icon-resolved %}} NGINX configuration error messages overlap outside the error window (45570)
- {{% icon-resolved %}} Syntax errors while saving template configuration (45573)
Expand Down
2 changes: 1 addition & 1 deletion content/nim/support/k8s-support-package.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ The F5 NGINX Instance Manager Helm chart includes the `k8s-support-package.sh` s
helm repo add nginx-stable https://helm.nginx.com/stable
helm repo update
helm pull nginx-stable/nms
tar zxvf nms-<version>.tgz
tar zxvf nms-<version>.tar.gz
```

2. Run the Kubernetes support package script. For available options, refer to the [arguments](#arguments) section:
Expand Down
Loading