E-GADS! 2.x
Administrator Manual
© Copyright 2004 Calvin Martini.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
Table of Contents
2.3 Basic Installation and Configuration
2.3.1 Installing the E-GADS! Package
2.3.2 Setting up the MySQL Database
2.3.5 Changing the admin User Password
3.1 The Administration Interface
3.1.3 Editing Province/State Types
3.2 Troubleshooting and Support
5 Map-Enabled Pre-Installation on Unix Platforms
5.3.1 Install the Operating System
5.3.2 Install Apache HTTP Server
5.3.11 (Optional) Install Analog
5.3.12 (Optional) Install Cronolog
6 Pre-Installation on Microsoft Platforms
8 GNU Free Documentation License
1 Introduction
This manual is written for E-GADS! System Administrators and contains detailed information on installation, administration and customization.
1.1 Policy Considerations
Volunteer search and rescue is about public service and trust. In the process of setting up a web-based database such as E-GADS!, it is important to develop the policy framework within which the system will be operated. The following are some points to consider when developing the local policies for your own implementation:
§ What are the responsibilities of the operator and users with respect to security of the data? You should clearly state the risk and measures you have taken to reduce the risks (server hardening, firewall, encryption, access controls and procedures, etc.).
§ What is the process for issuing accounts? Who has the authority to request and account? What are the access levels granted to categories of users?
§ Develop an acceptable use policy and state under which circumstances access may be terminated.
§ How long is data retained and who has the authority to remove old data?
§ This system can contain a great deal of personal information. What is your privacy policy? A privacy policy should state who owns the data, explain what the data will be used for and cover the appropriate use of the information including conditions under which information may be released and to whom.
§ If your organization has reporting requirements, make sure that users know these requirements and understand which fields are required and which are optional.
§ Develop a policy concerning certification requirements. Establish procedures for certifications at the national, provincial/state and/or local levels. Ensure users are familiar with these procedures and use access permissions to control which users can grant certifications.
§ Check local legal requirements relating to the above issues.
1.2 Security Features
The application has a number of security features to ensure data is handled in accordance with the established privacy policies:
§ User permissions are checked on each screen access - it is not possible to bypass the logon.
§ All accesses and actions performed on the system are fully logged.
§ If more than 5 successive attempts occur to log on to an account with the incorrect password, the account will be locked out and no further attempts will be allowed for the account for 60 minutes.
§ The system supports account expiry dates on a per account basis.
§ Access is categorised by search reports, membership and certifications; each of which is further broken down into none, read-only, read/write, delete and administrator level permissions. Each of these permissions is controlled on a per-team basis. Additionally, special director access permits read-only access to director contact information to facilitate work amongst directors. These can be combined in any manner to precisely match the specific requirements of a particular user without exposing unrelated information.
§ Users can change their own password.
§ The user name of the person who last edited a record is displayed at the bottom of each record update screen.
1.3 Useful Links
The following links provide useful information for E-GADS! system administrators or persons who are interested in learning more about the software.
§ http://e-gads.sourceforge.net/ - The home page for the E-GADS! application.
§ http://sardat.homeunix.org/sto_demo/display.php - The E-GADS! demonstration system.
2 Installation
2.1 Requirements
This software has been tested on RedHat Linux 7 and 8 and Microsoft Windows 98SE and 2000 Professional; however, since the software is run-time interpreted by the PHP engine, it should work fine on any systems on which PHP is supported.
For basic installation, the following supporting software is required:
1. Web server software compatible with PHP (e.g. Apache HTTPD, IIS, etc). Apache 2.x is an open source product released under the GNU Public License (GPL). Please refer to http://www.apache.org for more information on the Apache HTTP Server project.
2. PHP (4.3.2 has been tested). PHP is the scripting engine that interprests the .php files in the E-GADS! Application. Refer to http://www.php.net/ for further information. PHP is an open source product released under the GNU Public License (GPL) and is a project of the Apache Software Foundation.
3. MySQL (3.23 has been tested). MySQL is the back-end database server used by E-GADS! to store information. Refer to http://www.mysql.com/ for further information. MySQL is an open source product released under the GNU Public License (GPL). Note that is not necessary for the MySQL server to be on the same hardware as the web server/PHP server; you can use the $dbhostname variable in globals.php to specify the network address of the MySQL database server.
If you are not interested in supporting servers, several popular an internet service providers (ISP) offer PHP web hosting with MySQL database services. It should be possible to operate the E-GADS! system in such an environment.
Due to the private nature of the information that this system can store, it is recommended that you configure your web server to use SSL encryption as per your web server software's documentation. SSL configuration is not included within the scope of the E-GADS! system documentation.
E-GADS! is distributed in two packages, with map support or without map support. The map display provides a graphical interactive map showing the distribution of searches over a geographical area. This feature is only available on Unix systems as the third-party supporting components are not fully compatible with non-Unix (e.g. Microsoft or Apple) operating systems; however, don’t despair since this is truly an enhancement and is not required for core functionality.
The dataset provided with this release covers Canada only, although plans for data sets for other areas are in the works. The additional steps required to support this feature are significant and add tremendous complexity to the installation. Installations being co-hosted at an internet service provider (ISP) will not likely install or support the specialized components necessary to support the map functions.
To add map display functionality (Unix systems only), these additional open source components are required:
§ mapserver-3.6.4 – The MapServer core application
§ proj-4.4.5 – Cartographic projections library. Use by MapServer to perform on-the fly projection conversions.
§ proj-nad27-1.1 – The nad27 datum data for Proj.
§ gd-2.0.7gif – Graphic library used by MapServer to produce the map JPEG and GIF graphics.
§ gdal-1.1.8 0 – Geospatial Data Abstraction Library - translator library for raster and vector geospatial data formats.
§ libwww-5.3.2 - general-purpose client side Web API. Required for the MapServer --with-wmsclient (Web Map Server client) option.[c1]
2.2 Package Contents
The base package includes:
§ The GNU Public License (GPL) in README_License.txt
§ README_Changes.txt which contains the change history.
§ README_Notes.txt which includes release notes for the package.
§ The core E-GADS! scripts.
§ Documentation: User Manual, Administrator Manual and Developer Manual.
§ North American locales, ca_en-fr and us_en, containing text strings, graphics and starter data for the United States and Canada respectively. A locale contains all of the user interface’s language or sets of languages with corresponding terminology specific to a given geographic area. Only one locale can be active at one time.
Additional packages available separately may include:
§ Patches and upgrades.
§ Map data sets.
§ Utility scripts package.
§ Locales for other areas.
§ Other modules.
§ Third party software.
Most of these components can be found on the E-GADS! project page on SourceForge at http://sourceforge.net/projects/e-gads/.
2.3 Basic Installation and Configuration
2.3.1 Installing the E-GADS! Package
In this step you will extract the package files to your server’s file system. You can install the software package anywhere you like as long as your web server is properly configured to map to the content and the directory is configured to use PHP for the .php file type.
- Extract the software tarball/zip archive under your web server's home directory. This should create an e-gads directory containing the entire software package.
Unix: tar -zxf e-gads_2.x.x.tar.gz
- Set ownership and permissions. The web server user must have read access to all of the E-GADS! content and full access to the data directory. This example for a Unix system assumes the web server is running as user “web” and group “web”.
Unix:
chown -R web:web ./e-gads
chmod -R 744 ./e-gads
chmod u+rwx,g+rwxs,o= ./e-gads/data
find ./e-gads -type d -exec chmod g+x,o+x {} \;
chmod 744 ./e-gads/data/*
Windows:
\e-gads\* (Read)
\e-gads\data\* (Change)
2.3.2 Setting up the MySQL Database
In this section you will complete all of the steps required to install the database and configure the application to use it.
Before proceeding, ensure that you have administrator access to a fully functional MySQL server. If you do not have a functional MySQL server, do not proceed. If you do not have administrative access, you may need to have an administrative level user perform some of these steps for you.
Modifying the database name (the default is egads) is not normally required; feel free to change it but remember to carry the new name through the rest of the installation process. Also, the user name for the database user must be consistent throughout the following steps.
- Edit the setup.sql file to modify the MySQL user account password for the egads user. Change the 'CHANGE_ME' that follows "IDENTIFIED BY" in the GRANT statement to a strong password. Use this password in the remaining steps.
- Run the setup script using the mysql command (admin access required, use your own password in place of {password}):
Unix:
mysql --password={password} <./e-gads/setup.sql
Windows:
mysql --password={password} <e-gads\setup.sql
- Install the sample data set. The sample data set enables you to set up a test system to verify proper application functionality and to gain familiarity with the system prior to going live. Typically you use the sample data set as a starting point and add or remove data types to configure you local system before entering live data. Deleting data types once live data has been entered into the system is not recommended. You should carefully design your data types with reporting and future requirements in mind.
a. Edit the data.sql file to modify the egads user password as you did in the preceding step.
b. Run the script using the mysql command:
Unix:
mysql --password={password} <./e-gads/data.sql
Windows:
mysql --password={password} <e-gads\data.sql
2.3.3 Configuring globals.php
Edit globals.php to configure the variables under the "USER EDITABLE PARAMETERS" section. Generally, unless you have special requirements the only parameter you need to change is dbpassword.
On Microsoft systems, for parameters requiring file paths be sure to escape forward slashes as this character is the escape character in PHP; instead of “\”, use “\\”.
For fields requiring email addresses, be sure to escape the “@” character using a forward slash (e.g. “\@”) as it is a special character (refers to an array) in the PHP language.
The following is a list of user definable variables and an explanation for each.
§ $dbhostname - The hostname or IP address of the MySQL host (the default value is localhost).
§ $dbusername - The MySQL user account (the default value is egads).
§ $dbpassword - The MySQL user account password.
§ $dbname - The MySQL database (the default value is egads).
§ $locale – The relative path to the active locale, no trailing slash. (New in 2.2)
§ $error_url - The URL to send the user to when an error occurs. There is usually no reason to change it from the default value of "login.php".
§ $sr_notify - This is the email address to which notification messages are sent by the system. If multiple email addresses are used, separate them with a semicolon. This is currently used only for new search report records.
§ $admin_email - the email address to which administrative emails are sent by the system.
§ $mail_footer – This is a text footer that is displayed at the bottom of email addresses generated by the db_event_mail and db_emergency_mail scripts. Use of the “\n” newline and “\t” characters is supported.
§ ENABLEMAP; this is a constant. Set the value to TRUE to enable the map report function, to FALSE to disable it (default). Enabling the map function requires that mapserver and supporting libraries be installed and properly configured. Note that the map subsystem is currently only configured with Canadian data. For basic installations without map functionality, leave this set to FALSE.
§ $mapData – The relative path to the map data set, no trailing slash. (New in 2.2)
§ $logfile - Relative or absolute path to the application log file. The web server user must have write permission for this file. Detailed transaction information is written to this file for system administration purposes.
§ $debug_addr – Use this variable to define the IP network address of client PCs to display debug information to. If the client’s IP address matches this value, session information and other technical information will be displayed at the bottom of reports using the main view (display.php). This information may be useful for troubleshooting or development, but should otherwise be disabled (use the value “DISABLED” or any other value that won’t match an IP address) or set to localhost (127.0.0.1). PHP regular expressions are supported for this value. For example, a value of “192\.168\..*” will match any IP address on the 192.168 subnet. Note that the escape character “\” is used on the periods in the pattern because an unescaped period will match any single character. “.*” matches one or more occurrences of any character.
2.3.4 Testing
Log in to your new installation. Using a web browser, navigate to http://{host}/e-gads/login.php and enter user ID "admin" and password "password". Press the login button and you should enter the application. If you see an error, recheck the steps.
If you get an error, try restarting your web server and trying again before diving into troubleshooting steps; sometimes this will fix the problem. On new installations it is common to forget to restart the web server after configuration changes have been made.
If you see a text file instead of the log in screen, then PHP is either not installed or the web server is not configured for the .php file type.
If you see the login in screen but get an error when you attempt to log in, then either MySQL is not installed/not running, or globals.php is not properly configured for the database host or user account (user or password).
If you can’t log in due to an invalid password and your E-GADS system is running on a Microsoft Windows server, make sure that you have installed and enabled the php_mcrypt.dll extension. Refer to section 8 for more information.
2.3.5 Changing the admin User Password
Change your admin user password using the "Change Password" option under the "Main" menu.
2.3.6 Cleaning Up
Remove the setup.sql and data.sql scripts or make them non-readable to the web server user in order to prevent them being viewed through the web server. These scripts contain the MySQL egads user password.
2.4 Installing Locales
Locales are language modules for specific areas. Since both the languages and terminology are different in various countries and jurisdictions, the E-GADS! system has been designed to separate all text strings from the core code and place them in easily customizable modules called locales. Locales can contain one or more languages and all languages in the configured locale will be available to the users using the language submenu in the E-GADS! user interface. Only one active locale may be specified in the globals.php file.
Locales are installed under the /locales subdirectory. It is necessary to install at least one locale in order to get a running system. Refer to the E-GADS! project site on SourceForge to obtain locale modules.
2.5 Installing Map Modules
Map modules are (will be) available as separate packages. Please refer to the installation instructions supplied with the map package.
2.6 Upgrading
This section describes the steps required to upgrade from a previous version.
1. Back up the entire e-gads directory. This is not only for safety – you will need to transfer the values from the old globals.php configuration file to the new globals.php (for a new package version or for upgrades if a new version of globals.php is included in the package).
2. Back up the egads database for safety.
3. Extract the package archive and copy the contents into the installation directory.
4. Read the README_Notes.txt file for any important information about this release.
5. If one is provided, run the cleanup.sh (Unix servers) or cleanup.bat (Microsoft Windows servers) script. This script will remove files which are no longer necessary and will then delete itself.
6. If one is provided the previous version of the application (the script will be named convert_[previous version]_to_[current version].sql), run the database conversion script:
- Modify the script's USE line for the intended database name (from your globals.php)
- Run the script as the administrative user: mysql -p <convert_[previous version]_to_[current version].sql
- Delete the script – it contains the database admin password and is no longer necessary.
7. If required, using a text editor transfer the values from backup copy of globals.php to the new file.
8. Set the permissions on the E-GADS! directory. Refer to the basic installation instructions for details.
9. Test the site to ensure everything is working properly.
3 Administration
3.1 The Administration Interface
When Administration is chosen from the Main menu on the page, the administrative interface is displayed. Within this interface you can manage users and configure type codes for the database. Type codes are used to populate the drop down list choices for the various forms within the application.
The administrative interface uses the same design as the rest of the application; the New menu permits creation of new records for the currently displayed data type and the View menu is used to display data types for editing.
Since user management is the primary use for the administration interface, when you first enter the interface user data is displayed. The report title is shown at the top of the display area and the current display filter is shown immediately below it. The main body of the report is presented in a tabular format with the first column data serving as the link to edit the record. At the bottom of the user report data table is an “Email All” mailto link which when selected will open your locally configured email client with the email addresses of the displayed users entered in the recipient field. Below the data table is a query status line.
Figure 1. Administrative Interface, Default View.
The menu options on this page include:
§ Main: Return to Main View, Language, Logout
§ New – This button will create a new record of the currently displayed data type.
§ View – The View menu contains options to choose the currently displayed report:
- Team (All/Province/Team) – Displayed for the user report only. Allows you to filter the currently selected data based on province/state and team.
- Activities – Displays activity types used to populate the activity selection choices for search reports.
- Agencies – Displays agency types used to populate the agency selection choices for search reports.
- Calendar Events – Displays calendar event types used to populate the category selection choices for events.
- Certifications – Displays certification level types used to populate certification selection choices for member certifications and courses.
- Certifying Agencies – Displays certifying agency types used to populate agency selection choices for member certifications and courses.
- Conditions – Display conditions types used to populate condition selection choices for search subjects in search reports.
- Environment – Display environment types used to populate environment selection choices for search reports.
- Equipment – Display equipment types used to populate equipment selection choices for search subjects in search reports.
- Events – Display event types used to populate type of operation selection choices for search reports.
- Experience – Display experience types used to populate experience selection choices for search subjects in search reports.
- Outcomes – Display resource types used to populate outcome selection choices for search subjects in search reports.
- Positions – Display resource types used to populate resource selection choices for search reports.
- Provinces/States – Display province/state types used to populate province/state selection choices throughout the application.
- Resources – Display resource types used to populate resources used selection choices for search reports.
- Reasons – Display reason types used to populate reason 1 and reason 2 selection choices for search reports.
- Tactics – Display tactic types used to populate tactics used selection choices for search reports.
- Users – Displays system users. This is the default view when first entering the administrative interface.
- Weather – Display weather types used to populate weather selection choices for search reports.
- Display Print Version – Displays a printer friendly version of the current report without menu graphics. A “Return to Previous Page” link is shown at the top of this report to allow you to return to the normal view with menu.
§ Refresh - The refresh button is used to update the current display.
3.1.1 Editing Users
The user edit form allows you to create or update user accounts.
To create new users, select New from the main page when the Users report is displayed, complete the General Information section and define team permissions.
To edit existing user accounts, choose the link from the first column of the Users report that corresponds to the user record that you want to edit. The edit user form is displayed.
Figure 2. The user edit form showing a new record.
3.1.1.1 General Information
The following is a description of the fields on the user edit form:
§ User ID – A short and unique user ID. This will be used by the user to log in to the system
§ Full Name – The user’s full name.
§ Phone: 1 – The user’s phone number; useful for contacting the user for issues related to their account.
§ Email – The user’s internet email address; useful for contacting the user for issues related to their account.
§ Expires – The date on which the account will expire. When the use tries to log in beyond this date, they will be shown an “Account Expired” message and will not be able to proceed further. It is a good idea to establish a realistic expiry date to lessen the likelihood that the data in the system is not available to users who are no monger authorized to view the data. In most volunteer organizations, changes in structure will not be reported promptly to the System Administrator; since it is easy to extend an account on request, the expiry date should typically be one year – a common appointment term for positions within most organizations. To make an account relatively permanent, set an expiry date well in the future.
§ a_diralt – This checkbox specifies if this user is a director or alternate within the board of directors for the organization. If enabled, the user will have access to the director’s mailing list report for the purpose of obtaining contact information for their fellow directors or alternates.
§ a_admin – If enabled, this checkbox flags this user as a System Administrator and give them access to the Administration functions within the application. You can use this to delegate administrative access, but if you do make certain the administrative users understand how to use the system well as some actions (such as deleting data types) can have serious consequences.
§ Enter New Password – A password for the user. The password can contain any characters, but should not be overly long (no more than 8 characters, mixed numbers and letters is good). Since users can change their own password at any time, users should be informed of good password practices and be encouraged to change their passwords regularly. Passwords cannot be retrieved by the System Administrator; if a user forgets his/her password, all the System Administrator can do is change it and send the user the new password; however, the user can reset the password themselves using the “Forgot your password?” link on the log in page as long as their email address is the same as the one associated with the account.
§ Re-Enter New Password – Re-enter the password to confirm.
§ Province/State – Specifies the province/state that the user has access to. This setting affects the province/state choices presented to the user; if only one province/state is specified, the user will not be prompted for a province/state during data entry. If “All” is chosen this will active province/state selection prompts and fields.
3.1.1.2 Team Access
The team access section is where you define which teams users have access to and what level of access they have for each function for each team specified.
When teams have been added to the team access for the user, they will be displayed in a table above the Add Team area. You can add or modify assigned team access permissions by changing the access levels for the desired team, enabling the select checkbox for that team and pressing the “Save Updates” button. To delete assigned teams for this user, enable the corresponding checkbox for the team(s) to be deleted and press “Delete Selected”.
The following is an explanation of the access levels:
§ None – The user will have no access.
§ Read Only – The user will be able to display detailed records, but will not be able to edit or delete them.
§ Read/Write – The user will be able to display detailed records, create new records and edit existing records but will not be able to delete them.
§ Delete – The user will be able to display detailed records, create new records, edit existing records and delete records. This is full access for normal users.
§ Administrator – The user has all the permissions of a delete level user as well as special administrator level access for certain functions.[c2]
The following are descriptions of the edit team access subsection:
§ Select (Checkbox) – Enabling the checkbox selects the team row for the “Save Updates” or “Delete Selected” operations.
§ A_Search – The user’s access for search report records for this team.
§ A_memb – The user’s access for member records (except certifications) for this team.
§ A_cert – The user’s access for certification records reports for this team. A certification level of Administrator is required to grant certifications (date certified and expiry date) for certification types that have the Certifying User flag enabled.
§ A_train – The user’s access for training records for this team.
§ Save Updates – Saves updates to the selected records.
§ Delete Selected – Deleted the selected records.
Figure 3. The team access section showing delete level permissions for all teams.
The following are descriptions of the add team access subsection:
§ Team – The team to add permission for. As teams are added to a user’s team access permissions, the available team choices for adding team permissions will be reduced accordingly. The “All” team choice is available only when no teams have been added to the team permissions.
§ Access Searches – Determines the user’s access level for search report records.
§ Access Members – Determines the user’s access level for member records (except certifications).
§ Access Certifications – Determines the user’s access level for certification records.
§ Access Training – Determines the user’s access level for training records.
§ Add – When this Add button is pressed the system adds the team with the currently selected permissions to the assigned team access permissions for this user.
Figure 4. The Team Selection section showing read/write level access for a single team.
3.1.1.3 Action Buttons
§ Save – Saves the user record and returns to the main administration view.
§ Delete – Deletes the user from the system.
§ Reset – Returns all fields to the original values.
§ Cancel – Aborts the edit and returns to the main administration view.
3.1.2 Editing Agency Types
This section describes the edit form for both agencies and certifying agencies data types.
The menu bar on the agency edit form contains the following options:
§ Main: Return to Main View, Language, Logout
The agency editing form contains the following fields:
§ (language) Description - The name of the agency. This field is used to populate form field dropdown lists and so should not be overly long. More than one type field may be listed based on installed languages.
§ Address – The street address for the agency’s mailing address.
§ City – The city for the agency’s mailing address.
§ Province/State – The province for the agency. This value determines which province/state this agency will be listed in for the selected province in editing forms where agencies are specified.
§ Postal/Zip Code – The postal/zip code for the agency’s mailing address.
§ Phone 1 – The agency’s telephone number.
§ Phone Fax – The agency’s fax number.
§ Email – he agency’s internet email address.
§ Website – The address to the agency’s internet website.
Figure 5. The agency/certifying agency type edit form showing a new record.
3.1.2.1 Action Buttons
§ Save – Saves the agency record and returns to the main administration view.
§ Delete – Deletes the agency from the system.
§ Reset – Returns all fields to the original values.
§ Cancel – Aborts the edit and returns to the main administration view.
3.1.3 Editing Province/State Types
The list which follows is a description of the fields and buttons on the province/state type editing form:
§ Main: Return to Main View, Language, Logout
§ (language) Type - An easily recognizable short name for the data type. This field is used to populate form field dropdown lists. More than one type field may be listed based on installed languages.
§ (language) Description - Text describing the data type. This is used to build the description window displayed when you click on “Description” link next to a dropdown list field on certain edit forms. So that the user’s can have the opportunity to get definitions of the selection choices, it is important to include enough detail to describe the data type. More than one description field may be listed based on installed languages.
§ Extent – This is a parameter passed to MapServer to define the initial output extent to be displayed for this province/state in the map report. If you have map support enabled, you will need to specify these values. The fields is in the format [minx] [miny] [maxx] [maxy] where minx/miny defines the lower right hand corner and maxx/maxy defines the upper left hand corner. These need to be in the same units as the map data or, if specifying a different output projection, in the same units as the output projection. These values should be provided with your data set or alternatively you can determine the extents using a GIS package such as ArcView or the ogrinfo utility which is provided with the GDAL library. Refer to http://mapserver.gis.umn.edu/doc40/mapfile-reference.html#map for more information on this value. If you do not specify a value and are using map support, MapServer will display the entire dataset when generating images for this province/state.
§ Prefix – The prefix to be used when generating GSAR File IDs for search reports.
§ Logo file – The relative path and file name for the logo to be used in the upper left hand corner of printed versions of search reports. The image should be in JPEG or GIF format and be approximately 200x200 pixels in size.
§ Association – The name of the provincial/state organization. This field is used to title the printed version of the search reports. More than one type field may be listed based on installed languages.
§ Save – Saves the record and returns to the main administration view.
§ Delete – Deletes the province/state from the system. Important: deletion of data types should not be performed on systems containing live data without first manually converting all of the associated records to a new type code; otherwise, the type fields will not be properly displayed. It is very highly recommended to define all of your data types before entering live data into the system.
§ Reset – Returns all fields to the original values.
§ Cancel – Aborts the edit and returns to the main administration view.
Figure 6. The type edit form showing a province/state record.
3.1.3.1 Action Buttons
§ Save – Saves the province/state record and returns to the main administration view.
§ Delete – Deletes the province/state from the system. . Important: deletion of data types should not be performed on systems containing live data without first manually converting all of the associated records to a new type code; otherwise, the type fields will not be properly displayed. It is very highly recommended to define all of your data types before entering live data into the system.
§ Reset – Returns all fields to the original values.
§ Cancel – Aborts the edit and returns to the main administration view.
3.1.4 Editing Other Types
The list which follows is a description of the common fields and buttons on the following type editing forms: activities, calendar events, conditions, environment, equipment,
§ Main: Return to Main View, Language, Logout
§ (language) Type - An easily recognizable short name for the data type. This field is used to populate form field dropdown lists. More than one type field may be listed based on installed languages.
§ (language) Description - Text describing the data type. This is used to build the description window displayed when you click on “Description” link next to a dropdown list field on certain edit forms. So that the user’s can have the opportunity to get definitions of the selection choices, it is important to include enough detail to describe the data type. More than one description field may be listed based on installed languages.
§ Save – Saves the record and returns to the main administration view.
§ Delete – Deletes the data type from the system. Important: deletion of data types should not be performed on systems containing live data without first manually converting all of the associated records to a new type code; otherwise, the type fields will not be properly displayed. It is very highly recommended to define all of your data types before entering live data into the system.
§ Reset – Returns all fields to the original values.
§ Cancel – Aborts the edit and returns to the main administration view.
3.2 Troubleshooting and Support
If you are having problems with your E-GADS! implementation, here are some resources that may help you troubleshoot:
§ Recheck your installation steps. Many issues are related to file permissions, particularly for the data directory for which the web server user must have read/write permissions.
§ Check the mailing lists to see if others are experiencing the same problem.
§ Try to determine if the problem is related to E-GADS scripts or to supporting components such as PHP or MySQL. If your problem looks like it may be related to a third-party component, check the component’s website and the internet for information that may help you.
§ Search through the E-GADS project site (http://sourceforge.net/projects/e-gads/) to see if there is information that may provide clues.
§ Register a support request at http://sourceforge.net/projects/e-gads/.
3.3 Reporting Bugs
Generally it is always a good idea to upgrade to the latest production release before reporting a bug.
Please report all bugs through the bug system at http://sourceforge.net/projects/e-gads/. You will need a user account for the SourceForge site before you can post a bug using this method. Please include as much detail as possible including script or process which generated the error, the error message and any other information you think may help us isolate the problem You can also browse through bugs, patches, and release changes to see if this problems has already been fixed.
Once you have submitted a bug report, a developer will be assigned to follow up with you.
We also encourage you to join the e-gads-user and e-gads-notices mailing lists at http://sourceforge.net/projects/e-gads/ to keep informed of the latest developments and communicate with other users of the E-GADS! software worldwide.
3.4 Requesting Enhancements
Requests for new features are encouraged and are always welcome. Please use the RFE (Request for Enhancements) system at http://sourceforge.net/projects/e-gads/ to register such requests.
4 Customization
Extensive customization requires specialized skills; if you want to make significant changes to the software, the best bet is to join the e-gads-developer mailing list and review the E-GADS! Developer’s Guide. If your requirements are not unique, then it may be best to join the project as a developer and participate in the project so that others can also benefit from your efforts.
4.1 Customizing Map Data
4.2 Customizing Look and Feel
All users will be able to perform very basic customizations using the application’s administrative interface. Modifications of this type are limited to custom data types and specifying logos for printed search reports (under the province data type). Other modifications require knowledge of PHP scripting, HTML, MapServer (for map support enabled systems) and graphics software.
The following are files that will be of particular interest to those wishing to customize the look of the user interface:
§ css.html – Cascading Style Sheet (CSS) for the user interface.
§ css_print.html – Special CSS file for print version reports only.
§ lib_headers.php – Contains all of the code used to generate the header, footer and menu components of the user interface. Tread carefully as the coding is somewhat complex; stick to minor edits unless you know what you are doing.
§ images – Most images used in the interface are under the images subdirectory; the only exception is the menu button images which are language specific and are contained in the active locale subdirectory. The simplest way to customize an image is to obtain the name of the image by opening the E-GADS! application in your browser and checking the properties for the image object you are interested in; edit the image in a graphics editor (keeping the same dimensions) and save the file using the same name under the images directory.
§ (locale)/locale.php – Contains variables which specify the menu button image widths in pixels for both on ([1]) and off([2]) versions of the button.
5 Map-Enabled Pre-Installation on Unix Platforms
NOTE: The map feature is only used for a graphical "push-pin" report. Running without the map feature in no way impacts the functionality of the application. Since the dataset provided covers only Canada, installation of a map-enabled E-GADS! system should only be attempted by the most experienced and patient users. If these instructions look confusing to you, then perform a basic installation and run without the map feature.
There is an excellent step-by step procedure for configuring an Apache/PHP system at
These are detailed step-by-step instructions on how to configure a map-enabled E-GADS! system on a new Red Hat Linux server. The versions specified and the orders of the steps are critical. Depending on your specific system, you may experience various errors and warnings that are not covered here. This information is provided for your convenience only and it is not supported.
5.1 Assumptions
- The Unix system for these instructions is RedHat 8.
- Apache is installed to the default location (/usr/local/apache2)
- PHP is installed to the default location (/usr/local)
- The document root for Apache is /home/httpd/html.
- Components are extracted and built under /usr/local/src.
5.2 Required Files
Obtain the following files from the internet:
- httpd-2.0.44.tar.gz (apache web server)
- php-4.3.2.tar.gz (php script engine)
- e-gads package (latest production release)
- Mysql 3.23 (use the stock MySQL 3.23 rpm installed with the RedHat O/S since there are no special configurations)
- epsg
- libwww-5.3.2-20011211.tar.gz (required by mapserver)
- mapserver-3.6.4.tar.gz (mapserver)
- gd-2.0.7gif.tar.gz (graphics device
- gdal-1.1.8.tar.gz
- proj-4.4.5.tar.gz
- proj-nad27-1.1.tar.gz
Optionally, obtain these following components::
- analog-5.24.tar.gz (web server log analysis/statistical reporting package)
- cronolog-1.6.2.tar.gz (web server log rotation utility)
5.3 Procedure
5.3.1 Install the Operating System
In this step you will install and configure the RedHat 8 operating system.
- Install Red Hat 8 in a server configuration with development libraries , compiler and MySQL 3.28
The following are required packages (Included with Red Hat 8) which should be selected for the installation:
· Development tools: gcc, perl
· Kernel development
· X Software Development
· MySQL server 3.28
· libpng-1.2.2-8
· libpng-devel-1.2.2-8
· libjpeg-6b-21
· libjpeg-devel-6b-21
- Remove GD and PHP (and dependent files) if installed:
rpm -e gd
rpm -e php
- Check for other required packages:
rpm -q libpng-1.2.2-8
rpm -q libpng-devel-1.2.2-8
rpm -q libjpeg-6b-21
rpm -q libjpeg-devel-6b-21
5.3.2 Install Apache HTTP Server
This section describes the steps required to compile and install Apache 2.
- Extract the tarball:
cd /usr/local/src
tar -zxf /usr/local/src/httpd-2.0.44.tar.gz
- Configure for the compile
cd /usr/local/src/httpd-2.0.44
./configure --prefix=/usr/local/apache2 --enable-so
- Compile and install the binaries:
make
make install
- Test to see that apachectl will correctly start and stop the Apache HTTP Server:
/usr/local/apache2/bin/apachectl start
/usr/local/apache2/bin/apachectl stop
- Create the cgi-bin directory (required for the PHP installation):
mkdir -p /home/httpd/html/cgi-bin
- Edit /usr/local/apache2/conf/httpd.conf:
a. Set the document root for the web server:
FIND: DocumentRoot "/usr/local/apache2/htdocs"
REPLACE WITH: DocumentRoot "/home/httpd/html"
FIND: <Directory "/usr/local/apache2/htdocs">
REPLACE WITH: <Directory "/home/httpd/html">
b. Add the CGI handler:
AddHandler cgi-script .cgi
c. Set the options for the web server’s root:
<Directory "/home/httpd/html/">
Options All
</Directory>
d. Add the tmp directory for MapServer’s temporary files:
Alias /ms_tmp/ "/tmp/ms_tmp/"
e. Configure the CGI directory options and mapping:
<Directory "/home/httpd/html/cgi-bin">
AllowOverride None
Options None
Order allow,deny
Allow from all
</Directory>
ScriptAlias /cgi-bin/ "/home/httpd/html/cgi-bin/"
- Test to see that apachectl will still correctly start and stop the Apache HTTP Server. If not, recheck the configuration file edits.
/usr/local/apache2/bin/apachectl start
/usr/local/apache2/bin/apachectl stop
- Set up the boot startup scripts for Apache
ln -s /usr/local/apache2/bin/httpd /etc/rc.d/init.d/httpd
cd ../rc3.d
ln -s ../init.d/httpd S91httpd
cd ../rc2.d
ln -s ../init.d/httpd K09httpd
5.3.3 [c3]Run MySQL
- Start the MySQL daemon
/etc/init.d/mysql start
- Set the MySQL Admin password (If required)
shell> mysql -u root mysql
mysql> SET PASSWORD FOR root=PASSWORD('new_password');
- Configure MySQL to start up on boot:
ln -s ../init.d/mysqld S91mysqld
cd ../rc2.d
ln -s ../init.d/mysqld K09mysqld
5.3.4 [c4]Install Proj
This section describes the steps required to compile and install Proj, one of the supporting components for MapServer.
- Extract the tarball:
tar -zxf /usr/local/src/proj-4.4.5.tar.gz
cd /usr/local/src/proj-4.4.5
- Extract the NAD27 tarball:
cd nad
tar -zxf /usr/local/src/proj-nad27-1.1.tar.gz
- Configure in preparation for compilation:
cd ..
./configure
- Compile and install the binaries:
make
make install
- To enable Canadian WMS server support, obtain the custom data file from http://www2.dmsolutions.ca/mapserver/dl/proj4-epsg-with-42xxx.zip and install the contained epsg file to /usr/local/share/proj/epsg. Refer to the following link for more information:
http://www.maptools.org/maplab/index.phtml?page=maplab_linux.txt
- To add the Proj libraries to the runtime system library path, edit /etc/ld.so.conf to add /usr/local/lib, and then run "/sbin/ldconfig". This will permanently add /usr/local/lib to your system's runtime library path. Refer to the PHP MapScript FAQ for more information:
http://www.maptools.org/php_mapscript/index.phtml?page=faq.html#4.1
5.3.5 Install libwww
This section describes the steps required to compile and install libwww, one of the supporting components for MapServer.
- Extract the tarball:
tar -zxf /usr/local/src/libwww-5.3.2-20011211.tar.gz
- Configure options for compilation:
cd /usr/local/src/libwww
./configure
- Compile and install the binaries:
make
make install
- Add the new library:
cd ..
/sbin/ldconfig
5.3.6 Configure FreeType
Perform the following steps to link FreeType for use by MapServer:
cd /usr/include
ln -s freetype1/freetype freetype
5.3.7 Install GD
This section describes the steps required to compile and install GD, one of the supporting components for MapServer.
- Remove the GD RPM if it is already installed
rpm -e gd-devel
rm -f /usr/lib/libgd.*
- Extract the tarball:
tar -zxf /usr/local/src/gd-2.0.7gif.tar.gz
- Configure for compilation:
cd /usr/local/src/gd-2.0.7gif
./configure --with-jpeg --with-freetype --with-png
- Compile and install the binaries:
make
make install
5.3.8 Install GDAL
This section describes the steps required to compile and install GDAL, one of the supporting components for MapServer.
- Extract the tarball:
tar -zxf /usr/local/src/gdal-1.1.8.tar.gz
- Configure for compilation:
cd /usr/local/src/gdal-1.1.8
./configure \
--with-libz \
--with-png \
--with-libtiff=internal \
--with-geotiff=internal \
--with-jpeg \
--without-jasper \
--without-python
- Compile and install the binaries:
make
make ogr-all
make install
- Install the libraries:
cd ..
/sbin/ldconfig
5.3.9 Install PHP
In the following steps you will compile, install and configure PHP. Note that for MapServer to work, PHP must be installed as a CGI and not as a module.
- Compile and install PHP binaries:
a. Extract the tarball:
tar -zxf /usr/local/src/php-4.3.2.tar.gz
cd /usr/local/src/php-4.3.2
b. Configure for the build:
rm -f config.cache
./configure --enable-force-cgi-redirect --enable-shared --with-config-file-path=/usr/local/apache2/conf --with-gd=/usr/local --with-jpeg-dir=/usr --with-png-dir=/usr --with-zlib-dir=/usr --with-freetype-dir=/usr --with-ttf --enable-gd-native-ttf --with-mysql --with-regex=system --enable-dbase --enable-track-vars --enable-ftp
c. Compile the binaries:
make
d. Install the binaries and copy the php cgi executable to the web server’s configured cgi-bin directory:
make install
cp /usr/local/bin/php /home/httpd/html/cgi-bin/php
e. Install the sample php.ini configuration file
cp php.ini-dist /usr/local/apache2/conf/php.ini
cd ..
- Edit /usr/local/apache2/conf/php.ini to set logging to file and the extension directory:
log_errors = On
extension_dir = /usr/local/lib/php/extensions/
- Edit /usr/local/apache2/conf/httpd.conf to configure the php CGI type within Apache:
a. Comment out the php module related lines:
# <IfModule mod_php4.c>
# AddType application/x-httpd-php .php .php4 .php3 .phtml
# AddType application/x-httpd-php-source .phps
# </IfModule>
b. Add the lines to configure PHP as a CGI type:
AddType application/x-httpd-php4 .php4 .php3 .phtml .php
Action application/x-httpd-php4 /cgi-bin/php
- Restart the Apache HHTP Server to cause the configuration changes to take effect:
/etc/rc.d/init.d/httpd restart
5.3.10 Install MapServer
- Compile and install MapServer
a. If required, link GD library compiled in PHP step
ln -s /usr/lib/libgd.so.1.8.4 /usr/lib/libgd.so
b. Extract the tarball:
tar -zxf /usr/local/src/mapserver-3.6.4.tar.gz
c. Configure options for the compile:
cd /usr/local/src/mapserver-3.6.4
./configure --without-tiff --without-jpeg --with-proj --with-gdal=/usr/local/bin --with-php=/usr/local/src/php-4.3.2 --with-gd=/usr/local --with-freetype=/usr/bin --with-wfs --with-wfs-client --with-wmsclient --with-ogr --with-gdal --with-libwww --enable-runpath --enable-force-freetype1 --enable-internal-ld-detect
d. Compilation of the ogr library requires C++. If required, modify the Makefile:
LD= c++
e. Compile and install the MapServer binary:
make
cp /usr/local/src/mapserver-3.6.4/legend /usr/local/src/mapserver-3.6.4/mapserv /usr/local/src/mapserver-3.6.4/scalebar /home/httpd/html/cgi-bin
- Build and install PHP Mapscript:
cd /usr/local/src/mapserver-3.6.4/mapscript/php3
make
cd /usr/local/src/mapserver-3.6.4
cp mapscript/php3/php_mapscript.so /usr/local/lib/php/extensions/php_mapscript_36.so
cp /usr/local/lib/php/extensions/php_mapscript_36.so /usr/local/lib/php/extensions/php_mapscript.so
cd /usr/local/lib/php/extensions
ln -s php_mapscript_36.so php_mapscript.so
- Set up the ms_tmp directory used by MapServer for temporary files:
a. Create the directory:
mkdir /tmp/ms_tmp
chmod 777 /tmp/ms_tmp
b. Also add the commands from the previous step to /etc/rc.d/rc.local to recreate the directory when the system reboots, after a /tmp cleanup.
c. Create a logical link for the ms_tmp directory on the web server
cd /home/httpd/html
ln -s /tmp/ms_tmp ms_tmp
- Configure a cron script to manage the files in ms_tmp:
a. Create "/etc/cron.daily/ms_clear_tmp.sh". For really busy sites you can alternatively place the file under /etc/cron.hourly/. The script should contain:
#! /bin/sh
#
# MapServer temporary file cleanup - run daily by cron
#
# Flush all files from /tmp/ms_tmp older than 6 hours (360 minutes)
#
find /tmp/ms_tmp -name "*.*" -amin +360 -exec rm -f {} \;
exit 0
b. Set the permissions on the newly created script:
chmod 755 /etc/cron.daily/ms_clear_tmp.sh
5.3.11 (Optional) Install Analog
Analog is a web server analysis and reporting tool that can be used with Apache to produce traffic reports for your site.
- Extract the tarball:
cd /usr/local/src
tar -zxf /usr/local/src/analog-5.24.tar.gz
cd /usr/local/src/analog-5.24
- Compile the binary
make
5.3.12 (Optional) Install Cronolog
Cronolog is a log rotation tool that can be used to manage web server logs.
- Extract the tarball:
cd /usr/local/src
tar -zxf /usr/local/src/cronolog-1.6.2.tar
- Configure for compiling
cd /usr/local/src/cronolog-1.6.2
./configure
- Compile and install the binaries:
make
make install
- Configure Apache to pipe log output through Cronolog by modifying /usr/local/apache2/conf/httpd.conf as follows:
VERIFY: LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
COMMENT OUT: # ErrorLog logs/error_log
ADD: ErrorLog "|/usr/local/sbin/cronolog /usr/local/apache2/logs/errors_%Y-%m-%d.log"
ADD: CustomLog "|/usr/local/sbin/cronolog /usr/local/apache2/logs/access_%Y-%m-%d.log" combined
- Restart Apache to put the configuration changes into effect.
5.3.13 Install E-GADS!
- Install E-GADS as for basic installation.
- Set up the build_shp script to update the search reports layer periodically using cron.
a. Edit the build_shp.php script to set the province number ($s_province) based on types_provinces.
b. Set up the entry in the root crontab:
(Example root crontab entry)
45 00,12 * * * /home/httpd/html/e-gads/build_shp.php >>/var/log/build_shp.log 2>&1
6 Pre-Installation on Microsoft Platforms
This section describes the steps for preparing a Microsoft Windows server to receive the E-GADS! Application.
If you aren't running Microsoft Windows server or advanced server (which include IIS), the best bet is probably to run Apache HTTPD. It's easy to install using the pre-compiled Windows binaries. I installed version 2.0 on my Windows 2000 Professional system and it works fine.
I have heard that you can't run a web server (register a domain name) on Windows XP home. I can't confirm this, although I have run this configuration on a Microsoft XP Home computer for testing and development.
Here are the steps:
1. Download and install Apache 2.0 from:
http://apache.mirror.secondchapter.info/httpd/binaries/win32/apache_2.0.47-win32-x86-no_ssl.msi
2. Download and install PHP 4.3 from:
http://www.php.net/get/php-4.3.3-Win32.zip/from/a/mirror
3. Add the php_mcrypt.dll extension which is used by E-GADS! for password encryption:
a. Obtain the php-4.3-mcrypt.zip file from http://ftp.proventum.net/pub/php/win32/misc/mcrypt/ and extract the contents. This zip file is also available at https://sourceforge.net/projects/e-gads/ in the files section under Supporting Software for Microsoft Windows.
b. Copy the libmcrypt.dll it to a directory in your server’s system path; for example, C:\WINNT\System32.
c. Copy the php_crypt.dll to your php extensions directory (defined under extensions= in your php.ini file).
d. Enable the extension by removing the leading semicolon on the extension=php_mcrypt.dll line in your php.ini file.
e. Restart Apache to cause php to use the new php.ini configuration.
4. Download and install MySQL 3.23 from:
http://www.mysql.com/downloads/download.php?file=Downloads%2FMySQL-3.23%2Fmysql-3.23.57-win.zip&mirror=http%3A%2F%2Fmysql.mirrored.ca%2F
5. Install e-gads under the Apache htdocs directory. (On my system it was D:\Program Files\Apache Group\Apache2\htdocs)
6. Set the MySQL admin password (see MySQL documentation)
7. Install E-GADS as for basic installation.
7 Utility scripts
Several utility scripts are provided for your convenience. These scripts are not required for normal operation but may be useful for specific applications. Familiarity with Perl, PHP and shell scripting is assumed. If you aren’t comfortable with modifying Perl, PHP and shell scripts, then it is probably best to just delete these files since they all require modification before use.
The following is a listing of E-GADS! application scripts. To use them, modify as required and place them in you E-GADS! directory.
§ /nb_pub_summary.php – This is an example PHP script that wraps formatting around the base_summary.php script output in order to generate html output suitable for a website (www.nbgsara.nb.ca in this case). In the NBGSARA application this script is called from a cronjob on a daily basis with output redirected to a file. The resulting file is then transferred to the website using the ftp_files.php script. Using this method, a page on the public web site is updated daily during off-peak hours instead of being called real-time thus reducing load on the E-GADS! application server and MySQL database.
§ /nb_pub_searches.php - This is an example PHP script that wraps formatting around the base_searches.php script output in order to generate html output suitable for a website.
§ /nb_pub_teams.php - This is an example PHP script that wraps formatting around the base_teams.php script output in order to generate html output suitable for a website.
§ /pub_emergency.php - This is a php script which can be called from within the E-GADS! application to display the emergency contacts report without having to be logged in. The emergency contacts report typically contains public information that you may want non-users to be able to access. If your local policies don’t permit public distribution of emergency contact information, simply remove this file.
§ /pub_events.php - This is a php script which can be called from within the E-GADS! application to display the event calendar report without having to be logged in. The event calendar report typically contains public information that you may want non-users to be able to access. If your local policies don’t permit public distribution of emergency contact information, simply remove this file.
§ /pub_summary.php - This is a php script which can be called from within the E-GADS! application to display the statistical summary report without having to be logged in. The statistical summary report typically contains public information that you may want non-users to be able to access. This is a high-level report covering statistical information of a non-specific nature which does not contain information related to individuals. It does contain general information (costs, response times, duration, etc.), a breakdown of searches by requesting agency, non-specific subject data (distance from PLS, outcome, activities), and a membership summary (total members and age statistics). If your local policies don’t permit public distribution of statistical summary information, simply remove this file.
§ /pub_searches.php - This is a php script which can be called from within the E-GADS! application to display the search summary report without having to be logged in. The search summary report typically contains public information that you may want non-users to be able to access. If your local policies don’t permit public distribution of search summary information, simply remove this file.
§ /pub_teams.php - This is a php script which can be called from within the E-GADS! application to display the teams report without having to be logged in. The teams report typically contains public information that you may want non-users to be able to access. If your local policies don’t permit public distribution of team information, simply remove this file.
The following scripts can be used for automation. Since most will contain the database admin user password, ensure the scripts are readable only by root and are placed in a secure directory no accessible by the web server user.
§ /utilities/backup_prod.sh – An extremely simple shell script to perform a hotcopy of the e-gads MySQL database.
§ /utilities/biabam - A GPL bash shell attachment mailer by Mads Martin Jørgensen. This script is used by all of the utility scripts that mail attachments.
§ /utilities/contacts.sh – A quick and dirty shell script to ftp a file as a daily backup.
§ /utilities/crypt.php – A PHP script that outputs an encrypted value for a user specified input field. This is useful for determining if the PHP crypt function is working on your system. The crypt function is required in order for the password system within E-GADS! to work. Call this page from web browser through your web server.
§ /utilities/db_backup.sh – This is a shell script that backs up a mysql database and emails it to specified recipients using Biabam and SendMail. This is a surprisingly effective way to store offsite backups of the database it is fairly small (small enough to be transferred as a tarball as a mail attachment, on most email systems < 3 MB).
§ /utiltities/db_director_report.pl- This is a Perl script that mails an html copy of the members flagged as Directors to specified recipients using Biabam and SendMail.
§ /utilities/db_emergency_mail.pl - This is a Perl script that mails an html copy of the emergency contacts to specified recipients using biabam and sendmail.
§ /utilities/db_event_cal_mail.pl – This is a Perl script that mails an html copy of the event calendar to specified recipients using biabam and sendmail. Perl must be installed in order to use this script. Call this script without options to use the c_flag.txt flag file (updated by E-GADS!’s event_save.php script) in order to determine if events have changed (this could be run daily via cron in order to mail an updated calendar when changes occur). Alternatively, run the script passing the –f option which will send a report regardless of the flag file state (for example, on a monthly basis).
§ /utilities/dump_vars.php – Dumps HTTP server variables using PHP.
§ /utilities/ftp_files.php – This PHP script is used to transfer specified files to an FTP server. This can be used with the nb_ scripts to publish reports to a separate server via cron.
§ /utilities/ftp_files.ini – This is the configuration file for the ftp_files.php script. The [Settings] section defines the ftp server, user and password. The [File1], [File2], [File…] sections define the file(s) to be transferred, one file or file pattern per section.
§ /utilities/restore_prod.sh– An extremely simple shell script to restore a hotcopy of the e-gads MySQL database.
The following scripts can be used to provide links from a public web server to your E-GADS! application server on a server operating on a network where neither static nor dynamic DNS can be supported. The NBGSARA E-GADS! system ran this way for a while until we changed internet connection suppliers. It’s a quirky little hack, but you might find it amusing or useful.
These are the files you’ll need if you want to implement this:
§ /utilities/ip_forward.cgi
§ /utilities/ip_link.cgi
§ /utilities/monitor.pl
The system works like this:
- monitor.pl is run on the E-GADS! server via cron periodically; for example, every 15 minutes. This is used to call the ip_link.cgi file on the public webserver.
- ip_link.cgi – This perl script on the public webserver is called by monitor.pl and updates the IP address of the E-GADS! server stored in files on the public webserver.
- ip_forward.cgi is used as a link on a web page on the public web server. You pass the URI for the target server as a CGI parameter to the script. The script takes the parameters and uses them to build a redirection URL using the stored IP address created by ip_link.cgi.
8 GNU Free Documentation License
GNU Free Documentation License
Version 1.2, November 2002
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
C. State on the Title page the name of the publisher of the Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
-- End of Document --