esoc European Space Operations Centre Robert-Bosch-Strasse 5 64293 Darmstadt Germany Tel: (49)615190-0 Fax: (49)615190485 www.esa.int SSA DC-I Part 1 - System Administration & Operations Manual Administrator and User Manual Prepared by Vincenzo Todisco - Barbara Scarda Reference SSA-DC-SW-SAOM-0001 Issue 1 Revision 1 Date of Issue 24/08/2012 Status Final Document Type Administrator and User Manual Distribution Daniel Fischer Gaspard Gendreau Gian Maria Pinna Gianpiero Di Girolamo Giulio Maira Serge Moulin Vicente Navarro Fabrizio Giordano
Title Issue 1 Revision 1 Author Vincenzo Todisco - Barbara Scarda Approved by Date 24/08/2012 Date Gianpiero Di Girolamo 01/09/2012 Reason for change Issue Revision Date Delivery for D2 1 0 17/02/2012 Final delivery 1 1 24/08/2012 Issue 1 Revision 0 Reason for change Date Pages Comment First delivery for D2 17/02/2012 all - Issue 1 Revision 1 Reason for change Date Pages Comment Format changed according to ESA standard template 24/08/2012 all - Page 2/53
Table of Contents 1. INTRODUCTION... 5 1.1. REFERENCE DOCUMENTS... 5 1.2. APPLICABLE DOCUMENTS... 5 1.3. ACRONYMS... 6 2. INSTALLATION AND CONFIGURATION... 7 2.1. BASELINE ENVIRONMENT... 7 2.2. SOFTWARE ENVIRONMENT... 7 2.3. HOSTNAME CONVENTION USED... 8 2.4. INSTALLATION SEQUENCE... 9 2.5. MYSQL INSTALLATION AND CONFIGURATION... 10 2.5.1. SERVER INSTALLATION... 10 2.5.2. CONFIGURATION... 10 2.6. OPENDS INSTALLATION AND CONFIGURATION... 11 2.6.1. PRECONDITIONS... 11 2.6.2. INSTALLATION... 11 2.7. OPENAM INSTALLATION AND CONFIGURATION... 12 2.7.1. PRECONDITIONS... 12 2.7.2. OPENAM MAIN CONFIGURATION... 12 2.7.3. CONFIGURATION SUMMARY... 16 2.7.4. UNINSTALL PROCEDURE... 22 2.7.5. OPENAM CUSTOMIZATION... 22 2.8. LIFERAY - CONFIGURATION... 23 2.8.1. PRECONDITIONS... 23 2.8.2. INSTALLATION... 23 2.8.3. CONFIGURATION... 23 2.8.4. CONNECTION WITH MYSQL... 26 2.8.5. REMOVE UNNECESSARY PLUGINS... 26 2.8.6. KNOWLEDGE BASE, KNOWN ISSUES... 27 2.9. LIFERAY PORTAL SETUP... 28 2.9.1. SETUP CONFIGURATION... 28 2.9.2. LIFERAY COMPONENT INSTALLATION... 28 2.9.2.1. ESA 3 COLUMNS LAYOUT... 28 2.9.2.2. ESA 2 COLUMNS LAYOUT... 28 2.9.2.3. THEME... 28 2.9.2.4. EDIT USER HOOK... 29 2.9.2.5. LOGIN... 29 2.9.2.6. REGISTRATION... 29 2.9.2.7. ITOP WEB INTERFACE... 30 2.9.2.8. SESSION EXTENSION... 31 2.9.2.1. APPLY LOOK&FEEL TO THE SSA TECHNICAL WEB PORTAL PAGES... 31 2.10. ITOP: INSTALLATION AND CONFIGURATION... 32 2.10.1. PRECONDITIONS... 32 2.10.2. INSTALLATION... 32 2.10.3. CONFIGURATION... 32 Page 3/53
2.11. AWSTATS INSTALLATION AND CONFIGURATION... 34 2.11.1. PRECONDITIONS... 34 2.11.2. INSTALLATION... 35 2.11.3. CONFIGURATION... 35 2.12. SERVICE PROVIDER INSTALLATION... 38 2.12.1. PRECONDITIONS... 38 2.12.2. INSTALLATION... 38 2.12.3. CONFIGURATION... 38 2.12.4. KNOWLEDGE BASE, KNOWN ISSUES... 39 3. OPERATIONS... 40 3.1. LIFERAY - ADMINISTRATION... 40 3.1.1. HOW TO CREATE A NEW ARTICLE AND SAVE IT INTO THE CMS (CONTENT EDITOR)... 40 3.1.2. HOW TO PUBLISH THE ARTICLE MAKING IT VISIBLE FOR THE VIEWERS (CONTENT APPROVER)... 41 3.1.3. HOW TO PUBLISH THE ARTICLE MAKING IT VISIBLE FOR THE VIEWERS (CONTENT APPROVER)... 42 3.2. LIFERAY - PUBLIC AND REGISTERED USERS... 43 3.2.1. PUBLIC USERS... 43 3.2.2. REGISTERED USERS... 43 3.3. ITOP - PUBLIC USERS... 47 3.4. ITOP - ADMINISTRATOR USER... 48 3.5. ITOP - SERVICE DESK USERS... 49 3.6. AWSTATS... 49 3.7. OPENAM... 50 3.8. OPENDS... 52 Page 4/53
1. Introduction This document includes the Installation and Configuration Guide for the SSA DC-I Part 1 system, the Administrator s Manual and the User manual. 1.1. Reference Documents Ref. Document Title Reference AD_001 SMT Use Cases and Business Process SSA-DC-SW-SRS-0003 AD_002 Technical Web Portal High-Level Components Description SSA-CS-SW-TN-0001 AD_003 SSA DC-I Part 1 - ICT Support to Pilot Data Centre Implementation - Statement of Work SSA-CO-SOW-0001 AD_004 SSA Web Portal Requirements Specification SSA-CS-SW-RD-0001 Liferay Portal website OpenAM website http://www.liferay.com http://forgerock.com/openam.html 1.2. Applicable Documents Ref. Document Title Reference AD_005 AWStats logfile analyzer 7.0 Documentation http://awstats.sourceforge.net AD_006 How to setup authentication with itop http://www.combodo.com AD_007 itop 1.0 User's Guide http://www.combodo.com AD_008 itop 1.2 Administrator s Guide http://www.combodo.com AD_009 itop implementation guide http://www.combodo.com AD_010 ObjectQuery Language Reference http://www.combodo.com AD_011 Portal Administrator's Guide http://www.liferay.com AD_012 OpenAM 10 Administration Guide http://forgerock.com/openam.html AD_013 OpenAM Policy Agent 3 Installation Guide http://forgerock.com/openam.html AD_014 OpenAM 10 Installation Guide http://forgerock.com/openam.html AD_015 OpenAM 10 Reference http://forgerock.com/openam.html OpenDS http://www.opends.org Page 5/53
1.3. Acronyms Acronym CMS DB DAO DMZ DR FAQ HA HTTP ICT IDP IMS ITIL LAN LDAP MMI PDC RBAC RDBMS SMT SOAP SP SSA SSL SSO UC URL VLAN VPN Description Content Management System Database Data Access Object De-Militarized Zone Disaster Recovery Frequently Asked Questions High Availability HyperText Transfer Protocol Information and Communication Technology IDentity Provider Identity Management System Information Technology Infrastructure Library Local Area Network Lightweight Directory Access Protocol Man-Machine Interface Personal Digital Certificate Role-Based Access Control Relational DataBase Management System Service Management Tool Simple Object Access Protocol Service Provider Space Situational Awareness Secure Socket Layer Single Sign On Use Case Uniform Resource Locator Virtual LAN Virtual Private Network Page 6/53
2. Installation and Configuration This section details all steps required for the Installation and Configuration of the SSA DC- I system. 2.1. Baseline Environment This installation and configuration guide is intended for a server machine with the following software baseline: Operating System: SUSE Linux Enterprise Server 11 SP1 Apache 2.2 Web Server JDK 6 (Java Development Kit) MySQL 5.1 (rdbms) 2.2. Software Environment In the table below are listed the main COTS components that should be installed in order to make the SSA infrastructure operational. OpenAM 953 OpenDS 2.2.1 AWStats 7.0 itop 1.2 Liferay 6.0.5 Glassfish Application Server 3.0.1 SSO Web Agent 3 for Apache 2.2 Page 7/53
2.3. Hostname Convention used The table below shows the hosts naming convention used in this document to refer to the SSA components as well as the relation between those servers and COTS components. Note that the information reported below should be intended as an example, as in the operational scenario the host names might be different. The SSA infrastructure is built upon three servers: One server hosting the Web Portal and the IMS. One server hosting the SMT and the Statistic tool. One server hosting the RDBMS and the DS. Physical Server Server Aliases COTS Component DNS/ Hosts file Web Portal and IMS server SMT and Statistic server RDBMS/DS server portal.ssa.esa.int Liferay Portal DNS sso.ssa.esa.int OpenaAM DNS stats.ssa.esa.int AWstats DNS smt.ssa.esa.int Combodo itop DNS db.ssa.esa.int MySQL Hosts file ds.ssa.esa.int OpenDS Hosts file Please note that for those servers having into the DNS/Hosts file column the value Hosts file a registration in the DNS is not needed as they will be referenced only by SSA servers and not directly by the SSA user. Before proceeding with the installation of single components, please insert the aliases into the hosts file of all servers and be sure that all servers are reachable from each other. Page 8/53
2.4. Installation sequence As components have dependencies on other components the following installation sequence is suggested. o MySQL: installation and configuration (sect. 2.5) o OpenDS: installation and configuration (sect. 2.6) o OpenAM: installation and configuration (sect. 2.7) o Liferay Glassfish Bundle: configuration (sect. 2.8) o Liferay Glassfish Bundle: Portal Setup (sect. 2.9) o itop: installation and configuration (sect. 2.10) o AWStats: installation and configuration (sect. 2.11) o Web Agent (sect. 2.12) Page 9/53
2.5. MySQL Installation and Configuration This section deals with the essential details of the installation and configuration of MySql for the project at hand. Please refer to the MySql web site, www.mysql.com/ for a thorough documentation on getting, installing and configuring the MySql database 2.5.1. Server Installation On the target machine (db.ssa.esa.int) install the RDBMS MySQL Server using the target package installer (e.g. for SUSE use Yast2 from command line or Software Management through the graphical interface). 2.5.2. Configuration In order to make the MySQL server secure please remember to change the administrator (root) password using the command: mysqladmin -u root -p <new-password> After having changed the administrator password, check it by logging into MySQL server with the command: mysql u root -p (then enter the password) Restore the databases of Liferay and itop coming with the final delivery DC-I. In order to do that, type following commands into the db.ssa.esa.int server: Restore Liferay DB: mysql < Liferay.SQL -u root -p This command will create the databases ssalportal into MySQL Server prepared by Serco Team and already configured with some features. Restore itop DB mysql < itop.sql -u root -p This command will create the database itop into MySQL Server already configured. If after the restore of databases you encounter some issues in connecting to the MySQL Server, please refer to the official MySQL documentation to update privileges of users on single databases. For any further information in MySQL administration/installation, please refer to the official documentation. Page 10/53
2.6. OpenDS Installation and configuration This section deals with the steps for installing the OpenDS version 2.2.1 software package into the ds.ssa.esa.int server. The installation consists in unzipping the provided installation file OpenDS-2.2.1.zip, move its unzipped content into the intended directory (e.g. /opt/opends directory), ensure access rights and then run the setup command. Please refer to the OpenDS web site, https://www.opends.org/1.0, for further information on the product. 2.6.1. Preconditions The JDK 6 (not only the JRE) has to be already installed onto the machine 2.6.2. Installation Unzip the OpenDS-2.2.1.zip file provided in the installation bundle: unzip OpenDS-2.2.1.zip Assuming that the installation directory that suits your linux server is /opt, move and rename the unzipped content into /opt/opends, with a command as the following: mv OpenDS-2.2.1 /opt/opends move to the /opt directory and assign the 755 rights the the OpenDS directory recursively: cd /opt: chmod -R 755 OpenDS enter the OpenDS/ directory, run the setup command as root and complete the setup procedure: cd OpenDS/./setup & By default the OpenDS listen on port 389. For further details refer to the official documentation of OpenDS listed on the Applicable Documents paragraph. For any further information in OpenDS administration/installation, please refer to the official documentation. Page 11/53
2.7. OpenAM Installation and configuration This section details the installation of the IMS (Identity Management System) component that is part of the ForgeRock OpenAM Identity Services software module. This procedure references the openam_953.war file, provided with the installation bundle and also available for download from the ForgeRock website, as of April 2011, at the following address: http://www.forgerock.org/downloads/openam/snapshot9.5/openam_953.war The ForgeRock website also provides a comprehensive documentation at the address: https://wikis.forgerock.org/confluence/display/openam/add+authentication+to+a+web site+using+openam The package LiferaySSA-Glassfish.tar delivered contains OpenAM war file already deployed into Glassfish. It needs only too be configured. Untar as user root the package LiferaySSA-Glassfish.tar into the opt/ directory of portal.ssa.esa.int: tar xvf LiferaySSA-Glassfish.tar /opt/ The new directory Liferay should be created (/opt/liferay). Grant executable rights to the executable files inside the main glassfish directory and the bin directory. 2.7.1. Preconditions The file /opt/liferay/domains/domain1/config/domain.xml shall display the following parameters: -Xmx1024m; -XX:MaxPermSize=256 The OpenDS software is up and running 2.7.2. OpenAM Main Configuration NOTE: please replace the placeholder for the parameter values provided in the following examples with your own current values for the all the intended fields, such as the fully qualified domain name, the cookie domain, ldap configuration, etc. This section uses a series of screenshot to illustrate the OpenAM main configuration, please note that the actual screenshots and windows displayed during the process may be different from the ones here presented. Page 12/53
Please note that to configure OpenAM, the application server Glassfish should be up and running. Open a supported browser and go to the address: sso.ssa.esa.int:80/openam_953 A page like the one depicted below should be displayed: START Click on "Create New Configuration" and proceed with the following steps: 1) set amadmin password 2) set server URL as <hostname>.<domain name> (e.g. http://sso.ssa.esa.int:80/) Page 13/53
IMPORTANT NOTE: please ensure that the server URL is valid and reachable, otherwise at step (3) the value for the configuration ports field has to be "-1" Set cookie domain as. <domain name> (e.g..ssa.esa.int) (ensure that the cookie domain start with a dot character) Set configuration folder to /opt/openam_953 3) set root suffix for your LDAP environment as you defined into the OpenDS configuration (e.g. dc=ssa,dc=esa,dc=int ) Select First Instance, OpenSSO and as Port use 50389. Page 14/53
4) select external LDAP, then choose OpenDS and then fill in the fields as provided next: Set directory name (e.g. ds.ssa.esa.int). Page 15/53
Set the port as 389. Set the value for your root suffix (e.g. dc=ssa,dc=esa,dc=int ). Set the admin username (default to Directory Manager) and the admin password as you have already set into OpenDS. 5) select "no" to load balancer 6) set the UrlAccessAgent password 2.7.3. Configuration Summary Page 16/53
If the configuration procedure fails remove the folder /opt/openam_953 in order to be able to restart the process from step (1) If any problems arise during this phase, the following actions are recommended in order to clean it all and restart the process: remove the configuration folder /opt/openam_953 undeploy OpenAM using the Glassfish admin tool stop/start Glassfish re-deploy the openam_953.war file delivered on Glassfish (please see Deploy on Glassfish above) At this point OpenAM is installed and configured. Now you should configure some webagents by using the GUI provided by OpenAM. In order to do that, points your browser to: http://sso.ssa.esa.int/openam_953 After having inserted admin credentials the following page should be displayed: Go to Configuration-->Servers and Sites-->Default Settings Set the com.iplanet.am.cookie.c66encode property as "true" Page 17/53
Go to the Access Control tab, clicks on Top Realm, then on Agents tab. Now let s create 3 Policy Agents, one for Liferay, one for the SMT and one for the Statistics tool. The page of Policy Agent creation is like the following: Below the details to create all needed Policy Agents. o Liferay Policy Agent: Name: name of the agent (e.g. tnportalagent) Password: choose one password and remember it. Configuration: Centralized Server URL: the OpenAM deployment URL (e.g. http://sso.ssa.esa.inr:80/openam_953) Agent URL: the protected resource (e.g. http://portal.ssa.esa.int:80) o Apache Web Policy Agent: Name: name of the agent (e.g. apacheagent) Password: choose one password and remember it. Configuration: Centralized Server URL: the OpenAM deployment URL (e.g. http://sso.ssa.esa.inr:80/openam_953) Agent URL: the protected resource (e.g. http://smt.ssa.esa.int:80/) Page 18/53
Into Application tab of the Apache Web Agent enable Ignore Path Info for Not Enforced URLs and add the webservices of the SMT (e.g. http://smtssa.dev.eng.serco.eu/web/webservices/*). Check if into the Policy Agent page the FQDN option is disabled and SSO Only is enabled. Ensure that CDSSO is disabled in the Agent configuration "SSO" tab. Click on Subject and add the following users needed to administer and test the SSA infrastructure: o Liferay Technical Portal Administrator userid: tnadmin password: pass4tnadmin email: admin.tn@ssa.esa.int firstname: tnadmin lastname: tnadmin fullname: tnadmin tnadmin o SMT Administrator userid: itopremoteadmin password: pass4itop email: itop.remoteadmin@ssa.esa.int firstname: itop lastname: Admin fullname: itop Admin o SMT Technical Portal ICT Support Team (for ESA internal) userid: ictsupport password: pass4itop email: ictsupport@ssa.esa.int firstname: ICT lastname: Support fullname: ICT Support o SMT General Helpdesk Team (for open public) userid: helpdesk password: pass4itop Page 19/53
email: helpdesk@ssa.esa.int firstname: Public lastname: Helpdesk fullname: Public Helpdesk o SMT Neo Service Desk Team userid: neodesk password: pass4itop email: helpdesk.neo@ssa.esa.int firstname: NEO lastname: Helpdesk fullname: NEO Helpdesk o SMT SWE Service Desk Team userid: swedesk password: pass4itop email: helpdesk.swe@ssa.esa.int firstname: SWE lastname: Helpdesk fullname: SWE Helpdesk o SMT SST Service Desk Team userid: sstdesk password: pass4itop email: helpdesk.sst@ssa.esa.int firstname: SST lastname: Helpdesk fullname: SST Helpdesk o SMT Web Service for TN Portal userid: itopwebservice password: pass4itop email: itopwebservice@ssa.esa.int firstname: itopwebservice lastname: itopwebservice fullname: itopwebservice itopwebservice o AWStats Test Public User userid: statsuser Page 20/53
password: pass4statsuser email: statsuser@ssa.esa.int firstname: Stats lastname: User fullname: Stats User o Liferay/SMT Public Test User userid: portaluser password: pass4portaluser email: portaluser@ssa.esa.int firstname: Portal lastname: User fullname: Portal User o SMT ESA Test User userid: esauser password: pass4esauser email: esauser@ssa.esa.int firstname: Esa lastname: User fullname: Portal User After having configured all accounts as described above, it is possible to modify them or create other accounts referring to the relevant official documentation (Combodo itop, Liferay, OpenAM). Please note that some details of any new account should be defined in order to make the SSO working as expected. Those details are listed into the table below. Into rows are listed the applications and into columns is listed how it is named the account details inside the application. Application Userid Firstname Lastname Password Fullname Email itop Liferay Login (Account) Screen Name Name (Contact) First Name (Contact) Not needed Not needed Email (Contact) First Name Last Name Password Not needed Email Address OpenAM ID First Name Last Name Password Full Name Email Address Page 21/53
Into itop all users that need to use the SSO should be created into itop as External user. 2.7.4. Uninstall procedure To uninstall the software module follow these steps: Rename the configuration directory of OpenAM under the path /opt (/opt/openam_953) From the server machine where Glassfish is installed, open the Glassfish admin tool at the (default) address: http://ds.ssa.esa.int:4848 Click on "List of deployed applications" Select openam_953 Click undeploy 2.7.5. OpenAM customization OpenAM Login page: copy and overwrite the file "loginopenam.jsp" into the following path "/usr/liferay/glassfish- 3.0.1/domains/domain1/applications/openam_s951/config/auth/default" (where /usr/ is the path where the bundle liferay/glassfish has been installed) Banner on OpenAM: 1) create ssa "folder" inside /usr/liferay/glassfish- 3.0.1/domains/domain1/applications/openam_s951/images 2) copy the file inside the new folder For any further information in OpenAM administration/installation, please refer to the official documentation. Page 22/53
2.8. Liferay - Configuration This section deals with the essential details of the installation and configuration of Liferay. The Liferay version being used is shipped bundled with the Glassfish application server. Untar the file Liferay.tar into /opt directory. Please refer to the Liferay web site, http://www.liferay.com/, for a thorough documentation on the subject. 2.8.1. Preconditions The JDK 6 (not only the JRE) has to be already installed onto the machine. OpenDS installed and configured. OpenAM installed and configured 2.8.2. Installation At this point you should already have Liferay available into your filesystem. If not see chapter OpenAM Installation and Configuration. The package we delivered contains Liferay and Glassfish partially configured. Some minor changes/update on the configuration should be done as described in the next paragraphs. 2.8.3. Configuration Before proceed with this section, please be sure to have OpenAM already installed and configured. Login to the Liferay Portal through: http://portal.ssa.esa.int/c/portal/login with the preconfigured admin account: userid: tnadmin password: pass4tnadmin Update through the Liferay control panel the different section as described above: Control Panel -> Settings -> Authentication -> General Check that How do users authenticate? is set to By Screen Name. Check that all checkbox are unchecked. Control Panel -> Settings -> Authentication -> LDAP Page 23/53
On the LDAP Servers section click on Edit of the preconfigured opends server. o Check that into Default Values nothing is set. o Into Connection section Base Provider URL: update with the production hostname of the OpenDS server (e.g. ldap://ds.ssa.esa.int:389). Base DN: check if it is set as it has already been defined into the OpenDS configuration (e.g. ou=people,dc=ssa,dc=esa,dc=int) Principal: check if the credentials of OpenDS administrator are correct (e.g. cn=directory Manager,cn=Root,cn=config). Credentials: insert the correct password of OpenDS administrator provided during the configuration of OpenDS. Click on Test LDAP Connection. o On the Users section: Authentication Search Filter: (uid=@screen_name@) Import Search Filter: (objectclass=inetorgperson) Screen Name: uid Password: userpassword Email Address: mail Full Name: givenname Last Name: sn Group: groupmembership Click on Test LDAP Users : almost the tnadmin account should be displayed. o On the Groups section: Nothing to do o On the Export section: User DN: the exporting LDAP object configuration (e.g. ou=people,dc=ssa,dc=esa,dc=int). User Default Object Classes: person Groups DN: not used (e.g. ou=groups,dc=ssa,dc=esa,dc=int) Group Default Object Classes: top,groupofuniquenames o Click on Save button. Page 24/53
If all tests terminated with success click on Enabled checkbox into the main section. On the Import / Export section check if Import Enabled is checked. Leave Use LDAP Password Policy unchecked. Control Panel -> Settings -> Authentication -> CAS All disabled. Control Panel -> Settings -> Authentication -> Facebook All disabled. Control Panel -> Settings -> Authentication -> NTLM All disabled. Control Panel -> Settings -> Authentication -> OpenID All disabled. Control Panel -> Settings -> Authentication -> Open SSO Login URL: the URL composed by the OpenAM + the Technical Portal Login page (e.g. http://sso.ssa.esa.int:80/openam/ui/login?goto=http://ssa.esa.int:80/c/portal/lo gin). Logout URL: the URL composed by the OpenAM + the Technical Portal public home page page (e.g. http://sso.ssa.esa.int:80/openam/ui/logout?goto=http://ssa.esa.int:80/web/ssa/ home). Service URL: the URL of OpenAM (e.g. http://sso.ssa.esa.int:80/openam). Screen Name Attribute: uid. Email Address Attribute: mail. First Name Attribute: givenname. Last Name Attribute: sn. Click on Test OpenSSO Configuration and if it ends with success, check Enabled and LDAP Import Enabled checkboxes. Control Panel -> Settings -> Authentication -> SiteMinder All disabled. Page 25/53
2.8.4. Connection with MySQL Check if the configuration file portal-ext.properties located into /opt/liferay/domain/domain1/ liferay-portal/web-inf/classes appears as detailed below: # MySql Connection on server localhost jdbc.default.driverclassname=com.mysql.jdbc.driver jdbc.default.url=jdbc:mysql://db.ssa.esa.int:3306/ssalportal?useunicode=true&character Encoding=utf-8&useFastDateParsing=false jdbc.default.username=root jdbc.default.password=<root password> please replace the <root password> place holder with the actual root password, as chosen in the steps above. Stop Glassfish (if running) with the command: /opt/liferay/glassfish/bin/stopserv Restart Glassfish (if stopped) with the command: /opt/liferay/glassfish/bin/startserv IMPORTANT NOTE: if after this operation the virtualhosting stops working, then drop the database and repeat the entire process. 2.8.5. Remove unnecessary plugins The 7Cogs plugins installed by the default can be safely removed as to keep the environment as much clean as possible; for this purpose follow the next guidelines: Go to the Glassfish administration tool at the address http://portal.ssa.esa.int:4848 There perform the following actions: remove the 7Cogs hook remove the 7Cogs theme remove the 7Cogs mobile theme remove the chat-portlet remove the opensocial remove the google-maps remove the social-networking Page 26/53
Once done go into the "Configuration" section, select "JVM settings and then select the "JVM Options" Tab. In the displayed page ensure that the following parameters are set -Xmx1024m - XX:MaxPermSize=256m 2.8.6. Knowledge base, known Issues Issue: Glassfish does not start with error: cannot write domain folder. Solution: ensure that you are logged as root IMPORTANT NOTE: An error is returned if editing a user that does not have a "Title" defined (Mr.Dr.Ms, etc.) a hook has been created with name edit-user-hook to solve the problem. Issue: java.io.ioexception: Cookie names from OpenSSO service are not accessible Solution: this error occurs if the IDP cannot be reached, check the network and name resolution If the proxy-pass is used, check that UseCanonicalName and UseCanonicalPhysicalPort are both set to Off (see: http://httpd.apache.org/docs/current/mod/core.html#usecanonicalphysicalport) Issue: Liferay session has no apparent limit, while OpenAM has Max Session Time. This creates situation where Liferay session is active and OpenAM session has been invalidated Solution: Mitigate the risk of having the described situation by setting OpenAM Max Session Time = 720 (12 hours) The setting is possible inside Configuration --> Global --> Session For any further information in Liferay administration/installation, please refer to the official documentation. Page 27/53
2.9. Liferay Portal Setup This chapter illustrates the basic details of the Liferay Portal Setup. 2.9.1. Setup Configuration Check through the Liferay Control Panel if the commun ity SSA exists. Check if the Administrator user (tnadmin exists and has the administrator role). Create your users: <user-1>, <user-2>,.<user-n> inside SSA community (refer to the Liferay official documentation for this). 2.9.2. Liferay Component Installation This section explains how to install the developed Liferay components/plugins. The installation can be done in several way, the selected one is deemed to be the easiest. In order to install the plugins the following initial steps are necessary: 1) go to the Technical Web Portal home page and login with "Administrator" privileges. 2) Click on Manage on the displayed bar and then on "Control Panel" 3) Click on "Plugins Installation" from the left column, "Server" section 2.9.2.1. ESA 3 columns Layout 1) Click on the "Layout Template Plugins" link 2) Click on "Install More Layout Templates" button 3) Click on "Upload File" link 4) Click on "Browse" button and select the "SSAEsaLayout.war" 5) Click on "Install" 2.9.2.2. ESA 2 columns Layout 1) Click on the "Layout Template Plugins" link 2) Click on "Install More Layout Templates" button 3) Click on "Upload File" link 4) Click on "Browse" button and select the "SSAEsaLayout2Colums.war" 5) Click on "Install" 2.9.2.3. Theme 1) Click on the "Theme Plugins" link 2) Click on "Install More Theme" button 3) Click on "Upload File" link 4) Click on "Browse" button and select the "SSAEsa-theme.war" 5) Click on "Install" Page 28/53
2.9.2.4. Edit User hook 1) Click on the "Portlet Plugins" link 2) Click on "Install More Portlets" button 3) Click on "Upload File" link 4) Click on "Browse" button and select the "edit-user-hook-6.0.5.1.war" 5) Click on "Install" 2.9.2.5. Login 1) Click on the "Portlet Plugins" link 2) Click on "Install More Portlets" button 3) Click on "Upload File" link 4) Click on "Browse" button and select the "OpenAmLogin.war" 5) Click on "Install" 6) After the portlet has been correctly deployed into Glassfish, go to the configuration file config.xml located into the applications folder of Glassfish (e.g. /opt/liferay/glassfish-3.0.1/domains/domain1/applications/openamlogin/conf) and update the above fields as for the operational scenario: <openamadminuser><!-- OpenAM-admin --></openamadminuser> <openamadminpassword><!-- OpenAM-admin-password -- ></openamadminpassword> <openamurl><! OpenaAM-url --></openamurl> <loginredirecturl><! Resource-url --> </loginredirecturl> Replace <!-- OpenAM-admin --> with the userid of the OpenAm administrator (e.g. amadmin) as already defined into paragraph 2.7. Replace <!-- OpenAM-admin-password --> with the password of the OpenAm administrator as already defined into paragraph 2.7. Replace <! OpenaAM-url --> with the URL where OpenAm has been deployed (e.g. http://sso.ssa.esa.int:80/openam_953). Replace <! Resource-url --> with the URL where OpenAm should redirect the user browser after authentication (e.g. http://portal.ssa.esa.int:80/group/ssa/home). 2.9.2.6. Registration 1) Click on the "Portlet Plugins" link 2) Click on "Install More Portlets" button Page 29/53
3) Click on "Upload File" link 4) Click on "Browse" button and select the "OpenAmLogin.war" 5) Click on "Install" 6) Copy the file Activation.jsp into /usr/liferay/glassfish- 3.0.1/domains/domain1/applications/liferay-portal folder (throgugh a file transfer client) 7) After the portlet has been correctly deployed into Glassfish, go to the configuration file config.xml located into the applications folder of Glassfish (e.g. /opt/liferay/glassfish- 3.0.1/domains/domain1/applications/OpenAmRegistration/conf) and update the above fields as for the operational scenario: <openamadminuser><!-- OpenAM-admin --></openamadminuser> <openamadminpassword><!-- OpenAM-admin-password -- ></openamadminpassword> <openamurl><! OpenaAM-url --></openamurl> <activationurl><! Activation-url --></activationurl> <activationemailfrom><! Activation-email --> </activationemailfrom> <Service><! Service-url --> </Service> Replace <!-- OpenAM-admin --> with the userid of the OpenAm administrator (e.g. amadmin) as already defined into paragraph 2.7. Replace <!-- OpenAM-admin-password --> with the password of the OpenAm administrator as already defined into paragraph 2.7. Replace <! Activation-url --> with the URL where is placed the file activation.jsp (e.g. http://portal.sso.ssa.esa.int:80/activation.jsp). Replace <! Activation-email --> with the email of the sender of the activation email (e.g. webmaster@ssa.com). Replace <! Service-url --> with the URL of the web service exposed by itop (e.g. http://smt.ssa.esa.int:80/web/webservices/soapserver.php). It is placed into itop directory webservices/soapserver.php. 7) Create under the liferay-portal deployment directory the directory named captcha (e.g. /opt/liferay/glassfish-3.0.1/domains/domain1/applications/liferayportal/captcha) 2.9.2.7. ITOP Web Interface 1) Click on the "Portlet Plugins" link 2) Click on "Install More Portlets" button 3) Click on "Upload File" link Page 30/53
4) Click on "Browse" button and select the "ITOPWebInterface.war" 5) Click on "Install" 6) After the portlet has been correctly deployed into Glassfish, go to the configuration file config.xml located into the applications folder of Glassfish (e.g. /opt/liferay/glassfish-3.0.1/domains/domain1/applications/ ITOPWebInterface /conf) and update the above fields as for the operational scenario: <Service><! Service-url --> </Service> Replace <! Service-url --> with the URL of the web service exposed by itop (e.g. http://smt.ssa.esa.int:80/web/webservices/soapserver.php). It is placed into itop directory webservices/soapserver.php. 2.9.2.8. Session extension Copy and overwrite the file session.js into /usr/liferay/glassfish- 3.0.1/domains/domain1/applications/liferay-portal/html/js/liferay 2.9.2.1. Apply Look&Feel to the SSA Technical Web Portal pages 1 o Apply the layout template to the ssa community 1) go to the Technical Web Portal home page and login with "Administrator" privileges. 2) Click on "Manage" on the displayed bar and then on "Page Layout" 3) Check the SSA ESA Layout and save o Apply the theme to the ssa community 1) From the "Control Panel" click on "Communities" under "Portal" section 2) Click on "Action" and then "manage Pages" on the ssa community 3) CLick on Look&Feel 4) Click on the SSA ESA Theme 5) Click on "Private Pages" and follow again the steps from 1 to 4 1 Only the IRE environment. Then the DB synchronisation will avoid those steps in production. Page 31/53
2.10. itop: installation and configuration In this paragraph it is explained how it is possible to make install and configure itop. 2.10.1. Preconditions Apache 2.2 installed MySQL 5 installed and configured (itop database available as described into paragraph 2.5). File /etc/hosts configured with the alias of the SMT (e.g. smt.ssa.esa.int) on the public interface. 2.10.2. Installation Untar the package itop.tar given with the final delivery into the server smt.ssa.esa.int inside the directoty /srv/www/htdocs. The directory smt should be created. cd /srv/www/htdocs/ tar xvf SMT.tar. chown R <apacheuser>:<apachegroup> smt/ 2.10.3. Configuration Add the following configuration lines into your Apache virtual host configuration file (e.g. in SUSE /etc/apache2/vhosts.conf): <VirtualHost *:80> DocumentRoot /srv/www/htdocs/smt ServerName smt.ssa.esa.int DirectoryIndex index.php Options Indexes FollowSymLinks ErrorLog /var/log/apache2/itop_error.log CustomLog /var/log/apache2/itop_access.log common </VirtualHost> Update the itop configuration file config-itop.php placed into main directory of itop (e.g. /srv/www/htdocs/smt/web) with data related to the operational scenario: Page 32/53
'db_host' => 'db.ssa.esa.int', 'db_user' => 'root', 'db_pwd' => 'pass4root', 'db_name' => 'itop', Restart Apache and point your browser to the SMT home page (e.g. http://smt.ssa.esa.int/web) and test the access with the admin preconfigured local itop user: User: itopadmin Password: pass4itop Please note that this user is configured to not use SSO authentication. In this way if the SSO server is down, the admin user is still able to access to the SMT. For any further information in itop administration/installation, please refer to the official documentation. Page 33/53
2.11. AWStats installation and configuration In this paragraph it is explained how to make the statistic tool AWStats working properly. This tool is used to perform the access statistic on the Technical Portal. In order to do that, it should be enable the access Apache standard log on Glassfish. To do that, access to the Glassfish admin console (e.g. http://portal.ssa.esa.int:4848) and enable the access log: 2.11.1. Preconditions Apache 2.2 installed. Perl installed File /etc/hosts configured with the alias of the Statistic Tool (e.g. stats.ssa.esa.int) on the public interface. Page 34/53
2.11.2. Installation Untar the package AWStats.tar.tar given with the final delivery into the server stats.ssa.esa.int inside the directoty /srv/www/htdocs. The directory stats should be created. cd /srv/www/htdocs/ tar xvf STATS.tar. chown R <apacheuser>:<apachegroup> stats/ 2.11.3. Configuration Create the /etc/awstats directory and copy the conf file awstats.technicalportal.conf provided with the delicery inside it. This file contains the configuration for the Technical Portal. As AWStats is a log analysing tool it need logs to perform statistics. As logs are those of Technical Portal, they are into the other server portal.ssa.esa.int. Create into the server hosting portal.ssa.esa.int the following bash script sendlogs.sh (or copy it from the delivery package): Code Listing: sendlogs.sh #!/bin/bash date='date +"%Y-%m-%d"' indir='/opt/liferay/glassfish-3.0.1/domains/domain1/logs/access' outdir='/srv/www/htdocs/awstats/external-logs' logserver='stats.esa.int' user='ssaadm' scp -l ${user} ${indir}/server_access_log.${date}.txt ${logserver}:${outdir} Where: indir is the directory which contains the access log. outdir is the directory into the stats.ssa.esa.int server where AWStats expects to find the log file. logserver is the hostname of the server hosting AWStats. user is the remote user with which transfer the log file through SSH connection. Modify indir, outdir, logserver and user as on the operational scenario. Make sure that into stats.ssa.esa.int server the outdir exists. In case of not, remember to create it before testing the log transfer. Page 35/53
Insert it into crontab of portal.ssa.esa.int the following job which send every days at 01:00 AM the access log of portal.ssa.esa.int to stats.ssa.esa.int via SSH: 00 01 * * * <path to sendlogs.sh>/sendlogs.sh IMPORTANT NOTE: generate SSH keys in order to make this transfer password independent. Back to the stats.ssa.esa.int server create the Apache configuration file /etc/apache2/vhosts/awstats.conf and add the following configuration lines into it: <VirtualHost *:80> DocumentRoot /srv/www/htdocs/awstats ServerName stats-ssa.dev.eng.serco.eu DirectoryIndex index.php Alias /awstatsclasses "/srv/www/htdocs/awstats/wwwroot/classes/" Alias /awstatscss "/srv/www/htdocs/awstats/wwwroot/css/" Alias /awstatsicons "/srv/www/htdocs/awstats/wwwroot/icon/" ScriptAlias /awstats/ "/srv/www/htdocs/awstats/wwwroot/cgi-bin/" <Directory "/srv/www/htdocs/awstats/wwwroot"> Options None AllowOverride None Order allow,deny Allow from all </Directory> ErrorLog /var/log/apache2/stats_error.log CustomLog /var/log/apache2/stats_access.log common </VirtualHost> Remember to change the ServerName and other directives above in order to be compliant with the operational scenario. Restart Apache and point your browser to the Statistic Tool home page (e.g. http://stats.ssa.esa.int/web) and test the access. Add into root crontab the following job which is in charge of update statistics on awstats: 00 02 * * * perl /srv/www/htdocs/awstats/wwwroot/cgi-bin/awstats.pl -config=technicalportal Page 36/53
This makes the statistics update every day. For any further information in AWStats administration/installation, please refer to the official documentation. Page 37/53
2.12. Service Provider Installation This section details the installation of the Web Policy Agent Service Provider. The ForgeRock website also provides a comprehensive documentation at the address: https://wikis.forgerock.org/confluence/display/openam/web+server+configuration 2.12.1. Preconditions For the installation of the Service Provider the following preconditions are to be met: Java 6 installed Apache 2.2 installed The software package apache_v22_linux_agent_3.zip has to be available The Root account (root password) has to be available during the procedure The OpenAM admin account (amadmin password) has to be available during the procedure OpenAM shall be up and running 2.12.2. Installation Store the password for the agent created at paragraph 2.7 for the Web Policy Agent into a file /tmp/passwd; this will only last for the purposes of this installation and will be deleted at the next reboot. Unzip the software package apache_v22_linux_agent_3.zip (apache_linux_agent) into /opt. The directory web_agents will be created. 2.12.3. Configuration Go into /opt/web_agents/apache22_agent/bin and run./agentadmin install. On prompt specify the apache httpd.conf folder as (e.g./etc/apache2/) Specify the URL of the SSO as: http://<your-sso-machine><your-domainname>:80/openam_953 (e.g.: http://sso.ssa.esa.int:80/openam_953) 2 Specify the service provider URL: http://<your-smt-machine><your-domain-name>:80 (e.g.: http://smt.ssa.esa.int:80) 3 2 If you get the message WARNING: Unreachable Server URL : http://<your-sso-machine><your-domainname>:80/openam_953 (e.g.: http://sso.ssa.esa.int:80/openam_953), this is because the apache server is switched off (normal behavior) Page 38/53
Specify the agent name (e.g. apacheagent as already defined into OpenAm see paragraph 2.7) Specify the path of the file where the password is stored (/tmp/passwd) Confirm and proceed with the installation Note: the installation put an "include" directory into the httpd.conf file pointing to the agent configuration file/s. Start Apache with new configuration file, like: service apache2 restart Check if it works properly at the following URL: http://<your-smt-machine><yourdomain-name> /web (ex. http://smt.ssa.esa.int/web). You should automatically redirected to the OpenAM login page. 2.12.4. Knowledge base, Known Issues Issue: redirection to IDP does not work or loops continuously Solution: specify the goto parameter into Login URL in Agent configuration "OpenAM Services" tab and rename the existing goto parameter to goto2 For any further information in Web Policy Agent administration/installation, please refer to the official documentation. 3 If you get an ERROR that informs you that the URL format entered is incorrect or the agent container is still running or Unreachable Server URL : http://<your-smt-machine><your-domain-name>:80 (e.g.: http://smt.ssa.esa.int:80). This may be accounted to a proxy where the apache is running, try switching it off. Page 39/53
3. Operations 3.1. Liferay - Administration This section describes the roles available for the management of the portal as well as the functions for each role. A number of roles are identified for the management of the portal, as follows: Administrator The Administrator is capable of the following actions: o manage pages (i.e. Edit web content, Retrieve existing web content, publish existing web content /Approve, Expire web content) o manage users o manage roles o manage portal settings o server administration o register Content Editor The Content editor is capable of the following actions: o add content Content Approver The Content Approver is capable of the following actions: o publish / expire content The following management functions are described in detail: 3.1.1. How to create a new article and save it into the CMS (Content editor) 1. The Administrator/Content Editor user accesses the Web Portal Home page and logs into the Portal 2. The system recognises the user and displays the Home Page with an application bar at the top of the page 3. The application bar shall at least display the Add and Manage drop down menus Page 40/53
4. Choose Manage -> Control Panel 5. In the left column menu choose ssa -> Web Content 6. The Web Content area should display (at least): a. A listing of articles already created (eventually empty), with the available Actions that could be performed on them b. Buttons to add, expire and delete the articles, with labels that read like Add Web Content, Expire and Delete 7. The user chooses the Add Web Content action 8. A New Web Content form is displayed with fields in edit mode 9. The user fills in the form and then clicks on the Save as Draft button 10. The new article is successfully created and saved. The user is returned the message Your request processed successfully. 3.1.2. How to publish the article making it visible for the viewers (Content Approver) 1. The Content Approver user accesses the Web Portal Home page and logs into the Portal 2. The system recognises the user and displays the Home Page with an application bar at the top of the page 3. The application bar shall at least display the Add and Manage drop down menus 4. Choose Manage -> Control Panel 5. In the left column menu choose ssa -> Web Content 6. The Web Content area should display (at least): a. A listing of articles already created with the available Actions that could be performed on them b. Buttons to add, expire and delete the articles, with labels that read like Add Web Content, Expire and Delete 7. The user chooses in the listing an article that is still not published and then chooses Actions -> Edit 8. The Web Content article is displayed in edit mode Page 41/53
9. The user presses the Publish button to promote the article from the Draft to the Published status 10. The user is redirected on the articles listing; the user can acknowledge that the Publishing action has been successfully completed because of the message being returned Your request processed successfully and because the status of the article being published has changed from Draft to Approved. 3.1.3. How to publish the article making it visible for the viewers (Content Approver) 1. The Content Approver user accesses the Web Portal Home page and logs into the Portal 2. The system recognises the user and displays the Home Page with an application bar at the top of the page 3. The application bar shall at least display the Add and Manage drop down menus 4. Choose Manage -> Control Panel 5. In the left column menu choose ssa -> Web Content 6. The Web Content area should display (at least): a. A listing of articles already created with the available Actions that could be performed on them b. Buttons to add, expire and delete the articles, with labels that read like Add Web Content, Expire and Delete 7. The user chooses in the listing an article that is still not published and then chooses Actions -> Edit 8. The Web Content article is displayed in edit mode 9. The user press the Expire button to expire the article and move it from the Published to the Expired status 10. The user is redirected on the articles listing; the user can acknowledge that the Expiring request has been successfully completed because of the message being returned Your request processed successfully and because the status of the article being expired has changed from Approved to Expired. Page 42/53
3.2. Liferay - Public and Registered Users This section describes how Public and Registered Users can access the SSA Technical Web portal. 3.2.1. Public Users Public Users are defined as those users who visit the portal without registering / logging in. Public Users can access the portal via a browser and will be able to: access all public content on the homepage use the Search engine placed on right column navigate to the SSA applications via the links placed on the right-hand column of the homepage (SSA Precursors) navigate to the Forum and Calendar pages via the links placed just below the top banner image Public Users who wish to access the Private Area will need to become Registered Users. 3.2.2. Registered Users Registered Users are defined as those users who visit the portal, perform a Registration and are therefore able to Login and access the Private Area. In order to register, the following steps must be performed: click on the Register link placed on the left-hand column of the portal homepage Page 43/53
the following page will open (the validation text changes with each session) fill in all the mandatory fields of the Registration Form, e.g.: Page 44/53
NOTE - the password must not contain more than 8 characters NOTE if the verification text is not copied correctly, after clicking on Submit, the message an error occurred will be displayed on the page NOTE if the password inserted in the Confirm Password field does not correspond to the one inserted in the Password field, an error message WARNING: incorrect password will be displayed click on the Submit button a page displaying the registration successfully executed message will then appear an email message is automatically sent to the user s email address, with the following text in the body: account is registered. Click on the activation link http://portal.ssa.esa.int/activation.jsp?useremail=name@email.com the User must now click on the link, and a confirmation page will be opened stating that activation successfully executed. At the same time, another email message is sent, containing the text: account is activated Page 45/53
The User is now able to Login, by performing the following steps: go to the homepage of the portal, and insert the chosen username and password in the Login fields: at first login, a Password Reminder page will appear, with options to select and a field for the chosen Answer. Amongst the options there is also the possibility of inserting a uers s own question Click on the Save button The homepage will now appear, and the Login box on the left-hand column will display the username of the user who is logged in and the Logout option the Registered User is now able to enter the Private Area by clicking on the Tink on the man navigation bar below the banner image on top. Page 46/53
3.3. itop - Public Users When a public SSA user access to the SMT through the OpenAM authentication by typing http://smt.ssa.esa.int/web, the Portal User home page is displayed: If the user clicks on Create a new request the service selection form appears: Then the subservice selection form appears: Finally the user should fill in all relevant fields and click on Finish to raise the request to the relevant Support Team: Page 47/53
3.4. itop - Administrator User Below the SMT home page of the administrator profile is displayed. This kind of user full access to the SMT features (into the left menu all options are available). Page 48/53
3.5. itop - Service Desk Users Below the SMT home page of Service Desk profile is displayed. This kind of user has only a partial visibility of features offered by itop. 3.6. AWStats It is possible to access to statistics web site by typing on your browser http://<statisticserver>/awstats/awstats.pl?config=<configfile> (e.g. http://stats-ssa.dev.eng.serco.eu/awstats/awstats.pl?config=technicalportal).. Page 49/53
3.7. OpenAM In order to administer OpenAM point the browser to deployment URL http://<ims-server>:<port>/openam_953 (e.g. http://sso.ssa.esa.int/openam_953 and enter the administrator credentials. Once logged in the system should display the following page. Page 50/53
Click on Access Control -> Top Level Realm -> Subjects to see all users registered into SSA infrastructure. Click on Access Control -> Top Level Realm -> Agents to see all agents registered for SSA infrastructure. Page 51/53
3.8. OpenDS In order to administer the OpenDS run the command control-panel from the local server shell (e.g. /opt/opends/bin/control-panel). Please note that you should have an X Manager (or export X through SSH) in order to be able to view the administration GUI. You should be asked by the system to prompt the administrator password. And then the admin panel should appear. Page 52/53
Page 53/53