diff --git a/content/nim/disconnected/report-usage-disconnected-deployment.md b/content/nim/disconnected/report-usage-disconnected-deployment.md index 69d4d1b54e..4c27d04bd5 100644 --- a/content/nim/disconnected/report-usage-disconnected-deployment.md +++ b/content/nim/disconnected/report-usage-disconnected-deployment.md @@ -30,13 +30,99 @@ To configure NGINX Plus (R33 and later) to report usage data to NGINX Instance M --- -## Submit usage report to F5 {#submit-usage-report} +## Submit usage report to F5 with NGINX Instance Manager 2.22 and later {#submit-usage-report} + +{{< call-out "note" >}}Starting with NGINX Instance Manager 2.22, it's not possible to report usage with the REST API option.{{< /call-out >}} + +{{}} + +{{%tab name="bash script (recommended)"%}} + +To submit the usage report in a disconnected environment, use the provided `offline_usage.sh` script. Run this script on a system that can access NGINX Instance Manager and connect to the `https://product.connect.nginx.com/api/nginx-usage/batch` endpoint on port `443`. Replace each placeholder with your specific values. + +Download the {{}}[offline_usage.sh](/scripts/offline_usage.sh) script and make the script executable: + +```shell + chmod +x /offline_usage.sh +``` + +### Download usage report + +The download feature of the script takes the following arguments: +- ``: The admin username for NGINX Instance Manager authentication. +- ``: The admin password for NGINX Instance Manager authentication. +- ``: The IP address of the NGINX Instance Manager instance. + +And uses the following environment variable: + +| Variable | Description | Default value | +| --- | --- | --- | +| CURL_TIMEOUT | 30 | Connection timeout for curl requests in seconds | + +To download the usage report from NGINX Instance Manager, run the following command: + +```shell +./offline_usage.sh download +``` +1. The script verifies connectivity to the NGINX Instance Manager instance over HTTPS. +1. Checks that the device is in DISCONNECTED mode (exits with an error if mode is CONNECTED). +1. Downloads the usage report as a ZIP file to `/tmp/response.zip`. + +### Upload usage report + +To upload the usage acknowledgment to NGINX One Console, run the following command: + +```shell +./offline_usage.sh upload --result-dir [--endpoint-url ] +``` +Where: + +| Argument | Description | Required | +| --- | --- | --- | +| `` | The path to the usage acknowledgment ZIP file downloaded using the `download` operation. | Yes | +| --result-dir, -r | Directory used to track uploaded files and store unzipped contents. | Yes | +| --endpoint-url, -e | Upload endpoint URL. Default: https://product.connect.nginx.com/api/nginx-usage/batch | No | + +The script provides the following output: + +| File | Description | +| --- | --- | +| `/uploaded_filex.txt` | A text file containing the names of the succesfully uploaded files. | +| `/unzip/` | Extracted contents of the usage report | +| `/upload_usage.log` | Detailed log of all upload attempts (in CWD) | + +And returns one the following exit codes: + +| Code | Description | +| --- | --- | +| 0 | Operation completed successfully | +| 1 | Error — missing arguments, connectivity failure, invalid file, wrong device mode, or upload failure | + +{{%/tab%}} + +{{%tab name="Web interface"%}} + +Download usage report from the `https:///ui/nginx-plus` page. Replace `` with your NGINX Instance Manager's fully qualified domain name. + +Move the file to a machine with internet access, run the bash script with upload option. + +{{< call-out "note" "Behavior change" >}}Starting with NGINX Instance Manager 2.22, it's not necessary to reupload the usage acknowledgement file back to NGINX Instance Manager.{{< /call-out >}} + +{{%/tab%}} + +{{}} + +{{< call-out "note" "File size increase" >}}NGINX Instance Manager 2.22 and later have moved from reporting aggregated usage data to reporting the raw data that data planes send; the file sizes will be larger than before.{{< /call-out >}} + +--- + +## Submit usage report to F5 with NGINX Instance Manager 2.21 and earlier {#submit-usage-report-2.21} {{< call-out "tip" "Using the REST API" "" >}}{{< include "nim/how-to-access-nim-api.md" >}}{{}}
-{{}} +{{}} {{%tab name="bash script (recommended)"%}}