Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
XFWP(1)                 FreeBSD General Commands Manual                XFWP(1)

       xfwp - X firewall proxy

       xfwp [option ...]

       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

       -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

       -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
               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".

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

       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.

       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.

       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.

       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

       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.

       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

       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>

       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

       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

       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, respectively

       For the second type of authorization check, the configuration 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 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

       sitepolicy  a required keyword

                   specifies the policy string.  The string may contain any
                   combination of alphanumeric characters subject only to
                   interpretation by the target X server

       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
            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
                deny connection
              if (keyword == require)
                deny connection
                permit connection

       The site policy check is performed by xfwp only if the source-
       destination rules permit the connection.

       # 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 [NOTE:  If pm service
       # is explicitly qualified, line must include destination fields as
       # shown.]
       deny  eq  pm
       # permit xfindproxy X server connects to anywhere [NOTE:  If
       # fp service is explicitly qualified, line must include source fields
       # as shown.]
       permit  eq  fp
       # permit all connection types originating from the
       # IP domain only

       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.

       Xfwp should check server site policy and security extension before
       allocating a listen port.

       xfindproxy (1), Proxy Management Protocol spec V1.0, proxymngr(1),

       Reed Augliere, consulting to X Consortium, Inc.

XFree86                          Version 4.7.0                         XFWP(1)


Want to link to this manual page? Use this URL:

home | help