File: libdata_install.txt Title: LibData Installation Author: Paul F. Bramscher brams006@umn.edu Date: August 25, 2008 ============================================================================== TABLE OF CONTENTS ============================================================================== 1.0 Infrastructure 2.0 Architecture 3.0 Installation Procedures 4.0 Troubleshooting ============================================================================== 1.0 INFRASTRUCTURE ============================================================================== Hardware Developed and tested on generic intel-based Linux servers and Sun servers. Other hardware (Macintosh) should be possible with little or no code modification. Operating System LibData should run with little or no modification on most operating systems capable of running an AMP (Apache, mySQL, PHP) stack. The most current release of LibData has been developed on modern Ubuntu and Solaris servers. Web Server Apache 1.x or 2.x. LibData is split into two directories, one serving public interfaces, the administrative portion should be served from an SSL location (refer to installation steps below). Database mySQL 5.x, myISAM engine. Note that LibData was initially developed on a version of mySQL without support for transactions, and this produced greater atomicity of the SQL code -- which still persists. Programming Language Written exclusively in PHP. Coding is structured/function based for simplicity, using PHP object encapsulation only for security (session-related) purposes. Meaningful variable names have been used throughout. Recommended Browsers Note that no client-side programming was done (other than HTML and modest usage of CSS). Therefore LibData ought to be quite widely viewable by most any browser available. Additionally, there are no frames to contend with. Viewing is best at 1024 x 768+, particularly the administrative pages. ============================================================================== 2.0 ARCHITECTURE ============================================================================== ------------------- Directory Locations ------------------- LibData involves two main directories, one serving up the public interfaces, another containing the administrative side. Both the public and administrative directories can be renamed and move to any web served location after installation (refer to steps later in this document). The "include" subdirectory below the LibData administration directory must always be a subdirectory below administration and cannot be renamed to something other than "include" without some script modifications. Following is an out-of-box installation on an Ubuntu or other Debian based server: ----------------- Public interfaces ----------------- /var/www/html/libdata /images /styles ------------------------- Administrative interfaces ------------------------- /var/www-ssl/html/libdata_admin /docs /images /include /install (but should be moved elsewhere after installation) Note that the administration side is piped through SSL. It is strongly recommended that this portion be served SSL, since authentication and user management is handled by this portion of LibData. ============================================================================== 3.0 INSTALLATION PROCEDURES ============================================================================== ------------- Initial Setup ------------- Before proceeding to the installation steps, it is necessary to configure PHP and Apache for the following: (A) Interpretation of both .php and .phtml file extensions by the php engine. This is configured by default on modern Ubuntu and other distros. On Ubuntu, for instance, you'll notes that /etc/apache2/mods-available/php5.conf is configured to interpret both .php and .phtml files as PHP. (B) "register_globals = Off". Prior LibData releases required this to be On. LibData will work with either On or Off, but the recommended setting (and required with PHP 6) is now Off. (C) Also in the php.ini file, make sure that "magic_quotes_gpc = Off". gpc stands for get/post/cookie, and turning quote escaping on will create problems for interaction at various layers between HTML, PHP and mySQL. If it must be turned on, some work may need to be done with textInmySQL() and textSearchmySQL() in /libdata_admin/include/app_controls.php. This will be treated further in this document. (D) Apache SSL should be +StdEnvVars for the SSL port. (E) Server side Includes should be allowed. There may be additional tweaking based on your installation, but the previous are minimal required settings. -------------------------------------------------------------- (1) Position the LibData public and administrative directories -------------------------------------------------------------- LibData now comes packaged in a single tar.gz file which extracts to "libdata" (public side), "libdata_admin" (administrative side) and "libdata_install" (installation scripts and documentation) It's possible to rename the public or administrative directories to something more meaningful to your organization. Whatever directory names are chosen, changes will need to be made in the public and administrative "libdata_vars.php" configuration files (Step #2 below). It's possible to rename these directories after LibData is fully populated as well. Changes are simple and go into effect immediately. The public and administration portions of LibData should have different directory names. It's possible (but not recommended) to give them the same name if the public portion is in a directory like /www/html/libdata and the administrative resides in /www-ssl/html/libdata (they will be differentiated by port numbers and http vs. https). But to avoid confusion, we initially recommend giving them differing names. So move "libdata" to a public-facing location that makes sense for your organization. For instance, /var/www/html/{anything}. The administrative directory "libdata_admin" should also moved to a web served location -- but it is HIGHLY recommended that this directory be SSL served, since passwords, cookies and other information will be sent. As with the public portion of LibData, it's possible to rename this directory to something more meaningful to your installation. Whatever directory name is chosen, changes will need to be made in Step #2 below to configure LibData to recognize them. File permissions and ownerships should be tweaked by a unix administrator as necessary. -------------------------- (2) Tweak libdata_vars.php -------------------------- Path information and other settings are stored in the public and administrative halves of libdata in a file named libdata_vars.php. It must remain located in either (a) BOTH the libdata public and administration directories or (b) in the Apache-defined default location for server-side inclusions. Another possibility, depending on your configuration, is a symlinking strategy. But the simplist route at this point is just to maintain both files and keep them identical. Make edits to one, and "cp" it to the other. Both files should be tweaked with information specific to your installation: server name, LibData "system" name, administrator, e-mail contact information, etc. and installation directory locations. Take note of the existing format -- don't add or subtract trailing backslashes. These files can be tweaked any time, during installation or with a fully-populated production LibData. Changes go into effect immediately, there is no process to start/restart. *** New to LibData 2.30 are $LIBDATA_DB, $LIBDATA_DB_SESSION and $LIBDATA_DB_STATS. These three variables reference the libdata, libsession and libstats databases respectively. It is a future design goal to soft-code the names of the databases here, so that they may be easily changed without sifting through the entire PHP code base for LibData. Currently only $LIBDATA_DB_STATS performs this way. $LIBDATA_DB and $LIBDATA_DB_SESSION are not yet fully implemented. --------------------------------------------------------------------- (3) Perform some initial tweaks and run the install script libload.pl --------------------------------------------------------------------- The /libdata_install/libload.pl script is a Perl executable that creates the libdata, libstats and libsession databases -- and libdata and libsession mySQL users. It it configured out-of-box to be executed on the mySQL server for which you wish to install LibData, and it grants permissions to "localhost". If you have a different environment, for instance the LibData PHP scripts will be served on a dedicated webserver/cluster and the mySQL database will reside elsewhere, some tweaks are needed below. (A) Before running the script, note that libload.pl doesn't include the "-h {hostname}" flag for its various mySQL calls, so it assumes that you're currently logged into the host containing the mySQL server which will be getting the LibData database installation. If not, decide which is easier: change the script to specify a different "-h {hostname}" for each mysql call in the script -- or execute it from the mySQL server which will be getting the installation (probably the easier route). (B) Also note that /libdata_install/create.sql creates libdata and libsession users which have mySQL access granted from "localhost". This assumes that your LibData PHP scripts and mySQL database sit on the same machine. If not, modify the create.sql grants accordingly, to specify some other host, before running the libload.pl script. The mySQL user named "libdata" must have, at a minimum, SELECT, INSERT, UPDATE and DELETE capability for the libdata and libstats databases. The mySQL user "libsession" must have SELECT, INSERT, UPDATE and DELETE rights to the libsession database. (C) Passwords. While looking at create.sql, it's also probably a good idea to change the out-of-box passwords before executing the script. As mentioned, the libdata user needs access to both the libdata and libstats databases (so keep those passwords the same when making changes). The libsession user just needs access to the libsession database. (D) Running the script. *** IMPORTANT **************************************************************** Ensure that there are NO existing mysql databases named libdata, libstats or libsession on your server. They will be DESTROYED by the next step. Running the following script will DROP all existing LibData references to ensure a clean install of the databases, a base data set, and mysql users. ****************************************************************************** Run the script named libload.pl, and follow the instructions given. If you encounter errors with this step, double-check the following: (A) The location of the Perl interpreter might not necessarily be /usr/bin/perl. Please adjust the reference in libload.pl accordingly. Also, make sure that this file is executable (chmod +x libload.pl). (B) The mySQL daemon is initialized (for the first time), up and running. (C) The mySQL account/password you supplied is valid, and may access the mySQL command-line client with permissions required to perform the actions listed above. ----------------------------------------------------------- (4) Double-check the mySQL user permissions & host settings ----------------------------------------------------------- Use whichever mySQL client you are most comfortable with (command-line, phpMyAdmin, mySQL Administrator, etc.) access the internal "mysql" system database. In the mysql.user table the libload.pl script (previous step above) should have created basic libdata and libsession accounts with the following rights. Following is an example (from /libdata_admin/install/create.sql) of entering the rows manually: GRANT SELECT, INSERT, UPDATE, DELETE ON libsession.* TO libsession@localhost IDENTIFIED BY 'ch4ngeME'; GRANT SELECT, INSERT, UPDATE, DELETE ON libdata.* TO libdata@localhost IDENTIFIED BY 'changEth1s'; GRANT SELECT, INSERT, UPDATE, DELETE ON libstats.* TO libdata@localhost IDENTIFIED BY 'changEth1s'; If you ran the script with the default passwords in create.sql, now is a good time to change the passwords: (Reference: http://dev.mysql.com/doc/refman/5.1/en/passwords.html) For Example: shell> mysqladmin -u libdata -h host_name password "newpwd" shell> mysqladmin -u libsession -h host_name password "newpwd" ------------------------------------ (5) Configure PHP connection strings ------------------------------------ You'll also need to edit the LibData database connection strings in each of the following files, with an IP or valid DNS name appropriate to the GRANT settings produced from the previous steps: LibData administrative path: include/db_connect.php (libdata user: main database connection script for the administrative side) include/accessClass.php (libdata user: loads libdata access rights for current user session) include/sessionClass.php (libsession user: creates, destroys and validates sessions) LibData public path: db_connect.php (libdata user: main database connection script for the public side) Make sure that the hostnames and passwords in these files match what was indicated in the previous database install step. ------------------------------------------------------------------------- (6) The LibData system should now be functional. Login as administrator. ------------------------------------------------------------------------- The default LibData internal admin user/password was created when running libload.pl (specified in libdata.sql while creating the libdata.staff table). Go to the appropriate url and login as administrator. For example: https://www.yourlibrary.edu/libdata_admin/login.phtml default username: admin default password: libd4t4 (a) Click the Manager Functions link on the bottom of the main console. (b) Click "Manage Staff List" toward the bottom of the Manager Function menu. (c) Select the radio button for Administrator, System to edit that account. (d) Change the administrator password as desired. Note that passwords, for security purposes, are never displayed on any of the forms. Also, passwords for any account may be purged to NULL. This automatically renders the account inactive (accounts without passwords may not login). LibData enforces a minimum password length of 6 characters. Be sure not to purge the password for the admin account, or you'll need to enter mySQL natively with a client, and execute a query like this: UPDATE libdata.staff SET password = SHA('n3wpassw0rd') WHERE staff_id = 2; or some such in order to log back into the system as administrator (admin). This back-end method may be used to change the passwords of any LibData user. ------------------------------------- (7) Test mySQL single-quote escaping ------------------------------------- Assuming your LibData configuration is now functional, it's a good idea to test proper escaping of single-quotes. On the main authoring console, attempt to enter a resource with a single-quote in the title. For example: Here's a Title. (Note that it is necessary to select some initial master subject or master information type while creating a new resource). On the resource entry form, click the Save New Resource button. Then update the title field by editing out the quote. For example: Heres a Title. Click the Update Resource button. Then go back and add the single-quote one more time: Here's a Title. Click Update Resource again. This will test both the insert and update SQL functionality. If LibData reports a SQL error, you'll most likely need to make a tweak here: /libdata_admin/include/app_controls.php. Look for the functions textInmySQL() and textSearchmySQL(). Most all of LibData's mySQL select/insert/update calls are first routed here. Depending on your mySQL installation, and if you cannot adjust magic_quotes_gpc in the php.ini to "Off" (as recommended) you may need to make programmatic changes here, appropriate for your environment. Both textInmySQL() and textSearchmySQL() could be heavily armored with additional code for bullet-proofing, possible security issues, SQL-injection attacks, etc. Note that double-quotes can present a problem on many sites in all but textarea based HTML form fields -- textOutHTML() ought to fix this on most/all LibData forms. Other variants on these themes use the php functions addslashes() stripslashes(). Hopefully everything will be working and you won't need to make any modifications here. ------------ (8) Cleanup ------------ Ensure that the install subdirectory (/libdata_install/) is not located in a web-servable location, and give only root users access to it -- since re-running the install script will DROP a production/populated LibData database. It's also recommended to chmod -x libload.pl to prevent a malicious user (or yourself) from making a grave mistake to a production system... ------------------------------ Tips for further configuration ------------------------------ (1) The public libdata db_connect.php may, alternatively, use a different username/password from the administrative db_connect.php file. Furthermore, the public connection need have only SELECT rights to the libdata database, and SELECT and INSERT rights to the libstats database. There are several strategies to fine-tune security, some of them are related uniquely to your organization and desired levels of granularity. (2) The LibData db_connect.php file, independently in both the administrative and public halves of LibData, contains a function named mysql_tryquery(). This is a light wrapper around the built-in mysql_query() function. Note that there is a variable for debug mode ($db_debug). Setting this to 1 (true) will cause all SQL queries which fail to be output to the screen. This is not recommended for production or public side LibData. However, it can be used in conjunction with a mail() type function to the mail the failed query, mySQL error message, and date/time transparently to the system administrator. This functionality is not supplied (and requires a functioning SMTP gateway). However, the programming to enable this is quite minimal given the centralized routing with mysql_tryquery() in the db_connect.php files. (Remember that administrative and public LibData utilize their own separate db_connect.php files.) ============================================================================== 4.0 TROUBLESHOOTING ============================================================================== Debugging dynamic database applications offers challenges on several fronts. If there are problems using LibData at this point, there are four main areas to debug: (1) Linux/Unix. Are the libdata files set to the appropriate permissions? Are they web servable? (2) Apache. Is it serving up other web basic HTML pages? If you are using SSL, is it functioning properly? Check Apache log files. (3) PHP. Create basic "Hello World" PHP programs with both a .php and .phtml extension. Are they being served? Make sure that Apache is configured to interpret both .php and .phtml pages through the PHP parser. Make sure that the libdata_vars.php files, in both the public and administrative locations, have the correct information. It sometimes helps to run the phpinfo() function (visit the http://www.php.net site for documentation on it) for information gathering purposes. (4) mySQL. Make sure that the affected files (db_connect.php on both the public and administration sides, accessClass.php, and sessionClass.php) all have information which corresponds to the name of your mySQL server host, and the correct mySQL accounts and passwords. Ensure that those accounts have the appropriate permissions as specified in the installation procedures above. For installation problems or suggestions, please send an e-mail to the developer, Paul F. Bramscher (brams006@umn.edu), though neither I nor the University of Minnesota can make any guarantees or warranties with regard to LibData or its support. August 25, 2008 Paul F. Bramscher brams006@umn.edu University of Minnesota Libraries