1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
<!doctype html public "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>WN Auxiliary Modules</title>
<link rev="made" href="mailto:john@math.nwu.edu">
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
<meta http-equiv="last-modified" content="Fri, 09 Oct 1998 18:18:09 GMT">
<meta http-equiv="keywords" content="WN auxiliary modules">
</head>
<body bgcolor="#FFFFFF">
<p>
<a href="http://hopf.math.nwu.edu/"><img
src="images/powered.jpg"
border="0"
width="190"
height="41"
align="right"
alt="WN home page"
></a>
</p>
<strong>Version 2.0.3</strong>
<br>
<!-- pnuts --> <a href="utility.html">[Previous]</a> <a href="click.html">[Next]</a> <a href="manual.html">[Up]</a> <a href="manual.html">[Top]</a> <a href="dosearch.html">[Search]</a> <a href="docindex.html">[Index]</a>
<br clear="right">
<hr size="4">
<!-- #start -->
<h2 align="center"><em>WN</em> Auxiliary Modules</h2>
<hr size="4">
<p>
<em>WN</em> provides some features by auxiliary modules. These are
separate C programs called by the server to provide some function like
authorization (authentication) or indexed searches or database access.
The current release of <em>WN</em> has a module for authorization using
the <a href="http://www.w3c.org/Protocols/">HTTP/1.1</a> Basic
Authentication scheme supported by most clients and future releases will
have a module to do index searches.
</p>
<p>
The current version also has the support infrastructure or "hooks" for
several services which maintainers may wish to create.
</p>
<h3>14.1 <a name="db">Database Modules</a></h3>
<p>
The <code>index.cache</code> in each directory is in fact a small flat
database containing characteristics of that directory and the files
contained in it. This can be replaced on a per directory basis by a user
supplied module to provide the same information. In the <a
href="index_desc.html#index"><code>index</code></a> file for such a
directory you should create a <a href="appendixB.html#ddir">directory
directive</a> entry like:
</p>
<blockquote>
<code>
<a
href="appendixB.html#ddir.cache-module">Cache-Module=</a>/full/path/to/foo
</code>
</blockquote>
<p>
The program "<code>foo</code>" should be an interface to your
database. It is permissible to follow "<code>foo</code>" in this line
with any desired arguments to be passed to it. The program
"<code>foo</code>" should read the environment variable <a
href="appendixD.html#wn_key.WN_KEY"><code>WN_KEY</code></a> which will
contain everything after the final '<code>/</code>' in the URL being
served. Based on this key it should return a single line in the <a
href="cacheformat">format of an <code>index.cache</code></a> file. Any
"<code><a href="appendixB.html#fdir.file">File=</a></code>" directives in
an <a href="index_desc.html#index"><code>index</code></a> file which
contains a "<code><a
href="appendixB.html#ddir.cache-module">Cache-Module=</a></code>"
directive will be ignored.
</p>
<p>
You may wish the cache module function to have access to more information
about the request. If you put the directive "<code><a
href="appendixB.html#ddir.default-attributes">Default-attributes</a>=cgi</code>"
before the "<code><a
href="appendixB.html#ddir.cache-module">Cache-Module=</a></code>"
directive then all the <a href="appendixD.html">CGI environment
variables</a> will be set.
</p>
<p>
If the file cache module encounters an error, such as no entry
corresponding to the supplied key, it should return nothing and exit with
a negative status. This signals the server to return an appropriate
error message.
</p>
<h3>14.2 <a name="file">File Modules</a></h3>
<p>
It is perhaps more useful to have the files being returned reside in a
database. To use such a database interface called "<code>bar</code>", in
the <a href="index_desc.html#index"><code>index</code></a> file for its
directory you should create a <a href="appendixB.html#ddir">directory
directive</a> entry like:
</p>
<blockquote>
<code>
<a
href="appendixB.html#ddir.file-module">File-Module=</a>/full/path/to/bar
</code>
</blockquote>
<p>
The program "<code>bar</code>" should be an interface to your database.
It should read the environment variable <a
href="appendixD.html#wn_key.WN_KEY"><code>WN_KEY</code></a> which will
contain everything after the final '<code>/</code>' in the URL being
served. Based on this key it should return a document to be served
(perhaps after processing with wrappers or includes). When a file module
is used it is also necessary to either use a "<code><a
href="appendixB.html#ddir.cache-module">Cache-Module=</a></code>" or have
an actual <code>index.cache</code> file with the name of all documents
which might be returned by the database or to have an
<code>index.cache</code> file created from an <a
href="index_desc.html#index"><code>index</code></a> file containing the
directory directive "<code><a
href="appendixB.html#ddir.attributes.serveall">Attributes=serveall</a></code>".
If the file module encounters an error, such as no document corresponding
to the supplied key, it should return an appropriate error message of the
same <code>content-type</code> as the requested document.
</p>
<p>
As with <a href="#db">cache modules</a>, you may wish the file module
function to have access to more information about the request. If you
put the directive "<code><a
href="appendixB.html#ddir.default-attributes">Default-attributes=</a>cgi</code>"
before the "<code><a
href="appendixB.html#ddir.file-module">File-Module=</a></code>" directive
in your <a href="index_desc.html#index"><code>index</code></a> file then
all the <a href="appendixD.html">CGI environment variables</a> will be
set.
</p>
<h3>14.3 <a name="authorization">Authorization Modules</a></h3>
<p>
Authorization requests in <em>WN</em> are normally handled by an
authorization module. The current release contains a <a
href="access.html#authenticate">Basic Authentication module</a> and a <a
href="http://hopf.math.nwu.edu/digestauth/index.html">prototype
implementation of Digest Authentication</a>, but users are invited to
provide their own.
</p>
<blockquote>
<em>Warning:</em> I would strongly advise against using basic
authentication described here to protect sensitive information on a
server which runs on system on which untrusted users have accounts.
</blockquote>
<p>
The contents the <code>Authorization:</code> request header is passed to
the module on the UNIX <code><a
href="http://linux-howto.com/man/man3/stdio.3.html">stdin(3)</a></code>
stream (as of version 1.10).
</p>
<p>
The server expects this module to exit with a status indicating that
access is granted, denied, or that an error occurred. Anyone writing an
authorization module should consult the file
<code>/wnauth/wnauth.h</code>. The "<code>#define</code>s" listed there
specify the error status to use for granting, denying or indicating
certain errors.
</p>
<p>
To use a user supplied authorization module named <code>authmod</code>
the <a href="index_desc.html#index"><code>index</code></a> file of each
directory requiring authorization should contain lines like:
</p>
<blockquote>
<code>
<a
href="appendixB.html#ddir.authorization-realm">Authorization-realm=</a>myrealm
<br>
<a
href="appendixB.html#ddir.authorization-module">Authorization-module=</a>/full/path/to/authmod
<br>
<a
href="appendixB.html#ddir.authorization-type">Authorization-type=</a>basic
</code>
</blockquote>
<p>
The program <code>authmod</code> should indicate the granting or denial
of authorization by its exit status as described above. The "<code><a
href="appendixB.html#ddir.authorization-realm">Authorization-realm=</a></code>"
is a designation which is sent to the client with the authorization
request allowing the client to decide whether the user has already
supplied a password which can be reused (if the realm is the same as when
the password was supplied) or if a new password needs to be entered.
</p>
<h3>14.4 <a name="isearch">Index Search Modules</a></h3>
<p>
Indexed searches can be supported in <em>WN</em> by auxiliary modules.
Two such modules are provided as examples and maintainers may wish to
create others. To use such a module you should have an HTML <a
href="http://htmlhelp.com/reference/wilbur/block/form.html"><code><form></code></a>
action be something like:
</p>
<blockquote>
<code>
http://host/dir/search=index
</code>
</blockquote>
<p>
Then in the <a href="index_desc.html#index"><code>index</code></a> file
in the directory record you should have a line like:
</p>
<blockquote>
<code>
<a
href="appendixB.html#ddir.search-module">Search-Module=</a>/full/path/to/searchmod
</code>
</blockquote>
<p>
The program <code>searchmod</code> should read the CGI environment
variable <a
href="appendixD.html#cgi.QUERY_STRING"><code>QUERY_STRING</code></a> and
return a partial HTML document. The typical case would be the program
returns an unordered list of anchors to documents containing a match to
the query string. This list can be wrapped by including a "<code><a
href="appendixB.html#ddir.searchwrapper">Searchwrapper=</a></code>"
directory directive. If it is not, a default wrapper with text like
"<code>Here are the matches for your search.</code>" is supplied.
</p>
<p>
Two simple examples of a search-module (written in <a
href="http://www.perl.org/">perl</a>) are included in the distribution in
the files <code>bin/wnseven_m</code> and <code>bin/wnsectsearch</code>.
<p>
<!-- #end -->
<hr size="4">
<address>
<em>WN</em> version 2.0.3
<br>
Copyright © 1998 <a href="mailto:john@math.nwu.edu">John Franks
<john@math.nwu.edu></a>
<br>
licensed under the <a href="http://www.opencontent.org/opl.html">
OpenContent Public License</a>
<br>
last-modified: Fri, 09 Oct 1998 18:18:09 GMT
</address>
<!-- pnuts --> <a href="utility.html">[Previous]</a> <a href="click.html">[Next]</a> <a href="manual.html">[Up]</a> <a href="manual.html">[Top]</a> <a href="dosearch.html">[Search]</a> <a href="docindex.html">[Index]</a>
</body>
</html>
|
