manhole

manhole is a Python library, not a direct shell command. Its usage involves integrating it into your Python application. The primary entry point for activation is typically:

from manhole import install
install([parameters])

Once installed and the application is running, you connect to it from a shell, usually via nc (netcat) to the configured socket:

nc -U /path/to/manhole.sock (for Unix socket)
nc hostname port (for TCP socket)

socket_path
    The path for the Unix domain socket. If not provided, a temporary socket is created.

bind_address
    A (host, port) tuple for binding a TCP socket. Useful for network access.

activate_on
    A signal number (e.g., signal.SIGUSR1) that, when received by the process, activates the manhole if it's not already active.

daemonize
    Boolean. If True, the manhole listener will fork into a daemon process, detaching from the main application thread.

log_level
    Sets the logging level for manhole's internal operations.

locals
    A dictionary of variables to expose in the manhole's top-level scope when connected.

The manhole library provides an interactive console or 'manhole' into a running Python process. It allows developers to connect to a live application, inspect its state, debug issues, and even execute arbitrary Python code within the application's context. This is particularly useful for long-running services or daemon processes where traditional debugging tools like pdb might be impractical or require stopping the service. manhole typically exposes an entry point via a Unix domain socket or a TCP socket, allowing remote connection using tools like nc (netcat) or ssh (when using TCP over an SSH tunnel). It's designed to be lightweight and minimize impact on the application's performance, providing a powerful way to troubleshoot and monitor production systems without restarting them.

Security Risk: Exposing a manhole can be a significant security risk as it allows arbitrary code execution within the application's context. It should be used with extreme caution, especially in production environments, and preferably protected by strong access controls (e.g., restricted file permissions for Unix sockets, firewall rules, or SSH tunneling for TCP sockets).
Performance Impact: While designed to be lightweight, continuous or heavy interaction with the manhole can impact the application's performance.
Not a Standalone Command: manhole is a Python library to be integrated into an application, not a general-purpose shell command executed directly from the terminal like ls or grep.

To use manhole, first install it via pip: pip install manhole. Then, within your Python application's code, typically at startup:

import signal
from manhole import install

install(activate_on=signal.SIGUSR1, socket_path='/tmp/my_app_manhole.sock')

To connect from your shell:

kill -USR1
nc -U /tmp/my_app_manhole.sock
This will give you an interactive Python prompt within your running application.

manhole supports connections via Unix domain sockets (local file system path) and TCP sockets (network address and port). Unix sockets are generally preferred for security and performance when connecting from the same host. TCP sockets offer remote access but require careful security considerations (e.g., firewalls, SSH tunnels).

manhole emerged from the need to debug and inspect long-running Python applications (like web servers, background workers, or daemons) without interrupting their operation. Traditional debugging tools often require stopping or restarting the process. The library aims to provide a 'backdoor' for diagnostics, inspired by similar concepts in other languages/systems. Its development reflects the increasing complexity and uptime requirements of modern Python services, where real-time introspection is valuable.

pdb(1), strace(1), gdb(1), nc(1)