xfwp(1) xfwp(1)
NAME
xfwp - X firewall proxy
SYNOPSIS
xfwp [option ...]
COMMAND LINE OPTIONS
The command line options that can be specified are:
-cdt num_secs
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)
-clt num_secs
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)
-pdt num_secs
Used to override the default time-to-close (3600 seconds) for
Proxy Manager connections on which there is no activity
-config file_name
Used to specify the configuration the name of the configuration
file
-pmport port_number
Used to override the default port address (4444) for proxy man-
ager connections
-verify Used to display the configuration file rule that was actually
matched for each service request
-logfile file_name
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 suc-
cessful 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".
-loglevel {0,1}
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.
-max_pm_conns num_connections
Used to specify the maximum number of Proxy Manager connec-
tions. The default is 10.
-max_pm_conns num_connections
Used to specify the maximum number of X server connections.
The default is 100.
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 pro-
tect against mischief originating on the Intranet; however, when prop-
erly 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 envi-
ronment 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 con-
nect 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.
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 fire-
wall. 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 con-
figurable 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.
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 informa-
tion on these components. Xfwp diagnostics can be turned on by compil-
ing with the -DDEBUG switch. Connection status can be recorded by
using the -logfile and -loglevel command line options.
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 con-
nection 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. Connec-
tion 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 auto-
matically 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 alterna-
tive timeout value which will guarantee the availability of client lis-
ten 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 sec-
onds (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.
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 connec-
tion requests routed through xfwp will be by default permitted, assum-
ing that other X server authorization checks are successful. If a con-
figuration file is supplied but none of its entries matches the connec-
tion 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:
{permit | deny} <src> <src mask> [<dest> <dest mask> [<operator> <ser-
vice>]]
permit/deny the keywords ``permit'' or ``deny'' indicate whether the
rule will enable or disable access, respectively
src the IP address against the host who originated the connec-
tion request will be matched, expressed in IP format
(x.x.x.x)
src mask 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 ignored when comparing to the speci-
fied src
dest the IP address against which the destination of the incom-
ing connection request (i.e. the host IP of the X server to
which the incoming client is attempting to connect) will be
matched
dest mask 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 ignored when comparing to
the specified dest
operator always ``eq'' (if the service field is not NULL)
service one of the following three strings: ``pm'', ``fp'', or
``cd'', corresponding to proxy manager, xfindproxy, or
client data, respectively
For the second type of authorization check, the configuration file con-
tains zero or more site policy rules of the following form:
{require | disallow} sitepolicy <site_policy>
require specifies that the X server must be configured with at
least one of the corresponding site policies, else it must
refuse the connection.
disallow specifies that the X server must not be configured with any
of the corresponding site policies, else it must refuse the
connection.
sitepolicy a required keyword
<site_policy>
specifies the policy string. The string may contain any
combination of alphanumeric characters subject only to
interpretation by the target X server
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.
The algorithm for rule-matching is as follows:
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
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.
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:
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
The site policy check is performed by xfwp only if the source-destina-
tion rules permit the connection.
EXAMPLES
# 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
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.
BUGS
Xfwp should check server site policy and security extension before
allocating a listen port.
SEE ALSO
xfindproxy(1), Proxy Management Protocol spec V1.0, proxymngr(1),
Xserver(1)
AUTHOR
Reed Augliere, consulting to X Consortium, Inc.
X Version 11 Release 6.6 xfwp(1)
Mac OS X 10.4 X11 - Generated Sat Apr 30 05:01:10 CDT 2005