NGINX

Supported Technologies

tCell has pre-existing builds for these NGINX distributions. If your NGINX distribution does not match one on this list, see Build a custom agent for specific information on what to do.

Prerequisites

Before starting, confirm you have:

• Set up a tCell account
• Created a tCell application (Admin > Applications)
• Ensured NGINX is installed in the directory $NGINX_INSTALL_DIR
• Allowed outbound HTTPS connections to the tCell cloud (What IPs do tCell agents connect to?)
• Downloaded the agent and the config file:
  1. Click on "tCell Admin" in top nav bar.
  2. Click "Download Agent".
  3. Click on “Web Server Agent”.
  4. Select "NGINX" agent.
  5. Select "Create New API Key" (default).
  6. Download the tar.xz file.
  7. Click "Download Config File" to download the agent's config file (which is pre-populated with the application and key information).

Limitations

The NGINX Openresty variant of our module has some important limitations to be aware of when considering configuration and deployment.

• Openresty reads request bodies in a lazy manner, preventing us from inspecting POST data in endpoints that take advantage of LUA blocks unless that endpoint calls ngx.req.read_body() or uses the lua_need_request_body on; directive.ngx.req.read_body() or uses the lua_need_request_body on; directive.
• The agent does not support response-size events, nor response-size-based blocking rules on responses that do not include a Content-Length header. By default, LUA-generated response bodies are sent with a chunking transfer encoding and have an indeterminate Content-Length. If you wish to receive sensor events about large response sizes you will have to configure the Content-Length header manually.

Installation

1. Ensure you have /etc/nginx/nginx.conf and the modules directory. If necessary, create them.

2. Extract the downloaded NGINX agent tar.xz file.

3. Put the ngx_http_tcell_agent_module.so file that corresponds to your OS and NGINX version in --modules-path. (Package contains versions built for Ubuntu x-y, CentOS x-y, Amazon Linux.)

4. Add the line load_module modules/ngx_http_tcell_agent_module.so; to nginx.conf before the events block.
   
   Example:

    
   1
       user  nginx
   2
       worker_processes auto;
   3
   
   4
       error_log  logs/error.log;
   5
       error_log  logs/error.log  notice;
   6
       error_log  logs/error.log  info;
   7
       pid        logs/nginx.pid;
   8
   
   9
       load_module modules/ngx_http_tcell_agent_module.so;
   10
   
   11
       events {
   12
           worker_connections  1024;
   13
       }

5. Put the tcell_agent.config file in in the same directory as the nginx.conf file.

6. Add the line tcell_app_id APP_ID; to the events block in the /etc/nginx/nginx.conf file.
   
   Example: http {  tcell_app_id krtest-CeOCq;  ...}

7. Restart NGINX.

If you encounter a logged message similar to nginx: [emerg] module "modules/ngx_http_tcell_agent_module.so" is not binary compatible in /usr/local/nginx/conf/nginx.conf:11, this could mean:

• You selected an agent build that does not match your distribution
• Your NGINX build is a locally generated custom build. See Build a custom agent on how to work with Rapid7 to build a custom agent.

NGINX supports log rolling which allows the agent to continue adding new lines to a full log file. See set up log rolling.

Example: nginx -V

 
1
root@8a5fa88427d8:/etc/nginx# nginx -V
2

3
nginx version: nginx/1.14.0 (Ubuntu)
4

5
built with OpenSSL 1.1.1 11 Sep 2018
6

7
TLS SNI support enabled
8

9
configure arguments: --with-cc-opt='-g -O2 -fdebug-prefix-map=/build/nginx-GkiujU/nginx-1.14.0=. -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -fPIC' --prefix=/usr/share/nginx --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access.log --error-log-path=/var/log/nginx/error.log --lock-path=/var/lock/nginx.lock --pid-path=/run/nginx.pid --modules-path=/usr/lib/nginx/modules --http-client-body-temp-path=/var/lib/nginx/body --http-fastcgi-temp-path=/var/lib/nginx/fastcgi --http-proxy-temp-path=/var/lib/nginx/proxy --http-scgi-temp-path=/var/lib/nginx/scgi --http-uwsgi-temp-path=/var/lib/nginx/uwsgi --with-debug --with-pcre-jit --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-http_auth_request_module --with-http_v2_module --with-http_dav_module --with-http_slice_module --with-threads --with-http_addition_module --with-http_geoip_module=dynamic --with-http_gunzip_module --with-http_gzip_static_module --with-http_image_filter_module=dynamic --with-http_sub_module --with-http_xslt_module=dynamic --with-stream=dynamic --with-stream_ssl_module --with-mail=dynamic --with-mail_ssl_module

Verification

To verify that data are being sent to tCell, go to your tCell console and ensure that the number of web server agents listed for the application you just created is more than 0.

Troubleshooting

Log files can be found in the tcell/logs directory. If you don't see a tcell/logs directory, it's likely that the tCell agent has not started. If so:

1. Verify that the tCell agent is being added to the server startup by running the following command:

    
   1
   ps aux | grep --color tcell

2. Check for errors in your catalina.out log. Alternatively, running bin/catalina.sh run or bin/catalina.bat run on Windows will start tomcat in the foreground, and print any errors while starting up.

You can customize the log level in the tcell_agent.config file by adding a block such as the following:

json
1
"logging_options": {
2
    "enabled": true,
3
    "level": "INFO"
4
}

See tcell/tcell_agent.config.template for an example.

Valid log levels are:

• TRACE
• DEBUG
• INFO (default)
• WARN
• ERROR

The preceding list indicates the precedence among the levels, from top to bottom. When you enable a log level, the lower log levels are also enabled. For example, if you enable DEBUG, then INFO, WARN, and ERROR are also enabled.

When a log file becomes full, logging continues in a new log file. See Log Rolling for more information.