1XFWP(1)                     General Commands Manual                    XFWP(1)
2
3
4

NAME

6       xfwp - X firewall proxy
7

SYNOPSIS

9       xfwp [option ...]
10

COMMAND LINE OPTIONS

12       The command line options that can be specified are:
13
14       -cdt num_secs
15               Used to override the default time-to-close (604800 seconds) for
16               xfwp client data connections on  which  there  is  no  activity
17               (connections  over which X protocol is already being relayed by
18               xfwp)
19
20       -clt num_secs
21               Used to override the default time-to-close (86400 seconds)  for
22               xfwp  client  listen  ports  (ports  on xfwp to which X clients
23               first connect when trying to reach an X server)
24
25       -pdt num_secs
26               Used to override the default time-to-close (3600  seconds)  for
27               Proxy Manager connections on which there is no activity
28
29       -config file_name
30               Used to specify the configuration the name of the configuration
31               file
32
33       -pmport port_number
34               Used to override the default port address (4444) for proxy man‐
35               ager connections
36
37       -verify Used  to  display the configuration file rule that was actually
38               matched for each service request
39
40       -logfile file_name
41               Used to specify the name of  a  file  where  audit  information
42               should  be  logged.   The  format of a logged entry is: time of
43               day; event code; source IP address; destination IP address; and
44               configuration rule number.  The event codes are: "0" for a suc‐
45               cessful connection; "1" if a connection is denied because of  a
46               configuration  rule;  and "2" if a connection is denied because
47               of an authorization failure.  If the event code is "1",  and  a
48               configuration  file  is  used, the configuration rule number is
49               the line number of the configuration file where the  match  was
50               made (see the section CONFIGURATION FILE for more information).
51               If the event code is not "1", or if no  configuration  file  is
52               used, the configuration rule number is "-1".
53
54       -loglevel {0,1}
55               Used  to  specify  the  amount  of  audit detail that should be
56               logged.  If "0", all connections  are  logged.   If  "1",  only
57               unsuccessful connections are logged.
58
59       -max_pm_conns num_connections
60               Used  to  specify  the  maximum number of Proxy Manager connec‐
61               tions.  The default is 10.
62
63       -max_pm_conns num_connections
64               Used to specify the maximum number  of  X  server  connections.
65               The default is 100.
66

DESCRIPTION

68       The  X firewall proxy (xfwp) is an application layer gateway proxy that
69       may be run on a network firewall host to forward X traffic  across  the
70       firewall.  Used in conjunction with the X server Security extension and
71       authorization checking, xfwp constitutes a safe, simple,  and  reliable
72       mechanism  both  to  hide  the  addresses  of  X servers located on the
73       Intranet and to enforce a server connection policy.  Xfwp  cannot  pro‐
74       tect  against mischief originating on the Intranet; however, when prop‐
75       erly configured it can guarantee that only trusted clients  originating
76       on authorized external Internet hosts will be allowed inbound access to
77       local X servers.
78
79       To use xfwp there must be an X proxy manager running in the local envi‐
80       ronment  which  has been configured at start-up to know the location of
81       the xfwp.  [NOTE:  There may be more than one xfwp running in  a  local
82       environment; see notes below on load balancing for further discussion.]
83       Using the xfindproxy utility (which relays  its  requests  through  the
84       proxy  manager) a user asks xfwp to allocate a client listen port for a
85       particular X server, which is internally  associated  with  all  future
86       connection  requests  for that server.  This client listen port address
87       is returned by the proxy manager through xfindproxy.  The xfwp hostname
88       and port number is then passed out-of-band (i.e., via a Web browser) to
89       some remote X client, which will subsequently connect to  xfwp  instead
90       of to the target X server.
91
92       When  an  X  client  connection request appears on one of xfwp's listen
93       ports, xfwp connects to the X server associated with this  listen  port
94       and performs authorization checks against the server as well as against
95       its own configurable access control list for  requesting  clients.   If
96       these  checks  fail,  or if the requested server does not support the X
97       Security Extension, the client connection is refused.   Otherwise,  the
98       connection  is  accepted and all ensuing data between client and server
99       is relayed by xfwp until the client terminates the  connection  or,  in
100       the  case  of  an inactive client, until a configured timeout period is
101       exceeded.  Xfwp is designed to block while waiting for activity on  its
102       connections, thereby minimizing demand for system cycles.
103
104       If  xfwp  is run without a configuration file and thus no sitepolicy is
105       defined, if xfwp is using an X server where xhost +  has  been  run  to
106       turn  off  host-based authorization checks, when a client tries to con‐
107       nect to this X server via xfwp, the X server will deny the  connection.
108       If  xfwp does not define a sitepolicy, host-based authorization must be
109       turned on for clients to connect to an X server via the xfwp.
110

INTEROPERATION WITH IP PACKET-FILTERING ROUTERS

112       The whole purpose of the xfwp  is  to  provide  reliable  control  over
113       access  to  Intranet X servers by clients originating outside the fire‐
114       wall.  At the present time, such access control is  typically  achieved
115       by  firewall  configurations incorporating IP packet-filtering routers.
116       Frequently, the rules for such filters deny access to  X  server  ports
117       (range 6000 - 6xxx) for all Intranet host machines.
118
119       In  order for xfwp to do its job, restrictions on access for ports 6001
120       - 6xxx must be removed from the rule-base of  the  IP  packet-filtering
121       router.   [NOTE:  xfwp  only  assigns ports in the range beginning with
122       6001; access to port 6000 on all Intranet  hosts  may  continue  to  be
123       denied.]   This  does not mean the Intranet firewall will be opened for
124       indiscriminate entry by X clients.  Instead, xfwp supports a fully con‐
125       figurable  rule-based  access control system, similar to that of the IP
126       packet-filter router itself.  Xfwp in  effect  adds  another  level  of
127       packet-filtering  control  which  is  fully  configurable  and  applies
128       specifically to X traffic.  See section  entitled  CONFIGURATION  FILE,
129       below, for further details.
130

INSTALLATION, SETUP AND TROUBLESHOOTING

132       Xfwp  is typically run as a background process on the Intranet firewall
133       host.  It can  be  launched  using  any  of  the  command-line  options
134       described  above.   As noted above, xfwp works only in conjunction with
135       proxy manager and the xfindproxy utility.  It can also be configured to
136       support  a  user-defined  X server site security policy, in which the X
137       server is required to indicate to xfwp whether or not it  supports  the
138       particular policy.  Consult the X server man pages for further informa‐
139       tion on these components.  Xfwp diagnostics can be turned on by compil‐
140       ing  with  the  -DDEBUG  switch.   Connection status can be recorded by
141       using the -logfile and -loglevel command line options.
142

PERFORMANCE, LOAD BALANCING AND RESOURCE MANAGEMENT

144       Xfwp manages four different kinds of connections:  proxy  manager  (PM)
145       data,  X  client  listen,  X  client  data, and X server.  The sysadmin
146       employing xfwp must understand how the resources for each of these con‐
147       nection  types are allocated and reclaimed by xfwp in order to optimize
148       the availability of xfwp service.
149
150       Each connection-type has a default number of  allocation  slots  and  a
151       default timeout.  The number of allocation slots for PM connections and
152       X server connections is configurable via command line options.  Connec‐
153       tion  timeouts  are  also  configurable via command line options.  Each
154       connection timeout represents the period the connection will be allowed
155       to  remain  open  in  the  absence  of any activity on that connection.
156       Whenever there is activity on a connection, the time-to-close is  auto‐
157       matically  reset.  The default distribution of total process connection
158       slots across the four connection  types,  as  well  as  the  choice  of
159       default  timeouts  for the connection types, is governed by a number of
160       assumptions embedded in the xfwp use model.
161
162
163       The default number of PM connections is 10 and the default duration for
164       PM connections is 3,600 seconds (1 hour) for each connection after time
165       of last activity.  At start-up, xfwp listens for PM connection requests
166       on  any non-reserved port (default of 4444 if not specified on the xfwp
167       command-line).  The PM normally connects to xfwp only when  a  call  is
168       made  to  the PM with xfindproxy.  Thereafter, the PM remains connected
169       to xfwp, even after the messaging between them has been completed,  for
170       the  default connection duration period.  In some cases this may result
171       in depletion of available PM connection slots.  If the sysadmin expects
172       connections  to  a  single  xfwp from many PM's, xfwp should be started
173       using the -pdt command line option, with a timeout value reflecting the
174       desired  duration that inactive connections will be permitted to remain
175       open.
176
177       Xfwp client listeners are set up by a call to xfindproxy  and  continue
178       to  listen  for  X client connection requests for a default duration of
179       86,400 seconds (24 hours) from the point of last activity.  After  this
180       time  they are automatically closed and their fd's recovered for future
181       allocation.  In addressing the question of how to choose some  alterna‐
182       tive timeout value which will guarantee the availability of client lis‐
183       ten ports, sysadmins should take into consideration the expected  delay
184       between the time when the listener was allocated (using xfindproxy) and
185       the time when a client actually attempts to connect to  xfwp,  as  well
186       the  likelihood that client listeners will be re-used after the initial
187       client data connection is closed.
188
189       Each client connection is allocated a default lifetime of 604,800  sec‐
190       onds  (7  *  24 hours) from the point when it last saw activity.  After
191       this time it is automatically closed and its fd's recovered for  future
192       allocation.   Because  server  connections are not actually established
193       until a connection request from a remote X client arrives at one of the
194       xfwp's  client  listen  ports,  the client data timeout applies both to
195       client-xfwp connections as well as to xfwp-server connections.  If  the
196       system administrator expects many client data connections through xfwp,
197       an overriding of the default timeout should be considered.
198

CONFIGURATION FILE

200       The xfwp configuration file resides on the xfwp  host  machine  and  is
201       used  to  determine  whether  X client data connection requests will be
202       permitted or denied.  The path to the file  is  specified  at  start-up
203       time.  If no configuration file is specified, all X client data connec‐
204       tion requests routed through xfwp will be by default permitted,  assum‐
205       ing that other X server authorization checks are successful.  If a con‐
206       figuration file is supplied but none of its entries matches the connec‐
207       tion request then the connection is by default denied.
208
209       If  a line in the configuration file begins with the '#' character or a
210       new-line character, the line is ignored and the evaluator will skip the
211       line.
212
213       The  configuration file supports two entirely independent authorization
214       checks:  one which is performed by xfwp itself, and a second  which  is
215       the  result  of  xfwp's querying the target X server.  For the first of
216       these, the configuration file employs a syntax and semantic similar  to
217       that  of IP packet-filtering routers.  It contains zero or more source-
218       destination rules of the following form:
219
220       {permit | deny} <src> <src mask> [<dest> <dest mask> [<operator>  <ser‐
221       vice>]]
222
223
224       permit/deny the  keywords  ``permit''  or ``deny'' indicate whether the
225                   rule will enable or disable access, respectively
226
227       src         the IP address against the host who originated the  connec‐
228                   tion  request  will  be  matched,  expressed  in  IP format
229                   (x.x.x.x)
230
231       src mask    a subnet mask, also in IP format,  for  further  qualifying
232                   the source mask.  Bits set in the mask indicate bits of the
233                   incoming address to be ignored when comparing to the speci‐
234                   fied src
235
236       dest        the  IP address against which the destination of the incom‐
237                   ing connection request (i.e. the host IP of the X server to
238                   which the incoming client is attempting to connect) will be
239                   matched
240
241       dest mask   a subnet mask, also in IP format,  for  further  qualifying
242                   the  destination  mask.  Bits set in the mask indicate bits
243                   of the destination address to be ignored when comparing  to
244                   the specified dest
245
246       operator    always ``eq'' (if the service field is not NULL)
247
248       service     one  of  the  following  three strings:  ``pm'', ``fp'', or
249                   ``cd'', corresponding  to  proxy  manager,  xfindproxy,  or
250                   client data, respectively
251
252       For the second type of authorization check, the configuration file con‐
253       tains zero or more site policy rules of the following form:
254
255       {require | disallow} sitepolicy <site_policy>
256
257
258       require     specifies that the X server  must  be  configured  with  at
259                   least  one of the corresponding site policies, else it must
260                   refuse the connection.
261
262       disallow    specifies that the X server must not be configured with any
263                   of the corresponding site policies, else it must refuse the
264                   connection.
265
266       sitepolicy  a required keyword
267
268       <site_policy>
269                   specifies the policy string.  The string  may  contain  any
270                   combination  of  alphanumeric  characters  subject  only to
271                   interpretation by the target X server
272

RULES FOR EVALUATING THE XFWP CONFIGURATION FILE ENTRIES

274       For the first type of configurable authorization checking,  access  can
275       be  permitted or denied for each connection type based upon source and,
276       optionally, destination and service.  Each file entry must at a minimum
277       specify  the  keyword ``permit'' or ``deny'' and the two source fields.
278       The destination and service fields can be used to provide finer-grained
279       access control if desired.
280
281       The algorithm for rule-matching is as follows:
282
283            while (more entries to check)
284            {
285              if ((<originator IP> AND (NOT <src mask>)) == src)
286                [if ((<dest X server IP> AND (NOT <dest mask>)) == dest)]
287                  [if (service fields present and matching)]
288                    do either permit or deny connection depending on keyword
289              else
290                continue
291            }
292            if (no rule matches)
293              deny connection
294
295       If a permit or deny rule does not specify a service and operation, then
296       the rule applies to all services.  If a configuration file is specified
297       and  it  contains  at  least one valid deny or permit rule, then a host
298       that is not explicitly permitted will be denied a connection.
299
300       Site policy configuration checking constitutes a separate (and X server
301       only)  authorization check on incoming connection requests.  Any number
302       of require or disallow rules may be specified, but all rules must be of
303       the same type; that is, a single rule file cannot have both ``require''
304       and ``disallow'' keywords.  The algorithm for this check is as follows:
305
306            if (X server recognizes any of the site policy strings)
307              if (keyword == require)
308                permit connection
309              else
310                deny connection
311            else
312              if (keyword == require)
313                deny connection
314              else
315                permit connection
316
317       The site policy check is performed by xfwp only if the  source-destina‐
318       tion rules permit the connection.
319

EXAMPLES

321
322       # if and only if server supports one of these policies then authorize
323       # connections, but still subject to applicable rule matches
324       #
325       require sitepolicy policy1
326       require sitepolicy policy2
327       #
328       # deny pm connections originating on 8.7.6.5 [NOTE:  If pm service
329       # is explicitly qualified, line must include destination fields as
330       # shown.]
331       #
332       deny  8.7.6.5  0.0.0.0  0.0.0.0  255.255.255.255  eq  pm
333       #
334       # permit xfindproxy X server connects to anywhere [NOTE:  If
335       # fp service is explicitly qualified, line must include source fields
336       # as shown.]
337       #
338       permit  0.0.0.0  255.255.255.255   0.0.0.0  255.255.255.255  eq  fp
339       #
340       # permit all connection types originating from the 192.0.0.0
341       # IP domain only
342       #
343       permit  192.0.0.0   0.255.255.255
344
345
346       Care  should  be taken that source-destination rules are written in the
347       correct order, as the first matching rule will be applied.  In addition
348       to  parser syntax checking, a special command-line switch (-verify) has
349       been provided to assist the sysadmin  in  determining  which  rule  was
350       actually matched.
351

BUGS

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

SEE ALSO

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

AUTHOR

361       Reed Augliere, consulting to X Consortium, Inc.
362
363
364
365X Version 11                      xfwp 1.0.1                           XFWP(1)
Impressum