adding autoproxy content

source/clear-linux/guides/maintenance/autoproxy.rst

@@ -0,0 +1,18 @@
+.. _autoproxy:
+
+Autoproxy
+#########
+
+.. rst-class:: content-collapse
+
+About
+=====
+
+.. include:: autoproxy_about.txt
+
+.. rst-class:: content-collapse
+
+Guide
+=====
+
+.. include:: autoproxy_guide.txt

source/clear-linux/guides/maintenance/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.

source/clear-linux/guides/maintenance/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.<domain>
+
+: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:<port>"
+
+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.

source/clear-linux/guides/maintenance/maintenance.rst

@@ -10,6 +10,7 @@ completed.
 .. toctree::
    :maxdepth: 2
 
+   autoproxy
    developer-workstation
    swupd-search
    enable-user-space