Author: smumford Date: 2010-12-01 22:56:42 -0500 (Wed, 01 Dec 2010) New Revision: 5433 Added: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/GadgetProxyConfig.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/HTTPSConfiguration.xml Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Book_Info.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/ClusteringConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Configuration.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/DatabaseConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/EMailServiceConfiguration.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Getting_Started.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Installation.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Installation_Guide.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Introduction.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Launching.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Post_Installation.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Revision_History.xml epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Test_Your_Installation.xml Log: : Incorporated fixes from 5.1 docs reviews Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Book_Info.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Book_Info.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Book_Info.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -11,7 +11,7 @@ <subtitle>An Installation Guide for &PRODUCT;</subtitle> <productname>JBoss Enterprise Portal Platform</productname> <productnumber>5</productnumber> - <edition>1.6</edition> + <edition>1.7</edition> <pubsnumber>0</pubsnumber> <abstract> <para> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/ClusteringConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/ClusteringConfiguration.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/ClusteringConfiguration.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -44,7 +44,7 @@ <section id="sect-Reference_Guide-Clustering_Properties"> <title>configuration.properties</title> - <para>Edit the following entries in the <filename>$JBOSS_HOME/jboss-as/server/$CONFIG/conf/gatein/configuration.properties</filename> file:</para> + <para>Edit the following entries in the <filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/configuration.properties</filename> file:</para> <itemizedlist> <listitem> <para> @@ -97,7 +97,7 @@ </itemizedlist> <para> The default property file would look like the following: - <programlisting># Data +<programlisting># Data gatein.data.dir=/mnt/shared/mylocation # DB @@ -121,15 +121,17 @@ <title>Running with the cluster profile</title> <para>To run the portal in high-availability mode, you would need to start all nodes with an extra profile configuration as follows:</para> <formalpara><title>In Linux</title> - <para> - <literal>run.sh -c all -Dexo.profiles=cluster</literal> - </para> +<para> +<programlisting><command>run.sh -c all -Dexo.profiles=cluster</command> +</programlisting> +</para> </formalpara> <formalpara><title>In Windows</title> - <para> - <literal>run.bat -c all -Dexo.profiles=cluster</literal> - </para> +<para> +<programlisting><command>run.bat -c all -Dexo.profiles=cluster</command> +</programlisting> +</para> </formalpara> </section> </section> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Configuration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Configuration.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Configuration.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -9,7 +9,7 @@ <xi:include href="DatabaseConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="EMailServiceConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="ClusteringConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - + <xi:include href="HTTPSConfiguration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="GadgetProxyConfig.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </chapter> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/DatabaseConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/DatabaseConfiguration.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/DatabaseConfiguration.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -39,7 +39,7 @@ <para>To configure the database datasource used by JCR you will need to edit the datasource descriptor located at - <filename>$JBOSS_HOME/server/$CONFIG/deploy/gatein-ds.xml</filename>: + <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein-ds.xml</filename>: <programlisting> &lt;no-tx-datasource&gt; &lt;jndi-name&gt;gatein-jcr&lt;/jndi-name&gt; @@ -70,7 +70,7 @@ created.</para> <para>Add the JDBC driver to the classpath, by copying the relevant - JAR file to the <filename>$JBOSS_HOME/server/$CONFIG/lib</filename> directory.</para> + JAR file to the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/lib</filename> directory.</para> </section> @@ -79,7 +79,7 @@ <title>Configuring the database datasource for the default identity store</title> <para>To configure the database datasource used by IDM you will need to edit the - datasource descriptor located at <filename>$JBOSS_HOME/server/$CONFIG/deploy/gatein-ds.xml</filename>: + datasource descriptor located at <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein-ds.xml</filename>: <programlisting> &lt;no-tx-datasource&gt; @@ -239,7 +239,7 @@ <orderedlist> <listitem> <para> - Edit the file located at <filename>$JBOSS_HOME/server/$CONFIG/deploy/gatein-ds.xml</filename>. + Edit the file located at <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein-ds.xml</filename>. </para> </listitem> <listitem> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/EMailServiceConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/EMailServiceConfiguration.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/EMailServiceConfiguration.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -20,11 +20,11 @@ <title>Configuring the outgoing e-mail account</title> <para>The e-mail service can use any SMTP account configured in - <filename>$JBOSS_HOME/server/$CONFIG/conf/gatein/configuration.properties</filename></para> + <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/gatein/configuration.properties</filename></para> <para>The relevant section looks like:</para> - <programlisting># EMail +<programlisting># EMail gatein.email.smtp.username= gatein.email.smtp.password= gatein.email.smtp.host=smtp.gmail.com Added: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/GadgetProxyConfig.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/GadgetProxyConfig.xml (rev 0) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/GadgetProxyConfig.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -0,0 +1,82 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Installation_Guide.ent"> +%BOOK_ENTITIES; +]> + +<section> + <title>Gadget Proxy Configuration</title> + <section> + <title>Overview</title> + <para> + Gadget consumption requires a local anonymous proxy to route access to elements used by the gadgets. + </para> + <para> + This must be done to work around web-browser security mechanisms. + </para> + </section> + + <section> + <title>Setup the Filter</title> + <para> + The anonymous proxy can be setup to accept or refuse certain hosts. + </para> + <para> + By default, the proxy is closed to any host except the domain on which the gadget server is installed. + </para> + <para> + To modify the filtering of domain names, modify: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/conf/common/common-configuration.xml</filename> + </para> +<example> +<title>common-configuration.xml</title> +<programlisting language="XML" role="XML"><![CDATA[<component> + <key>org.exoplatform.web.security.proxy.ProxyFilterService</key> + <type>org.exoplatform.web.security.proxy.ProxyFilterService</type> + <init-params> + <values-param> + <!-- The white list --> + <name>white-list</name> + <value></value> + </values-param> + <values-param> + <name>black-list</name> + <value></value> + </values-param> + </init-params> + </component> ]]> +</programlisting> +</example> + <para> + 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. + </para> + <para> + If the domain name is not defined in either the white list or black list, access will be denied. + </para> + <para> + Multiple values can be added for each list and wildcards can also be used. + </para> + <para> + Below is an example of a valid configuration: + </para> +<example> +<title>Valid Proxy Configuration</title> +<programlisting language="XML" role="XML"><![CDATA[<component> + <key>org.exoplatform.web.security.proxy.ProxyFilterService</key> + <type>org.exoplatform.web.security.proxy.ProxyFilterService</type> + <init-params> + <values-param> + <!-- The white list --> + <name>white-list</name> + <value>*.example.com</value> + <value>www.example.net&lt;/value> + </values-param> + <values-param> + <name>black-list</name> + <value>evil.example.com</value> + </values-param> + </init-params> + </component> ]]> +</programlisting> +</example> + </section> +</section> \ No newline at end of file Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Getting_Started.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Getting_Started.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Getting_Started.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -6,17 +6,16 @@ <chapter id="Getting_Started"> <title>Getting Started</title> + <section id="Getting_Started-Pre_Requisites"> <title>Pre-Requisites</title> <para> - You must have adequate disk space to install a JDK and &PRODUCT; (about 520MB) while also allowing enough space for your applications. Before installing &PRODUCT; 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. - <!--However, only some combinations are certified (tested prior to shipping) or supported (on which you can open support tickets), the certified combinations are listed below. --> + You must have adequate disk space to install a JDK and &PRODUCT; (about 550MB) while also allowing enough space for your applications. Before installing &PRODUCT; 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. </para> <section id="Pre_Requisites-EAP"> <title>Enterprise Application Platform</title> - <para>The Enterprise Portal Platform 5.0 is built upon the Enterprise Application Platform 5.0. - For more details about the underlying platform such as the difference between the 4.3 and 5.0 versions, please refer to - the EAP installation guide available at: <ulink url="http://www.redhat.com/docs/en-US/JBoss_Enterprise_Application_P... + <para>&PRODUCT; is built upon &JBEAP;. For more details about the underlying platform please refer to + the EAP installation guide available at: <ulink url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_... </para> </section> <section id="Pre_Requisites-Hardware_and_Operating_System_Requirements"> @@ -24,7 +23,7 @@ <formalpara> <title>Minimum Installation Requirements</title> <para> - The 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 the JBoss Application Server depends. The JDK installation size is currently up to 150MB. + The 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. </para> </formalpara> <formalpara> @@ -49,7 +48,7 @@ The server configuration including the selected log files, their designated size and general server tuning. </para> </listitem> - </itemizedlist> + </itemizedlist> <para> 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: </para> @@ -208,10 +207,7 @@ </tbody> </tgroup> </table> - - <para> - The following is a list of supported databases and JDBC drivers: - </para> + <indexterm> <primary>System Requirements</primary> <secondary>Database</secondary> @@ -220,14 +216,12 @@ <primary>Database</primary> <secondary>System Requirements</secondary> </indexterm> - <table> - <title> - Supported and Certified Database / JDBC driver Combinations. - </title> - + <table> + <title>Supported Database and JDBC driver Combinations</title> <tgroup cols="2"> - <colspec colnum="1" colname="DB" colwidth="1*"></colspec> - <colspec colnum="2" colname="DB_driver" colwidth="1*"></colspec> + <colspec colnum="1" colname="c1" colwidth="1*"></colspec> + <colspec colnum="2" colname="c2" colwidth="1*"></colspec> + <spanspec spanname="hspan" namest="c1" nameend="c2" align="left"></spanspec> <thead> <row> <entry> @@ -239,6 +233,11 @@ </row> </thead> <tbody> + <row> + <entry spanname="hspan"> + <emphasis><emphasis role="bold">&PRODUCT; 5.0</emphasis></emphasis> + </entry> + </row> <row> <entry> MySQL 5.1 @@ -249,26 +248,26 @@ </row> <row> <entry> - Oracle 10g R2 (10.2.0.4) + Oracle 10g R2 <!--(10.2.0.4)--> </entry> <entry> - 10g R2 (10.2.0.4) + 10g R2 <!--(10.2.0.4)--> </entry> </row> <row> <entry> - Oracle 11g R1 (11.1.0.7.0) (Supported) + Oracle 11g R1 <!-- (11.1.0.7.0) -->(Supported) </entry> <entry> - 11g R1 (11.1.0.7.0) + 11g R1 <!--(11.1.0.7.0)--> </entry> </row> <row> <entry> - Oracle 11g RAC (11.1.0.7.0) (Supported) + Oracle 11g RAC <!--(11.1.0.7.0)--> (Supported) </entry> <entry> - 11g R1 (11.1.0.7.0) + 11g R1 <!--(11.1.0.7.0)--> </entry> </row> <row> @@ -316,12 +315,13 @@ Sybase 15.0.2 </entry> <entry> - JConnect v6.0.5 (Build 26564 / 11 Jun 2009) + JConnect v6.0.5 <!--(Build 26564 / 11 Jun 2009) --> </entry> </row> </tbody> </tgroup> </table> + <indexterm> <primary>System Requirements</primary> <secondary>Directory server</secondary> @@ -532,7 +532,8 @@ </listitem> --> <listitem> <para> - Create an environment variable that points to the JDK installation directory and call it <literal>JAVA_HOME</literal>. Add <literal>$JAVA_HOME/bin</literal> to the system path to be able to run <literal>java</literal> from the command line. You can do this by adding the following lines to the <filename>.bashrc</filename> file in your home directory. <programlisting> + Create an environment variable that points to the JDK installation directory and call it <literal>JAVA_HOME</literal>. Add <literal>$JAVA_HOME/bin</literal> to the system path to be able to run <literal>java</literal> from the command line. You can do this by adding the following lines to the <filename>.bashrc</filename> file in your home directory. +<programlisting> #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 @@ -650,5 +651,35 @@ </section> </section> + <section> + <title>Recommended Practices</title> + <para> + &PRODUCT; includes four pre-configured user accounts for testing and evaluation purposes. These accounts can be used for direct access to the portal. + </para> + <para> + For security reasons, before going in production, you should restrict the access to the login servlet to POST. + </para> + <para> + To do so, edit the file <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/gatein.ear/02portal.war/WEB-INF/web.xml</filename> and add: + </para> +<programlisting language="XML" role="XML"><![CDATA[ +<security-constraint> + <web-resource-collection> + <web-resource-name>login</web-resource-name> + <url-pattern>/login</url-pattern> + <http-method>GET</http-method> + <http-method>PUT</http-method> + <http-method>DELETE</http-method> + <http-method>HEAD</http-method> + <http-method>OPTIONS</http-method> + <http-method>TRACE</http-method> + </web-resource-collection> + <auth-constraint/> +</security-constraint> ]]></programlisting> + <para> + Doing this will render the login links provided on the front page inactive. + </para> + + </section> </chapter> Added: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/HTTPSConfiguration.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/HTTPSConfiguration.xml (rev 0) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/HTTPSConfiguration.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -0,0 +1,118 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "Installation_Guide.ent"> +%BOOK_ENTITIES; +]> +<section id="sect-Installation_Guide-HTTPS_Configuration"> + <title>HTTPS Configuration</title> + + <section id="sect-Installation_Guide-HTTPS_Configuration-Overview"> + <title>Overview</title> + <para> + &PRODUCT; 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 &PRODUCT; in HTTPS mode. + </para> + + </section> + <section id="sect-Installation_Guide-HTTPS_Configuration-Generate_Key"> + <title>Generate your key</title> + <para> + If you haven't a X.509 certificate, you can make a simple certificate using the <command>keytool</command> command: + </para> + <procedure> + <title><emphasis role="bold"></emphasis></title> + <step> + <para> + Change the variables in the following command to suit your circumstances then run it a terminal: + </para> +<programlisting>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"</programlisting> + <para> + Your key will be stored in <filename>server.keystore</filename> + </para> + </step> + <step> + <para> + Import your key into the Sun JDK keystore (this is required to help running gadget features) with the following command: + </para> +<programlisting>keytool -importkeystore -srckeystore server.keystore -destkeystore $JAVA_HOME/jre/lib/security/cacerts</programlisting> + </step> + </procedure> + </section> + + <section id="sect-Installation_Guide-HTTPS_Configuration-Use_In_Jboss"> + <title>Setup JBoss configuration to use your key</title> + <para> + To set the JBoss configuration to use the new key: + </para> + <procedure> + <title><emphasis role="bold"></emphasis></title> + <step> + <para> + Comment the following lines in <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/jbossweb.sar/server.xml</filename>: + </para> +<programlisting><![CDATA[<Connector protocol="HTTP/1.1" port="8080" address="${jboss.bind.address}" + connectionTimeout="20000" redirectPort="8443" > +]]></programlisting> + </step> + <step> + <para> + Uncomment the following lines... + </para> +<programlisting><![CDATA[<Connector protocol="HTTP/1.1" SSLEnabled="true" + port="8443" address="${jboss.bind.address}" + scheme="https" secure="true" clientAuth="false" + keystoreFile="$JAVA_HOME/jre/lib/security/cacerts" + keystorePass="123456" sslProtocol = "TLS" /> +]]></programlisting> + <para> + ...and change the values of <literal>keystoreFile</literal> and <literal>keystorePass</literal> to values of your key. + </para> + </step> + </procedure> + </section> + + <!-- Removed as per JBEPP-671 + <section id="sect-Installation_Guide-HTTPS_Configuration-Use_In_Tomcat"> + <title>Setup Tomcat configuration to use your key</title> + <para> + To set the Tomcat configuration to use the new key: + </para> + <procedure> + <title><emphasis role="bold"></emphasis></title> + <step> + <para> + Comment the following lines in <filename>tomcat/conf/server.xml</filename>: + </para> +<programlisting><![CDATA[<Connector port="8080" protocol="HTTP/1.1" + maxThreads="150" connectionTimeout="20000" + redirectPort="8443" URIEncoding="UTF-8" + emptySessionPath="true"/ > +]]></programlisting> + </step> + <step> + <para> + Uncomment the following lines... + </para> +<programlisting><![CDATA[<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" + maxThreads="150" scheme="https" secure="true" + clientAuth="false" sslProtocol="TLS" + keystoreFile="$JAVA_HOME/jre/lib/security/cacerts" + keystorePass="123456" /> +]]></programlisting> + <para> + ...and change the values of <literal>keystoreFile</literal> and <literal>keystorePass</literal> to values of your key. + </para> + </step> + </procedure> + </section>--> + + <section> + <title><emphasis role="bold">Restart</emphasis></title> + <para> + Once you have configured your environment, restart your &PRODUCT; instance. + </para> + <para> + You can now access the portal via address: <literal>https://<replaceable>&lt;ServerAddress&gt;</replaceable>:8443/portal</literal> + </para> + </section> +</section> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Installation.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Installation.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Installation.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -11,10 +11,10 @@ <title>Downloading</title> <para> - The officially supported versions are available from the JBoss Customer Support Portal (CSP) located at <ulink url="https://support.redhat.com/jbossnetwork/restricted/main.html&qu...;. Platforms including in your Support subscription are listed in the <literal>Software</literal> section. + The officially supported versions are available from the JBoss Customer Support Portal (CSP) located at <ulink url="https://access.redhat.com/home">https://access.redhat.c...;. Platforms including in your Support subscription are listed in the <literal>Software</literal> section. </para> </section> - + <section id="Installing"> <title>Installing</title> @@ -24,9 +24,11 @@ <itemizedlist> <listitem> <para> - Unzip <literal>jboss-epp-<replaceable>&lt;release&gt;</replaceable>.zip</literal> to extract the archive contents into the location of your choice. You can do this using the JDK <literal>jar</literal> tool (or any other ZIP extraction tool). <programlisting> - [vsr]$ <literal>cd jbeppinstallationdir</literal> - [vsr]$ <literal>jar -xvf jboss-epp-<replaceable>&lt;release&gt;</replaceable>.zip</literal></programlisting> + Unzip <literal>jboss-epp-<replaceable>&lt;release&gt;</replaceable>.zip</literal> to extract the archive contents into the location of your choice. You can do this using the JDK <literal>jar</literal> tool (or any other ZIP extraction tool). +<programlisting> +[vsr]$ <literal>cd jbeppinstallationdir</literal> +[vsr]$ <literal>jar -xvf jboss-epp-<replaceable>&lt;release&gt;</replaceable>.zip</literal> +</programlisting> </para> </listitem> <listitem> @@ -39,8 +41,10 @@ <note> <title>Server Configurations</title> <para> - Six types of server configurations will be included in your installation: <literal>minimal</literal>, <literal>default</literal>, <literal>production</literal>, <literal>all</literal>, <literal>standard</literal> and <literal>web</literal>. - The Getting Started Guide of &JBEAP; 5.0 explains in detail the different server configuration file sets. + Six types of server configurations will be included in your installation: <literal>minimal</literal>, <literal>default</literal>, <literal>production</literal>, <literal>all</literal>, <literal>standard</literal> and <literal>web</literal>. + </para> + <para> + The &JBEAP; <ulink type="http" url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_... Started Guide</ulink> explains in detail the different server configuration file sets. </para> </note> @@ -69,7 +73,7 @@ </listitem> <listitem> <para> - the <literal>production</literal> server configuration includes Portal components and clustering services. It is preconfigured with default settings which would be more accurate for a production environment. + the <literal>production</literal> server configuration includes Portal components and clustering services. It is preconfigured with default settings which would be more accurate for a production environment. </para> </listitem> </itemizedlist> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Installation_Guide.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Installation_Guide.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Installation_Guide.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -15,7 +15,8 @@ <xi:include href="Post_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Test_Your_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Uninstall_JBoss.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Uninstall_JBoss.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <index /> </book> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Introduction.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Introduction.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Introduction.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -18,7 +18,7 @@ <section id="Introduction-Other_Manuals"> <title>Other Manuals</title> <para> - If 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 <ulink url="http://www.redhat.com/docs/manuals/jboss"></ulink>;. + If 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 <ulink url="http://docs.redhat.com/docs/en-US/index.html"></ulin...;. </para> </section> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Launching.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Launching.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Launching.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -18,7 +18,7 @@ </step> <step> <para> - Within this directory navigate to <filename>/jboss-as/bin</filename>. + Within this directory navigate to <filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/bin</filename>. </para> </step> <step> @@ -62,7 +62,7 @@ <procedure> <step> <para> - Navigate to the <filename>/jboss-as/bin</filename> directory as discussed in <xref linkend="sect-Install_Guide-Launching_PRODUCT-Launching_a_Zip_installation" />. + Navigate to the <filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/bin</filename> directory as discussed in <xref linkend="sect-Install_Guide-Launching_PRODUCT-Launching_a_Zip_installation" />. </para> </step> <step> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Post_Installation.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Post_Installation.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Post_Installation.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -14,7 +14,7 @@ On a Linux Platform </title> <para> - Create an environment variable that points to the installation directory (<filename>JBOSS_DIST/jboss-as</filename>) and call it <literal>JBOSS_HOME</literal>. Add <literal>$JBOSS_HOME/bin</literal> 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 <filename>.bashrc</filename> file in your home directory. + Create an environment variable that points to the installation directory (<filename><replaceable>&lt;JBOSS_DIST&gt;</replaceable>/jboss-as</filename>) and call it <literal>JBOSS_HOME</literal>. Add <literal>$JBOSS_HOME/bin</literal> 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 <filename>.bashrc</filename> file in your home directory. </para> </formalpara> <programlisting> @@ -32,10 +32,14 @@ </title> <para> Create an environment variable called <literal>JBOSS_HOME</literal> that points to the installation directory, for example: <filename>C:\jboss-epp-5.0\jboss-as\</filename>. - In order to run the server from the command line add the <filename>bin</filename> directory to your path, for example: <filename>C:\jboss-epp-5.0\jboss-as\bin</filename>. - 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. </para> </formalpara> + <para> + In order to run the server from the command line add the <filename>bin</filename> directory to your path, for example: <filename>C:\jboss-epp-5.0\jboss-as\bin</filename>. + </para> + <para> + 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. + </para> </section> <section id="Adjust_Memory_Settings"> @@ -51,9 +55,9 @@ <para><remark>End Note to Reviewer</remark></para> --> <para> - If the server is running out of memory, you may adjust the memory settings before deploying the applications. You can do this by updating <literal>JAVA_OPTS</literal> settings in the file <filename>JBOSS_DIST/jboss-as/bin/run.conf</filename> on Linux or <filename>JBOSS_DIST/jboss-as/bin/run.conf.bat</filename> on Windows. The default values don't take into account the memory requirements of your applications: + If the server is running out of memory, you may adjust the memory settings before deploying the applications. You can do this by updating <literal>JAVA_OPTS</literal> settings in the file <filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/bin/run.conf</filename> on Linux or <filename><replaceable>JBOSS_HOME</replaceable>/jboss-as/bin/run.conf.bat</filename> on Windows. The default values don't take into account the memory requirements of your applications: <programlisting> - -Xms1303m -Xmx1303m -XX:MaxPermSize=256m .... +-Xms1303m -Xmx1303m -XX:MaxPermSize=256m .... </programlisting> </para> </section> @@ -73,33 +77,34 @@ It 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. </para> </important> - + <note> + <title><replaceable>JBOSS_HOME</replaceable> and <replaceable>&lt;PROFILE&gt;</replaceable></title> + <para> + <replaceable>JBOSS_HOME</replaceable> is the <filename>jboss-as</filename> directory, a level above the bin directory. <replaceable>&lt;PROFILE&gt;</replaceable> is the chosen server profile: all, default, minimal production, standard or web. + </para> + </note> <formalpara><title>Set up the <literal>jmx-console</literal> users and roles</title> <para> - Edit the <filename>jmx-console-users.properties</filename> file located in the <filename>$JBOSS_HOME/server/$CONFIG/conf/props/</filename> directory defining the username and password: + Edit the <filename>jmx-console-users.properties</filename> file located in the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/props/</filename> directory defining the username and password: </para> </formalpara> <programlisting>user=password</programlisting> <para> - Edit the <filename>jmx-console-roles.properties</filename> file located in the <filename>$JBOSS_HOME/server/$CONFIG/conf/props/</filename> directory to define the user's roles: + Edit the <filename>jmx-console-roles.properties</filename> file located in the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/conf/props/</filename> directory to define the user's roles: </para> <programlisting>user=JBossAdmin,HttpInvoker</programlisting> <formalpara><title>Set up the <literal>admin-console</literal> users and roles</title> <para> - Edit the <filename>web-console-users.properties</filename> file located in the <filename>$JBOSS_HOME/server/$CONFIG/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/</filename> directory: + Edit the <filename>web-console-users.properties</filename> file located in the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/</filename> directory: </para> </formalpara> <programlisting>user=password</programlisting> <para> - Edit the <filename>web-console-roles.properties</filename> file located in the <filename>$JBOSS_HOME/server/$CONFIG/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/</filename> directory: + Edit the <filename>web-console-roles.properties</filename> file located in the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/management/console-mgr.sar/web-console.war/WEB-INF/classes/</filename> directory: </para> <programlisting>user=JBossAdmin,HttpInvoker</programlisting> - <note><title>$JBOSS_HOME and $CONFIG</title> - <para> - <varname>$JBOSS_HOME</varname> is the <filename>jboss-as</filename> directory, a level above the bin directory. <varname>$CONFIG</varname> is the chosen server configuration - all, default, minimal production, standard or web. - </para> - </note> + <important> <para> Login credentials for the <literal>admin-console</literal> are the same as those used for the JMX console. @@ -108,11 +113,13 @@ <formalpara> <title>Set SuckerPassword for JBoss Messaging:</title> <para> - 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 <literal>suckerPassword</literal> attribute in the Server Peer configuration file: - <programlisting>$JBOSS_HOME/server/$CONFIG/deploy/messaging/messaging-jboss-beans.xml</programlisting> - Where <literal>$JBOSS_HOME</literal> is the install directory and <literal>$CONFIG</literal> is the server configuration being used. - To avoid a security risk, you MUST specify the value of the <literal>SuckerPassword</literal> attribute, failing which the default value will be used. Any one who knows the default password will be able to gain access to any destinations on the server. The following fragment should be uncommented and modified: - <programlisting>&lt;bean name="SecurityStore" + 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 <literal>suckerPassword</literal> attribute in the Server Peer configuration file: <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/messaging/messaging-jboss-beans.xml</filename>. + </para> + </formalpara> + <para> + To avoid a security risk, you MUST specify the value of the <literal>SuckerPassword</literal> attribute, failing which the default value will be used. Any one who knows the default password will be able to gain access to any destinations on the server. The following fragment should be uncommented and modified: + </para> +<programlisting>&lt;bean name="SecurityStore" class="org.jboss.jms.server.jbosssx.JBossASSecurityMetadataStore"&gt; &lt;!­­ default security configuration ­­­&gt; ­... @@ -124,8 +131,7 @@ ­... &lt;/bean&gt; </programlisting> - </para> - </formalpara> + </section> <section id="Disabling_Authentication"> @@ -134,23 +140,14 @@ <para> It is possible to disable authentication for specific services by following the instructions in this section. </para> - <para> - All paths specified in the sub-sections below are relative to <literal>$JBOSS_HOME</literal>. - </para> + <formalpara> <title>Disabling Authentication for JXM Console:</title> <para> - To disable authentication for the JMX console, edit the following file and comment out the security-constraint section: + To disable authentication for the JMX console, edit the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/jmx-console.war/WEB-INF/web.xml</filename> file and comment out the security-constraint section: </para> </formalpara> - <programlisting> -server/$CONFIG/deploy/jmx-console.war/WEB-INF/web.xml -</programlisting> - <para> - The following fragment should be commented out: - </para> -<programlisting> &lt;security-constraint&gt; &lt;web-resource-collection&gt; &lt;web-resource-name&gt;HtmlAdaptor&lt;/web-resource-name&gt; @@ -159,8 +156,6 @@ role JBossAdmin to access the HTML JMX console web application &lt;/description&gt; &lt;url-pattern&gt;/*&lt;/url-pattern&gt; - &lt;http-method&gt;GET&lt;/http-method&gt; - &lt;http-method&gt;POST&lt;/http-method&gt; &lt;/web-resource-collection&gt; &lt;auth-constraint&gt; &lt;role-name&gt;JBossAdmin&lt;/role-name&gt; @@ -170,12 +165,8 @@ <formalpara> <title>Disabling Authentication for Web Console:</title> <para> - To disable authentication for the Web console, edit the following file to comment out the security-constraint section: - <programlisting> -server/$CONFIG/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml - </programlisting> - The following fragment should be commented out: - <programlisting> + To disable authentication for the Web console, edit the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml</filename> file to comment out the security-constraint section: +<programlisting> &lt;security-constraint&gt; &lt;web-resource-collection&gt; &lt;web-resource-name&gt;HtmlAdaptor&lt;/web-resource-name&gt; @@ -196,12 +187,8 @@ <formalpara> <title>Disabling Authentication for HTTP Invoker:</title> <para> - To disable authentication for the http invoker, <literal>JNDIFactory</literal>, <literal>EJBInvokerServlet</literal>, and <literal>JMXInvokerServlet</literal> need to be removed from the security realm in the file: - <programlisting> -server/$CONFIG/deploy/httpha-invoker.sar/invoker.war/WEB-INF/web.xml - </programlisting> - For example, the security-constraint element should look as follows: - <programlisting> + To disable authentication for the http invoker, <literal>JNDIFactory</literal>, <literal>EJBInvokerServlet</literal>, and <literal>JMXInvokerServlet</literal> need to be removed from the security realm in the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml/deploy/httpha-invoker.sar/invoker.war/WEB-INF/web.xml</filename> file: +<programlisting> &lt;security-constraint&gt; &lt;web-resource-collection&gt; &lt;web-resource-name&gt;HttpInvokers&lt;/web-resource-name&gt; @@ -222,12 +209,13 @@ <formalpara> <title>Disabling Authentication for JMX Invoker:</title> <para> - To disable authentication for the JMX invoker, edit the following file to comment out the security interceptor passthrough: - <programlisting> -server/$CONFIG/deploy/jmx-invoker-service.xml - </programlisting> - Locate the mbean section with the class <literal>org.jboss.jmx.connector.invoker.InvokerAdaptorService</literal>. In that section comment out the line that relates to authenticated users: - <programlisting> + To disable authentication for the JMX invoker, edit the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/deploy/management/console-mgr.sar/web-console.war/WEB-INF/web.xml/deploy/httpha-invoker.sar/invoker.war/WEB-INF/web.xml/deploy/jmx-invoker-service.xml</filename> file to comment out the security interceptor passthrough: + </para> + </formalpara> + <para> + Locate the mbean section with the class <literal>org.jboss.jmx.connector.invoker.InvokerAdaptorService</literal>. In that section comment out the line that relates to authenticated users: + </para> +<programlisting> &lt;descriptors&gt; &lt;interceptors&gt; &lt;!-- Uncomment to require authenticated users --&gt; @@ -238,20 +226,19 @@ policyClass="StripModelMBeanInfoPolicy"/&gt; &lt;/interceptors&gt; &lt;/descriptors&gt; - </programlisting> - </para> - </formalpara> +</programlisting> + <formalpara> <title>Disabling Pre-configured Accounts</title> <para> - &PRODUCT; &VERSION; includes four pre-configured user accounts for testing and evaluation puposes. These accounts can be used for direct access to the portal. + &PRODUCT; includes four pre-configured user accounts for testing and evaluation puposes. These accounts can be used for direct access to the portal. </para> </formalpara> <para> For security reasons, before going in production, you should restrict the access to the login servlet to POST. </para> <para> - To do so, edit the file <filename>$JBOSS_HOME/server/[configuration]/gatein.ear/02portal.war/WEB-INF/web.xml</filename> and add: + To do so, edit the file <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/gatein.ear/02portal.war/WEB-INF/web.xml</filename> and add: </para> <programlisting language="XML" role="XML"><![CDATA[ <security-constraint> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Revision_History.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Revision_History.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Revision_History.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -8,6 +8,20 @@ <title>Revision History</title> <simpara> <revhistory> + <revision> + <revnumber>1.7</revnumber> + <date>Thu Dec 02 2010</date> + <author> + <firstname>Scott</firstname> + <surname>Mumford</surname> + <email&gt;smumford(a)redhat.com&lt;/email&gt; + </author> + <revdescription> + <simplelist> + <member>Incorporated generic updates from 5.1 docs.</member> + </simplelist> + </revdescription> + </revision> <revision> <revnumber>1.6</revnumber> <date>Thu Sep 30 2010</date> Modified: epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Test_Your_Installation.xml =================================================================== --- epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Test_Your_Installation.xml 2010-12-02 02:57:17 UTC (rev 5432) +++ epp/docs/branches/EPP_5_0_Branch/Installation_Guide/en-US/Test_Your_Installation.xml 2010-12-02 03:56:42 UTC (rev 5433) @@ -15,7 +15,7 @@ <itemizedlist> <listitem> <para> - move to the <filename>$JBOSS_HOME/bin</filename> directory; + move to the <filename><replaceable>JBOSS_HOME</replaceable>/bin</filename> directory; </para> </listitem> <listitem> @@ -24,7 +24,7 @@ <itemizedlist> <listitem> <para> - Ensure that you run the configuration corresponding to the <filename>$JBOSS_HOME/server/$CONFIG/</filename> chosen in <xref linkend="form-Portal_EAP-Using_a_MySQL_Database-Creating_a_MySQL_Database"></xref> + Ensure that you run the configuration corresponding to the <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>&lt;PROFILE&gt;</replaceable>/</filename> chosen in <xref linkend="form-Portal_EAP-Using_a_MySQL_Database-Creating_a_MySQL_Database"></xref> </para> </listitem> </itemizedlist> @@ -33,7 +33,7 @@ </itemizedlist> </para> <para> - The example below uses the production configuration. Your output should look like the following (accounting for installation directory differences) and should not contain any error or exception messages: + 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: </para> <programlisting> [user@localhost bin]$ ./run.sh -c production @@ -70,7 +70,7 @@ </programlisting> <note><title>Note: Production server log file</title> <para> - There is no "Server Started" message shown at the console when the server is started using the <literal>production</literal> profile. This message may be observed in the <filename>server.log</filename> file located in the <filename>server/production/log</filename> subdirectory. + There is no "Server Started" message shown at the console when the server is started using the <literal>production</literal> profile. This message may be observed in the <filename>server.log</filename> file located in the <filename><replaceable>JBOSS_HOME</replaceable>/server/production/log</filename> subdirectory. </para> </note> @@ -78,7 +78,7 @@ Ensure that port 8080 is not already in use and open <literal>http://localhost:8080/portal</literal> in your web browser. <footnote> <para> - Note that on some machines, the name localhost won’t resolve properly and you should use the local loopback address 127.0.0.1 instead. + Note that on some machines, the name localhost won’t resolve properly and you should use the local loopback address <ulink type="http" url="127.0.0.1">127.0.0.1</ulink> instead. </para> </footnote> The contents of your page should look similar to this: <xref linkend="Test_your_Installation-Test_your_Installation" />. @@ -97,7 +97,7 @@ </figure> </para> <para> - You are now ready to use &PRODUCT; 5.0. Refer to the User Guide and Reference Guide for more information about the product's feature set and example applications showcasing &PRODUCT; in action. + You are now ready to use &PRODUCT;. Refer to the User Guide and Reference Guide for more information about the product's feature set and example applications showcasing &PRODUCT; in action. </para> </chapter>