xfwp



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.



                                                                       XFWP(1)

Man(1) output converted with man2html