mitchell852 closed pull request #3105: Fixed minor spelling issues, made formatting slightly more consistent URL: https://github.com/apache/trafficcontrol/pull/3105
This is a PR merged from a forked repository. As GitHub hides the original diff on merge, it is displayed below for the sake of provenance: As this is a foreign pull request (from a fork), the diff is supplied below (as it won't show otherwise due to GitHub magic): diff --git a/docs/source/admin/quick_howto/ciab.rst b/docs/source/admin/quick_howto/ciab.rst index ab599b9f3..770e4ff5c 100644 --- a/docs/source/admin/quick_howto/ciab.rst +++ b/docs/source/admin/quick_howto/ciab.rst @@ -77,7 +77,7 @@ In a typical scenario, if the steps in `Building`_ have been followed, all that' .. seealso:: :ref:`tr-api` and :ref:`tm-api` -While the components may be interacted with by the host using these ports, the true operation of the CDN can only truly be seen from within the Docker network. To see the CDN in action, connect to a container within the CDN in a Box project and use cURL to request the URL ``http://video.demo1.mycdn.ciab.test`` which will be resolved by the DNS container to the IP of the Traffic Router, which will provide a ``302 FOUND`` response pointing to the Edge-Tier cache. A typical choice for this is the "enroller" service, which has a very nuanced purpose not discussed here but already has the ``curl`` command line tool installed. For a more user-friendly interface into the CDN network, see `The Test Client`_. +While the components may be interacted with by the host using these ports, the true operation of the CDN can only truly be seen from within the Docker network. To see the CDN in action, connect to a container within the CDN in a Box project and use cURL to request the URL ``http://video.demo1.mycdn.ciab.test`` which will be resolved by the DNS container to the IP of the Traffic Router, which will provide a ``302 FOUND`` response pointing to the Edge-Tier cache. A typical choice for this is the "enroller" service, which has a very nuanced purpose not discussed here but already has the ``curl`` command line tool installed. For a more user-friendly interface into the CDN network, see `VNC Server`_. .. code-block:: shell :caption: Example Command to See the CDN in Action @@ -100,14 +100,14 @@ variables.env .. [3] Please do NOT use the Perl endpoints directly. The CDN will only work properly if everything hits the Go API, which will proxy to the Perl endpoints as needed. X.509 SSL/TLS Certificates -========================= -All components in Apache Traffic Control utilize SSL/TLS secure communications by default. For SSL/TLS connections to properly validate within the "CDN in a Box" container network a shared self-signed X.509 Certificate Authority (CA) is generated at the first initial startup. Additional self-signed wildcard certificates are generated for each container service and all delivery services of the CDN. All certificates and keys are stored in the ``ca`` host volume which is located at ``infrastruture/cdn-in-a-box/traffic_ops/ca`` [4]_. +========================== +All components in Apache Traffic Control utilize SSL/TLS secure communications by default. For SSL/TLS connections to properly validate within the "CDN in a Box" container network a shared self-signed X.509 Certificate Authority (CA) is generated at the first initial startup. Additional self-signed wildcard certificates are generated for each container service and all delivery services of the CDN. All certificates and keys are stored in the ``ca`` host volume which is located at ``infrastruture/cdn-in-a-box/traffic_ops/ca`` [4]_. .. _ciab-x509-certificate-list: .. table:: Self-Signed X.509 Certificate List +---------------------------+-----------------------------------+------------------------------+ - | Filename | Description | X.509 CN/SAN | + | Filename | Description | X.509 CN/SAN | +===========================+===================================+==============================+ | CIAB-CA.crt | Shared CA Certificate | N/A | +---------------------------+-----------------------------------+------------------------------+ @@ -122,44 +122,44 @@ All components in Apache Traffic Control utilize SSL/TLS secure communications b .. [4] The ``ca`` volume is not purged with normal ``docker volume`` commands. This feature is by design to allow the existing shared SSL certificate to be trusted at the system level across restarts. To re-generate all SSL certificates and keys, remove the ``infrastructure/cdn-in-a-box/traffic_ops/ca`` directory before startup. -Trusting the CA +Trusting the CA --------------- -For developer and testing use-cases, it may be necessary to have full x509 CA validation by HTTPS clients [5]_. For x509 validation to work properly, the self-signed x509 CA certificate must be trusted either at the system leevel or by the client applicatoin itself. Procedures to import and trust the CA x.509 certifcate are outlined below [6]_. +For developer and testing use-cases, it may be necessary to have full x509 CA validation by HTTPS clients [5]_. For x509 validation to work properly, the self-signed x509 CA certificate must be trusted either at the system level or by the client application itself. Procedures to import and trust the CA x.509 certificate are outlined below [6]_. Importing the CA Certificate on OSX ----------------------------------- -1. Copy the CIAB root CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA.crt`` to the Mac. -2. Import the CIAB root CA certificate on the Mac. -3. Double-click the CIAB root CA certificate to open it in Keychain Access. -4. The CIAB root CA certificate appears in login. -5. Copy the CIAB root CA certificate to System. -6. Open the CIAB root CA certificate, expand Trust, select Use System Defaults, and save your changes. -7. Reopen the CIAB root CA certificate, expand Trust, select Always Trust, and save your changes. -8. Delete the CIAB root CA certificate from login. -9. Restart all HTTPS clients (browsers, etc). +#. Copy the CIAB root CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA.crt`` to the Mac. +#. Import the CIAB root CA certificate on the Mac. +#. Double-click the CIAB root CA certificate to open it in Keychain Access. +#. The CIAB root CA certificate appears in login. +#. Copy the CIAB root CA certificate to System. +#. Open the CIAB root CA certificate, expand Trust, select Use System Defaults, and save your changes. +#. Reopen the CIAB root CA certificate, expand Trust, select Always Trust, and save your changes. +#. Delete the CIAB root CA certificate from login. +#. Restart all HTTPS clients (browsers, etc). Importing the CA certificate on Windows --------------------------------------- -1. Copy the CIAB root CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA.crt`` to Windows filesystem. -2. As Administrator, start the Microsoft Management Console. -3. Add the Certificates snap-in for the computer account and manage certificates for the local computer. -4. Import the CIAB root CA certificate into Trusted Root Certification Authorities > Certificates. -5. Restart all HTTPS clients (browsers, etc). +#. Copy the CIAB root CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA.crt`` to Windows filesystem. +#. As Administrator, start the Microsoft Management Console. +#. Add the Certificates snap-in for the computer account and manage certificates for the local computer. +#. Import the CIAB root CA certificate into Trusted Root Certification Authorities > Certificates. +#. Restart all HTTPS clients (browsers, etc). Importing the CA certificate on Linux/Centos7 --------------------------------------------- -1. Copy the CIAB root CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA.crt`` to path ``/etc/pki/ca-trust/source/anchors``. -2. Run ``update-ca-trust-extract`` as the root user. -3. Restart all HTTPS clients (browsers, etc). +#. Copy the CIAB root CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA.crt`` to path ``/etc/pki/ca-trust/source/anchors``. +#. Run ``update-ca-trust-extract`` as the root user. +#. Restart all HTTPS clients (browsers, etc). Importing the CA certificate on Linux/Ubuntu -------------------------------------------- -1. Copy the CIAB root CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA.crt`` to path ``/usr/local/share/ca-certificates``. -2. Run ``update-ca-certificates`` as the root user. -3. Restart all HTTPS clients (browsers, etc). +#. Copy the CIAB root CA certificate from ``infrastructure/cdn-in-a-box/traffic_ops/ca/CIAB-CA.crt`` to path ``/usr/local/share/ca-certificates``. +#. Run ``update-ca-certificates`` as the root user. +#. Restart all HTTPS clients (browsers, etc). -.. [5] All containers within CDN-in-a-Box start up with the self-signed CA already trusted. -.. [6] HTTP Client applications such as Google Chrome, Firefox, curl, and wget can also be individually configured to trust the CA certificate. Each application procedure can be found quickly online via Google. +.. [5] All containers within CDN-in-a-Box start up with the self-signed CA already trusted. +.. [6] HTTP Client applications such as Google Chrome, Firefox, curl, and wget can also be individually configured to trust the CA certificate. Each application procedure can be found quickly online via Google. Advanced Usage ============== @@ -167,15 +167,15 @@ This section will be amended as functionality is added to the CDN in a Box proje The Enroller ------------ -The "enroller" provides an efficient way for Traffic Ops to be populated with data as CDN in a Box starts up. It connects to Traffic Ops as the admin user and processes files places in the docker volume shared between the containers. The enroller watches each directory within the ``/shared/enroller`` directory for new ``.json`` files to be created there. These files must follow the format outlined in the API guide for the ``POST`` method for each data type, (e.g. for a ``tenant``, follow the guidelines for ``POST api/1.4/regions``). Of note, the ``enroller`` does not require fields that reference database ids for other objects within the database. +The "enroller" provides an efficient way for Traffic Ops to be populated with data as CDN in a Box starts up. It connects to Traffic Ops as the admin user and processes files places in the docker volume shared between the containers. The enroller watches each directory within the ``/shared/enroller`` directory for new ``.json`` files to be created there. These files must follow the format outlined in the API guide for the ``POST`` method for each data type, (e.g. for a ``tenant``, follow the guidelines for ``POST api/1.4/regions``). Of note, the ``enroller`` does not require fields that reference database ids for other objects within the database. -The enroller runs within CDN in a Box using the ``-dir <dir>`` switch which provides the above behavior. It can also be run using the ``-http :<port>`` switch to instead have it listen on the indicated port. In this case, it accepts only POST requests with the JSON provided using the POST JSON method, e.g. ``curl -X POST https://enroller/api/1.4/regions -d @newregion.json``. CDN in a Box does not currently use this method, but may be modified in the future to avoid using the shared volume approach. +The enroller runs within CDN in a Box using the ``-dir <dir>`` switch which provides the above behavior. It can also be run using the ``-http :<port>`` switch to instead have it listen on the indicated port. In this case, it accepts only POST requests with the JSON provided using the POST JSON method, e.g. ``curl -X POST https://enroller/api/1.4/regions -d @newregion.json``. CDN in a Box does not currently use this method, but may be modified in the future to avoid using the shared volume approach. Mock Origin Service ------------------- -The default "origin" service container provides a basic static file HTTP server as the central respository for content. Additional files can be added to the origin root content directory located at ``infrastructure/cdn-in-a-box/origin/content``. To request content directly from the origin directly and bypass the CDN: +The default "origin" service container provides a basic static file HTTP server as the central respository for content. Additional files can be added to the origin root content directory located at ``infrastructure/cdn-in-a-box/origin/content``. To request content directly from the origin directly and bypass the CDN: -* Origin Service URL: http://origin.infra.ciab.test/index.html +* Origin Service URL: http://origin.infra.ciab.test/index.html * Docker Host: http://localhost:9200/index.html .. _ciab-optional-containers: @@ -200,91 +200,99 @@ Multiple optional containers may be combined by using a shell alias: mydc build mydc up -VNC Server +VNC Server ---------- -The tightvnc optional container provides a basic lightweight window manager (fluxbox), firefox browser, xterm, and a few other utilities within the CDN-In-A-Box tcnet bridge network. This can be very helpful for quick demonstrations of CDN-in-a-Box that require the use of real container network FQDNs and full X.509 validation. +The TightVNC optional container provides a basic lightweight window manager (fluxbox), Firefox browser, xterm, and a few other utilities within the CDN-In-A-Box tcnet bridge network. This can be very helpful for quick demonstrations of CDN-in-a-Box that require the use of real container network FQDNs and full X.509 validation. -1. Download and install a VNC client. TightVNC client is preferred as it supports window resizing, host-to-vnc copy/pasting, and optimized frame buffer compression. -2. Set your VNC console password by adding the ``VNC_PASSWD`` environment variable to ``infrastructure/cdn-in-a-box/varibles.env``. The password needs to be at least six characters long. The default password is randomized for security. -3. Start up CDN-in-a-Box stack using a custom bash alias +#. Download and install a VNC client. TightVNC client is preferred as it supports window resizing, host-to-vnc copy/pasting, and optimized frame buffer compression. +#. Set your VNC console password by adding the ``VNC_PASSWD`` environment variable to ``infrastructure/cdn-in-a-box/varibles.env``. The password needs to be at least six characters long. The default password is randomized for security. +#. Start up CDN-in-a-Box stack. It is recommended that this be done using a custom bash alias -.. code-block:: shell + .. code-block:: shell + :caption: CIAB Startup Using Bash Alias - # From infrastructure/cdn-in-a-box - alias mydc="docker-compose -f $PWD/docker-compose.yml -f $PWD/optional/docker-compose.vnc.yml" - docker volume prune -f - mydc build - mydc kill - mydc rm -fv - mydc up + # From infrastructure/cdn-in-a-box + alias mydc="docker-compose -f $PWD/docker-compose.yml -f $PWD/optional/docker-compose.vnc.yml" + docker volume prune -f + mydc build + mydc kill + mydc rm -fv + mydc up -4. Connect with a VNC client to localhost port 9080. -5. When Traffic Portal becomes available, the Firefox within the VNC instance will subsequently be started. -6. An xterm with bash shell is also automatically spawned and minimized for convenience. +#. Connect with a VNC client to localhost port 9080. +#. When Traffic Portal becomes available, the Firefox within the VNC instance will subsequently be started. +#. An xterm with bash shell is also automatically spawned and minimized for convenience. Socks Proxy ----------- -Dantes socks proxy is an optional container that can be used to provide browsers and other clients the ability to resolve DNS queries and network connectivity directly on the tcnet bridged interface. This is very helpful when running the CDN-In-A-Box stack on OSX/Windows docker host that lacks network bridge/ipforward support. Below is the basic procedure to enable the Socks Proxy support for CDN-in-a-Box: - -1. Start the CDN-in-a-Box stack at least once so that the x.509 self-signed certificate authority (CA) is created. -2. On the host, import and Trust the CA for your target OS. See `Trusting the CA`_ -3. On the host, using either firefox or chrome, download the FoxyProxy Standard browser plugin which enables dynamic proxy support via URL regex -4. Once FoxyProxy is installed, click the Fox icon on the upper right hand of the browser window, select 'Options' -5. Once in Options Dialog, Click 'Add New Proxy' and navigate to the General tab: -6. Fill in the General tab according to the table - - +------------+---------+ - | Name | Value | - +============+=========+ - | Proxy Name | CIAB | - +------------+---------+ - | Color | Green | - +------------+---------+ - -7. Fill in the Proxy Details tab according to the table - - +----------------------------+-----------+ - | Name | Value | - +============================+===========+ - | Manual Proxy Configuration | CIAB | - +----------------------------+-----------+ - | Host or IP Address | localhost | - +----------------------------+-----------+ - | Port | 9080 | - +----------------------------+-----------+ - | Socks Proxy | checked | - +----------------------------+-----------+ - | Socks V5 | selected | - +----------------------------+-----------+ - -8. Go to URL Patterns tab, click Add New Pattern, and fill out form according to - - +--------------+--------------+ - | Name | Value | - +==============+==============+ - | Pattern Name | CIAB Pattern | - +--------------+--------------+ - | URL Pattern | \*.test/\* | - +--------------+--------------+ - | Whitelist | selected | - +--------------+--------------+ - | Wildcards | selected | - +--------------+--------------+ - -9. Enable dynamic 'pre-defined and patterns' mode by clicking the fox icon in the upper right of the browser. This mode only forwards URLs that match the wildcard `\*.test/\*` to the Socks V5 proxy. - -10. On the docker host start up CDN-in-a-Box stack using a custom bash alias - -.. code-block:: shell - - # From infrastructure/cdn-in-a-box - alias mydc="docker-compose -f $PWD/docker-compose.yml -f $PWD/optional/docker-compose.socksproxy.yml" - docker volume prune -f - mydc build - mydc kill - mydc rm -fv - mydc up - -11. Once the CDN-in-a-box stack has started, use the aformentioned browser to access traffic portal via the socks proxy on the docker host. +Dante's socks proxy is an optional container that can be used to provide browsers and other clients the ability to resolve DNS queries and network connectivity directly on the tcnet bridged interface. This is very helpful when running the CDN-In-A-Box stack on OSX/Windows docker host that lacks network bridge/IP-forward support. Below is the basic procedure to enable the Socks Proxy support for CDN-in-a-Box: + +#. Start the CDN-in-a-Box stack at least once so that the x.509 self-signed certificate authority (CA) is created. +#. On the host, import and Trust the CA for your target OS. See `Trusting the CA`_ +#. On the host, using either Firefox or Chrome, download the FoxyProxy Standard browser plugin which enables dynamic proxy support via URL regular expression +#. Once FoxyProxy is installed, click the Fox icon on the upper right hand of the browser window, select 'Options' +#. Once in Options Dialog, Click 'Add New Proxy' and navigate to the General tab: +#. Fill in the General tab according to the table + + .. table:: General Tab Values + + +------------+---------+ + | Name | Value | + +============+=========+ + | Proxy Name | CIAB | + +------------+---------+ + | Color | Green | + +------------+---------+ + +#. Fill in the Proxy Details tab according to the table + + .. table:: Proxy Details Tab Values + + +----------------------------+-----------+ + | Name | Value | + +============================+===========+ + | Manual Proxy Configuration | CIAB | + +----------------------------+-----------+ + | Host or IP Address | localhost | + +----------------------------+-----------+ + | Port | 9080 | + +----------------------------+-----------+ + | Socks Proxy | checked | + +----------------------------+-----------+ + | Socks V5 | selected | + +----------------------------+-----------+ + +#. Go to URL Patterns tab, click Add New Pattern, and fill out form according to + + .. table:: URL Patters Tab Values + + +--------------+--------------+ + | Name | Value | + +==============+==============+ + | Pattern Name | CIAB Pattern | + +--------------+--------------+ + | URL Pattern | \*.test/\* | + +--------------+--------------+ + | Whitelist | selected | + +--------------+--------------+ + | Wildcards | selected | + +--------------+--------------+ + +#. Enable dynamic 'pre-defined and patterns' mode by clicking the fox icon in the upper right of the browser. This mode only forwards URLs that match the wildcard ``\*.test/\*`` to the Socks V5 proxy. + +10. On the docker host start up CDN-in-a-Box stack. It is recommended that this be done using a custom bash alias + + .. code-block:: shell + :caption: CIAB Startup Using Bash Alias + + # From infrastructure/cdn-in-a-box + alias mydc="docker-compose -f $PWD/docker-compose.yml -f $PWD/optional/docker-compose.socksproxy.yml" + docker volume prune -f + mydc build + mydc kill + mydc rm -fv + mydc up + +#. Once the CDN-in-a-box stack has started, use the aforementioned browser to access traffic portal via the socks proxy on the docker host. .. seealso:: `The official Docker Compose documentation CLI reference <https://docs.docker.com/compose/reference/>`_ for complete instructions on how to pass service definition files to the ``docker-compose`` executable. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
