1 /*_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/
5 * Function:..A description of the basic of TWEB, *
6 * the Tuebinger Web-X.500 gateway *
9 * Authors:...Dr. Kurt Spanier & Bernhard Winkler, *
10 * Zentrum fuer Datenverarbeitung, Bereich Entwicklung *
11 * neuer Dienste, Universitaet Tuebingen, GERMANY *
14 * Creation date: Z D D V V *
15 * September 14 1995 Z D D V V *
16 * Last modification: Z D D V V *
17 * January 15 1999 ZZZZ DDD V *
19 _/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/_/*/
27 2.1 A case of Public Relations
28 2.2 Configuration files and TWEB start-up
29 2.3 The running gateway
30 2.4 check4access: who is allowed to see (what) data
31 2.5 Preparing the data
32 2.6 Searching for data
33 2.7 Data based behaviour: the dynamic gateway
34 2.8 Restricting the service
35 2.8.1 Restricting the number of entries
36 2.8.2 Suppression of certain entries by RDN
37 2.8.3 Defining DIT areas for search-only operations
38 2.8.4 Controlling the hackers
39 3 Configuration of TWEB features in detail
40 3.1 Technical configuration options
41 3.2 Political configuration options
42 3.3 Load balancing configuration options
43 3.4 Display configuration options
44 4 Support and discussion list
49 TWEB is based on the Web500gw implementation by Frank Richter,
50 Technische Universitaet Chemnitz-Zwickau, which is based on the
51 go500gw implementation by Tim Howes, University of Michigan.
53 TWEB was compiled and tested on LINUX with cc, HPUX 9.05 with the
54 HP-ANSI C compiler, as well as SunOS 4.1.2 with the SUN C compiler.
55 TWEB was also compiled with gcc on all platforms. On SUN Solaris
56 2.6.x TWEB was also compiled with gcc 2.7.2.
58 The UMICH LDAP client library version 3.0 or 3.3
59 ( URL:ftp://terminator.rs.itd.umich.edu/ldap/ldap-3.3.tar.Z )
60 must be installed on the machine (library path and include file
61 path is configured in Makefile). With QUIPU ICR-2.x the ISODE-
62 provided LDAP libraries should be used. As such, TWEB only supports
63 LDAP version 2 with the University of Michigan type C API. TWEB is
64 also adapted for the OpenLDAP LDAP library, release version 1.1.2
65 (http://www.openldap.org).
67 An upgrade to LDAP version 3 and a C API standadized by the IETF
68 is planned for a not so far away future, most probably in step
69 with the OpenLDAP package.
71 TWEB, as provided here is a fully functional core gateway, which
72 is extended at the author's site by some local features. These
73 extensions are included into the same code base, so that some
74 "#ifdef TUE_TEL" or "#ifdef AMBIX" pre-processor statements can
75 be found throughout the code.
80 2.1 A case of Public Relations
82 TWEB is a gateway between the HTML-based World-Wide-Web (WWW
83 for short) and the X.500-based wordlwide directory, nowadays
84 mainly accessed through LDAP, the Leightweight Directory Access
85 Protocoll. As such, TWEB is a mediator between these worlds,
86 providing run-time access to a lively database and preparing
87 results in a usable format.
89 Why not access the directory directly via my browser-built-in
90 LDAP functionality, you may ask. One answer is, that TWEB with
91 it's build-in security features may provide access to more
92 internal data for permitted users, while denying these data for
93 outside users. This might be very handy from the database
94 administration point of view, easing the task of checking
95 for consistencies between seperate inside and outside databases.
97 Secondly, TWEB provides for a flexible display of results,
98 not just showing the pure data. Corporate identity, even when
99 using a staff's directory, can be implemented by an organization.
100 Furtheron, important messages and hints can be added on the fly,
101 that are relevant to the directory user. This is also possible
102 via HTTP links, provided either through the directory data (e.g.,
103 links to personal home pages) or embeded into HTML text loaded
104 during result page preparation. Thus, the integration of WWW and
105 the directory can be two-ways, not just one-way.
107 Thirdly, TWEB can, with some extensions not yet provided in
108 the current distribution, easily be configured to access the
109 directory more than once, in order to return results for a
110 single request. For example, this can be used to build a page
111 with the phoenbook entries of a whole department, institute, or
112 faculty, spanning many hierarchies is the underlying directory
113 database, as implemented at the University of Tuebingen.
115 When running TWEB with some of the configuration options, one
116 might easily find more points that are in favor of a gateway
117 solution, rather than purely accessing the data of a single
118 directory entry at a time.
120 BUT AFTER THIS SHORT EXCURSION INTO THE WORLD OF PR, LET'S
121 HAVE A LOOK AT WHAT TWEB PROVIDES AND WHAT FEATURES CAN
125 2.2 Configuration files and TWEB start-up
127 Allmost anything what TWEB provides is determined by a set of
128 configuration files during start-up, or at run-time. There is
129 the main ressource file (tweb.rc) that provides for basic,
130 language-independant features, like host and port of the connected
131 directory server. Language-specific configuration parameters
132 are located in the config files (tweb.conf.x), with x (0-9)
133 standing for any of a set of supported languages. Language
134 strings, that are used to build an HTML result page are taken
135 from the language files (tweb.lang.x), again with x indicating
136 the language in question. Those files are located in the
137 TWEB_conFiles subdirectory; the TWEB binary, probably via a
138 symbolic link, should also reside within that directory.
140 Header and footer files, and certain message files are loaded
141 during run-time, so that the content can be updated on-the-fly,
142 without restarting the gateway. Those files can be found in the
143 LDAP_etc subdirectory, but can also be located elsewhere, after
144 setting the ETCDIR parameter in the tweb.rc file.
146 Certain configuration parameters can be overridden by command
147 line parameters during start-up. Type 'tweb -h' to get a short
148 description of each command line parameter, or have a look at
149 the description below. The important parameters are '-l' for
150 selection of the LOCAL user of the syslog facility, and '-L'
151 for selection of languages.
153 When starting, TWEB first of all determines which languages should
154 be supported. A sub-process is created for each language by the
155 fork() system call, and the starting process is terminated. (In case
156 of only one language, TWEB will not fork, but instead use the first
157 process for the gateway service.) Each sub-process is responsible for
158 one of the languages, and presents hyperlinks to the other languages'
159 HTTP addresses on HTML pages, so that the user can switch from one
160 language to the other. When language hints are provided within the
161 directory data (see below) even attribute values may be presented
162 language-specific. (This is not to be mixed up with the LDAPv3
163 standard, which provides for language specification via attribute
166 The starting TWEB initializes itself by reading the tweb.rc, the
167 tweb.conf.x, and the tweb.lang.x files, and stores the configuration
168 in a global data structure that can be used by all parts of the
169 program. Command line options are considered last, and can override
170 previously defined parameters. In the tweb.rc and tweb.conf.x files
171 parameters are generally additive, meaning that configuration can be
172 spread across those files (e.g., GW-SWITCH can be set to language-
173 independant gateways in tweb.rc and extended by language-specific
174 gateways in the tweb.conf.x files.)
176 Also, message, header and footer files are checked for presence, and
177 a warning is printed to standard output, if they are missing. After
178 some more sanity checks of the configuration, TWEB connects to the
179 port it was configured for and starts listening for HTTP requests.
180 (In the tweb.rc config file only a base port is given; the gateway
181 process serving for language 0 will listen at this port; the gateway
182 for language 1 at port+1, for language 2 at port+2, and so on, upto
183 the language with number 9.)
186 2.3 The running gateway
188 When a request is started by an external HTTP client, TWEB checks
189 for access rights of that client (see below), and decides, whether
190 the request can be handled by the process itself (mainly simple
191 requests, like, e.g., sending the help file), or whether another
192 sub-process should be started. In both cases the TWEB master process
193 returns to listening for requests, so that new request can be
194 handled while old ones are still in progress.
196 A request is encoded into the URL, the Universial Ressource Locater,
197 the HTTP client sends to the gateway process. Such an URL is build
198 of different parts, as follows:
200 http://host:port/request
202 First of all, 'http://' defines the HTTP protocoll itself. As
203 TWEB is the mediator between WWW and the directory, it is an HTTP
204 server towards the browser, accepting normal HTTP request, but is an
205 LDAP client towards the directory server, sending LDAP requests.
207 Host and port are the same as in the tweb.rc configuration file,
208 and tell the browser, where to direct the request.
210 The request for TWEB is given in the last part of the URL, in a more
211 or less complicated format. The most simple request is the EMPTY
212 request ( http://host:port/ ), which will cause TWEB to return a
213 listing of directory entries just below it's BASEDN. (Besides beeing
214 the "home" for TWEB when sending an URL without further specification,
215 the BASEDN can also be configured as beeing the root entry of an DIT
216 area, and TWEB will only serve requests within, but not outside that
217 area; STRICT-BASEDN.)
219 All other requests are given by a starting letter (beware: that
220 letter is CASE-SENSITIVE) and possibly a further specification.
221 That letter directs TWEB to one of several actions, like returning
222 a directory listing, reading a specified entry, or sending a
223 formular for modification of an entry. If a directory look-up
224 is necessary, TWEB will perform that via LDAP, prepare the results
225 as an HTML page, and return it to the requesting client. After
226 that the process will die, unless it was the master process, that
227 returns to listening for further requests. Thus, TWEB's action is
228 as state-less as the HTTP protocoll itself, but some information
229 for subsequent client requests can be embedded into the result,
230 like for example a gateway-switch (see below) or an entries' old
231 data in a modification formular.
233 Like in HTTP, the TWEB request URL should contain no space characters,
234 and certain special chars should be HTML escaped. TWEB will allways
235 prepare such URLs in its own results, e.g., when returning a list of
236 entries, with each one beeing a clickable hyperlink for the next data
237 retrieval. Thus, during interaction with TWEB, the user has not to
238 consider such special characters, for they are converted automatically.
239 Only the very first link to TWEB, be it embedded into a web page, or
240 entered directly into the browser's 'goto URL' field, or whatever it is
241 called, should be checked for those characters.
244 2.4 check4access: who is allowed to see (what) data
246 A requesting client not only gives the URL to TWEB, but also it's
247 IP or Internet address. This is an address needed by computers to
248 find each other in the world-wide network. Normally, computers
249 have also so-called Internet Names, that are more human-readable.
250 To match IP addresses and internet names, the Domain Name Service
251 (DNS) is run on the Internet. When TWEB receives an IP adress,
252 it will try to look up the corresponding internet name of the
253 requesting client and use that information to decide on access
254 rights of the client. If a host's name cannot be found in the
255 DNS, this is also used as a bit of information. The configuration
256 parameters GRANT, REFUSE, ALLOW-STRING, and DENY-STRING can be
257 set to specify access rights based on internet names in a very
258 flexible way. Furtheron, the HTTP information of proxy access
259 is considered, if the parameters NO-PROXY and ALLOW-PROXY are set.
261 When TWEB has decided on access rights, it will continue depending
262 on these rights. When service is totally refused to a requesting
263 host, or a complete IP domain, a corresponding message is send to
264 the client and the TWEB process terminates. Otherwise, TWEB selects
265 one of two configured WEBDNs (the directory names of corresponding
266 entries in the local directory) and WEBPWs (corresponding passwords)
267 and sends the LDAP requests with these DNs to the directory server.
268 The server should of course be configured in a way, that the one DN
269 has access to internal data, whereas the other has not. Thus, data
270 retrieval can be controlled by the server, not only by TWEB itself.
273 2.5 Preparing the data
275 Almost any result page is build by combining different areas, as
276 appropriate for the result returned. A header and footer is located
277 at the top and the bottom of the HTML page, respectively. (In fact,
278 the footer is followed by a tiny TWEB version info, so the footer
279 is only the second-last element.) Below the header some internal
280 message can follow (ALLOW-MESSAGE), which will not be shown to an
281 outside requestor, and in front of the footer there can be a Legal
282 Message for the outsider (LEGAL; actually, if the ON-TOP parameter
283 is specified for the LEGAL option, this Legal Message will also be
284 printed at the beginning of the result page). Below the header/
285 internal message, an area for navigation, reading the current base
286 position and a search box may follow, that can be used for entering
287 further requests. Below that, the results of the current request
290 If there are more than one result entries to the current request (e.g.,
291 due to a listing of entries below the current DIT position, or multiple
292 matches for a search request), a hyperlink for each entry is displayed,
293 to give the user the possibility to follow the link and obtain the
294 results for the next request. The HREF within the hyperlink is a
295 complete URL, with host:port, and the directory entries' distinguished
296 name (DN) for the next request to TWEB.
298 Results can be grouped to different lists and sorted within each
299 group, according to the settings of the SORT configuration parameter,
300 and the entries' objectclasses. The objectclasses given in the SORT
301 configuration parameter are scanned for in each result entry,
302 sequentially, and an entry is placed into the appropriate group, as
303 soon as an objectclass is found. (Entries having none of the SORT
304 objectclasses will only be shown, if the SHOW-DEFOC configuration
305 parameter as well as a DEFAULT DISPLAY-TYPE is given.) After scanning
306 for groups, each group of entries is sorted according to the contents
307 of the sort attribute listed within the group's SORT clause, or by the
308 attribute "sn" (surname), if no explicite sort attribute is given, or
309 according to the entries' relative distinguished name, if there is no
310 sn attribute within the entries. The sorted groups are displayed in
311 the order, that is given numerically in the SORT clauses. Thus, the
312 order while scanning for objectclasses (i.e., preparing the groups)
313 is distinct from the order during display. Each group is prepanded
314 by the label given in the SORT clause, with a label consisting only
315 of space characters meaning no label. (Labels containing space
316 characters must be surrounded by double quote characters, i.e., '"'.)
318 If there is only one result to a request, TWEB will perform a read
319 request for the X.500 entry and display the attributes of the entry.
320 Since access rights are also checked at the server (see above), the
321 attribute list for a permitted user can differ from the list of an
322 external user. In each case, the attributes are sorted according to
323 the DISPLAY-OBJECT given in the SORT configuration parameter, after
324 classification of the entry to one of the SORT groups in much the
325 same way, as described above. The DISPLAY-OBJECT selects the attributes
326 to be displayed and determines the order of, as well as labels for
327 the attributes. (If the DISPLAY-OBJECT parameter is not given to the
328 SORT configuration option, DISPLAY-OBJECT DEFAULT will be used; if
329 that, however, is not given by the configuration files, the entry
330 will NOT be displayed!) The method for displaying is also given. Thus,
331 attributes can be displayed as simple strings, prepared as HTTP URLs,
332 or as mailto hyperlinks. A complete list of display methods is given
333 below with the description of the FIRST-PAGE configuration parameter.
334 Within the DISPLAY-OBJECT definition, FIRST-PAGE describes attributes
335 to be shown on a first HTML page, and SECOND-PAGE lists attributes
336 for a second HTML page, if given. To obtain the second page, a hyper-
337 link that directs TWEB to read the same entry again with additional
338 attributes, is placed at the end of the first page's attribute list.
341 2.6 Searching for data
343 As described above, one element of a result page may be a search box
344 that can be used to enter appropriate search strings. The input is
345 taken by TWEB and used according to the definitions of the
346 ldapfilter.conf file (a basic version is located in the LDAP_etc
347 sub directory.) In that file, rather complicated search algorithms
348 can be defined, but the most simple ones will be to look for cn or
349 sn attributes. By default, the search scope is restricted to one
350 level below the current DIT position, unless the base entry (the
351 current position) containes objectclasses 'organization' or
352 'organizationalUnit'. In this case, the search will cover the whole
353 DIT area rooted at the current position. (Subtree search.) This
354 scope also determines which search rules are taken from the
355 ldapfilter.conf file. (Look for "web500gw onelevel" and "web500gw
358 One word for a warning: since TWEB is currently based on LDAPv2 and
359 servers that are NOT aware of special characters, like german umlaute,
360 such characters should NOT be entered to the search box. Depending
361 on the server's implementation and configuration, these characters
362 might crash the server, since they are not one of the expected ASCII
363 characters. TWEB, on the other hand, can hardly figure out the
364 character entered because of differrent code tables in use with
365 the browsers and the platforms housing TWEB itself. If someone has
366 a simple sollution to the latter problem, the authers would welcome
367 a hint, so they could implement a safe character conversion method.
370 2.7 Data based behaviour: the dynamic gateway
372 In the 'preparing data' section, the construction of hyperlinks for
373 further requests was described for situations, when more than one
374 entry matches the previous request. For these hyperlinks, the under-
375 lying URL will normally contain the TWEB's own host and port address,
376 so that requests will be directed towards the same gateway. This,
377 however, can be modified by a feature called "gateway-switching",
378 directing further requests to other gateways.
380 Gateway-switching exists in two flavors: static (via the GW-SWITCH
381 configuration option) and dynamic (selected by the configuration
382 option DYNAMIC-GW) due to data contents. In both cases, a new host
383 and corresponding port address is inserted into the URL of a hyperlink.
385 Static gateway-switching is performed, if a DN given in the configu-
386 ration file, or an entry below that DN, is referred to in the hyperlink.
387 In that case, the beginning of the URL is taken from the configuration
388 file and the DN of the referred-to X.500 entry is appended. Like other
389 configuration options, GW-SWITCH in the tweb.rc file will refer to one
390 such external gateway for all TWEB languages, whereas GW-SWITCH in the
391 tweb.conf.x files will be language-specific.
393 When the configuration option DYNAMIC-GW is given, TWEB will scan each
394 entry to be referred to, for the presence of a so-called gateway-
395 switch-URL. For the time beeing, this is encoded in the attribute
396 "labeledURI", with the value having a special syntax. Normal syntax
397 is an URL of the from "http://host/ label". With the gateway-switching
398 option, this format is extended to "http://host:port/ label (gw)",
399 for a language-independant switch, and "http://host:port/ label (gw-xx)",
400 for a languager-specific switch. The "xx" has to be replaced by the
401 international 2-letter language tag, as defined in ISO 639, "Code for
402 the representation of names of languages" (see also RFC-1766). Thus,
403 "gw-de" means "german language", "gw-en" means "english", "gw-fr"
404 means "frensh". When displaying the contents of a labeledURI attribute,
405 TWEB will suppress values that follow the above syntax. For performance
406 reasons, searching of entries, as well as listing entries below the
407 current position (i.e., browsing through the directory), will allways
408 include look-up of the labeledURI and other attributes.
410 If both static and dynamic gateway-switching are active, the dynamic
411 switch will be considerred first; if no gateway-switch URL, first testing
412 for a language-specific one, than testing for an independant one, is
413 found within an entry, static switching is tested, again the specific
414 case prior to the un-specific.
416 The most prominent usage of the gateway-switching feature is to direct
417 requests for other organizations' data within a country (or for sub-
418 organizations within one organization) to specific gateways, thus
419 giving the option to implement a Corporate Identity for each organi-
420 zation via organization-specific header and footer files. Beside that,
421 of course, specific access policies can be implemented by each orga-
422 nization, and network traffic is reduced by accessing an organization's
423 data directly with a HTTP browser, not via an intermittant gateway
424 and X.500 server of another organization. This latter point may also
425 mean a much reduced response time, when unnecessary data transfers are
429 2.8 Restricting the service
431 A number of configuration options can be used to restrict the display
432 of certain information, or to deny service totally for certain users.
433 These options are described in the following sub-chapters.
435 2.8.1 Restricting the number of entries
437 Normally, an X.500 server will have an option "sizelimit" set to
438 some small or medium value, e.g., 100 or 500. This sizelimit will
439 prevent the number of entries returned for any one request, to
440 exceed that number. This is mainly set by the server's administrator
441 to reduce system and network load.
443 When displaying all entries returned from the server, TWEB might
444 produce a very large HTML file. That file may take some time for
445 transfer, and may be very un-handy, because of the long list of
448 To prevent the possibiloty of such large files, the TWEB administrator
449 can reduce the number of entries displayed even further, by use of
450 the MAXCOUNT configuration option. This will reduce the number of
451 ALL entries returned from the server.
453 If this restriction should only apply to person's entries, the
454 configuration option MAX-PERSON can be used. This option will
455 apply to each sub list of person's entries seperately. Thus, the
456 total number of persons may exceed the MAX-PERSON limit, if more
457 sub lists containing person's entries are given.
459 Each restriction of the number of entries to be displayed, will
460 lead to a random list of entries, cutting the results as soon as
461 the maximum count is reached. However, rhis is also true for the
462 sizelimit option at the server itself.
464 2.8.2 Suppression of certain entries by RDN
466 The server's access control rules will normally define, which entries
467 can be obtained by the TWEB gateway. In some situations, the TWEB
468 administrator might want to suppress even more entries, e.g., DSA
469 entries or other mere technical ones. (This can also mean, that
470 complete DIT areas could be hided from the user.)
472 To invoke that, the configuration option NO-SHOW-RDN can be defined
473 to reflect a space-seperated collection of RDNs, or parts of RDNs,
474 which will not be shown to the user. This, of course, is a very
475 crude method, but normally will give the results, the TWEB admin
476 may be interested in.
478 2.8.3 Defining DIT areas for search-only operations
480 As described allready in the "Restricting the number of entries"
481 section, large lists of entries may be cumbersome to read, if at
482 all they are returned completely by the server. To exclude the
483 possibility of such partial, or ultra-long lists, TWEB can be
484 configured to display the search box only at certain DIT positions.
485 This is done via the SEARCH-ONLY configuration option, which defines
486 the DIT area(s) for this restriction, as well as certain message
487 files, which should explain the local restriction to the user, and
488 tell him, how to find the information, he is looking for. The
489 SEARCH-ONLY configuration option will only take effect, when
490 browsing the directory, but not prevent a normal subtree search.
492 This configuration option, of course, can also be used to implement
493 certain access policies. The option will be active for both the
494 internal and the external user.
496 2.8.4 Controlling the hackers
498 From time to time, users will direct tools to the world-wide-web,
499 that will screen through all, what is supplied in the system. This
500 tools are known as robots, or crawles, and normally the collect data
501 to build indices for faster information retrieval.
503 Sometimes, however, these tools can be very ugly, especially, when
504 they try to collect data as fast as possible. This might cause
505 severe performance decrease, preventing other users to get data
506 at all. In order to have some mechanisms against this type of
507 data harvest, TWEB can be configured with the COMREFUSE option
508 activated, which will control the number of accesses to the gate-
509 way by a certain number of IP ranges within a selected time-slice.
511 Those IP ranges are constructed by reducing the requesting host's
512 32-bit Internet address to a 13-bit number, thus giving 8192
513 different IP ranges. Each IP range is controlled seperately during
514 a pre-set time-slice, and each IP range can be excluded from
515 further service (returning an appropriate error message), when
516 a pre-set number of accesses is reached within that time-slice.
517 All hosts of that IP range are suspended from TWEB's service for
518 a number of time-slices, and resumed for service afterwards.
521 3 Configuration of TWEB features in detail
523 Runtime configuration is provided by the files tweb.rc (general
524 configuration) and tweb.conf.x (language-specific configuration).
525 For each supported language there must be a tweb.conf.x and
526 tweb.lang.x file, with 0 <= x <= 9.
528 Remark: most of the features are best configured in the files as given
529 below, but there may be situations, where transfer, or even
530 splitting to other configuration files could be used, e.g.,
531 static gateway-switching may be configured in tweb.rc listing
532 organizations which support only one gateway, whereas organi-
533 zations supporting different language-specific gateways may be
534 configured in the appropriate tweb.conf.x files; the resulting
535 gw-switch list will contain all organizations, regardless of the
538 In order to keep off WWW robots from blocking the gateway put
539 a file with name robots.txt into the directory, together with
540 the tweb binary, containing the following:
546 This is the same behaviour as if there were a www-server with a
547 corresponding public directory containing the file robots.txt.
550 The following sections will list TWEB's configuration options.
551 (See also the example configuration files.)
554 3.1 Technical configuration options
556 This section lists options, which define the technical parameters of
557 TWEB's operation. Most of them are located in the tweb.rc configuration
558 file, but some could also go into the tweb.conf.x files.
560 LDAPD -- The host running the LDAP daemon
561 ( usually located in tweb.rc )
563 example: LDAPD x500.zdv.uni-tuebingen.de
565 LDAPPORT -- The port the LDAP daemon is listening on
566 ( usually located in tweb.rc )
568 example: LDAPPORT 389
570 WEBPORT -- The base port the gateway is attached to
571 (the language-specific offset x is added
572 to this number for every running GW)
573 ( usually located in tweb.rc )
575 example: WEBPORT 7000
577 TIMEOUT -- Timeout in seconds for any one LDAP
579 ( usually located in tweb.rc )
583 ETCDIR -- The directory containing support files
584 (help files, header/footer files ...)
585 ( usually located in tweb.rc )
587 example: ETCDIR ./LDAP_etc/
589 FILTERFILE -- The LDAP filterfile
590 ( usually located in tweb.rc )
592 example: FILTERFILE ldapfilter.conf
594 BASEDN -- The default starting point of DIB access, when
595 no other directory position is given
596 At this position, optional header and footer
597 information (HTML code in file) can be displayed
598 ( usually located in tweb.conf.x )
600 example: BASEDN "o=Universitaet Tuebingen, c=DE"
601 tweb-base.head.0 tweb-base.foot.0
603 HELPFILE -- Name and path of the help-file
604 ( usually located in tweb.conf.x )
606 example: HELPFILE tweb.help.0
608 FRIENDLYFILE -- Name and path of the friendly-file
609 ( usually located in tweb.conf.x )
611 example: FRIENDLYFILE ldapfriendly.0
613 HEADER/FOOTER -- General header/footer information displayed on
614 every HTML-page, except when other headers/footers
616 ( usually located in tweb.conf.x )
618 example: HEADER tweb.header.0
621 ALLOW-MSG -- Option to specify a special file located in the
622 ETCDIRectory containing a message to be displayed
623 in case of an allowed access to TWEB
625 ( usually located in tweb.conf )
627 example: ALLOW-MSG allow.msg.0
630 3.2 Political configuration options
632 This section lists options to implement a certain access policy with the
633 TWEB web-X.500 gateway, or to alter the behaviour of the gateway when
634 displaying data from certain DIT areas.
636 WEBDN -- The DN of a technical webgw X.500 entry,
637 which is used for a permitted (internal) user
638 (for logging AND access control)
639 ( usually located in tweb.rc )
641 example: WEBDN "cn=TWEB-quickie-intern,
642 ou=SERVICES, o=Universitaet
645 WEBPW -- The Password in the WEBDN entry
646 ( usually located in tweb.rc )
648 example: WEBPW password4quickie-intern
650 WEBDN2* -- The DN of a technical webgw X.500 entry,
651 which is used for a not-permitted (external) user
652 (for logging AND access control)
653 ( usually located in tweb.rc )
655 example: WEBDN2 cn=TWEB-quickie-extern,
656 ou=SERVICES, o=Universitaet
659 WEBPW2* -- The Password in the WEBDN2 entry
660 ( usually located in tweb.rc )
662 example: WEBPW2 password4quickie-extern
664 * setting WEBDN2 as well as WEBPW2 to real values is useful,
665 if the X.500 service in the background is also used by other
666 directory user agents; in this case, a clean distinction,
667 even on the ACL level, can be made between TWEB and those
669 To fully exploit the feature of two different WEBDNs the
670 DSA must support an ACL policy, which can reduce access
671 rights for a specified DN, while at the same time defining
672 broader access rights for a group of other DN, which may
673 also include the specific DN; such a behaviour is NOT
674 implemented in Isode's QUIPU 2.x DSA; a patch introducing
675 such a policy was developped at the University of Tuebingen
676 for QUIPU 2.2v4, and can be optained seperately.
677 Slapd stand-alone LDAP servers implement a different ACL
678 mechanism and can be configured more easily by use of the
679 first matching access-rule in the slapd.conf configuration file
681 GRANT** -- A string describing IP domains allowed to access
683 ( usually located in tweb.rc )
685 example: GRANT (www9|mog|x500server|meal)
686 \.zdv\.uni-tuebingen\.de$|
687 (abcde01|xyz)\.modem\.org\.de$
689 REFUSE** -- A string describing IP domains refused to access
691 ( usually located in tweb.rc )
693 example: REFUSE hackhost\.(org1\.)?uni-xyz\.de$
695 ALLOW-STRING** -- A string describing IP domains allowed to
696 access the DIB authorized by WEBDN (see above)
697 example: "\.de$|\.us$|\.edu$"
698 ==> host of domains de, us and edu will
699 have authorized access to the DSA, others NOT
700 ( usually located in tweb.rc )
702 example: ALLOW-STRING uni-tuebingen\.de$
704 DENY-STRING** -- The opposite of ALLOW-STRING. Here, access for
705 subsets of the ALLOW-STRING may be reduced.
706 ( usually located in tweb.rc )
708 example: DENY-STRING not\.secure\.host
711 ** GRANT/REFUSE are considered first to decide, whether the
712 requesting host will be served at all; only hosts granted
713 the service will be checked against ALLOW-STRING/DENY-STRING
714 to classify as internal or external user (hence, giving
715 WEBDN or WEBDN2 as the DN during X.500 look-up);
716 both, GRANT and ALLOW-STRING are used as positive-lists,
717 whereas REFUSE and DENY-STRING are used as negative-lists;
718 if the positive-lists are defined, and the requesting host's
719 IP domain is NOT covered by the list's description, the
720 host is considered as not-permitted; only when the host
721 is accepted by the positive-list, the negative-list will
722 be considered to decide on a more specific exclusion of
723 the host's IP domain;
724 if the positive-lists are not defined, each host will be
725 accepted, as if contained within the list; if the negative-
726 lists are not defined, each host will be accepted, as if
727 NOT contained within the list;
728 hosts NOT found in the Domain Name Service (DNS) will be
729 granted access, but will NEVER have authorized access
732 TWEBHOST -- Supplies a constant hostname in the returned URL
733 of HTTP links independant from the local one
734 ( usually located in tweb.rc )
736 example: TWEBHOST x500.zdv.uni-tuebingen.de
738 NO-PROXY -- Access restrictions for WWW-PROXY-Servers
739 ( usually located in tweb.rc )
743 ALLOW-PROXY -- if NO-PROXY is configured
744 access from a given set of proxy-hosts
745 ('host1:host2') is allowed
746 ( usually located in tweb.rc )
748 example: ALLOW-PROXY www1.zdv.uni-tuebingen.de:
749 www2.zdv.uni-tuebingen.de
751 COMREFUSE -- If configured, implements an interrupt-driven
752 time-slicing of the gateway. During these
753 slices only a maximum number of accesses
754 from a given group of IP-addresses is permitted;
755 additional accesses will lead to immediate
756 suspension of the IP connection to the WWW
757 client; this suspension will last for a con-
758 figured number of time-slices, and service
759 for the IP domain in question will resume
760 afterwards. Additionally, access statistics will
761 be dumped to a file at given intervals;
762 the duration of a time-slice will be computed
763 randomly between a minimum and maximum;
764 all times are given in seconds
765 ( usually located in tweb.rc )
767 example: COMREFUSE 100 200 40 12 43200
770 i.e.: minimum timeslice -> 100 secs
771 maximum timeslice -> 200 secs
772 number of accesses to tolerate in slice -> 40
773 how long will be blocked -> 12 slices
774 period to write a stat-file -> 43200 secs
775 name of stat-file -> ./stats/hack-stats
776 (i.e., file relative to TWEB binary)
778 STRICT-BASEDN -- Access to entries not below basedn is relayed
779 to another gateway ( -> GW-SWITCH must be set)
780 ( usually located in tweb.rc )
782 example: STRICT-BASEDN
784 MAXCOUNT -- The maximum number of displayed entries
785 ( usually located in tweb.rc )
787 example: MAXCOUNT 200
789 MAX-PERSON -- Maximum number of persons displayed in any of
790 the configured sub-lists ( -> SORT option),
791 if access is not allowed;
792 if STRICT is given, this number of persons is
793 shown at maximum, even in case of an
795 if NO-BROWSE is given, only non-person entries
796 will be displayed while browsing, whereas persons
797 have to be searched for
798 ( usually located in tweb.rc )
800 example: MAX-PERSON 5 STRICT NO-BROWSE
802 NO-SHOW-RDN -- Matching rules for RDNs that will NOT be displayed
803 (e.g., technical entries in the DIT or internal
804 OUs not to be displayed by the GW)
805 words surrounded by spaces will be matched as
806 substrings; allignment to the start or end of
807 the tested RDN can be enforced by surrounding
808 the words with "|", on either side
809 ( usually located in tweb.rc )
811 example: NO-SHOW-RDN "|cn=Dummy notToBeShownRDN"
813 SEARCH-ONLY -- Defines the root of a DIT area, where browsing
814 is restricted to non-person entries; person
815 entries can only be found by explicite searching
816 (with appropriate header and footer information)
817 ( usually located in tweb.conf )
819 example: SEARCH-ONLY "ou=students, o=my-university,
820 c=my" search-only.head.0
823 LEGAL -- Flag for displaying of a comment concerning
825 (the text is configured in the tweb.lang.x files,
826 string numbered 65 of the gateway)
827 (Comment: certainly, it would be better to have
828 that text in an external file)
829 Sub-option ON-TOP directs TWEB to display the
830 message immediately below the HEADER information,
831 not above the FOOTER message
832 ( usually located in tweb.rc )
834 example: LEGAL ON-TOP
836 CACHE-EXPIRE-DEFAULT -- The default value for the expire time
837 in seconds. After this time the page is no
838 longer cached by a browser or WWW cache.
839 ( usually located in tweb.rc )
841 example: CACHE-EXPIRE-DEFAULT 900
843 CACHING-TERMS -- A more detailed description of caching directives.
845 <expire-time> READ|MENU|L2ND RDN|OC <value>
848 To specify for a given access-type:
849 READ|MENU|L2ND (L2ND = second page) the expire-time
850 in seconds for given RDN|OC values
851 ( usually located in tweb.rc )
853 BEWARE: THIS OPTION IS NOT USED AT THE AUTHOR'S
854 SITE, ROUTINELY. THUS, CORRECT BEHAVIOUR
855 CANNOT BE GARANTEED !
857 example: CACHING-TERMS 3600 READ RDN Fax
859 10800 menu RDN Mueller
861 MODIFY/MODATTR -- Selects for specified object-class (MODIFY) the
862 attributes permitted for modification, their
863 labels and the maximum number of values to be
864 handled by TWEB (MODATTR)
865 ( usually located in tweb.conf )
867 BEWARE: THIS OPTION IS NOT USED AT THE AUTHOR'S
868 SITE, ROUTINELY. THUS, CORRECT BEHAVIOUR
869 CANNOT BE GARANTEED !
871 example: MODIFY person
872 MODATTR personalTitle title 1
873 telephoneNumber phone 2
876 NO-MODIFY -- Entries that contain one of the named
877 ObjectClasses will be displayed without
878 the possibility for modification.
879 ( usually located in tweb.rc )
881 example: NO-MODIFY |toc_primas|
884 3.3 Load balancing configuration options
886 This section lists configuration options related to gateway-switching.
888 GW-SWITCH -- Defines DIT areas, which will direct TWEB to
889 introduce other gateway addresses for the
890 so-called gateway-switching
891 (STATIC gateway-switching; see section 2.7)
892 ( usually located in tweb.conf )
894 REMARK: A set of slides explaining gateway-switching,
895 presented at the January-1999 DANTE meeting
896 in Utrecht, NL, can be found at the TWEB FTP
898 ftp://ftp-x500.uni-tuebingen.de/tweb
900 example: GW-SWITCH "ROOT" HTTP://x500-relay.
901 uni-tuebingen.de:8901/M
902 "c=DE" HTTP://x500-relay.
903 uni-tuebingen.de:8911/
905 DYNAMIC-GW -- If given, tells TWEB to use dynamic gateway-
906 switching; if not given, only static switching
907 will be used, if configured;
908 a labeledURI attribute in an X.500 entry con-
909 taining (gw), (gw-de), or (gw-en) in its label
910 part is used to link this entry to another gateway
911 ( usually located in tweb.rc )
915 3.4 Display configuration options
917 This section lists options related to the displaying of results on an
918 HTML page. The options direct display of entries, attributes, as well
919 as styles for displaying.
921 SORT -- Classification of a list of entries into sub-lists
922 according to their object classes; generating of
923 sub-lists will be according to the order the
924 OCs are given in the SORT option; displaying the
925 sub-lists will be according to the numbers given
926 as third parameter; sub-lists without an intro-
927 ducing label (second parameter) should have a
928 label of " "; the fourth parameter is the DISPLAY-
929 TYPE for a given object (see below) and the fifth
930 parameter is the attribute used for sorting;
931 parameters four and five are optional;
932 if not given reasonable defaults will be used;
933 if none of the entries objectclasses is given
934 in the SORT option, TWEB will randomly select
935 one of the entry's OCs as a new entry to the
936 SORT list, using DISPLAY-TYPE "default"; if that
937 type is not defined, the entry will NOT be
939 (see also section 2.5)
940 ( usually located in tweb.conf.x )
942 example: SORT person Staff 4 person tat_sort
943 organization Organizations 3 orgs
944 organizationalUnit "O Units" 2 ous
947 DISPLAY-OBJECT -- For specified DISPLAY-TYPES define the order,
948 labels and type of HTML-code produced for given
949 attributes (see FIRST-PAGE, SECOND-PAGE below);
950 a DISPLAY-TYPE "default" will match all types
951 NOT specifically listed; when the default type
952 is not giving, some X.500 entries might NOT be
953 displayed (see also SHOW-DEFOC below)
954 ( usually located in tweb.conf.x )
956 example: DISPLAY-OBJECT person
959 FIRST-PAGE -- Attributes to be displayed for a specified
961 Format: <attribute> <label> <display-type>
963 MULTILINE -- attribute with multiple lines
964 DATE -- attribute as date
965 HREF -- attribute with syntax DN
966 as hyperlink (READ DN entry)
967 URI -- attribute with syntax URL
969 MAILTO -- attribute as mailto (must be
970 supported by WWW client)
971 MOVETO -- like HREF, but the link will
972 be a LIST, instead of a READ
974 BMP -- phote as bitmap
975 JPEG -- photo as jpeg
976 JPEG2GIF -- convert jpeg to gif
977 BOOLEAN -- binary attribute
978 PGPKEY -- display PGPKey for cut&paste
979 DYNAMICDN -- uses DIT-CONFIG to show
980 attribute as hyperlink
981 INDEXURL -- show this hyperlink as defined
983 DEFAULT -- anything else
985 example: DISPLAY-OBJECT person
986 FIRST-PAGE cn Name DEFAULT
987 personalTitle Title DEFAULT
990 SECOND-PAGE -- show additional attributes not displayed on
993 example: DISPLAY-OBJECT person
996 SECOND-PAGE sn Surname DEFAULT
997 info Information DEFAULT
999 SHOW-DEFOC -- Show Default Objectclass. If no objectclass
1000 did match -> show entry with attributes as
1001 defined in default-display
1002 ( usually located in tweb.rc )
1006 PULL-DOWN-MENUS -- Use BUTTONS and PULL-DOWN-MENUS instead of links
1007 in order to support: help, language-switch,
1008 move-upwards and read-entry functionalities
1009 ( usually located in tweb.rc )
1011 example: PULL-DOWN-MENUS
1013 LANGUAGE -- The labels of buttons for the switch to
1014 the other started language-specific gateways
1015 ( usually located in tweb.rc )
1017 example: LANGUAGE Deutsch
1021 STRIP-PIN -- Specify here the object-classes where numbers
1022 ( PINs, personal ident numbers, etc. ) following
1023 an RDN will be stripped when displayed
1024 ( usually located in tweb.rc )
1026 example: STRIP-PIN |toc_profs|person|toc_primas|
1027 toc_cperson|toc_funcs|toc_pextra|
1029 INDIRECT-ATTRS -- Format:
1030 INDIRECT-ATTRS <ref-attribute>
1031 IND_ATTRS <selection> REPLACE|APPEND <attribute>
1032 <host> <port> <baseDN>
1034 If there is an attribute with name <ref-attribute>
1035 in a given entry, values of attribute <attribute>
1036 in this entry will be REPLACEed|APPENDed by values
1037 taken from the same attribute <attribute> of
1039 "cn=<ref-attribute-value>,<baseDN>",
1040 looked-up at an LDAP server <host>:<port>,
1041 but only when some value in <ref-attribute>
1042 matches <selection> at its beginning
1043 ( usually located in tweb.rc )
1045 example: INDIRECT-ATTRS tat_refattr
1046 IND_ATTRS POST- append postaladdress
1047 x500.uni-tuebingen.de 10100
1048 "ou=POST,ou=INTERNA,ou=NETZWERK,
1049 o=Universitaet Tuebingen,c=DE"
1051 DISP-SEA-RDN -- Make search-results to be displayed only by RDN
1052 and not by DN relative to the search-base
1053 ( usually located in tweb.rc )
1055 example: DISP-SEA-RDN
1057 INDEX-URL -- Display labels of hyperlinks only with selected
1058 RDN parts in the order configured by INDEX-URL;
1059 this option applies to URL attributes within an
1060 entry, which are directed towards other X.500
1061 entries; an application of that might be an
1063 DISPLAY-TYPE must be set to INDEXURL.
1064 ( usually located in tweb.rc )
1066 example: INDEX-URL 0,-2 "o=Universitaet Tuebingen, c=DE"
1068 i.e.: labels of a hyperlink below the University
1069 of Tuebingen are shown as follows:
1071 1. lowest part of the DN (e.g., a person's name)
1072 2. third-top-most part of the DN (e.g., faculty)
1074 all other DN parts will be supressed
1077 TABLES <ALLOW|ALL> <objectclass> <Button-label>
1078 <mode-selection>:<attribute>,<col-width>
1079 [&<attribute>,<col-width>]*
1081 During browsing, the entries listed below a
1082 base object (i.e., DIT position) can be displayed
1083 together with some selected attributes in a
1084 tabular format; the SORT configuration option
1085 will be applied to the entries; attribute mail
1086 will be displayed as mailto: and the RDN will
1087 be displayed as a link to the respective entry;
1088 in order to select the tabular format, TWEB will
1089 display a button with a given label, that, if
1090 pressed, will request the tabular format;
1091 however, the button will only be displayed, if
1092 the requesting user is allowed to get this
1093 feature (i.e., ALLOW will select internal users
1094 only, whereas ALL will select all users)
1096 example: TABLES ALLOW oleaf Tabelle persontable:rdn,28
1097 &telephonenumber,25&tat_dummyattr,2
1100 i.e.: ALLOW -> only allowed users will see the table
1101 oleaf -> table button is shown on presence of
1102 the objectclass oleaf in the base entry
1103 Tabelle -> the label for the table-request-
1105 persontable -> the keyword for function-
1106 selection of a persons' table
1107 rdn,28 -> first the rdn-attribute is shown
1108 in the table with width 28 percent
1109 telephonenumber,25 -> telephonenumber,
1111 tat_dummyattr,2 -> a separating column, width 2
1112 mail,45 -> the e-mail-address with width 45
1114 (all width values are given in percentage of
1115 the width of the browsers window, and should
1119 4 Support and discussion list
1121 Bug reports and flames (but also critical comments) send to
1123 tweb-support@mail500.uni-tuebingen.de.
1125 For general discussion (e.g., about interesting new features,
1126 which should be supported), there is a discussion list at
1128 tweb-l@mail500.uni-tuebingen.de.
1130 Send requests for subscription to
1132 tweb-l-request@mail500.uni-tuebingen.de.
1136 TWEB development team, Tuebingen, January, 15th, 1999