10:43 p.m.
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_Platf...
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_...
+ <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/keyto...
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>