man pages section 1: User Commands

Exit Print View

Updated: July 2014

xfwp (1)


xfwp - X firewall proxy


/usr/bin/xfwp [option ...]


User Commands                                             XFWP(1)

     xfwp - X firewall proxy

     /usr/bin/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 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
             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

X Version 11         Last change: xfwp 1.0.2                    1

User Commands                                             XFWP(1)

             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

     -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

X Version 11         Last change: xfwp 1.0.2                    2

User Commands                                             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

     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

     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.

X Version 11         Last change: xfwp 1.0.2                    3

User Commands                                             XFWP(1)

     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.

X Version 11         Last change: xfwp 1.0.2                    4

User Commands                                             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  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 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> <service>]]

     permit/deny the  keywords  ``permit''  or  ``deny'' indicate
                 whether the rule will enable or disable  access,

     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

X Version 11         Last change: xfwp 1.0.2                    5

User Commands                                             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,

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

     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:

X Version 11         Last change: xfwp 1.0.2                    6

User Commands                                             XFWP(1)

          while (more entries to check)
            if ((<originator IP> AND (NOT <src mask>)) == src)
              [if ((<dest X server IP> AND (NOT <dest mask>))  ==
                [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

X Version 11         Last change: xfwp 1.0.2                    7

User Commands                                             XFWP(1)

     # 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

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

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

     Reed Augliere, consulting to X Consortium, Inc.

     See   attributes(5)   for   descriptions  of  the  following

     |      ATTRIBUTE TYPE         |        ATTRIBUTE VALUE         |
     |Availability                 |x11/network/x11-network-proxies |
     |Interface Stability          |Committed                       |

X Version 11         Last change: xfwp 1.0.2                    8