.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: dacs_uproxy
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS_UPROXY" "8" "02/19/2019" "DACS 1.4.40" "DACS Web Services Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacs_uproxy \- minimal HTTP proxying
.SH "SYNOPSIS"
.HP \w'\fBdacs_uproxy\fR\ 'u
\fBdacs_uproxy\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This web service is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_uproxy\fR
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
\fBdacs_uproxy\fR, not the host that issues the initial request\&.
.PP
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
\fBDACS\fR\&. All access control is performed by the jurisdiction that runs
\fBdacs_uproxy\fR\&. Similarly, the program can be useful for forwarding requests that originate behind the firewall, subject to access control permission\&.
.PP
\fBdacs_uproxy\fR
is not a transparent proxy server\&. A request URL must be explicitly addressed to it and include a (partial) name for the target resource\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
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
\fBdacs_uproxy\fR\&.
.PP
Particular care must be taken if a program that is invoked by
\fBdacs_uproxy\fR
generates a redirect that may be handled internally by the program\*(Aqs web server\&. In this event the new request arising from the redirection
\fIwill not automatically be subjected to access control\fR
because the new request does come through
\fBdacs_uproxy\fR\&. 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\&.
.PP
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,
\m[blue]\fBUPROXY_APPROVED\fR\m[]\&\s-2\u[2]\d\s+2
directives must be configured to allow proxying to specific origin servers\&.
.PP
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\*(Aqs headers and other information\&.
.sp .5v
.RE
.PP
With the exception of the
Cookie
header, most request headers that accompany the initial request are sent with the proxied request\&.
\fBdacs_uproxy\fR
makes no attempt to "impersonate" the user\*(Aqs host, however\&. Therefore, to the origin server it appears as if the request is coming from
\fBdacs_uproxy\fR
and the IP address from which the forwarded request is sent\&. Any cookies sent with the initial request are interpreted by
\fBdacs_uproxy\fR
(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\&.
.PP
So that the proxied web service can tell that it is being invoked by
\fBdacs_uproxy\fR, an extension header named
DACS\-Uproxy\-Via
is included with the forwarded request\&. Its value is the URL of
\fBdacs_uproxy\fR
with the
proxied host
appended\&. With Apache, its value can be accessed from the environment variable
\fBHTTP_DACS_UPROXY_VIA\fR\&.
.PP
If
\fBdacs_uproxy\fR
is passed a
\m[blue]\fBDACS_APPROVAL\fR\m[]\&\s-2\u[3]\d\s+2
value, that value is forwarded with the request through the
DACS\-Uproxy\-Approval
header and made available by Apache in the
\fBHTTP_DACS_UPROXY_APPROVAL\fR
environment variable\&. A program invoked indirectly through
\fBdacs_uproxy\fR
can use this information to confirm that
\fBDACS\fR
authorized the request\&.
.PP
If the forwarded request generates a redirect (a
3xx
class HTTP status code is returned), it causes
\fBdacs_uproxy\fR
to return the redirection request\&.
.PP
The program is a minimal or "micro" HTTP proxy, hence the
\fIu\fR
in
\fBdacs_uproxy\fR
should really be the Greek letter
\fImu\fR\&.
.SS "Web Service Arguments"
.PP
With some exceptions, all arguments passed to
\fBdacs_uproxy\fR
are forwarded to the proxied request and are not interpreted by
\fBdacs_uproxy\fR\&. The first exception is
\m[blue]\fBDACS_ACS\fR\m[]\&\s-2\u[4]\d\s+2\&. Another exception is
\fIDACS_UPROXY\fR; if its value is
DEBUG, debugging output is produced\&. Neither of these arguments is forwarded with the proxied request\&.
.SS "Operation"
.PP
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
\fBdacs_uproxy\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
https://example\&.com/cgi\-bin/dacs/dacs_uproxy/foo\&.example\&.com/cgi\-bin/some_app
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
<acl_rule status="enabled">
  <services>
    <service url_expr=\*(Aq"${Conf::dacs_cgi_bin_prefix}/dacs_uproxy"\*(Aq/>
    <service url_expr=\*(Aq"${Conf::dacs_cgi_bin_prefix}/dacs_uproxy/*"\*(Aq/>
  </services>

  <rule order="allow,deny">
   <allow>
     user("auth")
   </allow>
  </rule>
</acl_rule>
.fi
.if n \{\
.RE
.\}
.sp
Most sophisticated rules may of course be used to further constrain how
\fBdacs_uproxy\fR
can be used and by whom\&.
.PP
The
\m[blue]\fBUPROXY_APPROVED\fR\m[]\&\s-2\u[2]\d\s+2
directive must be configured before
\fBdacs_uproxy\fR
will do anything, even if otherwise permitted by an access control rule\&.
.PP
If SSL/TLS is used for the proxied request, the usual
\fBDACS\fR
configuration directives for SSL/TLS apply \- see
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[5]\d\s+2\&. SSL/TLS can be used for the proxied request independently of whether it is used for the initial request\&.
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "BUGS"
.PP
The implementation may not yet fully conform to
\m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[6]\d\s+2\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[6]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[7]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2012 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[8]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
UPROXY_APPROVED
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#UPROXY_APPROVED
.RE
.IP " 3." 4
DACS_APPROVAL
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_approval
.RE
.IP " 4." 4
DACS_ACS
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_acs_argument
.RE
.IP " 5." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP " 6." 4
RFC 2616
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2616.txt
.RE
.IP " 7." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP " 8." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE