manhole 1.0.0

Options

manhole.install(
    verbose=True,
    verbose_destination=2,
    patch_fork=True,
    activate_on=None,
    oneshot_on=None,
    sigmask=manhole.ALL_SIGNALS,
    socket_path=None,
    reinstall_delay=0.5,
    locals=None
)

• verbose - Set it to False to squelch the logging.

• verbose_destination - Destination for verbose messages. Set it to a file descriptor or handle. Default is unbuffered stderr (stderr 2 file descriptor).

• patch_fork - Set it to False if you don’t want your os.fork and os.forkpy monkeypatched

• activate_on - Set to "USR1", "USR2" or some other signal name, or a number if you want the Manhole thread to start when this signal is sent. This is desireable in case you don’t want the thread active all the time.

• oneshot_on - Set to "USR1", "USR2" or some other signal name, or a number if you want the Manhole to listen for connection in the signal handler. This is desireable in case you don’t want threads at all.

• sigmask - Will set the signal mask to the given list (using signalfd.sigprocmask). No action is done if signalfd is not importable. NOTE: This is done so that the Manhole thread doesn’t steal any signals; Normally that is fine cause Python will force all the signal handling to be run in the main thread but signalfd doesn’t.

• socket_path - Use a specifc path for the unix domain socket (instead of /tmp/manhole-<pid>). This disables patch_fork as children cannot resuse the same path.

• reinstall_delay - Delay the unix domain socket creation reinstall_delay seconds. This alleviates cleanup failures when using fork+exec patterns.

• locals - Names to add to manhole interactive shell locals.

• daemon_connection - The connection thread is daemonic (dies on app exit). Default: False.

• redirect_stderr - Redirect output from stderr to manhole console. Default: True.

What happens when you actually connect to the socket

1. Credentials are checked (if it’s same user or root)

2. sys.__std*__/sys.std* are be redirected to the UDS

3. Stacktraces for each thread are written to the UDS

4. REPL is started so you can fiddle with the process

SIGTERM and socket cleanup

By default Python doesn’t call the atexit callbacks with the default SIGTERM handling. This makes manhole leave stray socket files around. If this is undesirable you should install a custom SIGTERM handler so atexit is properly invoked.

Example:

import signal
import sys

def handle_sigterm(signo, frame):
    sys.exit(128 + signo)  # this will raise SystemExit and cause atexit to be called

signal.signal(signal.SIGTERM, handle_sigterm)

1.0.0 (2014-10-13)

• Added socket_path install option (contributed by Nir Soffer).

• Added reinstall_delay install option.

• Added locals install option (contributed by Nir Soffer).

• Added redirect_stderr install option (contributed by Nir Soffer).

• Lots of internals cleanup (contributed by Nir Soffer).

0.6.2 (2014-04-28)

• Fix OS X regression.

0.6.1 (2014-04-28)

• Support for OS X (contributed by Saulius Menkevičius).