From 1e0175b1954375882eef4a8965983cb71f5c1894 Mon Sep 17 00:00:00 2001 From: Kevin Putnam Date: Mon, 25 Mar 2019 09:19:59 -0700 Subject: [PATCH] Move autoproxy content to updated guide template (#417) * first draft revision of autoproxy guide with guide template * removed related topics as there is currently nothing that qualifies * restructured a bit more to match guide template; removed autoproxy_about.txt and autoproxy_guide.txt as they are no longer needed * made changes recommended by @mvincerx * minor corrections based on feedback --- .../guides/maintenance/autoproxy.rst | 151 +++++++++++++++++- .../guides/maintenance/autoproxy_about.txt | 43 ----- .../guides/maintenance/autoproxy_guide.txt | 77 --------- 3 files changed, 143 insertions(+), 128 deletions(-) delete mode 100644 source/clear-linux/guides/maintenance/autoproxy_about.txt delete mode 100644 source/clear-linux/guides/maintenance/autoproxy_guide.txt diff --git a/source/clear-linux/guides/maintenance/autoproxy.rst b/source/clear-linux/guides/maintenance/autoproxy.rst index b5131ab7..129cae51 100644 --- a/source/clear-linux/guides/maintenance/autoproxy.rst +++ b/source/clear-linux/guides/maintenance/autoproxy.rst @@ -3,16 +3,151 @@ Autoproxy ######### -.. rst-class:: content-collapse +Autoproxy is provided to enable |CL-ATTR| to work smoothly behind a +corporate proxy. -About -===== +.. contents:: + :local: + :depth: 1 -.. include:: autoproxy_about.txt +Description +*********** -.. rst-class:: content-collapse +Autoproxy tries to detect 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. -Guide -===== +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”. -.. include:: autoproxy_guide.txt \ No newline at end of file +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 it works +************ + +We designed Autoproxy around tools provided by most Linux +distributions 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. All these steps happen in the background with no user interaction. + +Troubleshooting +=============== + +Autoproxy allows |CL| to operate seamlessly behind a proxy +because :ref:`swupd ` and other |CL| tools are implemented on +top of libcurl. Tools that do not use libcurl, like git, must +be configured independently. + +If you are familiar with PAC files and WPAD, you can use +:command:`pacdiscovery` and :command:`FindProxyForURL` to +troubleshoot problems with autproxy. + +.. note:: + + Learn more about WPAD, PAC files, and PAC functions at `findproxyforurl`_. + +.. _findproxyforurl: http://findproxyforurl.com/ + +Run :command:`pacdiscovery` with no arguments to indicate + +1. if there is a problem resolving the :command:`WPAD` host name resolution: + + .. code-block:: bash + + pacdiscovery + + .. code-block:: console + + failed getaddrinfo: No address associated with hostname + Unable to find wpad host + +2. or if the :command:`pacrunner` service is disabled (masked). + + .. code-block:: bash + + pacdiscovery + + .. code-block:: console + + 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-block:: bash + + systemctl unmask pacrunner.service + +:command:`FindProxyForURL` with :command:`busctl` can also indicate if the +:command:`pacrunner.service` is masked. + +.. code-block:: bash + + busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client + +.. code-block:: console + + 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-block:: bash + + busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client + +.. code-block:: console + + 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-block:: bash + + busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client + +.. code-block:: console + + 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-block:: bash + + 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/maintenance/autoproxy_about.txt b/source/clear-linux/guides/maintenance/autoproxy_about.txt deleted file mode 100644 index 80dcaa4e..00000000 --- a/source/clear-linux/guides/maintenance/autoproxy_about.txt +++ /dev/null @@ -1,43 +0,0 @@ -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/maintenance/autoproxy_guide.txt b/source/clear-linux/guides/maintenance/autoproxy_guide.txt deleted file mode 100644 index 3422a747..00000000 --- a/source/clear-linux/guides/maintenance/autoproxy_guide.txt +++ /dev/null @@ -1,77 +0,0 @@ -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