I am just tweaking TS-1077 now, it's functionally complete. I have pasted in a
write up I have for this patch, as it's a big one. Any additional commenting or
testing would be appreciated. Igor, if you could let me let me know if the
"External" section suffices for the admin docs...
TS-1077 Changes
External:
The primary purpose is to improve the configuration of HTTP proxy
ports. The previous configuration required the use of multiple interelated
values in the configuration file with different semantics and syntax. The new
style uses a single value
proxy.config.http.server_ports
to configure all HTTP ports, including SSL ports. The previous style is still
supported to ease the transition but it is now deprecated and is likely to be
removed at the next major release.
Ports are configured using _port descriptors_. The value for server_ports is a
space or comma separated list of these descriptors. Each descriptor is a
sequence of colon seperated keywords some of which may also have a value. The
value can directly follow the keyword or be separated by '=' for reading
convenience. The format was selected to be backwards compatible so that old
style specifications should continue to work.
The port is a special case. Any numeric value in a descriptor is
presumed to be the port value (host order). A port value *must* be provided in
every descriptor.
Keywords and values are case insensitive. Keywords are applied in left to right
order. Therefore the order is irrelevant in the absences of conflicts.
- ipv4
Bind the port to IPv4.
- ipv6
Bind the port to IPv6
- tr-in
Make the port inbound transparent.
- tr-out
Make the port outbound transparent.
- tr-full
Make the port inbound and outbound transparent. This is identical to
"tr-in:tr-out" and is provided for convenience.
- ssl
Make the port a terminated SSL connection.
- blind
Make the port a blind tunnel.
- compressed
Make the tunnel compressed.
- ip-in=
Bind the inbound (listening) port to the specified address. The address must
be enclosed in brackets '[]' if it is an IPv6 address. Brackets are optional
for IPv4 addresses. If this address is supplied the ipv4 and ipv6 options are
redundant but if present must agree with this value.
- ip-out=
Bind this local address for outbound connections to origin servers. The
address is specified as with ip-in. To specify both an IPv4 and IPv6 address
for outbound connections use this keyword twice, once for each family. The
address used for a specific connection is determined by the address family of
the origin server. It is an error to specify more than one outbound address per
family. This keyword has no relationship with the ipv4 and ipv6 keywords. This
option will override (disable) outbound transparency (tr-out, tr-full)
regardless of the keyword ordering.
The port descriptor ip-in and ip-out keywords override the global
incoming-ip-to-bind and outgoing-ip-to-bind values. If the former
(respectively) is not set then the latter is used and if neither is set, the
ANY (unspecified) address is used. To use the ANY address for a specific port
while using a specific address for all other ports the global option can be set
and the ANY address (0.0.0.0 for IPv4, [::] for IPv6) specified explicitly for
the appropriate port.
The -httpport / -p option has also been changed to parse this same format. This
is backwards compatible because a descriptor set of just "8080" means an IPv4
port on 8080. But it is now possible to configure ports from the command line
in exactly the same was as in the configuration file. If the command option is
used successfully (that is, the descriptor set is valid enough to describe at
least one port) then the configuration file is ignored[1].
[1] As a special case, if the configuration file has ssl.enabled set to 1, and
the command line has no SSL port, then one will be added.
Internal:
The handling of proxy port descriptions was unified in a new class,
HttpProxyPort, which replaces HttpEntryPoint and the hand rolled logic in the
Manager. HttpProxyPort is part of librecords as it is primarily a mechanism for
parsing configuration data.
In addition a hidden keyword "fd" was added to support specifying a file
descriptor along with all the other values. This enabled the -A option in the
Server to be removed along with all of the related specialized parsing. The
Manager now uses the --httpport option instead of -A in the same way (except
for the used of the 'fd' keyword) as a user. If a new option is added for the
configuration file and implemented in HttpProxyPort it will work for the
Manager to Server transition without further effort because Manager depends on
HttpProxyPort::toString to do the rendering for the command line option.
Internal parsing is also simplified as Server need only call the HttpProxyPort
parsing logic with either the command line argument or the configuration file
value. All other handling is identical. It is also identical between Manager
and Server.
A number of instances of ts_ip_endpoint were changed in InkInetAddr. This was
done in cases where the port and address are treated as separate entities,
particularly for configuration data. With ts_ip_endpoint there can be confusion
about where the port data is and how to store a port without an address or vice
versa. For data that will directly interact with the underlying socket calls is
kept as a ts_ip_endpoint.
The hardest implementation detail was passing the configuration to the HTTP
sessions objects for use while creating outbound connections to origin servers.
The transparency data was passed through the VC. This was removed and instead
all of the session level data is passed through the HttpAccept object, which in
turns sets the appropriate values in the HttpClientSession object when an
inbound connection is accepted. This yields easily accessible data for the
State Machine and transaction processing logic and avoid cluttering the VCs
with extraneous data. In particular there is no longer the issue of whether VC
data applies to the VC directly or it's "partner". Additional per port
configuration can be added much more easily. The values are added to
HttpProxyPort for parsing, HttpAccept::Options for conveyance, and then used in
HttpAccept::mainEvent to adjust the values in the HttpClientSession object.
In a related way, the configuration based support for setting the outbound
local IP address was removed and replaced with direct manipulation of the value
in the HttpClientSession object. This is easier and more reliable. In
conjunction with the previous point this makes additional per port runtime
configuration easier to implement.
