--- title: "NGINX community version" slug: "nginx-community-version" updated: 2024-12-05T08:45:37Z published: 2024-12-05T08:45:37Z --- > ## Documentation Index > Fetch the complete documentation index at: https://traceabledocs.document360.io/llms.txt > Use this file to discover all available pages before exploring further. # 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](/docs/nginx-community-version#verification) - [Upgrade](/docs/nginx-community-version#upgrade) - [Uninstall](/docs/nginx-community-version#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: ```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. ```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](/v1/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 ** ** ```actionscript sudo yum install nginx-module-traceable-1.NN.N ``` - **EPEL release:** Enter the following command to install NGINX module: ActionScript ** ** ```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:** ```actionscript load_module modules/ngx_http_traceableai_module.so; ``` - **EPEL release:** ```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` ```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; ``` Note: 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. #### 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. ```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. ```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: ```actionscript sudo nginx -s reload ``` [Verify](/docs/nginx-community-version#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. ```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](/v1/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 ** ** ```actionscript sudo yum install nginx-module-traceable-1.NN.N ``` 2. **EPEL release:** Enter the following command to install NGINX module: ActionScript ** ** ```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:** ```actionscript load_module modules/ngx_http_traceableai_module.so; ``` - **EPEL release:** ```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` ```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; ``` Note: 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. #### 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. ```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. ```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: ```actionscript sudo nginx -s reload ``` [Verify](/docs/nginx-community-version#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](/v1/docs/vm) topic. 2. Install the module. Replace `"NN.N"`with your NGINX version. ActionScript ** ** ```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` ```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 ** ** ```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; ``` Note: 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. #### 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. ```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. ```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: ```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 ** ** ```actionscript sudo yum remove nginx-module-traceable* ``` - **For Ubuntu** ActionScript ** ** ```actionscript sudo apt-get remove nginx-module-traceable* ``` 2. Remove the Traceable configuration lines from `nginx.conf` 3. Restart NGINX