Server Agent Options
- Environment Variables and Config File Properties
- Deprecated/Removed Environment Variables and Equivalents
- Config File Properties Without Environment Variables
- Configuration Conventions
Name | Supported Agents | Environment Variable | Config File Property | |
---|---|---|---|---|
App ID | All | TCELL_AGENT_APP_ID | app_id | |
API Key | All | TCELL_AGENT_API_KEY | api_key | |
API URL Prefix | All | TCELL_AGENT_API_URL | tcell_api_url | |
Input URL Prefix | All | TCELL_AGENT_INPUT_URL | tcell_input_url | |
Enable Agent | All | TCELL_AGENT_ENABLED | enabled | |
Agent Home Directory | All | TCELL_AGENT_HOME | N/A | |
Register Instrumentation | All | TCELL_AGENT_INSTRUMENT | N/A | |
Log Directory | All | TCELL_AGENT_LOG_DIR | log_dir | |
Config File Path | All | TCELL_AGENT_CONFIG | N/A | |
Enable JSON Body Inspection | All | TCELL_AGENT_ENABLE_JSON_BODY_INSPECTION | inspect_json_posts | |
Allow Payloads | All | TCELL_AGENT_ALLOW_PAYLOADS | allow_payloads | |
Allow Payload Logging | All | TCELL_AGENT_ALLOW_LOG_PAYLOADS | log_payloads | |
Host Identifier | All | TCELL_AGENT_HOST_IDENTIFIER | host_identifier | |
Enable Logging | All | TCELL_AGENT_LOG_ENABLED | logging_options.enabled | |
Log Filename | All | TCELL_AGENT_LOG_FILENAME | logging_options.filename | |
Logging Level | All | TCELL_AGENT_LOG_LEVEL | logging_options.level | |
Log Destination Type | All | TCELL_AGENT_LOG_DESTINATION | logging_options.destination | |
Max Log File Size | All | TCELL_AGENT_LOG_FILE_MAX_SIZE_MB | logging_options.max_file_size_mb | |
HMAC Key | All | TCELL_AGENT_HMAC_KEY | hmac_key | |
Password HMAC Key | All | TCELL_AGENT_PASSWORD_HMAC_KEY | password_hmac_key | |
Cache Directory | All | TCELL_AGENT_CACHE_DIR | N/A | |
Enable Reverse Proxy | All | TCELL_AGENT_REVERSE_PROXY | reverse_proxy | |
Reverse Proxy IP Address Header | All | TCELL_AGENT_REVERSE_PROXY_IP_ADDRESS_HEADER | reverse_proxy_ip_address_header | |
Max Header Size | All | TCELL_AGENT_MAX_HEADER_SIZE | max_csp_header_bytes | |
Max Number of Routes | All | TCELL_AGENT_MAX_ROUTES | max_routes | |
JS Agent API Base URL | All | TCELL_AGENT_JS_AGENT_API_URL | js_agent_api_base_url | |
JS Agent URL | All | TCELL_AGENT_JS_AGENT_URL | js_agent_url | |
Fetch Policies From tCell | All | TCELL_AGENT_UPDATE_POLICY | fetch_policies_from_tcell | |
Remove Server Header | NGINX | TCELL_AGENT_SERVER_HEADER_OFF | server_header_off | |
IIS URL Rewrite for ARR | .NET | TCELL_AGENT_IIS_URL_REWRITE | iis_url_rewrite | |
Log File Access | JVM | TCELL_AGENT_LOG_FILE_ACCESS | log_file_access | |
Package Tracker Interval | JVM | TCELL_AGENT_PACKAGE_TRACKER_INTERVAL_MS | N/A | |
Tomcat-specific Redirects | JVM | TCELL_AGENT_TOMCAT_SPECIFIC_REDIRECTS | tomcat_specific_redirects | |
Session Identifiers | All | N/A | session_identifiers | |
Do Not Instrument | JVM | N/A | do_not_instrument | |
Enabled Instrumentations | Ruby Python | N/A | enabled_instrumentations |
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.
Agent | Minimum version |
---|---|
Apache | 3.1.0 |
IIS | 2.0.0 |
Java | 1.13.0 |
.NET | 2.3.2 |
.NET Core | 2.3.2 |
NGINX | 3.1.0 |
Node.js | 2.2.0 |
Python | 1.7.0 |
Ruby | 2.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
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 thetcell_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_REVERSE_PROXY
reverse_proxy
- Description - When true, agent assumes there is a reverse proxy forwarding traffic to the application.
- Type - boolean
- Default -
true
- 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_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://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
- 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_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_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_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 - NExample - "this is a local secret"
NotesShould 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
Deprecated | Equivalent |
---|---|
TCELL_PASSWORD_HMAC_KEY | TCELL_AGENT_PASSWORD_HMAC_KEY |
TCELL_MAX_HTTP_HEADER_SIZE | TCELL_AGENT_MAX_HEADER_SIZE |
TCELL_HMAC_KEY | TCELL_AGENT_HMAC_KEY |
TCELL_AGENT_INSPECT_JSON_POSTS | TCELL_AGENT_ENABLE_JSON_BODY_INSPECTION |
TCELL_AGENT_LOG_FILE_SIZE | TCELL_AGENT_LOG_FILE_MAX_SIZE_MB |
TCELL_API_URL | TCELL_AGENT_API_URL |
Config File Properties Without Environment Variables
session_identifiers
- Description - 'Cookie', 'Header', or 'QueryString' parameters that hold a session value
- Type - SessionIdentifer 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)
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