This file contains several notes on installation and configuration of PHP VOMS-Admin.
More information can be found visiting project web-site: 
    http://grid.org.ua/development/pva/
Since v0.6 operation manual is available, containing latest information.

INSTALLATION--------------------------------------------------------------------

To begin using PVA you just need to unpack distribution archive to desired 
location and chagne config file as described below, corresponding your settings.

Out of box installation from packages automatically set most parameters accordingly.
Man pages for pva-config(config.inc) and addvo.conf are available in distribution.

For compatibility with methods used by grid middleware, based on hardcoded URLs 
to JAVA-based VOMS-Admin you need to use rewrite rules on your web server. At the
KNU Cluster, we use nginx (http://nginx.ru) web-server on machine where PVA 
is running and this is example rewrites for nginx:

        # PHP.VomsAdmin
        location ~ ^/vomses {
                rewrite /vomses /voms redirect;
        }

        location ~ ^/voms/([a-zA-Z_.]+)/services/VOMSCompatibility$ {
            rewrite ^/voms/([a-zA-Z_.]+)/services/VOMSCompatibility$ /voms/VOMSCompatibility.php?vo=$1 last;
        }

	location ~ ^/voms/([a-zA-Z_.]+)/services/VOMSAdmin$ {
            rewrite ^/voms/([a-zA-Z_.]+)/services/VOMSAdmin$ /voms/VOMSAdmin.php?vo=$1 last;
        }

	location ~ ^/voms/([a-zA-Z_.]+)/services/VOMSACL$ {
            rewrite ^/voms/([a-zA-Z_.]+)/services/VOMSACL$ /voms/VOMSACL.php?vo=$1 last;
        }

	location ~ ^/voms/([a-zA-Z_.]+)/services/VOMSAttributes$ {
            rewrite ^/voms/([a-zA-Z_.]+)/services/VOMSAttributes$ /voms/VOMSAttributes.php?vo=$1 last;
        }

	location ~ ^/voms/([a-zA-Z_.]+)/services/VOMSRegistration$ {
            rewrite ^/voms/([a-zA-Z_.]+)/services/VOMSRegistration$ /voms/VOMSRegistration.php?vo=$1 last;
        }

        location ~ ^/voms/([a-zA-Z_.]+)/Configuration.do$ {
            rewrite ^/voms/([a-zA-Z_.]+)/Configuration.do$ /voms/?vo=$1&action=configuration redirect;
        }

        location ~ ^/voms/(conf|modules|interfaces|lang) {
            rewrite /voms last;
        }

        location ~ ^/voms/([a-zA-Z_\.]+)/*([^p]$|[^h]p$|[^p]hp$|[^\.]php$) {
           rewrite ^/voms/([a-zA-Z_\.]+)/* /voms/?vo=$1 redirect;
        }

They are not 100% pretty, but woks:) Apache rewrite rules is in file .htaccess
that included into distribution (scince v0.3). Since packaging to RPM and DEB 
was implemented (v0.5) pva.conf is the prefered way to configure Apache.

P.S. You may also comment the following line in index.php to prevent some 
possible PHP Warnings to be displayed:
    error_reporting(E_ALL); ini_set("display_errors", 1);
Error reporting is enabled pointedly to detect possible bugs in code.

P.P.S. Read also WEBSERVERS NOTES

LANGUAGES SUPPORT---------------------------------------------------------------

Depending on your browser default language, several translations are loaded. 
Curently, only English, Ukrainian and Russian languages avaliable. 

Language files are located in the "lang" directory of the project, and have 
the following format: <lang code>.inc

File lang/en.inc (english translation) always loaded by default. If more 
specific lang-file exists (e.g. uk.inc) it will be loaded to, redefining 
english values of variables.

Overriding a default translation (like adding more info about service level 
agreement for your instance of PVA) is possible using $lang_overlay directory.

You may contribute to project, translating lang-file to another languages.

GLOBAL SERVER CONFIGURATION-----------------------------------------------------

The set of parameters used by whole server (independently of VO) assigned 
in the file conf/config.inc (/etc/pva/pva-config in packaged version)

The following variables are handled:

PVA server pathes:
    $pva_install_path="/path/to/pva/directory";			- required
    $ca_certificates_path="/etc/grid-security/certificates";	- required 
    $mail_filecopies_path="/path/to/pva/mailcopies";		- optional(v0.2)

$pva_install_path must contain full path to PVA install folder. 
Required for proper operation with files (VO configs first of all)
$ca_certificates_path contains path to trusted CA directory
$mail_filecopies_path control feature added in v0.2 version (see below)

PVA numerical constants:
    $members_per_page=10;					- required
    $lastresort_permissions = 517;				- required

$members_per_page control the limit of VO members displayed on one page.
$lastresort_permissions define the permissions due to ACL2 rules of original 
JAVA VOMS-Admin. This is guest access permissions (http access).

PVA mailing settings
    $mail_from = "from@your.domain";				- required
    $mail_from_name = "PHP VOMS Admin";				- required
    $voms_admin_mail = "admin@your.domain";			- required(v0.2)

$mail_from and $mail_from_name is used when PVA sends e-mail. 
For user confirmation, admin notification, etc.
$voms_admin_mail used by "Contact VOMS Server Admin" and "Request VOMS 
resources for new VO" features since v0.2 as target address.

PVA interface customisations:
    $default_view = "listvogroups";                 - optional(v0.6.7)
    $lang_overlay = "/etc/pva/lang-overlay";        - optional(v0.6.7)

Since PVA version 0.6.7 in addition to default "List served VOs" view on main 
page (listvos), "VO groups" view has been implemented (listvogroups). 
VO groups are configured via vogroups file in PVA VOs configuration directory.
If groups are configured - switch to groups view is shown on the main page.
By default 'listvos' view is used for main page, but can be redefined by 
$default_view variable.

To customize PVA text in any translation since version 0.6.7 you can use 
$lang_overlay directory. Overlay directory processing is similar to PVA intenal lang 
directory: language files (like en.inc) should contain variables with desired
text value.

VOMSES CONFIGURATION------------------------------------------------------------

To configure VOs that must be served by PVA you need to create VO-dependend 
config files (this step can be done automatically with pva-addvo script).

Each VO has own config file <VO name>.conf palced in conf/vomses directory. 
This file contains the following varibles:

VO MySQL database parameters (required):
    $dbhost="localhost";
    $dbpasswd="###PASSWORD###";
    $dbname="voms_vo_name";
    $dbuser="voms";

VOMSD paremeters to genetare VO configuration (requred):
    $vo_port = "15102";
    $vo_host="fqdn.of.server";
    $vo_cert="/etc/grid-security/servercert.pem";

VO information (optional -> changed from web UI (0.3) -> suppressed by database values (0.6)):
    $defaultca="default CA DN";
    $vo_rules_link="http://link.to.vo.usage.rules";
    $vo_mainurl="http://vo.main.page/";
    $vo_description="Human readable VO name and/or purposes";

$defaultca parameter is used when choosing CA in dropdown lists as selected 
value by default (e.g. adding new users)
$vo_rules_link will appeared in new user registration form.
$vo_mainurl and $vo_description is handled since v0.2 and displayed on the main
page if set.

NOTE! Since v0.6 VO config parameters (except MySQL database parameters) valuable only 
on VO creation. Then parameters are stored in database and variables in file will be ignored.

DATABASE SCHEMA CHANGES REQUIRED------------------------------------------------------

Since version 0.6.5 this task can be acomplished with pva-dbschema-update script.
For already configured VO databases (PVA configuration files exists) schema update 
script invoked authomaticaly on package post-install.

If you want to change database manually migrating from original VOMS distribution with
JAVA VOMS-Admin you need to add aditional fields in `memb_req` table structure for 
proper registration requests handling:

ALTER TABLE `memb_req` 
ADD `institute` VARCHAR( 255 ) NOT NULL ,
ADD `phone` VARCHAR( 255 ) NOT NULL DEFAULT '',
ADD `comment` VARCHAR( 255 ) NOT NULL DEFAULT '' 

This fields are present in original Java-based VOMS-Admin web interface but 
not tracked by the system. I think that is good idea to handle this information 
and decided to add needed fields to database (0.1).

PVA version 0.6 adds aditional tables for transactions and replication handling.
For more information read README.transactions

Additional fields and tables does not affect backward compatibility.

WEBSERVER NOTES-----------------------------------------------------------------

With nginx webserver check that all necesarry SSL variables exported:
[root]# cat /etc/nginx/fastcgi_params_ssl
include /etc/nginx/fastcgi_params;

fastcgi_param HTTPS                 on;
fastcgi_param SSL_PROTOCOL          $ssl_protocol;
fastcgi_param SSL_CIPHER            $ssl_cipher;
fastcgi_param SSL_PROTOCOL_VERSION  $ssl_protocol;
fastcgi_param SSL_CLIENT_CERT       $ssl_client_raw_cert;
fastcgi_param SSL_CLIENT_S_DN       $ssl_client_s_dn;
fastcgi_param SSL_CLIENT_I_DN       $ssl_client_i_dn;
fastcgi_param SSL_CLIENT_VERIFY     $ssl_client_verify;


SPECIAL FUNCTIONAL FEATURES NOT SUPPORTED IN ORIGINAL JAVA-BASED VOMS-ADMIN-----

1. Ability to show a list of external VOs (configured and served by other 
servers). (since v0.2) 
List of this VOs must specified in conf/vomses/external file, that contains an 
array:
        $external_vos = array (
		"external VO1 name" => array (
			"vomsurl"	=> "external VO1 VOMS Sevrer URL",
			"description"	=> "external VO1 description",
			"mainurl"	=> "external VO1 homepage"
		),
		.....
		"external VOn name" => array (
                        "vomsurl"       => "external VOn VOMS Sevrer URL",
                        "description"   => "external VOn description",
                        "mainurl"       => "external VOn homepage"
                ),
        );

If an array or file not present - external VOs section will not shown by PVA.
With this feature descriptions and links to VO's web-site are also added to 
PVA main page.

P.S. This feature has been impemented on demand of UNG (UAG in the past) 
requirements to consolidate all ukrainian VOs in one list.

2. Contact VOMS Server Admin (since v0.2)
Form for sending messages to server admin. Any user may send message. 
If authenticated with user certificate - sending message is simple - just 
write a text and press "Send" button. If no authentication - kaptcha is used
to prevent bots spaming.

3. Request VOMS resources for new VO (since v0.2)
Another form, that provide ability to send request for new VO serving. 
All possible information about VO, that PVA hanle may be specified. Resulting 
message, that will be sent to VOMS server admin formated as ready to export 
BASH variables.

4. Automated addvo BASH-script (fully functional since v0.3)
Create database and table structure for VO. Create vomsd and PVA configs 
for new VO. (pva-addvo in packaged version) 

Works with varibles according to "Request VOMS resources" syntax.
To use script - edit "Configuration" section according to you settings and 
just execute script. You may also check and rewrite some templates in 
gen_vomsd_config() function if required.

pva-addvo man page is also available since v0.5.1

Example usage: 
VOPORT=15110 ./addvo ./mail_copies/new_VO_request_07_Jan_2010_11_36_17

5. VO Preferences (since v0.3)
VO Administrator now have an ability to change VO properties (description, 
links to VO rules and homepage, default CA) directly from PHP VOMS-Admin 
web-interface, without contacting VOMS server admin.

6. Dissmiss own VO membership (since v0.4)
Each user now have the link "Leave this VO", that allow to dismiss own 
membership in VO.

7. Transactions (since v0.6)
Any operations that change VO information used transactions. PVA able to 
store transactions log.

8. Replication (since v0.6)
Keep all transactions in sync beetwen several PVA servers. Replication is 
implementen on per-VO basis and may be controled from web-UI directly by 
VO-Admin without contacting with VOMS-server administrator.
Replicants are authomaticaly displayed in VO-list and added to vomses
configuration to improve usability.

9. VO groups (since v0.6.7)
VO groups are configured using conf/vomses/vogroups file. For more information
about the syntax please look for a comments inside vogroups file.

KNOWN RELATED ISSUES -----------------------------------------------------

Following issues exists for old MySQL vesions when using dots in database name.
PVA addvo script authomaticly change dots to underscores on the new VO database 
creation. Migrating from other solutions, please ensure database name does not 
contains dots for proper operation.

MySQL < 5.0 does not support dots in database names.
MySQL < 5.5 break stored procedures calls for database with dots.


