Section 6 Installing the LISTSERV web interface
Note: These are the “manual” instructions for installing the web interface. If you are using the .bin.gz installer kit, the kit can install these files and make the appropriate permissions changes for you.
IMPORTANT: The directories indicated in the section below are the usual defaults for Apache running under unix. If you use them, the web interface usually will work properly without much adjustment required (permissions, ownership, umask, SELinux security contexts, etc.).
If you choose to install LISTSERV's web interface in a location other than under the default Apache DocumentRoot, and/or to install the "wa" cgi in a place other than the default Apache CGI directory, you are responsible for ensuring that the appropriate permissions, ownership, umask, SELinux security context, and so forth, are properly set such that "wa" can be executed by the Apache (httpd) process, and the files LISTSERV needs for the web interface can be created and read from wherever you have decided to install them.
L-Soft support generally is unable to assist with troubleshooting problems encountered when not using the Apache default directories. Apache is not L-Soft's product and our assistance in troubleshooting the web interface in such instances is limited to recommending that file and directory permissions and so forth (as noted above) have been thoroughly checked to ensure the following:
Note: The disk location of the cgi-bin directory may be dependent on your unix OS (and even for Linux, may differ between distributions). Be sure to determine the correct location before continuing. For instance, RHEL/CentOS distributions of Linux generally place cgi-bin under /var/www/ , whereas Ubuntu seems to place it under /usr/lib . If you are unsure about this location, please consult your web server documentation and/or your operating system documentation.
- Copy the ‘wa’ executable from your source scratch directory to the CGI script directory for your web server. You can call it something else, but a short name will help keep the HTML documents small! Note that you need to make ‘wa’ run suid listserv in order to allow it to access LISTSERV archive files (the correct permissions for ‘wa’ MUST be 4755 and it MUST be owned by ‘listserv’). (See above for instructions on how to do this automatically at install time.) For instance,
-rwsr-xr-x. 1 listserv listserv 1226904 Jun 10 2019 wa
- If your system is running SELinux, you will likely as not have to tell it to allow CGI to run. To determine whether or not the feature is enabled, issue the following command at a unix command prompt:
If the response is “httpd_enable_cgi --> off”, you will have to turn it on by issuing the command
setsebool -P httpd_enable_cgi=1
and you can run the getsebool command again to see if it succeeded. If it did, the response will be “httpd_enable_cgi --> on”.
- Create a subdirectory under your web server's DocumentRoot to contain the various files LISTSERV will be creating. You should not use the DocumentRoot itself, as LISTSERV will create quite a few files! The suggested name for this subdirectory is ‘archives’. This directory MUST be rwx accessible by the ‘listserv’ user, which should be set as the owner. The group is typically 'root', and the group and other users MAY have rx access. For instance,
drwxr-xr-x. 9 listserv root 4096 Apr 22 11:00 archives
You must also create a subdirectory under the ‘archives’ directory called ‘upload’, again, rwx accessible by the ‘listserv’ user. LISTSERV and WA use this directory for virus scanning, among other things. If this directory is not created, or is not created with the proper permissions, the posting section of the interface will not work. In this case, the group usually needs to be 'apache', which also needs rwx permissions so that it can write files uploaded via the 'wa' CGI. Other users do not need access to this directory. For instance,
drwxrwx---. 2 listserv apache 21 Apr 13 16:11 upload
- Create a world-readable file called /etc/lsv-wa.config with the following two statements:
where ‘xxx’ is the absolute path to the "archives" directory you’ve just created and ‘yyy’ is the URL to this directory (preferably relative). For instance:
- Modify LISTSERV’s configuration (go.user) file to add two variables, as follows:
- WWW_ARCHIVE_CGI is the relative URL that leads to the CGI script you have just installed. Typically this will be something like ‘/cgi-bin/wa'. This is a relative URL, not an OS path name.
- WWW_ARCHIVE_DIR is the full path name to the directory you created in step 4.
- You must also export the variables. So the entire group of settings will look like this in go.user:
- For each list that you want accessible through the web interface, you must create a subdirectory in the directory you created in step 4, named like the list. For instance, if you create ‘archives/xyz-l’, the list XYZ-L will be accessible through the interface. Note that only lists with public archives are ever made accessible, for security reasons.
- Finally, restart LISTSERV. It should create a file accessible with the URL http://localhost/archives/index.html, and from there you should be able to access all the postings.
Complete information on installing the Web Archive Interface is also found in the Site Manager’s Operations Manual.
6.1 Linux and SELInux issues
(This section is RedHat/CentOS specific, but might be applicable to other Linux distributions if they use SELinux.)
If you are starting from scratch with a brand new Linux machine, you are probably going to have to change some of the SELinux firewall settings, which are generally not permissive by default for the web server.
As indicated above, there is at least one SELinux Boolean value that needs to be changed before you can use CGI. There may be other SELinux settings that need to be tweaked before you will be able to reach the web interface. Unfortunately, if SELinux is blocking you, Apache usually doesn't make that clear and simply tells you you don't have access.
Unfortunately, you may find yourself in a position where you can reach the web interface but can't do anything, like log in or create a password. That probably means you have to configure the SELinux security thing to allow httpd to connect to the network first:
sudo setsebool -P httpd_can_network_connect 1
You have to do this because the firewall is normally set to be restrictive/enforcing by default. So in order for httpd to communicate with LISTSERV, it has to be able to connect to the network. The default is to disallow this (0) so we must set it manually to 1.
If you later experience problems with WA writing to the "upload" directory, you may also need to execute
sudo semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/archives/upload'
sudo restorecon -v '/var/www/html/archives/upload'
It looks like this:
[you@yourserver cgi-bin]$ sudo semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/archives/upload'
[you@yourserver cgi-bin]$ sudo restorecon -v '/var/www/html/archives/upload'
restorecon reset /var/www/html/archives/upload context unconfined_u:object_r:httpd_sys_content_t:s0->unconfined_u:object_r:httpd_sys_rw_content_t:s0
There is a utility called "sealert" that you can use to help puzzle out SELinux problems (which are logged in the /var/log/audit/audit.log file). You install "sealert" as part of the setroubleshoot-server package:
sudo yum install setroubleshoot-server
This installs a bunch of dependencies along with it; just accept them and it will install. You can then run the utility against the audit log:
sudo sealert -a /var/log/audit/audit.log
and it prints a nice little report that helps explain what's going on and how to fix it.
Important: L-Soft neither provides or supports "sealert" or any other SELinux utility. We have found "sealert" useful in diagnosing problems with our own Linux machines, but your use of any third party utility or utilities such as are installed by setroubleshoot-server is strictly at your own risk.