mx4j/src/docs/english jsr160-explained.xml,1.13,1.14
Simone Bordet <[email protected]> Mon, 21 Feb 2005 11:33:25 +0000
| Newsgroups | gmane.comp.java.mx4j.cvs |
|---|---|
| Message-ID | <[email protected]> |
Update of /cvsroot/mx4j/mx4j/src/docs/english
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv11324/src/docs/english
Modified Files:
jsr160-explained.xml
Log Message:
+ Added section on how to run http-based connectors over HTTPS
+ Removed section on using MX4J with J2SE 5, since now MX4J implements the service provider mechanism
Index: jsr160-explained.xml
===================================================================
RCS file: /cvsroot/mx4j/mx4j/src/docs/english/jsr160-explained.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -C2 -d -r1.13 -r1.14
*** jsr160-explained.xml 13 Feb 2005 18:02:32 -0000 1.13
--- jsr160-explained.xml 21 Feb 2005 11:33:19 -0000 1.14
***************
*** 1261,1264 ****
--- 1261,1435 ----
<section>
+ <title>Using HTTP-based connectors over HTTPS</title>
+ <para>
+ The HTTP-based connectors, namely the soap, hessian and burlap connectors, can be run over the HTTPS
+ protocol.
+ </para>
+ <para>
+ The configuration of the MX4J connector is quite simple, but requires understanding of how certificates
+ and security in general work in the Java platform.
+ <sbr/>
+ You can find more information on the security in the Java platform
+ <ulink url="http://java.sun.com">here</ulink>.
+ <!-- TODO: fix security URL -->
+ </para>
+ <para>
+ HTTP-based MX4J connectors can be run over HTTPS by adding the string "+ssl" (without quotes) to
+ the protocol of the JMXServiceURL normally used to start the connector over the plain HTTP protocol.
+ <sbr/>
+ For example, the JMXServiceURL to start the SOAP connector server over plain HTTP would be something like
+ </para>
+ <para>
+ service:jmx:soap://host:8080/jmxconnector
+ </para>
+ <para>
+ while the JMXServiceURL to start the SOAP connector server over HTTPS would be something like
+ </para>
+ <para>
+ service:jmx:soap+ssl://host:8443/jmxconnector
+ </para>
+ <para>
+ However, this is not enough, since running a web container over HTTPS requires a detailed configuration
+ of the web container itself and of the keystore that contains the certificate with the public key for the
+ SSL protocol.
+ </para>
+ <section>
+ <title>Configuration of the web container</title>
+ <para>
+ The configuration of the web container usually requires to specify a file path for the keystore, the
+ keystore and the key passwords, and of course the HTTPS port the web container will listen to, that
+ must match the port provided in the JMXServiceURL.
+ </para>
+ <para>
+ This configuration is to be specified in the environment Map passed at the moment of the creation of the
+ JMXConnectorServer using the
+ <classname>mx4j.tools.remote.http.HTTPConnectorServer.WEB_CONTAINER_CONFIGURATION</classname>
+ constant as key, and a String that points to the file path of the configuration file as value.
+ <sbr/>
+ Below there is a sample configuration file for the default web container used by MX4J,
+ <ulink url="http://jetty.mortbay.com">Jetty</ulink>.
+ </para>
+ <para>
+ <example>
+ <title>Example Jetty configuration file to run JMXConnectorServers over HTTPS</title>
+ <programlisting>
+ <![CDATA[
+ <?xml version="1.0" encoding="ISO-8859-1" ?>
+ <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
+
+ <Configure class="org.mortbay.jetty.Server">
+ <Call name="addListener">
+ <Arg>
+ <New class="org.mortbay.http.SunJsseListener">
+ <Set name="Port">8443</Set>
+ <Set name="PoolName">P1</Set>
+ <Set name="MaxIdleTimeMs">30000</Set>
+ <Set name="lowResources">30</Set>
+ <Set name="LowResourcePersistTimeMs">2000</Set>
+ <Set name="Keystore"><SystemProperty name="jetty.home" default="."/>/mx4j.ks</Set>
+ <Set name="Password">mx4jmx4j</Set>
+ <Set name="KeyPassword">mx4jmx4j</Set>
+
+ <Set name="HttpHandler">
+ <New class="org.mortbay.http.handler.MsieSslHandler">
+ <Set name="UserAgentSubString">MSIE 5</Set>
+ </New>
+ </Set>
+ </New>
+ </Arg>
+ </Call>
+ </Configure>
+ ]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ Note that the configuration specifies the keystore file path, the keystore and the key passwords.
+ <sbr/>
+ Jetty allows the passwords to be obfuscated; see the Jetty documentation for more details.
+ <!-- TODO: find jetty docs URL -->
+ </para>
+ </section>
+ <section>
+ <title>Configuration of the keystore</title>
+ <para>
+ The keystore must contain a valid certificate issued for the server host where the
+ web container (started by the HTTP-based JMXConnectorServer) will run on.
+ <sbr/>
+ This is normally specified in the common name part of the distinguished name of the certificate.
+ </para>
+ <para>
+ Furthermore, the certificate must be trusted by the client.
+ This means that the certificate must be signed by
+ a well-known certification authority, and that the root certification authority must be present
+ in the trusted certificates of the Java platform on client side, normally stored in the
+ $JAVA_HOME/jre/lib/security/cacerts file.
+ </para>
+ <para>
+ In the more common case of "experiments", or during development, you can create a self-signed
+ certificate using this command:
+ </para>
+ <para>
+ $JAVA_HOME/bin/keytool -genkey -keyalg "RSA" -keystore mx4j.ks -storepass mx4jmx4j -dname "cn=myhost"
+ </para>
+ <para>
+ Replace the keystore file path and password with your choices, and replace the common name value with
+ the host name the web container will run on.
+ </para>
+ <para>
+ To avoid to import this certificate in the trusted certificates of the Java platform on client side, you must
+ specify the following system property (using either the -D syntax in the command line that starts the JVM,
+ or calling
+ <classname>System.setProperty</classname> in your program):
+ </para>
+ <para>
+ javax.net.ssl.trustStore=mx4j.ks
+ </para>
+ <para>
+ Replace the keystore file path with your choice.
+ </para>
+ <para>
+ Needless to say we don't recommend to set these java properties in your programs, nor to share
+ the keystore between client and server. What should be done in real environments is to sign the
+ certificate with a trusted certification authority.
+ </para>
+ </section>
+ <section>
+ <title>Code examples</title>
+ <para>
+ Refer to the examples bundled with the MX4J distribution, specifically the
+ <classname>mx4j.examples.tools.remote.hessian.ssl.*</classname> files.
+ </para>
+ <para>
+ <example>
+ <title>Starting and connecting to the Hessian connector server over HTTPS</title>
+ <programlisting>
+ <![CDATA[
+ // Server side configuration; copy/paste the jetty configuration above into a file named
+ // jetty.mx4j.xml and put it in the directory from where the JVM is launched
+ Map serverEnv = new HashMap();
+ serverEnv.put(HTTPConnectorServer.WEB_CONTAINER_CONFIGURATION, "jetty.mx4j.xml");
+
+ // Note the null host: it will use the current host name, that must match the common name
+ // present in the certificate contained in the keystore
+ JMXServiceURL url = new JMXServiceURL("hessian+ssl", null, 8443, "/hessianjmx");
+
+ JMXConnectorServer cntorServer = JMXConnectorServerFactory.newJMXConnectorServer(url, serverEnv, newMBeanServer());
+ cntorServer.start();
+
+ // Client side configuration; specify the trusted keystore with a system property.
+ // NOT recommended for production environments.
+ System.setProperty("javax.net.ssl.trustStore", "mx4j.ks");
+ JMXConnector cntor = JMXConnectorFactory.connect(url);
+ MBeanServerConnection cntion = cntor.getMBeanServerConnection();
+ int count = cntion.getMBeanCount().intValue();
+ ]]>
+ </programlisting>
+ </example>
+ </para>
+ </section>
+ </section>
+ <!--
+ <section>
<title>How to use MX4J's JSR 160 connectors with J2SE 5+</title>
<para>
***************
*** 1292,1298 ****
This means that by default, J2SE 5 only recognizes JMXServiceURLs of this type:
<sbr/>
! <classname>service:jmx:rmi:///jndi/whatever</classname> and
<sbr/>
! <classname>service:jmx:iiop:///jndi/whatever</classname>,
<sbr/>
and it is only able to instantiate
--- 1463,1469 ----
This means that by default, J2SE 5 only recognizes JMXServiceURLs of this type:
<sbr/>
! service:jmx:rmi:///jndi/whatever and
<sbr/>
! service:jmx:iiop:///jndi/whatever,
<sbr/>
and it is only able to instantiate
***************
*** 1354,1358 ****
</para>
</section>
!
<section>
<title>Porting old MX4J remoting code to JSR 160</title>
--- 1525,1529 ----
</para>
</section>
! -->
<section>
<title>Porting old MX4J remoting code to JSR 160</title>
-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click