Network filters

Network filters operate on raw L4 byte streams. They sit between the listener manager's connection accept and any L7 layer, and they are the place to plug in non-HTTP protocols. There are 28 in-tree filters under source/extensions/filters/network/, and another set under contrib/.

Categories

Category	Filters	Notes
L7 dispatchers	http_connection_manager, generic_proxy	Terminal filters that produce L7 streams. The HCM is by far the most important — see HTTP connection manager.
Plain TCP	tcp_proxy, direct_response, echo	Simple forwarding / fixed-response.
Database / message proxies	mongo_proxy, redis_proxy, dubbo_proxy, thrift_proxy, zookeeper_proxy	Protocol-aware L7 over TCP. The contrib tree adds mysql_proxy, postgres_proxy, kafka, rocketmq_proxy, sip_proxy.
Auth / policy	ext_authz, rbac	Same primitives as the HTTP variants.
Rate limiting	ratelimit, local_ratelimit, tcp_bandwidth_limit, connection_limit	Per-connection or per-byte.
Process plumbing	ext_proc	Streams bytes to an external server for processing.
SNI helpers	sni_cluster, sni_dynamic_forward_proxy	Pick a cluster from SNI value.
Reverse tunnel	reverse_tunnel	Long-lived back-channel from edge proxy.
Geoip	geoip	Annotates connection metadata.
Stateful	set_filter_state, match_delegate	Same building blocks as HTTP.
Scriptable	wasm, dynamic_modules	Network-level Wasm and dynamic-module filters.

Lifecycle

sequenceDiagram
    participant L as Listener
    participant LF as Listener filters
    participant FCM as FilterChainManager
    participant Conn as Network::ConnectionImpl
    participant NF as Network filters
    participant Term as Terminal (HCM/tcp_proxy)

    L->>LF: accept
    LF->>FCM: choose filter chain (SNI/ALPN/source)
    FCM->>Conn: instantiate
    FCM->>NF: build chain (read + write filters)
    Conn->>NF: onNewConnection / onData
    NF->>Term: data flows through

Network::Filter (envoy/network/filter.h) splits into:

• Network::ReadFilter — runs on bytes coming from the downstream client.
• Network::WriteFilter — runs on bytes going back to the downstream client.

A single class can implement both. The HCM is a ReadFilter because it interprets request bytes; it writes back via the codec, not as a WriteFilter.

Anatomy of a filter

source/extensions/filters/network/<name>/
├── BUILD
├── <name>.{h,cc}        # The filter
├── config.{h,cc}        # The factory + REGISTER_FACTORY
└── <name>_protocol.{h,cc}  # Optional protocol parser

Filter:

class MyFilter : public Network::ReadFilter {
  Network::FilterStatus onNewConnection() override;
  Network::FilterStatus onData(Buffer::Instance&, bool end_stream) override;
  void initializeReadFilterCallbacks(Network::ReadFilterCallbacks&) override;
};

Factory:

class MyFilterConfig : public Common::FactoryBase<MyFilterProto> {
  Network::FilterFactoryCb createFilterFactoryFromProtoTyped(...) override;
};
REGISTER_FACTORY(MyFilterConfig, Server::Configuration::NamedNetworkFilterConfigFactory);

tcp_proxy

source/common/tcp_proxy/ implements the simplest non-trivial L4 forwarder: pick a cluster, get a TCP connection, and shuttle bytes both ways. Used directly for non-HTTP traffic and as the basis for several other filters. Its config is in source/extensions/filters/network/tcp_proxy/.

Generic proxy

generic_proxy (source/extensions/filters/network/generic_proxy/) is a framework for building stream-multiplexed protocol proxies (similar to HCM but generic). Codecs are pluggable extensions; the framework handles routing, retry, filter chains. Used by contrib/generic_proxy/ implementations.

Stats

Each filter has its own counters and gauges. Common ones:

• tcp_proxy.cx_total, tcp_proxy.cx_active
• mongo.cx_drain_close, mongo.collection.<name>.query_total
• redis.cx_total, redis.upstream_cx_drain_close

Adding a new network filter

Same recipe as for an HTTP filter; replace Http → Network in factory and registration:

1. source/extensions/filters/network/<name>/
2. api/envoy/extensions/filters/network/<name>/v3/
3. Register in extensions_build_config.bzl.
4. Tests under test/extensions/filters/network/<name>/.
5. Release note + CODEOWNERS + metadata.

See also

• Listener manager — the host of network filter chains.
• HTTP connection manager — the most important network filter.
• HTTP filters — the L7 cousin.