[jboss-cvs] JBossAS SVN: r101506 - projects/docs/enterprise/5.0/Installation_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Feb 25 20:11:39 EST 2010
Author: benlc
Date: 2010-02-25 20:11:38 -0500 (Thu, 25 Feb 2010)
New Revision: 101506
Modified:
projects/docs/enterprise/5.0/Installation_Guide/en-US/Book_Info.xml
projects/docs/enterprise/5.0/Installation_Guide/en-US/Installation_With_ZIP_Download.xml
projects/docs/enterprise/5.0/Installation_Guide/en-US/Post_Installation.xml
projects/docs/enterprise/5.0/Installation_Guide/en-US/Test_Your_Installation.xml
Log:
'committing revisions based on JBPAPP-3280'
Modified: projects/docs/enterprise/5.0/Installation_Guide/en-US/Book_Info.xml
===================================================================
--- projects/docs/enterprise/5.0/Installation_Guide/en-US/Book_Info.xml 2010-02-26 00:56:46 UTC (rev 101505)
+++ projects/docs/enterprise/5.0/Installation_Guide/en-US/Book_Info.xml 2010-02-26 01:11:38 UTC (rev 101506)
@@ -6,7 +6,7 @@
<title>Installation Guide</title>
<subtitle>for Use with JBoss Enterprise Application Platform 5.0</subtitle>
<edition>1.0</edition>
- <pubsnumber>9</pubsnumber>
+ <pubsnumber>10</pubsnumber>
<productname>JBoss Enterprise Application Platform</productname>
<productnumber>5.0</productnumber>
<!-- <pubdate>, 2009</pubdate> -->
Modified: projects/docs/enterprise/5.0/Installation_Guide/en-US/Installation_With_ZIP_Download.xml
===================================================================
--- projects/docs/enterprise/5.0/Installation_Guide/en-US/Installation_With_ZIP_Download.xml 2010-02-26 00:56:46 UTC (rev 101505)
+++ projects/docs/enterprise/5.0/Installation_Guide/en-US/Installation_With_ZIP_Download.xml 2010-02-26 01:11:38 UTC (rev 101506)
@@ -15,24 +15,32 @@
<section id="Installation">
<title>Installation</title>
-
+ <!-- *|*|*| = Leaving these remarks in as they relate to a reviewed update performed on 26/02/10. i.e. "Waveriders" note this is current (as at Feb 10) material.
+ <remark>Change here: removed the native installation form the application unzip instructions.</remark>
+ <remark>Linked the reader to the JBoss Native Installation section instead</remark>
+ -->
<para>
- Download the JBoss Enterprise Application Platform ZIP file from the CSP site that is correct for your operating system and architecture. In this form of installation, unzip the downloaded zip files to the directory of your choice.</para>
-
+ Download the JBoss Enterprise Application Platform ZIP file from the CSP site that is correct for your operating system and architecture. In this form of installation, unzip the downloaded zip files to the directory of your choice.
+ </para>
<itemizedlist>
<listitem>
<para>
Unzip <literal>jboss-eap-<replaceable><release></replaceable>.zip</literal> to extract the archive contents into the location of your choice.</para>
<programlisting>
[vsr]$ <literal>cd /directory/to/install/in</literal>
-[vsr]$ <literal>unzip jboss-eap-<replaceable><release></replaceable>.zip jboss-eap-native-5.0.0-<replaceable><operating_system>-<system_architecture></replaceable>.zip</literal>
+[vsr]$ <literal>unzip jboss-eap-<replaceable><release></replaceable>.zip </literal>
</programlisting>
</listitem>
<listitem>
<para>
- You are done with the installation. You should now have a directory called <filename>jboss-eap-<replaceable><release></replaceable></filename>. Refer to the Getting Started Guide to understand and explore the Platform Directory Structure.
- </para>
+ You should now have a directory called <filename>jboss-eap-<replaceable><release></replaceable></filename>. Refer to <xref linkend="sect-Installation_With_Zip_Download-JBoss_Native_Installation"/> for information regarding the installation of the JBoss Native package.
+ </para>
+ <note><title>Platform Directory Structure</title>
+ <para>
+ Refer to the Getting Started Guide to understand and explore the Platform Directory Structure.
+ </para>
+ </note>
</listitem>
</itemizedlist>
<important>
@@ -46,14 +54,114 @@
This is needed because of the Windows UAC. On Windows 2003 the <guimenuitem>Run As Administrator</guimenuitem> step is not needed as long as the current user has the correct privileges to install the service.
</para>
</important>
- <section>
- <title>JBoss Native Installation Notes</title>
- <formalpara>
+ <section id ="sect-Installation_With_Zip_Download-JBoss_Native_Installation">
+ <title>JBoss Native Installation</title>
+ <!-- *|*|*|
+ <remark>/* start of edits for native zip installation </remark>
+ <remark>Change here: Title changed to JBoss Native Installation.</remark>
+ <remark>Introductory section describing JBoss Native included.</remark>
+ -->
+ <formalpara><title>The Native Package</title>
+ <para>
+ The Native package is an optional component for the JBoss Enterprise Application Platform incorporating JBoss Native and the mod_jk technologies.
+ </para>
+ </formalpara>
+ <para>
+ These technologies are described as follows:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ JBoss Native consists of the Apache Portable Runtime (APR), OpenSSL and Tomcat Native (TC-native);
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Apache Portable Runtime (APR) provides superior scalability, performance, and improved integration with native server technologies. APR is a highly portable library that is at the heart of Apache HTTP Server 2.x. It enables access to advanced IO functionality (for example: sendfile, epoll and OpenSSL), Operating System level functionality (for example: random number generation and system status), and native process handling (shared memory, NT pipes and Unix sockets).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ OpenSSL implements the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols and includes a basic cryptographic library.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tomcat Native (TC-Native) is a Java Native Interface (JNI) that provides much of Tomcat's core functionality in native code rather than Java. This allows for an overall increase in the speed of a server.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ mod_jk is a connector that is used to connect the Tomcat JSP container and other web services such as Apache.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <!-- *|*|*|
+ <remark>
+ The Release notes say that openSSL and APR are included in Operating System but APR is not included. So reference to APR has been removed from the note below.
+ </remark>
+ -->
+ <note><title>openSSL</title>
+ <para>
+ The Red Hat Enterprise Linux 5 distribution of the Native package does not contain
+ OpenSSL as this is already packaged with the Operating System.
+ </para>
+ </note>
+ <!-- *|*|*|
+ <remark>Linux zip installation covered separately here (removed from "Installation With ZIP Download")</remark>
+ -->
+ <formalpara>
+ <title>Linux Installation Notes for JBoss Native</title>
+ <para>
+ For Linux, there are 32-bit and 64-bit installations of JBoss Native available. Download the appropriate zip file for your operating system and architecture. Once downloaded, copy or move the zip file to the directory one level above the <filename>jboss-eap-<replaceable><release></replaceable></filename> directory. This is the <quote><literal>/directory/to/install/in</literal></quote> referred to in <xref linkend="Installation"/>.
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Unzip the JBoss Native package:
+ </para>
+
+ <programlisting>
+[vsr]$ <literal>cd /directory/to/install/in</literal>
+[vsr]$ <literal>unzip jboss-eap-native-5.0.0-<replaceable><operating_system></replaceable>-<replaceable><system_architecture></replaceable>.zip </literal>
+</programlisting>
+ </listitem>
+ <listitem>
+ <para>
+ Once unzipped, the package will be installed in the <filename>jboss-eap-<replaceable><release></replaceable></filename> directory as a <filename>native</filename> subdirectory.
+ </para>
+<programlisting>jboss-eap-<replaceable><release></replaceable>
+| `-- jboss-as
+| `-- native
+| `-- resteasy
+| `-- seam</programlisting>
+ </listitem>
+ </itemizedlist>
+ <!-- *|*|*|
+ <remark>
+ The APR package is covered in the note below as it is not included in RHEL 5. JBPAPP-3280
+ </remark>
+ -->
+ <note><title>APR Packages</title>
+ <para>
+ Ensure that the APR packages (apr and apr-util) are installed on the system prior to starting the server. Determine whether the packages are installed:
+ <programlisting>[vsr]$ yum list apr apr-util</programlisting>
+ If they are not installed run the following command as the root user:
+ <programlisting>[root]$ yum install apr apr-util</programlisting>
+ </para>
+ </note>
+ <!-- *|*|*|
+ <remark>end of edits for native zip installation */ </remark>
+ -->
+ <formalpara>
<title>Windows Installation Notes for JBoss Native</title>
<para>
- The version of the <filename>jboss-eap-native</filename> package being installed on Windows, must align with the architecture version of the isntalled JVM. If you have a 32-bit JVM installed on a 64-bit Windows system then a 32-bit JBoss Native package will need to be installed.
+ The version of the <filename>jboss-eap-native</filename> package being installed on Windows, must align with the architecture version of the installed JVM. If you have a 32-bit JVM installed on a 64-bit Windows system then a 32-bit JBoss Native package will need to be installed.
</para>
- </formalpara>
+ </formalpara>
<formalpara>
<title>Solaris Installation Notes for JBoss Native</title>
<para>
Modified: projects/docs/enterprise/5.0/Installation_Guide/en-US/Post_Installation.xml
===================================================================
--- projects/docs/enterprise/5.0/Installation_Guide/en-US/Post_Installation.xml 2010-02-26 00:56:46 UTC (rev 101505)
+++ projects/docs/enterprise/5.0/Installation_Guide/en-US/Post_Installation.xml 2010-02-26 01:11:38 UTC (rev 101506)
@@ -48,7 +48,11 @@
<para>
To avoid memory issues, 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> to match your application requirements. The default settings are:
<programlisting>
- -Xms1303m -Xmx1303m -XX:PermSize=256m -XX:MaxPermSize=256m
+ <!-- *|*|*| = Leaving these remarks in as they relate to a reviewed update performed on 26/02/10. i.e. "Waveriders" note this is current (as at Feb 10) material.
+ <remark>Change here: new format in the run.conf file (i.e. no -XX:PermSize=256m)</remark>
+ -->
+ -Xms1303m -Xmx1303m -XX:MaxPermSize=256m
+ <!-- -Xms1303m -Xmx1303m -XX:PermSize=256m -XX:MaxPermSize=256m -->
</programlisting>
</para>
<important>
@@ -61,16 +65,54 @@
<title>
Post Installation Security Configuration
</title>
+ <!-- *|*|*|
+ <remark>Changed the majority of this section. eg *-roles.properties files not mentioned but must be edited for access to the consoles.</remark>
+ -->
<para>
- When installed from the zip archive, all JBoss services require authentication to access most JBoss services, including administrative services. Additionally no user accounts are set up. This is to stop default user/password-based attacks.
+ When 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.
</para>
+ <important><title>Default admin user configuration</title>
+ <para>
+ 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 user/password definition format only.
+ </para>
+ </important>
+ <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:
+ </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:
+ </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:
+ </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:
+ </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>
+ <!-- This content is prior to a Feb 10 update.
<formalpara>
<title>Set up Accounts for <literal>jmx-console</literal> and the invokers by modifying:</title>
<para>
<filename>$JBOSS_HOME/server/$CONFIG/conf/props/jmx-console-users.properties</filename>
</para>
</formalpara>
+ <para>
+ Change the # admin=JBossAdmin,HttpInvoker to user=JBossAdmin,HttpInvoker
+ </para>
<formalpara>
<title>Set up Accounts for <literal>web-console</literal> users by modifying:</title>
<para>
@@ -82,33 +124,40 @@
Login credentials for the <literal>admin-console</literal> are the same as those used for the JMX console.
</para>
</important>
+ -->
+ <!-- *|*|*|
+ <remark>SuckerPassword changed to suckerPassword</remark>
+ -->
<formalpara>
- <title>Set SuckerPassword for JBoss Messaging:</title>
+ <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 this parameter <literal>SuckerPassword</literal> in the configuration file:
+ 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 this parameter <literal>suckerPassword</literal> in the configuration file:
+ </para>
+ </formalpara>
<programlisting>
- $JBOSS_HOME/server/$CONFIG/messaging/messaging-jboss-beans.xml
+ <!-- *|*|*|
+ <remark>changed the path here "deploy" was not included</remark>
+ -->
+ $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 attribute <literal>SuckerPassword</literal>, 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>
- <mbean code="org.jboss.jms.server.ServerPeer"
- name="jboss.messaging:service=ServerPeer"
- xmbean-dd="xmdesc/ServerPeer-xmbean.xml">
+ <!-- Where <literal>$JBOSS_HOME</literal> is the install directory and <literal>$CONFIG</literal> is the server configuration being used.
+ -->
+ <para>
+ To avoid a security risk, you MUST specify the value of the attribute <literal>suckerPassword</literal>, otherwise the default value will be used. Knowledge of the default password will allow access to any destination on the server. The following fragment should be uncommented and modified:
+ </para>
+ <!-- *|*|*|
+ <remark>Changed xml file extract as it is now different than what was listed</remark>
+ -->
+ <programlisting><bean name="SecurityStore" class="org.jboss.jms.server.jbosssx.JBossASSecurityMetadataStore">
+ <!-- default security configuration -->
...
...
...
+ <property name="suckerPassword">CHANGE ME!!</property>
...
- <!-- The password used by the message sucker connections to create connections.
- THIS SHOULD ALWAYS BE CHANGED AT INSTALL TIME TO SECURE SYSTEM -->
- <attribute name="SuckerPassword"></attribute>
-
...
...
- ...
- </mbean>
- </programlisting>
- </para>
- </formalpara>
+</bean></programlisting>
+
</section>
</chapter>
Modified: projects/docs/enterprise/5.0/Installation_Guide/en-US/Test_Your_Installation.xml
===================================================================
--- projects/docs/enterprise/5.0/Installation_Guide/en-US/Test_Your_Installation.xml 2010-02-26 00:56:46 UTC (rev 101505)
+++ projects/docs/enterprise/5.0/Installation_Guide/en-US/Test_Your_Installation.xml 2010-02-26 01:11:38 UTC (rev 101506)
@@ -4,8 +4,11 @@
<chapter id="Test_your_Installation">
<title>Test your Installation</title>
+ <!-- *|*|*| = Leaving these remarks in as they relate to a reviewed update performed on 26/02/10. i.e. "Waveriders" note this is current (as at Feb 10) material.
+ <remark>Change here: referred only to JBOSS_HOME. Removed reference to JBOSS_DIST/jboss-as/bin</remark>
+ -->
<para>
- After you have installed the JBoss Enterprise Application Platform, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. Make sure you have set the <literal>JBOSS_HOME</literal> envirnoment variables as explained in <ulink url="Post_Installation_Configuration"/>. To test your installation, move to <filename>JBOSS_DIST/jboss-as/bin</filename> directory and execute the <filename>run.bat</filename> (for Windows) or <filename>run.sh</filename> (for Linux) script, as appropriate for your operating system. Your output should look like the following (accounting for installation directory differences) and contain no error or exception messages:
+ After you have installed the JBoss Enterprise Application Platform, it is wise to perform a simple startup test to validate that there are no major problems with your Java VM/operating system combination. Make sure you have set the <literal>JBOSS_HOME</literal> environment variable as explained in <ulink url="Post_Installation_Configuration"/>. To test your installation, move to the <filename>$JBOSS_HOME/bin</filename> directory and execute the <filename>run.bat</filename> (for Windows) or <filename>run.sh</filename> (for Linux) script, as appropriate for your operating system. Your output should look like the following (accounting for installation directory differences) and contain no error or exception messages:
</para>
<programlisting>
[vrenish at vinux bin]$ ./run.sh
@@ -34,8 +37,21 @@
18:45:50,449 INFO [ServerInfo] OS-System: Linux 2.6.9-42.0.3.EL,i386
18:45:51,824 INFO [Server] Core system initialized
18:45:59,622 INFO [WebService] Using RMI server codebase: http://127.0.0.1:8083 /
-18:45:59,659 INFO [Log4jService$URLWatchTimerTask] Configuring from URL: resour ce:jboss-log4j.xml
+18:45:59,659 INFO [Log4jService$URLWatchTimerTask] Configuring from URL: resource:jboss-log4j.xml
</programlisting>
+<!-- *|*|*|
+ <remark>/* Added from here ... JBPAPP-3280</remark>
+-->
+<formalpara><title>APR Message</title>
+ <para>
+ When using the JBoss Native zip installation, install apr and apr-util as discussed in <xref linkend="sect-Installation_With_Zip_Download-JBoss_Native_Installation"/> if the following message is displayed when starting the server:
+ <programlisting>WARN [AprLifecycleListener] The Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: /home/user/installLocation/jboss-eap-5.0/native/lib.
+ </programlisting>
+ </para>
+</formalpara>
+<!-- *|*|*|
+ <remark>... to here */</remark>
+-->
<note>
<para>
There is no <emphasis>Server Started</emphasis> message shown at the console when the server is started using the <literal>production</literal> profile. This message can be observed in the <filename>server.log</filename> file located in the <filename>server/production/log</filename> subdirectory.
@@ -45,8 +61,13 @@
</para>
</note>
<para>
- Now open <literal>http://localhost:8080</literal> in your web browser. (Make sure you dont have anything else already on your machine using that port).<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.</para></footnote> The contents of your page should look similar to this: <xref linkend="Test_your_Installation-Test_your_Installation" />.
+ Now open <literal>http://localhost:8080</literal> in your web browser. (Make sure you dont have anything else already on your machine using that port).
+ <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.
+ </para>
+ </footnote>
+ The contents of your page should look similar to this: <xref linkend="Test_your_Installation-Test_your_Installation" />.
</para>
<para>
<figure id="Test_your_Installation-Test_your_Installation">
@@ -58,8 +79,31 @@
</mediaobject>
</figure>
</para>
+ <!-- *|*|*|
+ <remark>/* Added from here ... JBPAPP-3280</remark>
+ -->
<para>
+ Clicking on the <guilabel>Administration Console</guilabel> link will redirect the user to a login page. Entering the username and password as configured in <xref linkend="Post-Installation"/> will result in the display of the administration console. If this is not the case, check that the server has been started in one of the <quote>out of the box</quote> supported configurations (see <xref linkend="migration.admin"/>) and that the user accounts have been correctly set up as per the instructions in <xref linkend="Post-Installation"/>.
+ </para>
+ <formalpara><title>The Administration Console and SystemFactoryInfo Messages</title>
+ <para>
+ When accessing the administration console, the following warnings may be displayed or logged:
+ <programlisting>WARN [SystemInfoFactory] System info API not accessible on this platform (native shared library not found in java.library.path).
+INFO [PluginContainerResourceManager] Discovering Resources...
+WARN [JMXDiscoveryComponent] Unable to complete base jmx server discovery (enable DEBUG for stack): java.lang.UnsupportedOperationException: No native library available - Cannot get the process table information without native support
+ </programlisting>
+ </para>
+ </formalpara>
+ <para>
+ These warnings relate to the inability of <application>RHQ</application> to perform process table scans as <application>SIGAR</application>, which is used to monitor external processes, is not packaged with <application>RHQ</application>. These messages are returned due to the fact that <application>RHQ</application> is embedded in the administration console. The messages can therefore be ignored as external process monitoring is not a function performed by the administration console.
+ </para>
+ <!-- *|*|*|
+ <remark>...to here */</remark>
+ -->
+ <para>
You are now ready to use the JBoss Enterprise Application Platform. Refer to the Getting Started Guide for more information about the platform layout and example applications showcasing JBoss in action.
</para>
+
+
</chapter>
More information about the jboss-cvs-commits
mailing list