Server Agent Options

• Environment Variables and Config File Properties
• Deprecated/Removed Environment Variables and Equivalents
• Config File Properties Without Environment Variables
• Configuration Conventions

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.

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

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:

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://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
• 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

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

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"

Proxy Username

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

Proxy Password

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