2 <title 2> 3 <title 3> 99 <title 99> #____________________________________________________________________ # Got to home page: click <$http>/<$hnprefix>/cindex e.g http://hypernews.site1.org/Hypernews/site1/cindex #____________________________________________________________________ # Add password for HyperNews Owner account: The admin account <$owner_org> has empty password intially. Login to the admin account with empty password. Set a password for it as follows: Click the "Member info" from the HyperNews home page. Type in the HyperNews owner's ID defined as $owner_org in hnrc. Then click "Inquire". Type new passwords under "New Password" and "New Password again". Leave the "Current Password for HyperNews" blank. Then click "Update" to set the new password for the HyperNews owner. Click "Member list" from the home page to check the existing accounts at this point as defined by @hnAdmin in hnrc. #____________________________________________________________________ # Add member to this site For members to create forums, you need to create their accounts first. You may also need to set up their privilege on disk with something like: $ pts ad -u <uid> -g <afs-group> for AFS. Give write access of the hndocs area to all the experts with an equivalent command. #___________________________________________________________________________ # 4. Create a new forum: #__ by experts #____________________________________________________________________ # Create new forum: Experts can click "Request a New forum" in the top menu to create new forums. #____________________________________________________________________ # The check list: A. The expert should have created/edited ORG/hndocs/CATEGORIES B. The expert should have clicked 'New members' from the home page to become a member of this site or someone else created new accounts for him or her. #____________________________________________________________________ # New forum page: goto the home page http://<$http><$hnprefix>/cindex and click "Request new forum" #__ Usr ID: terryh #__ Forum Title: <whatever> #__ more than one word is ok #__ Forum Short Description: <description> #__ Forum Long Description: <descriptions...> #____________________________________________________________________ # What HyperNews Owner should do: ($owner_org in hnrc) Upon receiving the mail, do the following: $ cd Admin; ./create-forum.pl #__ must run from Admin/ #__ careful if $allowEmailIn=1 and @hnMailAnnounce is set in hnrc. The mail gateway request will be sent to the mail masters. Answer the following questions: #__ Owner Nickname: <enter the uid of the actual expert> #__ Subdirectory: <one word> #__ Forum Title: <words...> #__ Note: <one line> #__ Categories: <number> #__ see hndocs/CATEGORIES At this point the forum is up and running except the e-mail part. You may also want to check that you have write access to the forum. #__________________________________________________________________________ # 5. Setting up the e-mail gateway for a new forum: The HyperNews should be up and running now and user can post messages with the browser. To allow posting messages through e-mail and allow mail distribution, do the following steps in this section. #____________________________________________________________________ # The check list for the e-mail mechanism: Check the following items to enable the e-mail mechanism: #__ The $allowEmailIn = 1 in hnrc. #__ The $mail_admin_password in hnrc is not blank. #__ Use "Member List" from the home page to check that the 'HNMail' account has been set up properly. #__ ask the system admistrator of your machine to install perl module MIME::Parser to process e-mails in MIME format. #____________________________________________________________________ # Adding a forum's e-mail gateway to the database: The following e-mail gateways for each forum must be added to the aliases file ('/usr/lib/aliases' or '.qmail-' or procmail configuration, or similar): #____________________________________________________________ # To set it up yourself If you are setting the forum's e-mail gateway yourself, add the following entries to your local mail system's gateway alias file: #__ aliases.hnews:<forum gateway>: #__ aliases.hnews:Owner-<forum gateway>: <owner of HyperNews> #__ <form gateway>@<pipe server> #__ pipe_option:<forum gateway>@<pipe server>=<path>/.scripts/mail-incoming.pl -f /<forum> For example: aliases.hnews:hn-fusion: aliases.hnews:Owner-hn-fusion: me@slac.my.edu hn-fusion@pipe.lists.my.edu pipe_option:fn-fusion@pipe.lists.my.edu=/afs/my.edu/site/fusion/.scripts/mail-incoming.pl -f /fusion #____________________________________________________________ # To be set up by mail master If the forum's e-mail gateway is to be set up by the mail master of you computer system, first check that the @hnMailAnnounce in hnrc has been set with the mail masters' names. When the HyperNews administrator runs Admin/create-forum.pl to create a forum, a request with the forum's e-mail gateway information will be sent to the mail masters listed in @hnMailAnnounce. #____________________________________________________________________ # Completing the e-mail gateway setup: Once the new forum's e-mail gateway aliases have been added, make the following changes to hndocs/<forum>.html,urc to get this forum's e-mail gateway ready: #__ ListAddress: <forum gateway>@<server> (e.g. forum-hn@my.edu) #__ Name: <owner name> #___ full name of forum's owner #__ From: <uid> #__ the UID of forum's owner #__________________________________________________________________________ # 6. Subscribe HNMail to this forum. Normally you do not need to create new member, HN should know about the main account HNMail if it is in @hnadmin of hnrc. Just click "subscription". #__________________________________________________________________________ # 7. Some per-forum control files #__________________________________________________________________ # .notNotifyPoster (a minor subject here) The equivalence of hnrc's hnNotifyPoster is hndocs/<forum>/.notNotifyPoster. If this file exists, the poster of a message will not be notified. #____________________________________________________________ # .posterList (a minor subject here) To set up a forum that only certain people can post. Put uids into hndocs/<forum>/.posterList. Separate the uids with spaces, tabs, or linefeeds. Only members on this list are allowed to post. #__________________________________________________________________________ # 8. Debugging o Set the master switch DEBUG to 1 in the hndocs/debugOption. Turn it off as soon as the debugging is over. o If a message posted via e-mail disappears, try the following: 1. Check the hndocs/REJECTMAIL directory to see if it is rejected due to wrong e-mail address or that it is from a non-member's e-mail address when $hnMailFromMembersOnly is et to 1 in Admin/hnrc. 2. Check the error log of the Apache server (e.g. /opt/apache/logs error_log. If the relevant message is "Invalid URI in request POST HTTP/1.0", then you may have forgotten to run "./.script/setup.pl" when you switch from one major version of HyperNews to another. #__________________________________________________________________________ # 9. Migrate very old HyperNews. o The original versions of HyperNews do not use empty directories to mark threads. When migrating these very old HyperNews, some messages will be missing. o Run script 'conv-hn.pl' to add empty directories after one migrates from very old HyperNews (before 2000) to new HyperNews. #__________________________________________________________________________ # 10. Search engine. o You can set up the HyperNews first before worrying about the search engine swish-e. The search button is in the top menu. o Once the HyperNews is up the running, take a look at INSTALL-swish-e about how to install swish-e (if not installed yet) and how to create (and update) the search indexes.

This is a simple installation guide for the HyperNews. #___________________________________________________________________________ # Download the HyperNews source code: o Prepare a separate area with the same permission as the HyperNews data area so that the permission is consistent. o Download the HyperNews source code from http://hypernews.slac.stanford.edu/hn/download/ and keep it in this (code) area separated from the installation (data) area. Most of the perl scripts are in the subdirectory .script. #___________________________________________________________________________ # 1. Set up : #____________________________________________________________________ # Give write access to servers: #__ during installation only #____________________________________________________________ # For AFS file system: $ mkdir #__ create the top directory $ cd $ fs sa . write #__ access for apache server $ fs sa . write #__ access for mail server The and are normally replaced with respective AFS group that has them as member respectively. Then add the apache server and the mail server into to gain access to the directory. #_____________________________________________________ # Example: $ fs la babar:mail-server rlidwk babar:host-www rlidwk $ pts mem g-babar:host-www 134.79.16.997 #__ the apache server $ pts mem g-babar:mail-server 134.79.16.998 #__ the mail server #____________________________________________________________ # For NFS file system: $ mkdir #__ create the top directory $ cd $ chgrp . #__ set group ID for directory $ chmod g+s . #__ create new dir with same $ chmod g+w . #__ give write access to The should be the same group that the apache server uses when it runs. Examples are 'nobody', etc. One may need to use 'sudo' to execute chgrp and chmod commands. #____________________________________________________________________ # Set up .scripts: The hypernews source should reside elsewhere. $ cd $ ln -s . #__ e.g. ln -s /.scripts . #____________________________________________________________________ # Run fixperlpath: $ cd /.scripts $ edit header of fixPerlURL #__ e.g. #!/usr//bin/perl $ make fix #__ fix header for scripts #____________________________________________________________________ # Run first pass with setup.pl: $ cd #__ back to top of tree $ ./.scripts/setup.pl #__ creates hnrc in Admin/ #____________________________________________________________________ # Edit Admin/hnrc $ cd /Admin $ edit hnrc #__ edit the hnrc Just following the "<___" and edit the input fields..... #____________________________________________________________ # How to set hnrc to deal with SPAM o The recommended settings to prevent SPAM are the following: $joinSF = 1; #__ anyone can create new account $hnMailFromMembersOnly = 1; #__ only member can post via email $addResponseSF= 2; #__ only member can post thru web $requestForum= 2; #__ only member can request forum o The SPAM situation can be bad With joinSF=1 by allowing anyone to create new account. We can either set up the system to require new users to have some preexisting external accounts (e.g. SLAC, CERN, etc), or set hnrc parameters $validateEmail=1 and/or $moderateMembership=1 to utilize e-mail validation and/or account moderation. #____________________________________________________________________ # Run second pass with setup.pl: #__ sync changes in hnrc $ cd #__ go to top of tree $ ./.scripts/setup.pl #__ sync variables in hnrc $ ls -lda hndocs #__ check its existence #__ Note: since the parameters in hnrc depend on each other, whenever one makes changes to hnrc or switch between different version of .scripts for testing, it's best to rerun setup.pl, especially if the $addResponseSF has been changed. #____________________________________________________________ # How to migrate to new version of HyperNews: First download the new version of source code and see that the symlink /.scripts points to the /.scripts. Run setup.pl to merge the new parameters into Admin/hnrc, edit hnrc to change/check the values of these parameters, then run setup.pl again to synchonrize all the parameters in hnrc. #__ Note: the previous hnrc is saved as hnrc-. So one can check the migration with "diff hnrc- hnrc". #__ Note: to get the latest default of a hnrc variable, set this variable to "" in hnrc, then run setup.pl. For example, you can do this with $MIMEtype to get the latest full list of attachment file types. #____________________________________________________________________ # Remove write access from : #__ from top level only. #____________________________________________________________ # For AFS file system: $ cd #__ one level above hndocs $ fs sa . g-babar:host-www rl #__ read access for server $ fs sa . g-babar:mail-server none #__ no access, mail server #____________________________________________________________ # For NFS file system: $ cd /hndocs $ ls -lda . #__ check permission/group drwxrwsr-x ... #__ group writable, s-bit $ .scripts/dodir.pl chgrp . #__ fix group name $ .scripts/dodir.pl chmod g+ws . #__ fix write access One may need to use 'sudo' to execute dodir.pl command. These steps make sure that all subdirectories under hndocs have g+sw bit (write access for ) and belong to , which is the group that apache server sets itself to when it runs. If you do not know what should be, first use 'chmod 777' to give write access to all directories under hndocs, then run HyperNews and get the value of from files under hndocs that the apache server creates. Then turn off 777 from all directories and rerun these 2 dodir.pl steps. #___________________________________________________________________________ # 2. Add configuration to Apache server: #__ e.g /apache/httpd.conf #____________________________________________________________________ # Authentication control for / #__ full path to site area Satisfy any #__ allow all access methods AllowOverride All #__ allow .htaccess fully Options FollowSymLinks #__ allow following symlinks #____________________________________________________________________ # Edit the URL aliases. The is $hndocs in hnrc Alias /hn//Icons "/Icons" #__ Icons Alias /hn//JS "/JS" #__ Javascripts ScriptAlias /HyperNews// "///" #__ scripts Note: the /hn/ is for data while /HyperNews/ is for scripts. #____________________________________________________________________ # Reboot apache server #__ effect the configuration $ ps aux | grep opt | grep root # or equivalent command on host "root : /opt/apache2/bin/httpd -k start" $ sudo kill -USR1 #__ restart the server #___________________________________________________________________________ # 3. Ready to go: #____________________________________________________________________ # Create hndocs/CATEGORIES: #__ categories of forums Give expert write access to ORG/hndocs so that they can edit CATEGORIES. Example of "CATEGORIES": 1 2 <title 2> 3 <title 3> 99 <title 99> #____________________________________________________________________ # Got to home page: click <$http>/<$hnprefix>/cindex e.g http://hypernews.site1.org/Hypernews/site1/cindex #____________________________________________________________________ # Add password for HyperNews Owner account: The admin account <$owner_org> has empty password intially. Login to the admin account with empty password. Set a password for it as follows: Click the "Member info" from the HyperNews home page. Type in the HyperNews owner's ID defined as $owner_org in hnrc. Then click "Inquire". Type new passwords under "New Password" and "New Password again". Leave the "Current Password for HyperNews" blank. Then click "Update" to set the new password for the HyperNews owner. Click "Member list" from the home page to check the existing accounts at this point as defined by @hnAdmin in hnrc. #____________________________________________________________________ # Add member to this site For members to create forums, you need to create their accounts first. You may also need to set up their privilege on disk with something like: $ pts ad -u <uid> -g <afs-group> for AFS. Give write access of the hndocs area to all the experts with an equivalent command. #___________________________________________________________________________ # 4. Create a new forum: #__ by experts #____________________________________________________________________ # Create new forum: Experts can click "Request a New forum" in the top menu to create new forums. #____________________________________________________________________ # The check list: A. The expert should have created/edited ORG/hndocs/CATEGORIES B. The expert should have clicked 'New members' from the home page to become a member of this site or someone else created new accounts for him or her. #____________________________________________________________________ # New forum page: goto the home page http://<$http><$hnprefix>/cindex and click "Request new forum" #__ Usr ID: terryh #__ Forum Title: <whatever> #__ more than one word is ok #__ Forum Short Description: <description> #__ Forum Long Description: <descriptions...> #____________________________________________________________________ # What HyperNews Owner should do: ($owner_org in hnrc) Upon receiving the mail, do the following: $ cd Admin; ./create-forum.pl #__ must run from Admin/ #__ careful if $allowEmailIn=1 and @hnMailAnnounce is set in hnrc. The mail gateway request will be sent to the mail masters. Answer the following questions: #__ Owner Nickname: <enter the uid of the actual expert> #__ Subdirectory: <one word> #__ Forum Title: <words...> #__ Note: <one line> #__ Categories: <number> #__ see hndocs/CATEGORIES At this point the forum is up and running except the e-mail part. You may also want to check that you have write access to the forum. #__________________________________________________________________________ # 5. Setting up the e-mail gateway for a new forum: The HyperNews should be up and running now and user can post messages with the browser. To allow posting messages through e-mail and allow mail distribution, do the following steps in this section. #____________________________________________________________________ # The check list for the e-mail mechanism: Check the following items to enable the e-mail mechanism: #__ The $allowEmailIn = 1 in hnrc. #__ The $mail_admin_password in hnrc is not blank. #__ Use "Member List" from the home page to check that the 'HNMail' account has been set up properly. #__ ask the system admistrator of your machine to install perl module MIME::Parser to process e-mails in MIME format. #____________________________________________________________________ # Adding a forum's e-mail gateway to the database: The following e-mail gateways for each forum must be added to the aliases file ('/usr/lib/aliases' or '.qmail-' or procmail configuration, or similar): #____________________________________________________________ # To set it up yourself If you are setting the forum's e-mail gateway yourself, add the following entries to your local mail system's gateway alias file: #__ aliases.hnews:<forum gateway>: #__ aliases.hnews:Owner-<forum gateway>: <owner of HyperNews> #__ <form gateway>@<pipe server> #__ pipe_option:<forum gateway>@<pipe server>=<path>/.scripts/mail-incoming.pl -f /<forum> For example: aliases.hnews:hn-fusion: aliases.hnews:Owner-hn-fusion: me@slac.my.edu hn-fusion@pipe.lists.my.edu pipe_option:fn-fusion@pipe.lists.my.edu=/afs/my.edu/site/fusion/.scripts/mail-incoming.pl -f /fusion #____________________________________________________________ # To be set up by mail master If the forum's e-mail gateway is to be set up by the mail master of you computer system, first check that the @hnMailAnnounce in hnrc has been set with the mail masters' names. When the HyperNews administrator runs Admin/create-forum.pl to create a forum, a request with the forum's e-mail gateway information will be sent to the mail masters listed in @hnMailAnnounce. #____________________________________________________________________ # Completing the e-mail gateway setup: Once the new forum's e-mail gateway aliases have been added, make the following changes to hndocs/<forum>.html,urc to get this forum's e-mail gateway ready: #__ ListAddress: <forum gateway>@<server> (e.g. forum-hn@my.edu) #__ Name: <owner name> #___ full name of forum's owner #__ From: <uid> #__ the UID of forum's owner #__________________________________________________________________________ # 6. Subscribe HNMail to this forum. Normally you do not need to create new member, HN should know about the main account HNMail if it is in @hnadmin of hnrc. Just click "subscription". #__________________________________________________________________________ # 7. Some per-forum control files #__________________________________________________________________ # .notNotifyPoster (a minor subject here) The equivalence of hnrc's hnNotifyPoster is hndocs/<forum>/.notNotifyPoster. If this file exists, the poster of a message will not be notified. #____________________________________________________________ # .posterList (a minor subject here) To set up a forum that only certain people can post. Put uids into hndocs/<forum>/.posterList. Separate the uids with spaces, tabs, or linefeeds. Only members on this list are allowed to post. #__________________________________________________________________________ # 8. Debugging o Set the master switch DEBUG to 1 in the hndocs/debugOption. Turn it off as soon as the debugging is over. o If a message posted via e-mail disappears, try the following: 1. Check the hndocs/REJECTMAIL directory to see if it is rejected due to wrong e-mail address or that it is from a non-member's e-mail address when $hnMailFromMembersOnly is et to 1 in Admin/hnrc. 2. Check the error log of the Apache server (e.g. /opt/apache/logs error_log. If the relevant message is "Invalid URI in request POST HTTP/1.0", then you may have forgotten to run "./.script/setup.pl" when you switch from one major version of HyperNews to another. #__________________________________________________________________________ # 9. Migrate very old HyperNews. o The original versions of HyperNews do not use empty directories to mark threads. When migrating these very old HyperNews, some messages will be missing. o Run script 'conv-hn.pl' to add empty directories after one migrates from very old HyperNews (before 2000) to new HyperNews. #__________________________________________________________________________ # 10. Search engine. o You can set up the HyperNews first before worrying about the search engine swish-e. The search button is in the top menu. o Once the HyperNews is up the running, take a look at INSTALL-swish-e about how to install swish-e (if not installed yet) and how to create (and update) the search indexes.