393 lines
17 KiB
Groff
393 lines
17 KiB
Groff
.\" $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.
|