NAME

       dacs_uproxy - minimal HTTP proxying

SYNOPSIS

       dacs_uproxy [dacsoptions[1]]

DESCRIPTION

       This web service is part of the DACS suite.

       The dacs_uproxy web service accepts an incoming HTTP request (the initial request), then reissues a
       nearly identical HTTP request to a different URL (the proxied request) and returns its unaltered
       response. The initial request must use either the GET or POST HTTP method; the proxied request will use
       the same method as the initial request. Note that the origin server (the web server that receives the
       proxied request) will see a request that originates at the host that runs dacs_uproxy, not the host that
       issues the initial request.

       When run on a firewall host, the program can be useful for forwarding incoming requests to interior
       hosts. An origin server does not need to be running DACS. All access control is performed by the
       jurisdiction that runs dacs_uproxy. Similarly, the program can be useful for forwarding requests that
       originate behind the firewall, subject to access control permission.

       dacs_uproxy is not a transparent proxy server. A request URL must be explicitly addressed to it and
       include a (partial) name for the target resource.

           Security

           The program must be configured with care because it can expose otherwise inaccessible hosts to
           arbitrary HTTP requests from any source that can connect to dacs_uproxy.

           Particular care must be taken if a program that is invoked by dacs_uproxy generates a redirect that
           may be handled internally by the program's web server. In this event the new request arising from the
           redirection will not automatically be subjected to access control because the new request does come
           through dacs_uproxy. Therefore, local redirects must be avoided by proxied web services, resources
           that might be invoked through a local redirect must be publicly accessible, or authorization checking
           must somehow be arranged for these resources.

           Access control rules are primarily responsible for expressing restrictions on what can be proxied and
           who can use this service. By default, all access to this service is denied. Additionally,
           UPROXY_APPROVED[2] directives must be configured to allow proxying to specific origin servers.

           Although in its current form the program has the effect of anonymizing the proxied request, this is
           more of a bug than a feature. Future versions may forward an initial request's headers and other
           information.

       With the exception of the Cookie header, most request headers that accompany the initial request are sent
       with the proxied request.  dacs_uproxy makes no attempt to "impersonate" the user's host, however.
       Therefore, to the origin server it appears as if the request is coming from dacs_uproxy and the IP
       address from which the forwarded request is sent. Any cookies sent with the initial request are
       interpreted by dacs_uproxy (e.g., to identify the user making the request for access control purposes).
       At present, it is not possible to forward cookies with the proxied request.

       So that the proxied web service can tell that it is being invoked by dacs_uproxy, an extension header
       named DACS-Uproxy-Via is included with the forwarded request. Its value is the URL of dacs_uproxy with
       the proxied host appended. With Apache, its value can be accessed from the environment variable
       HTTP_DACS_UPROXY_VIA.

       If dacs_uproxy is passed a DACS_APPROVAL[3] value, that value is forwarded with the request through the
       DACS-Uproxy-Approval header and made available by Apache in the HTTP_DACS_UPROXY_APPROVAL environment
       variable. A program invoked indirectly through dacs_uproxy can use this information to confirm that DACS
       authorized the request.

       If the forwarded request generates a redirect (a 3xx class HTTP status code is returned), it causes
       dacs_uproxy to return the redirection request.

       The program is a minimal or "micro" HTTP proxy, hence the u in dacs_uproxy should really be the Greek
       letter mu.

   Web Service Arguments
       With some exceptions, all arguments passed to dacs_uproxy are forwarded to the proxied request and are
       not interpreted by dacs_uproxy. The first exception is DACS_ACS[4]. Another exception is DACS_UPROXY; if
       its value is DEBUG, debugging output is produced. Neither of these arguments is forwarded with the
       proxied request.

   Operation
       A specification of the proxied request appears as a component of the initial request. It is best to
       explain this with an example. Let us assume that the URL for the dacs_uproxy that the client wants to use
       is https://example.com/cgi-bin/dacs/dacs_uproxy. Let us also assume that the client wants to access a web
       service at foo.example.com (the proxied host) and that this web service can be invoked from example.com
       (the proxying host) as https://foo.example.com/cgi-bin/some_app. To achieve this, the client would invoke
       this URL:

           https://example.com/cgi-bin/dacs/dacs_uproxy/foo.example.com/cgi-bin/some_app

       Note that no scheme is included with the name of the proxied host. A port number may follow it, however,
       and any path components that follow are appended (after the mapping specified by UPROXY_APPROVED) to form
       the final proxied URL.

       For this example to be authorized, an access control rule must grant the user access to the initial URL.
       Whether there is additional access control enforced at the proxied host is the responsibility of a web
       administrator. A simple rule that grants access to any authenticated user looks like this:

           <acl_rule status="enabled">
             <services>
               <service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_uproxy"'/>
               <service url_expr='"${Conf::dacs_cgi_bin_prefix}/dacs_uproxy/*"'/>
             </services>

             <rule order="allow,deny">
              <allow>
                user("auth")
              </allow>
             </rule>
           </acl_rule>

       Most sophisticated rules may of course be used to further constrain how dacs_uproxy can be used and by
       whom.

       The UPROXY_APPROVED[2] directive must be configured before dacs_uproxy will do anything, even if
       otherwise permitted by an access control rule.

       If SSL is used for the proxied request, the usual DACS configuration directives for SSL apply - see
       dacs.conf(5)[5]. SSL can be used for the proxied request independently of whether it is used for the
       initial request.

DIAGNOSTICS

       The program exits 0 if everything was fine, 1 if an error occurred.

BUGS

       The implementation may not yet fully conform to RFC 2616[6].

SEE ALSO

       RFC 2616[6]

AUTHOR

       Distributed Systems Software (www.dss.ca[7])

COPYING

       Copyright2003-2012 Distributed Systems Software. See the LICENSE[8] file that accompanies the
       distribution for licensing information.

NOTES

        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. UPROXY_APPROVED
           http://dacs.dss.ca/man/dacs.conf.5.html#UPROXY_APPROVED

        3. DACS_APPROVAL
           http://dacs.dss.ca/man/dacs_acs.8.html#dacs_approval

        4. DACS_ACS
           http://dacs.dss.ca/man/dacs_acs.8.html#dacs_acs_argument

        5. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

        6. RFC 2616
           http://www.rfc-editor.org/rfc/rfc2616.txt

        7. www.dss.ca
           http://www.dss.ca

        8. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE

DACS 1.4.28b                                       02/04/2014                                     DACS_UPROXY(8)