"Fossies" - the Fresh Open Source Software Archive

Member "dacs-1.4.46/man/dacs_uproxy.8" (8 Jun 2021, 12834 Bytes) of package /linux/www/dacs-1.4.46.txz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 .\" Copyright (c) 2003-2021
    2 .\" Distributed Systems Software.  All rights reserved.
    3 .\" See the file LICENSE for redistribution information.
    4 .\" $Id: copyright-nr 3149 2021-01-14 21:54:54Z brachman $
    5 .\"     Title: dacs_uproxy
    6 .\"    Author: [see the "AUTHOR" section]
    7 .\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
    8 .\"      Date: 06/08/2021
    9 .\"    Manual: DACS Web Services Manual
   10 .\"    Source: DACS 1.4.46
   11 .\"  Language: English
   12 .\"
   13 .TH "DACS_UPROXY" "8" "06/08/2021" "DACS 1.4.46" "DACS Web Services Manual"
   14 .\" -----------------------------------------------------------------
   15 .\" * (re)Define some macros
   16 .\" -----------------------------------------------------------------
   17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   18 .\" toupper - uppercase a string (locale-aware)
   19 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   20 .de toupper
   21 .tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ
   22 \\$*
   23 .tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz
   24 ..
   25 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   26 .\" SH-xref - format a cross-reference to an SH section
   27 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   28 .de SH-xref
   29 .ie n \{\
   30 .\}
   31 .toupper \\$*
   32 .el \{\
   33 \\$*
   34 .\}
   35 ..
   36 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   37 .\" SH - level-one heading that works better for non-TTY output
   38 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   39 .de1 SH
   40 .\" put an extra blank line of space above the head in non-TTY output
   41 .if t \{\
   42 .sp 1
   43 .\}
   44 .sp \\n[PD]u
   45 .nr an-level 1
   46 .set-an-margin
   47 .nr an-prevailing-indent \\n[IN]
   48 .fi
   49 .in \\n[an-margin]u
   50 .ti 0
   51 .HTML-TAG ".NH \\n[an-level]"
   52 .it 1 an-trap
   53 .nr an-no-space-flag 1
   54 .nr an-break-flag 1
   55 \." make the size of the head bigger
   56 .ps +3
   57 .ft B
   58 .ne (2v + 1u)
   59 .ie n \{\
   60 .\" if n (TTY output), use uppercase
   61 .toupper \\$*
   62 .\}
   63 .el \{\
   64 .nr an-break-flag 0
   65 .\" if not n (not TTY), use normal case (not uppercase)
   66 \\$1
   67 .in \\n[an-margin]u
   68 .ti 0
   69 .\" if not n (not TTY), put a border/line under subheading
   70 .sp -.6
   71 \l'\n(.lu'
   72 .\}
   73 ..
   74 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   75 .\" SS - level-two heading that works better for non-TTY output
   76 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   77 .de1 SS
   78 .sp \\n[PD]u
   79 .nr an-level 1
   80 .set-an-margin
   81 .nr an-prevailing-indent \\n[IN]
   82 .fi
   83 .in \\n[IN]u
   84 .ti \\n[SN]u
   85 .it 1 an-trap
   86 .nr an-no-space-flag 1
   87 .nr an-break-flag 1
   88 .ps \\n[PS-SS]u
   89 \." make the size of the head bigger
   90 .ps +2
   91 .ft B
   92 .ne (2v + 1u)
   93 .if \\n[.$] \&\\$*
   94 ..
   95 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   96 .\" BB/BE - put background/screen (filled box) around block of text
   97 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   98 .de BB
   99 .if t \{\
  100 .sp -.5
  101 .br
  102 .in +2n
  103 .ll -2n
  104 .gcolor red
  105 .di BX
  106 .\}
  107 ..
  108 .de EB
  109 .if t \{\
  110 .if "\\$2"adjust-for-leading-newline" \{\
  111 .sp -1
  112 .\}
  113 .br
  114 .di
  115 .in
  116 .ll
  117 .gcolor
  118 .nr BW \\n(.lu-\\n(.i
  119 .nr BH \\n(dn+.5v
  120 .ne \\n(BHu+.5v
  121 .ie "\\$2"adjust-for-leading-newline" \{\
  122 \M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
  123 .\}
  124 .el \{\
  125 \M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[]
  126 .\}
  127 .in 0
  128 .sp -.5v
  129 .nf
  130 .BX
  131 .in
  132 .sp .5v
  133 .fi
  134 .\}
  135 ..
  136 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  137 .\" BM/EM - put colored marker in margin next to block of text
  138 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  139 .de BM
  140 .if t \{\
  141 .br
  142 .ll -2n
  143 .gcolor red
  144 .di BX
  145 .\}
  146 ..
  147 .de EM
  148 .if t \{\
  149 .br
  150 .di
  151 .ll
  152 .gcolor
  153 .nr BH \\n(dn
  154 .ne \\n(BHu
  155 \M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[]
  156 .in 0
  157 .nf
  158 .BX
  159 .in
  160 .fi
  161 .\}
  162 ..
  163 .\" -----------------------------------------------------------------
  164 .\" * set default formatting
  165 .\" -----------------------------------------------------------------
  166 .\" disable hyphenation
  167 .nh
  168 .\" disable justification (adjust text to left margin only)
  169 .ad l
  170 .\" -----------------------------------------------------------------
  171 .\" * MAIN CONTENT STARTS HERE *
  172 .\" -----------------------------------------------------------------
  173 .SH "Name"
  174 dacs_uproxy \- minimal HTTP proxying
  175 .SH "Synopsis"
  176 .fam C
  177 .HP \w'\fBdacs_uproxy\fR\ 'u
  178 \fBdacs_uproxy\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
  179 .fam
  180 .SH "DESCRIPTION"
  181 .PP
  182 This web service is part of the
  183 \fBDACS\fR
  184 suite\&.
  185 .PP
  186 The
  187 \fBdacs_uproxy\fR
  188 web service accepts an incoming HTTP request (the
  189 initial request), then reissues a nearly identical HTTP request to a different URL (the
  190 proxied request) and returns its unaltered response\&. The initial request must use either the
  191 \FCGET\F[]
  192 or
  193 \FCPOST\F[]
  194 HTTP method; the proxied request will use the same method as the initial request\&. Note that the
  195 origin server
  196 (the web server that receives the proxied request) will see a request that originates at the host that runs
  197 \fBdacs_uproxy\fR, not the host that issues the initial request\&.
  198 .PP
  199 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
  200 \fBDACS\fR\&. All access control is performed by the jurisdiction that runs
  201 \fBdacs_uproxy\fR\&. Similarly, the program can be useful for forwarding requests that originate behind the firewall, subject to access control permission\&.
  202 .PP
  203 \fBdacs_uproxy\fR
  204 is not a transparent proxy server\&. A request URL must be explicitly addressed to it and include a (partial) name for the target resource\&.
  205 .if n \{\
  206 .sp
  207 .\}
  208 .RS 4
  209 .BM yellow
  210 .it 1 an-trap
  211 .nr an-no-space-flag 1
  212 .nr an-break-flag 1
  213 .br
  214 .ps +1
  215 \fBSecurity\fR
  216 .ps -1
  217 .br
  218 .PP
  219 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
  220 \fBdacs_uproxy\fR\&.
  221 .PP
  222 Particular care must be taken if a program that is invoked by
  223 \fBdacs_uproxy\fR
  224 generates a redirect that may be handled internally by the program\'s web server\&. In this event the new request arising from the redirection
  225 \fIwill not automatically be subjected to access control\fR
  226 because the new request does come through
  227 \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\&.
  228 .PP
  229 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,
  230 \m[blue]\fBUPROXY_APPROVED\fR\m[]\&\s-2\u[2]\d\s+2
  231 directives must be configured to allow proxying to specific origin servers\&.
  232 .PP
  233 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\&.
  234 .sp .5v
  235 .EM yellow
  236 .RE
  237 .PP
  238 With the exception of the
  239 Cookie
  240 header, most request headers that accompany the initial request are sent with the proxied request\&.
  241 \fBdacs_uproxy\fR
  242 makes no attempt to "impersonate" the user\'s host, however\&. Therefore, to the origin server it appears as if the request is coming from
  243 \fBdacs_uproxy\fR
  244 and the IP address from which the forwarded request is sent\&. Any cookies sent with the initial request are interpreted by
  245 \fBdacs_uproxy\fR
  246 (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\&.
  247 .PP
  248 So that the proxied web service can tell that it is being invoked by
  249 \fBdacs_uproxy\fR, an extension header named
  250 DACS\-Uproxy\-Via
  251 is included with the forwarded request\&. Its value is the URL of
  252 \fBdacs_uproxy\fR
  253 with the
  254 proxied host
  255 appended\&. With Apache, its value can be accessed from the environment variable
  256 \fBHTTP_DACS_UPROXY_VIA\fR\&.
  257 .PP
  258 If
  259 \fBdacs_uproxy\fR
  260 is passed a
  261 \m[blue]\fBDACS_APPROVAL\fR\m[]\&\s-2\u[3]\d\s+2
  262 value, that value is forwarded with the request through the
  263 DACS\-Uproxy\-Approval
  264 header and made available by Apache in the
  265 \fBHTTP_DACS_UPROXY_APPROVAL\fR
  266 environment variable\&. A program invoked indirectly through
  267 \fBdacs_uproxy\fR
  268 can use this information to confirm that
  269 \fBDACS\fR
  270 authorized the request\&.
  271 .PP
  272 If the forwarded request generates a redirect (a
  273 \FC3xx\F[]
  274 class HTTP status code is returned), it causes
  275 \fBdacs_uproxy\fR
  276 to return the redirection request\&.
  277 .PP
  278 The program is a minimal or "micro" HTTP proxy, hence the
  279 \fIu\fR
  280 in
  281 \fBdacs_uproxy\fR
  282 should really be the Greek letter
  283 \fImu\fR\&.
  284 .SS "Web Service Arguments"
  285 .PP
  286 With some exceptions, all arguments passed to
  287 \fBdacs_uproxy\fR
  288 are forwarded to the proxied request and are not interpreted by
  289 \fBdacs_uproxy\fR\&. The first exception is
  290 \m[blue]\fBDACS_ACS\fR\m[]\&\s-2\u[4]\d\s+2\&. Another exception is
  291 \fIDACS_UPROXY\fR; if its value is
  292 \FCDEBUG\F[], debugging output is produced\&. Neither of these arguments is forwarded with the proxied request\&.
  293 .SS "Operation"
  294 .PP
  295 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
  296 \fBdacs_uproxy\fR
  297 that the client wants to use is
  298 \FChttps://example\&.com/cgi\-bin/dacs/dacs_uproxy\F[]\&. Let us also assume that the client wants to access a web service at
  299 \FCfoo\&.example\&.com\F[]
  300 (the
  301 proxied host) and that this web service can be invoked from
  302 \FCexample\&.com\F[]
  303 (the
  304 proxying host) as
  305 \FChttps://foo\&.example\&.com/cgi\-bin/some_app\F[]\&. To achieve this, the client would invoke this URL:
  306 .sp
  307 .if n \{\
  308 .RS 4
  309 .\}
  310 .fam C
  311 .ps -1
  312 .nf
  313 .if t \{\
  314 .sp -1
  315 .\}
  316 .BB lightgray adjust-for-leading-newline
  317 .sp -1
  318 
  319 https://example\&.com/cgi\-bin/dacs/dacs_uproxy/foo\&.example\&.com/cgi\-bin/some_app
  320 .EB lightgray adjust-for-leading-newline
  321 .if t \{\
  322 .sp 1
  323 .\}
  324 .fi
  325 .fam
  326 .ps +1
  327 .if n \{\
  328 .RE
  329 .\}
  330 .PP
  331 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
  332 UPROXY_APPROVED) to form the final proxied URL\&.
  333 .PP
  334 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:
  335 .sp
  336 .if n \{\
  337 .RS 4
  338 .\}
  339 .fam C
  340 .ps -1
  341 .nf
  342 .if t \{\
  343 .sp -1
  344 .\}
  345 .BB lightgray adjust-for-leading-newline
  346 .sp -1
  347 
  348 <acl_rule status="enabled">
  349   <services>
  350     <service url_expr=\'"${Conf::dacs_cgi_bin_prefix}/dacs_uproxy"\'/>
  351     <service url_expr=\'"${Conf::dacs_cgi_bin_prefix}/dacs_uproxy/*"\'/>
  352   </services>
  353 
  354   <rule order="allow,deny">
  355    <allow>
  356      user("auth")
  357    </allow>
  358   </rule>
  359 </acl_rule>
  360 .EB lightgray adjust-for-leading-newline
  361 .if t \{\
  362 .sp 1
  363 .\}
  364 .fi
  365 .fam
  366 .ps +1
  367 .if n \{\
  368 .RE
  369 .\}
  370 .sp
  371 Most sophisticated rules may of course be used to further constrain how
  372 \fBdacs_uproxy\fR
  373 can be used and by whom\&.
  374 .PP
  375 The
  376 \m[blue]\fBUPROXY_APPROVED\fR\m[]\&\s-2\u[2]\d\s+2
  377 directive must be configured before
  378 \fBdacs_uproxy\fR
  379 will do anything, even if otherwise permitted by an access control rule\&.
  380 .PP
  381 If SSL/TLS is used for the proxied request, the usual
  382 \fBDACS\fR
  383 configuration directives for SSL/TLS apply \- see
  384 \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\&.
  385 .SH "DIAGNOSTICS"
  386 .PP
  387 The program exits
  388 \FC0\F[]
  389 if everything was fine,
  390 \FC1\F[]
  391 if an error occurred\&.
  392 .SH "BUGS"
  393 .PP
  394 The implementation may not yet fully conform to
  395 \m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[6]\d\s+2\&.
  396 .SH "SEE ALSO"
  397 .PP
  398 
  399 \m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[6]\d\s+2
  400 .SH "AUTHOR"
  401 .PP
  402 Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[7]\d\s+2)
  403 .SH "COPYING"
  404 .PP
  405 Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
  406 \m[blue]\fB\FCLICENSE\F[]\fR\m[]\&\s-2\u[8]\d\s+2
  407 file that accompanies the distribution for licensing information\&.
  408 .SH "Notes"
  409 .IP " 1." 4
  410 dacsoptions
  411 .RS 4
  412 \%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
  413 .RE
  414 .IP " 2." 4
  415 UPROXY_APPROVED
  416 .RS 4
  417 \%http://dacs.dss.ca/man/dacs.conf.5.html#UPROXY_APPROVED
  418 .RE
  419 .IP " 3." 4
  420 DACS_APPROVAL
  421 .RS 4
  422 \%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_approval
  423 .RE
  424 .IP " 4." 4
  425 DACS_ACS
  426 .RS 4
  427 \%http://dacs.dss.ca/man/dacs_acs.8.html#dacs_acs_argument
  428 .RE
  429 .IP " 5." 4
  430 dacs.conf(5)
  431 .RS 4
  432 \%http://dacs.dss.ca/man/dacs.conf.5.html
  433 .RE
  434 .IP " 6." 4
  435 RFC 2616
  436 .RS 4
  437 \%https://www.rfc-editor.org/rfc/rfc2616.txt
  438 .RE
  439 .IP " 7." 4
  440 www.dss.ca
  441 .RS 4
  442 \%https://www.dss.ca
  443 .RE
  444 .IP " 8." 4
  445 \FCLICENSE\F[]
  446 .RS 4
  447 \%http://dacs.dss.ca/man/../misc/LICENSE
  448 .RE