Python

Supported Technologies

Confirm that the tCell agent supports your Python configuration, as shown below:

VersionApp ServersWeb FrameworksOSAuthentication Frameworks
2.7.10+
3.4*
uWSGI 2.0.x
Gunicorn 19.10.x, 20.0.x
Flask 0.8.x+, 1.x
Django 1.7+, 2.x, 3.x*
CentOS 6+
Ubuntu 14+
Debian 8+
Alpine 3.7.1+
Not applicable

CentOS 6.0 End of Life Announcement

As of December 31, 2021, Rapid7 will End-of-Life (EOL) tCell Agents on CentOS 6.0. The Agent documentation and support requirements will reflect this change at the same time. See the CentOS end-of-life announcement to see if you are affected and what actions you can take.

Python Support Legend

* - Login support only works with Django

Prerequisites

  • tCell account
  • Application created with tCell (Admin > Applications)
  • Outbound HTTPS connections to the tCell cloud allowed What IPs do tCell agents connect to?
  • Agent and config file downloads

To download the agent and config file:

  1. Click on "tCell Admin" in top nav bar.
  2. Click "Download Agent".
  3. Select "Python" agent.
  4. Select "Create New API Key" (default).
  5. Click "Download Config File" to download the agent's config file. The config file is pre-populated with the application and API key information.

Installation

  1. Install the tcell agent.
    tCell agent install
    1
    pip install tcell_agent
  2. Add the tcell_agent.config to your tcell directory, generally /var/www/html/tcell.
  3. Update your wsgi file to contain the following lines, substituting the /var/www/html/tcell as needed:
    wsgi file update
    1
    os.environ['TCELL_AGENT_CONFIG'] = '/var/www/html/tcell/tcell_agent.config'
    2
    os.environ['TCELL_AGENT_HOME'] = '/var/www/html/tcell'
    3
    import tcell_agent
    4
    tcell_agent.init()

Here is a complete example using wsgi: example_wsgi.py

Update the Agent

To update the Python agent to the newest version, run:

tCell agent update
1
pip install --upgrade tcell_agent

With this command, pip automatically updates the agent to the latest release in the Python Package Index.

Verification

To verify that data is being sent to tCell go to your tCell console and ensure that the number of app 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:

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

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

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