|
| 1 | +--- |
| 2 | +title: Custom dimensions for log entries |
| 3 | +toc: false |
| 4 | +weight: 200 |
| 5 | +nd-content-type: reference |
| 6 | +nd-product: NAP-WAF |
| 7 | +--- |
| 8 | + |
| 9 | +Custom dimensions log entries feature refers to the new configuration in F5 WAF for NGINX, where the new directive called `app_protect_custom_log_attribute` is assigned to a particular location or server or http level in the `nginx.conf` file. The need is to be able to add custom identifiers to the respective location and/or server and identify requests in the Security Log by those identifiers. |
| 10 | + |
| 11 | +The `app_protect_custom_log_attribute` directive will be used to track the assigned location/server/http dimension of each request by adding the `app_protect_custom_log_attribute` to the **Security Logs** a.k.a **Request Logs**. Since it is a custom attribute a customer can set, that custom attribute will appear for every request log entry that was handled by that location/server. |
| 12 | + |
| 13 | +### Configuration |
| 14 | + |
| 15 | +A new directive `app_protect_custom_log_attribute` will be added to the `nginx.conf` file. You can set this directive at all scopes: http, server and location. The setting at the location scope overrides the setting in the server and/or http scopes and the server scope overrides the http scope. The `app_protect_custom_log_attribute` directive syntax will consist of a **name/value** or **key/value** pair i.e. "app_protect_custom_log_attribute <name> <value>". |
| 16 | + |
| 17 | +Example Configuration: |
| 18 | + |
| 19 | +In the below example, we are configuring the `app_protect_custom_log_attribute` directive at the server and location level where we define the **key/value** pair as one string. |
| 20 | + |
| 21 | +```nginx |
| 22 | +
|
| 23 | +user nginx; |
| 24 | +load_module modules/ngx_http_app_protect_module.so; |
| 25 | +error_log /var/log/nginx/error.log debug; |
| 26 | +
|
| 27 | +events { |
| 28 | + worker_connections 65536; |
| 29 | +} |
| 30 | +server { |
| 31 | +
|
| 32 | + listen 80; |
| 33 | +
|
| 34 | + server_name localhost; |
| 35 | + proxy_http_version 1.1; |
| 36 | + app_protect_custom_log_attribute ‘environment' 'env1'; |
| 37 | +
|
| 38 | + location / { |
| 39 | +
|
| 40 | + app_protect_enable on; |
| 41 | + app_protect_custom_log_attribute gateway gway1; |
| 42 | + app_protect_custom_log_attribute component comp1; |
| 43 | + proxy_pass http://172.29.38.211:80$request_uri; |
| 44 | + } |
| 45 | + } |
| 46 | +``` |
| 47 | + |
| 48 | +The **key/value** pair will be 'environment env1', ‘gateway gway1’ and ‘component comp1’ in the above examples, i.e. |
| 49 | + |
| 50 | +- app_protect_custom_log_attribute environment env1; |
| 51 | +- app_protect_custom_log_attribute gateway gway1; |
| 52 | +- app_protect_custom_log_attribute component comp1; |
| 53 | + |
| 54 | +The above key/value pair will be parsed as below: |
| 55 | + |
| 56 | +```shell |
| 57 | +"customLogAttributes": [ |
| 58 | + { |
| 59 | + "name": "gateway", |
| 60 | + "value": "gway1" |
| 61 | + }, |
| 62 | + { |
| 63 | + "name": "component", |
| 64 | + "value": "comp1" |
| 65 | + }, |
| 66 | +] |
| 67 | +``` |
| 68 | + |
| 69 | +### Things to Remember While Configuring the Custom Dimensions Log Entries |
| 70 | + |
| 71 | +The `app_protect_custom_log_attribute` directive has a few limitations which should be kept in mind while configuring this directive: |
| 72 | + |
| 73 | +- Key and value strings are limited to 64 chars |
| 74 | +- Maximum possible directive numbers are limited to 10 (in total) in each context i.e. Limit of 10 keys and values |
| 75 | + |
| 76 | +### Errors and Warnings |
| 77 | + |
| 78 | +An error message "`app_protect_custom_log_attribute` directive is invalid" will be displayed in the Security Log if the below conditions are met: |
| 79 | + |
| 80 | +1. If the `app_protect_custom_log_attribute` exceeds the maximum number of 10 directives |
| 81 | +2. If the `app_protect_custom_log_attribute` exceeds the maximum name length of 64 chars |
| 82 | +3. If the `app_protect_custom_log_attribute` exceeds the maximum value of 64 chars |
| 83 | + |
| 84 | +Error message example: |
| 85 | + |
| 86 | +```shell |
| 87 | +app_protect_custom_log_attribute directive is invalid. Number of app_protect_custom_log_attribute directives exceeds maximum |
| 88 | +``` |
| 89 | + |
| 90 | +### Logging and Reporting |
| 91 | + |
| 92 | +When `app_protect_custom_log_attribute` is assigned to a particular location/server/http context, it will appear in the `json_log` field as a new JSON property called "customLogAttributes" at the top level. The property will not appear if no `app_protect_custom_log_attribute` directive was assigned. |
| 93 | + |
| 94 | +Attributes at the http level applies to all servers and locations unless a specific server or location overrides the same key with a different value. Same goes for the server level and all locations under it. In the below example, the "environment" attribute will appear in logs of all locations under that server. |
| 95 | + |
| 96 | +Security logging example in json_log: |
| 97 | + |
| 98 | +```json |
| 99 | +""customLogAttribute"":[{""name"":""component"",""value"":""comp1""},{""name"":""gateway"",""value"":""gway1""}]}" |
| 100 | +``` |
0 commit comments