[gatein-commits] gatein SVN: r8440 - epp/docs/branches/5.2/Installation_Guide/en-US.
do-not-reply at jboss.org
do-not-reply at jboss.org
Mon Feb 20 23:43:41 EST 2012
Author: jaredmorgs
Date: 2012-02-20 23:43:40 -0500 (Mon, 20 Feb 2012)
New Revision: 8440
Modified:
epp/docs/branches/5.2/Installation_Guide/en-US/Book_Info.xml
epp/docs/branches/5.2/Installation_Guide/en-US/HTTPSConfiguration.xml
epp/docs/branches/5.2/Installation_Guide/en-US/Installation_Guide.xml
epp/docs/branches/5.2/Installation_Guide/en-US/Revision_History.xml
Log:
Changes to HTTPS Setup section as part of BZ#794440
Modified: epp/docs/branches/5.2/Installation_Guide/en-US/Book_Info.xml
===================================================================
--- epp/docs/branches/5.2/Installation_Guide/en-US/Book_Info.xml 2012-02-20 21:46:06 UTC (rev 8439)
+++ epp/docs/branches/5.2/Installation_Guide/en-US/Book_Info.xml 2012-02-21 04:43:40 UTC (rev 8440)
@@ -9,7 +9,7 @@
<productname>JBoss Enterprise Portal Platform</productname>
<productnumber>5.2</productnumber>
<edition>5.2.1</edition>
- <pubsnumber>1</pubsnumber>
+ <pubsnumber>2</pubsnumber>
<abstract>
<para>
This book provides information about obtaining, installing and running JBoss Enterprise Portal Platform. It forms part of the complete document suite along with the <emphasis role="bold">User Guide</emphasis> and <emphasis role="bold">Reference Guide</emphasis> available at <ulink url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Portal_Platform/index.html" type="http"/>.
Modified: epp/docs/branches/5.2/Installation_Guide/en-US/HTTPSConfiguration.xml
===================================================================
--- epp/docs/branches/5.2/Installation_Guide/en-US/HTTPSConfiguration.xml 2012-02-20 21:46:06 UTC (rev 8439)
+++ epp/docs/branches/5.2/Installation_Guide/en-US/HTTPSConfiguration.xml 2012-02-21 04:43:40 UTC (rev 8440)
@@ -1,118 +1,108 @@
-<?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" [
+<?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>
- JBoss 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.
- </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><PROFILE></replaceable>/deploy/jbossweb.sar/server.xml</filename>:
+ <title><remark>BZ#794440 </remark>HTTPS Configuration</title>
+ <remark>https://bugzilla.redhat.com/show_bug.cgi?id=794440 - 20120221 - Reworked the entire section to cover keystore and truststore configuration specific to EPP. </remark>
+ <para>JBoss Enterprise Portal Platform runs by default in HTTP mode. For security purposes, and to ensure portal gadgets run correctly, configure it to run in HTTPS mode. </para>
+ <important>
+ <para>Understanding the fundamentals of keystore and truststore configuration is critical to the tasks in this section. </para>
+ <para>Refer to the JBoss Enterprise Application Platform <citetitle>Security Guide</citetitle> <citetitle>"SSL Encryption Overview"</citetitle> chapter for detailed encryption theory and procedures relevant to all JBoss Middleware platforms. </para>
+ </important>
+ <para>There are a number of steps required to enable HTTPS on the platform. In summary, the steps are:</para>
+ <orderedlist>
+ <listitem>
+ <para>Generate encryption keys and certificate. </para>
+ </listitem>
+ <listitem>
+ <para>Export the self-signed certificate.</para>
+ </listitem>
+ <listitem>
+ <para>Import the certificate to the trust store.</para>
+ </listitem>
+ <listitem>
+ <para>Define the keystore and truststore details in the HTTPS connector directive file.</para>
+ </listitem>
+ </orderedlist>
+ <task>
+ <title>Task: Enable HTTPS Communication</title>
+ <tasksummary>
+ <para>Follow this procedure to configure the HTTPS connector for the platform.</para>
+ </tasksummary>
+ <taskprerequisites>
+ <title>Prerequisites</title>
+ <itemizedlist>
+ <listitem>
+ <para>Read and understand how keypairs and certificates operate in the "SSL Encryption Overview" section of the JBoss Enterprise Application Platform <ulink url="http://docs.redhat.com/docs/en-US/JBoss_Enterprise_Application_Platform/5/html/Security_Guide/chap-Secure_Socket_Layer.html#sect-keystore-background">
+ <citetitle>Security Guide</citetitle>
+ </ulink></para>
+ </listitem>
+ <listitem>
+ <para>Understand the command-line parameters of <command>keytool</command> as documented in the <ulink url="http://docs.oracle.com/javase/1.5.0/docs/tooldocs/solaris/keytool.html">Oracle Java Tools documentation</ulink> </para>
+ </listitem>
+ <listitem>
+ <para>Know the JDK keystore password (default is "<literal>changeme</literal>").</para>
+ </listitem>
+ </itemizedlist>
+ </taskprerequisites>
+ <procedure>
+ <step>
+ <para>Navigate to<filename> <replaceable>JBOSS_HOME</replaceable>/jboss-as/server/<replaceable>PROFILE</replaceable>/conf/</filename></para>
+ </step>
+ <step>
+ <para>Generate the keystore by executing the following command. Ensure you substitute the <replaceable>values</replaceable> with information relevant to your organization, and record the information for later use:</para>
+ <programlisting>[conf]$ keytool -genkey -alias <replaceable>epp5key</replaceable> -keyalg RSA -keystore <replaceable>server.keystore</replaceable> -storepass <replaceable>123456</replaceable> -keypass <replaceable>123456</replaceable> -dname "CN=<replaceable>Person Name</replaceable>, OU=<replaceable>Org_Unit</replaceable>, O=<replaceable>Organization/URL</replaceable>, L=<replaceable>Server Location</replaceable>, S=<replaceable>State</replaceable>, C=<replaceable>Country</replaceable>"</programlisting>
+ </step>
+ <step>
+ <para>Import the keystore to the JDK keystore by executing the following command. </para>
+ <important>
+ <para>You must enable elevated privileges to execute this command. </para>
+ </important>
+ <programlisting>[conf]# keytool -importkeystore -srckeystore <replaceable>server.keystore</replaceable> -alias <replaceable>epp5key</replaceable> -destkeystore $JAVA_HOME/jre/lib/security/cacerts</programlisting>
+ <para>When prompted, provide the destination (JDK) keystore password, as well as the source keystore password you created in the previous step.</para>
+ </step>
+ <step>
+ <para>Execute the following command to verify the keystore file has been correctly imported into the JDK keystore:</para>
+ <programlisting>[conf]# keytool -list -keystore /usr/java/<replaceable>JDK_VERSION</replaceable>/jre/lib/security/cacerts -alias <replaceable>epp5key</replaceable></programlisting>
+ <formalpara>
+ <title>Result</title>
+ <para>The command returns one PrivateKeyEntry</para>
+ </formalpara>
+ </step>
+ <step>
+ <para>Open <filename><replaceable>JBOSS_HOME</replaceable>/server/<replaceable>PROFILE</replaceable>/deploy/jbossweb.sar/server.xml</filename>:
</para>
-<programlisting language="XML" role="XML"><![CDATA[<Connector protocol="HTTP/1.1" port="8080" address="${jboss.bind.address}"
- connectionTimeout="20000" redirectPort="8443" >
-]]></programlisting>
- </step>
- <step>
- <para>
- Uncomment the following lines...
+ </step>
+ <step>
+ <para>Uncomment the 8443 SSL Connector block, and specify the keystore and truststore values.
</para>
-<programlisting language="XML" role="XML"><![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.
+ <programlisting language="XML"><Connector protocol="HTTP/1.1" SSLEnabled="true" port="8443" address="${jboss.bind.address}"
+ scheme="https" secure="true" clientAuth="false"
+ sslProtocol = "TLS"
+ keystoreFile="${jboss.server.home.dir}/conf/<replaceable>server.keystore</replaceable>"
+ keystorePass="123456"
+ truststoreFile="/usr/java/<replaceable>JDK_VERSION/</replaceable>jre/lib/security/cacerts"
+ truststorePass="<replaceable>changeit</replaceable>"
+ keyAlias="<replaceable>epp5key</replaceable>"
+/></programlisting>
+ <para><literal>keystoreFile</literal> and <literal>keystorePass</literal> attributes point to the <replaceable>server.keystore</replaceable> file stored in the <filename>/conf</filename> directory, while <literal>truststoreFile</literal> and <literal>truststorePass</literal> point to the JDK keystore.
</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 JBoss Enterprise Portal Platform instance.
- </para>
- <para>
+ </step>
+ <step>
+ <para>Save and close the file.</para>
+ </step>
+ <step>
+ <para>Restart the portal.</para>
+ </step>
+ </procedure>
+ </task>
+ <formalpara>
+ <title>Result</title>
+ <para>You have configured the platform to communicate using a secure connection.</para>
+ </formalpara>
+ <para>
You can now access the portal via address: <literal>https://<replaceable><ServerAddress></replaceable>:8443/portal</literal>
</para>
- </section>
</section>
Modified: epp/docs/branches/5.2/Installation_Guide/en-US/Installation_Guide.xml
===================================================================
--- epp/docs/branches/5.2/Installation_Guide/en-US/Installation_Guide.xml 2012-02-20 21:46:06 UTC (rev 8439)
+++ epp/docs/branches/5.2/Installation_Guide/en-US/Installation_Guide.xml 2012-02-21 04:43:40 UTC (rev 8440)
@@ -1,6 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!-- This document was created with Syntext Serna Free. -->
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!-- This document was created with Syntext Serna Free. --><!DOCTYPE book 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 status="draft">
Modified: epp/docs/branches/5.2/Installation_Guide/en-US/Revision_History.xml
===================================================================
--- epp/docs/branches/5.2/Installation_Guide/en-US/Revision_History.xml 2012-02-20 21:46:06 UTC (rev 8439)
+++ epp/docs/branches/5.2/Installation_Guide/en-US/Revision_History.xml 2012-02-21 04:43:40 UTC (rev 8440)
@@ -9,6 +9,20 @@
<simpara>
<revhistory>
<revision>
+ <revnumber>5.2.1-2</revnumber>
+ <date>Mon Feb 21 2012</date>
+ <author>
+ <firstname>Jared</firstname>
+ <surname>Morgan</surname>
+ <email/>
+ </author>
+ <revdescription>
+ <simplelist>
+ <member>Incorporated changes to https://bugzilla.redhat.com/show_bug.cgi?id=794440.</member>
+ </simplelist>
+ </revdescription>
+ </revision>
+ <revision>
<revnumber>5.2.1-1</revnumber>
<date>Mon Feb 20 2012</date>
<author>
More information about the gatein-commits
mailing list