DPI

All dpi value types are described here.

Protocol Inspection

inspection size limit

type: map

This will set size limit for each protocol with no explicit size limit in their specification.

The keys ars:

  • ftp_greeting_msg

    optional, type: humanize usize

    Set for FTP server greeting message.

    default: 512

  • http_request_uri

    optional, type: humanize usize

    Set for HTTP client request URI.

    default: 4096

  • imap_greeting_msg

    optional, type: humanize usize

    Set for IMAP server greeting message.

    default: 512

  • nats_info_line

    optional, type: humanize usize

    Set for NATS server info line.

    default: 1024

  • smtp_greeting_msg

    optional, type: humanize usize

    Set for SMTP server greeting message.

    default: 512

    Deprecated since version 1.9.0: not used anymore, the max SMTP reply line length should be 512

protocol inspect action

type: string

Set what we should do to a specific application protocol.

The possible values for this are:

  • block

    Block the traffic. And we will try to send application level error code to the client.

  • intercept

    Intercept the traffic. This is the default value.

  • bypass

    Bypass the interception. The traffic will be transferred transparently.

  • detour

    Send the traffic to a stream detour service, which will be configured at somewhere in the context.

Added in version 1.9.9.

inspect rule

yaml value: map

All the rules share the same config format described in this section.

An inspect rule is consisted of many records, each of them has an associated protocol inspect action.

The value in map format is consisted of the following fields:

  • any of the protocol inspect actions as the key str

    The value should be a valid record or a list of them, with the key string as the acl action. See detail types for the format of each record type.

Added in version 1.9.9.

dst subnet inspect rule

yaml value: inspect rule

The record type should be ip network str.

Added in version 1.9.9.

exact host inspect rule

yaml value: inspect rule

The record type should be host.

Added in version 1.9.9.

child domain inspect rule

yaml value: inspect rule

Specify the parent domain to match, all children domain in this domain will be matched.

The record type should be domain.

Added in version 1.9.9.

protocol inspect policy

yaml value: string | map

This rule set is used to match dst host for each protocol inspection call.

Consisted of the following rules:

The match order is the same as the list order above.

One can use the string type to define a default action for any upstream traffic, regardless of the host,

Added in version 1.9.9.

protocol inspection

type: map

This set the basic protocol inspection config.

The keys are:

  • inspect_max_depth

    optional, type: usize

    Set the max inspection depth. The stream will be treated as unknown protocol if it’s nested too much.

    default: 4

  • data0_buffer_size

    optional, type: humanize usize

    Set the stream buffer size for protocol inspection.

    default: 4096

  • data0_wait_timeout

    optional, type: humanize duration

    Set the wait timeout for the initial data, from either the client side or the server side.

    default: 60s

  • data0_read_timeout

    optional, type: humanize duration

    Set the read timeout value when reading initial data for protocol inspection after it’s arrival.

    If timeout, the protocol will be considered as unknown.

    default: 4s

  • data0_size_limit

    optional, type: inspection size limit

    Set inspection size limit for each protocol.

    default: set with default value

maybe protocol

type: str

The following values are supported:

  • http

  • https

  • smtp

  • ssh

  • ftp

  • pop3

  • pop3s

  • nntp

  • nntps

  • imap

  • imaps

  • nats

  • bittorrent

portmap

type: seq | map

Set the protocol indication for each port.

For seq value, each element should be a map, with two keys:

  • port

    required, type: u16

    Set the port number.

  • protocol

    required, type: maybe protocol | seq

    Set the protocol(s).

For map value, the key should be the port, and the value should be the same as the protocol above.

server tcp portmap

type: portmap

Set the protocol indication for each server side tcp port.

See the code lib/g3-dpi/src/protocol/portmap.rs for default set ports.

client tcp portmap

type: portmap

Set the protocol indication for each client side tcp port.

See the code lib/g3-dpi/src/protocol/portmap.rs for default set ports.

stream dump

type: map | str

Set stream dump config. You can use this to dump streams to wireshark udpdump.

The keys are:

  • peer

    required, type: env sockaddr str

    Set the peer udp socket address.

    default: 127.0.0.1:5555

  • socket_buffer

    optional, type: socket buffer config

    Set the buffer config for the udp socket.

    default: not set

  • misc_opts

    optional, type: udp misc sock opts

    Set misc udp socket options on created udp sockets.

    default: not set

  • packet_size

    optional, type: usize

    Set the max udp packet size.

    default: 1480

  • client_side

    optional, type: bool

    Set this to true to dump client side traffic.

    default: false, the remote side traffic will be dumped

    Added in version 1.9.7.

TLS Interception

tls cert agent

type: map | str

Set the config for tls certificate agent / generator.

The keys are:

  • query_peer_addr

    optional, type: env sockaddr str

    Set the peer udp socket address.

    default: 127.0.0.1:2999

  • query_socket_buffer

    optional, type: socket buffer config

    Set the socket buffer config for the socket to peer.

    default: not set

  • query_wait_timeout

    optional, type: humanize duration

    Set the timeout for the cache runtime to wait response from the query runtime.

    default: 4s

  • protective_cache_ttl

    optional, type: u32

    Set the protective cache ttl for certificates returned by peer.

    default: 10

  • maximum_cache_ttl

    optional, type: u32

    Set the maximum cache ttl for certificates returned by peer.

    default: 300

  • cache_request_batch_count

    optional, type: usize

    Set the batch request count in cache runtime.

    default: 10

  • cache_request_timeout

    optional, type: humanize duration

    Set the request timeout for the caller.

    default: 4s

  • cache_vanish_wait

    optional, type: humanize duration

    Set the vanish time after the record is considered expired (not the certificate expire time).

    default: 300s

For str value, it will parsed as query_peer_addr and use default value for other fields.

Changed in version 1.7.11: allow str value

tls interception client

type: map

Set the tls client config for tls interception.

The keys are:

  • min_tls_version

    optional, type: tls version

    Set the minimal TLS version to use.

    default: not set

    Added in version 1.9.9.

  • max_tls_version

    optional, type: tls version

    Set the maximum TLS version to use.

    default: not set

    Added in version 1.9.9.

  • ca_certificate

    optional, type: tls certificates

    Add CA certificate for certificate verification of the upstream server.

    default: not set

  • no_default_ca_certificate

    optional, type: false

    Set if we should not load the system default CA certificates.

    default: false

  • handshake_timeout

    optional, type: humanize duration

    Set the timeout for upstream tls handshake.

    default: 10s

  • no_session_cache

    optional, type: bool

    Set if we should disable tls session cache.

    default: false

  • session_cache_lru_max_sites

    optional, type: usize

    Set how many LRU sites should have cached sessions.

    default: 128

  • session_cache_each_capacity

    optional, type: usize

    Set how many sessions should be kept for each site.

    default: 16

  • supported_groups

    optional, type: str

    Set the supported elliptic curve groups.

    default: not set

    Added in version 1.7.35.

  • use_ocsp_stapling

    optional, type: bool

    Set this to true to request a stapled OCSP response from the server.

    Verify of this response is still not implemented.

    default: false

    Added in version 1.7.35.

  • enable_sct

    optional, type: bool

    Enable the processing of signed certificate timestamps (SCTs) for OpenSSL, or enables SCT requests for BoringSSL.

    Verify of this response is still not implemented for BoringSSL variants.

    default: not set, the default value may vary between different OpenSSL variants

    Added in version 1.7.35.

  • enable_grease

    optional, type: bool

    Enable GREASE. See RFC 8701.

    default: not set, the default value may vary between different OpenSSL variants

    Added in version 1.7.35.

  • permute_extensions

    optional, type: bool

    Whether to permute TLS extensions.

    default: not set, the default value may vary between different OpenSSL variants

    Added in version 1.7.36.

  • insecure:

    optional, type: bool

    DANGEROUS: Enable to not verify peer (server) tls certificates.

    When this option is enabled, verify errors will be logged to the configured structured logger.

    default: false

    Added in version 1.11.0.

tls interception server

Added in version 1.7.36.

type: map

Set the tls server config for tls interception.

The keys are:

  • accept_timeout

    optional, type: humanize duration

    Set the timeout for client tls handshake.

    This timeout value is also used for accepting the initial ClientHello message.

    default: 10s, alias: handshake_timeout

HTTP Interception

h1 interception

type: map

Set the config for HTTP 1.x interception.

The keys are:

  • pipeline_size

    optional, type: nonzero usize

    Set the pipeline size.

    default: 10

  • pipeline_read_idle_timeout

    optional, type: humanize duration

    Set the idle timeout of the client side IDLE http connections.

    default: 5min

  • req_header_recv_timeout

    optional, type: humanize duration

    Set the max time to wait a full request header after the client connection become readable.

    default: 30s

  • rsp_header_recv_timeout

    optional, type: humanize duration

    Set the max time duration after the full request sent and before receive of the whole response header.

    default: 60s

  • req_header_max_size

    optional, type: humanize usize

    Set the max request header size.

    default: 64KiB

  • rsp_header_max_size

    optional, type: humanize usize

    Set the max response header size.

    default: 64KiB

  • body_line_max_length

    optional, type: int

    Set the max line length for lines (trailer and chunk size) in http body.

    default: 8192

  • steal_forwarded_for

    optional, type: bool

    Set if we should delete the Forwarded and X-Forwarded-For headers from the client’s intercepted transparent request.

    default: false

    Added in version 1.9.2.

h2 interception

type: map

Set the config for HTTP 2.0 interception.

The keys are:

  • max_header_list_size

    optional, type: humanize u32

    Set the max header size.

    default: 64KiB, alias: max_header_size

  • max_concurrent_streams

    optional, type: u32

    Set the max concurrent stream that can be initiated by client. The remote peer will also give a max concurrent stream limit, the minimum one of them will be sent to the client.

    default: 128

  • max_frame_size

    optional, type: humanize u32

    Set the max frame size.

    default: 256KiB, min: 16K, max: 16M - 1

    Changed in version 1.11.3: adjust the value to be in the range min-max automatically

  • stream_window_size

    optional, type: humanize u32

    Set the INITIAL_WINDOW_SIZE in http2 SETTINGS frame. This will set the window size for each stream.

    default: 1MiB

    Added in version 1.11.7.

  • connection_window_size

    optional, type: humanize u32

    Set the window size for the h2 connection.

    default: 2MiB

    Added in version 1.11.7.

  • max_send_buffer_size

    optional, type: humanize usize

    Set the max send buffer size.

    default: 8MiB

  • upstream_handshake_timeout

    optional, type: humanize duration

    Set the http2 handshake timeout to upstream.

    default: 10s

  • upstream_stream_open_timeout

    optional, type: humanize duration

    Set the upstream stream open timeout.

    default: 10s

  • client_handshake_timeout

    optional, type: humanize duration

    Set the http2 handshake timeout to client.

    default: 4s

  • ping_interval

    optional, type: humanize duration

    Set the time interval to send HTTP2 PING frames.

    default: 60s

    Added in version 1.11.7.

  • rsp_header_recv_timeout

    optional, type: humanize duration

    Set the max time duration after the full request sent and before receive of the whole response header.

    default: 60s

  • silent_drop_expect_header

    optional, type: bool

    Set if we should drop the Expect http header silently. If not set, a 417 Expectation Failed response will be sent to client.

smtp interception

  • greeting_timeout

    optional, type: humanize duration

    Set the timeout value for the forward of the upstream SMTP Greeting message.

    default: 5min

  • quit_wait_timeout

    optional, type: humanize duration

    Set the timeout value for the forward of the upstream QUIT response.

    default: 60s

  • command_wait_timeout

    optional, type: humanize duration

    Set the timeout value for the wait of the next client SMTP command.

    default: 5min

  • response_wait_timeout

    optional, type: humanize duration

    Set the timeout value for the wait of the most of upstream SMTP command response.

    default: 5min

  • data_initiation_timeout

    optional, type: humanize duration

    Set the timeout value for the initial confirm response to DATA command from upstream.

    default: 2min

  • data_termination_timeout

    optional, type: humanize duration

    Set the timeout value for the final status response to DATA command from upstream.

    default: 10min

  • allow_on_demand_mail_relay

    optional, type: bool

    Set whether we should enable rfc2645 ODMR protocol support.

    Note

    Interception for the SMTP connection inside ODMR is currently not supported.

    default: false

  • allow_data_chunking

    optional, type: bool

    Set whether we should enable rfc3030 BDAT command support.

    Note

    ICAP integration is not available currently.

    default: false

  • allow_burl_data

    optional, type: bool

    Set whether we should enable rfc4468 BURL command support.

    Note

    ICAP integration is not available currently.

    default: false

Added in version 1.9.2.

imap interception

  • greeting_timeout

    optional, type: humanize duration

    Set the timeout value for the forward of the upstream IMAP Greeting message.

    default: 5min

  • authenticate_timeout

    optional, type: humanize duration

    Set the total time to wait before the connection enter authenticated state.

    default: 5min

  • logout_wait_timeout

    optional, type: humanize duration

    Set the timeout value for the forward of the upstream LOGOUT response.

    default: 10s

  • command_line_max_size

    optional, type: usize

    Set the max size for a single IMAP command line.

    default: 4096

  • response_line_max_size

    optional, type: usize

    Set the max size for a single IMAP response line.

    default: 4096

  • forward_max_idle_count

    optional, type: usize

    Set the max IDLE count allowed when forwarding IMAP command/response lines, including IMAP IDLE state.

    The IDLE check interval will be task_idle_check_interval.

    default: 30

  • transfer_max_idle_count

    optional, type: usize

    Set the max IDLE count allowed when transferring IMAP command/response literal data.

    The IDLE check interval will be task_idle_check_interval.

    default: 5

Added in version 1.9.7.