1XFWP(1) General Commands Manual XFWP(1)
2
6 xfwp - X firewall proxy
7
9 xfwp [option ...]
10
12 The command line options that can be specified are:
13 -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 -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 -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 -config file_name
30 Used to specify the configuration the name of the configuration
31 file
32 -pmport port_number
34 Used to override the default port address (4444) for proxy man‐
35 ager connections
36 -verify Used to display the configuration file rule that was actually
38 matched for each service request
39 -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 -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 -max_pm_conns num_connections
60 Used to specify the maximum number of Proxy Manager connec‐
61 tions. The default is 10.
62 -max_pm_conns num_connections
64 Used to specify the maximum number of X server connections.
65 The default is 100.
66
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 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 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 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
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 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
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
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 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 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 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 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
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 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 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 {permit | deny} <src> <src mask> [<dest> <dest mask> [<operator> <ser‐
221 vice>]]
222 permit/deny the keywords ``permit'' or ``deny'' indicate whether the
225 rule will enable or disable access, respectively
226 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 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 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 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 operator always ``eq'' (if the service field is not NULL)
247 service one of the following three strings: ``pm'', ``fp'', or
249 ``cd'', corresponding to proxy manager, xfindproxy, or
250 client data, respectively
251 For the second type of authorization check, the configuration file con‐
253 tains zero or more site policy rules of the following form:
254 {require | disallow} sitepolicy <site_policy>
256 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 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 sitepolicy a required keyword
267 <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
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 The algorithm for rule-matching is as follows:
282 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 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 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 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 The site policy check is performed by xfwp only if the source-destina‐
318 tion rules permit the connection.
319
321 # 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 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
353 Xfwp should check server site policy and security extension before
354 allocating a listen port.
355
357 xfindproxy (1), Proxy Management Protocol spec V1.0, proxymngr(1),
358 Xserver(1)
359
361 Reed Augliere, consulting to X Consortium, Inc.
362X Version 11 xfwp 1.0.1 XFWP(1)