vrr/g3
2
0
Fork 0
mirror of https://github.com/bytedance/g3.git synced 2026-05-04 14:40:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 6

initial commit

Browse source
This commit is contained in:
zhangjingqiang 2023-03-09 17:55:45 +08:00
commit 13716f4923
1425 changed files with 163227 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

207
g3proxy/doc/configuration/values/acl.rst Normal file
View file

@ -0,0 +1,207 @@
.. _configure_acl_value_types:
***
ACL
***
All acl value types are described here.
Basic Type
==========
.. _conf_value_acl_action:
acl action
----------
**yaml value**: str
There are 4 types of acl actions:
* permit
Permit if match the rule. Alternatives: allow, accept.
* permit_log
Permit if match the rule and log. Alternatives: allow_log, accept_log.
* forbid
Forbid if match the rule. Alternatives: deny, reject.
* forbid_log
Forbid if match the rule and log. Alternatives: deny_log, reject_log.
.. _conf_value_acl_rule:
acl rule
--------
**yaml value**: mix
All the rules share the same config format described in this section.
An acl rule is consisted of many records, each of them has an associated :ref:`acl action <conf_value_acl_action>`.
A default missed action can be set in the rule, it set the default action if no record matches.
The value in map format is consisted of the following fields:
* default
Set the default acl action if no rule match.
Default action if rule is set but with *default* omitted: forbid if not specified in the rule's doc.
* any of the acl 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.
The value could also be a single record or a list of them, which means only them are permitted with no log.
The default missed action is **forbid** and the default found action is **permit**,
if they are not specified in the detail types.
.. _conf_value_acl_rule_set:
acl rule set
------------
**yaml value**: seq
Acl rule set is a group of at least 2 acl rules. The rules are matched in order, see detail types for the real order.
If any record in any rules is matched, that acl action will be used. If missed in all rules, all default missed actions
will be compared and the most strict one will be used, so there is no default missed action at rule set level.
Detail Type
===========
.. _conf_value_network_acl_rule:
network acl rule
----------------
**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
The record type should be :ref:`ip network str <conf_value_ip_network_str>`.
.. _conf_value_egress_network_acl_rule:
egress network acl rule
-----------------------
**yaml value**: :ref:`network acl rule <conf_value_network_acl_rule>`
The same type as network acl rule. Default added: forbid unspecified, loopback, link-local and discard-only addresses.
.. _conf_value_ingress_network_acl_rule:
ingress network acl rule
------------------------
**yaml value**: :ref:`network acl rule <conf_value_network_acl_rule>`
The same type as network acl rule. Default added: permit 127.0.0.1 and ::1.
.. _conf_value_dst_subnet_acl_rule:
dst subnet acl rule
-------------------
**yaml value**: :ref:`network acl rule <conf_value_network_acl_rule>`
The same type as network acl rule. Default added: forbid unspecified, loopback and link-local addresses.
.. _conf_value_exact_host_acl_rule:
exact host acl rule
-------------------
**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
The record type should be :ref:`host <conf_value_host>`.
.. _conf_value_exact_port_acl_rule:
exact port acl rule
-------------------
**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
The record type should be :ref:`ports <conf_value_ports>`.
.. _conf_value_child_domain_acl_rule:
child domain acl rule
---------------------
**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
Specify the parent domain to match, all children domain in this domain will be matched.
The record type should be :ref:`domain <conf_value_domain>`.
.. _conf_value_regex_set_acl_rule:
regex set acl rule
------------------
**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
The record type should be a valid regex string.
.. _conf_value_dst_host_acl_rule_set:
dst host acl rule set
---------------------
**yaml value**: :ref:`acl rule set <conf_value_acl_rule_set>`
This rule set is used to match dst host for each request.
Consisted of the following rules:
* exact_match
:ref:`exact host acl rule <conf_value_exact_host_acl_rule>`
* child_match
:ref:`child domain acl rule <conf_value_child_domain_acl_rule>`
* regex_match
:ref:`regex set acl rule <conf_value_regex_set_acl_rule>`
* subnet_match
Match only if the host is an IP Address. The type is
:ref:`dst subnet acl rule <conf_value_dst_subnet_acl_rule>`
The match order is the same as the list order above.
.. _conf_value_user_agent_acl_rule:
user agent acl rule
-------------------
**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
The record type should be a valid **product** string as specified in `rfc7231 User-Agent`_.
The default missed action is **permit** and the default found action is **forbid**.
.. _rfc7231 User-Agent: https://tools.ietf.org/html/rfc7231#section-5.5.3
.. _conf_value_proxy_request_acl_rule:
proxy request acl rule
----------------------
**yaml value**: :ref:`acl rule <conf_value_acl_rule>`
The record type should be a valid :ref:`proxy request type <conf_value_proxy_request_type>`.

117
g3proxy/doc/configuration/values/audit.rst Normal file
View file

@ -0,0 +1,117 @@
.. _configure_audit_value_types:
*****
Audit
*****
All audit value types are described here.
ICAP
====
.. _conf_value_audit_icap_service_config:
icap service config
-------------------
**type**: map | str
Config ICAP service.
For *str* value, the value will be treated as *url* as described following.
For *map* value, the keys are:
* url
**required**, **type**: :ref:`url str <conf_value_url_str>`
Set the ICAP service url.
* tcp_keepalive
**optional**, **type**: :ref:`tcp keepalive <conf_value_tcp_keepalive>`
Set the keep-alive config for the tcp connection to ICAP server.
**default**: enabled with default value
* icap_connection_pool
**optional**, **type**: :ref:`icap connection pool <conf_value_audit_icap_connection_pool>`
Set the connection pool config.
**default**: set with default value
* icap_max_header_size
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set the max header size when parsing response from the ICAP server.
**default**: 8KiB
* preview_data_read_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the timeout value for the read of preview data.
If timeout, preview will not be used in the request send to the ICAP server.
**default**: 4s
* respond_shared_names
**optional**, **type**: :ref:`http header name <conf_value_http_header_name>` or seq of this
Set the headers returned by ICAP server in REQMOD response that we should send in the following RESPMOD request.
This config option now only apply to REQMOD service.
**default**: not set
.. versionadded:: 1.7.4
* bypass
**optional**, **type**: bool
Set if we should bypass if we can't connect to the ICAP server.
**default**: false
.. _conf_value_audit_icap_connection_pool:
icap connection pool
--------------------
**type**: map
The keys are:
* check_interval
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the min idle check interval.
New connections will be established if the idle connections are less than *min_idle_count*.
**default**: 10s
* max_idle_count
**optional*, **type**: usize
Set the maximum idle connections count.
**default**: 128
* min_idle_count
**optional**, **type**: usize
Set the minimum idle connections count.
**default**: 16

213
g3proxy/doc/configuration/values/base.rst Normal file
View file

@ -0,0 +1,213 @@
.. _configure_base_value_types:
****
Base
****
.. _conf_value_nonzero_u32:
nonzero u32
===========
**yaml value**: int
A non-zero u32 in value type.
.. _conf_value_humanize_usize:
humanize usize
==============
**yaml value**: int | str
For *str* value, it support units of 2^10 like "KiB", "MiB", or units of 1000 like "KB", "MB".
For *int* value or *str* value without unit, the unit will be bytes.
.. seealso::
`humanize_rs bytes <https://docs.rs/humanize-rs/0.1.5/humanize_rs/bytes/index.html>`_
.. _conf_value_humanize_u32:
humanize u32
============
**yaml value**: int | str
For *str* value, it support units of 2^10 like "KiB", "MiB", or units of 1000 like "KB", "MB".
For *int* value or *str* value without unit, the unit will be bytes.
.. _conf_value_humanize_duration:
humanize duration
=================
**yaml value**: int | str
For *str* value, at least one unit is required. Multiple units string like "1h 30m 71s" is also supported.
See `duration units`_ for all supported units.
For *int* and *real* value, the unit will be seconds.
.. seealso::
`humanize_rs duration <https://docs.rs/humanize-rs/0.1.5/humanize_rs/duration/index.html>`_
.. _duration units: https://docs.rs/humanize-rs/0.1.5/src/humanize_rs/duration/mod.rs.html#115
.. _conf_value_username:
username
========
**yaml value**: str
The UTF-8 username to be used in different contexts.
Should be less than or equal to 255 bytes.
.. _conf_value_password:
password
========
**yaml value**: str
The UTF-8 password to be used in different contexts.
Should be less than or equal to 255 bytes.
.. _conf_value_upstream_str:
upstream str
============
**yaml value**: str
The string should be in *<ip>[:<port>]* or *<domain>[:<port>]* format.
If omitted, the *port* will be set to *0*.
.. _conf_value_url_str:
url str
=======
**yaml value**: str
The string should be a valid url.
.. _conf_value_ascii_str:
ascii str
=========
**yaml value**: str
The string should only consists of ascii characters.
.. _conf_value_rfc3339_datetime_str:
rfc3339 datetime str
====================
**yaml value**: str
The string should be a value rfc3339 datetime string.
.. _conf_value_selective_pick_policy:
selective pick policy
=====================
**yaml value**: str
The policy to select item from selective vectors.
The following values are supported:
* random
The default one.
* serial | sequence
For nodes with the same weights, the order is kept as in the config.
* round_robin | rr
For nodes with the same weights, the order is kept as in the config.
* rendezvous
Rendezvous Hash. The key format is defined in the context of each selective vector.
* jump_hash
Jump Consistent Hash. The key format is defined in the context of each selective vector.
.. _conf_value_weighted_upstream_addr:
weighted upstream addr
======================
**yaml value**: map | string
A upstream str with weight set, which make can be grouped into selective vector.
The map consists 2 fields:
* addr
**required**, **type**: :ref:`upstream str <conf_value_upstream_str>`
The real value.
* weight
**optional**, **type**: f64
The weight of the real value.
**default**: 1.0
If the value type is string, then it's value will be the *addr* field, with *weight* set to default value.
.. _conf_value_weighted_name_str:
weighted name str
=================
**yaml value**: map | string
A name string with weight set, which make can be grouped into selective vector.
The map consists 2 fields:
* name
**required**, **type**: string
The name. The meaning of the name is depending on the config context.
* weight
**optional**, **type**: f64
The weight of the name.
**default**: 1.0
If the value type is string, then it's value will be the *name* field, with *weight* set to default value.
.. _conf_value_list:
list
====
**yaml value**: mix
A list container type for type T.
The value could be a single value of type T, or a sequence of values of type T.

482
g3proxy/doc/configuration/values/dpi.rst Normal file
View file

@ -0,0 +1,482 @@
.. _configure_dpi_value_types:
***
DPI
***
All dpi value types are described here.
Protocol Inspection
===================
.. _conf_value_dpi_inspection_size_limit:
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**: :ref:`humanize usize <conf_value_humanize_usize>`
Set for FTP server greeting message.
**default**: 512
* http_request_uri
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set for HTTP client request URI.
**default**: 4096
* imap_greeting_msg
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set for IMAP server greeting message.
**default**: 512
* nats_info_line
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set for NATS server info line.
**default**: 1024
* smtp_greeting_msg
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set for SMTP server greeting message.
**default**: 512
.. _conf_value_dpi_protocol_inspection:
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**: :ref:`humanize usize <conf_value_humanize_usize>`
Set the stream buffer size for protocol inspection.
**default**: 4096
* data0_wait_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_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**: :ref:`humanize duration <conf_value_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**: :ref:`inspection size limit <conf_value_dpi_inspection_size_limit>`
Set inspection size limit for each protocol.
**default**: set with default value
.. _conf_value_dpi_maybe_protocol:
maybe protocol
--------------
**type**: str
The following values are supported:
* http
* https
* smtp
* ssh
* ftp
* pop3
* pop3s
* nntp
* nntps
* imap
* imaps
* nats
* bittorrent
.. _conf_value_dpi_portmap:
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**: :ref:`maybe protocol <conf_value_dpi_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.
.. _conf_value_dpi_server_tcp_portmap:
server tcp portmap
------------------
**type**: :ref:`portmap <conf_value_dpi_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.
.. _conf_value_dpi_client_tcp_portmap:
client tcp portmap
------------------
**type**: :ref:`portmap <conf_value_dpi_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.
TLS Interception
================
.. _conf_value_dpi_tls_cert_generator:
tls cert generator
------------------
**type**: map
Set the config for tls certificate generator.
The keys are:
* query_peer_addr
**optional**, **type**: :ref:`sockaddr str <conf_value_sockaddr_str>`
Set the peer udp socket address.
**default**: 127.0.0.1:2999
* query_socket_buffer
**optional**, **type**: :ref:`socket buffer config <conf_value_socket_buffer_config>`
Set the socket buffer config for the socket to peer.
**default**: not set
* query_wait_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the timeout for the cache runtime to wait response from the query runtime.
**default**: 400ms
* 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**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the request timeout for the caller.
**default**: 800ms
* cache_vanish_wait
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the vanish time after the record is considered expired (not the certificate expire time).
**default**: 300s
.. _conf_value_dpi_tls_interception_client:
tls interception client
-----------------------
**type**: map
Set the tls client config for tls interception.
The keys are:
* ca_certificate
**optional**, **type**: :ref:`tls certificates <conf_value_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**: :ref:`humanize duration <conf_value_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
HTTP Interception
=================
.. _conf_value_dpi_h1_interception:
h1 interception
---------------
**type**: map
Set the config for HTTP 1.x interception.
The keys are:
* pipeline_size
**optional**, **type**: usize
Set the pipeline size.
**default**: 10
* pipeline_read_idle_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the idle timeout of the client side IDLE http connections.
**default**: 5min
* req_header_recv_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_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**: :ref:`humanize duration <conf_value_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**: :ref:`humanize usize <conf_value_humanize_usize>`
Set the max request header size.
**default**: 64KiB
* rsp_header_max_size
**optional**, **type**: :ref:`humanize usize <conf_value_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
.. _conf_value_dpi_h2_interception:
h2 interception
---------------
**type**: map
Set the config for HTTP 2.0 interception.
The keys are:
* max_header_list_size
**optional**, **type**: :ref:`humanize u32 <conf_value_humanize_u32>`
Set the max header size.
**default**: 64KiB
* max_concurrent_streams
**optional**, **type**: u32
Set the max concurrent stream for each http2 connection.
**default**: 16
* max_frame_size
**optional**, **type**: :ref:`humanize u32 <conf_value_humanize_u32>`
Set the max frame size.
**default**: 1MiB
* max_send_buffer_size
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set the max send buffer size.
**default**: 16MiB
* disable_upstream_push
**optional**, **type**: bool
Set if we should disable server push.
**default**: false
* upstream_handshake_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the http2 handshake timeout to upstream.
**default**: 10s
* upstream_stream_open_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the upstream stream open timeout.
**default**: 10s
* client_handshake_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the http2 handshake timeout to client.
**default**: 4s
* rsp_header_recv_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_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.

71
g3proxy/doc/configuration/values/fs.rst Normal file
View file

@ -0,0 +1,71 @@
.. _configure_fs_value_types:
**********
Filesystem
**********
.. _conf_value_hybrid_map:
hybrid map
==========
**yaml value**: seq | str
This is a hybrid container for a sequence of maps which may reside in other files.
For *seq* value, all of it's values should be the final map, or a valid *str* value as described below.
For *str* value, it should be a valid path, which may be absolute or relative to the directory of the main conf file.
The path may be a file or directory:
* If the path is a directory, the non-symbolic files in it with extension *.conf* will be parsed as described below.
* If the path is a file, it should contains one or many yaml docs, each doc will be the final map.
.. _conf_value_file_path:
file path
=========
**yaml value**: str
This set the path for a regular file to be used.
The file should be an absolute path, or relative to a predefined path.
The path should be existed, or can be auto created, according to the specific config.
.. _conf_value_file:
file
====
**yaml value**: str
This set a file to be read. The file should be an absolute path, or relative to a predefined path.
.. _conf_value_absolute_path:
absolute path
=============
**yaml value**: str
The set a file path to be used. The path should be absolute.
.. _conf_value_config_file_format:
config file format
==================
**yaml value**: str
Set the format for the related config file.
The following values are supported:
* yaml
* json
The default vary in different contexts.

22
g3proxy/doc/configuration/values/index.rst Normal file
View file

@ -0,0 +1,22 @@
******************
Common Value Types
******************
There are many common values used across this document.
The meanings and formats of them are described as follows:
.. toctree::
base
fs
network
acl
audit
dpi
tls
rate_limit
resolve
metrics
route
runtime

128
g3proxy/doc/configuration/values/metrics.rst Normal file
View file

@ -0,0 +1,128 @@
.. _configure_metrics_value_types:
*******
Metrics
*******
.. _conf_value_metrics_value:
metrics value
=============
**yaml value**: limited str
Only the following characters are allowed:
a to z, A to Z, 0 to 9, -, _, ., / or Unicode letters (as per the specification)
The character range is the same as `OpenTSDB metrics-and-tags`_.
.. _OpenTSDB metrics-and-tags: http://opentsdb.net/docs/build/html/user_guide/writing/index.html#metrics-and-tags
.. _conf_value_static_metrics_tags:
static metrics tags
===================
**yaml value**: map
This should be a map, each key will be the tag name, and it's value will be the tag value.
The tag name and the tag value should be of type :ref:`metrics value <conf_value_metrics_value>`.
.. _conf_value_metrics_name:
metrics name
============
**yaml value**: :ref:`metrics value <conf_value_metrics_value>`
The metrics name
.. _conf_value_statsd_client_config:
Statsd Client Config
====================
The full format of the root value should be a map, with the following keys:
target_unix
-----------
**optional**, **type**: mix
You can set this if you want to send statsd metrics to a custom unix socket path.
The value can be a map, with the following keys:
* path
**required**, **type**: :ref:`absolute path <conf_value_absolute_path>`
The syslogd daemon listen socket path.
If the value type is str, the value should be the same as the value as *path* above.
**default**: not set
.. versionadded:: 1.3.5
target_udp
----------
**optional**, **type**: mix
You can set this if you want to send statsd metrics to a remote statsd which listening on a udp socket.
The value can be a map, with the following keys:
* address
**optional**, **type**: :ref:`sockaddr str <conf_value_sockaddr_str>`
Set the remote socket address.
**default**: 127.0.0.1:8125
* bind_ip
**optional**, **type**: :ref:`ip addr str <conf_value_ip_addr_str>`
Set the ip address to bind to for the local socket.
**default**: not set
If the value type is str, the value should be the same as the value as *address* above.
.. versionadded:: 1.3.5
target
------
**optional**, **type**: map
This is just another form to set statsd target address.
The key *udp* is just handled as *target_udp* as above.
The key *unix* is just handled as *target_unix* as above.
prefix
------
**optional**, **type**: :ref:`metrics name <conf_value_metrics_name>`
Set the global prefix for all metrics.
**default**: "g3proxy"
emit_duration
-------------
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the emit duration for local stats. All stats will be send out in sequence.
**default**: 200ms

817
g3proxy/doc/configuration/values/network.rst Normal file
View file

@ -0,0 +1,817 @@
.. _configure_network_value_types:
*******
Network
*******
.. _conf_value_sockaddr_str:
sockaddr str
============
**yaml value**: str
The string should be in *<ip>[:<port>]* format, in which the port may be omitted if a default value is available.
.. _conf_value_ip_addr_str:
ip addr str
===========
**yaml value**: str
The string should be in *<ip>* format.
.. _conf_value_ipv4_addr_str:
ipv4 addr str
=============
**yaml value**: str
The string should be in *<ipv4 address>* format.
.. _conf_value_ipv6_addr_str:
ipv6 addr str
=============
**yaml value**: str
The string should be in *<ipv6 address>* format.
Ipv4 mapped address should not be set when this type is required.
.. _conf_value_ip_network_str:
ip network str
==============
**yaml value**: str
The string should be a network address in CIDR format, or just an ip address.
.. _conf_value_egress_area:
egress area
===========
**yaml value**: str
Area of the egress ip address. The format is strings joined with '/', like "中国/山东/济南".
.. _conf_value_host:
host
====
**yaml value**: str
A host value. Which should be either a valid domain, or a valid IP address.
.. _conf_value_domain:
domain
======
**yaml value**: str
A domain value. The string value should be able to convert to a IDNA domain.
Leading '.' is not allowed.
.. _conf_value_ports:
ports
=====
**yaml value**: mix
A collection of ip ports. The base type may be:
* u16 port
A single port.
* <start>-<end> port range
A port range, which includes both *start* and *end*. *end* should be greater than *start*.
* comma separated discrete port(s)
A list of port. Each could be a port or a range of ports.
The yaml value could be:
* int
int base type.
* str
str base types.
* array
array of base types.
.. _conf_value_port_range:
port range
==========
**yaml value**: mix
A consequent range of ip ports. It consists of 2 fields:
* start
**required**, **type**: u16, **inclusive**
The start of the port range. Should be greater than zero.
* end
**required**, **type**: u16, **inclusive**
The end of the port range. Should be greater than *start*.
The yaml value for *port range* can be in the following formats:
* str
In format <start>-<end>. Extra whitespaces is allowed.
* map
The keys of this map are the fields as described above.
.. _conf_value_socket_buffer_config:
socket buffer config
====================
**yaml value**: mix
It consists of 2 fields:
* recv
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set the recv buf size.
**default**: not set
* send
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set the send buf size.
**default**: not set
The yaml value for *socket buffer config* can be in the following formats:
* int | string
The value will be set for both **recv** and **send** fields above.
* map
The keys of this map are the fields as described above.
.. _conf_value_tcp_listen:
tcp listen
==========
**yaml value**: mix
It consists of 4 fields:
* address
**required**, **type**: :ref:`sockaddr str <conf_value_sockaddr_str>`
Set the listen socket address.
**default**: [::]:0, which has empty port
* backlog
**optional**, **type**: unsigned int
Set the listen backlog number for tcp sockets. The default value will be used if the specified value is less than 8.
**default**: 4096
.. note::
If the backlog argument is greater than the value in /proc/sys/net/core/somaxconn, then it is silently truncated
to that value. Since Linux 5.4, the default in this file is 4096; in earlier kernels, the default value is 128.
* ipv6_only
**optional**, **type**: bool
Listen only to ipv6 address only if address is set to [::].
**default**: false
* instance
**optional**, **type**: int
Set how many listen instances. If *scale* is set, this will be the least value.
**default**: 1
* scale
**optional**, **type**: float | string
Set the listen instance count scaled according to available parallelism.
For string value, it could be in percentage (n%) or fractional (n/d) format.
Example:
.. code-block:: yaml
scale: 1/2
# or
scale: 0.5
# or
scale: 50%
**default**: 0
.. versionadded:: 1.7.8
The yaml value for *listen* can be in the following formats:
* int
Set the port only.
* :ref:`sockaddr str <conf_value_sockaddr_str>`
Set ip and port. The port field is required.
* map
The keys of this map are the fields as described above.
.. _conf_value_tcp_connect:
tcp connect
===========
**yaml value**: map
This set TCP connect params.
It consists of 2 fields:
* max_retry
**optional**, **type**: int
Set the max tcp connect retry for a single upstream connection of the same address family.
The total tcp connect tries will be *1 + max_retry*.
Each resolved IP addr will be tried at most once.
**default**: 2, which means the total tries is 3
* each_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the max timeout for each connection to the resolved addr of the upstream.
**default**: 30s
.. _conf_value_happy_eyeballs:
happy eyeballs
==============
**yaml value**: map
This set Happy Eyeballs params for multiple tcp connections.
It consists of the following fields:
* resolution_delay
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
The resolution delay time for the wait of the preferred address family after another one is returned.
**default**: 50ms
* second_resolution_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
The timeout time for the wait of the second resolution after no running connection attempts.
**default**: 2s
* first_address_family_count
**optional**, **type**: usize
The address to try before use the addresses from another address family.
**default**: 1
* connection_attempt_delay
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
The delay time before start a new connection after the previous one.
**default**: 250ms, **min**: 100ms, **max**: 2s
.. versionadded:: 1.5.3
.. _conf_value_tcp_keepalive:
tcp keepalive
=============
**yaml value**: mix
This set TCP level keepalive settings.
It consists of 2 fields:
* enable
**optional**, **type**: bool
Set whether tcp keepalive should be enabled.
**default**: false, which means you can set limit on other values in case keepalive is needed somewhere
* idle_time
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the keepalive idle time.
**default**: 60s
* probe_interval
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the probe interval after idle.
**default**: not set, which means the OS default value will be used
* probe_count
**optional**, **type**: u32
Set the probe count.
**default**: not set, which means the OS default value will be used
If the root value type is bool, the value will be parsed the same as the *enable* key.
If the root value type is not map and not bool, the value will be parsed the same as the *idle_time* key, but with
*enable* set to true.
.. _conf_value_tcp_misc_sock_opts:
tcp misc sock opts
==================
**yaml value**: map
This set misc tcp socket options.
Keys:
* no_delay
**optional**, **type**: bool
Set value for tcp level socket option TCP_NODELAY. If set to true, disable the Nagle algorithm.
**default**: the default value varies, check the doc of the outer option
* mss
**optional**, **type**: u32, **alias**: max_segment_size
Set value for tcp level socket option TCP_MAXSEG, the maximum segment size for outgoing TCP packets.
**default**: not set
* ttl
**optional**, **type**: u32, **alias**: time_to_live
Set value for ip level socket option IP_TTL, the time-to-live field in each sent packet.
**default**: not set
* tos
**optional**, **type**: u8, **alias**: type_of_service
Set value for ip level socket option IP_TOS, the type-of-service field in each sent packet.
**default**: not set
* mark
**optional**, **type**: u32, **alias**: netfilter_mark
Set value for socket level socket option SO_MARK, the netfilter mark value for our tcp sockets.
**default**: not set
.. _conf_value_udp_misc_sock_opts:
udp misc sock opts
==================
**yaml value**: map
This set misc udp socket options.
Keys:
* ttl
**optional**, **type**: u32, **alias**: time_to_live
Set value for ip level socket option IP_TTL, the time-to-live field in each sent packet.
**default**: not set
* tos
**optional**, **type**: u8, **alias**: type_of_service
Set value for ip level socket option IP_TOS, the type-of-service field in each sent packet.
**default**: not set
* mark
**optional**, **type**: u32, **alias**: netfilter_mark
Set value for socket level socket option SO_MARK, the netfilter mark value for our tcp sockets.
**default**: not set
.. _conf_value_http_header_name:
http header name
================
**yaml value**: str
This string should be a valid HTTP header name.
.. _conf_value_http_keepalive:
http keepalive
==============
**yaml value**: mix
This set HTTP level keepalive settings.
It consists of 2 fields:
* enable
**optional**, **type**: bool
Set whether tcp keepalive should be enabled.
**default**: true
* idle_expire
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the idle expire time for the saved connection.
If the last active time for the connection has elapsed, the connection will be dropped.
**default**: 60s
If the root value type is bool, the value will be parsed the same as the *enable* key.
If the root value type is not map and not bool, the value will be parsed the same as the *idle_expire* key, but with
*enable* set to true.
.. _conf_value_http_forwarded_header_type:
http forwarded header type
==========================
**yaml value**: str | bool
This set the header type we set in requests for identifying the originating IP address of a client connected to us.
The string values are:
* none
Do not set any header.
* classic
Use the de-facto standard header *X-Forwarded-For*, this is widely used.
* standard
Use the standard header *Forwarded* defined in rfc7239. We set both the *for* and the *by* parameter in this case.
If the yaml value type is bool, *true* will be *classic*, and *false* will be none.
.. _conf_value_http_forward_capability:
http forward capability
=======================
**yaml value**: map
The following fields can be set:
* forward_https
**optional**, **type**: bool
Whether we should forward request of https url to next proxy.
If not, we will do tls handshake with upstream locally.
**default**: false
* forward_ftp
**optional**, **type**: bool
Whether we should forward all requests of ftp url to next proxy.
If not, we will act as a ftp client.
It can be overwritten by the specific forward_ftp_* options as described below for the corresponding http methods.
**default**: false
* forward_ftp_get
**optional**, **type**: bool
Whether we should forward the GET request of ftp url to next proxy.
If not, we will act as a ftp client.
**default**: false
* forward_ftp_put
**optional**, **type**: bool
Whether we should forward the PUT request of ftp url to next proxy.
If not, we will act as a ftp client.
**default**: false
* forward_ftp_del
**optional**, **type**: bool
Whether we should forward the DELETE request of ftp url to next proxy.
If not, we will act as a ftp client.
**default**: false
.. _conf_value_http_server_id:
http server id
==============
**yaml value**: str
Set http server id (server name) for http forwarding services.
All characters should be ASCII in range '0x20' - '0x7E', except for ';' and ','.
.. _conf_value_proxy_protocol_version:
proxy protocol version
======================
**yaml value**: u8
Set the PROXY protocol version.
We support version 1 and version 2 for outgoing tcp connections.
.. _conf_value_ftp_control_config:
ftp control config
==================
**yaml value**: map
The following fields can be set:
* max_line_len
**optional**, **type**: usize
Set the max line length.
**default**: 2048
* max_multi_lines
**optional**, **type**: usize
Set the max lines for multi-line reply.
**default**: 128
* command_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the general command timeout value for commands with no explicit timeout config.
**default**: 10s
.. _conf_value_ftp_transfer_config:
ftp transfer config
===================
**yaml value**: map
The following fields can be set:
* list_max_line_len
**optional**, **type**: usize
Set the max line length for list reply.
**default**: 2048
* list_max_entries
**optional**, **type**: usize
Set the max lines will be handled in list reply.
**default**: 1024
* list_all_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the timeout value for listing.
**default**: 120s, **max**: 300s
* end_wait_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the timeout value when waiting for the end of the transfer action at both the control and the transfer channel.
**default**: 10s
.. _conf_value_ftp_client_config:
ftp client config
=================
**yaml value**: map
The following fields can be set:
* control
**optional**, **type**: :ref:`ftp control config <conf_value_ftp_control_config>`
Set config for the ftp control channel.
* transfer
**optional**, **type**: :ref:`ftp transfer config <conf_value_ftp_transfer_config>`
Set config for the ftp transfer channels.
* connect_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the connection timeout for both control and transfer channels.
**default**: 30s
* greeting_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the timeout for waiting of the greeting message from the server.
**default**: 10s
* always_try_epsv
**optional**, **type**: bool
Set if we should always try EPSV command even server doesn't set it in feature.
**default**: true
.. _conf_value_dns_encryption_protocol:
dns encryption protocol
=======================
**yaml value**: enum
The followings values are supported:
* dns-over-tls | dot | tls
If `dns over tls`_ should be used.
.. _dns over tls: https://datatracker.ietf.org/doc/html/rfc7858
* dns-over-https | doh | https
If `dns over https`_ should be used.
.. _dns over https: https://datatracker.ietf.org/doc/html/rfc8484
.. _conf_value_dns_encryption_config:
dns encryption config
=====================
**yaml value**: map | str
The following fields can be set:
* tls_name
**required**, **type**: :ref:`tls name <conf_value_tls_name>`
Set the tls server name.
* protocol
**optional**, **type**: :ref:`dns encryption protocol <conf_value_dns_encryption_protocol>`
Set the encryption protocol.
**default**: dns-over-tls
* tls_client
**optional**, **type**: :ref:`rustls client config <conf_value_rustls_client_config>`
Set the tls client config.
.. note:: not all fields will be used, check the doc of each key has the value *dns encryption config*.
**default**: not set
If in str format, the value will be treated as field *tls_name*.
.. versionadded:: 1.1.4
.. _conf_value_proxy_request_type:
proxy request type
==================
**yaml type**: enum string
The values are:
* HttpForward
* HttpsForward
* FtpOverHttp
* HttpConnect
* SocksTcpConnect
* SocksUdpAssociate

176
g3proxy/doc/configuration/values/rate_limit.rst Normal file
View file

@ -0,0 +1,176 @@
.. _configure_rate_limit_value_types:
**********
Rate Limit
**********
.. _conf_value_tcp_sock_speed_limit:
tcp socket speed limit
======================
**yaml value**: mix
It consists of 3 fields:
* shift_millis | shift
**type**: int
The time slice we use to count is *2 ^ N* milliseconds, where N is set by this key and should be in range [0 - 12].
If N is 10, and the time slice is 1024ms. If omitted, this means the limit is not set.
* upload | north | upload_bytes | north_bytes
**type**: :ref:`humanize usize <conf_value_humanize_usize>`
This sets the upload bytes in the time slice. *0* means delay forever.
* download | south | download_bytes | south_bytes
**type**: :ref:`humanize usize <conf_value_humanize_usize>`
This set the max download bytes in the time slice. *0* means delay forever.
The yaml value for *tcp_sock_speed_limit* can be in varies formats:
* :ref:`humanize usize <conf_value_humanize_usize>`
This will set upload and download to the same value, with shift_millis set to 10.
* map
The keys of this map are the fields as described above.
.. _conf_value_udp_sock_speed_limit:
udp socket speed limit
======================
**yaml value**: mix
It consists of 4 fields:
* shift_millis | shift
**type**: int
The time slice we use to count is *2 ^ N* milliseconds, where N is set by this key and should be in range [0 - 12].
If N is 10, and the time slice is 1024ms. If omitted, this means the limit is not set.
* upload_bytes | north_bytes
**type**: :ref:`humanize usize <conf_value_humanize_usize>`
This sets the upload bytes in the time slice. *0* means no limit.
* download_bytes | south_bytes
**type**: :ref:`humanize usize <conf_value_humanize_usize>`
This set the max download bytes in the time slice. *0* means no limit.
* upload_packets | north_packets
**type**: int [usize]
This set the max upload packets in the time slice. *0* means no limit.
* download_packets | south_packets
**type**: int [usize]
This set the max download packets in the time slice. *0* means no limit.
The yaml value for *udp_sock_speed_limit* can be in varies formats:
* :ref:`humanize usize <conf_value_humanize_usize>`
This will set upload and download bytes to the same value, set shift_millis to 10 and disable check on packets.
* map
The keys of this map are the fields as described above.
.. _conf_value_request_limit:
request limit
=============
**yaml value**: mix
It consists of 2 fields:
* shift_millis | shift
**type**: int
The time slice we use to count is *2 ^ N* milliseconds, where N is set by this key and should be in range [0 - 12].
If N is 10, and the time slice is 1024ms. If omitted, this means the limit is not set.
* requests
**type**: usize
This sets the max requests in the time slice. 0 is not allowed.
.. _conf_value_rate_limit_quota:
rate limit quota
================
**yaml value**: mix
It consists of 3 fields:
* rate
**type**: :ref:`nonzero u32 <conf_value_nonzero_u32>`
If int or str without any unit, the default unit will be per second.
Supported units for str:
- /s, per second
- /m, per minute
- /h, per hour
* replenish_interval
**type**: :ref:`humanize duration <conf_value_humanize_duration>`
Construct a quota that replenishes one cell in a given interval. The default max_burst value is 1 is its not specified
along with this option.
* max_burst
Adjusts the maximum burst size for a quota to construct a rate limiter with a capacity
for at most the given number of cells
.. note:: *rate* and *replenish_interval* is conflict with each other, the latter one in conf will take effect.
The yaml value for *u32 limit quota* can be in varies formats:
* simple rate
Just the rate value. The max_burst value is the same as the one set in the rate.
* map
The keys of this map are the fields as described above.
.. _conf_value_random_ratio:
random ratio
============
**yaml value**: f64 | str | bool | integer
Set a random ratio between 0.0 and 1.0 (inclusive).
For *str* value, it can be in fraction form (n/d), in percentage form (n%), or just a float string.
For *bool* value, *false* means 0.0, *true* means 1.0.
For *integer* value, only 0 and 1 is allowed.

89
g3proxy/doc/configuration/values/resolve.rst Normal file
View file

@ -0,0 +1,89 @@
.. _configure_resolve_value_types:
*******
Resolve
*******
.. _conf_value_resolve_strategy:
Resolve Strategy
================
**yaml value**: mix
The *Resolve Strategy* config is not for resolvers, but for the users of resolvers.
The type for this is *map*, which consists of keys as follows:
query
-----
**optional**, **type**: enum str
The query strategy, which will be used by the resolver while resolving.
The value should be:
* Ipv4Only
* Ipv6Only
* Ipv4First (default)
* Ipv6First
pick
----
**optional**, **type**: enum str
The pick strategy, which will be used when selecting the best ip address from all the results.
The value should be:
* Random (default)
* First
.. _conf_value_resolve_redirection:
Resolve Redirection
===================
**yaml value**: mix
The *Resolve Redirection* config is not for resolvers, but for the users of resolvers.
The type for this could be *seq*, which consists of many rules of type
:ref:`resolve redirection rule <conf_value_resolve_redirection_rule>`.
The type for this could also be *map*, in such case, each kv pair will be one rule,
with the key as it's *exact* value, and the value as it's *to* value.
.. _conf_value_resolve_redirection_rule:
Resolve Redirection Rule
------------------------
Each rule should be a map with the following keys:
* exact
**required**: false, **type**: :ref:`domain <conf_value_domain>`
Set the exact domain to replace.
* parent
**required**: false, **type**: :ref:`domain <conf_value_domain>`
Set the parent domain to replace.
* to
**required**: true, **type**: mix
Set the replacement value for the match.
For *exact* match, the value should be :ref:`host <conf_value_host>` or an array of ip addresses.
For *parent* match, the value should be :ref:`domain <conf_value_domain>`.
Either *exact* or *parent* should be set for the rule.

75
g3proxy/doc/configuration/values/route.rst Normal file
View file

@ -0,0 +1,75 @@
.. _configure_route_value_types:
*****
Route
*****
.. _conf_value_host_matched_object:
Host Matched Object
===================
**yaml value**: map | seq of map
This set a host based match object for generic type T, which will be specified in the real config options.
The yaml value for T will be a map, but with the following keys as reserved as they are used by the match rules:
* exact_match
**optional**, **type**: :ref:`host <conf_value_host>`
Match if this is the exact host.
* child_match
**optional**, **type**: :ref:`domain <conf_value_domain>`
Match if the target host is a child domain of this parent domain.
* set_default
**optional**, **type**: bool
If true, also set this T as default value
**default**: false
If none of the above keys found, the parsed T value will also be used as the default value.
A match object can contains one or more T(s), which means the yaml type for this object could be a single T,
or a sequence of T.
Only a single T is allowed for each match rules, including the default one.
.. _conf_value_uri_path_matched_object:
Uri Path Matched Object
=======================
**yaml value**: map | seq of map
This set a url path based match object for generic type T, which will be specified in the real config options.
The yaml value for T will be a map, but with the following keys as reserved as they are used by the match rules:
* prefix_match
**optional**, **type**: str
Match if the target url path has this prefix.
* set_default
**optional**, **type**: bool
If true, also set this T as default value
**default**: false
If none of the above keys found, the parsed T value will also be used as the default value.
A match object can contains one or more T(s), which means the yaml type for this object could be a single T,
or a sequence of T.
Only a single T is allowed for each match rules, including the default one.

81
g3proxy/doc/configuration/values/runtime.rst Normal file
View file

@ -0,0 +1,81 @@
.. _configure_runtime_value_types:
*******
Runtime
*******
.. _conf_value_cpu_set:
cpu set
=======
**yaml value** seq | usize
A `CPU_SET(3)`_ for use with `sched_setaffinity(2)`_.
The value should be a CPU ID, starting from 0, or a sequence of CPU IDs.
.. _CPU_SET(3): https://man7.org/linux/man-pages/man3/CPU_SET.3.html
.. _sched_setaffinity(2): https://man7.org/linux/man-pages/man2/sched_setaffinity.2.html
.. versionadded:: 1.3.1
.. _conf_value_unaided_runtime_config:
unaided runtime config
======================
**yaml value**: map
This is the config for unaided runtime.
The keys are:
thread_number
-------------
**optional**, **type**: usize
Set the thread number.
**default**: the number of logic CPU cores
thread_stack_size
-----------------
**optional**, **type**: :ref:`humanize usize <conf_value_humanize_usize>`
Set the stack size for worker threads. For *<int>* value, the unit is bytes.
**default**: system default
sched_affinity
--------------
**optional**, **type**: map | bool
Set the sched affinity for each threads.
For map value, the key should be the thread id starting from 0, and the value should be :ref:`cpu set <conf_value_cpu_set>`.
For bool value:
* if true, a default CPU SET will be set for each thread, the CPU ID in the set will match the thread ID.
* if false, no sched affinity will be set, just as if this config option is not present.
**default**: no sched affinity set
.. versionadded:: 1.3.1
max_io_events_per_tick
----------------------
**optional**, **type**: usize
Configures the max number of events to be processed per tick.
**default**: 1024, tokio default value
.. versionadded:: 1.7.6

405
g3proxy/doc/configuration/values/tls.rst Normal file
View file

@ -0,0 +1,405 @@
.. _configure_tls_value_types:
***
TLS
***
.. _conf_value_tls_name:
tls name
========
**yaml type**: string
Set the dns name / ip address for server certificate verification.
If not set, the corresponding peer address will be used.
.. note:: IP address is not supported by now
.. _conf_value_tls_certificates:
tls certificates
================
**yaml type**: :ref:`file <conf_value_file>` | seq
Set the certificate file(s), which should be in PEM format(`openssl-req(1)`_).
If relative, it will be searched in the directory that contains current config file.
.. _openssl-req(1): https://www.openssl.org/docs/manmaster/man1/openssl-req.html
.. _conf_value_tls_private_key:
tls private_key
===============
**yaml type**: :ref:`file <conf_value_file>`
Set the private key file, which should be in PKCS#8(`openssl-genpkey(1)`_) or traditional PEM format.
If relative, it will be searched in the directory that contains current config file.
The last one in the file will be used if many keys are found.
.. versionchanged:: support traditional PEM format since version 1.3.2
.. _openssl-genpkey(1): https://www.openssl.org/docs/manmaster/man1/openssl-genpkey.html
.. _conf_value_tls_cert_pair:
tls cert pair
=============
**yaml value**: map
A pair value contains tls certificate and private key.
The keys are:
* certificate
**required**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
Set client certificates if client auth is needed by remote server.
Private key must also be set if client auth is needed.
**default**: not set
* private_key
**required**, **type**: :ref:`tls private_key <conf_value_tls_private_key>`
Set the private key for client if client auth is needed by remote server.
Client certificates are also needed if client auth is needed.
**default**: not set
.. versionadded:: 1.7.7
.. _conf_value_openssl_protocol:
openssl protocol
================
**yaml value**: string
Set openssl protocol version.
Current supported values are:
- tls1.2
- tls1.3
.. versionadded:: 1.7.7
.. _conf_value_openssl_ciphers:
openssl ciphers
===============
**yaml value**: string or seq
Set openssl cipher list or ciphersuites for the specified protocol.
Values can be obtained from `openssl ciphers -v` command.
For string value, it can be ciphers joined by ':'.
For seq value, each one should be a cipher string.
.. versionadded:: 1.7.7
.. _conf_value_openssl_tls_client_config:
openssl tls client config
=========================
**yaml value**: map
The tls config to be used as a tls client.
The map is consists of the following fields:
* protocol
**optional**, **type**: :ref:`openssl protocol <conf_value_openssl_protocol>`
Set to use a specific protocol version.
**default**: not set
.. versionadded:: 1.7.7
* ciphers
**optional**, **type**: :ref:`openssl ciphers <conf_value_openssl_ciphers>`
**require**: protocol
Set to use a specific set of ciphers for the specified protocol version.
**default**: not set
.. versionadded:: 1.7.7
* disable_sni
**optional**, **type**: bool
Whether to send the Server Name Indication (SNI) extension during the client handshake.
**default**: false
* cert_pair
**optional**, **type**: :ref:`tls cert pair <conf_value_tls_cert_pair>`
**conflict**: certificate, private_key
Set the client certificate and private key pair.
**default**: not set
.. versionadded:: 1.7.7
* certificate
**optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
**conflict**: cert_pair
Set client certificates if client auth is needed by remote server.
Private key must also be set if client auth is needed.
**default**: not set
* private_key
**optional**, **type**: :ref:`tls private_key <conf_value_tls_private_key>`
**conflict**: cert_pair
Set the private key for client if client auth is needed by remote server.
Client certificates are also needed if client auth is needed.
**default**: not set
* ca_certificate | server_auth_certificate
**optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
A list of certificates for server auth. If not set, the system default ca certificates will be used.
**default**: not set
* no_default_ca_certificate
**optional**, **type**: bool
Set if you don't want to load default ca certificates.
**default**: false
* handshake_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the tls handshake timeout value.
**default**: 10s
* no_session_cache
**optional**, **type**: bool
Set if you want to disable cache of TLS sessions.
**default**: false
* use_builtin_session_cache
**optional**, **type**: bool
Set if we should use OpenSSL builtin session cache.
**default**: false
.. versionadded:: 1.7.7
* session_cache_lru_max_sites
**optional**, **type**: usize
Set how many LRU sites should have cached sessions.
Only in use if this tls client is used by many sites.
**default**: 128
* session_cache_each_capacity
**optional**, **type**: usize
Set how many sessions should be kept for each site.
**default**: 16
.. versionadded:: 1.1.4
.. _conf_value_rustls_client_config:
rustls client config
====================
**yaml value**: map
The tls config to be used as a tls client.
The map is consists of the following fields:
* no_session_cache
**optional**, **type**: bool
Set if you want to disable cache of TLS sessions.
**default**: false
.. versionadded:: 1.1.4
* disable_sni
**optional**, **type**: bool
Whether to send the Server Name Indication (SNI) extension during the client handshake.
**default**: false
.. versionadded:: 1.1.4
* max_fragment_size
**optional**, **type**: usize
Set the maximum size of TLS message we'll emit.
**default**: default value in tls driver
* cert_pair
**optional**, **type**: :ref:`tls cert pair <conf_value_tls_cert_pair>`
**conflict**: certificate, private_key
Set the client certificate and private key pair.
**default**: not set
.. versionadded:: 1.7.8
* certificate
**optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
Set client certificates if client auth is needed by remote server.
Private key must also be set if client auth is needed.
**default**: not set
* private_key
**optional**, **type**: :ref:`tls private_key <conf_value_tls_private_key>`
Set the private key for client if client auth is needed by remote server.
Client certificates are also needed if client auth is needed.
**default**: not set
* ca_certificate | server_auth_certificate
**optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
A list of certificates for server auth. If not set, the system default ca certificates will be used.
**default**: not set
* no_default_ca_certificate
**optional**, **type**: bool
Set if you don't want to load default ca certificates.
**default**: false
.. versionadded:: 1.1.4
* use_builtin_ca_certificate
**optional**, **type**: bool
Set to true if you want to use built in webpki-roots ca certificates as default ca certificates.
**default**: false
* handshake_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the tls handshake timeout value.
**default**: 10s
.. _conf_value_rustls_server_config:
rustls server config
====================
**yaml value**: map
The tls config to be used as a tls server.
The map is consists of the following fields:
* cert_pairs
**optional**, **type**: :ref:`tls cert pair <conf_value_tls_cert_pair>` or seq
Set certificate and private key pairs for this TLS server.
.. note:: At least set this or certificate & private_key.
.. versionadded:: 1.7.8
* certificate
**optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
Set the certificates for this TLS server.
.. note:: At least set this or cert_pairs
* private_key
**optional**, **type**: :ref:`tls private_key <conf_value_tls_private_key>`
Set the private key for this TLS server.
.. note:: At least set this or cert_pairs
* enable_client_auth
**optional**, **type**: bool
Set if you want to enable client auth.
* ca_certificate | client_auth_certificate
**optional**, **type**: :ref:`tls certificates <conf_value_tls_certificates>`
A list of certificates for client auth. If not set, the system default ca certificates will be used.
**default**: not set
* handshake_timeout
**optional**, **type**: :ref:`humanize duration <conf_value_humanize_duration>`
Set the tls handshake timeout value.
**default**: 10s