diff --git a/source/clear-linux/guides/clearlinux/autoproxy.rst b/source/clear-linux/guides/clearlinux/autoproxy.rst new file mode 100644 index 00000000..fe4c3987 --- /dev/null +++ b/source/clear-linux/guides/clearlinux/autoproxy.rst @@ -0,0 +1,18 @@ +.. _autoproxy: + +Autoproxy +######### + +.. rst-class:: html-toggle + +About +===== + +.. include:: autoproxy_about.txt + +.. rst-class:: html-toggle + +Guide +===== + +.. include:: autoproxy_guide.txt \ No newline at end of file diff --git a/source/clear-linux/guides/clearlinux/autoproxy_about.txt b/source/clear-linux/guides/clearlinux/autoproxy_about.txt new file mode 100644 index 00000000..80dcaa4e --- /dev/null +++ b/source/clear-linux/guides/clearlinux/autoproxy_about.txt @@ -0,0 +1,43 @@ +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. + +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 Clear Linux, all of the work is done behind the scenes to +effortlessly use your network and have connections “just work”. + +This feature removes massive complications in network connectivity due to +proxy issues. You can automate tasks like unit testing without worrying +about the proxy not being set and you can remove unset proxies from the +equation when dealing with network unavailability across systems. + +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.txt b/source/clear-linux/guides/clearlinux/autoproxy_guide.txt new file mode 100644 index 00000000..3422a747 --- /dev/null +++ b/source/clear-linux/guides/clearlinux/autoproxy_guide.txt @@ -0,0 +1,77 @@ +Autoproxy allows |CL| to operate seamlessly behind a proxy +because, :ref:`swupd-guide` 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:`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 + +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 avialable, or if :command:`pacrunner` is running +without a PAC file, :command:`FindProxyForURL` will return "DIRECT". + +.. 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 f2c65575..c4a308da 100644 --- a/source/clear-linux/guides/guides.rst +++ b/source/clear-linux/guides/guides.rst @@ -13,9 +13,30 @@ 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 +.. toctree:: + :maxdepth: 1 + :glob: + + clearlinux/* + +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 712e3844..00000000 --- a/source/clear-linux/guides/maintenance/maintenance.rst +++ /dev/null @@ -1,28 +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 - telemetry-enable - 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