[interchange-cvs] interchange - heins modified 2 files
interchange-cvs at icdevgroup.org
interchange-cvs at icdevgroup.org
Tue Jun 29 01:48:45 EDT 2004
User: heins
Date: 2004-06-29 05:48:42 GMT
Modified: dist/src/mod_perl2 README
Modified: dist/src/mod_perl2/Interchange Link.pm
Log:
* Add notes/docs reminding people about permissions, which may not be
as obvious to all as it is to some of us.
Revision Changes Path
1.2 +251 -233 interchange/dist/src/mod_perl2/README
rev 1.2, prev_rev 1.1
Index: README
===================================================================
RCS file: /var/cvs/interchange/dist/src/mod_perl2/README,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- README 22 Apr 2004 19:30:40 -0000 1.1
+++ README 29 Jun 2004 05:48:41 -0000 1.2
@@ -1,270 +1,288 @@
+Interchange::Link(3) User Contributed Perl Documentation Interchange::Link(3)
+
+
+
NAME
- Interchange::Link -- mod_perl 1.99/2.0 module for linking to Interchange
+ Interchange::Link -- mod_perl 1.99/2.0 module for linking to Inter-
+ change
VERSION
- $Revision: 1.1 $
+ $Revision: 1.2 $
SYNOPSIS
- <Location /foundation>
- SetHandler perl-script
- PerlResponseHandler Interchange::Link
- PerlOptions +GlobalRequest
- PerlSetVar InterchangeServer /var/run/interchange/socket
- PerlSetVar OrdinaryFileList "/foundation/images/ /foundation/dl/"
- </Location>
+ <Location /foundation>
+ SetHandler perl-script
+ PerlResponseHandler Interchange::Link
+ PerlOptions +GlobalRequest
+ PerlSetVar InterchangeServer /var/run/interchange/socket
+ PerlSetVar OrdinaryFileList "/foundation/images/ /foundation/dl/"
+ </Location>
DESCRIPTION
- Interchange::Link is designed to replace the vlink and tlink programs
- that come with Interchange. The Interchange link protocol has been
- implemented via an Apache mod_perl modules which saves us the (small)
- overhead of the execution of a CGI program.
-
- In addition, it will deliver downloadable files in a streaming fashion
- without keeping Interchange open, which cuts overhead dramatically for
- large downloadable files. See FileDeliveryBase.
+ Interchange::Link is designed to replace the vlink and tlink programs
+ that come with Interchange. The Interchange link protocol has been
+ implemented via an Apache mod_perl modules which saves us the (small)
+ overhead of the execution of a CGI program.
+
+ In addition, it will deliver downloadable files in a streaming fashion
+ without keeping Interchange open, which cuts overhead dramatically for
+ large downloadable files. See FileDeliveryBase.
- Note that this module is not compatible with Apache 1.
+ Note that this module is not compatible with Apache 1.
PREREQUISITES
- You must have mod_perl 1.99 or higher installed on your Apache. On a Red
- Hat-style Linux system, it is as simple as:
+ You must have mod_perl 1.99 or higher installed on your Apache. On a
+ Red Hat-style Linux system, it is as simple as:
- rpm -i mod_perl-1.99.XX-X.rpm
- service httpd restart
+ rpm -i mod_perl-1.99.XX-X.rpm
+ service httpd restart
- Installation of mod_perl will vary from system to system. Consult the
- mod_perl documentation. Sometimes it is as easy as
+ Installation of mod_perl will vary from system to system. Consult the
+ mod_perl documentation. Sometimes it is as easy as
- perl -MCPAN -e 'install ModPerl::Registry'
+ perl -MCPAN -e 'install ModPerl::Registry'
- but often it is not.
+ but often it is not.
- Usually you can download the package from http://perl.apache.org/ and
- follow those instructions.
+ Usually you can download the package from http://perl.apache.org/ and
+ follow those instructions.
INSTALLATION
- You must specify that Apache use mod_perl, and you must tell it where to
- find the Perl modules you want to use.
+ You must specify that Apache use mod_perl, and you must tell it where
+ to find the Perl modules you want to use.
- On a Red Hat Linux system you might copy this file to
- /usr/lib/httpd/perl/ via this procedure:
+ On a Red Hat Linux system you might copy this file to
+ /usr/lib/httpd/perl/ via this procedure:
- mkdir -p /usr/lib/httpd/perl/Interchange
- cp Link.pm /usr/lib/httpd/perl/Interchange
+ mkdir -p /usr/lib/httpd/perl/Interchange
+ cp Link.pm /usr/lib/httpd/perl/Interchange
- Then you provide a startup script that tells mod_perl where its
- libraries are:
+ Then you provide a startup script that tells mod_perl where its
+ libraries are:
- cd /usr/lib/httpd/perl
- echo "use lib qw(/usr/lib/httpd/perl);1;" > startup.pl
+ cd /usr/lib/httpd/perl
+ echo "use lib qw(/usr/lib/httpd/perl);1;" > startup.pl
- Then you can put in your /etc/httpd/conf/httpd.conf:
+ Then you can put in your /etc/httpd/conf/httpd.conf:
- PerlModule Apache2
- PerlRequire /usr/lib/httpd/perl/startup.pl
+ PerlModule Apache2
+ PerlRequire /usr/lib/httpd/perl/startup.pl
- Finally, you specify a location like:
+ Finally, you specify a location like:
- <Location /foundation>
- SetHandler perl-script
- PerlResponseHandler Interchange::Link
- PerlOptions +GlobalRequest
- PerlSetVar InterchangeServer /var/run/interchange/socket
- PerlSetVar OrdinaryFileList "/foundation/images/ /foundation/dl/"
- </Location>
+ <Location /foundation>
+ SetHandler perl-script
+ PerlResponseHandler Interchange::Link
+ PerlOptions +GlobalRequest
+ # Make sure you set SocketPerms to 0666 (or 0660 with appropriate
+ # setgid group ownership of the directory)
+ PerlSetVar InterchangeServer /var/run/interchange/socket
+ PerlSetVar OrdinaryFileList "/foundation/images/ /foundation/dl/"
+ </Location>
- Note: The Apache <Location> path should not contain a dot (.) or any
- other characters except A-Z, a-z, 0-9 or a hyphen (-), so:
+ Note: The Apache <Location> path should not contain a dot (.) or any
+ other characters except A-Z, a-z, 0-9 or a hyphen (-), so:
- <Location /shop.name> is invalid, whereas:
- <Location /shop-name> is valid.
+ <Location /shop.name> is invalid, whereas:
+ <Location /shop-name> is valid.
- The specifics of the configuration are discussed in the next section.
+ The specifics of the configuration are discussed in the next section.
CONFIGURATION
- The module understands directives set via the mod_perl "PerlSetVar"
- directive.
+ The module understands directives set via the mod_perl "PerlSetVar"
+ directive.
- InterchangeServer
- This specifies the way to contact the primary and possibly
- additionial Interchange servers. The InterchangeServer directive
- takes either a pathname to the Interchange UNIX socket or a
- host:port specification if you want to use INET mode.
-
- Normally this takes the form of:
-
- PerlSetVar InterchangeServer /var/run/interchange/socket
-
- If you want to specify more than one so that a backup server can
- provide request support in case of failure:
-
- PerlSetVar InterchangeServer "/var/run/interchange/socket 10.1.1.1:7786"
-
- The optional InterchangeServerBackup directive takes the same
- arguments, but should obviously point to a different Interchange
- server than the primary. The InterchangeServerBackup directive is
- only of any use if you have multiple Interchange servers configured
- in a clustered environment.
-
- If you want to randomly select from a series of clustered servers,
- do:
-
- PerlSetVar InterchangeServer "10.1.1.1:7786 10.1.1.2:7786 10.1.1.3:7786"
- PerlSetVar RandomServer 1
-
- Note: The Apache <Location> path should not contain a dot (.) or any
- other characters except A-Z, a-z, 0-9 or a hyphen (-), so:
-
- <Location /shop.name> is invalid, whereas:
- <Location /shop-name> is valid.
-
- Example of a UNIX mode local connection:
-
- <Location /shop>
- SetHandler perl-script
- PerlResponseHandler Interchange::Link
- PerlSetVar InterchangeServer /opt/interchange/etc/socket
- </Location>
-
- Example of INET mode local connection:
-
- <Location /shop>
- SetHandler perl-script
- PerlResponseHandler Interchange::Link
- PerlSetVar InterchangeServer localhost:7786
- </Location>
-
- UNIX mode local primary connection and INET mode remote backup
- connection:
-
- <Location /shop>
- SetHandler perl-script
- PerlResponseHandler Interchange::Link
- PerlSetVar InterchangeServer /opt/interchange/etc/socket
- PerlSetVar InterchangeServerBackup another.server.com:7786
- </Location>
-
- The default if not set is "127.0.0.1:7786".
-
- ConnectTries and ConnectRetryDelay
- The ConnectTries parameter specifies the number of connection
- attempts to make before giving up. ConnectRetryDelay specifies the
- delay, in seconds, between each retry attempt.
-
- The ConnectTries default is 10 and the ConnectRetryDelay default is
- 2 seconds. Here is an example:
-
- <Location /shop>
- SetHandler perl-script
- PerlResponseHandler Interchange::Link
- PerlSetVar ConnectTries 10
- PerlSetVar ConnectRetryDelay 1
- </Location>
-
- DropRequestList
- The DropRequestList allows a list of space-separated URI components
- to be specified. If one of the list entries is found anywhere in the
- requested URI, the request will be dropped with a 404 (not found)
- error, without the request being passed to Interchange. This
- parameter is useful for blocking known Microsoft IIS attacks like
- "Code Red", so that we don't waste any more time processing the
- (bogus) requests than we have to.
-
- <Location /shop>
- SetHandler perl-script
- PerlResponseHandler Interchange::Link
- PerlSetVar DropRequestList "/default.ida /x.ida /cmd.exe /root.exe"
- </Location>
-
- OrdinaryFileList
- The OrdinaryFileList allows a list of space-separated URI path
- components to be specified. If one of the list entries is found at
- the start of any request then that request will not be passed to
- Interchange. Instead, the file will be directly served by Apache.
- For example:
-
- <Location />
- SetHandler perl-script
- PerlResponseHandler Interchange::Link
- PerlSetVar OrdinaryFileList "/foundation/ /interchange-5/ /robots.txt"
- </Location>
-
- This will result in the following:
-
- www.example.com/index.html (handled by Interchange)
- www.example.com/ord/basket.html (handled by Interchange)
- www.example.com/foundation/images/somefile.gif (served by Apache)
- www.example.com/robots.txt (served by Apache)
-
- You should add a trailing slash to directory names to prevent, for
- instance, "/images/foo.gif" from being confused with the likes of
- "/images.html". If OrdinaryFileList was set to "/images" then both
- of those requests would be handled by Apache. If OrdinaryFileList
- was set to "/images/" then "/images/foo.gif" would be handled by
- Apache and "/images.html" would be handled by Interchange.
-
- If you're using "<Location />" then you will need a dummy
- "index.html" file in your VirtualHost's DocumentRoot directory to
- avoid permission problems assocated with the Apache directory index
- creation code.
-
- InterchangeScript
- The InterchangeScript parameter allows the SCRIPT_NAME to be
- different from the <Location>. For example:
-
- <Location /shop>
- ...
- </Location>
-
- The above will set the SCRIPT_NAME to "/shop".
-
- <Location /shop>
- ...
- PerlSetVar InterchangeScript /foo
- </Location>
-
- The above will set the SCRIPT_NAME to "/foo", instead of "/shop"
- before passing the request to Interchange.
-
- The appropriate SCRIPT_NAME must be configured into the "Catalog"
- directive in your interchange.cfg file.
-
- FileDeliveryBase
- Interchange::Link can deliver files without needing to keep
- Interchange open. To do this, you set the HTTP Status: header to
- "httpd_deliver". In Interchange 5.0 or higher you can do this by
- putting in a page:
-
- [deliver
- status=httpd_deliver
- location=directory/file.ext
- type=application/octet-stream
- ]
-
- The "FileDeliveryBase" setting determines where the file will be
- relative to. While you can set it to "/", that is not recommended as
- files like "/etc/passwd" could be delivered.
-
- The default is the document root of the Apache server. To protect
- files from being served directly by Apache, you can either put them
- under a directory at the Interchange location, or you can use normal
- Apache exclusions.
+ InterchangeServer
+ This specifies the way to contact the primary and possibly additio-
+ nial Interchange servers. The InterchangeServer directive takes
+ either a pathname to the Interchange UNIX socket or a host:port
+ specification if you want to use INET mode.
+
+ Normally this takes the form of:
+
+ PerlSetVar InterchangeServer /var/run/interchange/socket
+
+ Note that your file permissions for the socket file need to allow
+ the Apache User uid to read and write it. This usually means "Sock-
+ etPerms 0666" or in interchange.cfg. You can also do "SocketPerms
+ 0666" if you set the group of the containing directory to the
+ Apache Group value, and change the directory permissions to enable
+ the setgid bit. (That is accomplished with "chmod g+s <direc-
+ tory>".)
+
+ If you want to specify more than one so that a backup server can
+ provide request support in case of failure:
+
+ PerlSetVar InterchangeServer "/var/run/interchange/socket 10.1.1.1:7786"
+
+ The optional InterchangeServerBackup directive takes the same argu-
+ ments, but should obviously point to a different Interchange server
+ than the primary. The InterchangeServerBackup directive is only of
+ any use if you have multiple Interchange servers configured in a
+ clustered environment.
+
+ If you want to randomly select from a series of clustered servers,
+ do:
+
+ PerlSetVar InterchangeServer "10.1.1.1:7786 10.1.1.2:7786 10.1.1.3:7786"
+ PerlSetVar RandomServer 1
+
+ Note: The Apache <Location> path should not contain a dot (.) or
+ any other characters except A-Z, a-z, 0-9 or a hyphen (-), so:
+
+ <Location /shop.name> is invalid, whereas:
+ <Location /shop-name> is valid.
+
+ Example of a UNIX mode local connection:
+
+ <Location /shop>
+ SetHandler perl-script
+ PerlResponseHandler Interchange::Link
+ PerlSetVar InterchangeServer /opt/interchange/etc/socket
+ </Location>
+
+ Example of INET mode local connection:
+
+ <Location /shop>
+ SetHandler perl-script
+ PerlResponseHandler Interchange::Link
+ PerlSetVar InterchangeServer localhost:7786
+ </Location>
+
+ UNIX mode local primary connection and INET mode remote backup con-
+ nection:
+
+ <Location /shop>
+ SetHandler perl-script
+ PerlResponseHandler Interchange::Link
+ PerlSetVar InterchangeServer /opt/interchange/etc/socket
+ PerlSetVar InterchangeServerBackup another.server.com:7786
+ </Location>
+
+ The default if not set is "127.0.0.1:7786".
+
+ ConnectTries and ConnectRetryDelay
+ The ConnectTries parameter specifies the number of connection
+ attempts to make before giving up. ConnectRetryDelay specifies the
+ delay, in seconds, between each retry attempt.
+
+ The ConnectTries default is 10 and the ConnectRetryDelay default is
+ 2 seconds. Here is an example:
+
+ <Location /shop>
+ SetHandler perl-script
+ PerlResponseHandler Interchange::Link
+ PerlSetVar ConnectTries 10
+ PerlSetVar ConnectRetryDelay 1
+ </Location>
+
+ DropRequestList
+ The DropRequestList allows a list of space-separated URI components
+ to be specified. If one of the list entries is found anywhere in
+ the requested URI, the request will be dropped with a 404 (not
+ found) error, without the request being passed to Interchange.
+ This parameter is useful for blocking known Microsoft IIS attacks
+ like "Code Red", so that we don't waste any more time processing
+ the (bogus) requests than we have to.
+
+ <Location /shop>
+ SetHandler perl-script
+ PerlResponseHandler Interchange::Link
+ PerlSetVar DropRequestList "/default.ida /x.ida /cmd.exe /root.exe"
+ </Location>
+
+ OrdinaryFileList
+ The OrdinaryFileList allows a list of space-separated URI path com-
+ ponents to be specified. If one of the list entries is found at
+ the start of any request then that request will not be passed to
+ Interchange. Instead, the file will be directly served by Apache.
+ For example:
+
+ <Location />
+ SetHandler perl-script
+ PerlResponseHandler Interchange::Link
+ PerlSetVar OrdinaryFileList "/foundation/ /interchange-5/ /robots.txt"
+ </Location>
+
+ This will result in the following:
+
+ www.example.com/index.html (handled by Interchange)
+ www.example.com/ord/basket.html (handled by Interchange)
+ www.example.com/foundation/images/somefile.gif (served by Apache)
+ www.example.com/robots.txt (served by Apache)
+
+ You should add a trailing slash to directory names to prevent, for
+ instance, "/images/foo.gif" from being confused with the likes of
+ "/images.html". If OrdinaryFileList was set to "/images" then both
+ of those requests would be handled by Apache. If OrdinaryFileList
+ was set to "/images/" then "/images/foo.gif" would be handled by
+ Apache and "/images.html" would be handled by Interchange.
+
+ If you're using "<Location />" then you will need a dummy
+ "index.html" file in your VirtualHost's DocumentRoot directory to
+ avoid permission problems assocated with the Apache directory index
+ creation code.
+
+ InterchangeScript
+ The InterchangeScript parameter allows the SCRIPT_NAME to be dif-
+ ferent from the <Location>. For example:
+
+ <Location /shop>
+ ...
+ </Location>
+
+ The above will set the SCRIPT_NAME to "/shop".
+
+ <Location /shop>
+ ...
+ PerlSetVar InterchangeScript /foo
+ </Location>
+
+ The above will set the SCRIPT_NAME to "/foo", instead of "/shop"
+ before passing the request to Interchange.
+
+ The appropriate SCRIPT_NAME must be configured into the "Catalog"
+ directive in your interchange.cfg file.
+
+ FileDeliveryBase
+ Interchange::Link can deliver files without needing to keep Inter-
+ change open. To do this, you set the HTTP Status: header to
+ "httpd_deliver". In Interchange 5.0 or higher you can do this by
+ putting in a page:
+
+ [deliver
+ status=httpd_deliver
+ location=directory/file.ext
+ type=application/octet-stream
+ ]
+
+ The "FileDeliveryBase" setting determines where the file will be
+ relative to. While you can set it to "/", that is not recommended
+ as files like "/etc/passwd" could be delivered.
+
+ The default is the document root of the Apache server. To protect
+ files from being served directly by Apache, you can either put them
+ under a directory at the Interchange location, or you can use nor-
+ mal Apache exclusions.
BUGS
- Send bug reports and suggestions to the Interchange users list,
- <interchange-users at icdevgroup.org>.
+ Send bug reports and suggestions to the Interchange users list, <inter-
+ change-users at icdevgroup.org>.
COPYRIGHT AND LICENSE
- Copyright (C) 1996-2002 Red Hat, Inc.
- Copyright (C) 2002-2003 Interchange Development Group
+ Copyright (C) 1996-2002 Red Hat, Inc.
+ Copyright (C) 2002-2004 Interchange Development Group
+
+ This program is free software. You can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation. You may refer to either version 2 of the
+ License or (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of MER-
+ CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
+ Public License for more details.
+
- This program is free software. You can redistribute it and/or modify it
- under the terms of the GNU General Public License as published by the
- Free Software Foundation. You may refer to either version 2 of the
- License or (at your option) any later version.
-
- This program is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
- Public License for more details.
+perl v5.8.4 2004-06-29 Interchange::Link(3)
1.2 +13 -4 interchange/dist/src/mod_perl2/Interchange/Link.pm
rev 1.2, prev_rev 1.1
Index: Link.pm
===================================================================
RCS file: /var/cvs/interchange/dist/src/mod_perl2/Interchange/Link.pm,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Link.pm 22 Apr 2004 19:30:40 -0000 1.1
+++ Link.pm 29 Jun 2004 05:48:42 -0000 1.2
@@ -2,10 +2,10 @@
# tlink.pl: runs as a cgi program and passes request to Interchange server
#
-# $Id: Link.pm,v 1.1 2004/04/22 19:30:40 mheins Exp $
+# $Id: Link.pm,v 1.2 2004/06/29 05:48:42 mheins Exp $
#
# Copyright (C) 1996-2002 Red Hat, Inc.
-# Copyright (C) 2002-2003 Interchange Development Group
+# Copyright (C) 2002-2004 Interchange Development Group
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License as
@@ -45,7 +45,7 @@
=head1 VERSION
-$Revision: 1.1 $
+$Revision: 1.2 $
=head1 SYNOPSIS
@@ -116,6 +116,8 @@
SetHandler perl-script
PerlResponseHandler Interchange::Link
PerlOptions +GlobalRequest
+ # Make sure you set SocketPerms to 0666 (or 0660 with appropriate
+ # setgid group ownership of the directory)
PerlSetVar InterchangeServer /var/run/interchange/socket
PerlSetVar OrdinaryFileList "/foundation/images/ /foundation/dl/"
</Location>
@@ -146,6 +148,13 @@
PerlSetVar InterchangeServer /var/run/interchange/socket
+Note that your file permissions for the socket file need to allow the
+Apache User uid to read and write it. This usually means "SocketPerms
+0666" or in interchange.cfg. You can also do "SocketPerms 0666" if you
+set the group of the containing directory to the Apache Group value,
+and change the directory permissions to enable the setgid bit. (That is
+accomplished with "chmod g+s <directory>".)
+
If you want to specify more than one so that a backup server can provide
request support in case of failure:
@@ -309,7 +318,7 @@
=head1 COPYRIGHT AND LICENSE
Copyright (C) 1996-2002 Red Hat, Inc.
- Copyright (C) 2002-2003 Interchange Development Group
+ Copyright (C) 2002-2004 Interchange Development Group
This program is free software. You can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
More information about the interchange-cvs
mailing list