"gunzip hypernewsX.X.tar.gz" and "tar xf hypernewsX.X.tar" will untar into the directory HyperNewsX.X where X.X is the version number. The scripts are all in the .scripts subdirectory. 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. (This is basically fixed now, but people will still use the old URL.)
Make sure your tar extraction created a symbolic link from HyperNews/.scripts/.scripts to HyperNews/.scripts.
You may want to change how your server is configured so you can avoid mentioning "cgi-bin" in your URLs (or any other prefix, for that matter). For NCSA's server (and similar servers, such as Apache), add to srm.conf:
ScriptAlias /HyperNews/ <Your Directory>/HyperNews/and then restart (or kill -1) the server. (Don't 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 need to enter a special configuration for your HyperNews directory, like this:
<Directory <your path>/HyperNews> AllowOverride All Options FollowSymLinks </Directory>
For the CERN server add to httpd.conf:
# 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/* >
For the CERN server, depending on your configuration, you may also have to create .www_acl files in the HyperNews, .scripts, and SECURED directories. The setup.pl script may do this correctly for you already. It should probably contain:
* : GET,POST : @*.*.*.*For Netscape Commerce Server, add the following to the obj.conf file. You'll have to adjust things to your situation and desired HyperNews configuration. (e.g. 'pentauth.cgi' is a script you might create that is called when authentication fails - remove the Error reason line if you don't use it. The AddLog line might also fail for you.)
<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>
The document directory must always be writable by the user or group id running your httpd. If the user/group is "nobody/nogroup", you may experience problems since that user/group may have less privileges (depending on your operating system). If you leave it as "nobody/nogroup", perhaps you will need to set $hnfilemode and $hndirmode to 777. If you change the server to run as a normal user and group (such as http/www), then you could set yourself up as a member of the same group, make the file and directory modes include group writable - then manual maintenance will be easier, should it be needed.
HyperNews works with the cgiwrap program, at least in some configurations. Cgiwrap will change the user/group that runs HyperNews scripts to be the owner/group of the scripts themselves, so you can keep everything owned and writable only by you.
Be careful to disable server side includes (it's usually disabled by default for ".html" files - that's all that is needed) in the HyperNews document directory unless you have a trusted user community. Server side includes will enable users to read almost anything on your disk or execute any command simply by writing the appropriate message.
You can restrict read access for the HyperNews document directory so the server itself only allows members 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, and need not be restricted (users might get multiple authentication dialogs if you do), 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 is protected by the same .htaccess file as the .scripts directory so only administrators have access to it.
HyperNews is configured by executing a setup script in one of two ways. The first way is that you can run HyperNews/.scripts/setup.pl from a command line. (Also HyperNews/Admin/setup.pl in 1.9.4.) You must do so in a way that allows the server process to write to the HyperNews script directories during the time that you are setting up HyperNews. The server also needs to be able to continue to write to the other directories that are created to hold articles and messages. This means you must first either 'su' to the user that runs your server, or make sure you and the server user share a group and you use group writable mode for files and directories.
The result of configuring HyperNews is that directories will be created as needed to contain links to scripts, access restrictions, icons, and articles and messages, when they are created. Also, a configuration file named "hnrc" is created in your HyperNews directory that sets all the variables that control how HyperNews works. (In 1.9.4, the hnrc file is instead put in the HyperNews/Admin subdirectory.) 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.
The second way of configuring HyperNews is from a browser. Open the following URL, substituting whatever is appropriate for your installation.
http://<your.server>/HyperNews/.scripts/setup-form.pl/Include the trailing "/" if you can so the script can figure out your document root directory.
The file setup-form.cgi should be linked to setup-form.pl if your server requires a ".cgi" suffix. (In 1.9.4, the .cgi file is provided in the distribution.)
There is a simpler alternative script, called setup-short-form.pl, that you can try instead. (This short form will probably be the default in the future.)
The form that comes up describes most of the configuration options. Here is a (somewhat obsolete) sample of what this form looks like. 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 protection to the directories. It is not wise to leave it in this state, however.
After you submit the setup-form.pl form the first time, HyperNews will create the access restriction files, so you will have to authenticate as one of the administrators for subsequent attempts. New administrators, who do not have a password already, will be given new random passwords, (emailed to them if possible and displayed to you when you submit the setup-form or call setup.pl from the command line). Remember these passwords or you will be unable to even change the setup after that. Even if a later step in the setup process fails, if an administrator password is created, it will be used thereafter until it is changed by some other means. If you get totally messed up, remove the access restriction files, and any forgotten passwords in the .htpasswd file.
[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.]
You may also want to separately edit the .scripts/icons-table, to include the relationships and icons that you want. Each icon will be looked up in the $hniconsURL directory. The distribution includes a directory of Icons that might be useful. To install them, select the option on the setup form or 'setup.pl -I'.
When you consider what access permissions to allow for you 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 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 everyone, and HyperNews will detect that users have been authenticated by the server already. However, this will not 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 but see $hnGroupMembers and $hnGroupAccess. (Also see the $externalSecurity option in hnrc file.)
HyperNews 1.9.2 includes optional use of DBM password files with the Netscape server, but for many Perl installations, NDBM_File.pm is missing. A simple fix, if you are not using this option, is to comment out line 11 in change-member-lib.pl which references NDBM_File.pm. (1.9.3 avoids this problem.)
HyperNews 1.9.3 contains a bug if you you are restricting writing messages to members only. See the HyperNews Bugs page for the workaround.
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 1.9B4 is in the HyperNews/.scripts directory, not in the HyperNews directory. In 1.9B5, it is moved back to the HyperNews directory, but now the setup scripts will look for it both places. In 1.9.4, we moved to the Admin directory, where I think it will stay.)
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 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.
Problems may arise if you create a base article using one version of HyperNews - the article will remember what version was used. I believe in all cases, this should not matter, but it is best to avoid problems by creating articles with the version that will be used thereafter. We'll fix this in a future version. (I believe it is fixed already.)
A future version of HyperNews will make subgroups even easier, but for now, you have to do it manually. First install HyperNews 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). Name the directory after the group who will have access to it. 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 a copy of the hnrc file from the first installation, if you want to use that for default values. Also make a symbolic link from the ".scripts" directory to wherever the .scripts directory in the first installation was (e.g. ln -s ../HyperNews/.scripts .scripts). Then open setup-form.pl in that directory as above. In the $hnGroup field, specify the name of this group.
Since the .scripts directory is a link, running "setup.pl" or "./setup.pl" in that directory might get confused about where your parent directory is, with the appropriate hnrc file - so try ".scripts/setup.pl" instead. 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.
If you want your HyperNews documents (articles and messages) to be secure from access by other installations of the HyperNews scripts on the server or from direct server access, you should probably assign the $hndocs 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.
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. The $hnGroup subdirectory of $hnPeople will list just the members of that group. Use the edit-member.pl function for the group to add members.
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.
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.
You should also provide an instruction page for how to use HyperNews, customized for your configuration. You can start with the instructions.html included in the distribution. The setup process does not install any instructions document since you should first customize it for your configuration. Also, the icons in that document are assumed to be in the directory "/Icons". By default, the variable $instructionsURL in hnrc references our instructions at "http://union.ncsa.uiuc.edu/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.