From: Willy Tarreau Date: Wed, 14 May 2025 13:39:15 +0000 (+0200) Subject: DOC: config: move address formats definition to section 2 X-Git-Tag: v3.2-dev16~9 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=423dffa308a73bca87e7456ae57e80ce4163df6c;p=thirdparty%2Fhaproxy.git DOC: config: move address formats definition to section 2 Section 2 describes the config file format, variables naming etc, so there's no reason why the address format used in this file should be in a separate section, let's bring it into section 2 as well. --- diff --git a/doc/configuration.txt b/doc/configuration.txt index 42cacddf7..0166e2d9a 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -46,7 +46,11 @@ Summary 2.6. Size format 2.7. Name format for maps and ACLs 2.8. Variables -2.9. Examples +2.9. Address formats +2.9.1. Address family prefixes +2.9.2. Socket type prefixes +2.9.3. Protocol prefixes +2.10. Examples 3. Global parameters 3.1. Process management and security @@ -142,11 +146,6 @@ Summary 10.2. Default parameters 10.3. Limitations -11. Address formats -11.1. Address family prefixes -11.2. Socket type prefixes -11.3. Protocol prefixes - 1. Quick reminder about HTTP ---------------------------- @@ -1454,7 +1453,198 @@ true when variables are compared to static value. The right matching method must be used. -2.9. Examples +2.9. Address formats +-------------------- + +Several statements as "bind, "server", "nameserver" and "log" requires an +address. + +This address can be a host name, an IPv4 address, an IPv6 address, or '*'. +The '*' is equal to the special address "0.0.0.0" and can be used, in the case +of "bind" or "dgram-bind" to listen on all IPv4 of the system.The IPv6 +equivalent is '::'. + +Depending of the statement, a port or port range follows the IP address. This +is mandatory on 'bind' statement, optional on 'server'. + +This address can also begin with a slash '/'. It is considered as the "unix" +family, and '/' and following characters must be present the path. + +Default socket type or transport method "datagram" or "stream" depends on the +configuration statement showing the address. Indeed, 'bind' and 'server' will +use a "stream" socket type by default whereas 'log', 'nameserver' or +'dgram-bind' will use a "datagram". + +Optionally, a prefix could be used to force the address family and/or the +socket type and the transport method. + + +2.9.1. Address family prefixes +------------------------------ + +'abns@' following is an abstract namespace (Linux only). + +'abnsz@' following is a zero-terminated abstract namespace + (Linux only). + +'fd@' following address is a file descriptor inherited from the + parent. The fd must be bound and may or may not already be + listening. + +'ip@
[:port1[-port2]]' following
is considered as an IPv4 or + IPv6 address depending on the syntax. Depending + on the statement using this address, a port or + a port range may or must be specified. + +'ipv4@
[:port1[-port2]]' following
is always considered as + an IPv4 address. Depending on the statement + using this address, a port or a port range + may or must be specified. + +'ipv6@
[:port1[-port2]]' following
is always considered as + an IPv6 address. Depending on the statement + using this address, a port or a port range + may or must be specified. + +'sockpair@' following address is the file descriptor of a connected unix + socket or of a socketpair. During a connection, the initiator + creates a pair of connected sockets, and passes one of them + over the FD to the other end. The listener waits to receive + the FD from the unix socket and uses it as if it were the FD + of an accept(). Should be used carefully. + +'unix@' following string is considered as a UNIX socket . this + prefix is useful to declare an UNIX socket path which don't + start by slash '/'. + + +2.9.2. Socket type prefixes +--------------------------- + +Previous "Address family prefixes" can also be prefixed to force the socket +type and the transport method. The default depends of the statement using +this address but in some cases the user may force it to a different one. +This is the case for "log" statement where the default is syslog over UDP +but we could force to use syslog over TCP. + +Those prefixes were designed for internal purpose and users should instead use +use aliases of the next section "2.9.3 Protocol prefixes". However these can +sometimes be convenient, for example in combination with inherited sockets +known by their file descriptor number, in which case the address family is "fd" +and the socket type must be declared. + +If users need one those prefixes to perform what they expect because +they can not configure the same using the protocol prefixes, they should +report this to the maintainers. + +'stream+@
' forces socket type and transport method + to "stream" + +'dgram+@
' forces socket type and transport method + to "datagram". + +'quic+@
' forces socket type to "datagram" and transport + method to "stream". + + + +2.9.3. Protocol prefixes +------------------------ + +'quic4@
[:port1[-port2]]' following
is always considered as + an IPv4 address but socket type is forced to + "datagram" and the transport method is forced + to "stream". Depending on the statement using + this address, a UDP port or port range can or + must be specified. It is equivalent to + "quic+ipv4@". + +'quic6@
[:port1[-port2]]' following
is always considered as + an IPv6 address but socket type is forced to + "datagram" and the transport method is forced + to "stream". Depending on the statement using + this address, a UDP port or port range can or + must be specified. It is equivalent to + "quic+ipv6@". + +'tcp@
[:port1[-port2]]' following
is considered as an IPv4 + or IPv6 address depending of the syntax but + socket type and transport method is forced to + "stream". Depending on the statement using + this address, a port or a port range can or + must be specified. It is considered as an alias + of 'stream+ip@'. + +'tcp4@
[:port1[-port2]]' following
is always considered as + an IPv4 address but socket type and transport + method is forced to "stream". Depending on the + statement using this address, a port or port + range can or must be specified. + It is considered as an alias of 'stream+ipv4@'. + +'tcp6@
[:port1[-port2]]' following
is always considered as + an IPv6 address but socket type and transport + method is forced to "stream". Depending on the + statement using this address, a port or port + range can or must be specified. + It is considered as an alias of 'stream+ipv4@'. + +'mptcp@
[:port1[-port2]]' following
is considered as an IPv4 + or IPv6 address depending of the syntax but + socket type and transport method is forced to + "stream", with the MPTCP protocol. Depending + on the statement using this address, a port or + a port range can or must be specified. + +'mptcp4@
[:port1[-port2]]' following
is always considered as + an IPv4 address but socket type and transport + method is forced to "stream", with the MPTCP + protocol. Depending on the statement using + this address, a port or port range can or + must be specified. + +'mptcp6@
[:port1[-port2]]' following
is always considered as + an IPv6 address but socket type and transport + method is forced to "stream", with the MPTCP + protocol. Depending on the statement using + this address, a port or port range can or + must be specified. + +'udp@
[:port1[-port2]]' following
is considered as an IPv4 + or IPv6 address depending of the syntax but + socket type and transport method is forced to + "datagram". Depending on the statement using + this address, a port or a port range can or + must be specified. It is considered as an alias + of 'dgram+ip@'. + +'udp4@
[:port1[-port2]]' following
is always considered as + an IPv4 address but socket type and transport + method is forced to "datagram". Depending on + the statement using this address, a port or + port range can or must be specified. + It is considered as an alias of 'dgram+ipv4@'. + +'udp6@
[:port1[-port2]]' following
is always considered as + an IPv6 address but socket type and transport + method is forced to "datagram". Depending on + the statement using this address, a port or + port range can or must be specified. + It is considered as an alias of 'dgram+ipv4@'. + +'uxdg@' following string is considered as a unix socket but + transport method is forced to "datagram". It is considered as + an alias of 'dgram+unix@'. + +'uxst@' following string is considered as a unix socket but + transport method is forced to "stream". It is considered as + an alias of 'stream+unix@'. + +In future versions, other prefixes could be used to specify protocols like +QUIC which proposes stream transport based on socket of type "datagram". + + +2.10. Examples ------------- # Simple configuration for an HTTP proxy listening on port 80 on all @@ -29971,195 +30161,6 @@ must not exceeds the size of a buffer. However, there is no reserve to respect here. -11. Address formats -------------------- - -Several statements as "bind, "server", "nameserver" and "log" requires an -address. - -This address can be a host name, an IPv4 address, an IPv6 address, or '*'. -The '*' is equal to the special address "0.0.0.0" and can be used, in the case -of "bind" or "dgram-bind" to listen on all IPv4 of the system.The IPv6 -equivalent is '::'. - -Depending of the statement, a port or port range follows the IP address. This -is mandatory on 'bind' statement, optional on 'server'. - -This address can also begin with a slash '/'. It is considered as the "unix" -family, and '/' and following characters must be present the path. - -Default socket type or transport method "datagram" or "stream" depends on the -configuration statement showing the address. Indeed, 'bind' and 'server' will -use a "stream" socket type by default whereas 'log', 'nameserver' or -'dgram-bind' will use a "datagram". - -Optionally, a prefix could be used to force the address family and/or the -socket type and the transport method. - - -11.1. Address family prefixes ------------------------------ - -'abns@' following is an abstract namespace (Linux only). - -'abnsz@' following is a zero-terminated abstract namespace - (Linux only). - -'fd@' following address is a file descriptor inherited from the - parent. The fd must be bound and may or may not already be - listening. - -'ip@
[:port1[-port2]]' following
is considered as an IPv4 or - IPv6 address depending on the syntax. Depending - on the statement using this address, a port or - a port range may or must be specified. - -'ipv4@
[:port1[-port2]]' following
is always considered as - an IPv4 address. Depending on the statement - using this address, a port or a port range - may or must be specified. - -'ipv6@
[:port1[-port2]]' following
is always considered as - an IPv6 address. Depending on the statement - using this address, a port or a port range - may or must be specified. - -'sockpair@' following address is the file descriptor of a connected unix - socket or of a socketpair. During a connection, the initiator - creates a pair of connected sockets, and passes one of them - over the FD to the other end. The listener waits to receive - the FD from the unix socket and uses it as if it were the FD - of an accept(). Should be used carefully. - -'unix@' following string is considered as a UNIX socket . this - prefix is useful to declare an UNIX socket path which don't - start by slash '/'. - - -11.2. Socket type prefixes --------------------------- - -Previous "Address family prefixes" can also be prefixed to force the socket -type and the transport method. The default depends of the statement using -this address but in some cases the user may force it to a different one. -This is the case for "log" statement where the default is syslog over UDP -but we could force to use syslog over TCP. - -Those prefixes were designed for internal purpose and users should instead use -use aliases of the next section "11.3 Protocol prefixes". However these can -sometimes be convenient, for example in combination with inherited sockets -known by their file descriptor number, in which case the address family is "fd" -and the socket type must be declared. - -If users need one those prefixes to perform what they expect because -they can not configure the same using the protocol prefixes, they should -report this to the maintainers. - -'stream+@
' forces socket type and transport method - to "stream" - -'dgram+@
' forces socket type and transport method - to "datagram". - -'quic+@
' forces socket type to "datagram" and transport - method to "stream". - - - -11.3. Protocol prefixes ------------------------ - -'quic4@
[:port1[-port2]]' following
is always considered as - an IPv4 address but socket type is forced to - "datagram" and the transport method is forced - to "stream". Depending on the statement using - this address, a UDP port or port range can or - must be specified. It is equivalent to - "quic+ipv4@". - -'quic6@
[:port1[-port2]]' following
is always considered as - an IPv6 address but socket type is forced to - "datagram" and the transport method is forced - to "stream". Depending on the statement using - this address, a UDP port or port range can or - must be specified. It is equivalent to - "quic+ipv6@". - -'tcp@
[:port1[-port2]]' following
is considered as an IPv4 - or IPv6 address depending of the syntax but - socket type and transport method is forced to - "stream". Depending on the statement using - this address, a port or a port range can or - must be specified. It is considered as an alias - of 'stream+ip@'. - -'tcp4@
[:port1[-port2]]' following
is always considered as - an IPv4 address but socket type and transport - method is forced to "stream". Depending on the - statement using this address, a port or port - range can or must be specified. - It is considered as an alias of 'stream+ipv4@'. - -'tcp6@
[:port1[-port2]]' following
is always considered as - an IPv6 address but socket type and transport - method is forced to "stream". Depending on the - statement using this address, a port or port - range can or must be specified. - It is considered as an alias of 'stream+ipv4@'. - -'mptcp@
[:port1[-port2]]' following
is considered as an IPv4 - or IPv6 address depending of the syntax but - socket type and transport method is forced to - "stream", with the MPTCP protocol. Depending - on the statement using this address, a port or - a port range can or must be specified. - -'mptcp4@
[:port1[-port2]]' following
is always considered as - an IPv4 address but socket type and transport - method is forced to "stream", with the MPTCP - protocol. Depending on the statement using - this address, a port or port range can or - must be specified. - -'mptcp6@
[:port1[-port2]]' following
is always considered as - an IPv6 address but socket type and transport - method is forced to "stream", with the MPTCP - protocol. Depending on the statement using - this address, a port or port range can or - must be specified. - -'udp@
[:port1[-port2]]' following
is considered as an IPv4 - or IPv6 address depending of the syntax but - socket type and transport method is forced to - "datagram". Depending on the statement using - this address, a port or a port range can or - must be specified. It is considered as an alias - of 'dgram+ip@'. - -'udp4@
[:port1[-port2]]' following
is always considered as - an IPv4 address but socket type and transport - method is forced to "datagram". Depending on - the statement using this address, a port or - port range can or must be specified. - It is considered as an alias of 'dgram+ipv4@'. - -'udp6@
[:port1[-port2]]' following
is always considered as - an IPv6 address but socket type and transport - method is forced to "datagram". Depending on - the statement using this address, a port or - port range can or must be specified. - It is considered as an alias of 'dgram+ipv4@'. - -'uxdg@' following string is considered as a unix socket but - transport method is forced to "datagram". It is considered as - an alias of 'dgram+unix@'. - -'uxst@' following string is considered as a unix socket but - transport method is forced to "stream". It is considered as - an alias of 'stream+unix@'. - -In future versions, other prefixes could be used to specify protocols like -QUIC which proposes stream transport based on socket of type "datagram". /* * Local variables: