> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/web-application-and-api-protection-waap/data-collection/gateways-load-balancers/nginx/nginx-community-version.md).

# NGINX community version

Traceable supports the following operating systems:

* Amazon Linux 2
* CentOS 7 and 8
* Ubuntu 18.0.4 and Ubuntu 20.0.4
* Debian 10

***

## NGINX community support

| NGINX community major version | Minor versions                                                                                            |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| 1.11.x                        | 1.11.10, 1.11.11, 1.11.12, 1.11.13                                                                        |
| 1.12.x                        | 1.12.0,1.12.1,1.12.2                                                                                      |
| 1.13.x                        | 1.13.0, 1.13.1, 1.13.2, 1.13.3, 1.13.4, 1.13.5, 1.13.6, 1.13.7, 1.13.8, 1.13.9, 1.13.10, 1.13.11, 1.13.12 |
| 1.14.x                        | 1.14.0,1.14.1,1.14.2                                                                                      |
| 1.15.x                        | 1.15.0,1.15.8                                                                                             |
| 1.16.x                        | 1.16.0, 1.16.1                                                                                            |
| 1.17.x                        | 1.17.0, 1.17.1, 1.17.2, 1.17.3, 1.17.4, 1.17.5, 1.17.6, 1.17.7, 1.17.8, 1.17.9, 1.17.10                   |
| 1.18.x                        | 1.18.0                                                                                                    |
| 1.19.x                        | 1.19.0                                                                                                    |
| 1.20.x                        | 1.20.0, 1.20.1                                                                                            |
| 1.21.x                        | 1.21.0, 1.21.1, 1.21.3, 1.21.4, 1.21.5, 1.21.6                                                            |
| 1.22.x                        | 1.22.1                                                                                                    |
| 1.23.x                        | 1.23.2, 1.23.3, 1.23.4                                                                                    |
| 1.24.x                        | 1.24.0                                                                                                    |
| 1.25.x                        | 1.25.0, 1.25.1, 1.25.2, 1.25.3, 1.25.4, 1.25.5                                                            |
| 1.26.x                        | 1.26.1, 1.26.2                                                                                            |
| 1.27.x                        | 1.27.0, 1.27.1, 1.27.2                                                                                    |

Refer to the [NGINX 0.1.75 release notes](https://docs.traceable.ai/docs/rnnginx23#0175-4th-may) to view NGINX agent support for CentOS 7 and CentOS 8.

***

The installation topic is divided into:

* Individual OS-specific instructions
* [Verification](#verification)
* [Upgrade](#upgrade)
* [Uninstall](#uninstall)

***

## Validations script

Traceable provides a NGINX validation script. The script validates whether you are running a version of NGINX that is supported by Traceable. Traceable provides:

* yum package for the official NGINX CentOS and EPEL repos.
* apt packages for the official NGINX Ubuntu repos.

Enter the following command:

```language-actionscript
curl -L https://downloads.traceable.ai/install/nginx/validate.sh | sh -
```

##

***

## Amazon Linux 2

Installing Traceable’s Tracing agent on NGINX community version running on Amazon Linux 2 consists of the following steps:

1. Check NGINX repository
2. Install Traceable’s Tracing agent
3. Edit `nginx.conf` file
4. Reload NGINX

### Step 1 - Check NGINX repository

Enter the following command to check from which repository NGINX was installed.

```language-actionscript
yum info nginx | grep "From repo"
```

### Step 2 - Install NGINX tracing agent

Complete the following steps to install Traceable NGINX Tracing agent:

1. Set up the yum repository. You might have already done this as part of setting up traceable-agent. For more information, see **Setup the repository** in [Virtual machine](https://docs.traceable.ai/docs/vm) topic.
2. Install the Tracing agent. Replace `"NN.N"`with your NGINX version.
   * \*\*Non-EPEL release: \*\*\
     Enter the following command to install NGINX module:

     ActionScript

     ```language-actionscript
     sudo yum install nginx-module-traceable-1.NN.N
     ```
   * \*\*EPEL release: \*\*\
     Enter the following command to install NGINX module:

     ActionScript

     ```language-actionscript
     sudo yum install nginx-module-traceable-epel-1.NN
     ```

### Step 3 - Edit the configuration file

Edit your `nginx.conf` file, for example, `/etc/nginx/nginx.conf`. Complete the following steps:

1. Add the load module directive after `pid /run/nginx.pid`
   * \*\*Non-EPEL release: \*\*

     ```language-actionscript
     load_module modules/ngx_http_traceableai_module.so;
     ```
   * **EPEL release:**

     ```language-actionscript
     load_module /usr/lib64/nginx/modules/ngx_http_traceableai_module.so;
     ```
2. Add the following to the `nginx.conf` file in the `http` block above the `include /etc/nginx/conf.d/*.conf`

```language-actionscript
traceableai {
    service_name nginx;
    collector_host localhost;
    collector_port 9411;
    blocking on;
    config_endpoint localhost:5441;
  }
  # enable monitoring for all requests.
  opentracing on;
  # propagate request context to upstream services
  opentracing_propagate_context;
```

{% hint style="info" %}
If your location block has `proxy_set_header` set, add `opentracing_propagate_context` to the location block, else add `opentracing_propagate_context` to the http block as shown in step 2 above.
{% endhint %}

#### Optional - Add custom error code

You can add a custom error code in 4xx series as response status code when a request gets blocked. You can configure this in the `nginx.conf` file by setting `blocking_status_code` field in the `traceableai section`. The default value is set to 403. The following is an example snippet, with the last line showing the `blocking_status_code` value set to 472.

```language-actionscript
traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }
```

#### Content capture

You can configure the type of content you wish to capture. Configure `capture_content_types` inside the traceableai section. Capturing of the following content types is supported:

* `xml`
* `json`
* `grpc`
* `x-www-form-urlencoded`

If you wish to capture XML json, specify the directive as `capture_content_types xml json`. If the directive is not specified, Traceable by default captures json, grpc, and x-www-form-urlencoded content as these are the most common content types.

```language-actionscript
traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on; 
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        # capture content type
        capture_content_types xml json
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }
```

### Step 4 - Reload NGINX

Enter the following command to reload NGINX configuration:

```language-actionscript
sudo nginx -s reload
```

[Verify](#verification) whether the installation was successful.

***

## CentOS

Installing Traceable’s Tracing agent on NGINX community version running on CentOS consists of the following steps:

1. Check NGINX repository
2. Install Traceable’s Tracing agent
3. Edit `nginx.conf` file
4. Reload NGINX

### Step 1 - Check NGINX repository

Enter the following command to check from which repository NGINX was installed.

```language-actionscript
yum info nginx | grep "From repo"
```

### Step 2 - Install NGINX tracing agent

Complete the following steps to install Traceable NGINX Tracing agent:

1. Set up the yum repository. You might have already done this as part of setting up traceable-agent. For more information, see **Setup the repository** in [Virtual machine](https://docs.traceable.ai/docs/vm) topic.
2. Install the Tracing agent. Replace `"NN.N"`with your NGINX version.
   1. \*\*Non-EPEL release: \*\*\
      Enter the following command to install NGINX module:

      ActionScript

      ```language-actionscript
      sudo yum install nginx-module-traceable-1.NN.N
      ```
   2. \*\*EPEL release: \*\*\
      Enter the following command to install NGINX module:

      ActionScript

      ```language-actionscript
      sudo yum install nginx-module-traceable-epel-1.NN
      ```

### Step 3 - Edit the configuration file

Edit your `nginx.conf` file, for example, `/etc/nginx/nginx.conf`. Complete the following steps:

1. Add the load module directive after `pid /run/nginx.pid`
   * \*\*Non-EPEL release: \*\*

     ```language-actionscript
     load_module modules/ngx_http_traceableai_module.so;
     ```
   * **EPEL release:**

     ```language-actionscript
     load_module /usr/lib64/nginx/modules/ngx_http_traceableai_module.so;
     ```
2. Add the following to the `nginx.conf` file in the `http` block above the `include /etc/nginx/conf.d/*.conf`

```language-actionscript
traceableai {
    service_name nginx;
    collector_host localhost;
    collector_port 9411;
    blocking on;
    config_endpoint localhost:5441;
  }
  # enable monitoring for all requests.
  opentracing on;
  # propagate request context to upstream services
  opentracing_propagate_context;
```

{% hint style="info" %}
If your location block has `proxy_set_header` set, add `opentracing_propagate_context` to the location block, else add `opentracing_propagate_context` to the http block as shown in step 2 above.
{% endhint %}

#### Optional - Add custom error code

You can add a custom error code in 4xx series as response status code when a request gets blocked. You can configure this in the `nginx.conf` file by setting `blocking_status_code` field in the `traceableai section`. The default value is set to 403. The following is an example snippet, with the last line showing the `blocking_status_code` value set to 472.

```language-actionscript
traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }
```

#### Content capture

You can configure the type of content you wish to capture. Configure `capture_content_types` inside the traceableai section. Capturing of the following content types is supported:

* `xml`
* `json`
* `grpc`
* `x-www-form-urlencoded`

If you wish to capture xml json, specify the directive as `capture_content_types xml json`. If the directive is not specified, Traceable by default captures json, grpc, and x-www-form-urlencoded content as these are the most common content types.

```language-actionscript
traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        # capture content type
        capture_content_types xml json
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }
```

### Step 4 - Reload NGINX

Enter the following command to reload NGINX configuration:

```language-actionscript
sudo nginx -s reload
```

[Verify](#verification) whether the installation was successful.

***

## Ubuntu

Installing Traceable’s Tracing agent on NGINX community version running on Ubuntu 18.0.4 or 20.0.4 consists of the following steps:

1. Install Traceable’s Tracing agent
2. Edit `nginx.conf` file
3. Reload NGINX

### Step 1 - Install NGINX tracing agent

Complete the following steps to install Traceable NGINX module:

1. Set up the apt repository. You might have already done this as part of setting up traceable-agent. For more information, see **Setup the repository** in [Virtual machine](https://docs.traceable.ai/docs/vm) topic.
2. Install the module. Replace `"NN.N"`with your NGINX version.

   ActionScript

   ```language-actionscript
   sudo apt-get install nginx-module-traceable-1.NN.N
   ```

### Step 2 - Edit the configuration file

Edit your nginx.conf file, for example, `/etc/nginx/nginx.conf`

1. Add the load module directive after `pid /run/nginx.pid`

   ```language-actionscript
   load_module modules/ngx_http_traceableai_module.so;
   ```
2. Add the following to the `nginx.conf` file in the `http` block above the include `/etc/nginx/conf.d/*.conf;`line:

   ActionScript

   ```language-actionscript
   traceableai {
       service_name nginx;
       collector_host localhost;
       collector_port 9411;
       blocking on
       config_endpoint localhost:5441;
     }
     # enable monitoring for all requests.
     opentracing on;
     # propagate request context to upstream services
     opentracing_propagate_context;
   ```

{% hint style="info" %}
If your location block has `proxy_set_header` set, add `opentracing_propagate_context` to the location block, else add `opentracing_propagate_context` to the http block as shown in step 2 above.
{% endhint %}

#### Optional - Add custom error code

You can add custom error code in 4xx series as response status code when a request gets blocked. You can configure this in the `nginx.conf` file by setting `blocking_status_code` field in the `traceableai section`. The default value is set to 403. Following is an example snippet with the last line showing the `blocking_status_code` value set to 472.

```language-actionscript
traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        #blocking_skip_internal_request off;
          blocking_status_code 472;
    }
```

#### Content capture

You can configure the type of content you wish to capture. Configure `capture_content_types` inside the traceableai section. Capturing of the following content types is supported:

* `xml`
* `json`
* `grpc`
* `x-www-form-urlencoded`

If you wish to capture xml json, specify the directive as `capture_content_types xml json`. If the directive is not specified, Traceable by default captures json, grpc, and x-www-form-urlencoded content as these are the most common content types.

```language-actionscript
traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        # capture content type
        capture_content_types xml json
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }
```

### Step 3 - Reload NGINX

Enter the following command to reload NGINX configuration:

```language-actionscript
sudo nginx -s reload
```

***

## Verification

You can complete the following steps to verify if the installation was successful:

1. Exercise the applications routing through NGINX
2. Visit the [Traceable platform](https://app.traceable.ai/explorer?time=1h\&scope=endpoint-traces) and confirm traces are showing up.

***

## Upgrade

To upgrade the NGINX tracing agent:

1. Install the module as per the install section.
2. Update the config in nginx.conf if needed.
3. Restart nginx

***

## Uninstall

Complete the following steps to uninstall NGINX tracing agent:

1. Depending on how the module was installed
   1. Remove the dynamic library files: `ngx_http_traceableai.module.so` and `libtraceable.so`.
      * **For Amazon Linux 2 and CentOS**

        ActionScript

        ```language-actionscript
        sudo yum remove nginx-module-traceable*
        ```
      * **For Ubuntu**

        ActionScript

        ```language-actionscript
        sudo apt-get remove nginx-module-traceable*
        ```
2. Remove the Traceable configuration lines from `nginx.conf`
3. Restart NGINX