Server Agent Options

NameSupported AgentsEnvironment VariableConfig File Property
App IDAllTCELL_AGENT_APP_IDapp_id
API KeyAllTCELL_AGENT_API_KEYapi_key
API URL PrefixAllTCELL_AGENT_API_URLtcell_api_url
Input URL PrefixAllTCELL_AGENT_INPUT_URLtcell_input_url
Enable AgentAllTCELL_AGENT_ENABLEDenabled
Agent Home DirectoryAllTCELL_AGENT_HOMEN/A
Register InstrumentationAllTCELL_AGENT_INSTRUMENTN/A
Log DirectoryAllTCELL_AGENT_LOG_DIRlog_dir
Config File PathAllTCELL_AGENT_CONFIGN/A
Enable JSON Body InspectionAllTCELL_AGENT_ENABLE_JSON_BODY_INSPECTIONinspect_json_posts
Allow PayloadsAllTCELL_AGENT_ALLOW_PAYLOADSallow_payloads
Allow Payload LoggingAllTCELL_AGENT_ALLOW_LOG_PAYLOADSlog_payloads
Host IdentifierAllTCELL_AGENT_HOST_IDENTIFIERhost_identifier
Enable LoggingAllTCELL_AGENT_LOG_ENABLEDlogging_options.enabled
Log FilenameAllTCELL_AGENT_LOG_FILENAMElogging_options.filename
Logging LevelAllTCELL_AGENT_LOG_LEVELlogging_options.level
Log Destination TypeAllTCELL_AGENT_LOG_DESTINATIONlogging_options.destination
Max Log File SizeAllTCELL_AGENT_LOG_FILE_MAX_SIZE_MBlogging_options.max_file_size_mb
HMAC KeyAllTCELL_AGENT_HMAC_KEYhmac_key
Password HMAC KeyAllTCELL_AGENT_PASSWORD_HMAC_KEYpassword_hmac_key
Cache DirectoryAllTCELL_AGENT_CACHE_DIRN/A
Proxy URLAll except Apache and CloudfrontTCELL_AGENT_PROXY_URLproxy_url
Proxy UsernameAll except Apache and CloudfrontTCELL_AGENT_PROXY_USERNAMEproxy_username
Proxy PasswordAll except Apache and CloudfrontTCELL_AGENT_PROXY_PASSWORDproxy_password
Enable Reverse ProxyAllTCELL_AGENT_REVERSE_PROXYreverse_proxy
Reverse Proxy IP Address HeaderAllTCELL_AGENT_REVERSE_PROXY_IP_ADDRESS_HEADERreverse_proxy_ip_address_header
Max Header SizeAllTCELL_AGENT_MAX_HEADER_SIZEmax_csp_header_bytes
Max Number of RoutesAllTCELL_AGENT_MAX_ROUTESmax_routes
Enable Subresource IntegrityAllTCELL_AGENT_ENABLE_JS_AGENT_SRIenable_js_agent_sri
JS Agent API Base URLAllTCELL_AGENT_JS_AGENT_API_URLjs_agent_api_base_url
JS Agent URLAllTCELL_AGENT_JS_AGENT_URLjs_agent_url
Fetch Policies From tCellAllTCELL_AGENT_UPDATE_POLICYfetch_policies_from_tcell
Use Native CertsAllTCELL_AGENT_USE_NATIVE_CERTSuse_native_certs
Session IdentifiersAllN/Asession_identifiers
IIS URL Rewrite for ARR.NETTCELL_AGENT_IIS_URL_REWRITEiis_url_rewrite
Block Log4shell EnabledJVMTCELL_AGENT_BLOCK_LOG4SHELL_ENABLEDblock_log4shell_enabled
Log File AccessJVMTCELL_AGENT_LOG_FILE_ACCESSlog_file_access
Package Tracker IntervalJVMTCELL_AGENT_PACKAGE_TRACKER_INTERVAL_MSN/A
Tomcat-specific RedirectsJVMTCELL_AGENT_TOMCAT_SPECIFIC_REDIRECTStomcat_specific_redirects
Do Not InstrumentJVMN/Ado_not_instrument
Remove Server HeaderNGINXTCELL_AGENT_SERVER_HEADER_OFFserver_header_off
Inspect Multipart PostsNGINX and ApacheTCELL_AGENT_INSPECT_MULTIPART_POSTSinspect_multipart_posts
Multipart Parser Time BudgetNGINX and ApacheTCELL_AGENT_MULTIPART_PARSER_TIME_BUDGET_MSmultipart_parser_time_budget_ms
Multipart Parser SPACE BudgetNGINX and ApacheTCELL_AGENT_MULTIPART_PARSER_SPACE_BUDGET_BYTESmultipart_parser_space_budget_bytes
Enabled InstrumentationsRuby
Python
N/Aenabled_instrumentations
Proxy URLAll except Apache and CloudfrontPROXY_URLproxy_url
Proxy UsernameAll except Apache and CloudfrontPROXY_USERNAMEproxy_username
Proxy PasswordAll except Apache and CloudfrontPROXY_PASSWORDproxy_password

Environment Variables and Config File Properties

Agent Versions

These agent versions support all of the environment variables and config file properties described in this document (Server Agent Options). Earlier agent versions may also support some variables and properties.

AgentMinimum version
Apache3.1.0
IIS2.0.0
Java1.13.0
.NET2.3.2
.NET Core2.3.2
NGINX3.1.0
Node.js2.2.0
Python1.7.0
Ruby2.3.0

Details

See Configuration Conventions for the log and cache directory defaults, configuration file structure, configuration sources, configuration file path, and their priorities.

TCELL_AGENT_APP_ID

app_id

  • Description - Identifies the tCell application.
  • Type - string
  • Required? - Y
  • Example - exampleapp-L4Ihu

TCELL_AGENT_API_KEY

api_key

  • Description - The Server Agent API Key, created through the tCell web UI, that grants permission to a specific tCell application.
  • Type - string
  • Required? - Y
  • Example - abcd-efgh-hijk

TCELL_AGENT_API_URL

tcell_api_url

  • Description - The URL prefix to poll for new configuration information. Should correspond to the AWS region where your tCell data is stored.
  • Type - string
  • Default - https://us.agent.tcell.insight.rapid7.com/api/v1
  • Required - N
  • Example - http://10.0.2.2:8000

All Collectors must be able to establish outbound connectivity on port 443 to *.endpoint.ingress.rapid7.com and communicate with the domains shown in the Data and Storage (S3) columns of the following table according to your geographic region. For example, for tCell subscribers that elect to store their data in Australia, Collectors must be able to communicate with the following endpoints using port 443:

  • *.endpoint.ingress.rapid7.com
  • au.data.insight.rapid7.com
  • s3-ap-southeast-2.amazonaws.com
RegionData endpointStorage (S3 endpoint)
United States - 1data.insight.rapid7.coms3.amazonaws.com
United States - 2us2.data.insight.rapid7.coms3.us-east-2.amazonaws.com
United States - 3us3.data.insight.rapid7.coms3.us-west-2.amazonaws.com
Canadaca.data.insight.rapid7.coms3.ca-central-1.amazonaws.com
Europeeu.data.insight.rapid7.coms3.eu-central-1.amazonaws.com
Japanap.data.insight.rapid7.coms3-ap-northeast-1.amazonaws.com
Australiaau.data.insight.rapid7.coms3-ap-southeast-2.amazonaws.com

If you intend to deploy token-based Insight Agents through your Collectors, you also need to allow outbound connectivity from each Collector on port 443 to the endpoint that provides the agent's configuration files. Just like the Data and Storage endpoints in the previous table, you can configure your firewall rules to allow your Collectors to connect to a region-specific version of the Deployment endpoint to meet this requirement:

RegionDeployment endpoint
United States - 1us.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files
United States - 2us2.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files
United States - 3us3.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files
Canadaca.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files
Europeeu.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files
Japanap.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files
Australiaau.deployment.endpoint.ingress.rapid7.com/api/v1/get_agent_files

TCELL_AGENT_INPUT_URL

tcell_input_url

  • Description - The URL prefix at which to send events.
  • Type - string
  • Default - https://us.input.tcell.insight.rapid7.com/api/v1
  • Required - N
  • Example - http://10.0.2.2:3000

TCELL_AGENT_ENABLED

enabled

  • Description - When false, the agent does nothing for an application.
  • Type - boolean
  • Default - true
  • Required - N
  • Example - false

TCELL_AGENT_HOME

N/A

  • Description - The absolute file path to the directory in which the agent will create log and cache directories by default, assuming no other configuration.
  • Default
  • Example - /etc/tcell
  • Notes For the .NET, .NET Core, and IIS Web Server agents, the specified path will store the /logs and the /cache folder. It never looks for the tcell_agent.config file in this location."

TCELL_AGENT_INSTRUMENT

N/A

  • Description - When false, the agent does not register instrumentation. It will still request policies.
  • Type - boolean
  • Default - true

TCELL_AGENT_LOG_DIR

log_dir

  • Description - Directory for all logs
  • Type - string
  • Required - N
  • Example - /var/log/tcell
  • Default - $TCELL_HOME/logs

TCELL_AGENT_CONFIG

N/A

  • Description - The absolute file path to the tCell agent config file
  • Default
  • Type - string
  • Example - /etc/tcell

TCELL_AGENT_ENABLE_JSON_BODY_INSPECTION

inspect_json_posts

  • Description - When true, the agent inspects request bodies for JSON and XML content
  • Type - boolean
  • Default - false

TCELL_AGENT_ALLOW_PAYLOADS

allow_payloads

  • Description - When true, the agent includes inspected request payloads in events sent to the cloud. The payloads can match a regex (cmdi, xss, sqli, fpt, etc.) of up to 150 characters.
  • Type - boolean
  • Default - true
  • Example - false

TCELL_AGENT_ALLOW_LOG_PAYLOADS

log_payloads

  • Description - When true, the agent logs inspected request payloads in a tcell_agent_payloads.log file in the configured log directory.
  • Type - boolean
  • Default - true
  • Required - N
  • Example - true

TCELL_AGENT_HOST_IDENTIFIER

host_identifier

  • Description - Agent host identifier to use. Each agent must have a different identifier. Defaults to hostname provided by the operating system.
  • Type - string
  • Required - N
  • Default - (Defaults to OS hostname)
  • Example - web-host-1

TCELL_AGENT_LOG_ENABLED

logging_options.enabled

  • Description - Enables agent logging.
  • Type - boolean
  • Default - true

TCELL_AGENT_LOG_FILENAME

logging_options.filename

  • Description - Sets the agent logging filename. By default, this is relative to the tcell directory. Can also pass an absolute path.
  • Type - string
  • Default - tcell.log

TCELL_AGENT_LOG_LEVEL

logging_options.level

  • Description - Sets the agent logging level. Possible values are 'error', 'warn', 'info', 'debug', and 'trace'.
  • Type - enumeration
  • Default - info

TCELL_AGENT_LOG_DESTINATION

logging_options.destination

  • Description - Specifies the type of log output.
  • Type - Enumeration ('stdout', 'file', 'filenorolling'); filenorolling is the same as file, but the agent will not roll log files after they reach a certain size.
  • Default - file

TCELL_AGENT_LOG_FILE_MAX_SIZE_MB

logging_options.max_file_size_mb

Description - Sets the maximum size allowed for a tCell log file (in MBs). The initial and minimum size of a log file is 1 MB. There is no maximum size limit. The size limit applies to every log file in the log file folder, which can hold a maximum of 10 log files.\n\nThe location of a log file folder depends on the agent type. For the IIS and .NET agent types, the log file folder locations depend on the configuration and the IDs of the apps that run tCell:

  • IIS \nC:\\ProgramData\\Rapid7, Inc\\tCell IIS Agent\\LM\\W3SVC\\2\\ROOT\\[sub app name]\n
  • .NET \nC:\\ProgramData\\Rapid7, Inc\\tCell .NET Agent\\[web app name]\\[sub app name]
  • For all other agent types, the log file folder location is\n\ntcell/logs\n

TCELL_AGENT_HMAC_KEY

hmac_key

  • Description - The key to use for hashing sensitive values in tCell Agent events.
  • Type - string
  • Default - If customizing, set it to the same value for all agents within the same application.
  • Required - N

TCELL_AGENT_PASSWORD_HMAC_KEY

password_hmac_key

  • Description - Key to use for hashing password values for login events related to Account Takeover.
  • Type - string
  • Default - N

TCELL_AGENT_CACHE_DIR

N/A

  • Description - The absolute file path to the directory that holds the policy cache.
  • Type - string
  • Default

TCELL_AGENT_PROXY_URL

  • Description - The url of the proxy that you proxy your traffic through. It should include the protocol, host and port. The proxy port for the R7 Collector is 8037.
  • Required - N
  • Example - http://myr7collector:8037"

TCELL_AGENT_PROXY_USERNAME

  • Description - If basic authentication is enabled for the proxy, enter the username for authentication.
  • Required - N
  • Example - jsmith

TCELL_AGENT_PROXY_PASSWORD

  • Description - If basic authentication is enabled for the proxy, enter the password for authentication.
  • Required - N
  • Example - T3stP@ssword3

TCELL_AGENT_REVERSE_PROXY

reverse_proxy

  • Description - When true, agent assumes there is a reverse proxy forwarding traffic to the application.
  • Type - boolean
  • Default - true, for Apache and Nginx false.
  • Required - N

TCELL_AGENT_REVERSE_PROXY_IP_ADDRESS_HEADER

reverse_proxy_ip_address_header

  • Description - Header to check for a request's originating IP
  • Type - string
  • Default - X-Forwarded-For
  • Required - N
  • Example - X-Real-IP

TCELL_AGENT_MAX_HEADER_SIZE

max_csp_header_bytes

  • Description - The maximum size in bytes of a response header injected by the agent. If an agent-configured header exceeds this threshold, the header will not be set. Generally this affects Content-Security-Policy (CSP) related headers set by the agent.

  • Notes

    • .NET/.NET Core agents - Default header size 10240 bytes. Header cannot exceed maximum size of 32768 bytes.
    • Node.js agent - Header cannot exceed maximum size of 16384 bytes.
    • Python agent - Header cannot exceed maximum size of 16384 bytes.
    • Ruby agent - Header cannot exceed maximum size of 16384 bytes.
    • IIS Web Server - No maximum header size limit
    • Java agent - No maximum header size limit
    • nApache install - Default header size 10240 bytes; no maximum header size limit

TCELL_AGENT_MAX_ROUTES

max_routes

  • Description - Limits the maximum number of routes to detect and report to the tCell service. When running in a web server environment where the number of routes may be very large such as thousands or tens of thousands, it may be preferable to prevent the agent from using excessive resources identifying and transmitting route information to the service.\nIf not specified, defaults to 10000. Minimum value is 100.
  • Type - integer
  • Default - 10000
  • Required - N
  • Example - 1000

TCELL_AGENT_ENABLE_JS_AGENT_SRI

enable_js_agent_sri

  • Description - Enables Subresource Integrity (SRI) for JS Agent injection. If JS Agent is self-hosted (js_agent_url is set to a custom domain) while SRI is enabled, the custom js_agent_url value is ignored and the default js_agent_url value is used instead. To use a custom js_agent_url value, set enable_js_agent_sri to false.
  • Type - boolean
  • Required - N
  • Example - false
  • Default - true

TCELL_AGENT_JS_AGENT_API_URL

js_agent_api_base_url

  • Description - The URL prefix at which to send events from the injected JS agent
  • Type - string
  • Required - N
  • Default - https://us.agent.tcell.insight.rapid7.com/api/v1, https://us2.agent.tcell.insight.rapid7.com/api/v1, https://us3.agent.tcell.insight.rapid7.com/api/v1 https://eu.agent.tcell.insight.rapid7.com/api/v1, https://au.agent.tcell.insight.rapid7.com/api/v1

TCELL_AGENT_JS_AGENT_URL

js_agent_url

  • Description - The URL at which to retrieve the JS Agent. This value is ignored if enable_js_agent_sri is set to true.
  • Type - string
  • Default - https://us.jsagent.tcell.insight.rapid7.com/tcellagent.min.js

TCELL_AGENT_UPDATE_POLICY

fetch_policies_from_tcell

  • Description - When false, the agent does not update its policy.
  • Type -- boolean
  • Default - true

TCELL_AGENT_USE_NATIVE_CERTS

use_native_certs

  • Description - Causes the agent to use the system TLS certificates to validate connections to the tCell API endpoints.
  • Type - boolean
  • Required - N
  • Default - false
  • Example - true

TCELL_AGENT_SERVER_HEADER_OFF

(NGINX Only)

server_header_off

  • Description - When true, the agent removes any 'Server' header entries from responses to avoid leaking information.
  • Type - boolean
  • Default - N
  • Required - N
  • Example - false

TCELL_AGENT_INSPECT_MULTIPART_POSTS

(NGINX and Apache)

inspect_multipart_posts

  • Description - Enables the parsing and inspection of multipart posts for webserver agents. This is all the fields of POST requests with a multipart/form-data content type, excluding file uploads. The maximum added latency per request and maximum memory allocated per request can be specified with the multipart_parser_time_budget_ms and multipart_parser_space_budget_bytes config variables respectively.
  • Default - false
  • Required - N
  • Example - true

TCELL_AGENT_MULTIPART_PARSER_TIME_BUDGET_MS

(NGINX and Apache)

multipart_parser_time_budget_ms

  • Description - The maximum amount of time in milliseconds the parser will spend processing each new post request.
  • Default - 25
  • Required - N
  • Example - 10

TCELL_AGENT_MULTIPART_PARSER_SPACE_BUDGET_BYTES

(NGINX and Apache)

multipart_parser_space_budget_bytes

  • Description - The maximum number of bytes the multipart parser will allocate per request when parsing each request.
  • Default - 10000000
  • Required - N
  • Example - 6400

TCELL_AGENT_IIS_URL_REWRITE

(.NET Only)

iis_url_rewrite

  • Description - Set this to true, if running Application Request Routing (ARR).\nWith default agent behavior, the agent could interfere with requests containing a body that are intended to be routed to another server. When true, we work around the problem by re-writing the body to the request after reading it.
  • Type - boolean
  • Default - false
  • Required - N
  • Example - true

TCELL_AGENT_BLOCK_LOG4SHELL_ENABLED

(JVM Only)

block_log4shell_enabled

  • Description - If true, block all Log4J JNDI lookups.
  • Type - boolean
  • Default - true

TCELL_AGENT_LOG_FILE_ACCESS

(JVM Only)

log_file_access

  • Description - When true, the agent logs file access to two files in the configured log directory:

    • opened_for_read.csv\
    • opened_for_write.csv
  • Type - boolean

  • Default - false

  • Required - N

  • Example - "this is a local secret"

  • Notes - Should only be used for debugging as application performance may suffer.

TCELL_AGENT_PACKAGE_TRACKER_INTERVAL_MS

(JVM Only)

N/A

  • Description - How often the Package Tracker should check for newly seen code sources, in milliseconds.
  • Type - Number
  • Default - 30000

TCELL_AGENT_TOMCAT_SPECIFIC_REDIRECTS

(JVM Only)

tomcat_specific_redirects

  • Description - When true, the agent registers additional redirect instrumentation that is specific to Tomcat. Usually this is not necessary, even when using Tomcat.
  • Type - boolean
  • Default - false

Deprecated/Removed Environment Variables and Equivalents

DeprecatedEquivalent
TCELL_PASSWORD_HMAC_KEYTCELL_AGENT_PASSWORD_HMAC_KEY
TCELL_MAX_HTTP_HEADER_SIZETCELL_AGENT_MAX_HEADER_SIZE
TCELL_HMAC_KEYTCELL_AGENT_HMAC_KEY
TCELL_AGENT_INSPECT_JSON_POSTSTCELL_AGENT_ENABLE_JSON_BODY_INSPECTION
TCELL_AGENT_LOG_FILE_SIZETCELL_AGENT_LOG_FILE_MAX_SIZE_MB
TCELL_API_URLTCELL_AGENT_API_URL

Config File Properties Without Environment Variables

session_identifiers

  • Description - 'Cookie', 'Header', or 'QueryString' parameters that hold a session value
  • Type - SessionIdentifier Array SessionIdentifier: { "type": "?", "name": "?" }
  • Default -
  • Required - N
  • Example - [{"type":"cookie","name":"mycustomsesscookie"}]

do_not_instrument

(JVM Only)

  • Description - A list of fully qualified Java class names to exclude from instrumentation.
  • Type - string array
  • Default - N
  • Required - N
  • Example - [\"java.lang.String\", \"java.util.Map\"]

enabled_instrumentations

(Ruby and Python Only)

As of Python 1.7.2, you can disable Local File and OS Commands implementations. For more information, see Disable the Local File and OS Commands feature.

  • Type - json object (hash)
  • Description - Enable/Disable specific library instrumentation. This is meant to avoid conflicts when using tcell-hooks.
  • Default - NULL
  • Required - N
  • Example - {"enabled_instrumentations": { "doorkeeper":true, "devise":true, "authlogic":true}}

Sub Option - doorkeeper

  • Type - boolean
  • Description - Enable/Disable doorkeeper library instrumentation.
  • Default - true
  • Required - N
  • Example - false

Sub Option - devise

  • Type - boolean
  • Description - Enable/Disable devise library instrumentation.
  • Default - true
  • Required - N
  • Example - false

Sub Option - authlogic

  • Type - boolean
  • Description - Enable/Disable authlogic library instrumentation.
  • Default - true
  • Required - N
  • Example - false

Sub Option - django_auth

  • Type - boolean
  • Description - Enable/Disable django_auth library instrumentation.
  • Default - true
  • Required - N
  • Example - false