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

XFree86				 Version 4.7.0			       XFWP(1)

NAME | SYNOPSIS | COMMAND LINE OPTIONS | DESCRIPTION | INTEROPERATION WITH IP PACKET-FILTERING ROUTERS | INSTALLATION, SETUP AND TROUBLESHOOTING | PERFORMANCE, LOAD BALANCING AND RESOURCE MANAGEMENT | CONFIGURATION FILE | RULES FOR EVALUATING THE XFWP CONFIGURATION FILE ENTRIES | EXAMPLES | BUGS | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=xfwp&sektion=1&manpath=XFree86+4.7.0>

home | help