These instructions are rather detailed, and many of the details may not apply to your situation. But you should skim over them just so you know what you are missing. With the state of web servers and browsers still changing rapidly, it is difficult to make systems that work in all possible situations, and so your best tool is knowledge.
Installation involves first unpacking the source code into a directory that allows CGI programs. Then you may have to fix the Perl paths in the scripts.
An important consideration is setting up the HyperNews Document Directory, referred to as $hndocs in this document and elsewhere. This is where all your forums, messages, and member info files are stored.
Then you will configure HyperNews to set the options that control how HyperNews works. You can do this via a web-based form or via direct editing of the configuration file, hnrc. When you eventually reinstall HyperNews to upgrade or fix problems, you can use a slightly easier process. You can also do Multiple Installations of Hypernews when you want different groups of users or different configuration options for sets of related forums.
See What's Next for an overview of other installation related topics, including creating forums, adding members, writing instructions. Also look in the section on Typical Problems that you might encounter while installing HyperNews.
cd .../cgi-bin gunzip hypernews.tar.gz tar xf hypernews.tar
That will create the directory cgi-bin/HyperNews### where ### is the version number. You will want to change the directory name to just "HyperNews" before announcing availability. We don't recommend you leave it with the version number intact since lots of internal URLs will have to be changed when you upgrade. (The internal dependence on the URL is basically fixed now, but people will continue to use old URLs for a long time.)
All the scripts are stored in the HyperNews###/.scripts subdirectory, which may be invisible to you (use ls -a to see it). Make sure your tar extraction created a symbolic link from HyperNews/.scripts/.scripts to HyperNews/.scripts. Use ls -F to see symbolic link files with appended '@'.
You may want to change how your server is configured so you can avoid including "cgi-bin" in your URLs (or any other prefix, for that matter). Instructions for how to do that, and other server configurations, are given in the following sections.
After HyperNews is fully configured by running the setup.pl script (don't do it now), the other scripts in the .scripts directory will be "used" via the HyperNews directory and the Admin and SECURED directories. Not all scripts are available in all those directories, depending on the access control settings you choose. There are three ways that the scripts may be used: by pointing to them with "symbolic links", which is the easiest and the default, by so-called "hard links", and by copying them. You will need to use setup.pl with the --hardlink or --copy options to use the scripts that way. Copying the scripts is more awkward to deal with if you have to make any changes to the code or if you have multiple installations, but it is necessary on some servers that restrict use of links. The hnrc file will remember which way you set this option and do the same each time you run setup.pl or use a setup form. See more about running setup.pl below.
ScriptAlias /HyperNews/ <Your Directory>/HyperNews/(You shouldn't need to make a ScriptAlias for the .scripts directory or other subdirectories of HyperNews.)
You may need to configure your server to loosen the restrictions on what scripts are allowed to do in your HyperNews directory. For example, in recent versions of Apache (1.1.1) the default for cgi-bin in access.conf is:
Options None AllowOverride NoneYou may need to enter a special configuration for your HyperNews directory, like this:
<Directory <your-path-to>/HyperNews> AllowOverride All Options FollowSymLinks </Directory>
For Apache 1.3 you may need to use 'Options +FollowSymLinks' instead, depending on how your server configures other directories.
Finally, restart (or kill -HUP) the server to cause the server to use your configuration changes.
# HyperNews Protect clauses ?? # HyperNews Exec clauses Exec /HyperNews/SECURED/* <Your Directory>/HyperNews/SECURED/* Exec /HyperNews/.scripts/* <Your Directory>/HyperNews/.scripts/* Exec /HyperNews/* <Your Directory>/HyperNews/* # A version of the following line is already in the .conf file, # and must remain at the end. <Pass /* /local/Web/* >
Depending on your configuration, you may also have to create .www_acl files in the HyperNews, .scripts, SECURED, and Admin directories. The setup.pl script may do this correctly for you already. It should probably contain:
* : GET,POST : @*.*.*.*Note that you cannot use email addresses as userids with the CERN server. So create an initial admin userid that is not an email address, then later use the password it displays to go change the member info to add an email address if you wish.
<Object ppath="/usr/ns-home/cgi-bin/HyperNews/SECURED/*"> AuthTrans fn="basic-ncsa" userfile="/usr/local/etc/httpd/htdocs/hn/hnpeople/.htpasswd" auth-type="basic" PathCheck fn="require-auth" realm="HyperNews" auth-type="basic" auth-user="*" Error reason="Unauthorized" fn="query-handler" path="/usr/ns-home/cgi-bin/pentauth.cgi" AddLog fn="common-log" name="log0" </Object>
But we don't recommend you do the above if your server is shared by many other users or virtual hosts. This is because HyperNews writes its data onto disk, and so other users on the same system might otherwise have read or write access. Instead, use some setuid mechanism, described in the following sections.
There are two distinct sets of users to keep in mind, by the way. Unix users are one set; we are particularly concerned with the person who installs HyperNews via some Unix account (called the "installer" from now on) and the "user" (e.g. httpd) who runs the server. There may be many other Unix users on your machine that may have read, write, or execute permission on your files and directories. The other set of users are the people that access HyperNews via the web. This set of Web users includes all the users who identify themselves with User IDs as well as the anonymous users with no User IDs. It also includes the HyperNews administrators with special administrative powers. The Unix users and Web users are unrelated to each other although they may just happen to have the same identifiers used by the same people in some cases. Similarly, there are two different unrelated sets of groups: Unix groups and HyperNews or Web groups. The Web Server Groups are not used by HyperNews, except in old versions - instead, HyperNews defines and uses its own group mechanism.
If you wish to protect the privacy of messages, membership information, and all HyperNews data, and thus prevent unauthorized use, we need to arrange to change the Unix ownership of the files as they are written so they can only be read or written by the installer. The problem is that the server is typically run by another user, such as root, nobody, httpd, or something else. One solution is live with it as described above. The better solution is to arrange to have HyperNews be run as the same user who owns the scripts, namely the installer. Given this motivation, we can now describe several possible ways to make this happen.
To use cgiwrap (at least version 3.6.3) with HyperNews symbolic links, you will need to make sure that it is compiled using the --without-check-symlink option. Either that, or don't use symbolic links with HyperNews. (See setup.pl command line options below.)
The following instructions assume you are installing HyperNews in a cgi-bin directory that is accessed via your login ID. For example, the URL for HyperNews might be /loginID/cgi-bin/HyperNews, where loginID is replaced by your login ID. Or if you have a virtual (or real) domain, the URL might simply be http://your.domain/cgi-bin/HyperNews. If necessary, you might be able to make a symbolic link from cgi-bin in your personal public_html directory to the place where HyperNews is installed. There are other ways that cgiwrap can be used with different ways of configuring the server and installing HyperNews, but you're on your own for now.
If you are using server-based authentication (i.e. not using the HyperNews form-based $manualSecurity option), we need to do a bit more configuration. To get the server to authenticate users when using the cgiwrap program, we need to arrange that cgiwrap is accessed from inside the HyperNews subdirectories protected by the .htaccess files - this will cause the server's authentication (and access restrictions) to be applied. Here is what must be done:
cd cgi-bin ln -s /full/path/to/cgiwrap cgiwrapNext run `make cgiwrap` from the .scripts directory - this adds links from the HyperNews directory and subdirectories to this cgiwrap above your HyperNews directory. (You will need to run it from the command line only once per installation.) It also adds links for cgiwrap.cgi and cgiwrapd. (You may need to use cgiwrap.cgi instead of plain cgiwrap if your server requires all CGI programs to end in ".cgi". The cgiwrapd form is used for debugging, but only if ".cgi" is not also required.)
With that done, now we could access one of the scripts, say edit-article.pl, with the following URL:
http://your.domain/cgi-bin/HyperNews/SECURED/cgiwrap/<your-login>/HyperNews/SECURED/edit-article.plNote that the "/HyperNews/SECURED" appears twice in the URL. We can hide the use of cgiwrap and all these internal details by using a few ScriptAlias directives added to your server configuration.
ScriptAlias /HyperNews/SECURED/ /full/path/to/HyperNews/SECURED/cgiwrap/<your-login>/HyperNews/SECURED/ ScriptAlias /HyperNews/Admin/ /full/path/to/HyperNews/Admin/cgiwrap/<your-login>/HyperNews/Admin/ ScriptAlias /HyperNews/.scripts/ /full/path/to/HyperNews/.scripts/cgiwrap/<your-login>/HyperNews/.scripts/ ScriptAlias /HyperNews/ /full/path/to/HyperNews/cgiwrap/<your-login>/HyperNews/Then your URL would be simplified to just:
http://your.domain/cgi-bin/HyperNews/SECURED/edit-article.plIf you are using a version of Apache that supports the ScriptAliasMatch directive, you can simplify the above set of ScriptAlias directives to a single line:
ScriptAliasMatch ^/HyperNews(/SECURED|/Admin|/\.scripts)?/(.*) /full/path/to/HyperNews$1/cgiwrap/liberte/HyperNews$1/$2If you need to debug how cgiwrap is being used, add the following alias, and use HyperNewsDebug instead of HyperNews.
ScriptAliasMatch ^/HyperNewsDebug(/SECURED|/Admin|/\.scripts)?/(.*) /full/path/to/HyperNews$1/cgiwrapd/liberte/HyperNews$1/$2
You might want to restrict read access for the HyperNews document directory so the server only allows HyperNews members or admin to read the files directly. HyperNews setup will do this for you if you make reading restricted to members only.
The Icons directory needs to be accessible via the server, and it should probably not be restricted (you don't want users to get an authentication dialog for each icon), so you should probably put it somewhere outside of the $hndocs directory if the document directory is restricted.
Bug: If you change your $hndocs directory between multiple calls to setup, the setup process may not change the $hniconsURL accordingly so it will not point to the same directory as $hnicons. For now, just fix it manually in the hnrc file.
The hnpeople directory (in your $hndocs directory by default), where all the member information goes, is protected by the same .htaccess file as the HyperNews/.scripts directory so only administrators have access to it. The HyperNews/SECURED directory is protected by hnpeople/.htgroupmembers, and you can also use this in other directories just by linking to it.
The result of configuring HyperNews is that directories will be created as needed to contain links to scripts, access restrictions, icons, forums and messages. Also, a configuration file named "hnrc" is created in your HyperNews/Admin directory that sets all the variables that control how HyperNews works.
HyperNews is configured by executing a setup script in one of two ways. The first way is via the command line: HyperNews/.scripts/setup.pl. (Also HyperNews/Admin/setup.pl after version 1.9.4.) The second way, with a browser, is discussed below.
The first time you run setup.pl, if no hnrc file exists, one will be created with default values. Edit this file to set the values to what you want and run setup.pl again. The comments in the hnrc file are probably not sufficient for you to know what to set the values to. It would be best for you to use the second way of configuring HyperNews, described next, at least to read the documentation it contains. But there are several configuration options only available in the hnrc file, at least for now.
The setup.pl script also has several options that can be used from the command line. To see a description of these, run setup.pl --help.
http://<your.server>/HyperNews/.scripts/setup-form.pl/Include the trailing "/" so the script can try to figure out your document root directory.
If you see code instead of the HTML text and form that was supposed to result from executing the code, then you need to do something to make the server execute the code instead. You might need to change your server configuration regarding cgi-bin executables; see the earlier discussion on that issue. An alternative is to use setup-form.cgi instead; it is linked to setup-form.pl, so you can use that instead if your server requires a ".cgi" suffix.
Here is a (somewhat obsolete) sample of what the setup-form looks like.
The setup-form provides many of the common configuration options, but there is a simpler form with fewer option available, called setup-short-form.pl, that you may try instead.
After you fill out the form and submit it, several things will be checked, and if all is OK, several things will be created or updated. The results of that process will be displayed to you.
You will need to make your HyperNews cgi directory and the .scripts and Admin subdirectory writable by the server temporarily before you submit the form, so it can build the appropriate links to the scripts and add access restrictions to the directories. However, it is not wise to leave the directories in this writable state after you are done configuring HyperNews.
After you submit the setup-form.pl form the first time (or after you run setup.pl from the command line for a second time), HyperNews will create the access restriction files, so you will have to authenticate as one of the administrators for subsequent attempts. New administrators, those who do not have a password already, will be given empty passwords. Remember to change these passwords. If you forget all your administrator passwords, the easiest thing to do is to remove the access restriction files (.htaccess) in the .scripts directory and other directories, if necessary. Then use edit-member.pl to change the passwords.
[The CERN server requires that user IDs must be nicknames only - no email addresses (or no dots in the user ID anyway). (This is not checked by HyperNews, unfortunately.) So the passwords that will be generated for new administrators will not be emailed to them - even more reason to remember the passwords when they are given to you. The CERN server is no longer recommended anyway.]
When you consider what access permissions to allow for your installation, note that there is a conflict in allowing anyone to join while only allowing members to read. We wanted to leave the 'get' script where it is whether or not there are access restrictions, so you would not have to change URLs if you change the access restrictions from public to private or vice versa. Therefore, when reading is restricted to members only, everything is restricted including the joining of new members. You can work around this problem by manually putting links to the edit-member.pl and change-member.pl scripts in another directory that does not have access restrictions, and also make links in that directory to the hnrc file and to the .scripts directory.
If your server restricts access independent of HyperNews, you might be able to use that with HyperNews. If the restriction is by domain, then the server only knows that users come from the specified domain(s). But if the restriction is to a set of users, HyperNews can use the info for its authentication. Just configure HyperNews to allow reading, etc by anyone, and HyperNews will detect that users have been authenticated by the server already. However, server authentication will not by itself provide personal info, such as the user's name and home page, and more importantly, whether the user is an administrator. So you will have to use the edit-member.pl form to join members using the same user IDs. Administrators are identified only in the setup process.
If you want HyperNews to manage the same password file as is used outside of HyperNews, you should probably be able to do this by configuring HyperNews to use the same file. See $hnPassword in the hnrc file. Managing the group files is a different story; HyperNews checks whether a user is a group member itself rather than using the server's mechanism. (Also see the $externalSecurity option in hnrc file.)
HyperNews includes optional use of DBM password files with the Netscape server.
You may want to copy the hnrc file from the old version over to the new version before running the configuration script; this way you will get whatever settings were used previously by default. (Note that the location of hnrc in older versions was in the HyperNews or HyperNews/.scripts directory. The setup scripts will look for it both old places. In 1.9.4, we moved it to the Admin directory, where I think it will stay.)
If you are using cgiwrap, you will need to make a new link to it in the new installation.
When you are satisfied that the new installation works, then just swap it in by changing directory names (e.g. mv HyperNews HyperNews.old; mv HyperNews1.9.6 HyperNews). (Actually, you probably don't want to do this casually because someone might be in the middle of an operation such as writing a message; this could be a problem when security options change or the names of scripts or form fields change. To be extra safe, shut your server down temporarily.) Let us know if you have any problems doing this.
When installing HyperNews for the first time, it is typically more work because many issues need to be worked out. It would be nice if an autoconfig or Perl Makefile.PL installation process could be used, but I don't know one that has been adapted to know about CGI programs and web servers. Please let me know if you come across one.
Nevertheless, I use the following procedure:
cd HyperNews###/.scripts # Edit fixPerlPath, then do: make fix make setup # Edit Admin/hnrc, fix other things, such as hndocs, then do: make setup make installWhen reinstalling HyperNews, the process is much simpler if the current configuration can be reused. The following assumes that the current installation is in HyperNews in the same directory as the new installation. After untarring into the new HyperNews### directory (### is the version number), I do:
cd HyperNews###/.scripts make copyconf # This copies configuration info from HyperNews. make fix make setup # Repeat as needed to change configuration. make installAfter the make install, the old HyperNews directory is renamed HyperNews.old (after removing any previous HyperNews.old) and the HyperNews### directory is moved to HyperNews. Note that your current directory has been changed in the process. You can undo the install step, in case you need to go back and fix something, with:
make undoinstallIf instead of installing a new version, you want to make a copy of the current installation that is in HyperNews, you can do the following, as long as there is not already a HyperNews### directory:
cd HyperNews/.scripts make clone make copyconf make setup make installTo make a distribution copy of HyperNews, I do:
make dist # Create hypernews.tar.gz make docs # Create hndocs.tar.gz
A future version of HyperNews will make multiple installations even easier, but for now, you have to do it manually. First install HyperNews normally as described above with the group (specified in $hnGroup) having no name. This will establish the "root" level and corresponding root level administrators.
Then, for each new installation, make a new directory. This directory may be anywhere, and in particular, it may be a subdirectory of the HyperNews directory (though that might make upgrading HyperNews more complex because you cannot just replace the HyperNews directory). You may want to add more ScriptAlias directives to your server configuration (or whatever is appropriate for your server) for these additional script directories.
In the directory for an installation, make an Admin subdirectory, and
copy the hnrc file from the first installation into Admin, if you want
to use that for default configuration. What you change in the
configuration of this installation depends on why you are doing a
separate installation - change whatever is appropriate and share the
rest. Make a symbolic link from the ".scripts" subdirectory to
wherever the .scripts directory in the first installation was
(e.g.
If you are running setup.pl from the command line, since the .scripts directory is a link, running "setup.pl" or "./setup.pl" in that directory will assume you mean the root installation. So try ".scripts/setup.pl" or "Admin/setup.pl" instead, starting from the correct parent directory. If you use the setup form, and you link all the subgroup .scripts directories to the root level .scripts, then the administrators for the root level are the only ones who can setup subgroups.
For example, let's make an installation of HyperNews for a group called 'Staff. We already have 'HyperNews' installed in one directory as the 'root' installation, and we want the Staff installation at the same level. Do the following:
$ cd cgi-bin $ mkdir Staff $ ls -F HyperNews/ Staff/ $ cd Staff $ mkdir Admin $ ln -s ../HyperNews/.scripts .scripts $ ls -aF ./ ../ .scripts@ Admin/ $ cp ../HyperNews/Admin/hnrc Admin $ vi Admin/hnrc # Change configuration of this installation. $ ./Admin/setup.pl # Execute setup.pl from the command line.If you want your HyperNews documents (forums and messages) to be secure from access by other installations of HyperNews (possibly other groups of users), or from direct server access, you should probably assign the $hndocs directory for each installation to a different directory rather than share the same directory or nest the directories. In each directory, include an appropriate .htaccess file (or whatever your server calls it) to restrict access. HyperNews scripts don't look at the .htaccess file for the documents they access (only the server itself does), and that's why you don't want to nest the document directories.
You can use the .htaccess files that HyperNews already produces by linking to them. To protect your "hn" directory, do:
cd hn; ln -s hnpeople/Admin/.htgroupaccess .htaccess
If you restrict access to your $hndocs directory, you should probably also change $hnicons and $hniconsURL to be outside of the $hndocs directory then, so they will remain publically accessible, and sharable. The Icons should probably *not* be protected, otherwise people may get authentication requests for the first 4 icons (if the brower makes 4 simultaneous requests).
To share membership files across installations, and thus share password files, in each installation, simply assign the $hnPeople variable to the same directory. You should probably move the $hnPeople directory out of the $hndocs directory for this purpose. (Note that the default value for $hnPeople in the setup-form is relative to the $hndocs.) The $hnGroup subdirectory of $hnPeople will list only the members of that group. Use the edit-member.pl function for the group to add members to that group. Adding a member to a group also adds the same member to parent levels all the way up to the root.
Since adding a new group requires some manual installation in the file system, there is no risk that anyone but the installer could do so. In the future, we will supply a script to do this more automatically, and then only the admin for a group would be allowed to add a subgroup.
To enable this use of cookies, you must edit your hnrc file to change the $UseCookies and $HNCookiePassword variables. (You don't need to run setup.pl after making this change.) If you set $UseCookies to 'sometimes', each user will have the option to use cookes for their own access.
You'll also want to add some members via your browser using the edit-member.pl program. See the instructions for becoming a member. But as an administrator, you should be aware of more of the security issues regarding membership.
In the current version of HyperNews, the only way to remove members once you have added them is manually. To do that, go into your hnpeople directory and remove the files corresponding to members you want to remove. Also remove them from the .htpasswd file.
HyperNews provides support for bidirectional email. If you want to allow outgoing email only or also incoming email, see that page for documentation.
A number of additional customizations are available in the hnrc file. One that is frequently asked for is reversing the order of the messages. See $reverseMessages for that.
By default, the variable $instructionsURL in hnrc references our instructions at " http://www.hypernews.org/HyperNews/get/hypernews/instructions.html". The $instructionsURL variable could point to either a HyperNews page that you create, or to a normal page. Or you can point to our instructions, but I would prefer that you not do that because users often get lost on my server thinking they are on your server. On the other hand, if you don't customize your instructions, you might as well point to our instructions.
But please do not just copy the pages of instruction forums themselves; although it will appear to be a working forum to users, the copy you get will not be updated even though the controls will work to add messages to the HyperNews.org instruction forums. Everyone will be confused.
If you get a permission problem saying that some file could not be written, or perhaps files are silently not being written, this is probably a permission problem. Most likely, the user:group running your server is incompatible with the owner:group of the files or directories it is trying to modify. See the section above on setting up your Documents Directory. The same issues apply to the HyperNews program directory and subdirectories, although after installation is completed, these directories and script files should not be modified.
If you get an error about an UnknownUser when you try to create a forum, this is probably because the server is not properly authenticating you. Check how your server is set up to do authentication and then check whether HyperNews has set up the access files correctly to use the server's authentication. The HyperNews programs should see the REMOTE_USER if all is correct.
If you get an error when adding a message but the message gets added anyway (do a reload to find out), one cause for this is that outgoing email is failing for some reason. One reason it fails is that you have not set up an email alias for the address named by your $mail_to variable, 'HyperNews' by default. See your hnrc file for details. You can also fix this by turning off email subscription and notification either in the setup form or in the hnrc file.
Another common failure is that after creating a forum, the browser waits for a long time, or returns immediately with "No data". It is supposed to show you the forum that was created. Or you may notice this same kind of problem in a couple other places in HyperNews. This problem is due to the lack of support by some servers for relative indirections. There is a work around described on the bugs page. Version 1.9.6 avoids the problem altogether.