JBoss Enterprise Portal Platform 5.1 Installation GuideAn Installation Guide for JBoss Enterprise Portal Platform 5.1.1

Installation Guide

JBoss Enterprise Portal Platform 5.1 Installation Guide An Installation Guide for JBoss Enterprise Portal Platform 5.1.1 Edition 2Editor Editor Editor Editor Copyright 2011 Red Hat, Inc. The text of and illustrations in this document are licensed by Red Hat under a Creative Commons AttributionShare Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version. Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law. Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries. Linux is the registered trademark of Linus Torvalds in the United States and other countries. Java is a registered trademark of Oracle and/or its affiliates. XFS is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries. MySQL is a registered trademark of MySQL AB in the United States, the European Union and other countries. All other trademarks are the property of their respective owners. Scott Mumford Luc Texier Thomas Heute Ben Clare

This book provides information about obtaining, installing and running JBoss Enterprise Portal Platform. It forms part of the complete document suite along with the User Guide and Reference Guide available at http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/index.html.

Preface v 1. Document Conventions ................................................................................................... v 1.1. Typographic Conventions ...................................................................................... v 1.2. Pull-quote Conventions ........................................................................................ vi 1.3. Notes and Warnings ............................................................................................ vii 2. Getting Help and Giving Feedback ................................................................................. vii 2.1. Do You Need Help? ............................................................................................ vii 2.2. Give us Feedback .............................................................................................. viii 1. Introduction 1 1.1. Other Manuals ............................................................................................................. 1 2. Getting Started 2.1. Upgrading and Add-ons ................................................................................................ 2.2. Pre-Requisites .............................................................................................................. 2.2.1. Enterprise Application Platform ........................................................................... 2.2.2. System Requirements ........................................................................................ 2.2.3. Configuring Your Java Environment .................................................................... 2.3. Recommended Practices .............................................................................................. 3. Installation 3.1. Downloading .............................................................................................................. 3.2. Installing .................................................................................................................... 3.3. Choosing a server configuration .................................................................................. 4. Post Installation Configuration 4.1. Set JBOSS_HOME Environment Variable ................................................................... 4.2. Adjust memory settings .............................................................................................. 4.3. Post Installation Security Configuration ....................................................................... 4.4. Disabling Authentication .............................................................................................. 5. Configuration 5.1. Database Configuration .............................................................................................. 5.1.1. Overview ......................................................................................................... 5.1.2. Configuring the database datasource for JCR .................................................... 5.1.3. Configuring the database datasource for the default identity store ....................... 5.1.4. Example with MySQL Server 5.1 ...................................................................... 5.2. E-Mail Service Configuration ....................................................................................... 5.2.1. Overview ......................................................................................................... 5.2.2. Configuring the outgoing e-mail account ............................................................ 5.3. Clustering Configuration .............................................................................................. 5.3.1. Overview ......................................................................................................... 5.3.2. Prerequisites ................................................................................................... 5.3.3. configuration.properties .................................................................................... 5.3.4. Running with the cluster profile ......................................................................... 5.4. HTTPS Configuration .................................................................................................. 5.4.1. Overview ......................................................................................................... 5.4.2. Generate your key ........................................................................................... 5.4.3. Setup JBoss configuration to use your key ........................................................ 5.4.4. Restart ........................................................................................................... 5.5. Gadget Proxy Configuration ........................................................................................ 5.5.1. Overview ......................................................................................................... 5.5.2. Setup the Filter ................................................................................................ 6. Installing Add-ons 7. Test your Installation 3 3 3 3 4 6 9

11 11 11 11 13 13 13 13 15 19 19 19 19 20 21 24 24 24 24 24 25 25 25 26 26 26 26 27 27 27 27 29 31 iii

Installation Guide 8. Uninstall JBoss Enterprise Portal Platform A. Revision History Index 33 35 37

iv

Preface1. Document ConventionsThis manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information. In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.1

1.1. Typographic ConventionsFour typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows. Mono-spaced Bold Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example: To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command. The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context. Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example: Press Enter to execute the command. Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 to return to your X-Windows session. The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously). If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example: File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions. Proportional Bold This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example: Choose System Preferences Mouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click

1

https://fedorahosted.org/liberation-fonts/

v

Preface Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand). To insert a special character into a gedit file, choose Applications Accessories Character Map from the main menu bar. Next, choose Search Find from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Doubleclick this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose Edit Paste from the gedit menu bar. The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context. Mono-spaced Bold Italic or Proportional Bold Italic Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example: To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com. The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home. To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release. Note the words in bold italics above username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system. Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example: Publican is a DocBook publishing system.

1.2. Pull-quote ConventionsTerminal output and source code listings are set off visually from the surrounding text. Output sent to a terminal is set in mono-spaced roman and presented thus:books books_tests Desktop Desktop1 documentation downloads drafts images mss notes photos scripts stuff svgs svn

Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:package org.jboss.book.jca.ex1; import javax.naming.InitialContext;

vi

Notes and Warningspublic class ExClient { public static void main(String args[]) throws Exception { InitialContext iniCtx = new InitialContext(); Object ref = iniCtx.lookup("EchoBean"); EchoHome home = (EchoHome) ref; Echo echo = home.create(); System.out.println("Created Echo"); System.out.println("Echo.echo('Hello') = " + echo.echo("Hello")); } }

1.3. Notes and WarningsFinally, we use three visual styles to draw attention to information that might otherwise be overlooked.

NoteNotes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

ImportantImportant boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

WarningWarnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. Getting Help and Giving Feedback2.1. Do You Need Help?If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at http://access.redhat.com. Through the customer portal, you can: search or browse through a knowledgebase of technical support articles about Red Hat products. submit a support case to Red Hat Global Support Services (GSS). vii

Preface access other product documentation. Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at https://www.redhat.com/mailman/ listinfo. Click on the name of any mailing list to subscribe to that list or to access the list archives.

2.2. Give us FeedbackIf you find a typographical error, or know how this guide can be improved, we would love to hear from you. Submit a report in Bugzilla against the product JBoss Enterprise Portal Platform 5 and the component docs-Installation_Guide. The following link will take you to a pre-filled bug 2 report for this product: http://bugzilla.redhat.com/ . Fill out the following template in Bugzilla's Description field. Be as specific as possible when describing the issue; this will help ensure that we can fix it quickly.Document URL:

Section Number and Name:

Describe the issue:

Suggestions for improvement:

Additional information:

Be sure to give us your name so that you can receive full credit for reporting the issue.

2

https://bugzilla.redhat.com/enter_bug.cgi?product=JBoss%20Enterprise%20Portal%20Platform%205&component=docsInstallation_Guide&version=5.1

viii

Chapter 1.

IntroductionJBoss Enterprise Portal Platform is the open source implementation of the Java EE suite of services and Portal services running atop JBoss Enterprise Application Platform. It comprises a set of offerings for enterprise customers who are looking for pre-configured profiles of JBoss Enterprise Middleware components that have been tested and certified together to provide an integrated experience. Its easyto-use server architecture and high flexibility makes JBoss the ideal choice for users just starting out with J2EE, as well as senior architects looking for a customizable middleware platform. Because it is Java-based, JBoss Enterprise Portal Platform is cross-platform and easy to install and use on any operating system that supports Java. Installing JBoss Enterprise Portal Platform is simple and easy. In this guide you will learn how to install, configure and secure JBoss Enterprise Portal Platform.

1.1. Other ManualsIf you are looking for detailed information about other JBoss Middleware products such as JBoss Enterprise Applications Platform please refer to the manuals available online at http://docs.redhat.com/ docs/en-US/index.html.

1

2

Chapter 2.

Getting Started2.1. Upgrading and Add-onsIf you currently have an installation of JBoss Enterprise Portal Platform in operation, you should read the notes below to ensure you choose the correct installation/migration path for your circumstances.

Upgrading JBoss Enterprise Portal PlatformIt is possible to upgrade from JBoss Enterprise Portal Platform version 5.0 or 5.1.0 to JBoss Enterprise Portal Platform 5.1.1. To upgrade, copy any customized configuration files and database settings from your existing JBoss Enterprise Portal Platform installation to the corresponding location of the 5.1.1 installation.

Add-onsThe Site Publisher add-on that is part of the 5.1.1 release can only be installed into a clean installation of JBoss Enterprise Portal Platform version 5.1 or later. It cannot be installed into a pre-existing and configured JBoss Enterprise Portal Platform installation (that is; a deployment that contains configuration settings or data that is not standard in the release). Likewise, Site Publisher cannot be installed onto JBoss Enterprise Portal Platform 5.0 or 5.0.1 versions (including installations that include the technical preview release of the Site Publisher extension). You must deploy a new instance of JBoss Enterprise Portal Platform 5.1.1 in order to use the Site Publisher add-on.

2.2. Pre-RequisitesYou must have adequate disk space to install a JDK and JBoss Enterprise Portal Platform (about 550MB) while also allowing enough space for your applications. Before installing JBoss Enterprise Portal Platform you must have a working installation of Java. Since JBoss is 100% pure Java you can have it working on any Operating System / Platform that supports Java.

2.2.1. Enterprise Application PlatformJBoss Enterprise Portal Platform is built upon JBoss Enterprise Application Platform. For more details about the underlying platform please refer to the EAP installation guide available at: http:// docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/index.html

3

Chapter 2. Getting Started

2.2.2. System RequirementsMinimum Installation RequirementsThe minimum hard disk space required to support the installation of the JBoss Enterprise Portal Platform is about 550MB. Additional space is required for the installation of the JDK upon which the JBoss Application Server depends. The JDK installation size is currently up to 150MB.

Minimum Operational RequirementsThe minimum hardware required to support an operational JBoss Application Server varies depending on the following: The size and complexity of the applications being served; The demand placed on the server by the number and frequency of client requests; The server configuration including the selected log files, their designated size and general server tuning. The following discussion relates to the deployment of a simple application on a server experiencing minimal demand. In view of this, the absolute minimum requirements for an operational server are: Disk Space: 1.5 GB The default server log file storage configuration is 500MB. The remaining 500 MB is allocated to the server installation (240 MB), the required JDK (150 MB) and some additional space for applications (110 MB). CPU: Intel Pentium Processor @ 1GHz Core 2 Duo, Core 2 Quad and Intel Xeon chips will improve the performance of servers which experience high demand. RAM: 1.5 GB RAM installations of 2 GB or more will be required to run a server upon which small to medium applications are deployed. 4 GB or more is preferable for larger applications or to run a GUI server interface.

ImportantA server's performance must be viewed in light of the applications deployed on the server, the demand placed on the server by client requests and any post-installation server configuration or tuning.

Supported InstallationsFor the latest information on supported Operating System / JVM combinations and supported Database platforms, please always refer to http://www.jboss.com/products/platforms/portals/ testedconfigurations/. The following is a list of certified operating systems and JVM version combinations: 4

System Requirements

Table 2.1. Supported Operating System / JVM Combinations. Operating System Red Hat Enterprise Linux 5 x86 Red Hat Enterprise Linux 5 x86 Red Hat Enterprise Linux 5 x86 Red Hat Enterprise Linux 5 x86_64 Red Hat Enterprise Linux 5 x86_64 Red Hat Enterprise Linux 5 x86_64 Microsoft Windows 2008 x86 Microsoft Windows 2008 x86_64 Solaris 10 JVM Version Sun JVM 1.6 Update 15 OpenJDK 1.6.0-b09 IBM JDK 1.6.0 SR5 Sun JVM 1.6 Update 15 OpenJDK 1.6.0-b09 IBM JDK 1.6.0 SR5 Sun JVM 1.6 Update 15 Sun JVM 1.6 Update 15 Sun JVM 1.6 Update 15

The following is a cumulative table of supported databases and JDBC drivers. Entries shown for each release are supported in addition to those in previous releases:

Table 2.2. Supported Database and JDBC driver Combinations Database JBoss Enterprise Portal Platform 5.0 MySQL 5.1 Oracle 10g R2 Oracle 11g R1 (Supported) Oracle 11g RAC (Supported) Microsoft SQL Server 2005 SP3 Microsoft SQL Server 2008 SP1 PostgresSQL 8.3.7 PostgresSQL 8.2.4 (Supported) DB2 9.7 Sybase 15.0.2 JBoss Enterprise Portal Platform 5.1 Oracle 11g R2 Oracle 11g R2 RAC 11g R2 11g R2 RAC MySQL Connector/J 5.1.8 10g R2 11g R1 11g R1 Microsoft JDBC Driver 2.0 Microsoft JDBC Driver 2.0 PostgresSQL Driver JDBC4, 8.3-605 PostgresSQL Driver JDBC4, 8.2-510 IBM Data Server Driver for JDBC and SQLJ (JCC Driver) Version: 9.1 (fixpack 3a) JConnect v6.0.5 Database driver

The following is a list of supported directory servers: Table 2.3. Supported and Certified directory servers Directory Server OpenDS OpenDS Version 1.2 2.0

5

Chapter 2. Getting Started Directory Server OpenLDAP Red Hat Directory Server MS Active Directory Version 2.4 7.1 Windows Server 2008

2.2.3. Configuring Your Java EnvironmentYou must have a working installation of JDK 1.6 before you install JBoss Enterprise Portal Platform. You can install the 32-bit or 64-bit JVM as per your requirements. In this guide we will show you how to install a 32-bit Sun JDK 6.0 using RHN, on a generic Linux Platform and Microsoft Windows Platform. But before we do that let's take a look at some of the benefits of using a 64-bit JVM. Benefits of 64-bit JVM on 64-bit OS and Hardware: Wider datapath: The pipe between RAM and CPU is doubled, which improves the performance of memory-bound applications. 64-bit memory addressing gives virtually unlimited (1 exabyte) heap allocation. However large heaps affect garbage collection. Applications that run with more than 1.5 GB of RAM (including free space for garbage collection optimization) should utilize the 64-bit JVM.

NoteApplications that run on a 32-bit JVM and do not require more than minimal heap sizes will gain nothing from a 64-bit JVM. Barring memory issues, 64-bit hardware with the same relative clock speed and architecture is not likely to run Java applications faster than their 32-bit cousin.

Installing and Configuring JDK 6.0 using RHN Java SDKs are provided by the Red Hat Enterprise Linux 5 Base and Supplementary channels for your Linux variant and architecture. The available JDKs corresponding to each channel and architecture are listed below: Red Hat Enterprise Linux 5 Java SDKs Channel: rhel--server-5 java-1.6.0-openjdk Channel: rhel--server-supplementary-5 java-1.6.0-sun (Sun) java-1.6.0-ibm (IBM) Ensure that the -devel packages are also installed. Selecting alternatives for java, javac and java_sdk_1.6.0 (setting java_sdk_1.6.0 is optional). This is only needed if you want to use the SysV service script and/or want this installed SDK to be the default java and javac in the system. This choice can often be overridden by setting the JAVA_HOME environment variable. 6

Configuring Your Java Environment The alternatives system allows different versions of Java, from different sources, to co-exist on your system. You should make sure the desired one is selected so that the service script uses the one you want. As root, issue the following command:/usr/sbin/alternatives --config java

and make sure the desired one is selected (marked with a '+'), or select it by entering its number as prompted. Make sure you do the same for javac and java_sdk_1.6.0. We recommend that all point to the same manufacturer and version. Installing and Configuring JDK 6.0 on a generic Linux platform Download the Java 2 Platform, Standard Edition (J2SE) Development Kit (JDK) 6.0 from Sun's website: http://java.sun.com/javase/downloads/index.jsp#need. From this page, select the latest update under the Java Platform, Standard Edition heading. Alternatively, this page can be accessed directly at http://java.sun.com/javase/downloads/ widget/jdk6.jsp. Follow the instructions presented on this page including selecting the appropriate platform and architecture. Clicking the Continue button will display the download options (depending on whether the user chooses to register): jdk-6u-linux--rpm.bin or; jdk-6u-linux-.bin If installing the JDK on Red Hat Enterprise Linux, Fedora, or another RPM-based Linux system, it is recommended that the self-extracting file containing the RPM package is selected. This option will set up and use the SysV service scripts in addition to installing the JDK. The RPM option is also recommended if the JBoss Enterprise Portal Platform is being set up in a production environment. Create an environment variable that points to the JDK installation directory and call it JAVA_HOME. Add $JAVA_HOME/bin to the system path to be able to run java from the command line. You can do this by adding the following lines to the .bashrc file in your home directory.

#In this example /usr/java/jdk1.6.0_19 is the JDK installation directory. export JAVA_HOME=/usr/java/jdk1.6.0_19 export PATH=$PATH:$JAVA_HOME/bin

Set this variable for the user account performing the installation and also for the user account that will run the server. If you have more than one version of JVM installed in your machine, make sure you are using the JDK1.6 installation as the default java and javac. You can do this using the alternatives system. The alternatives system allows different versions of Java, from different sources to co-exist on your system.

7

Chapter 2. Getting Started

NoteSelecting alternatives as decribed below can be avoided by setting the JAVA_HOME environment variable as explained in the previous step.

Select alternatives for java, javac and java_sdk_1.6.0 As root, type the following command at the shell prompt and you should see something like this:[root@vsr ~]$ /usr/sbin/alternatives --config java There are 2 programs which provide 'java'. Selection Command ----------------------------------------------1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java *+ 2 /usr/lib/jvm/jre-1.6.0-sun/bin/java Enter to keep the current selection[+], or type selection number:

Make sure the Sun version - jre-1.6.0-sun in this case - is selected (marked with a '+' in the output), or select it by entering its number as prompted. Repeat the same for javac and java_sdk_1.6.0.

[root@vsr ~]$ /usr/sbin/alternatives --config javac There are 1 programs which provide 'javac'. Selection Command ----------------------------------------------*+ 1 /usr/lib/jvm/java-1.6.0-sun/bin/javac Enter to keep the current selection[+], or type selection number:

[root@vsr ~]$ /usr/sbin/alternatives --config java_sdk_1.6.0 There are 1 programs which provide 'java_sdk_1.6.0'. Selection Command ----------------------------------------------*+ 1 /usr/lib/jvm/java-1.6.0-sun Enter to keep the current selection[+], or type selection number:

You should verify that java, javac and java_sdk_1.6.0 all point to the same manufacturer and version. Make sure that the java executable is in your path and that you are using an appropriate version. To verify your Java environment, type java -version at the shell prompt and you should see something like this:

[root@vsr ~]$ java -version java version "1.6.0_19" Java(TM) SE Runtime Environment (build 1.6.0_19-b01) Java HotSpot(TM) Server VM (build 14.2-b01, mixed mode)

8

Recommended Practices Installing and Configuring JDK 6.0 on Microsoft Windows Download the Java 2 Platform, Standard Edition (J2SE) Development Kit (JDK) 6.0 from Sun's website: http://java.sun.com/javase/downloads/index.jsp#need. From this page, select the latest update under the Java Platform, Standard Edition heading. Alternatively, this page can be accessed directly at http://java.sun.com/javase/downloads/ widget/jdk6.jsp. Follow the instructions presented on this page including selecting the appropriate platform and architecture. Clicking the Continue button will display the download option (depending on whether the user chooses to register): jdk-6u-windows-.exe Create an environment variable called JAVA_HOME that points to the JDK installation directory, for example: C:\Program Files\Java\jdk1.6.0_19\. In order to run java from the command line add the jre\bin directory to your path, for example: C:\Program Files\Java\jdk1.6.0_19\jre\bin. You may set these variables by going to the System Properties window then select the Advanced tab and finally click on the Environment Variables button.

2.3. Recommended PracticesJBoss Enterprise Portal Platform includes four pre-configured user accounts for testing and evaluation purposes. These accounts can be used for direct access to the portal. For security reasons, before going in production, you should restrict the access to the login servlet to POST. To do so, edit the file JBOSS_HOME/server//deploy/gatein.ear/02portal.war/ WEB-INF/web.xml and add:

login /login GET PUT DELETE HEAD OPTIONS TRACE

Doing this will render the login links provided on the front page inactive.

9

10

Chapter 3.

Installation3.1. DownloadingThe officially supported versions are available from the JBoss Customer Support Portal (CSP) located at https://access.redhat.com/home. Platforms including in your Support subscription are listed in the Software section.

3.2. InstallingTo install from a zip file, simply unzip the downloaded file to a directory of your choice. Unzip jboss-epp-.zip to extract the archive contents into the location of your choice. You can do this using the JDK jar tool (or any other ZIP extraction tool).

[vsr]$ cd jbeppinstallationdir [vsr]$ jar -xvf jboss-epp-.zip

You are done with the installation! You should now have a directory called jbossepp-.

Server ConfigurationsSix types of server configurations will be included in your installation: minimal, default, production, all, standard and web. The JBoss Enterprise Application Platform Getting Started Guide explains in detail the different server configuration file sets.1

3.3. Choosing a server configurationThe important differences between the Portal and JBoss Enterprise Application Platform server configurations are: the minimal, web and standard server configurations do not contain any Portal relevant components. These directories exist for the sake of consistency with JBoss Enterprise Application Platform the default server configuration includes non-clustered Portal components. This is the server configuration that is started when no other configuration is specified. the all server configuration includes the Portal and services used for running on a cluster. the production server configuration includes Portal components and clustering services. It is preconfigured with default settings which would be more accurate for a production environment.

1

http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/index.html

11

Chapter 3. Installation

gatein.ear ArchiveThe gatein.ear archive, which contains the Portal components, is located in the deploy folder of the default, all and production server configurations.

12

Chapter 4.

Post Installation Configuration4.1. Set JBOSS_HOME Environment VariableOn a Linux PlatformCreate an environment variable that points to the installation directory (/jboss-as) and call it JBOSS_HOME. Add $JBOSS_HOME/bin to the system path to be able to run the server from the command line. You can do this by adding the following lines to the .bashrc file in your home directory.

#In this example /home/user/jboss-epp-/jboss-as is the installation directory. export JBOSS_HOME=/home/user/jboss-epp-/jboss-as export PATH=$PATH:$JBOSS_HOME/bin

Set this variable for the user account(s) that will run the server.

On Microsoft WindowsCreate an environment variable called JBOSS_HOME that points to the installation directory, for example: C:\jboss-epp-\jboss-as\. In order to run the server from the command line add the bin directory to your path, for example: C: \jboss-epp-\jboss-as\bin. You may set these variables by going to the System Properties window then select the Advanced tab and finally click on the Environment Variables button.

4.2. Adjust memory settingsIf the server is running out of memory, you may adjust the memory settings before deploying the applications. You can do this by updating JAVA_OPTS settings in the file JBOSS_HOME/jboss-as/ bin/run.conf on Linux or JBOSS_HOME/jboss-as/bin/run.conf.bat on Windows. The default values don't take into account the memory requirements of your applications:

-Xms1303m -Xmx1303m -XX:MaxPermSize=256m ....

4.3. Post Installation Security ConfigurationWhen installed from the zip archive, authentication is required to access the majority of JBoss services, including administrative services. User accounts have not been set up to eliminate the possibility of default username/password based attacks.

13

Chapter 4. Post Installation Configuration

Default Admin User ConfigurationIt is recommended that the admin=admin username and password configuration, which is commented out by default, not be used for a production server. The admin user is included as an example of the username/password definition format only.

JBOSS_HOME and JBOSS_HOME is the jboss-as directory, a level above the bin directory. is the chosen server profile: all, default, minimal production, standard or web.

Set up the jmx-console users and rolesEdit the jmx-console-users.properties file located in the JBOSS_HOME/server// conf/props/ directory defining the username and password:user=password

Edit the jmx-console-roles.properties file located in the JBOSS_HOME/server// conf/props/ directory to define the user's roles:user=JBossAdmin,HttpInvoker

Set up the admin-console users and rolesEdit the web-console-users.properties file located in the JBOSS_HOME/server// deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/ directory:user=password

Edit the web-console-roles.properties file located in the JBOSS_HOME/server// deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/ directory:user=JBossAdmin,HttpInvoker

ImportantLogin credentials for the admin-console are the same as those used for the JMX console.

SuckerPassword for JBoss Messaging:JBoss Messaging makes internal connections between nodes in order to redistribute messages between clustered destinations. These connections are made with the user name of a special reserved user whose password is specified by the suckerPassword attribute in the Server Peer 14

Disabling Authentication configuration file: JBOSS_HOME/server//deploy/messaging/messaging-jbossbeans.xml. Procedure 4.1. Set suckerPassword for JBoss Messaging 1. Edit the JBOSS_HOME/server//deploy/messaging/messaging-jbossbeans.xml file and change the suckerPassword value from "CHANGE ME!!" to a plain text password:CHANGE ME!!

2.

Insert the same password you stored in the messaging-jboss-beans.xml file into the following command:JAVA_HOME/bin/java -cp JBOSS_HOME/client/jboss-messaging-client.jar org.jboss.messaging.util.SecurityUtil PLAIN_TEXT_PASSWORD

3.

Copy the encrypted password generated by the above command into the SuckerPassword attribute of the JBOSS_HOME/server//deploy/messaging/messagingservice.xml file:ENCRYPTED_PASSWORD

The suckerpassword in the messaging-service.xml file is for "client side" configuration and is used to initiate a connection, while the suckerpassword in messaging-jboss-beans.xml is part of the "server side" configuration and is used to authenticate incoming connection request.

4.4. Disabling AuthenticationIt is possible to disable authentication for specific services by following the instructions in this section.

Disabling Authentication for JXM Console:To disable authentication for the JMX console, edit the JBOSS_HOME/server//deploy/ jmx-console.war/WEB-INF/web.xml file and comment out the security-constraint section:

HtmlAdaptor An example security config that only allows users with the role JBossAdmin to access the HTML JMX console web application /* JBossAdmin

Disabling Authentication for Web Console:To disable authentication for the Web console, edit the JBOSS_HOME/server//deploy/ management/console-mgr.sar/web-console.war/WEB-INF/web.xml file to comment out the security-constraint section: 15

Chapter 4. Post Installation Configuration

HtmlAdaptor An example security config that only allows users with the role JBossAdmin to access the HTML JMX console web application /* GET POST JBossAdmin

Disabling Authentication for HTTP Invoker:To disable authentication for the http invoker, JNDIFactory, EJBInvokerServlet, and JMXInvokerServlet need to be removed from the security realm in the JBOSS_HOME/ server//deploy/management/console-mgr.sar/web-console.war/WEB-INF/ web.xml/deploy/httpha-invoker.sar/invoker.war/WEB-INF/web.xml file:

HttpInvokers An example security config that only allows users with the role HttpInvoker to access the HTTP invoker servlets /restricted/* GET POST HttpInvoker

Disabling Authentication for JMX Invoker:To disable authentication for the JMX invoker, edit the JBOSS_HOME/server//deploy/ management/console-mgr.sar/web-console.war/WEB-INF/web.xml/deploy/httphainvoker.sar/invoker.war/WEB-INF/web.xml/deploy/jmx-invoker-service.xml file to comment out the security interceptor passthrough: Locate the mbean section with the class org.jboss.jmx.connector.invoker.InvokerAdaptorService. In that section comment out the line that relates to authenticated users:

16

Disabling Authentication

Disabling Pre-configured AccountsJBoss Enterprise Portal Platform includes four pre-configured user accounts for testing and evaluation purposes. These accounts can be used for direct access to the portal. For security reasons, before going in production, you should restrict the access to the login servlet to POST. To do so, edit the file JBOSS_HOME/server//gatein.ear/02portal.war/WEBINF/web.xml and add:

login /login GET PUT DELETE HEAD OPTIONS TRACE

Doing this will render the login links provided on the front page inactive.

17

18

Chapter 5.

Configuration5.1. Database Configuration5.1.1. OverviewA Java Database Connectivity (JDBC) connector/driver is required for JBoss Enterprise Portal Platform to communicate with a relational database management system (RDBMS). JBoss Enterprise Portal Platform comes bundled with the Hypersonic SQL (HSQL) database in order for users to get up and running quickly without having to initially set up a database and the server. However, HSQL should not be used in a production environment and Red Hat does not offer ANY support for it. Therefore we recommend to setup a RDBMS and JBoss Enterprise Portal Platform connect to it as follows: JBoss Enterprise Portal Platform has two different database dependencies. One is the identity service configuration, which depends on Hibernate. The other database dependency is the Java Content Repository (JCR) service, which depends on the native JDBC API. JCR has the capability to integrate with any existing datasource implementation. When you start the portal for the first time, it will automatically create the proper schema (assuming that the database user has the appropriate permissions).

NoteJBoss Enterprise Portal Platform assumes the default encoding for your database is latin1.

5.1.2. Configuring the database datasource for JCRTo configure the database datasource used by JCR you will need to edit the datasource descriptor located at JBOSS_HOME/server//deploy/gatein-ds.xml:

gatein-jcr jdbc:hsqldb:${jboss.server.data.dir}${/}gatein${/}hypersonic${/}gatein-jcr-localDB org.hsqldb.jdbcDriver sa 5 20 0 32

Edit the values of driver-class, connection-url, user-name and password to match the specific values for your database (Please refer to your database JDBC driver documentation for more information about these attributes). 19

Chapter 5. Configuration In the case of HSQL, the databases are created automatically. For any other database you will need to firstly create the database. Make sure the user has rights to create tables on the database and to update them as, during the first start up, they will be automatically created. Add the JDBC driver to the classpath, by copying the relevant JAR file to the JBOSS_HOME/ server//lib directory.

5.1.3. Configuring the database datasource for the default identity storeTo configure the database datasource used by IDM you will need to edit the datasource descriptor located at JBOSS_HOME/server//deploy/gatein-ds.xml:

gatein-idm jdbc:hsqldb:${jboss.server.data.dir}${/}gatein${/}hypersonic${/}gatein-idm-localDB org.hsqldb.jdbcDriver sa 5 20 0 32

More information about setting up datasources can be found in the Enterprise Application Platform documentation.

Using SybaseSybase requires a particular configuration of JBoss Enterprise Portal Platform, to switch on that configuration, it is mandatory to run the portal with the extra sybase profile. This would mean to run the application server with sh run.sh -Dexo.profiles=sybase in a single node and sh run.sh -Dexo.profiles=sybase,cluster for a cluster node.

20

Example with MySQL Server 5.1

Do not delete JBOSS_HOME/server//dataThe JCR can store information both in a database and on the file system depending on the configuration of the value storage. Refer to the JBoss Enterprise Portal Platform Reference Guide for more information. By default, the portal will store information required to run the portal in JBOSS_HOME/ server//data/gatein/jcr/values/. You can change this directory location by editing the JBOSS_HOME/server// conf/gatein/configuration.properties file, the name of the property being: gatein.jcr.storage.data.dir

5.1.4. Example with MySQL Server 5.1

Installing the MySQL JDBC connectorThe MySQL JDBC connector is required for EPP to use a MySQL database: The mysql-java-connector package is available through Red Hat Network . This is the recommended installation method. For users who are not able to access the Red Hat Network, MySQL is available directly from http:// 2 www.mysql.com . You should download a version listed in the Certified Configurations table available 3 on the JBoss Enterprise Portal Platform JBoss website.1

Creating a MySQL DatabaseIf you have just installed MySQL, make sure the MySQL server is running, and then run the following command to set the root user password:

mysqladmin -u root password 'new-root-user-password'

1. Run the following command to log in to MySQL. Enter the root user password when prompted:

mysql -u root -p

2. Use the CREATE DATABASE command to create a new gateinjcr database.

1 2

https://www.redhat.com/wapps/sso/rhn/login.html?redirect=http%3A%2F%2Frhn.redhat.com%2Frhn%2FYourRhn.do http://www.mysql.com/downloads/connector/j/ 3 http://www.jboss.com/products/platforms/portals/testedconfigurations/

21

Chapter 5. Configuration

Note: Database namesThe remainder of this guide, and the configuration examples that follow assume the database names to be gateinjcr and gateinidm. If you change the database names, please update gatein-ds.xml accordingly (for each server configuration used).

mysql> CREATE DATABASE gateinjcr;

The output should be similar to the following:

Query OK, 1 row affected (0.00 sec)

Then repeat with:mysql> CREATE DATABASE gateinidm;

At this point, the SHOW DATABASES; command should display the gatein databases:

mysql> SHOW DATABASES; +--------------------+ | Database | +--------------------+ | information_schema | | gateinjcr | | gateinidm | | mysql | +--------------------+ 4 rows in set (0.00 sec)

It is safe to ignore the other databases. 3. Add a new user and give that user access to the gatein databases. The following example adds a new user named gateinuser, with the password gateinpassword. It is recommended that you choose a different password to the one supplied here by changing gateinpassword to some other password:CREATE USER 'gateinuser'@'localhost' IDENTIFIED BY 'gateinpassword';

4. Grant the necessary privileges to the user:

mysql> GRANT ALL PRIVILEGES ON gateinjcr.* TO 'gateinuser'@'localhost' IDENTIFIED BY 'gateinpassword' WITH GRANT OPTION;

mysql> GRANT ALL PRIVILEGES ON gateinidm.* TO 'gateinuser'@'localhost' IDENTIFIED BY 'gateinpassword' WITH GRANT OPTION;

22

Example with MySQL Server 5.1

MySQL Datasource DescriptorWe now need to change the portal database descriptor 1. Edit the file located at JBOSS_HOME/server//deploy/gatein-ds.xml. 2. Update the following lines in the Datasource descriptor to reflect the correct database, username and password respectively: jdbc:mysql://mysql-hostname:3306/DATABASE; In this example the database name is gateinjcr for the first datasource listed in gateinds.xml. The database name for the second datasource is gateinidm. See the example gateinds.xml file provided. USER-NAME; The user-name for this example is gateinuser. PASSWORD; This example uses the gateinpassword password. Enter this or the password chosen at Creating a MySQL Database. gatein-ds.xml will then look like: gatein-idm jdbc:mysql://mysql-hostname:3306/gateinidm com.mysql.jdbc.Driver gateinuser gateinpassword 5 20 0 32 gatein-jcr jdbc:mysql://mysql-hostname:3306/gateinjcr com.mysql.jdbc.Driver gateinuser gateinpassword 5 20 0 32

23

Chapter 5. Configuration

ImportantSome underlying JBoss Enterprise Application Platform services might still be using Hypersonic which is an in-VM database server loaded in the same memory space. To connect these services to another RDBMS or disable them please refer to the EAP documentation or simply contact JBoss Support for assistance.

5.2. E-Mail Service Configuration5.2.1. OverviewJBoss Enterprise Portal Platform includes an e-mail sending service that needs to be configured before it can function properly. This service, for instance, is used to send e-mails to users who forgot their password or username.

5.2.2. Configuring the outgoing e-mail accountThe e-mail service can use any SMTP account configured in JBOSS_HOME/server// conf/gatein/configuration.properties The relevant section looks like:# EMail gatein.email.smtp.username= gatein.email.smtp.password= gatein.email.smtp.host=smtp.gmail.com gatein.email.smtp.port=465 gatein.email.smtp.starttls.enable=true gatein.email.smtp.auth=true gatein.email.smtp.socketFactory.port=465 gatein.email.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

The email service is pre-configured for GMail, so that any GMail account can be used with minimal configuration. Simply enter the full GMail address as the username and fill in the corresponding password. In corporate environments you will want to use your corporate SMTP gateway. When using it over SSL, such as in the default configuration, you may need to configure a certificate truststore containing your SMTP server's public certificate. Depending on the key sizes, you may then also need to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for your Java Runtime Environment.

5.3. Clustering Configuration5.3.1. OverviewJBoss Enterprise Portal Platform has been developed to support high availability and high horizontal and vertical scalability. The setup instructions have been kept to a minimum, however, a good understanding of clustering services in JBoss Enterprise Application Platform and JBoss Cache would be required in order to configure the optimal settings. 24

Prerequisites

5.3.2. PrerequisitesThe clustering services are available only in the all and production server configurations. Additionally the following prerequisites should be met: a rapid shared file system is required such as a Storage Area Network (SAN) and; databases should be shared among the various nodes of the cluster and configured to point to the same instances.

5.3.3. configuration.propertiesEdit the following entries in the JBOSS_HOME/jboss-as/server//conf/gatein/ configuration.properties file: gatein.jcr.storage.data.dir; To specify the location of the "value storage". This folder must not be deleted as it contains data required for the portal to run. For more details about "value storage" please refer to the JCR configuration in the JBoss Enterprise Portal Platform Reference Guide available at http:// docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/index.html gatein.jcr.index.data.dir; To specify the location on a shared file system to store the JCR index. If the directory is deleted, the JCR will recreate the indexes on next start of the server. (This operation may take a very long time, depending on the size of the data stored in the JCR).

gatein.jcr.index.changefilterclass; This must be changed to org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheIndexChangesFilt gatein.jcr.config.type; This must be changed to cluster. The default property file would look like the following:# Data gatein.data.dir=/mnt/shared/mylocation # DB gatein.db.data.dir=${gatein.data.dir}/db # JCR gatein.jcr.config.type=cluster gatein.jcr.datasource.name=java:gatein-jcr gatein.jcr.datasource.dialect=auto

gatein.jcr.data.dir=${gatein.data.dir}/jcr gatein.jcr.storage.data.dir=${gatein.jcr.data.dir}/values gatein.jcr.index.data.dir=${gatein.jcr.data.dir}/lucene gatein.jcr.index.changefilterclass=org.exoplatform.services.jcr.impl.core.query.jbosscache.JBossCacheInde [...]

5.3.4. Running with the cluster profileTo run the portal in high-availability mode, you would need to start all nodes with an extra profile configuration as follows:

25

Chapter 5. Configuration

In Linuxrun.sh -c all -Dexo.profiles=cluster

In Windowsrun.bat -c all -Dexo.profiles=cluster

5.4. HTTPS Configuration5.4.1. OverviewJBoss Enterprise Portal Platform runs, by default, in HTTP mode. However, for security purposes, you can configure it to run in HTTPS mode. This section explains how to run JBoss Enterprise Portal Platform in HTTPS mode.

5.4.2. Generate your keyIf you haven't a X.509 certificate, you can make a simple certificate using the keytool command: Procedure 5.1. 1. Change the variables in the following command to suit your circumstances then run it a terminal:keytool -genkey -alias serverkeys -keyalg RSA -keystore server.keystore -storepass 123456 -keypass 123456 -dname "CN=localhost, OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY"

Your key will be stored in server.keystore 2. Import your key into the Sun JDK keystore (this is required to help running gadget features) with the following command:keytool -importkeystore -srckeystore server.keystore -destkeystore $JAVA_HOME/jre/lib/ security/cacerts

5.4.3. Setup JBoss configuration to use your keyTo set the JBoss configuration to use the new key: Procedure 5.2. 1. Comment the following lines in JBOSS_HOME/server//deploy/jbossweb.sar/ server.xml:

2.

Uncomment the following lines...

...and change the values of keystoreFile and keystorePass to values of your key.

5.4.4. RestartOnce you have configured your environment, restart your JBoss Enterprise Portal Platform instance. You can now access the portal via address: https://:8443/portal

5.5. Gadget Proxy Configuration5.5.1. OverviewGadget consumption requires a local anonymous proxy to route access to elements used by the gadgets. This must be done to work around web-browser security mechanisms.

5.5.2. Setup the FilterThe anonymous proxy can be setup to accept or refuse certain hosts. By default, the proxy is closed to any host except the domain on which the gadget server is installed. To modify the filtering of domain names, modify: JBOSS_HOME/server//deploy/ gatein.ear/02portal.war/WEB-INF/conf/common/common-configuration.xml Example 5.1. common-configuration.xml org.exoplatform.web.security.proxy.ProxyFilterService org.exoplatform.web.security.proxy.ProxyFilterService white-list black-list

The proxy will deny access to a resource that is on the blacklist. If the domain name does not match any of the blacklist, the proxy filter will verify if the domain name is on the white list. If the domain name is not defined in either the white list or black list, access will be denied. Multiple values can be added for each list and wildcards can also be used. Below is an example of a valid configuration: 27

Chapter 5. Configuration

Example 5.2. Valid Proxy Configuration org.exoplatform.web.security.proxy.ProxyFilterService org.exoplatform.web.security.proxy.ProxyFilterService white-list *.example.com www.example.net black-list evil.example.com

28

Chapter 6.

Installing Add-onsImportantDo not read further in this guide if you intend to install the JBoss Site Publisher add-on.

At this point you should refer to the JBoss Site Publisher Installation Guide available at http:// docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/index.html and install the add-on. Once you have completed the installation for the JBoss Site Publisher extension, you should return to this document and continue this process.

29

30

Chapter 7.

Test your InstallationAfter you have installed the JBoss Enterprise Portal Platform, it is wise to perform a simple start up test to validate that there are no major problems with your Java VM/operating system combination. Make sure you have set the JBOSS_HOME environment variables as explained in Chapter 4, Post Installation Configuration. To test your installation: move to the JBOSS_HOME/bin directory; execute the run.bat (for Windows) or run.sh (for Linux) script, as appropriate for your operating system; Ensure that you run the configuration corresponding to the JBOSS_HOME/server// chosen in Creating a MySQL Database The example below uses the production configuration. Your output should look like the following (accounting for installation directory differences and version numbers) and should not contain any error or exception messages:

[user@localhost bin]$ ./run.sh -c production ========================================================================= JBoss Bootstrap Environment JBOSS_HOME: /home/user/jboss-epp-5.0/jboss-as JAVA: /usr/java/jdk1.6.0_16/bin/java JAVA_OPTS: -Dprogram.name=run.sh -server -Xms1303m -Xmx1303m -XX:MaxPermSize=256m -Dorg.jboss.resolver.warning=true -Dsun.rmi.dgc.client.gcInterval=3600000 -Dsun.rmi.dgc.server.gcInterval=3600000 Dsun.lang.ClassLoader.allowArraySyntax=true -Dexo.conf.dir.name=gatein -Djava.net.preferIPv4Stack=true CLASSPATH: /home/user/jboss-epp-5.0/jboss-as/bin/run.jar/usr/java/jdk1.6.0_16/lib/tools.jar ========================================================================= 16:59:41,401 INFO [ServerImpl] Starting JBoss (Microcontainer)... 16:59:41,401 INFO [ServerImpl] Release ID: JBoss [EAP] 5.0.0.GA (build: SVNTag=JBPAPP_5_0_0_GA date=200910202128) 16:59:41,402 INFO [ServerImpl] Bootstrap URL: null 16:59:41,402 INFO [ServerImpl] Home Dir: /home/user/jboss-epp-5.0/jboss-as 16:59:41,402 INFO [ServerImpl] Home URL: file:/home/user/jboss-epp-5.0/jboss-as/ 16:59:41,402 INFO [ServerImpl] Library URL: file:/home/user/jboss-epp-5.0/jboss-as/lib/ 16:59:41,403 INFO [ServerImpl] Patch URL: null 16:59:41,403 INFO [ServerImpl] Common Base URL: file:/home/user/jboss-epp-5.0/jboss-as/ common/ 16:59:41,404 INFO [ServerImpl] Common Library URL: file:/home/user/jboss-epp-5.0/jboss-as/ common/lib/ 16:59:41,404 INFO [ServerImpl] Server Name: production ... ... 16:59:44,345 INFO [JMXKernel] Legacy JMX core initialized

31

Chapter 7. Test your Installation

Note: Production server log fileThere is no "Server Started" message shown at the console when the server is started using the production profile. This message may be observed in the server.log file located in the JBOSS_HOME/server/production/log subdirectory.

Ensure that port 8080 is not already in use and open http://localhost:8080/portal in your web browser.

NoteOn some machines, the name localhost wont resolve properly and you should use the local loopback address 127.0.0.1 instead.

The contents of your page should look similar to this: Figure 7.1, Test your Installation.

Figure 7.1. Test your Installation You are now ready to use JBoss Enterprise Portal Platform. Refer to the User Guide and Reference Guide for more information about the product's feature set and example applications showcasing JBoss Enterprise Portal Platform in action.

32

Chapter 8.

Uninstall JBoss Enterprise Portal PlatformAs JBoss Enterprise Portal Platform was installed from a zip file, you may uninstall it by simply deleting the JBoss Enterprise Portal Platform directory installed on your system.

33

34

Appendix A. Revision HistoryRevision Fri Jul 15 2011 2-5.1.4 Updated for 5.1.1 Release. Scott Mumford

Revision 1-5.2 Wed June 22 2011 Incorporated new Bugzilla feedback link. Corrected minor typographical errors.

Scott Mumford smumford@redhat.com

Revision 1-1.1 Tue Nov 24 2009 Initial creation of book in Publican

Scott Mumford smumford@redhat.com

35

36

IndexCClustering Configuration, 24 Configuration Clustering, 24 Database, 19 MySQL, 21

DDatabase Configuration, 19 MySQL, 21 System Requirements, 5

Ffeedback contact information for this manual, viii

Hhelp getting help, vii

MMySQL, 21

SSystem Requirements Database, 5 Directory server, 5 OS/JVM, 5

37

38