trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject git commit: Documentation: Add ip_resolve option description.
Date Mon, 19 Aug 2013 20:27:03 GMT
Updated Branches:
  refs/heads/master 1bde1bdc4 -> 19bcb1680


Documentation: Add ip_resolve option description.


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/19bcb168
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/19bcb168
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/19bcb168

Branch: refs/heads/master
Commit: 19bcb16808ab4ad5876ae5ff9664c59dffce3572
Parents: 1bde1bd
Author: Alan M. Carroll <amc@network-geographics.com>
Authored: Mon Aug 19 15:26:38 2013 -0500
Committer: Alan M. Carroll <amc@network-geographics.com>
Committed: Mon Aug 19 15:26:38 2013 -0500

----------------------------------------------------------------------
 doc/admin/security-options.en.rst               | 40 +++++-----
 .../configuration/records.config.en.rst         | 81 +++++++++++++++++---
 2 files changed, 91 insertions(+), 30 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/19bcb168/doc/admin/security-options.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/security-options.en.rst b/doc/admin/security-options.en.rst
index 2038281..6227b70 100644
--- a/doc/admin/security-options.en.rst
+++ b/doc/admin/security-options.en.rst
@@ -5,20 +5,20 @@ Security Options
 
 .. Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
-  distributed with this work for additional information
-  regarding copyright ownership.  The ASF licenses this file
-  to you under the Apache License, Version 2.0 (the
-  "License"); you may not use this file except in compliance
-  with the License.  You may obtain a copy of the License at
- 
-   http://www.apache.org/licenses/LICENSE-2.0
- 
-  Unless required by applicable law or agreed to in writing,
-  software distributed under the License is distributed on an
-  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-  KIND, either express or implied.  See the License for the
-  specific language governing permissions and limitations
-  under the License.
+   distributed with this work for additional information
+   regarding copyright ownership.  The ASF licenses this file
+   to you under the Apache License, Version 2.0 (the
+   "License"); you may not use this file except in compliance
+   with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing,
+   software distributed under the License is distributed on an
+   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied.  See the License for the
+   specific language governing permissions and limitations
+   under the License.
 
 Traffic Server provides a number of security features.
 
@@ -63,6 +63,8 @@ To do this, we
 #. Run the command :option:`traffic_line -x` to apply the configuration
    changes.
 
+.. _configuring-ssl-termination:
+
 Using SSL Termination
 =====================
 
@@ -129,7 +131,7 @@ client/Traffic Server connections, you must do the following:
 
    -  Set the port number used for SSL communication using :ts:cv:`proxy.config.http.server_ports`.
    -  Edit :file:`ssl_multicert.config` to specify the filename and location of the
-     SSL certificates and provate keys.
+      SSL certificates and provate keys.
    -  (Optional) Configure the use of client certificates: Client
       certificates are located on the client. If you configure Traffic
       Server to require client certificates, then Traffic Server
@@ -144,7 +146,7 @@ client/Traffic Server connections, you must do the following:
 
 In order to accomplish this, we
 
-2. Edit the following variables in the :ref:`records-config-ssl-termination` section of
+#. Edit the following variables in the :ref:`records-config-ssl-termination` section of
    :file:`records.config`
 
    -  :ts:cv:`proxy.config.http.server_ports`
@@ -153,12 +155,12 @@ In order to accomplish this, we
    -  :ts:cv:`proxy.config.ssl.server.private_key.path`
    -  :ts:cv:`proxy.config.ssl.CA.cert.path`
 
-3. Run the command :option:`traffic_line -L` to restart Traffic Server on the
+#. Run the command :option:`traffic_line -L` to restart Traffic Server on the
    local node or :option:`traffic_line -M` to restart Traffic Server on all
    the nodes in a cluster.
 
 
-.. XXX:: This numbering is ridiculous.
+.. This numbering is ridiculous.
 
 .. _traffic-server-and-origin-server-connections:
 
@@ -219,7 +221,7 @@ Traffic Server and origin server connections, you must do the following:
 
 In order to accomplish this, we:
 
-.. XXX:: This numbering is ridiculous. I need to re-read this doc with a fresh mind and re(number|order)
it.
+.. This numbering is ridiculous. I need to re-read this doc with a fresh mind and re(number|order)
it.
 
 2. Edit the following variables in the :ref:`records-config-ssl-termination` section of
    :file:`records.config`:

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/19bcb168/doc/reference/configuration/records.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/configuration/records.config.en.rst b/doc/reference/configuration/records.config.en.rst
index 7759953..6749d71 100644
--- a/doc/reference/configuration/records.config.en.rst
+++ b/doc/reference/configuration/records.config.en.rst
@@ -359,14 +359,14 @@ ipv6
    Use IPv6. This is forced if the ``ip-in`` option is used with an IPv6 address.
 
 tr-in
-   Inbound transparent. The proxy port will accept connections to any IP address on the port.
To have IPv6 inbound transparent you must use this and the ``ipv6`` option. This overrides
`proxy.local.incoming_ip_to_bind`_.
+   Inbound transparent. The proxy port will accept connections to any IP address on the port.
To have IPv6 inbound transparent you must use this and the ``ipv6`` option. This overrides
:ts:cv:`proxy.local.incoming_ip_to_bind`.
 
    Not compatible with: ``ip-in``, ``ssl``, ``blind``
 
 tr-out
-   Outbound transparent. If ATS connects to an origin server for a transaction on this port,
it will use the client's address as its local address. This overrides `proxy.local.outgoing_ip_to_bind`_.
+   Outbound transparent. If ATS connects to an origin server for a transaction on this port,
it will use the client's address as its local address. This overrides :ts:cv:`proxy.local.outgoing_ip_to_bind`.
 
-   Not compatible with: ``ip-out``, ``ssl``
+   Not compatible with: ``ip-out``, ``ssl``, ``ip-resolve``
 
 tr-full
    Fully transparent. This is a convenience option and is identical to specifying both ``tr-in``
and ``tr-out``.
@@ -374,25 +374,27 @@ tr-full
    Not compatible with: Any option not compatible with ``tr-in`` or ``tr-out``.
 
 tr-pass
-   Transparent pass through. This option is useful only for inbound transparent proxy ports.
If the parsing of the expected HTTP header fails, then the transaction is switched to a blind
tunnel instead of generating an error response to the client. It effectively enables `proxy.config.http.use_client_target_addr`_
for the transaction as there is no other place to obtain the origin server address.
+   Transparent pass through. This option is useful only for inbound transparent proxy ports.
If the parsing of the expected HTTP header fails, then the transaction is switched to a blind
tunnel instead of generating an error response to the client. It effectively enables :ts:cv:`proxy.config.http.use_client_target_addr`
for the transaction as there is no other place to obtain the origin server address.
 
 ip-in
-   Set the local IP address for the port. This is the address to which clients will connect.
This forces the IP address family for the port. The ``ipv4`` or ``ipv6`` can be used but it
is optional and is an error for it to disagree with the IP address family of this value. An
IPv6 address **must** be enclosed in square brackets. If this is omitted `proxy.local.incoming_ip_to_bind`_
is used.
+   Set the local IP address for the port. This is the address to which clients will connect.
This forces the IP address family for the port. The ``ipv4`` or ``ipv6`` can be used but it
is optional and is an error for it to disagree with the IP address family of this value. An
IPv6 address **must** be enclosed in square brackets. If this options is omitted :ts:cv:`proxy.local.incoming_ip_to_bind`
is used.
 
    Not compatible with: ``tr-in``.
 
 ip-out
-   Set the local IP address for outbound connections. This is the address used by ATS locally
when it connects to an origin server for transactions on this port. If this is omitted `proxy.local.outgoing_ip_to_bind`_
is used.
+   Set the local IP address for outbound connections. This is the address used by ATS locally
when it connects to an origin server for transactions on this port. If this is omitted :ts:cv:`proxy.local.outgoing_ip_to_bind`
is used.
 
    This option can used multiple times, once for each IP address family. The address used
is selected by the IP address family of the origin server address.
 
    Not compatible with: ``tr-out``.
 
 ip-resolve
-   Set the IP address resolution style for the origin server for transactions on this proxy
port.
+   Set the :ts:cv:`host resolution style <proxy.config.hostdb.ip_resolve>` for transactions
on this proxy port.
+
+   Not compatible with: ``tr-out``.
 
 ssl
-   Require SSL termination for inbound connections. SSL must be configured for this option
to provide a functional server port.
+   Require SSL termination for inbound connections. SSL :ref:`must be configured <configuring-ssl-termination>`
for this option to provide a functional server port.
 
    Not compatible with: ``tr-in``, ``tr-out``, ``blind``.
 
@@ -420,7 +422,7 @@ compress
 
 .. topic:: Example
 
-   Listen on port 8080 for IPv6, fully transparent. Set up an SSL port on 443. These ports
will use the IP address from `proxy.local.incoming_ip_to_bind`_.  Listen on IP address ``192.168.17.1``,
port 80, IPv4, and connect to origin servers using the local address ``10.10.10.1`` for IPv4
and ``fc01:10:10:1::1`` for IPv6.::
+   Listen on port 8080 for IPv6, fully transparent. Set up an SSL port on 443. These ports
will use the IP address from :ts:cv:`proxy.local.incoming_ip_to_bind`.  Listen on IP address
``192.168.17.1``, port 80, IPv4, and connect to origin servers using the local address ``10.10.10.1``
for IPv4 and ``fc01:10:10:1::1`` for IPv6.::
 
       8080:ipv6:tr-full 443:ssl ip-in=192.168.17.1:80:ip-out=[fc01:10:10:1::1]:ip-out=10.10.10.1
 
@@ -431,7 +433,7 @@ compress
 Traffic Server allows tunnels only to the specified ports.
 Supports both wildcards ('\*') and ranges ("0-1023").
 
-.. note:: These are the ports on the *origin server*, not `server ports <#proxy-config-http-server-ports>`_.
+.. note:: These are the ports on the *origin server*, not Traffic Server :ts:cv:`proxy ports
<proxy.config.http.server_ports>`.
 
 .. ts:cv:: CONFIG proxy.config.http.insert_request_via_str INT 1
    :reloadable:
@@ -1216,9 +1218,66 @@ set then IP address is rotated on every request. This setting takes
precedence o
 
 When this and :ts:cv:`proxy.config.hostdb.strict_round_robin` are both disabled (set to ``0``),
Traffic Server always
 uses the same origin server for the same client, for as long as the origin server is available.
Otherwise if this is
-set then to :arg:`N` the IP address is rotated if more than :arg:`N` seconds have past since
the first time the
+set to :arg:`N` the IP address is rotated if more than :arg:`N` seconds have past since the
first time the
 current address was used.
 
+.. ts:cv:: CONFIG proxy.config.hostdb.ip_resolve STRING ipv4;ipv6
+
+   Set the host resolution style.
+
+This is an ordered list of keywords separated by semicolons that specify how a host name
is to be resolved to an IP address. The keywords are case
+insensitive.
+
+=======  =======
+Keyword  Meaning
+=======  =======
+ipv4     Resolve to an IPv4 address.
+ipv6     Resolve to an IPv6 address.
+client   Resolve to the same family as the client IP address.
+none     Stop resolving.
+=======  =======
+
+The order of the keywords is critical. When a host name needs to be resolved it is resolved
in same order as the
+keywords. If a resolution fails, the next option in the list is tried. The keyword ``none``
means to give up resolution
+entirely. The keyword list has a maximum length of three keywords, more are never needed.
By default there is an
+implicit ``ipv4;ipv6`` attached to the end of the string unless the keyword ``none`` appears.
+
+.. topic:: Example
+
+   Use the incoming client family, then try IPv4 and IPv6. ::
+
+      client;ipv4;ipv6
+
+   Because of the implicit resolution this can also be expressed as just ::
+
+      client
+
+.. topic:: Example
+
+   Resolve only to IPv4. ::
+
+      ipv4;none
+
+.. topic:: Example
+
+   Resolve only to the same family as the client (do not permit cross family transactions).
::
+
+      client;none
+
+This value is a global default that can be overridden by :ts:cv:`proxy.config.http.server_ports`.
+
+.. note::
+
+   This style is used as a convenience for the administrator. During a resolution the *resolution
order* will be
+   one family, then possibly the other. This is determined by changing ``client`` to ``ipv4``
or ``ipv6`` based on the
+   client IP address and then removing duplicates.
+
+.. important::
+
+   This option has no effect on outbound transparent connections The local IP address used
in the connection to the
+   origin server is determined by the client, which forces the IP address family of the address
used for the origin
+   server. In effect, outbound transparent connections always use a resolution style of "``client``".
+
 Logging Configuration
 =====================
 


Mime
View raw message