.. _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_static_sockaddr_str:

static sockaddr str
===================

**yaml value**: str

The string should be in *@<domain>:<port>* or *@<ip>:<port>* format.

It is different from :ref:`upstream str <conf_value_upstream_str>` as:

- It will be resolved when we load the config files
- The domain is only allowed to be resolved to just 1 IP address

.. _conf_value_env_sockaddr_str:

env sockaddr str
================

**yaml value**: :ref:`sockaddr str <conf_value_sockaddr_str>` or :ref:`static sockaddr str <conf_value_static_sockaddr_str>` or :ref:`env var <conf_value_env_var>`

The string should be in *<ip>[:<port>]* format, in which the port may be omitted if a default value is available.

.. versionadded:: 1.7.31

.. _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 the following fields:

* address

  **required**, **type**: :ref:`env sockaddr str <conf_value_env_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.

* netfilter_mark

  **optional**, **type**: unsigned int

  Set the netfilter mark (SOL_SOCKET, SO_MARK) value for the listening socket. If this field not present,
  the mark value will not be touch. This value can be used for advanced routing policy or netfilter rules.

* 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_udp_listen:

udp listen
==========

**yaml value**: mix

It consists of the following fields:

* address

  **required**, **type**: :ref:`env sockaddr str <conf_value_env_sockaddr_str>`

  Set the listen socket address.

  **default**: [::]:0, which has empty port

* ipv6_only

  **optional**, **type**: bool

  Listen only to ipv6 address only if address is set to [::].

  **default**: false

* socket_buffer

  **optional**, **type**: :ref:`socket buffer config <conf_value_socket_buffer_config>`

  Set an explicit socket buffer config.

  **default**: not set

* socket_misc_opts

  **optional**, **type**: :ref:`udp misc sock opts <conf_value_udp_misc_sock_opts>`

  Set misc UDP socket options.

  **default**: not set

* 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

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.

.. versionadded:: 1.7.30

.. _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

* dns-over-http/3 | doh3 | h3

  If *dns over http/3* should be used.

* dns-over-quic | doq | quic

  If `dns over quic`_ should be used.

.. _dns over quic: https://datatracker.ietf.org/doc/html/rfc9250

.. versionchanged:: added dns over quic support since version 1.7.15

.. versionchanged:: added dns over http/3 support since version 1.7.27

.. _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