fix links&formatting in Security Options docs as well as splitdns.config reference.
The Security Options document has the most bizzarre numbering I've seen in a while. it needs to be rewritten or re-ordered. Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/d9c639be Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/d9c639be Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/d9c639be Branch: refs/heads/master Commit: d9c639bea4e841f7dee5dcc77472461020de5e09 Parents: 5c68757 Author: Igor GaliÄ <[email protected]> Authored: Sun Aug 18 23:27:44 2013 +0200 Committer: Igor GaliÄ <[email protected]> Committed: Sun Aug 18 23:27:44 2013 +0200 ---------------------------------------------------------------------- doc/admin/security-options.en.rst | 22 ++++----- .../configuration/records.config.en.rst | 2 + .../configuration/splitdns.config.en.rst | 47 +++++++++++--------- 3 files changed, 39 insertions(+), 32 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/d9c639be/doc/admin/security-options.en.rst ---------------------------------------------------------------------- diff --git a/doc/admin/security-options.en.rst b/doc/admin/security-options.en.rst index 6bf8ccf..a3c6e51 100644 --- a/doc/admin/security-options.en.rst +++ b/doc/admin/security-options.en.rst @@ -22,11 +22,6 @@ Security Options Traffic Server provides a number of security features. -This chapter discusses the following topics: - -.. toctree:: - :maxdepth: 2 - .. _controlling-client-access-to-cache: Controlling Client Access to the Proxy Cache @@ -40,6 +35,8 @@ the proxy cache by editing a configuration file. #. Run the command :option:`traffic_line -x` to apply the configuration changes. +.. _configuring-dns-server-selection-split-dns: + Configuring DNS Server Selection (Split DNS) ============================================ @@ -102,19 +99,19 @@ Server connections only**. The figure above depicts the following: -**Step 1:** The client sends an HTTPS request for content. Traffic +# The client sends an HTTPS request for content. Traffic Server receives the request and performs the SSL 'handshake' to authenticate the client (depending on the authentication options configured) and determine the encryption method that will be used. If the client is allowed access, then Traffic Server checks its cache for the requested content. -**Step 2:** If the request is a cache hit and the content is fresh, then +# If the request is a cache hit and the content is fresh, then Traffic Server encrypts the content and sends it to the client. The client decrypts the content (using the method determined during the handshake) and displays it. -**Step 3:** If the request is a cache miss or cached content is stale, +# If the request is a cache miss or cached content is stale, then Traffic Server communicates with the origin server via HTTP and obtains a plain text version of the content. Traffic Server saves the plain text version of the content in its cache, encrypts the content, @@ -152,7 +149,7 @@ client/Traffic Server connections, you must do the following: In order to accomplish this, we -2. Edit the following variables in the ``SSL Termination`` section of +2. Edit the following variables in the :ref:`records-config-ssl-termination` section of :file:`records.config` - :ts:cv:`proxy.config.http.server_ports` @@ -167,6 +164,9 @@ In order to accomplish this, we local node or :option:`traffic_line -M` to restart Traffic Server on all the nodes in a cluster. + +.. XXX:: This numbering is ridiculous. + .. _traffic-server-and-origin-server-connections: Traffic Server and Origin Server Connections @@ -226,7 +226,9 @@ Traffic Server and origin server connections, you must do the following: In order to accomplish this, we: -2. Edit the following variables in the ``SSL Termination`` section of +.. XXX:: 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`: - :ts:cv:`proxy.config.ssl.auth.enabled` http://git-wip-us.apache.org/repos/asf/trafficserver/blob/d9c639be/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 7fc2d71..9e1b8b3 100644 --- a/doc/reference/configuration/records.config.en.rst +++ b/doc/reference/configuration/records.config.en.rst @@ -1543,6 +1543,8 @@ URL Remap Rules Set this variable to ``1`` if you want to retain the client host header in a request during remapping. +.. _records-config-ssl-termination: + SSL Termination =============== http://git-wip-us.apache.org/repos/asf/trafficserver/blob/d9c639be/doc/reference/configuration/splitdns.config.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/configuration/splitdns.config.en.rst b/doc/reference/configuration/splitdns.config.en.rst index 4765ca5..343a7f1 100644 --- a/doc/reference/configuration/splitdns.config.en.rst +++ b/doc/reference/configuration/splitdns.config.en.rst @@ -23,8 +23,7 @@ splitdns.config The :file:`splitdns.config` file enables you to specify the DNS server that Traffic Server should use for resolving hosts under specific conditions. -For more information, refer to `Configuring DNS Server Selection (Split -DNS) <../security-options#SplitDNS>`_. +For more information, refer to :ref:`configuring-dns-server-selection-split-dns`. To specify a DNS server, you must supply the following information in each active line within the file: @@ -51,29 +50,35 @@ Format ====== Each line in the :file:`splitdns.config` file uses one of the following -formats: - -:: +formats: :: dest_domain=dest_domain | dest_host | url_regex named=dns_server def_domain=def_domain search_list=search_list The following list describes each field. -*``dest_domain``* {#dest_domain} +.. _splitdns-config-format-dest-domain: + +``dest_domain`` A valid domain name. This specifies that DNS server selection will be based on the destination domain. You can prefix the domain with an exclamation mark (``!``) to indicate the NOT logical operator. -*``dest_host``* {#dest_host} +.. _splitdns-config-format-dest-host: + +``dest_host`` A valid hostname. This specifies that DNS server selection will be based on the destination host. You can prefix the host with an exclamation mark (``!``) to indicate the ``NOT`` logical operator. -*``url_regex``* {#url_regex} +.. _splitdns-config-format-url-regex: + +``url_regex`` A valid URL regular expression. This specifies that DNS server selection will be based on a regular expression. -*``dns_server``* {#dns_server} +.. _splitdns-config-format-dns-server: + +``dns_server`` This is a required directive. It identifies the DNS server that Traffic Server should use with the given destination specifier. You can specify a port using a colon (``:``). If you do not specify a @@ -83,44 +88,42 @@ The following list describes each field. You must specify the domains with IP addresses in CIDR ("dot") notation. -*``def_domain``* {#def_domain} +.. _splitdns-config-format-def-domain: + +``def_domain`` A valid domain name. This optional directive specifies the default domain name to use for resolving hosts. Only one entry is allowed. If you do not provide the default domain, the system determines its value from ``/etc/resolv.conf`` -*``search_list``* {#search_list} +.. _splitdns-config-format-search-list: + +``search_list`` A list of domains separated by spaces or semicolons (;). This specifies the domain search order. If you do not provide the search - list, the system determines the value from ``/etc/resolv.conf`` + list, the system determines the value from :manpage:`resolv.conf(5)` Examples ======== -Consider the following DNS server selection specifications: - -:: +Consider the following DNS server selection specifications: :: dest_domain=internal.company.com named=255.255.255.255:212 255.255.255.254 def_domain=company.com search_list=company.com company1.com dest_domain=!internal.company.com named=255.255.255.253 -Now consider the following two requests: - -:: +Now consider the following two requests: :: http://minstar.internal.company.com This request matches the first line and therefore selects DNS server ``255.255.255.255`` on port ``212``. All resolver requests use ``company.com`` as the default domain, and ``company.com`` and -``company1.com`` as the set of domains to search first. - -:: +``company1.com`` as the set of domains to search first. :: http://www.microsoft.com This request matches the second line. Therefore, Traffic Server selects DNS server ``255.255.255.253``. Because no ``def_domain`` or ``search_list`` was supplied, Traffic Server retrieves this information -from ``/etc/resolv.conf`` +from :manpage:`resolv.conf(5)`
