This file contains instructions for installing WIST. The 'QUICK START' session shows how to immediately perform an installation using the default, "out-of-the-box" configuration. Following these instructions are details of the configuration parameters and instructions on how to edit them to customize the configuration to suit your needs. QUICK START (using default configuration) ========================================= 0) See Requirements section of README.txt, and make sure all the prerequisites are installed. 1) Configure memcached per instructions. Use the default port of 11211. Add memcached to your startup scripts. 2) Unpack the tarball somewhere outside of /opt/wist or /opt/wist-1.1. The package is not designed for in-place installation. 3) Create required directories mkdir /opt/wist-1.1 mkdir /opt/pcapstore_filestore 4) Set permissions on /opt/pcapstore_filestore to be readable and writable by your web server per local security policy 5) If using postgresql, edit "Makefile" and "config.sitedef" and replace "mysql" with "postgresql" 6) type 'make' from the top-level directory (i.e., the one that contains this file INSTALL.txt) 7) Set ownership and permissions of all CGI scripts in the directory /opt/wist-1.1/www/cgi-bin to be executable by the Web server per local security policy. 8) Configure database. See 8a for mysql or 8b for postgresql. 8a) Configure mysql (if not using postgresql) - you must enable InnoDB and MyISAM support a) create a database to store WIST internal data and form tables CREATE DATABASE wistdb; b) grant the appropriate privileges for the WIST user GRANT SELECT, INSERT, UPDATE ON wistdb.* TO wistapp@localhost IDENTIFIED BY 'wistpass'; c) create helper tables and grant privileges mysql -u root -p wistdb < wist/mysql/sessionVars.sql mysql -u root -p wistdb < wist/mysql/user.sql mysql -u root -p wistdb < wist/mysql/enumgroup.sql mysql -u root -p wistdb < wist/mysql/enumvalue.sql mysql -u root -p wistdb < pcapstore/mysql/pcs_tables_create.sql mysql -u root -p wistdb < pcapstore/mysql/pcs_tables_addcon.sql GRANT SELECT, INSERT, UPDATE, DELETE ON wistdb.sessionVars TO wistapp@localhost; d) save privileges FLUSH PRIVILEGES; 8b) Configure postgresql (if not using mysql) a) create a schema (not a database, since we need to access these tables at the same time as we're accessing the ones with our data) to store WIST internal data and form tables: CREATE SCHEMA wistdb; Note that our examples assume both the database and schema are named "wistdb" but if you'll be using another database for your actual data, create the schema "wistdb" under it. b) grant the appropriate privileges for the WIST user CREATE USER wistapp WITH UNENCRYPTED PASSWORD 'wistpass'; GRANT ALL PRIVILEGES ON SCHEMA wistdb TO wistapp; Be sure that user authentication is set to "trust" rather than "ident" for local connections, so you can connect as this user using password-based authentication. c) create helper tables and grant privileges psql -U wistapp -W wistdb < wist/psql/sessionVars.sql psql -U wistapp -W wistdb < wist/psql/user.sql psql -U wistapp -W wistdb < wist/psql/enumgroup.sql psql -U wistapp -W wistdb < wist/psql/enumvalue.sql psql -U wistapp -W wistdb < pcapstore/psql/pcs_tables_create.sql psql -U wistapp -W wistdb < pcapstore/psql/pcs_tables_addcon.sql 9) configure apache; Add the following to your apache2 configuration file (e.g., /etc/apache2/sites-available/default) ScriptAlias /wist/cgi-bin/ "/opt/wist/www/cgi-bin/" Alias /wist/ "/opt/wist/www/" 10) WIST should now be configured. Use WIST Builder to start building simple workflows (all mysql data for the workflow must exist in a single innodb table). More complex workflows must be written manually using the instructions in docs/wist.txt. http://yourserver/wist/cgi-bin/wistBuilder The templates produced by WIST Builder should be placed in: /opt/wist/templates/wistForms/ For example, if you have a workflow called myworkflow, it should be in: /opt/wist/templates/wistForms/myworkflow.wf You can then upload data at: http://yourserver/wist/cgi-bin/wist/myworkflow/ or browse existing data at: http://yourserver/wist/cgi-bin/wistBrowse/myworkflow/ TROUBLESHOOTING =============== * Note that the installation script is relatively timid and does not automatically create the root directory for WIST installation, nor does it create the root of the Pcapstore file storage tree used to store WIST uploads. If they do not already exist, they must be created by hand. If you edit the default configuration, make sure the directories identified by the variables 'WISTINSTALLDIR' and 'pcapstore_filestore_root' are already created and have the appropriate permissions (in particular, make sure that 'pcapstore_filestore_root' is readable and writable by the userid used by the Web server). * Note that WIST in general and WIST Builder in particular require Javascript enabled. If you do not see a 'Continue' button when using WIST Builder make sure you have not disabled Javascript or blocked it using a plugin (i.e. Noscript or Adblock Plus for Firefox). * If you have trouble with uploading images, try testing Pcapstore individually. A simple test script has been provided in 'pcapstore/client-perl-lib/originaltest_clientside.pl'. Edit the script such that the 'use lib' line refers to PCAPSTORE_CLIPERLLIB and run it. If you have ImageMagick installed and available in the standard executable path, you should see a picture of a monkey holding a baseball bat if the test succeeds. * If you see an error message asking 'is archive dir available?' then that usually means there is a problem accessing the file storage tree. Make sure that you created the directory defined as 'pcapstore_filestore_root' and that the permissions are set appropriately such that the Web server can read and write to it. * If WIST Builder can't connect to the database with the username and password you configured WIST to use (e.g., wistapp, wistpass), look for the following in your apache2 error log: [error] [client yourclient] DBI connect(':localhost;mysql_local_infile=1','wistapp',...) failed: Client does not support authentication protocol requested by server; consider upgrading MySQL client at /opt/wist/lib/DB.pm line 80, referer: http://yourserver/wist/cgi-bin/wistBuilder In that case, your DBD::mysql perl module is linked against an older version of the mysql client libraries. Make sure you have a more recent version of these libraries; for example, under Debian, the package is called libmysqlclient15-dev. Then, try starting CPAN, and forcing a re-compilation and re-install of the DBD::mysql module. DEFAULT CONFIGURATION DETAILS AND EDITING INSTRUCTIONS ====================================================== CONFIGURATION OVERVIEW ====================== The WIST package is made up of the WIST system itself (in the subdirectory 'wist'), the file storage engine used by WIST (in the 'Pcapstore' subdirectory) and an installation utility to help configure the setup and deployment of these components (in the subdirectory 'sitedefedit'). The installation process consists of editing a master configuration file used by WIST, creating the necessary directory structures for the scripts, libraries and support files, and copying and editing script and library files. This whole process is driven by the top-level Makefile with the help of a master configuration file ('config.sitedef'). By default the settings of 'config.sitedef' define a simplified configuration to make installation as simple as possible for new users. However, by editing variable assignments in the Makefile and 'config.sitedef' one can customize the installation to suit local needs. The variables defined in the Makefile identify paths where files are actually installed as well as the location of the master parameter file used by the 'sitedefedit' tool to perform script editing. Most of the other parameters are defined in the 'config.sitedef' file, including database parameters and URL paths for CGI scripts. Note that the 'config.sitedef' file is not used after installation is complete. It is merely used to create the initial 'wist.conf', the WIST configuration file, and the code for CGI scripts and libraries while performing the initial installation. WIST may be customized after installation by editing 'wist.conf' directly. If experienced users wish to bypass the automated generation of 'wist.conf', they may either wish to reuse a 'wist.conf' they already have or use 'wist.exampleconf', which is nothing more than a copy of 'wist.conf' for hand editing. To install a custom 'wist.conf' file, simply replace the auto-generated 'wist.conf' file after installation is complete. MAKEFILE SETTINGS ================= Several variables in the Makefile define the filesystem paths where files for WIST and Pcapstore are actually installed. This includes the installation location and symbolic link path for WIST. 'WISTINSTALLDIR' : The absolute path where WIST is to be installed. This defines where the actual installation is performed, though usually it will be reached via a symbolic link defined by 'WISTPATH'. 'WISTPATH' : The absolute path for the logical location of WIST. The symbolic link will be created here which defines the conventional path for WIST, should one wish to upgrade WIST and keep the previous version around. 'PCAPSTORE_SRVCGIROOT' : Location for Pcapstore CGI scripts. The CGI scripts for Pcapstore implement a service interface for storing and retrieving files used by clients (like WIST). 'PCAPSTORE_SRVPERLLIB' : Absolute path for server libraries used internally by Pcapstore. These are to be installed only on the host where Pcapstore files are physically stored. 'PCAPSTORE_CLIPERLLIB' : Absolute path for client libraries used by Pcapstore clients, including WIST. This should be installed on the system hosting WIST (and optionally other systems where programs will use the Pcapstore.pm to store and retrieve files). CONFIG.SITEDEF SETTINGS ======================= The file 'config.sitedef' contains the primary parameters used to set up install WIST using the 'sitedefedit' tool (provided in the 'sitedefedit' directory). The 'config.sitedef' file contains a header line ('[[def]]') followed by a set of variable definitions where each line contains a name, an equal sign ('=') and a value immediately following one another without any whitespace. Lines beginning with a hash character ('#') are comments and ignored for the purposes of installation. The variables collectively control the following aspects of the WIST configuration: * Database connection parameters * Perl executable path used in CGI scripts * Pathnames for libraries and configuration files * URL components for Pcapstore service URL's * Location of the Pcapstore file storage tree * Wist path definitions Note that most of the WIST parameters are actually controlled by the 'wist.conf' file generated during the installation process. Once installation has been completed, this file may be edited directly to change the configuration of WIST. The initial definition of 'wist.conf' is generated as part of the configuration process to simplify initial configuration for the user. For those variables that can be set directly in wist.conf, the corresponding WIST variable is noted. The variables define the following parameters: * Database connection parameters -------------------------------- 'db_hostname' (wist.conf: dbHost), 'db_database' (wist.conf: dbDatabase), 'db_username' (wist.conf: dbReadUser, dbWriteUser), 'db_password' (wist.conf: dbReadPassword, dbWritePassword): These set the basic database connection parameters. By default they designate 'wistdb' as the WIST database on the local host and assign the username 'wistapp' and the password 'wistpass' to be used for database connections. * Perl executable path used in CGI scripts ------------------------------------------ 'perlpath' : This sets the Perl executable path for all CGI scripts. Normally this is something like '/usr/bin/perl' or '/usr/local/bin/perl'. * Pathnames for libraries and configuration files ------------------------------------------------- 'wistpcapdevlib', 'wistpcappublib' : Absolute paths for the WIST Perl modules. By default these are defined to be the same but they may be set differently if one wishes to set up a development environment with its own WIST installation, say to work on the WIST code itself. The development environment is invoked when the environment variable 'DEV' for the WIST CGI scripts is set to a value that evaluates to boolean true in Perl (i.e. 1). This can be done with the 'SetEnv' option in Apache (i.e. 'SetEnv DEV 1') 'wistpcapdevconf', 'wistpcappubconf' : Absolute paths for the development and production WIST configuration files. Note that by default 'wist_dev.conf' is defined but not actually created. One may create a 'wist_dev.conf' by copying and editing 'wist.conf'. * URL components for Pcapstore service URL's -------------------------------------------- 'pcapstore_service_uriprefix', 'pcapstore_service_host', 'pcapstore_service_port' : Components for Pcapstore URL prefix for CGI scripts. By default defines 'http://localhost:80/wist/cgi-bin/' as the prefix for Pcapstore CGI scripts (i.e. they're located in the same directory as the WIST CGI scripts). * Location of the Pcapstore file storage tree --------------------------------------------- 'pcapstore_filestore_root' : Absolute path to the root of the file storage tree used by Pcapstore. 'pcapstore_temppath' : Absolute path to a directory where Pcapstore may create temporary files. * Wist path definitions ----------------------- 'wistdocumentroot' (wist.conf: documentRoot): Absolute path to root all WIST documents in filesystem. 'documentUrl' (wist.conf: documentUrl): URL prefix for all WIST documents (Web server's URL alias to 'wistdocumentroot') 'wistcgiurl' (wist.conf: cgiUrl): URL prefix for all WIST CGI scripts. 'wistjsurl' (wist.conf: jsUrl): URL prefix for all Javascript files use by WIST. 'wistcssurl' (wist.conf: cssUrl): URL prefix for all stylesheets used by WIST. 'wistimageurl' (wist.conf:imageUrl): 'wisttemplatebase' (wist.conf: templateBase): Directory for all WIST display templates. 'wistformtemplatebase' (wist.conf: formTemplateBase): Directory for all WIST form templates. 'wistcgiroot' (wist.conf: cgiRoot): Directory location for all WIST CGI scripts. 'wistimagebase' (wist.conf: imageBase): Directory for all resource images used by WIST.