MirBSD manpage: xfwp(1)


XFWP(1)             UNIX Programmer's Manual              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 pro-
             tocol 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 manager 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 con-
             nection is denied because of an authorization
             failure.  If the event code is "1", and a configura-
             tion 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

XFree86                   Version 4.5.0                         1

XFWP(1)             UNIX Programmer's Manual              XFWP(1)

             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
             connections.  The default is 10.

     -max_pm_conns num_connections
             Used to specify the maximum number of X server con-
             nections.  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 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 associ-
     ated 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

XFree86                   Version 4.5.0                         2

XFWP(1)             UNIX Programmer's Manual              XFWP(1)

     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.

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 con-
     trol is typically achieved by firewall configurations incor-
     porating 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 confi-
     gurable 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 information on these components.  Xfwp
     diagnostics can be turned on by compiling with the -DDEBUG
     switch. Connection status can be recorded by using the -log-
     file and -loglevel command line options.

XFree86                   Version 4.5.0                         3

XFWP(1)             UNIX Programmer's Manual              XFWP(1)

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 con-
     figurable 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 connec-
     tion.  Whenever there is activity on a connection, the
     time-to-close is automatically reset.  The default distribu-
     tion of total process connection slots across the four con-
     nection 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 per-
     mitted 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 considera-
     tion 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.

XFree86                   Version 4.5.0                         4

XFWP(1)             UNIX Programmer's Manual              XFWP(1)

     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 connec-
     tions.  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 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 configura-
     tion 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> <service>]]

     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 connection 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 specified src

XFree86                   Version 4.5.0                         5

XFWP(1)             UNIX Programmer's Manual              XFWP(1)

     dest        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

     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, respec-
                 tively

     For the second type of authorization check, the configura-
     tion file contains 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 pol-
                 icies, else it must refuse the connection.

     disallow    specifies that the X server must not be config-
                 ured with any of the corresponding site poli-
                 cies, else it must refuse the connection.

     sitepolicy  a required keyword

     <site_policy>
                 specifies the policy string.  The string may
                 contain any combination of alphanumeric charac-
                 ters subject only to interpretation by the tar-
                 get X server

RULES FOR EVALUATING THE XFWP CONFIGURATION

     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 ``per-
     mit'' or ``deny'' and the two source fields.  The destina-
     tion and service fields can be used to provide finer-grained
     access control if desired.

     The algorithm for rule-matching is as follows:

XFree86                   Version 4.5.0                         6

XFWP(1)             UNIX Programmer's Manual              XFWP(1)

          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 con-
     figuration file is specified and it contains at least one
     valid deny or permit rule, then a host that is not expli-
     citly permitted will be denied a connection.

     Site policy configuration checking constitutes a separate
     (and X server only) authorization check on incoming connec-
     tion 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-destination 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

XFree86                   Version 4.5.0                         7

XFWP(1)             UNIX Programmer's Manual              XFWP(1)

     # 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 writ-
     ten 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.

XFree86                   Version 4.5.0                         8

Generated on 2021-12-07 11:07:08 by $MirOS: src/scripts/roff2htm,v 1.103 2021/01/23 20:24:35 tg Exp $ — This product includes material provided by mirabilos.

These manual pages and other documentation are copyrighted by their respective writers; their sources are available at the project’s CVSweb, AnonCVS and other mirrors. The rest is Copyright © 2002–2021 MirBSD.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.