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
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
|
<section id="installation">
<title>Apache Rivet &version; Installation</title>
<procedure>
<para>
Rivet &version; runs with the Apache 2.2.x and 2.4.x HTTP web servers.
It is known to build and run on various Linux distributions
(Debian & Ubuntu, Redhat, SuSE and CentOS), FreeBSD and OpenBSD. For some
of these Unix-like operative systems
<ulink url="http://tcl.apache.org/rivet/html/download.html">binary packages</ulink>
are already available for download.
</para>
<para>
Rivet &version2-generic; was restricted to work with the
<ulink url="&apachedoc-prefork;">prefork</ulink> MPM
of the Apache HTTP webserver. MPM modules are fundamental components of the
webserver architecture. They provide multiple implementations of multiprocessing
in order to better suit specific OS features and scalability requirements.
The prefork MPM exploited the UNIX traditional approach to multiprocess server
applications based on the
<ulink url="https://en.wikipedia.org/wiki/Fork_(system_call)">fork</ulink>
system call. This model has several limitations but also some advantages. The
solution we adopted tries to attain the best from any MPM as much as possible
and Rivet &version; is now able to run with the
<ulink url="&apachedoc-worker;">worker</ulink>
and the
<ulink url="&apachedoc-event;">event</ulink>
MPMs. Rivet &version; has not been ported to OS of the Windows family
but we feel that the current design would fit just fine with the Windows specific
MPMs such as
<ulink url="&apachedoc-winnt;">winnt</ulink>.
</para>
<para>
If you need to build Apache Rivet yourself this is the procedure to follow
</para>
<step performance="required">
<title>Building Tcl: requirements</title>
<para>
Installing Rivet is about endowing the Apache HTTP webserver with the ability
of running scripts written with the Tcl programming language.
Therefore the
<ulink url="http://www.tcl.tk/">Tcl</ulink> language with its runtime,
development libraries and shell (≥8.5.10 required, ≥8.6.0 recommended)
have to be installed. Building Rivet you will
have to tell the scripts where the Tcl libraries are located via the
<option>--with-tcl</option> option of the <command>configure</command> script
(see below).
</para>
<para>
Several Tcl packages shipped with rivet need also the
<ulink url="http://core.tcl.tk/itcl/">Itcl</ulink>
OOP extension of Tcl. If you need to run any of the
<link href="session_package">Session</link> or <link href="dio">DIO</link>
packages you need to install this language extension but you don't need it
to build mod_rivet
</para>
<para>
The
<ulink url="&apache-url;">Apache HTTP Webserver</ulink> development
files and libraries are required along with the
<ulink url="&apache-apr;">Apache Portable Runtime</ulink>
and the
<ulink url="&apache-apreq;">libapreq</ulink> library.
</para>
</step>
<step>
<title>Building Rivet</title>
</step>
<step performance="optional">
<title>Getting and Installing the Apache Sources</title>
<para>
You can build Rivet either statically (compiled into the Apache web
server) or dynamically (as a loadable shared library).
We recommend that you build Rivet as a shared library, for maximum flexibility.
We will tell Rivet where it the Apache development files and libraries are located
via the <option>--with-apxs</option> option to <command>configure</command> (see below).
</para>
<para>
Most modern Unix OS (Linux and FreeBSD systems included) come with their
own packages of the Apache Web Server executables, runtime libraries and development files
and libraries. Check the documentation of the package manager of your OS
to find out how to install this software
</para>
</step>
<step>
<title>Uncompress Sources</title>
<para>
Download the sources at <ulink url="&rivet-download;"/>.
</para>
<para>
We will assume that you have Apache installed at this point.
You must uncompress the Rivet sources in the directory where you
wish to compile them.
<programlisting>gunzip rivet-&fullversion;.tar.gz
tar -xvf rivet-&fullversion;.tar.gz</programlisting>
</para>
</step>
<step>
<title>Building Rivet</title>
<substeps>
<step>
<para>
Rivet uses the standard <command>./configure ; make ; make install</command>
sequence which installs to their target directories the Apache module, the binary libraries and the
Tcl code
</para>
<para>
There are several rivet specific options to configure that might be useful (or needed):
<variablelist>
<varlistentry>
<term>--with-apache</term>
<listitem>
<para>
Defines the configure internal variable 'apache_base'. This variable
points to the root of the Apache web server directory hierarchy
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-tcl</term>
<listitem>
<para>
This points to the directory where the
<filename>tclConfig.sh</filename> file is located.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-tclsh</term>
<listitem>
<para>This points to the location of the
<filename>tclsh</filename> executable.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-apxs</term>
<listitem>
<para>
The location of the <filename>apxs</filename>
program that provides information about the
configuration and compilation options of Apache modules.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-apache-include[=DIR]</term>
<listitem>
<para>
Locates the Apache include files on your computer, if they're not in standard directory.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-version-display=[yes|no]</term>
<listitem>
<para>
This option enables Rivet to display its version in the
logfiles when Apache is started. The default is to keep the Rivet version hidden.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-rivet-target-dir=DIR</term>
<listitem>
<para>
This option is for fine tuning of the installation final directories. Rivet Tcl packages,
commands and loadable libraries go into the same directory hierarchy
(by default is ${apache_base}/lib/rivet${PACKAGE_VERSION}, where $apache_base takes
the value set by --with-apache)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-upload-dir=DIR</term>
<listitem>
<para>
Configures Rivet's default upload directory. It can be overridden in the configuration
either globally or specifically for a virtual host
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-post-max=BYTES</term>
<listitem>
<para>
The value to this option establishes a default for the maximum size of POST data.
Default: 0 (unlimited size)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-head-requests</term>
<listitem>
<para>
By default HEAD requests don't go through the usual request processing which leads
to script execution and therefore resource consumption and Rivet returns a
standard hardcoded HTML header to save CPU time. --enable-head-requests
can change the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-rivet-commands-export</term>
<listitem>
<para>
By default Rivet's commands are put on the export list of the <code>::rivet</code>
namespace. With this option you may prevent it thus forcing the programmers to
fully qualify in their code. By default this option is enabled and it can be
changed in the configuration with the directive ExportRivetNS. Disabling
this option can be also reverted to 'On' with the --enable-import-rivet-commands
switch
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-import-rivet-commands</term>
<listitem>
<para>
Rivet's namespace is by default imported into the global namespace. Enabling the import
of Rivet's commands overrides the switch and forces --enable-rivet-commands-export=yes
thus demanding the commands to be exported (otherwise it would generate errors at run-time).
This option is disabled by default and it can be changed in the configuration with
the ImportRivetNS directive
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-virtual-interps-separation</term>
<listitem>
<para>
This option changes the default for the SeparateVirtualInterps configuration
variable. Default: 0 (no separation among interpreters)
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Example: configuring the build system to compile Rivet for an Apache HTTP server custom installation,
using tcl8.6. In this specific case the determination of the apxs path is redundant and it could be
omitted since it could be inferred from the --with-apache option value
</para>
<programlisting>./configure --with-tcl=/usr/lib/tcl8.6/ --with-tclsh=/usr/bin/tclsh8.6 \
--with-apxs=/usr/local/apache2/bin/apxs --with-apache=/usr/local/apache2 \
--with-rivetlib-target-dir=/usr/local/apache2/rivet3.0</programlisting>
</step>
<step>
<title>Run make</title>
<para>
At this point, you are ready to run make, which should
run to completion without any errors (a warning or two
is OK, generally).
</para>
</step>
<step>
<title>Install</title>
<para>
Now, you are ready to run the
</para>
<programlisting>make install</programlisting>
<para>
to install the resulting files. The <code>install</code> target
actually fires the <code>install-binaries</code> and
<code>install-packages</code> targets which in turn
copy the binary modules and Tcl packages to their destination
directories. This commands create a functional Rivet environment with its
core language.
</para>
</step>
</substeps>
</step>
<step>
<title>Apache Configuration Files</title>
<para>
Rivet is relatively easy to configure - we start off by
adding the module itself:
</para>
<programlisting>LoadModule rivet_module <replaceable>/usr/lib/apache2/modules/mod_rivet.so</replaceable></programlisting>
<para>
This tells Apache to load the Rivet shared object, wherever
it happens to reside on your file system. Now we have to
tell Apache what kind of files are "Rivet" files and how to
process them:
</para>
<programlisting>AddType application/x-httpd-rivet rvt
AddType application/x-rivet-tcl tcl</programlisting>
<para>
These tell Apache to process files with the
<filename>.rvt</filename> and <filename>.tcl</filename>
extensions as Rivet files.
</para>
<para>
The characters encoding can be changed using the <command>header type</command> command,
but you can also change the default charset for the whole site:
</para>
<programlisting>AddType 'application/x-httpd-rivet;charset=utf-8' rvt</programlisting>
<para>
All the pages generated by Rivet on this site will be sent with a
<command>Content-Type:'text/html;charset=utf-8'</command> header.
</para>
<para>You may also wish to use Rivet files as index files for
directories. In that case, you would do the following:</para>
<programlisting>DirectoryIndex index.html index.htm index.shtml index.cgi index.tcl index.rvt</programlisting>
<para>
For other directives that Rivet provides for Apache
configuration, please see <xref linkend="directives"/>.
</para>
</step>
</procedure>
</section>
|
