Compatibility — servers, task queues, client libraries¶

What tethered enforces under the servers, task queues and client libraries people deploy, what needs a particular configuration, what tethered refuses at start-up, and what it does not see at all. Everything on this page was measured: each row names the container suite in tests_containers/ that asserts it, and the versions it was measured with. The cookbook has the configuration for each server; the security model has the limits as part of the threat model.

How to read this page¶

What was measured. Each suite builds a wheel of tethered from the source tree, installs it into the official python:X.Y-slim Docker image the way a user installs it, starts the real server or library, and asks it to reach four destinations: a host the policy allows (allowed.test:9001), a forbidden name, a forbidden raw address, and the allowed name on a port the rule does not cover. The destinations count every connection and datagram that arrives. "Refused" on this page means that nothing arrived, not only that the application saw an exception. Every suite runs on Python 3.11, 3.12, 3.13, 3.14 and 3.15, on Linux x86-64 with glibc.

The results.

The versions. Every table names the release it was measured with. A row holds for that release; where a behaviour depends on the release (uvicorn's does), the row says so. To run a suite yourself: uv run python tests_containers/run.py --suite uvicorn --python 3.13.

Measured once. A few statements come from single runs made while the suites were written and are not asserted by a test. They are marked "measured once".

What "not seen" means¶

tethered is an audit hook. CPython raises an audit event when Python code calls into the socket module (socket.getaddrinfo, socket.connect, socket.sendto) or launches a process (subprocess.Popen, os.exec*), and tethered's hook decides at that event. The hook is called by the interpreter. It cannot add an event where the interpreter raises none.

A library that resolves names and opens connections inside its own compiled code never calls Python's socket module. libcurl, libpq, the gRPC core, librdkafka and the libuv loop inside uvloop are examples. No event is raised, the hook is not called, and tethered has nothing to decide. For such a library, under any policy:

• the forbidden name is looked up, and the forbidden address and port are reached;
• no exception is raised and no log line is written;
• locked=True and fail_closed=True change nothing, because they act on events that never come;
• log_only=True reports nothing, so a log-only rollout does not reveal these connections either;
• on_blocked is not called and a scope() does not apply.

No setting of tethered changes this, and no later version of tethered can, for as long as it works through audit events. Where tethered knows of a common case it refuses to run instead of running unenforced: it keeps uvloop and pycares from being imported under a policy (below). For everything else on this page that is "not seen", the remedy is a pure-Python driver where one exists (the tables name it), or a control below Python: a network policy, a firewall rule, seccomp.

Event loops and green threads¶

Where a process still ends on uvloop. The refusal works where a policy that enforces is active in the interpreter that imports uvloop. It does not cover:

• A log_only policy. It refuses nothing, the import of uvloop included. The server runs on uvloop, and nothing that goes through the loop is reported: the list of what would be blocked stays empty for every asynchronous call. tethered logs one warning (tethered: uvloop is loaded in this process.). Code that uses the socket module itself is still reported. Run a log-only rollout of an asyncio application with the loop named (uvicorn --loop asyncio). Pinned by uvicorn, fastapi, gunicorn_uvicorn, hypercorn, granian, sanic, aiohttp.
• A scope() with no activate() under it. A scope alone does not keep uvloop out. On uvloop, asyncio.open_connection and loop.create_connection inside the scope reach refused destinations; loop.sock_connect, asyncio.to_thread and blocking code are refused by the scope. One warning is logged. With --loop asyncio everything is refused. Pinned by uvicorn.
• An interpreter outside a lock. Under mod_wsgi, an application whose interpreter existed before another application locked a policy is refused every socket, but it holds no policy of its own, so it can import uvloop, and a connection on a uvloop loop then arrives at a forbidden destination. Pinned by modwsgi.
• A server that swallows the refusal. uvicorn's default --lifespan auto takes any exception from a hand-written ASGI lifespan handler for "this application does not support lifespan". An application that activates there, after uvicorn has loaded uvloop, is served on uvloop with no policy at all. tethered logs the refusal as an error before it raises it, and that one line is all that is left. FastAPI and Starlette report a failed start-up and the server exits. Pinned by uvicorn.

Web servers¶

uvicorn¶

Measured with uvloop 0.23.0 installed, as it is with uvicorn[standard], and an application that calls activate() when it is imported. Suites: uvicorn (uvicorn 0.54.0) and uvicorn_legacy (uvicorn 0.46.0).

On the standard loop the uvicorn suite covers every way out of a coroutine listed under Event loops, a response of 20 MB under a plain and a locked policy, Python children and external tools launched from a handler, and external_subprocess_policy="block".

Which releases import the application first (measured once, on Python 3.13, not asserted by a suite): uvicorn 0.47.0 is the first release whose uvicorn main:app imports the application before it chooses the loop. From 0.50.0 the worker and reload processes choose the loop first again, which is the "never serves" row; 0.49.0 with --workers 2 worked. Do not build on the order: name the loop.

FastAPI¶

Measured with fastapi 0.143.0 installed as fastapi[standard] (fastapi-cli 0.0.32, starlette 1.7.0, httpx 0.28.1 on anyio 4.15.1, uvloop 0.23.0). Suites: fastapi (uvicorn 0.54.0) and uvicorn_legacy (uvicorn 0.46.0). fastapi run has no option for the event loop, and UVICORN_LOOP does not reach it.

Of the compiled modules a fastapi[standard] installation brings, uvloop is the only one that imports the C library's connect and getaddrinfo itself (a test of the fastapi suite).

gunicorn¶

Measured with gunicorn 26.2.0.

For gunicorn's uvicorn worker the release that changed the order is older than for the uvicorn command (measured once, not asserted by a suite): with uvicorn 0.35.0 the worker set the loop up first, and gunicorn exited with "Worker failed to boot" unless --preload was given; from 0.36.0 it imports the application first.

The gevent worker.

• Hazard: a refused lookup sometimes never returns. tethered logs a refusal in the thread in which the audit event is raised, and for a lookup under gevent's default resolver that is one of gevent's pool threads. After monkey-patching, the lock of a logging handler is gevent's, and when several pool threads log at the same moment one of them is now and then never woken. Its lookup never returns, the request hangs, and a worker that is told to restart or to stop waits for that request until gunicorn's graceful timeout (30 seconds by default). Measured on Python 3.13 with gevent 26.9.0: a stuck request in 8 of 30 stress runs of a gunicorn gevent worker (4 of 30 with --preload, 0 of 60 without tethered), and, without gunicorn, a greenlet that never came back in 9 and 15 of 120 new processes that each made 40 refused lookups from 8 greenlets. It is not specific to tethered: an audit hook that logs and raises did the same in 7 of 120 processes, one that only raises in none. Allowed lookups and connections were never affected (0 of 360). How often it happens in a long-lived worker was not established. One mitigation was measured: with the tethered logger set to ERROR, so that tethered does not log its warning for a refusal, 0 of 180 processes had a stuck greenlet. That is a measurement, not a guarantee, it removes tethered's own line about each refusal (the exception is still raised), and anything else that logs from the resolver's threads can trigger the same.
• gevent's hub prints a traceback for every refused lookup. Adding tethered.EgressBlocked to the hub's NOT_ERROR silences it.
• Process launches go through gevent's own subprocess, which forks and calls os.exec* from Python. tethered sees os.exec* events inside the forked child, one for each PATH directory that is tried. A child started with sys.executable inherits the policy, with an explicit environment that lacks the policy variable too. What changes is where tethered's log lines go: the forked child writes them to its stderr, which is the pipe the application captures. A warning about an external launch (one per PATH directory tried) is therefore in the captured stderr of the tool, or ahead of its output with stderr=subprocess.STDOUT, and in the server log only when stderr is inherited. Under "block" with captured stderr the refusal is logged nowhere; the SubprocessBlocked exception is all there is.
• gunicorn 26.2.0 has no eventlet worker.

hypercorn and Quart¶

Measured with hypercorn 0.18.0, trio 0.34.0, uvloop 0.23.0; Quart 0.23.1 (0.22.0 on Python 3.11 and 3.12). hypercorn's master never imports the application; each worker is a new Python process that does.

granian¶

Measured with granian 2.8.4, rloop 0.5.0, uvloop 0.23.0. granian's main process never imports the application; each worker does, after granian has created the worker's event loop. --loop auto (the default) takes rloop if it can be imported, then uvloop, then asyncio's own. And granian imports every loop package it finds as soon as granian itself is imported, whichever --loop was asked for.

sanic¶

Measured with sanic 25.12.1 and uvloop 0.23.0, which sanic installs as a dependency. import sanic itself imports uvloop.

aiohttp¶

Measured with aiohttp 3.14.4, aiodns 4.0.4, pycares 5.1.0, gunicorn 26.2.0.

daphne and Twisted¶

Measured with daphne 4.2.3 and Twisted 26.4.0. daphne is one process and runs Twisted's reactor on a standard asyncio event loop.

A refusal is raised inside the reactor, and Twisted expects OSError and socket.gaierror there, not a RuntimeError:

• A refused connection attempt (reactor.connectTCP, TCP4ClientEndpoint) reaches the caller as Twisted's own TimeoutError, when the attempt's timeout is over: 30 seconds unless the caller says otherwise.
• A refused lookup is never reported: the Deferred of HostnameEndpoint.connect, twisted.web.client.Agent.request and reactor.resolve never fires.
• A refused datagram (transport.write(data, addr)) and a refused reactor.spawnProcess raise to the caller.
• tethered's own warning is in the log in every case. Twisted's traceback of the refusal is only there with daphne -v 2.
• reactor.spawnProcess with its default, empty environment is an os.posix_spawn whose environment lacks the policy variable: under a plain policy a Python child is launched with a warning and runs without the policy; under a lock or "block" it is refused.

tornado¶

Measured with tornado 6.5.10 and pycurl 7.48.0.

uWSGI¶

Measured with uWSGI 2.0.31, which embeds Python in its own binary.

sys.executable is the uwsgi binary. tethered recognizes a Python child by sys.executable, and under uWSGI that is not an interpreter: subprocess.run([sys.executable, "script.py"]) starts uWSGI, not Python ("unable to load configuration from ..."). tethered notices, logs a warning when the policy is activated (tethered: sys.executable is /usr/local/bin/uwsgi, the program that embeds Python here, not a Python interpreter. ...), and counts every launch as external: warned about, and refused under "block", with the reason in the log line. That includes a launch of the real interpreter (["/usr/local/bin/python", "script.py"]), although that child does inherit the policy; under a lock it is given the policy variable when its explicit environment lacks it, like any program started through subprocess. --py-sys-executable /path/to/python puts it right, with a virtualenv too: the warning is gone and a child started with sys.executable is a Python child that inherits.

Mounted applications. uWSGI loads the first application in the main interpreter and each later one in a new interpreter, unless --single-interpreter is given. With the same locked policy in both, the second joins the lock and its activate() is a no-op. A first application that does not lock, followed by one that does, is outside the lock and has no network at all, loopback included. After a reload the same deployment behaves differently: the main interpreter inherits the lock, and the first application is held to the second's policy. With different locked policies the second application gets TetheredLocked; if it lets the exception out, uWSGI does not start. Unlocked policies in several interpreters share the policy variable, as under mod_wsgi. One policy for all mounted applications, locked by the first, is the arrangement that holds.

uWSGI's own behaviour that matters here: SIGTERM reloads unless --die-on-term is given, and an uncaught exception closes the connection without a response.

waitress¶

Measured with waitress 3.0.2: one process and a pool of threads.

mod_wsgi¶

Measured with mod_wsgi 6.1.0 and Apache 2.4 as Debian packages it (2.4.68 when measured). mod_wsgi runs each application group in an interpreter of its own, and a locked policy is one per process, so what counts is the order in which the interpreters of a process come into being. The cookbook has the configurations.

On Python 3.12, WSGIPerInterpreterGIL On crashed the daemon process as soon as a second group loaded an application, with and without tethered (measured once, 32 of 32 starts); the suite does not run that combination.

Flask and Django¶

Measured with Flask 3.1.3 (Werkzeug 3.1.9) and Django 6.1.2 (5.2.18 on Python 3.11), under gunicorn 26.2.0, with requests 2.34.2.

What holds under every server¶

An uncaught EgressBlocked does not take a worker down. The request fails the way any uncaught exception does on that server, and the worker keeps serving: a 500 under uvicorn, hypercorn, granian, sanic, aiohttp, daphne, tornado's own server, gunicorn's sync, gthread and gevent workers, waitress, mod_wsgi, Flask and Django; no response under gunicorn's tornado worker (the connection stays open) and under uWSGI (the connection is closed). Those two servers do the same with any uncaught exception when tethered is not installed.

Process launches from a handler, under a locked policy with the default external_subprocess_policy="warn" (suites gunicorn, modwsgi, and each server suite for the first and the last row):

external_subprocess_policy="block" refuses what libraries launch, too. On Linux, ctypes.util.find_library() runs ldconfig, and platform.platform() runs uname. Under "block":

• ctypes.util.find_library() raises SubprocessBlocked (suite clients), and with it the import of trio (suite hypercorn). asyncssh and psycopg 3 in its Python implementation make the same call while they are imported. Import such libraries before activate().
• celery worker does not start: its banner calls platform.platform(), which catches only OSError (suite celery). Call platform.platform() once before activate(); it caches the answer.

Under the default "warn" these launches are logged as external launches and carried out, under a locked policy as well.

A locked policy survives whatever re-executes the server. The new process image inherits the locked policy from its environment before the application is imported, and a locked policy cannot be changed without its token. So an application that asks for a different locked policy after a re-execution gets TetheredLocked:

Not affected: uWSGI with --lazy-apps, gunicorn without --preload, mod_wsgi in daemon mode (a touched script restarts the process), and unlocked policies. The same policy asked for again is a no-op everywhere. To change a locked policy, stop the server and start it.

Task queues and process pools¶

In every system below, each process that runs task code held the policy, plain and locked, including processes started later, and a Python child of a task inherited it. The suites use Redis 8 on loopback as broker and result store.

The fork server. A worker of the forkserver start method is a copy of the fork server process, not of the process that asks for it. A fork server that was started before activate() holds no policy, and neither does any worker it produces from then on, also after activate(locked=True). Asking it for a worker goes over a socket and raises no launch event, so tethered can neither refuse nor complete it. forkserver is the default start method on Linux from Python 3.14. activate() logs one warning when it finds a fork server already running. Call activate() before the first pool or process is started; a fork server that starts under the policy passes it on.

A broker that is addressed by name has to be in the allow list. Otherwise the Celery worker ends at start-up with EgressBlocked for the broker's address (suite celery). kombu retries connection errors; EgressBlocked is not one, so the mistake is not retried for ever.

Celery's gevent pool and a lookup that never returns. The hazard of gevent's thread-pool resolver, described under gunicorn, is there with --pool gevent too: when refused lookups overlap, the task of one of them now and then never finishes. The worker goes on running other tasks. A warm shutdown (SIGTERM) waits for running tasks without a time limit, so with such a task it does not end. Measured once, on Python 3.12 and 3.13 with Celery 5.6.3 and gevent 26.9.0, not asserted by a suite: under eight refused lookups at a time a task was stuck after 152 and after 328 lookups, the worker was still running two minutes after SIGTERM, and it ended at once when it was then sent SIGQUIT, Celery's cold shutdown.

What an operator sees for a refused task. Nothing arrived in any of these, and in no system did the workers die.

Scopes¶

A tethered.scope() around the work of one request or one task, in a process whose policy allows more than the scope does. Measured with gunicorn 26.2.0, uvicorn 0.54.0 on the standard loop, gevent 26.9.0, Celery 5.6.3 and eventlet 0.41.2.

What a scope does not reach:

• Another thread. A thread started inside the block, and work handed to loop.run_in_executor, run without the scope and reach what it refuses; the policy of the process still applies to them. asyncio.to_thread copies the context and stays inside the scope. Under gevent a "thread" is a greenlet, and it starts without the scope in the same way. Suites: gunicorn, uvicorn, gunicorn_gevent.
• A name lookup made in a pool thread. asyncio's loop and gevent's default resolver call getaddrinfo in a thread of a pool, which does not carry the scope. The DNS query for a name the scope refuses therefore leaves the process; a connection to that name is refused by the scope. A blocking lookup in the thread that entered the scope is refused before any query is sent. Suites: uvicorn, gunicorn_gevent.

Scopes were not measured under the other servers and task queues of this page.

Client libraries¶

Each library was asked for the four destinations under the policy allow=["allowed.test:9001"], and, as a control, with no tethered and an audit hook that records what events the library raises. The table is the one the clients suite prints at the end of a run; this copy is from a run on Python 3.13. clients_niquests measures niquests in the same way. Every row is the same under a locked policy as under a plain one.

Of the 70 arrangements of the clients suite, 47 are enforced, 13 are not seen, 4 are partly enforced, and in 6 an allowed host is refused. The two niquests arrangements are one of each of the first and the last kind.

The column "A refused name reaches the caller as" says what the code that called the library gets when the forbidden name is refused.

HTTP and WebSocket clients¶

PostgreSQL¶

MySQL¶

SQL Server and Oracle¶

Redis, MongoDB, memcached¶

Messaging and RPC¶

Cloud SDKs¶

Sockets, standard-library protocol clients, SSH¶

A resolver of the library's own, then a Python socket¶

Other runtimes¶

Notes on the table¶

Refusals at the connection can arrive inside an ExceptionGroup. The last column is about a refused name, which is refused at the lookup. httpx.AsyncClient, anyio.connect_tcp and trio.open_tcp_stream deliver a refusal at the connection (a port rule, or a raw address) inside an ExceptionGroup, which except tethered.EgressBlocked does not catch. Use except* (the cookbook).

What makes a library that resolves names itself work. Each of these was measured:

• aiohttp: call activate() before aiohttp is imported, or pass aiohttp.TCPConnector(resolver=aiohttp.ThreadedResolver()), or uninstall aiodns.
• eventlet: EVENTLET_NO_GREENDNS=yes.
• gevent: its default resolver, not ares.
• niquests: no resolver= argument.
• Any of them: one lookup of the name through the standard resolver by the application before the library is used, which gives tethered the name. The suite calls _socket.getaddrinfo(host, port) or _socket.gethostbyname(host), the C functions behind the socket module's, because gevent and eventlet replace socket.getaddrinfo with their own resolver. Or a rule for the address itself; the library's own resolver then still sends every name it is asked for to the name server.

The first time a connection is refused to an address that tethered has no name for, under a policy with hostname rules, tethered logs one line that says where the name may have gone (tethered: no hostname is known for the refused address ...). It is said once per process.

pycares is kept from loading. With a policy active that is not log_only, import pycares raises ImportError, and so does import aiodns. aiohttp then uses ThreadedResolver. A pycares that was imported before activate() is left alone, and activate() is not refused: what it resolves is refused at the connection, so nothing gets out unnoticed, with one exception. c-ares sends its DNS queries in C: a query to a name server at a forbidden address is sent (pinned by clients), where the same query by dnspython is refused at socket.sendto. Under a log_only policy pycares loads, and aiohttp with aiodns then reports the allowed host as blocked, by its address.

Loaded is not used. Whether a C library's networking is in play cannot be read from what is imported: _awscrt is loaded by every botocore import when awscrt is installed, although boto3 keeps using urllib3; grpc._cython.cygrpc is loaded by google-cloud-storage, which makes its requests with requests; psycopg2._psycopg is loaded by eventlet.monkey_patch().

Not in the table: psycopg 3's c implementation (the same code as binary, built against the system's libpq); boto3's CRT transfer manager (it could not be pointed at the test destinations; its transport is the awscrt row); gevent's dnspython resolver (with gevent 26.9.0 and dnspython 2.9.0 it resolves nothing, with or without tethered). On Python 3.15 confluent-kafka and the C extension of mysql-connector-python had no wheel when this was measured, so those two rows are from Python 3.11 to 3.14.

Installing, upgrading and removing tethered¶

What tethered puts on disk is what its wheel holds: the tethered/ package with the compiled extension, tethered.pth beside it, and the .dist-info directory. At run time it writes no file. While a policy is active it keeps _TETHERED_CHILD_POLICY in the environment of the process, where every child program finds the allow list, and deactivate() removes it. tethered.pth is read by every interpreter that starts in the environment, and it imports tethered only when that variable is set.

The rows below are measured once, with pip 26.2.1 and uv 0.13.0 on Python 3.13, on Linux (the image of a suite; python:3.13-slim for uv) and on Windows 11. No suite asserts them.

Install, upgrade and remove tethered from outside the processes that hold a locked policy: a deployment step or a shell, not a child of the application. The locked-mode guard on tethered.pth is described in the subprocess page; it refuses the file by its name and directory, however the installer names that directory, and the same file where uv keeps it in its cache. Windows does not delete a loaded extension module for any installer, so the ~ethered directory is to be expected whenever tethered is upgraded while a process has it imported.

What was not tested¶

• Installers. Anything but pip 26.2.1 and uv 0.13.0 on Python 3.13, and of uv only the arrangements above. conda, poetry and pipx were not run.
• Platforms. Windows and macOS servers, musl (Alpine), ARM, and free-threaded builds of Python. Everything here ran on Linux x86-64 with glibc. The unit tests in tests/ run on Windows and Linux; they do not start servers.
• The network itself. The destinations are on the loopback interface of a container without a network. TLS, proxies, connection reuse, HTTP/2 and HTTP/3, and real DNS were not exercised. WebSockets were tested as a client (websockets), not as a server protocol.
• Client libraries. oracledb in thick mode, pyodbc with Microsoft's driver, the c implementation of psycopg 3, pyarrow, polars and duckdb, DNS over HTTPS, TLS or QUIC in niquests, and what any client library does on uvloop.
• Asynchronous servers. Litestar, Django Channels itself and Django's ASGI entry point, gunicorn's own ASGI worker beyond its choice of loop, granian --reload and its embedded server, sanic's inspector and ASGI mode, hypercorn and sanic with a worker that is killed, arq with --watch.
• WSGI servers. uWSGI's emperor, mules, spooler, cheaper mode and --touch-reload, its gevent and asyncio plugins, and uWSGI behind a web server that speaks the uwsgi protocol; waitress on anything but TCP; a mod_wsgi packaged by a distribution, Apache's worker MPM, and mod_wsgi on Windows; the Flask reloader with a changed locked policy.
• Task queues. Brokers other than Redis, celery multi and --detach, Celery's pool-restart remote control, rq cron, dramatiq-gevent, Huey's greenlet workers, supervisorctl, multiprocessing.Process on its own and managers.
• uvicorn releases other than 0.54.0 and 0.46.0. The statements about 0.47.0, 0.50.0 and 0.36.0 come from single runs.