"Fossies" - the Fresh Open Source Software Archive 
Member "cgiwrap-4.1/doc/install" (16 Jun 2008, 14823 Bytes) of package /linux/www/old/cgiwrap-4.1.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 CGIWrap - Installation Instructions
2 __________________________________________________________________
3
4 There are two sets of installation instructions here. The basic ones I
5 use, and a real-world example config contributed by Piotr Klaban below.
6
7 Quick Installation
8
9 Look at the notes to see if there are any hints for your platform.
10
11 Issue "./configure --help" to find out the various configuration
12 options. You will need to specify some of them. At the very
13 least, you will want to specify "--with-httpd-user=USERID".
14
15 Type "./configure <options>" with whatever options you need..
16
17 Type "make"
18
19 If you specified the installation directory in the options, you can
20 type "make install" to do all the following steps.
21
22 Copy cgiwrap executable to your servers cgi-bin directory
23
24 Make cgiwrap owned by root, executable by all, and setuid. (Note: This
25 step must be performed while logged in as "root")
26
27 chown root cgiwrap
28 chmod 4755 cgiwrap
29
30 Hardlink or symlink nph-cgiwrap, nph-cgiwrapd, cgiwrapd to cgiwrap in
31 the cgi-bin directory.
32
33 ln [-s] cgiwrap cgiwrapd
34 ln [-s] cgiwrap nph-cgiwrap
35 ln [-s] cgiwrap nph-cgiwrapd
36
37 You can, if you wish, install it with less permissive permissions. (Eg.
38 4750) But if you do this, make sure that the group of cgiwrap is
39 the same as the group that the server runs as.
40
41 *VERY IMPORTANT* - Do NOT allow any non-trusted user to run scripts
42 directly out of the main cgi-bin directory, as this will allow
43 them to use cgiwrap to run any of the other users scripts. The
44 reason for this is that if they can run scripts as the same
45 userid as the web server, they can subvert some of cgiwrap's
46 security checks to allow them to run other users scripts. I
47 recommend not running ANY scripts on the web server directly,
48 once you have cgiwrap installed.
49
50 Configuration Options
51
52 The following are options available with the 'configure' command. Items
53 in boldface are highly recommended. Defaults can be seen by issuing
54 './configure --help' or by looking at the 'config.h' file after you
55 have run 'configure'.
56
57 At an absolute minimum, you will probably want to specify the
58 '--with-install-dir' and '--with-httpd-user' options.
59
60 --with-perl=PATH
61 path to perl executable to use
62
63 --with-local-contact-name=NAME
64 Specify the name of the local contact
65
66 --with-local-contact-email
67 Specify the local contact's email address
68
69 --with-local-contact-phone
70 Specify the local contact's phone number
71
72 --with-local-contact-url
73 Specify a URL for the local contact
74
75 --with-local-site-url
76 Specify a URL for this site
77
78 --with-local-doc-url
79 Specify a URL for a local copy of the cgiwrap docs
80
81 --with-wall
82 Add the '-Wall' option for compilation with gcc, this is
83 intended primarily for development debugging.
84
85 --with-install-group=GROUP
86 group to install cgiwrap as
87
88 --with-install-dir=PATH
89 path to installation directory - this should be the path to your
90 server's cgi-bin directory
91
92 --with-cgi-dir=PATH
93 path relative to home dir for cgi scripts
94
95 --with-multiuser-cgi-dir=PATH
96 define a central cgi script directory that is searched if the
97 script is not found in a user directory. This can be used to
98 make a single script available that will run as any user,
99 however, this can be very dangerous if you're not extremely
100 careful designing your script. Do not enable this unless you
101 know what you're doing. It is not needed for normal usage.
102
103 --with-httpd-user=USER
104 define what userid the web server is running as - this is
105 required
106
107 --without-check-httpd-user
108 don't check to make sure cgiwrap is being run by server userid -
109 this is not recommended
110
111 --without-check-owner
112 disable check for matching owner
113
114 --without-check-group
115 disable check for matching group
116
117 --without-check-setuid
118 disable check for setuid script
119
120 --without-check-setgid
121 disable check for setgid script
122
123 --without-check-group-writable
124 disable check for group writable script
125
126 --without-check-world-writable
127 disable check for world writable script
128
129 --without-check-symlink
130 disable check for symlinked script
131
132 --with-check-shell
133 enable check for a valid user shell
134
135 --with-require-redirect-url
136 require that REDIRECT_URL be set in calling environment
137
138 --with-chroot=PATH
139 chroots script to PATH prior to script execution, requires
140 specific environment to be set up. See chroot docs for more
141 details.
142
143 --with-minimum-uid=UID set the minimum uid of user that can use
144 cgiwrap, defaults to 100
145
146 --with-minimum-gid=GID set the minimum gid or aux gid of user that can
147 use cgiwrap - not enabled by default
148
149 --with-logging-syslog=LABEL
150 enable logging script execution to syslog
151
152 --with-logging-file=FILE
153 enable logging script execution to file
154
155 --without-script-subdirs
156 prevent users from storing scripts in subdirs
157
158 --without-redirect-stderr
159 don't redirect stderr to stdout in scripts
160
161 --without-initgroups
162 disable use of initgroups() to clear non-userid auxilliary
163 groups
164
165 --without-setgroups
166 disable use of setgroups() to add userid's auxilliary groups
167
168 --with-rewrite=FILE
169 use a file to rewrite user directories
170
171 --with-setenv-path=STRING
172 set PATH environment variable to STRING
173
174 --with-setenv-tz=STRING
175 set TZ environment variable to STRING
176
177 --with-rlimit-cpu=SECONDS
178 limit cpu time with setrlimit
179
180 --with-rlimit-vmem=BYTES
181 limit total virtual memory with setrlimit
182
183 --with-rlimit-as=BYTES
184 limit total available memory with setrlimit
185
186 --with-rlimit-fsize=BYTES
187 limit writable file size with setrlimit
188
189 --with-rlimit-data=BYTES
190 limit data segment size with setrlimit
191
192 --with-rlimit-stack=BYTES
193 limit stack segment size with setrlimit
194
195 --with-rlimit-core=BYTES
196 limit core file size with setrlimit
197
198 --with-rlimit-rss=BYTES
199 limit resident set size with setrlimit
200
201 --with-rlimit-nproc=COUNT
202 limit number of processes with setrlimit
203
204 --with-rlimit-nofile=COUNT
205 limit number of open files with setrlimit
206
207 --with-rlimit-memlock=BYTES
208 limit lockable memory with setrlimit
209
210 --with-allow-file=FILE
211 limit cgiwrap usage
212
213 --with-deny-file=FILE
214 limit cgiwrap usage
215
216 --with-vhost-allow-dir=DIR
217 limit cgiwrap usage specific to each vhost, to restrict
218 UnixTools.ORG, you would create the access file
219 'DIR/unixtools.org'.
220
221 --with-vhost-deny-dir=DIR
222 limit cgiwrap usage specific to each vhost
223
224 --with-host-checking
225 allow specifying hosts in allow/deny files
226
227 --with-afs=DIR
228 enable afs setpag() support
229 __________________________________________________________________
230
231 Password Protected Installation
232
233 The following are pecial additional instructions for installing a copy
234 of cgiwrap that allows users to create access controlled scripts. For
235 this to work, you will need to have a single common password file that
236 will be used by all authenticated scripts.
237
238 Re run configure, specify "public_html/auth-cgi-bin" instead of
239 "public_html/cgi-bin" for the cgi directory.
240
241 Type make.
242
243 Create a new server cgi-bin directory called "auth-cgi-bin", and
244 install this new copy of cgiwrap into that directory the same
245 way you installed it into the cgi-bin directory. (4 copies, and
246 set permissions). You will now be able to use the url:
247 http://server/auth-cgi-bin/cgiwrap...
248
249 To enable access control, place a .htaccess or equivalent file in the
250 auth-cgi-bin directory where cgiwrap is located, that requires
251 authentication to get at any file in that directory, but will
252 allow any valid user to get through.
253
254 Now, your users can simply check: 1. That their script was executed by
255 them (eg. check the real uid of the script to make sure someone
256 else wasn't running it by hand) 2. That the REMOTE_USER
257 environment variable contains a user name that they want to
258 allow to access the script.
259 __________________________________________________________________
260
261 Supplementary Configuration
262
263 If you enabled the access file checking, you need to make sure and
264 create the necessary files.
265
266 If you enabled the user directory rewriting feature, you need to create
267 the configuration file that you specified in the configure run.
268 __________________________________________________________________
269
270 Here is the real-world example, for those who have problems
271 with cgiwrap installing.
272
273 Assumptions:
274
275 A. I use cgi-bin/ for global cgi scripts, you may choose /cgi-sys/ instead.
276 B. I have installed apache in /usr/local/apache/ directory, you may have
277 it in different location (/etc/httpd/ etc.)
278 C. I use WWW as a user web directory ('UserDir WWW' Apache directive),
279 you may choose public_html if you wish.
280 D. I allow users place .cgi and .php scripts everywhere under the WWW/ director
281 y
282 (--with-cgi-dir=WWW cgiwrap configuration option), you may choose another me
283 thod.
284 E. I have system-wide html pages in /usr/local/apache/WWW/HTML
285 ('DocumentRoot /usr/local/apache/WWW/HTML' apache directive)
286 and system-wide cgi-bin/ directory in /usr/local/apache/WWW/cgi-bin/
287 ('ScriptAlias' apache directive)
288
289 Make sure you have installed php, that you can run it from the command line,
290 and you see the '--enable-discard-path' configuration option in the output
291 of the following command:
292 % php -i | grep configure
293 If not, then before/after installing cgiwrap, install php as a normal program
294 with the configuration option: --enable-discard-path
295
296 cgiwrap install procedure:
297
298 1. download and unpack cgiwrap archive
299
300 % wget http://telia.dl.sourceforge.net/sourceforge/cgiwrap/cgiwrap-3.8.tar.gz
301 % gtar zxvf cgiwrap-3.8.tar.gz
302 % cd cgiwrap-3.8
303
304 2. configure it:
305
306 Replace:
307 - /usr/local/bin/php with /usr/bin/php or other location of your php program
308 - WWW (in --with-cgi-dir=WWW) with public_html i.e. your users web directory
309 - /usr/local/apache/WWW/cgi-bin with /home/httpd/cgi-sys if you use such a valu
310 e
311 for ScriptAlias
312 - admin@man.torun.pl with YOUR contact address
313 - www (in --with-httpd-user=www) with apache if you run web server as 'apache'
314 user
315
316 ./configure --with-check-shell --with-rlimit-core=0 --with-rlimit-cpu=60 \
317 --without-redirect-stderr --without-logging-file --with-perl=/usr/bin/perl \
318 --with-httpd-user=www --with-cgi-dir=WWW \
319 --with-install-dir=/usr/local/apache/WWW/cgi-bin --with-wall \
320 --with-local-contact-email=admin@man.torun.pl --with-php=/usr/local/bin/php \
321 --with-php-interpreter
322
323 # wait ...
324 # wait more until configure checks everything
325
326 3. run make
327
328 % make
329
330 That should output:
331
332 gcc -c -Wall -g -O2 -I. -I. debug.c
333 gcc -c -Wall -g -O2 -I. -I. util.c
334 util.c: In function `CheckUser':
335 util.c:370: warning: suggest parentheses around assignment used as truth value
336 util.c: In function `UserInFile':
337 util.c:1088: warning: subscript has type `char'
338 util.c:1096: warning: subscript has type `char'
339 gcc -c -Wall -g -O2 -I. -I. fetch.c
340 gcc -c -Wall -g -O2 -I. -I. stdutil.c
341 gcc -c -Wall -g -O2 -I. -I. msgs.c
342 gcc -o cgiwrap cgiwrap.o debug.o util.o fetch.o stdutil.o msgs.o
343
344 4. install with 'make install':
345
346 % make install
347
348 That would be executed (make install -n):
349
350 rm -f /usr/local/apache/WWW/cgi-bin/cgiwrap
351 rm -f /usr/local/apache/WWW/cgi-bin/cgiwrapd
352 rm -f /usr/local/apache/WWW/cgi-bin/nph-cgiwrap
353 rm -f /usr/local/apache/WWW/cgi-bin/nph-cgiwrapd
354 # rm -f /usr/local/apache/WWW/cgi-bin/php-cgiwrap
355 # rm -f /usr/local/apache/WWW/cgi-bin/php-cgiwrapd
356 cp cgiwrap /usr/local/apache/WWW/cgi-bin/cgiwrap
357 chown root /usr/local/apache/WWW/cgi-bin/cgiwrap
358 chgrp root /usr/local/apache/WWW/cgi-bin/cgiwrap
359 chmod 4755 /usr/local/apache/WWW/cgi-bin/cgiwrap
360 ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/cgiwrapd
361 ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/nph-cgiw
362 rap
363 ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/nph-cgiw
364 rapd
365 # ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/php-cg
366 iwrap
367 # ln /usr/local/apache/WWW/cgi-bin/cgiwrap /usr/local/apache/WWW/cgi-bin/php-cg
368 iwrapd
369
370 Then you see you have cgiwrap in the /usr/local/apache/WWW/cgi-bin/
371 directory.
372
373 5. Now configure Apache:
374
375 % cd /usr/local/apache/conf (on linux: % cd /etc/httpd/conf/)
376 % vim httpd.conf (or % pico httpd.conf)
377
378 5a) add these lines to global directives:
379
380 # change /usr/local/apache/WWW/cgi-bin/ to YOUR /cgi-bin/ real path
381 ScriptAlias /cgi-bin/ "/usr/local/apache/WWW/cgi-bin/"
382
383 AddHandler cgi-wrapper .php
384 AddHandler cgi-wrapper .cgi
385 Action cgi-wrapper /cgi-bin/cgiwrap
386
387 5b) do not run cgiwrap on .cgi scripts in the global /cgi-bin/ directory:
388
389
390 AllowOverride None
391 Options None
392 AddHandler cgi-script .cgi
393
394
395 5c) I have a phpMyAdmin installed in /user/local/apache/WWW/HTML/phpMyAdmin/,
396 and I want it to be run as a 'www' user from the /WWW/HTML/ directory
397
398
399 Action cgi-wrapper /cgi-bin/cgiwrap/www/HTML
400
401
402 5d) I have some Virtual Domains defined. Every user can have its own
403 virtual domain. I want .cgi and .php scripts to be run as a specified user
404 ('makler' in this situation):
405
406
407 ServerAdmin info@klaban.torun.pl
408 DocumentRoot /home/[... home directory/WWW here ...]/makler/WWW
409 ServerName www.klaban.torun.pl
410 ErrorLog logs/klaban_error_log
411 CustomLog logs/klaban_access_log combined
412 Action cgi-wrapper /cgi-bin/cgiwrap/makler
413
414 # [... other configuration stuff discarded ...]
415
416
417
418 6. Test your configuration before Apache reload (you may use /etc/init.d/httpd
419 instead of ~www/bin/apachectl):
420
421 % ~www/bin/apachectl configtest
422 Syntax OK
423
424 7. Reload apache web server:
425
426 % ~www/bin/apachectl stop # (or: ~www/bin/apachectl restart)
427 % ~www/bin/apachectl start
428
429 8. Test if the simple php script is executed OK:
430
431 8a) create php script - your php scripts should be owned by the user, not root:
432
433 % su makler
434 % echo '\n"; ?> HTML too' > ~makler/WWW/test-php.php
435
436 8b) point your web browser to: http://www.klaban.torun.pl/test-php.php
437
438 Now you should see:
439 php is OK
440 HTML too
441
442 --
443 Piotr Klaban