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
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
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
Remove Server HeaderNGINXTCELL_AGENT_SERVER_HEADER_OFFserver_header_off
IIS URL Rewrite for ARR.NETTCELL_AGENT_IIS_URL_REWRITEiis_url_rewrite
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
Session IdentifiersAllN/Asession_identifiers
Do Not InstrumentJVMN/Ado_not_instrument
Enabled InstrumentationsRuby
Python
N/Aenabled_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.

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

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_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

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 - 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