diff --git a/source/clear-linux/guides/clearlinux/autoproxy.rst b/source/clear-linux/guides/clearlinux/autoproxy.rst new file mode 100644 index 00000000..eb9c7301 --- /dev/null +++ b/source/clear-linux/guides/clearlinux/autoproxy.rst @@ -0,0 +1,18 @@ +.. _autoproxy: + +Autoproxy +######### + +.. rst-class:: html-toggle + +About +===== + +.. include:: autoproxy_about.rst.txt + +.. rst-class:: html-toggle + +Guide +===== + +.. include:: autoproxy_guide.rst.txt diff --git a/source/clear-linux/guides/clearlinux/autoproxy_about.rst.txt b/source/clear-linux/guides/clearlinux/autoproxy_about.rst.txt new file mode 100644 index 00000000..c74a381a --- /dev/null +++ b/source/clear-linux/guides/clearlinux/autoproxy_about.rst.txt @@ -0,0 +1,46 @@ +The |CL-ATTR| is the first Linux distribution to support autoproxy. The OS +can discover a Proxy Auto-Config (PAC) script and use it to automatically +resolve the proxy needed for a given connection. With Autoproxy, you can use +|CL| inside any proxy environment without having to manually +configure the proxies: + +* Automate unit testing without worrying about the proxy not being set +* Remove unset proxies from the equation when dealing with network + unavailability across systems. + +* Automate unit testing without worrying about the proxy not being set +* Remove unset proxies from the equation when dealing with network + unavailability across systems. + +Corporate and private networks can be very complex, needing to restrict and +control network connections for security reasons. The typical side effects +are limited or blocked connectivity and requiring manual configuration of +proxies to perform the most mundane tasks such as cloning a repo or checking +for updates. With |CL|, all of the work is done behind the scenes to +effortlessly use your network and have connections “just work”. + +How Autoproxy works +------------------- + +We designed autoproxy around general tools provided by nearly any Linux +distribution with a few minor additions and modifications. We leveraged the +DHCP and network information provided from systemd and created a +PAC-discovery daemon. The daemon uses the information to resolve a URL for a +PAC file. The daemon then passes the URL into PACrunner*. PACrunner +downloads the PAC file and uses the newly implemented Duktape* engine to +parse it. + +.. figure:: figures/autoproxy_0.png + :width: 400px + + Figure 1: Autoproxy Flow + +From that point on, any cURL* or network requests query PACrunner for the +correct proxy to use. We modified the cURL library to communicate with +PACrunner over DBus. However, cURL will ignore PACrunner and run normally if +no PAC file is loaded or if you set any proxies manually. Thus, your +environment settings are respected and no time is wasted trying to resolve a +proxy. + +More importantly: all these steps happen in the background, very quickly, and +with no user interaction. \ No newline at end of file diff --git a/source/clear-linux/guides/clearlinux/autoproxy_guide.rst.txt b/source/clear-linux/guides/clearlinux/autoproxy_guide.rst.txt new file mode 100644 index 00000000..ca4f64b8 --- /dev/null +++ b/source/clear-linux/guides/clearlinux/autoproxy_guide.rst.txt @@ -0,0 +1,79 @@ +Autoproxy allows |CL| to operate seamlessly behind a proxy +because :ref:`software update ` and other |CL| tools are +implemented on top of libcurl. Tools that do not use libcurl, like git, must +be configured independently. + +If you encounter problems with autoproxy functioning, use +:command:`sudo pacdiscovery` and :command:`FindProxyForURL` to +help troubleshoot assuming a familiarity with PAC files and WPAD. + +.. note:: + + Learn more about WPAD, PAC files, and PAC functions at `findproxyforurl`_. + +.. _findproxyforurl: http://findproxyforurl.com/ + +Running :command:`pacdiscovery` with no arguments will immediately indicate +one of the following: + +1. If there is a problem resolving the :command:`WPAD` host name resolution: + + .. code:: console + + $ pacdiscovery + failed getaddrinfo: No address associated with hostname + Unable to find wpad host + +2. Or if the :command:`pacrunner` service is disabled (masked): + + .. code:: console + + $ pacdiscovery + PAC url: http://autoproxy.your.domain.com/wpad.dat + Failed to create proxy config: Unit pacrunner.service is masked. + +Unmask the :command:`pacrunner` service by running: + +.. code:: console + + $ systemctl unmask pacrunner.service + +:command:`FindProxyForURL` with :command:`busctl` can also indicate if the +:command:`pacrunner.service` is masked. + +.. code:: console + + $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com" + Unit pacrunner.service is masked. + dig wpad, dig wpad. + +:command:`FindProxyForURL` returns the URL and port of the proxy server when +an external URL and host are provided as arguments. + +.. code:: console + + $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com" + s "PROXY proxy.your.domain.com:" + +If a proxy server is not available, or if :command:`pacrunner` is running +without a PAC file, :command:`FindProxyForURL` will return "DIRECT". Otherwise, +it should return your local proxy settings as shown above. + +.. code:: console + + $ busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com" + s "DIRECT" + +Once :command:`pacdiscovery` is able to look up :command:`WPAD`, restart the +:command:`pacrunner` service: + +.. code:: console + + $ systemctl stop pacrunner + $ systemctl restart pacdiscovery + +.. note:: + + A "domain" or "search" entry in :file:`/etc/resolv.conf` is required for short + name lookups to resolve. The :file:`resolv.conf` man page has additional + details. \ No newline at end of file diff --git a/source/clear-linux/guides/clearlinux/figures/autoproxy_0.png b/source/clear-linux/guides/clearlinux/figures/autoproxy_0.png new file mode 100644 index 00000000..7a02cd81 Binary files /dev/null and b/source/clear-linux/guides/clearlinux/figures/autoproxy_0.png differ diff --git a/source/clear-linux/guides/guides.rst b/source/clear-linux/guides/guides.rst index f6d33320..c5470f0b 100644 --- a/source/clear-linux/guides/guides.rst +++ b/source/clear-linux/guides/guides.rst @@ -5,7 +5,7 @@ Guides Our Guides: -* Provide a critical, fundamental understanding of |CL| features +* Provide a critical, fundamental understanding of |CL-ATTR| features * Show you how to leverage the full feature set of |CL| * Enhance your productivity when using |CL| @@ -13,10 +13,31 @@ Our Guides: The following guides provide step-by-step instructions for tasks that come after completing the |CL| :ref:`installation `. -.. toctree:: - :maxdepth: 2 +Clear Linux Tooling +=================== - maintenance/maintenance - network/network - deploy-at-scale +.. toctree:: + :maxdepth: 1 + :glob: + + clearlinux/* telemetrics/telemetrics + +Maintenance +=========== + +.. toctree:: + :maxdepth: 1 + :glob: + + maintenance/* + deploy-at-scale + +Network +======= + +.. toctree:: + :maxdepth: 1 + :glob: + + network/* \ No newline at end of file diff --git a/source/clear-linux/guides/maintenance/maintenance.rst b/source/clear-linux/guides/maintenance/maintenance.rst deleted file mode 100644 index 0751cd2b..00000000 --- a/source/clear-linux/guides/maintenance/maintenance.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _maintenance: - -Maintenance guide -################# - -These guides provide step-by-step instructions for common tasks associated -with maintaining |CL-ATTR| after :ref:`installation ` is -completed. - -.. toctree:: - :maxdepth: 2 - - developer-workstation - swupd-search - enable-user-space - swupd-guide - bulk-provision - mixer - mixin - validate-signatures - time - hostname - increase-virtual-disk-size - download-verify-decompress-linux - download-verify-decompress-mac - download-verify-decompress-windows - autospec diff --git a/source/clear-linux/guides/network/network.rst b/source/clear-linux/guides/network/network.rst deleted file mode 100644 index 5df83dcb..00000000 --- a/source/clear-linux/guides/network/network.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _network: - -Network guide -############# - -This guide provides step-by-step instructions for common tasks associated with -the configuration, administration, and use of networks in the |CLOSIA|. - -.. toctree:: - :maxdepth: 1 - - ipxe-install - dpdk - network-bonding - custom-clear-container - vnc \ No newline at end of file