Merge branch 'main' into unit-docs

Author: ADubhlaoich

.github/pull_request_template.md

@@ -21,16 +21,16 @@ Closes #ISSUE
 
 Before merging a pull request, run through this checklist and mark each as complete.
 
-- [ ] I have read the [contributing guidelines](/CONTRIBUTING.md)
+- [ ] I have read the [contributing guidelines](https://github.com/nginx/documentation/blob/main/CONTRIBUTING.md)
 - [ ] I have signed the [F5 Contributor License Agreement (CLA)](https://github.com/f5/.github/blob/main/CLA/cla-markdown.md)
-- [ ] I have ensured that documentation content adheres to [the style guide](/templates/style-guide.md)
+- [ ] I have ensured that documentation content adheres to [the style guide](https://github.com/nginx/documentation/blob/main/templates/style-guide.md)
 - [ ] If the change involves potentially sensitive changes, I have assessed the possible impact
 - [ ] If applicable, I have added tests that prove my fix is effective or that my feature works
 - [ ] If applicable, I have checked that any relevant tests pass after adding my changes
-- [ ] I have updated any relevant documentation ([`README.md`](/README.md) and [`CHANGELOG.md`](/CHANGELOG.md))
+- [ ] I have updated any relevant documentation ([`README.md`](https://github.com/nginx/documentation/blob/main/README.md) and [`CHANGELOG.md`](https://github.com/nginx/documentation/blob/main/CHANGELOG.md)
 - [ ] I have rebased my branch onto main
 - [ ] I will ensure my PR is targeting the main branch and pulling from my branch from my own fork
 
 Potentially sensitive changes include anything involving code, personally identify information (PII), live URLs or significant amounts of new or revised documentation.
 
-Please refer to [our style guide](/templates/style-guide.md) for guidance about placeholder content.
+Please refer to [our style guide](https://github.com/nginx/documentation/blob/main/templates/style-guide.md) for guidance about placeholder content.

.github/workflows/build-push.yml

@@ -59,7 +59,7 @@ jobs:
     uses: nginxinc/docs-actions/.github/workflows/docs-build-push.yml@9c59fab05a8131f4d691ba6ea2b6a119f3ef832a # v1.0.7
     with:
       production_url_path: ""
-      preview_url_path: "/previews/docs"
+      preview_url_path: "${{ vars.PREVIEW_URL_PATH }}"
       docs_source_path: "public"
       docs_build_path: "./"
       doc_type: "hugo"

.github/workflows/linkchecker.yml

@@ -72,7 +72,7 @@ jobs:
         uses: azure/login@a65d910e8af852a8061c627c456678983e180302 # v2.2.0
         with:
           creds: ${{secrets.AZURE_CREDENTIALS_DOCS}}
- 
+
       - name: Retrieve secrets from Keyvault
         if: env.isProduction != 'true'
         id: keyvault

archetypes/concept.md

@@ -35,7 +35,7 @@ It is an example of a <other concept>, and is closely related to <third concept>
 
 ## Use cases
 
-[//]: # "Name the individual use case sections after the actual use case itself, e.g "Route traffic between applications"
+[//]: # "Name the individual use case sections after the actual use case itself, e.g 'Route traffic between applications'"
 
 ### Use case 1
 

config/_default/config.toml

@@ -16,7 +16,9 @@ enableGitInfo = true
   ngf = '/nginx-gateway-fabric/:sections[1:]/:filename'
   nim = '/nginx-instance-manager/:sections[1:]/:filename'
   nms = '/nginx-management-suite/:sections[1:]/:filename'
+  unit = '/nginx-unit/:sections[1:]/:filename'
   agent = '/nginx-agent/:sections[1:]/:filename'
+  nginxaas = '/nginxaas/azure/:sections[1:]/:filename'
 
 [caches]
   [caches.modules]

content/includes/nginxaas-azure/logging-analysis-azure-storage.md

@@ -0,0 +1,48 @@
+---
+docs: "DOCS-000"
+---
+
+If the diagnostic setting destination details included a storage account, logs show up in the storage container "insights-logs-nginxlogs" with the following format: `resourceID=/<NGINXaaS-resourceID>/y=<YYYY>/m=<MM>/d=<DD>/h=<HH>/PT1H.json`
+
+{{<bootstrap-table "table table-striped table-bordered">}}
+| **Attribute**               | **Description** |
+|-----------------------------|-----------------|
+| `<NGINXaaS-resourceID>`     | The resourceID of the NGINXaaS deployment in upper case.|
+| `<YYYY>`                    | The four-digit year when the log batch was generated.|
+| `<MM>`                      | The two-digit month when the log batch was generated.|
+| `<DD>`                      | The two-digit day when the log batch was generated.|
+| `<HH>`                      | The two-digit hour value that indicates the starting hour for the log batch, in 24 hour UTC format|
+{{</bootstrap-table>}}
+
+{{<note>}}It can take up to 90 minutes after adding diagnostic settings for logs to appear in the provided Azure Storage container.{{</note>}}
+
+Each log event in the "PT1H.json" file is written in a new line delimited JSON text format. The properties that show up in each log line are described in the [Top Level Common Schema](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/resource-logs-schema#top-level-common-schema) documentation.
+
+For instance, an access log event logging to a particular file path will have attributes similar to this example:
+
+```yaml
+{
+	"category": "NginxLogs",
+	"location": "westcentralus",
+	"operationName": "NGINX.NGINXPLUS/NGINXDEPLOYMENTS/LOG",
+	"properties": {
+		"message": "172.92.129.50 - \"-\" [18/Jan/2024:17:59:00 +0000] \"GET / HTTP/1.1\" 200 11232 \"-\" \"curl/8.4.0\" \"-\" \"20.69.58.179\" sn=\"localhost\" rt=0.000 ua=\"-\" us=\"-\" ut=\"-\" ul=\"-\" cs=\"-\" ",
+		"filePath": "/var/log/nginx/access.log"
+	},
+	"resourceId": "/SUBSCRIPTIONS/FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF/RESOURCEGROUPS/RESOURCEGROUP1/PROVIDERS/NGINX.NGINXPLUS/NGINXDEPLOYMENTS/TEST1",
+	"time": "2024-01-18T17:59:00.363956795Z"
+}
+```
+
+If [syslog-based](#logging-to-syslog) logs are used, the log event entry has different **properties** sub-fields:
+
+```yaml
+#...
+"properties": {
+		"message": "172.92.129.50 - - [16/Jan/2024:18:00:00 +0000] \"GET / HTTP/1.1\" 200 11232 \"-\" \"curl/8.4.0\"",
+		"tag": "nginx",
+		"severity": "info",
+		"facility": "local7"
+	},
+#...
+```

content/includes/nginxaas-azure/logging-analysis-logs-analytics.md

@@ -0,0 +1,30 @@
+---
+docs: "DOCS-000"
+---
+
+If the diagnostic setting destination details included a Logs Analytics workspace, logs show up in the table "NGXOperationLogs" with the following non-standard attributes:
+
+{{<bootstrap-table "table table-striped table-bordered">}}
+| **Attribute**               | **Description** |
+|-----------------------------|-----------------|
+| **Location**                  | The location of the NGINXaaS resource.|
+| **Message**                 | The generated NGINX log line. |
+| **FilePath**                 | The path to which NGINX logs were configured to be logged to if the nginx config used file-based logs. |
+| **Tag**                 | The tag with which NGINX logs were generated if syslog-based log configuration is used. By default this is nginx |
+| **Facility**                 | The syslog facility with which NGINX logs were generated if syslog-based log configuration is used. |
+| **Severity**                | The syslog severity with which NGINX logs were generated if syslog-based log configuration is used. |
+
+{{</bootstrap-table>}}
+
+Using a [KQL](https://learn.microsoft.com/en-us/azure/data-explorer/kusto/query/), a custom query can be run to view the logs:
+
+```
+NGXOperationLogs
+| where Location contains "eastus"
+```
+
+For more information on the standard attributes that appear in Logs Analytics,see the [Standard columns in Azure Monitor Logs](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/log-standard-columns) documentation.
+
+For more information on using [KQL](https://learn.microsoft.com/en-us/azure/data-explorer/kusto/query/) see [Queries in Log Analytics](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/queries?tabs=groupby).
+
+{{<note>}}It can take up to 90 minutes after adding diagnostic settings for logs to appear in the provided Logs Analytics Workspace.{{</note>}}

content/includes/nginxaas-azure/logging-config-access-logs.md

@@ -0,0 +1,39 @@
+---
+docs: "DOCS-000"
+---
+
+NGINX access logs are disabled by default. You can enable access logs by adding **access_log** directives to your NGINX configuration to specify the location of the logs and formats. The log path should always be configured to be inside **/var/log/nginx**.
+
+```nginx
+http {
+	log_format myfmt '$remote_addr - $remote_user [$time_local] '
+						   '"$request" $status $body_bytes_sent '
+						   '"$http_referer" "$http_user_agent" "$gzip_ratio"';
+
+	access_log /var/log/nginx/nginx-access.log myfmt;
+	# ...
+}
+```
+
+{{<note>}} The **$time_local** variable includes the date and time for each log. It helps with ordering logs after export. {{</note>}}
+
+To explicitly disable access logs, apply the following config:
+
+```nginx
+http {
+	access_log off;
+}
+```
+
+or
+
+```nginx
+http {
+	access_log /dev/null;
+}
+```
+
+To learn more about how to specify `access__log` in different configuration levels and their effect, see [access_log](https://nginx.org/en/docs/http/ngx_http_log_module.html#access_log)
+
+{{<warning>}}Unless you use **syslog**, keep NGINX logs in the **/var/log/nginx** directory. Otherwise, you may lose data from your logs.
+{{</warning>}}

content/includes/nginxaas-azure/logging-config-error-logs.md

@@ -0,0 +1,19 @@
+---
+docs: "DOCS-000"
+---
+
+By default, NGINXaaS for Azure puts the error log at **/var/log/nginx/error.log**. It includes messages with severity **error** and above.
+
+While you should configure log files in the **/var/log/nginx** directory, you can change the filename and severity level. For example, the following line in the NGINX configuration sends errors to the `nginx-error.log` file, and limits messages to a severity level of **emerg**:
+
+```nginx
+error_log /var/log/nginx/nginx-error.log emerg;
+```
+
+Alternatively, you can disable error logs completely with the following line:
+
+```nginx
+error_log /dev/null;
+```
+
+To learn more about how to specify `error_log` in different configuration levels, see the documentation of the [error_log](https://nginx.org/en/docs/ngx_core_module.html?#error_log) directive.

content/includes/nginxaas-azure/logging-limitations.md

@@ -0,0 +1,8 @@
+---
+docs: "DOCS-000"
+---
+
+1. File-based logs must be configured to use the path **/var/log/nginx**.
+1. The **gzip** parameter for the **access_log** directive is not supported, and uploading a config with this parameter will cause an error.
+1. Logging **error_log** to a cyclic memory buffer using the **memory:** prefix is not allowed and will cause a config upload error.
+1. Egress Networking charges apply for traffic sent from the NGINX deployment to a syslog server present in a different VNet.