Wacs Installation Guide

This book is an installation guide for WACS site managers or system administrators seeking to install the WACS environment on their systems. It does assume a certain amount of familiarity with the normal processes of installing software packages on your systems; the sections on manual installation in particular also assume a basic knowledge of using the Unix operating system (or any other future supported OS platform).

To get the best from this book, you should ideally be familiar with the basic user interface of the WACS applications themselves - the WACS User Guide would be an ideal primer for this and should introduce you to many of the concepts and tools being used here. There is also no substitute for using a real WACS site to get a general feel for how things work and are laid out.

The task of installing WACS onto a new server system consists of a number of distinct steps; these are:

Some of these topics will be mentioned briefly here and will be covered in more depth in other guides in the WACS documentation set.

For copyright/licensing reasons, the example images feature sets from photoshoots by the main developer of WACS (Beaky) and a friend of his. These sets will be available on our demonstration site when that goes live. Please understand that due to the bandwidth and storage costs in running such a server on the internet, and the need to verify (as best we can) that the applicant is an adult, there is a small charge for access to the site.

If you are using either the RPM packages of the WACS applications, or the easyinstall script, and are using the default applications (MySQL in particular), the prerequisite applications will be automatically installed if they are not already present. If not, or you are using a different database (Oracle, or another like PostGres SQL), you will need to install these applications first as detailed in the table below and then follow the manual install steps:

	Note
	This feature is new in Wacs 0.8.1 and is only currently available for Fedora 8 and 9 based systems. It is our hope to extend the packaged software approach to include other platforms in a future release.

Where available for a given distribution and release, there are a number of WACS RPM or .deb packages you can make use of to install the WACS system. If you are using one of the more sophisticated package managers (yum, etc), you need only ask it to install the main wacs package and that tells the package manager what other components it needs to complete the install. This will bring in both the system packages needed - web server, database, perl libraries, etc - and the other parts of the WACS system needed for a working installation. If you are using one of the simpler package managers (rpm etc), it will complain about absense of the required packages until all the dependencies have been installed manually.

Since sourceforge.net doesn't yet seem to support YUM repos properly you will have to download the requisite WACS packages manually in order for the install to proceed.

	Warning
	In order to conform to the the Fedora packaging guidelines, quite a few of the file locations are different on the packaged version of WACS, from that created by the easyinstall script or manual process. It shouldn't cause problems, but you do need to be aware of it, particularly if moving a configuration file between releases.

The easyinstall script was our pre-packaging approach to installing WACS and is still the standard method on Ubuntu and can be used on Fedora distributions as well. At present, pending the development of a web based configurator, easyinstall is a more complete solution and the resulting WACS installation is better able to run "out of the box" with less configuration work still to do.

This the only option available for any kind of unsupported operating system platform. The instructions later in this guide take you through all of the tasks needed step by step. This does assume some basic familiarity with command line operation of the Linux/Unix environment.

The first step obviously is to download the appropriate packages for the operating system release, version and processor platform that you intend to run it on. Where a package contains noarch that means that it is suitable for any processor architecture running that distribution of Linux. Initially RPM packaged versions are available for Fedora 8 (labeled fc8) and Fedora 9 (labeled fc9), with future versions expected to support Ubuntu (using deb packages) and CENTos (and thus RHEL).

For an initial WACS installation (in this example for release 0.8.1 on an x86_64 machine running Fedora 8), you will probably want the following packages:

If you plan on making use of the download toolset to connect to subscription sites for automatic downloads (although do be aware that only a very few sites are supported so far), you will also want to get the package called wacs-download-0.8.1-1.noarch.fc8.rpm. You may also wish to download one of the two versions of the documentation package: wacs-doc-pdf-0.8.1-1.noarch.fc8.rpm or wacs-doc-html-0.8.1-1.noarch.fc8.rpm - you can always access the same documentation direct from our sourceforge web site.

Once you've downloaded the right packages, you need to gain the appropriate privileges and install the packages. There are any number of ways to do this, and you can pretty much use any of them; the example below uses the command-line based yum package manager:

# yum install --nogpgcheck wacs*.rpm
[...]
#

It is also possible to do this with the file manager, right clicking on each package file and choosing Install Package. The order on this is a bit tricky, but if you start with wacs-core and wacs-hostauth, then do the other packages and finally do the main wacs package, this should work out OK.

Once the packages, and their dependencies, have been installed please confirm that both the Apache 2 Web Server (httpd) and the MySQL Database Server (mysqld) are enabled and running. In the GNOME desktop, the System -> Administration -> Services menu will take you to the Service Configuration screen where you need to both enable and start httpd and mysqld if these are not shown as currently running. If you prefer using the command line, the following steps will do the same task:

# /sbin/service httpd start
Starting httpd:                                    [ OK ]
# /sbin/service mysqld start
Starting MySQL:                                    [ OK ]
# /sbin/chkconfig --levels 345 httpd on
# /sbin/chkconfig --levels 345 mysqld on
#

The final system configuration step before starting work on getting WACS configured is to ensure that SELinux is running in a reduced mode that will not block the WACS components from working. This is only an issue on Fedora and other Red Hat based releases at present. We hope to have this resolved by the next release of WACS. You can determine the current mode of SELinux using the sestatus command:

% /usr/sbin/sestatus
SELinux status:                 disabled
% 

To change the normal operational mode, you need to edit the file called /etc/sysconfig/selinux and change the line which reads SELINUX=enabled to either SELINUX=permissive (generates big log files and slows machine but allows for SELinux to be turned back on later more easily) or SELINUX=disabled (which disables it completely but can cause problems in the future if you want to switch it back on). You will also probably want to disable it immediately rather than doing a reboot before you can continue working on WACS - to do this, become root and run the following:

# /usr/sbin/setenforce 0
setenforce: SELinux is disabled
#

You can check this change has taken effect by using the sestatus command again.

The normal action of the RPM packages is to create a user account to hold all the datafiles, typically called simply wacs. Unless you choose to do otherwise, the images and video clips loaded into the WACS system are normally stored in the home directory of this account. For obvious reasons, the security on this directory is locked down pretty hard, so you will need to pay attention to it. In order for the system to work at all, you will need to grant access to the accompanying wacs group. This can be done with:

# chgrp g+rwxs ~wacs
# 

In addition to this, you may wish to add your own personal account to the wacs group so that you can use tools like rungq, mencoder et al on the archive directly. To do this you use the usermod command, substituting the your_name with your user name:

# usermod -a -G wacs your_name
#

	Warning
	After you've added yourself to the wacs group, the change will almost certainly not take place within the current session. You will have to log out and log back in again for your membership to be recognised. The groups command lists the groups you are currently in; when this list includes wacs, things should be working - when it does not, they won't be!

Connect to the database as the root user, giving the password as appropriate; if you've not set one the default is blank so just press return when prompted. You then create the database and the user account (once for each place you might be coming from), give access to that user account to the database, flush the contents and then quit. Here's a sample conversation - you obviously need to replace the 'myserver.example.com' with whatever your real fully qualified domain name is. You might also wish to choose a more secure password, but do remember you need to change it in /etc/wacs.d/wacs.cfg (dbpass and phpdbconnect variables) as well or it just won't work.

Here goes:

# mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 80
Server version: 5.0.45 Source distribution

Type 'help;' or \h for help. Type '\c' to clear the buffer.

mysql> CREATE DATABASE wacs;
Query OK, 1 row affected (0.03 sec)

mysql> CREATE USER 'wacs'@'myserver.example.com'
    -> IDENTIFIED BY 'wacs';
Query OK, 0 rows affected (0.08 sec)

mysql> CREATE USER 'wacs'@'myserver'
    -> IDENTIFIED BY 'wacs';
Query OK, 0 rows affected (0.00 sec)

mysql> CREATE USER 'wacs'@'localhost'
    -> IDENTIFIED BY 'wacs';
Query OK, 0 rows affected (0.00 sec)

mysql> GRANT ALL ON wacs.* TO wacs;
Query OK, 0 rows affected (0.00 sec)

mysql> COMMIT;
Query OK, 0 rows affected (0.00 sec)

mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.00 sec)

mysql> QUIT;
Bye
#

The next step is to log in as the wacs user account you just created and run the SQL scripts that create the various database tables. There are scripts provided for both MySQL 5 and Oracle 10, but this example is based upon using the MySQL 5 version. These should be found in /usr/share/wacs/creation/MySQL5.

# cd /usr/share/wacs/creation/MySQL5
# mysql -u wacs -p wacs
Enter password:
Welcome to the MySQL monitor.  Commands end withh ; or \g.
Your MySQL connection id is 82
Server version: 5.0.45 Source distribution

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> source create_mysql.sql
WACS Database Table Creation Script for MySQL
Commencing Table Creation:
  1. Photographer
Query OK, 0 rows affected (0.23 sec)

  2. Vendor
Query OK, 0 rows affected (0.01 sec)

  3. Sets
Query OK, 0 rows affected (0.01 sec)

  4. Models
Query OK, 0 rows affected (0.02 sec)

  5. Assoc
Query OK, 0 rows affected (0.01 sec)

  6. Idmap
Query OK, 0 rows affected (0.01 sec)

  7. Download
Query OK, 0 rows affected (0.00 sec)

  8. Tag
Query OK, 0 rows affected (0.01 sec)

  9. Conn
Query OK, 0 rows affected (0.02 sec)

 10. Keyword
Query OK, 0 rows affected (0.01 sec)

Tables Created - Committing Changes
Query OK, 0 rows affected (0.00 sec)

Completed.
mysql> commit;
Query OK, 0 rows affected (0.00 sec)

mysql> quit;
Bye
#

	Note
	this step is RECOMMENDED unless you know precisely what you are doing. Some commercial sites may not wish to preload this data, but should substitute their own alternatives if they want certain features to work.

	Warning
	If you changed the password in step 1. above from the default value, you NEED to have made the matching change to the configuration file before doing this step.

There are three database tables that contain standard values, plus whatever you add to them over time; these are called keywords, photographers and vendors. In this step you will be loading some initial values into these database tables. To do this you need to go to /usr/share/wacs/samples/database and run the three populate commands in the utils directory on the XML data files there.

# cd /usr/share/wacs/samples/database
# /usr/share/wacs/utils/keywordpop keywords.xml
Inserting Entry For Keyword: seethru
Inserting Entry For Keyword: nopanties
Inserting Entry For Keyword: teen
[...]
Inserting Entry For Keyword: cyc
Inserting Entry For Keyword: country
Inserting Entry For Keyword: alley
# /usr/share/wacs/utils/photpop photographers.xml
Inserting Entries For Photographer: DFR
Inserting Entries For Photographer: SWE
Inserting Entries For Photographer: MAX
[...]
Inserting Entries For Photographer: JAN
Inserting Entries For Photographer: TOB
Inserting Entries For Photographer: HBM
# /usr/share/wacs/utils/vendpop vendors.xml
Inserting Entries For Site: SE
Inserting Entries For Site: WACSD
Inserting Entries For Site: FJ
[...]
Inserting Entries For Site: AMK
Inserting Entries For Site: KPC
Inserting Entries For Site: KHA
#

	Note
	This is a very optional step but will help you if you're setting up a WACS web site for the first time.

This step loads two sample model records into the database to provide an example of how a typical model record might look. There are two such files provided in /usr/share/wacs/samples/models containing details of two models: Sabrina and Roxanne.

# cd /usr/share/wacs/samples/models
# wacsimport Sabrina-18.xml
Keyless ID map for JAFN
# wacsimport Roxanne-24.xml
#

	Note
	This step is not yet possible but will be very shortly. Please keep watching the WACS website for the announcement of our demonstration web site.

You will first need to download the sets that appeal to you, so if you select set number 14 for instance, you will need the set14.zip file and the set14.xml file. Once you have these downloaded, place them both in the same directory and run the wacsxmlin program to load the data from the XML file. The zip file will be automatically unpacked and it's contents placed in the images area.

# cd ~/Download
# wacsxmlin set14.xml
[ADD MORE DETAILS HERE!]
[...]
#

The easy bits are looked after by the upgrade command; to run this download and unpack the new distribution, and as the super user (root) run the following commands:

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

At the end of it's run, upgrade will print out some key notes about things that will require manual attention to get the new release working. The section below will give you some guidance on how these may be achieved.

The upgrade command will give you some information on what extra steps you may need to take to migrate to this release. For example, it may tell you that a new database field needs to be added to a particular model schema. In the transition from 0.5 to 0.6.x the mrace field was added, and upgrade will tell you about this. First step is to find the specification of the field from the appropriate SQL script in the creation directory, so for Oracle this will be creation/ora_models.sql. From this you will see that the field specification for Oracle is:

[...]
 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.

SELinux is an enhancement to Linux that allows potentially vulnerable services (like an internet-exposed web server) to be operated on a basis where each action the program tries to take needs to be explicitly allowed, rather than the normal allowed unless denied approach of most Unix environments. As such SELinux presents a whole new group of challenges for getting WACS to work, because we have to extend the ruleset as to what is allowed and what is not. It can be done, but it will take work and some experimentation. Whereever we have not used the Operating System supplied packages (Web Server, Database, etc), we're going to have to add those rules. The first thing to check is whether SELinux is enabled - to do this, type:

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

If it's either disabled, or is enabled but with a current mode of permissive, it's not actualling going to be causing us a problem right now. If it is enabled and enforcing, we've got to work on it. The web server process needs a security context of httpd_sys_content_t to be present on any directory it needs to access, so the first step is to add this context to each directory (outside of the normal ones) that it is likely to access. This is done with the chcon commands shown above in the manual install chapter - example:

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

In addition to the directory gaining the httpd_sys_content_t security context, any pre-existing files will also need the same, so this can be done with:

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

To inspect the security context of a file or directory, you use the -Z option to the ls command:

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

While the easyinstall script does try to set these for all the areas the web server might go (/var/run/wacs, /etc/wacs.d and the files area /home/wacs/*), any problems which are causing avc_denied messages in the dmesg output are most likely down to this issue.