WACS: Installation

Contents

• Requirements
• Obtaining WACS
• Installation
• Easy Installation
• Manual Installation
• Upgrading an existing installation
• The upgrade command
• Additional Work Needed
• Troubleshooting
• Special Notes About SELinux

• a server running a recent version of Linux/Unix with:
  • at least 256MB of RAM (512MB or more preferred)
  • a *LOT* of hard disc space available
  • connection to a suitable home network
  • the system administrator (root) password
• a suitable web server (apache 2.0 is ideal)
• a recent version of perl (perl 5.8 is ideal) and the following modules from CPAN (www.cpan.org):
• a relational database (Oracle 10g or MySQL 5 are actively supported, most others with a perl DBI interface should work).
  • Perl DBI - generic database routines
  • Perl DBD - database driver module for appropriate database eg DBD::Oracle for Oracle 10g.
  • XML::Simple - XML parser library
  • Data::Dumper - data structure debug module
  • File::Basename - file name demangler
  • Authen::SimplePam - perl and PAM authentication backend
  • MIME::Base64 - MIME acsii armour package for base 64 encoding
• php is also used by the htmlbones stuff. A separate wacs-php module is available for Web Designers.

To get the latest official release, go to the sourceforge project page and click on download. If the latest release is 0.7.3, then download wacs-0.7.3.tar.gz. Once downloaded, save it somewhere appropriate for unpacking - the installation will work without the archive, although there are sample configs and docuentation files which are not installed anywhere. If for instance you've decided to keep wacs in an "src/wacs" directory of your home directory and your web browser has placed the downloaded file on your Desktop, do:

% cd
% mkdir -p src/wacs
% cd src/wacs
% tar -xzvf ~/Desktop/wacs-0.7.3.tar.gz
x wacs-0.6.2/README
[...]
% cd wacs-0.7.3

To get the very latest version from the sourceforge subversion repository, do the following:

% cd
% mkdir -p src/wacs
% cd src
% svn co https://wacsip.svn.sourceforge.net/svnroot/wacsip/trunk wacs
[...]
% cd wacs

You do need to be aware that the MySQL network layer appears to be extremely sensitive to what the host is called. It needs to have a permanent, static name which is correctly mapped in the hosts or DNS so that hostname maps to ip address and the ip address maps back to THE SAME hostname. If this isn't the case, the final part of the installation - creating the database schemas and populating them - may well not work.

Easy Install

Other non-RPM based distributions will almost certainly fail (apart from Ubuntu which should work), but if you feed back the error messages, we'll have a go at fixing it. If using an apt-get based distribution, modifying the places where it checks for "Ubuntu" to whatever your distribution returns when you do an lsb_release -sir may well help.

To run easyinstall, become the super user (root) and issue the following commands:

# cd unpack_location/install
# ./easyinstall

Once you've done that you will need to add some model details and content to the server. There's a step-by-step guide on how to do this in the next section, getting started, and a more detailed discussion of the addmodel, addassoc and generate commands used for this in the page on console tools.

Manual Install

1. check the web server is working, install the barebones WACS index pages from the htmlbones directory of the distribution into your web tree and check you can see it. On a default Fedora Core 5 installation, this would be done with:

   # cd unpack_location
   # mkdir /var/www/html/wacs
   # cp -rp htmlbones/* /var/www/html/wacs
   #
   

2. For the perl modules, first check whether your operating system distribution includes them - Fedora Core 5 had packages called perl-DBI and perl-DBD-MySQL - so these could be simply installed with yum install perl-DBI and yum install perl-DBD-MySQL. The next easiest way to install the necessary perl modules, if they are not already present, is to use the cpan command. This can typically be done with:

   # cpan install XML::Simple
   # cpan install Data::Dumper
   # cpan install File::Basename
   # cpan install Authen::SimplePam
   #
   

3. install the Wacs.pm and WacsId.pm perl modules into the site_perl directory of your system - change the 5.8.8 to whatever your current version of perl is. [NB: note the change of case of the first letter of the perl module name from wacs.pm to Wacs.pm, and of wacsid.pm to WacsId.pm]:

   # cd unpack_location
   # cp modules/wacs.pm /usr/lib/perl5/site_perl/5.8.8/Wacs.pm
   # cp modules/wacsid.pm /usr/lib/perl5/site_perl/5.8.8/WacsId.pm
   #
   

4. install the wacs PAM (Plugable Authentication Modules) configuration into the /etc/pam.d directory. Please note that due to the way that PAM works, if your system uses shadow passwords (in the /etc/shadow file), you will need to grant read access to the /etc/shadow file to the apache web server so it can authenticate normal users. Please see the security section for more information. Create the /var/run/wacs directory where the dynamic leases files are stored and change it's ownership to apache (or whatever your web server user is).

   # cp unpack_location/security/wacs.pam /etc/pam.d/wacs
   # chown root.root /etc/pam.d/wacs
   # chmod 644 /etc/pam.d/wacs
   # chgrp apache /etc/shadow
   # chmod g+r /etc/shadow
   # mkdir /var/run/wacs
   # chown apache.apache /var/run/wacs
   #
   

   NOTE: if you run selinux (Security Enhanced Linux) on Fedora Core or Redhat (or another future distro that includes it), you will need to give apache privilege to read the /var/run/wacs directory - this can be done by changing the context of the directories and files. The commands to do this are:

   # chcon system_u:object_r:httpd_sys_content_t /var/run/wacs
   # chcon -R system_u:object_r:httpd_sys_content_t /var/run/wacs/*
   # 
   

   
   If the leases file does not exist when you first do this and you encounter problems, try using the second of these two commands again.
5. install the wacs application programs into the cgi-bin tree:

   # cd unpack_location
   # cp index/wacs* models/wacs* presentation/wacs* /var/www/cgi-bin/
   # cp retrieval/wacs* search/wacs* tag/wacs* /var/www/cgi-bin/
   # cp security/wacs* manage/wacs* /var/www/cgi-bin/
   # chmod 755 /var/www/cgi-bin/wacs*
   #
   

6. copy the applications that are just duplicate versions of existing commands and change the appropriate mode variables:

   # cd /var/www/cgi-bin
   # cp wacsmodelpage wacsmpthumbs
   # editor wacsmpthumbs
   # cp wacsimgcats wacsvidcats
   # editor wacsvidcats
   # cp wacsimgcats wacsphotcats
   # editor wacsphotcats
   # cp wacsimglist wacsvidlist
   # editor wacsvidlist
   # cp wacsnewsets wacsnewvideo
   # editor wacsnewvideo
   #
   

   edit the file and change the mode variable (thumbsmode in this case). Repeat this process for wacsimgcats becomes wacsvidcats and wacsphotcats, and so on. At the end, make sure all of the copies are executable:
   

   # cd /var/www/cgi-bin
   # chmod 755 wacs*
   

7. install the configuration file, wacs.cfg into a suitable location such as /etc/wacs.d or /usr/local/etc/wacs.d. Edit this file and make sure the key settings are right for your server, specifically the location of the image files, the location of the video files and the server name in the URLs. You will also need settings for the database user name and password you intend to use, and the environment and path locations needed for the database system you are using. For more information, see the next section on the configuration file.
8. create a suitable permanent access control list in the configuration directory choosen above, the supplied wacs.acl should provide a suitable template. This step can be skipped if you're only ever going to use lease-based access with logins. For more information on the format of the access control lists, please set the security section.
9. create a suitable owner account for the wacs data tables in your database system. The instructions here cover doing this for both MySQL and Oracle 10g, in that order:

   With MySQL 5.x, this would be done with:

   % mysql --user=root
   Welcome to the MySQL monitor.  Commands end with ; or \g.
   Your MySQL connection id is 17 to server version: 5.0.22
   
   Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
   
   mysql> create database wacs;
   
   mysql> create user 'wacs'@'myserver' identified by 'wacs';
   
   mysql> create user 'wacs'@'localhost' identified by 'wacs';
   
   mysql> grant all on wacs.* to wacs;
   
   mysql> commit;
   
   mysql> flush privileges;
   
   mysql> quit
   

   With Oracle 10g, this would be something like:

   % sqlplus
   
   SQL*Plus: Release 10.1.0.3.0 - Production on Fri Sep 29 14:53:56 2006
   
   Copyright (c) 1982, 2004, Oracle.  All rights reserved.
   
   Enter user-name: system
   Password: *******
   
   Connected to:
   Oracle Database 10g Release 10.1.0.3.0 - 64bit Production
   
   SQL> create user wacs identified by wacs;
   
   User created.
   
   SQL> grant connect, resource to wacs;
   
   Grant succeeded.
   
   SQL> alter user wacs default tablespace main quota unlimited on main;
   
   User altered.
   
   SQL> commit;
   
   Commit complete.
   
   SQL> quit
   Disconnected from Oracle Database 10g Release 10.1.0.3.0 - 64bit Production
   

   Of course there is a huge amount of variance in how any given database is installed, so you will need some knowledge about your installation. For instance, your main tablespace may not be called "main" as it is in the example.
10. login as the database user just created and run the table create SQL script from the creation directory of the wacs distribution. These scripts are called by a single creation script, the one for oracle is called create_oracle.sql, the one for MySQL is called create_mysql.sql.

    To run this on MySQL 5.1 using the account created in the step above, you would do the following:

    % cd unpack_location/creation
    % mysql --user=wacs --password=wacs wacs < create_mysql
    [...]
    %
    

    To run this on Oracle 10g using the account created in the step above, you would do the following:

    % cd unpack_location/creation
    % sqlplus wacs/wacs @create_oracle
    
    SQL*Plus: Release 10.1.0.2.0 - Production on Fri Oct 6 19:11:41 2006
    
    Copyright (c) 1982, 2004, Oracle.  All rights reserved.
    
    
    Connected to:
    Oracle Database 10g Release 10.1.0.3.0 - 64bit Production
    
    WACS Database Table Creation Script for Oracle
    
    Commencing Table Creation:
    
      1. Photographer
    
    
    Table created.
    
      2. Vendor
    
    
    Table created.
    
      3. Sets
    
    
    Table created.
    
      4. Models
    
    
    Table created.
    
      5. Assoc
    
    
    Table created.
    
      6. Idmap
    
    
    Table created.
    
      7. Download
    
    
    Table created.
    
      8. Tag
    
    
    Table created.
    
    Tables Created - Committing Changes
    
    
    Commit complete.
    
    Completed.
    
    Disconnected from Oracle Database 10g Release 10.1.0.3.0 - 64bit Production
    %
    

11. The penultimate step is to install the tools scripts, and if required the download and migrate tools, into a suitable directory, normally this would be /usr/local/bin, but it could be put within the wacs tree if desired. /usr/local/bin is usually in the default path for all the shells and thus available to user accounts without further work. To install, do:

    # cd unpack_location
    # cp -p tools/* /usr/local/bin
    # cp -p download/* /usr/local/bin
    # cp -p migrate/* /usr/local/bin
    #
    

    If you want to put it somewhere else, within the wacs home area would be fine, somewhere like /home/wacs/bin, but you will then need to add that directory to the path of your shell. For the C-shell, you would add set path=(/home/wacs/bin $path) into the .cshrc file in the home directory of your own account and those of other people who might be adding contents to the wacs server. For the Bourne style shells (sh,bash,etc), you would need to add PATH=/home/wacs/bin:$PATH and export PATH to the .profile or .bashrc files in the home directories. Once added, depending on the shell, you may need to type rehash to rescan the path for the new commands.

12. The next step is to populate the vendor database with the sample records, which can be done with:

    # cd unpack_location/populate
    # ./vendpop vendors.xml
    Inserting Entries For Site: ATKP
    Inserting Entries For Site: AMK
    Inserting Entries For Site: ATE
    Inserting Entries For Site: SE
    #
    

    Please contribute back vendor descriptions you create to be included in the next release.
13. Next we need to preload the keywords database table so that the automatic tagging will occur correctly. We do this with:

    # cd unpack_location/populate
    # ./keywordpop keywords.xml
    [...]
    #
    

14. Finally we need to load the photographers database with some initial example records, which can be done with:

    # cd unpack_location/populate
    # ./photpop photographers.xml
    [...]
    #
    

# cd unpack_location/install
# ./upgrade
WACS - Upgrade
--------------
[...]
Do you wish to continue? (y/n): y
[...]
# 

[...]
 mrace            varchar2(15),
[...]

You have three options for adding this to the database - you can choose to alter the existing schema (may leave fields in an odd order in describe); you can rename the existing table, create the new one, copy the data across and then repoint any relational constraints to the new table; or you can export your entire database, create a fresh one and import the records back in (the tools for this are incomplete in 0.6.1 but just about usuable). The former is quick and easy if the database supports it but leaves the field list in an odd order; the middle one is more work but produces a fully "normal" schema in the end but requires serious black magic if your database understands relational constraints. The final one is *VERY* experimental at this point but will improve with time.

Here is a worked example that shows how to use the alter table syntax in Oracle's SQL*Plus command interpreter to add one field called mrace:

% sqlplus
[...]
Username: wacs
Password: ****

sqlplus> alter table models
       > add ( mrace      varchar2(15) );

Table altered.
sqlplus> commit; 

Commit complete.
sqlplus> desc models
[...]
 MRACE                VARCHAR2(15)
sqlplus> quit
%

Another issue you need to be aware of is that the upgrade script will not over-write any existing files in the wacs web document tree (by default this is /var/www/html/wacs) because you may well have tailored them and we wouldn't want to overwrite those. You may well therefore need to look at what is in the htmlbones directory and copy some of the new files across into your web tree, or merge the new html into your modified version of the pages.

Troubleshooting

• Is there an error being reported?
  1. If you get the error message Can't find lsb_release in order to determine distribution and you are on a recent Fedora Core version, try running: yum install redhat-lsb and then running the installer again. Upgrades often leave out this package although it should be part of the standard operating system.
  2. If you get the error message DBI connect('wacs:myserver.myisp.com','wacs',...) failed: Can't connect to MySQL server on 'myserver.myisp.com' (110) at ./vendpop line 39 check that you can ping the hostname of your server locally. Often people don't have things set up so that a machine with an "internet name" can see itself by the same name on the local network. The above error is a symptom of this problem.
  3. Check the apache web server log file in /var/log/httpd/myserver-errorlog
  4. Check the system messages in /var/log/messages
  5. Check the output from the kernel by running dmesg (a common cause of trouble is the SELinux security mechanism, an avc_denied message in the output of dmesg is a solid clue to this - see comments below on SELinux)
• Is the web server running?
  1. If you point a web browser at the top level URL of your server, do you get a web page back, be it a distribution-supplied test page or previous pages you placed there?
  2. Can you get the wacs main page? (http://myserver/wacs/)
  3. Can you get any response from the WACS cgi-bin programs, even so much as a coloured background to a blank screen? (http://myserver/cgi-bin/wacsnewmodels)
  4. Is there an httpd process running? (ps wax | grep httpd)
  5. Is the HTTPD set to start automatically? (chkconfig --list httpd)
• Is the database server running?
  1. See if you can connect using the SQL monitor - called mysql for MySQL, sqlplus for Oracle 10g.
  2. Check for the database processes running - mysqld for MySQL, a whole cluster of oracle* and ora_* processes for Oracle 10g.

% sestatus
SELinux status:                 enabled
SELinuxfs mount:                /selinux
Current mode:                   permissive
Mode from config file:          permissive
Policy version:                 20
Policy from config file:        targeted
%

# chcon system_u:object_r:httpd_sys_content_t /var/run/wacs
#

# chcon -R system_u:object_r:httpd_sys_content_t /var/run/wacs/*
#

# ls -Z /var/run/wacs/
-rw-r--r--  apache apache system_u:object_r:httpd_var_run_t leases.acl
#