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
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
|
<!doctype html public "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>Filters on the WN server</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 filters">
</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="field.html">[Previous]</a> <a href="range.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">Filters on the <em>WN</em> Server</h2>
<hr size="4">
<h3>8.1 <a name="process">Processing a File as it is Served</a></h3>
<p>
An arbitrary "filter" can be assigned to any file to be served. A filter
is a program which reads the file and has the program output served
rather than the content of the file. One common use of this feature is
for on-the-fly decompression. For, example a file can be stored in its
compressed form and assigned a filter like the UNIX <a
href="http://linux-howto.com/man/man1/zcat.1.html"><code>zcat(1)</code></a>
utility which uncompresses it. Then the client is served the
uncompressed file but only the compressed version is stored on disk. As
another example, you might use "<code>nroff -man</code>" as a filter to
process UNIX <a
href="http://linux-howto.com/man/man1/man.1.html"><code>man(1)</code></a>
utility for formatting man pages before serving. There are many other
interesting uses of filters. Be creative!
</p>
<p>
A filter is assigned to a file by use of the "<code><a
href="appendixB.html#fdir.filter">Filter=</a></code>" directive in the
file's record in its <code>index.cache</code> file. For example, the
lines:
</p>
<blockquote>
<code>
<a href="appendixB.html#fdir.file">File=</a>foo.gz
<br>
<a href="appendixB.html#fdir.content-type">Content-type=</a>text/plain
<br>
<a href="appendixB.html#fdir.filter">Filter=</a>/usr/local/bin/zcat
<br>
<a
href="appendixB.html#fdir.content-encoding">Content-encoding=</a>none
</code>
</blockquote>
<p>
cause the compressed file <code>foo.gz</code> to be uncompressed on the
fly and served to the client as a <code>text/plain</code> document.
Notice that it is necessary to have the content-encoding line to override
the default action of <a
href="index_desc.html#wndex"><code>wndex</code></a> which is to infer
from the "<code>.gz</code>" suffix that the content-encoding is
<code>x-gzip</code>. If the compressed file were named simply
"<code>foo</code>" then the content-encoding line would be unnecessary.
</p>
<p>
The "<code><a href="appendixB.html#fdir.filter">Filter=</a></code>"
directive takes the value of a path to a file in three different forms.
If the path begins with a '<code>/</code>' then it is relative to the
system root. If it begins with '<code>~/</code>' then it is relative to
the <em>WN</em> hierarchy root, and otherwise it is relative to the
directory containing the <a
href="index_desc.html#index"><code>index</code></a> file.
</p>
<p>
If a file has a filter only that file will be filtered, not any <a
href="parse.html#wrapping">wrappers</a> or <a
href="parse.html#including">includes</a>.
</p>
<p>
The ability to filter files can be restricted in several ways. If
<em>WN</em> is invoked with the <a
href="appendixA1.html#e_opt"><code>-e</code></a> option then no includes,
filters, or <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a>
programs will be executed.
</p>
<p>
The <a href="appendixA1.html#E_opt"><code>-E</code></a> option in
conjunction with the <a href="appendixA1.html#t_opt"><code>-t</code></a>
or <a href="appendixA1.html#T_opt"><code>-T</code></a> option restricts
the use of filters to those listed in <code>index.cache</code> files
owned by trusted users or groups. The <a
href="appendixA1.html#u_opt"><code>-u</code></a> option allows only the
use of filters owned by the owner of the <code>index.cache</code> file
which lists them.
</p>
<p>
The directory directive:
</p>
<blockquote>
<code>
<a
href="appendixB.html#ddir.default-filter">Default-Filter=</a>/path2/filter
</code>
</blockquote>
<p>
specifies that files in this directory should all be treated as if the
"<code><a href="appendixB.html#fdir.filter">Filter=</a></code>" file
directive had been set to <code>/path2/filter</code>. To override this
setting and specify no filter use the "<code><a
href="appendixB.html#fdir.filter">Filter=</a><none></code>"
directive.
</p>
<h3>8.2 <a name="cgi">Filters as a Substitute for CGI Programs</a></h3>
<p>
The filter mechanism built into <em>WN</em> has most of the functionality
of the <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">Common Gateway
Interface (CGI) standard</a> and has some features <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> does not. Filters
are also in some ways more secure. This makes them a good choice for
applications where compatibility with the <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> standard is not
required.
</p>
<p>
The first thing to note is that there is no requirement that the filter
program actually make use of the file being filtered. This file must
exist though.
</p>
<p>
Thus if an empty file "<code>foo</code>" is created and has an <a
href="index_desc.html#index"><code>index</code></a> file entry like:
</p>
<blockquote>
<code>
<a href="appendixB.html#fdir.file">File=</a>foo
<br>
<a href="appendixB.html#fdir.content-type">Content-type=</a>text/html
<br>
<a href="appendixB.html#fdir.filter">Filter=</a>someprogram
<br>
<a href="appendixB.html#fdir.attributes">Attributes=</a>parse,cgi
</code>
</blockquote>
<p>
then the output of the program "<code>someprogram</code>" will be served.
A program used in this way differs somewhat from a <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> program in that no
headers should be supplied by the program as <em>WN</em> will
automatically provide them. For example, while a <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> program typically
starts with printing "<code>Content-type: text/html</code>" followed by a
blank line, this should not be done for "<code>someprogram</code>" in the
<code>index</code> entry above, because <em>WN</em> will automatically
provide the appropriate <a
href="http://www.w3c.org/Protocols/">HTTP/1.1</a> headers based on the
"<code><a
href="appendixB.html#fdir.content-type">Content-type=</a>text/html</code>"
line in the <a href="index_desc.html#index"><code>index</code></a> file.
</p>
<p>
An important difference between filters and <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> programs is that the
output of filters can be <a href="parse.html">parsed</a> while <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> output cannot. The
fact that you want the output parsed must be signalled by the use of an
"<code><a
href="appendixB.html#fdir.attributes.parse">Attributes=parse</a></code>"
line in the directory's <a
href="index_desc.html#index"><code>index</code></a> file.
</p>
<p>
If you wish to have all the standard <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> environment variables
made available to the filter program you can do so by adding the line:
</p>
<blockquote>
<code>
<a href="appendixB.html#fdir.attributes.cgi">Attributes=cgi</a>
</code>
</blockquote>
<p>
to the file record. A list of these environment variables can be found
in appendix "<a href="appendixD.html">CGI and other Environment Variables
for the <em>WN</em> Server</a>" in this guide. Also see the <a
href="examples/sample.cgi">sample CGI program</a> which is located in the
file <code>/docs/examples/sample.cgi</code> which accompanies the
<em>WN</em> distribution.
</p>
<p>
One difference between <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> programs and filters
is that with filters there is no way to have a non-empty <a
href="appendixD.html#cgi.PATH_INFO"><code>PATH_INFO</code></a>
environment variable since anything appended to the path part of the URL
will be interpreted as a path to an actual file. Of course the "query"
part of a URL (everything after a '<code>?</code>') will work for filters
as well as <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a>
programs and its contents will be put in the <a
href="appendixD.html#cgi.QUERY_STRING"><code>QUERY_STRING</code></a>
environment variable.
</p>
<p>
Another difference between <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> and filter programs
is in the handling of <code>POST</code> or <code>PUT</code> data. A <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> program reads the
data provided by the client on its UNIX <code><a
href="http://linux-howto.com/man/man3/stdio.3.html">stdin(3)</a></code>
stream. This is not possible for a filter since its <code><a
href="http://linux-howto.com/man/man3/stdio.3.html">stdin(3)</a></code>
is attached to the file it is supposedly filtering. To use the
<code>PUT</code> or <code>POST</code> method with a filtered file, the
"<code><a
href="appendixB.html#fdir.attributes.post">Attributes=post</a></code>"
directive must be used since otherwise the server will not permit a
<code>POST</code> or <code>PUT</code>. It is then possible to read the
<code>POST</code>ed data by opening and reading the temporary file
containing this data. The name of this file changes with each request,
but if "<code><a
href="appendixB.html#fdir.attributes.cgi">Attributes=cgi</a></code>" is
used then the name is given in the <em>WN</em> specific CGI environment
variable <a
href="appendixD.html#wn_cgi.HTTP_POST_FILE"><code>HTTP_POST_FILE</code></a>
or <a
href="appendixD.html#wn_cgi.HTTP_PUT_FILE"><code>HTTP_PUT_FILE</code></a>
depending on the method used to submit the data.
</p>
<p>
One advantage of using a filter instead of a <a
href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a> program is that it
may have slightly better security. With a filter the name of the
executed program is never visible outside the server. It is not in any
URL and it is not in any served file. Perhaps a more important feature
is that no arguments can be supplied to a filter except those listed in
the <a href="index_desc.html#index"><code>index</code></a> file filter
entry. Unlike <a href="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI/1.1</a>
programs, it is not possible for a remote user to supply any arguments
whatsoever to the program.
</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="field.html">[Previous]</a> <a href="range.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>
|
