path: root/app/xfwp/xfwp.man

.\" $Xorg: xfwp.man,v 1.4 2001/02/09 02:05:46 xorgcvs Exp $
.\" Copyright 1996, 1998  The Open Group
.\" 
.\" Permission to use, copy, modify, distribute, and sell this software and its
.\" documentation for any purpose is hereby granted without fee, provided that
.\" the above copyright notice appear in all copies and that both that
.\" copyright notice and this permission notice appear in supporting
.\" documentation.
.\" 
.\" The above copyright notice and this permission notice shall be included
.\" in all copies or substantial portions of the Software.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
.\" OTHER DEALINGS IN THE SOFTWARE.
.\" 
.\" Except as contained in this notice, the name of The Open Group shall
.\" not be used in advertising or otherwise to promote the sale, use or
.\" other dealings in this Software without prior written authorization
.\" from The Open Group.
.\" 
.\"
.\" $XFree86: xc/programs/xfwp/xfwp.man,v 1.7 2001/02/07 22:35:23 tsi Exp $
.\"
.nh
.TH XFWP 1 __xorgversion__
.SH NAME
xfwp - X firewall proxy
.SH SYNOPSIS
.B xfwp
[option ...]
.PP
.SH COMMAND LINE OPTIONS 
The command line options that can be specified are:
.PP
.TP 8
.B \-cdt \fInum_secs\fP
Used to override the default time-to-close (604800 seconds) for xfwp client 
data connections on which there is no activity (connections over which 
X protocol is already being relayed by xfwp) 
.PP
.TP 8
.B \-clt \fInum_secs\fP
Used to override the default time-to-close (86400 seconds) for xfwp client 
listen ports (ports on xfwp to which X clients first connect when trying to 
reach an X server)
.PP
.TP 8
.B \-pdt \fInum_secs\fP
Used to override the default time-to-close (3600 seconds) for Proxy Manager 
connections on which there is no activity 
.PP
.TP 8
.B \-config \fIfile_name\fP
Used to specify the configuration the name of the configuration file
.PP
.TP 8
.B \-pmport \fIport_number\fP
Used to override the default port address (4444) for proxy manager connections
.PP
.TP 8
.B \-verify
Used to display the configuration file rule that was actually matched for
each service request
.PP
.TP 8
.B \-logfile \fIfile_name\fP
Used to specify the name of a file where audit information should be logged.
The format of a logged entry is: time of day; event code; source IP address;
destination IP address; and configuration rule number.  The event codes 
are: "0" for a successful connection; "1" if a connection is denied because of 
a configuration rule; and "2" if a connection is denied because of an
authorization failure.  If the event code is "1", and a configuration file
is used, the configuration rule number is the line number of the 
configuration file where the match was made (see the section 
CONFIGURATION FILE for more information).  If the event code is not "1",
or if no configuration file is used, the configuration rule number is "-1".
.PP
.TP 8
.B \-loglevel \fI{0,1}\fP
Used to specify the amount of audit detail that should be logged.  If "0", 
all connections are logged.  If "1", only unsuccessful connections are logged.
.PP
.TP 8
.B \-max_pm_conns \fInum_connections\fP
Used to specify the maximum number of Proxy Manager connections.  The
default is 10.
.PP
.TP 8
.B \-max_pm_conns \fInum_connections\fP
Used to specify the maximum number of X server connections.  The
default is 100.
.PP
.SH DESCRIPTION
The X firewall proxy (xfwp) is an application layer gateway proxy
that may be run on a network firewall host to forward X traffic
across the firewall.  Used in conjunction with the X server Security 
extension and authorization checking, xfwp constitutes a safe, simple,
and reliable mechanism both to hide the addresses of X servers located
on the Intranet and to enforce a server connection policy.  Xfwp cannot
protect against mischief originating on the Intranet; however, when 
properly configured it can guarantee that only trusted clients originating
on authorized external Internet hosts will be allowed inbound access to 
local X servers. 

To use xfwp there must be an X proxy manager running in the local environment
which has been configured at start-up to know the location of the xfwp. 
[NOTE:  There may be more than one xfwp running in a local environment; 
see notes below on load balancing for further discussion.]  Using the 
xfindproxy utility (which relays its requests through the proxy manager) 
a user asks xfwp to allocate a client listen port for a particular X server, 
which is internally associated with all future connection requests for that 
server.  This client listen port address is returned by the proxy manager
through xfindproxy.  The xfwp hostname and port number is then passed 
out-of-band (i.e., via a Web browser) to some remote X client, which will 
subsequently connect to xfwp instead of to the target X server.
 
When an X client connection request appears on one of xfwp's listen ports,
xfwp connects to the X server associated with this listen port and performs 
authorization checks against the server as well as against its own configurable
access control list for requesting clients.  If these checks fail, or if
the requested server does not support the X Security Extension, the client 
connection is refused.  Otherwise, the connection is accepted and all ensuing 
data between client and server is relayed by xfwp until the client terminates 
the connection or, in the case of an inactive client, until a configured 
timeout period is exceeded.  Xfwp is designed to block while waiting for
activity on its connections, thereby minimizing demand for system cycles. 

If xfwp is run without a configuration file and thus no sitepolicy is
defined, if xfwp is using an X server where xhost + has been run to turn 
off host-based authorization checks, when a client tries to connect to 
this X server via xfwp, the X server will deny the connection.  If xfwp 
does not define a sitepolicy, host-based authorization must be turned on 
for clients to connect to an X server via the xfwp.
.PP
.SH INTEROPERATION WITH IP PACKET-FILTERING ROUTERS
The whole purpose of the xfwp is to provide reliable control over access
to Intranet X servers by clients originating outside the firewall.  At
the present time, such access control is typically achieved by firewall 
configurations incorporating IP packet-filtering routers.  Frequently,
the rules for such filters deny access to X server ports (range 6000 -
6xxx) for all Intranet host machines.

In order for xfwp to do its job, restrictions on access for ports 6001 - 6xxx
must be removed from the rule-base of the IP packet-filtering router.  [NOTE:
xfwp only assigns ports in the range beginning with 6001; access to port
6000 on all Intranet hosts may continue to be denied.]  This does not 
mean the Intranet firewall will be opened for indiscriminate entry by X
clients.  Instead, xfwp supports a fully configurable rule-based access
control system, similar to that of the IP packet-filter router itself. 
Xfwp in effect adds another level of packet-filtering control which is
fully configurable and applies specifically to X traffic.  See section
entitled CONFIGURATION FILE, below, for further details. 
.PP
.SH INSTALLATION, SETUP AND TROUBLESHOOTING
Xfwp is typically run as a background process on the Intranet firewall host.
It can be launched using any of the command-line options described above.
As noted above, xfwp works only in conjunction with proxy manager and the 
xfindproxy utility.  It can also be configured to support a user-defined
X server site security policy, in which the X server is required to indicate
to xfwp whether or not it supports the particular policy.  Consult the 
X server man pages for further information on these components.  Xfwp 
diagnostics can be turned on by compiling with the -DDEBUG switch.  
Connection status can be recorded by using the -logfile and -loglevel
command line options.
.PP
.SH PERFORMANCE, LOAD BALANCING AND RESOURCE MANAGEMENT 
Xfwp manages four different kinds of connections:  proxy manager (PM) data, 
X client listen, X client data, and X server.  The sysadmin employing xfwp 
must understand how the resources for each of these connection types are 
allocated and reclaimed by xfwp in order to optimize the availability of 
xfwp service.

Each connection-type has a default number of allocation slots and 
a default timeout.  The number of allocation slots for PM connections
and X server connections is configurable via command line options.
Connection timeouts are also configurable via command line options.
Each connection timeout represents the period the connection 
will be allowed to remain open in the absence of any activity on that 
connection.  Whenever there is activity on a connection, the time-to-close 
is automatically reset.  The default distribution of total process connection 
slots across the four connection types, as well as the choice of default
timeouts for the connection types, is governed by a number of assumptions
embedded in the xfwp use model. 


The default number of PM connections is 10 and the
default duration for PM connections is 3,600
seconds (1 hour) for each connection after time of last activity.  
At start-up, xfwp listens for PM connection requests on any non-reserved 
port (default of 4444 if not specified on the xfwp command-line).  The PM 
normally connects to xfwp only when a call is made to the PM with xfindproxy.  
Thereafter, the PM remains connected to xfwp, even after the messaging between 
them has been completed, for the default connection duration period.  In some 
cases this may result in depletion of available PM connection slots.
If the sysadmin expects connections to a single xfwp from many PM's,
xfwp should be started using the -pdt command line option, with a timeout 
value reflecting the desired duration that inactive connections will be 
permitted to remain open. 

Xfwp client listeners are set up by a call to xfindproxy and continue to 
listen for X client connection requests for a default duration of 86,400 
seconds (24 hours) from the point of last activity.  After this time they
are automatically closed and their fd's recovered for future allocation.
In addressing the question of how to choose some alternative timeout
value which will guarantee the availability of client listen ports,
sysadmins should take into consideration the expected delay between
the time when the listener was allocated (using xfindproxy) and the time 
when a client actually attempts to connect to xfwp, as well the likelihood
that client listeners will be re-used after the initial client data 
connection is closed. 

Each client connection is allocated a default lifetime of 604,800 
seconds (7 * 24 hours) 
from the point when it last saw activity.  After this time it is 
automatically closed and its fd's recovered for future allocation.
Because server connections are not actually established until a connection 
request from a remote X client arrives at one of the xfwp's client listen 
ports, the client data timeout applies both to client-xfwp connections as well
as to xfwp-server connections.  If the system administrator expects many
client data connections through xfwp, an overriding of the default timeout
should be considered. 
.PP
.SH CONFIGURATION FILE 
The xfwp configuration file resides on the xfwp host machine and is
used to determine whether X client data connection requests will be
permitted or denied.  The path to the file is specified at start-up
time.  If no configuration file is specified, all X client data 
connection requests routed through xfwp will be by default permitted,
assuming that other X server authorization checks are successful.  If
a configuration file is supplied but none of its entries matches the 
connection request then the connection is by default denied.

If a line in the configuration file begins with the '#' character
or a new-line character, the line is ignored and the evaluator will 
skip the line.

The configuration file supports two entirely independent authorization
checks:  one which is performed by xfwp itself, and a second which is the 
result of xfwp's querying the target X server.  For the first of these,
the configuration file employs a syntax and semantic similar to that of IP 
packet-filtering routers.  It contains zero or more source-destination
rules of the following form:
.PP
{permit | deny} <src> <src mask> [<dest> <dest mask> [<operator> <service>]]
.sp
.IP permit/deny 12
the keywords ``permit'' or ``deny'' indicate whether the 
rule will enable or disable access, respectively
.IP src 12
the IP address against the host who originated the 
connection request will be matched, expressed in IP 
format (x.x.x.x)
.IP "src mask" 12
a subnet mask, also in IP format, for further qualifying
the source mask.  Bits set in the mask indicate bits of the
incoming address to be \fIignored\fP when comparing to the specified src
.IP dest 12
the IP address against which the destination of the 
incoming connection request (i.e. the host IP of the 
X server to which the incoming client is attempting to
connect) will be matched
.IP "dest mask" 12
a subnet mask, also in IP format, for further qualifying
the destination mask.  Bits set in the mask indicate bits of the
destination address to be \fIignored\fP when comparing to the specified dest
.IP operator 12
always ``eq'' (if the service field is not NULL)
.IP service 12
one of the following three strings:  ``pm'', ``fp'', or
``cd'', corresponding to proxy manager, xfindproxy, or
client data, respectively 
.PP
For the second type of authorization check, the configuration file contains 
zero or more site policy rules of the following form:
.PP
{require | disallow} sitepolicy <site_policy> 
.sp
.IP require 12
specifies that the X server \fImust\fP be configured with \fIat least one\fP
of the corresponding site policies, else it must refuse the connection.
.IP disallow 12
specifies that the X server \fImust not\fP be configured with \fIany\fP of
the corresponding site policies, else it must refuse the connection.
.IP sitepolicy 12
a required keyword
.IP "<site_policy>" 12
specifies the policy string.  The string may contain any
combination of alphanumeric characters subject 
only to interpretation by the target X server
.PP
.SH RULES FOR EVALUATING THE XFWP CONFIGURATION FILE ENTRIES
For the first type of configurable authorization checking, access
can be permitted or denied for each connection type based upon
source and, optionally, destination and service.  Each file entry must
at a minimum specify the keyword ``permit'' or ``deny'' and the two
source fields.  The
destination and service fields can be used to provide finer-grained 
access control if desired.
.PP
The algorithm for rule-matching is as follows:  
.PP
.RS 3
  while (more entries to check)
  {
    if ((<originator IP> AND (NOT <src mask>)) == src)
      [if ((<dest X server IP> AND (NOT <dest mask>)) == dest)] 
        [if (service fields present and matching)]
          do either permit or deny connection depending on keyword
    else
      continue 
  }
  if (no rule matches) 
    deny connection
.RE
.PP
If a permit or deny rule does not specify a service and operation, then
the rule applies to all services.  If a configuration file is specified 
and it contains at least one valid deny or permit rule, then a host 
that is not explicitly permitted will be denied a connection.
.PP
Site policy configuration checking constitutes a separate (and X server
only) authorization check on incoming connection requests.  Any number of
require or disallow rules may be specified, but all rules must be of the
same type; that is, a single rule file cannot have both ``require'' and
``disallow'' keywords.  The algorithm for this check is as follows:
.PP
.RS 3
  if (X server recognizes any of the site policy strings)
    if (keyword == require)
      permit connection
    else
      deny connection
  else 
    if (keyword == require)
      deny connection
    else
      permit connection 
.RE
.PP
The site policy check is performed by xfwp only if the source-destination
rules permit the connection.
.PP
.SH
EXAMPLES
.PP
.sp
\fC
.nf
\&# if and only if server supports one of these policies then authorize 
\&# connections, but still subject to applicable rule matches
\&#
require sitepolicy policy1
require sitepolicy policy2
\&#
\&# deny pm connections originating on 8.7.6.5 [NOTE:  If pm service
\&# is explicitly qualified, line must include destination fields as
\&# shown.]
\&#
deny  8.7.6.5  0.0.0.0  0.0.0.0  255.255.255.255  eq  pm
\&#
\&# permit xfindproxy X server connects to anywhere [NOTE:  If
\&# fp service is explicitly qualified, line must include source fields
\&# as shown.]
\&#
permit  0.0.0.0  255.255.255.255   0.0.0.0  255.255.255.255  eq  fp 
\&#
\&# permit all connection types originating from the 192.0.0.0 
\&# IP domain only 
\&#
permit  192.0.0.0   0.255.255.255 
.fi
\fP
.PP
Care should be taken that source-destination rules are written in the correct
order, as the first matching rule will be applied.  In addition to parser
syntax checking, a special command-line switch (-verify) has been provided
to assist the sysadmin in determining which rule was actually matched.  
.PP
.SH BUGS
.PP
Xfwp should check server site policy and security extension before
allocating a listen port. 
.PP 
.SH SEE ALSO
xfindproxy (1), Proxy Management Protocol spec V1.0, proxymngr(1), Xserver(1)
.SH AUTHOR
Reed Augliere, consulting to X Consortium, Inc.