readme.html

Ringlink 3.3

Contents

Introduction

Ringlink is a CGI Perl program that provides the tools necessary to run and administer rings of websites. You are permitted to make use of it for free, but if you intend to copy, modify or redistribute Ringlink, you must make sure that your actions are in compliance with the terms of the GNU General Public License (also included in the file LICENSE.TXT in the distribution).

If you encounter problems when installing or using Ringlink, you find a couple of tips at the homepage about how to get help. You are strongly recommended to subscribe to the Ringlink-open mailing list in order to keeping yourself posted on the development of Ringlink.

System Requirements

This is what's needed for a successful and complete installation of Ringlink:

  • A web server with CGI capabilities
  • Perl 5.005 or later with the modules included in the Perl distribution installed
  • The libwww-perl bundle (needed for the checker to work)
  • The zlib compression library and the CPAN module Compress::Zlib (needed for creating and extracting zip files)
  • A configuration that allows email messages to be sent from a script to any email address, either via a command line MTA (mail transfer agent) such as sendmail, or directly from Perl

Ringlink has proved to work fine on a variety of Unix-like and Windows platforms. A web server with CGI and a reasonably up to date (>= 5.005) Perl version, where Ringlink won't run at all, still remains to be found.

A warning, though: Ringlink makes use of a function called flock() to prevent that files get corrupted because more than one user write to them concurrently. That feature is not implemented on Windows 98 (or 95). Accordingly, running Ringlink on Windows 95/98 means an increased risk that files get corrupted.

Upgrades

Basically you should keep the files in the data directory as is, while the old program files should be exchanged for the program files of the new release. Be careful to upload all the CGI directory and Ringlink library files mentioned in the Upload and permissions section below.

However, rlconfig.pm has always been edited by the user, and sometimes one or more of the template files have as well:

rlconfig.pm System configuration file
admin.html
bottom.html
mail.html
main.html
top.html		 A user, who wants to control the generated HTML for the whole Ringlink installation in other ways than via the configuration file, should preferably modify these templates.

Sometimes it may be appropriate to keep the old copies of the just mentioned files, and make similar changes to those copies as have been made in the original files. For that reason, the upgrade note includes information about changes to the configuration file and the templates that affect how the program works.

Upgrade Note

If you are upgrading from release 2.41 or earlier:
Ringlink 2.5 and later requires (at least) version 5.005 of Perl. Do not upgrade if the Perl interpreter on your web server is older than version 5.005.

In release 3.0, the previous template files ( mainhtml.pm, admhtml.pm and mailhtml.pm ) were exchanged for five files located in a separate /templates directory. The new templates don't include any Perl code, but just HTML markup, CSS, and special template variables which Ringlink replaces with various data. Furthermore, in release 3.03 the format of the template variables was changed from [VARIABLE] to %VARIABLE%.
Consequently, previously done customization of either the *html.pm files, or of the templates with the previous template variable format, must be redone.

If you are upgrading from a pre 3.0 release of Ringlink, and provided that you have the statistics feature enabled, the first thing you need to do when the new program files are in place - and you have run langinstall.pl - is to convert the statistics files by starting admin.pl and running the "Reset stats" routine. Normally all registered hits data are reset to zero when running "Reset stats". However, running the routine once in connection with an upgrade from a version lower than 3.0 will convert the old files, while the hits data are preserved.

Significant changes in the configuration file and the template files since release 3.03:

Description Release File(s)
new variable $rlmain::autoringprevent for enabling a feature that prevents automatic (spam) additions of rings 3.3 rlconfig.pm
SMTP option default for sending emails
Unlike before, Ringlink will use the SMTP option unless the $rlmain::smtp{smtp} line has been commented out.		 3.1 rlconfig.pm
new template variable %NOINDEX% to prevent redundant search engine listings 3.04 top.html
authentication to mail server made easy when the SMTP option is selected
(the $rlmain::smtpserver variable exchanged)		 3.04 rlconfig.pm
 

Installation

You will need to do some preparations before you upload the files on your server:

To the extent you need to edit the program files, do not use anything but a plain text editor. For instance, if you would use an HTML editor, the files might be changed unintentionally, resulting in problems when trying to run the program.
The files in the /templates directory may be edited with an HTML editor, though.

  1. Perl interpreter
    If you are going to install Ringlink in a Unix environment, you must make sure that the first line of each CGI file, i.e. those with the file extension .pl, points to an appropriate Perl interpreter on your server. The correct path should be stated in the web host's documentation about CGI scripts, but that's not always the case.

    The default path: 
         #!/usr/bin/perl -T
    often works without any need to change it.

    Occasionally that path works fine with other CGI scripts, but still results in an "Internal Server Error" message when you try to run Ringlink. The explanation can then be that it points to Perl 4, and that the path to Perl 5, which is required for Ringlink, is for instance: 
         #!/usr/bin/perl5 -T
    Examples of other occurring variants are: 
         #!/usr/local/bin/perl -T
     #!/usr/local/bin/perl5 -T
    The -T switch after all the suggestions above makes Ringlink run under "taint mode", which means that Perl carries out certain security checks. So, whichever path is applicable, do not skip the -T switch.
     
  2. Path to the Ringlink library
    The directory with program specific Perl modules (the *.pm files in the distribution) is called the Ringlink library. In order to let Perl know the location of the library, the second line of each CGI file looks like this: 
         use lib 'lib';
    This command presupposes that the Ringlink library is a subdirectory to the CGI directory (i.e. the directory with the CGI files), and that the subdirectory is named lib. It will normally not need to be edited, but if the server configuration requires it, you may need to edit the command to include the full path to the Ringlink library. It may look something like this: 
         use lib 'd:/scripts/ringlink/lib';
    Note, also, that there may be other reasons why the full path is required or advisable. Compare Configuration file below.

    If you run Ringlink under mod_perl, and the location of the Ringlink library was not set via a startup.pl file at the start of the Apache server, you always need to change the second line to the full path.
     
  3. File extension
    Some systems need the file extension .cgi instead of .pl in the names of the CGI files in order to understand that the files shall be executed. If that's the case for you, you have to rename all the *.pl files to *.cgi.

    If you are able to control the server configuration in this respect, through a .htaccess file or in some other way, you may prefer not to have any extension at all. Ringlink works just fine whatever you choose, as long as you don't change the actual file names.
     
  4. Security
    There are two small .htaccess files included in the distribution. Their purpose is to prevent the files in the Ringlink library and the data directory from being readable from a browser, since some of the files in those directories will include sensitive information such as passwords and the ring members' email addresses. The .htaccess files might make a difference in this respect, but in many cases they don't:

    • They will only work on Apache servers.
    • A few Apache servers are configured not to let the server access be controlled by the users in this way.
    • On many servers with "real cgi-bins", reading access to all files and directories under the cgi-bin is prevented anyway. If that's the case for you, you can refrain from uploading the .htaccess files (even if they do no harm if you still use them).
    • If you are on a server where the .htaccess files don't work, and the access hasn't been properly restricted otherwise, you are strongly recommended to study the related security discussion in the FAQ.

  5. Configuration file
    You will need to edit the rlconfig.pm file. When doing so, you should carefully study the comments in that file together with these instructions.
    Before you edit rlconfig.pm, you have to decide in which directories the files are going to be placed. Often you'd better just follow the directory structure in the Ringlink distribution file, but if you decide otherwise, e.g. in order to address the browser access issue mentioned in the previous section, please study the following extra carefully:

    • Placing the CGI files somewhere under the cgi-bin directory is common practice, and required by some systems. If your system allows it, you can put them whereever you like, as long as you put all the 17 files in the same directory.
    • If the Ringlink library is some other directory than the subdirectory lib to the CGI directory, you need to change the use lib 'lib'; command accordingly. (See Path to the Ringlink library above.)
    • The index.html file can be put whereever you like, as long as it can be read from the browsers of your site's visitors. (Unlike the CGI files, the *.pm files, the template files, the ??.po files, the .htaccess files and the ringredirect.db file, you are also free to rename index.html to whatever you prefer. The file is intended to work as a template when you create the "homepage" of your Ringlink installation.)
    • You need to create a directory where Ringlink will store files containing the number of member sites (provided that the statistics feature is enabled.) Suggested name is sitecount, but you can choose any name. Note, though, that this directory shall be browser readable, i.e. you shall be able to access a file in it via a URL, so often it may not be put under the cgi-bin directory. Suggested location is under the directory where you put the index.html file.
    • The files with the registered ring and site info will be saved in the data directory. You can place the data directory whereever you like (and it does not necessarily need to be named data).

  6. mod_perl
    The files ringlink_mod_perl.conf and startup.pl are example files, and they are included in the distribution only as a help to them who want to run Ringlink under Apache mod_perl. (If you don't know what mod_perl is, don't bother about those files; just keep on reading.)
     
  7. Output to external program
    Via a variable in rlconfig.pm, the output from the admin routines can be directed to some other program, such as a PHP script. You'll see more about how it works, if you study the files example.php and example.css.
     
  8. Upload and permissions
    Now you are ready to create the necessary directories and upload the files.

    • The placing of the CGI directory, the data directory, and the Ringlink library is commented on in section 5. It's simpliest, and often appropriate, to follow the structure in the distribution file:
      CGI directory /cgi-bin/ringlink
      Data directory /cgi-bin/ringlink/data
      Ringlink library /cgi-bin/ringlink/lib

    • Observe the following locations of files and directories: 
      [CGI directory]/admin.pl        \
               /goto.pl         |
               /home.pl         |
               /langinstall.pl  |
               /list.pl         |
               /main.pl         |
               /newring.pl      |
               /newsite.pl      |
               /next.pl          > CGI files
               /next5.pl        |
               /prev.pl         |
               /prev5.pl        |
               /rand.pl         |
               /ringadmin.pl    |
               /search.pl       |
               /siteadmin.pl    |
               /stats.pl        /
      (Avoid keeping non-Ringlink files in the same directory as the CGI files.) 
                     /lang/de.po      \
               /lang/en.po      |
               /lang/es.po      |
               /lang/fr.po      |
               /lang/nl.po       > Language files
               /lang/ru.po      |
               /lang/sv.po      |
               /lang/tr.po      |
               /lang/zh.po      /

               /lang/mo            Directory

               /templates/admin.html  \
               /templates/bottom.html |
               /templates/mail.html    > Templates
               /templates/main.html   |
               /templates/top.html    /

[Data directory]/.htaccess
                /ringredirect.db

[Ringlink library]/.htaccess
                  /ring.pm
                  /rlconfig.pm     Config. file
                  /rlmain.pm
                  /site.pm

                  /Archive/Zip.pm

                  /Archive/Zip/Tree.pm

                  /CGI/Carp.pm

                  /File/Find.pm

                  /HTTP/BrowserDetect.pm

                  /Locale/PGetText.pm

                  /Mail/Sender.pm

                  /MIME/Base64.pm
                  /MIME/QuotedPrint.pm

                  /Parallel/ForkManager.pm

                  /RLDir/Global.pm

                  /Tie/File.pm
    • Make sure that the files are uploaded in ASCII mode. The .gif files shall be uploaded in binary mode, though.
       
    • Chmod the CGI files 755 (or whatever permissions your web hosting provider prescribes).
       
    • Ringlink must have write access to three directories:
        • the data directory
        • the mo directory
        • the directory with files containing the number of member sites
      You may need to chmod those directories 777. You should only do that, though, if your server configuration requires it, or else you unnecessarily open up for unauthorized write access. You can find out whether there is a need by simply trying to run Ringlink without changing those permissions. If they need to be changed, Ringlink will tell you.
      If you are on a shared Windows NT server, you may not have access to change the file permissions of a directory, and in that case you need to ask your web hosting provider to do it.

  9. Languages installation
    When you have uploaded all the files, and set the appropriate file permissions, the first thing you need to do is to run langinstall.pl. The easiest way to run the script is to simply request it from the browser. This will create the necessary language databases in the mo directory.

That should be it. Enjoy your Ringlink installation! And, when it's up and running, I'd appreciate if you go to the Ringlink Systems Directory and submit your installation.


January 3, 2009

Gunnar Hjalmarsson


P.S. Don't forget to backup the data files.