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

FreeBSD Manual Pages

  
 
  

home | help
XFWP(1)			    General Commands 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 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  un-
	       successful 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 In-
       tranet 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 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  ac-
       cess to Intranet	X servers by clients originating outside the firewall.
       At the present time, such access	control	is typically achieved by fire-
       wall  configurations  incorporating  IP packet-filtering	routers.  Fre-
       quently,	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  de-
       nied.]  This does not mean the Intranet firewall	will be	opened for in-
       discriminate 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  de-
       scribed	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 us-
       ing 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 em-
       ploying 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 de-
       fault 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  de-
       fault timeouts for the connection types,	is governed by a number	of as-
       sumptions 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 us-
       ing 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 in-
		   terpretation	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  ac-
       tually matched.

BUGS
       Xfwp  should check server site policy and security extension before al-
       locating	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.

X Version 11			  xfwp 1.0.3			       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:
<https://www.freebsd.org/cgi/man.cgi?query=xfwp&sektion=1&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help