You have two options to start Hazelcast Management Center:
- Deploy the file
mancenter
-version.war
on your Java application server/container. - Start Hazelcast Management Center from the command line and then have the Hazelcast cluster members communicate with it. This means that your members should know the URL of the
mancenter
application before they start.
Starting with WAR File
Here are the steps.
- Download the latest Hazelcast ZIP from hazelcast.org. The ZIP contains the
mancenter
-version.war
file under the directorymancenter
. - You can directly start
mancenter
-version.war
file from the command line. The following command will start Hazelcast Management Center on port 8080 with context root 'mancenter' (http://localhost:8080/mancenter
).
java -jar mancenter-*version*.war 8080 mancenter
Enabling TLS/SSL when starting with WAR file
When you start Management Center from the command line, it will serve the pages unencrypted by using "http", by default. To enable TLS/SSL, use the following command line parameters when starting the Management Center:
-
-Dhazelcast.mc.tls.enabled=true
(default is false) -
-Dhazelcast.mc.tls.keyStore=path to your keyStore
-
-Dhazelcast.mc.tls.keyStorePassword=password for your keyStore
-
-Dhazelcast.mc.tls.trustStore=path to your trustStore
-
-Dhazelcast.mc.tls.trustStorePassword=password for your trustStore
You can leave trust store and trust store password values empty to use the system JVM's own trust store.
Following is an example on how to start Management Center with TLS/SSL enabled from the command line:
java -Dhazelcast.mc.tls.enabled=true -Dhazelcast.mc.tls.keyStore=/some/dir/selfsigned.jks -Dhazelcast.mc.tls.keyStorePassword=yourpassword -jar mancenter-3.8.2.war
You can access Management Center from the following HTTPS URL on port 8443: https://localhost:8443/mancenter
To override the HTTPS port, you can give it as the second argument when starting Management Center. For example:
java -Dhazelcast.mc.tls.enabled=true -Dhazelcast.mc.tls.keyStore=/dir/to/certificate.jks -Dhazelcast.mc.tls.keyStorePassword=yourpassword -jar mancenter-3.8.2.war 80 443 mancenter
This will start Management Center on HTTP port 80 and HTTPS port 443 with context path /mancenter
. Note that accessing port 80 with an http://
prefix will redirect the users to an https://
URL on port 443. It means that the users will use HTTPS regardless of the version of the URL they use.
Mutual authentication
Mutual authentication allows cluster members to have their keyStores and Management Center to have their trustStores so that Management Center can know which members it can trust. To enable mutual authentication, you need to use the following command line parameters when starting the Management Center:
-Dhazelcast.mc.tls.mutualAuthentication=REQUIRED
And at member side, you need to set the following JVM arguments when starting the member:
-Djavax.net.ssl.keyStore=path to your keyStore -Djavax.net.ssl.keyStorePassword=yourpassword
Please see the below example snippet to see the full command to start Management Center:
java -Dhazelcast.mc.tls.enabled=true -Dhazelcast.mc.tls.keyStore=path to your keyStore -Dhazelcast.mc.tls.keyStorePassword=password for your keyStore -Dhazelcast.mc.tls.trustStore=path to your trustStore -Dhazelcast.mc.tls.trustStorePassword=password for your trustStore -Dhazelcast.mc.tls.mutualAuthentication=REQUIRED -jar mancenter.war
And the full command to start the cluster member:
java -Djavax.net.ssl.keyStore=path to your keyStore -Djavax.net.ssl.keyStorePassword=yourpassword -Djavax.net.ssl.trustStore=path to your trustStore -Djavax.net.ssl.trustStorePassword=yourpassword -jar hazelcast.jar
The parameter -Dhazelcast.mc.tls.mutualAuthentication
has two options:
-
REQUIRED
: If the cluster member does not provide a keystore or the provided keys are not included in Management Center's truststore, the cluster member will not be authenticated. -
OPTIONAL
: If the cluster member does not provide a keystore, it will be authenticated. But if the cluster member provides keys that are not included in Management Center's truststore, the cluster member will not be authenticated.
Excluding Specific TLS/SSL Protocols
When you enable TLS on the Management Center, it will support the clients connecting with any of the TLS/SSL protocols that the JVM supports by default. In order to disable specific protocols, you need to set the -Dhazelcast.mc.tls.excludeProtocols
command line argument to a comma separated list of protocols to be excluded from the list of supported protocols. For example, to allow only TLSv1.2, you need to add the following command line argument when starting the Management Center:
-Dhazelcast.mc.tls.excludeProtocols=SSLv3,SSLv2Hello,TLSv1,TLSv1.1
When you specify the above argument, you should see a line similar to the following in the Management Center log:
2017-06-21 12:35:54.856:INFO:oejus.SslContextFactory:Enabled Protocols [TLSv1.2] of [SSLv2Hello, SSLv3, TLSv1, TLSv1.1, TLSv1.2]
Configuring Session Timeout
If you have started Management Center from the command line by using the WAR file, by default, sessions that are inactive for
30 minutes are invalidated. To change this, you can use the -Dhazelcast.mc.session.timeout.seconds
command line parameter.
For example, the following command starts Management Center with a session timeout period of 1 minute:
java -Dhazelcast.mc.session.timeout.seconds=60 -jar mancenter-3.9.2.war
If you have deployed Management Center on an application server/container, you can configure the default session timeout period of the application server/container to change the session timeout period for Management Center. If your server/container allows application specific configuration, you can use it to configure the session timeout period for Management Center.
Disabling Multiple Simultaneous Login Attempts
Normally, a user account on Management Center can be used from multiple locations at the same time. If you want to prevent
others from logging in, when there's already someone logged in with the same username, you can start Management Center with
the -Dhazelcast.mc.allowMultipleLogin=false
command line parameter.
NOTE: If you choose to do so, consider also choosing a smaller session timeout value to prevent a leftover session from another location preventing login for a long time. Another option is forcing logout on multiple logins, as described below.
Forcing Logout on Multiple Simultaneous Login Attempts
When you disable multiple simultaneous login attempts, the first one to login with a username stays logged in until
that username explicitly logs out or its session expires. In the meantime, no one else can login with the same username. If you
want to force logout for the first user and let the newcomer login, you need to start Management Center with the
-Dhazelcast.mc.forceLogoutOnMultipleLogin=true
command line parameter.
Using a Dictionary to Prevent Weak Passwords
In order to prevent certain words from being included in the user passwords, you can start the Management Center
with -Dhazelcast.mc.security.dictionary.path
command line parameter which points to a text file that contains a word
on each line. As a result, the user passwords will not contain any dictionary words, making them harder to guess.
The words in the dictionary need to be at least 3 characters long in order to be used for checking the passwords. The shorter
words will be ignored to prevent them from blocking the usage of many password combinations. You can configure
the minimum length of words by starting the Management Center with -Dhazelcast.mc.security.dictionary.minWordLength
command line parameter and setting it to a number.
An example to start the Management Center using the aforementioned parameters is shown below:
java -Dhazelcast.mc.security.dictionary.path=/usr/MCtext/pwd.txt -Dhazelcast.mc.security.dictionary.minWordLength=3 -jar mancenter.war
Starting with an Extra Classpath
You can also start the Management Center with an extra classpath entry (for example, when using JAAS authentication) by using the following command:
java -cp "mancenter-*version*.war:/path/to/an/extra.jar" Launcher 8080 mancenter
On Windows, the command becomes as follows (semicolon instead of colon):
java -cp "mancenter-*version*.war;/path/to/an/extra.jar" Launcher 8080 mancenter
Starting with Scripts
Optionally, you can use the scripts startManCenter.bat
or startManCenter.sh
located in the directory mancenter
to start the Management Center.
Deploying to Application Server
Or, instead of starting at the command line, you can deploy it to your application server (Tomcat, Jetty, etc.).
If you have deployed mancenter-*version*.war
in your already-SSL-enabled web container, configure hazelcast.xml
as follows.
<management-center enabled="true">
https://localhost:sslPortNumber/mancenter
</management-center>
If you are using an untrusted certificate for your container, which you created yourself, you need to add that certificate to your JVM first. Download the certificate from the browser, after this you can add it to JVM as follows.
keytool -import -noprompt -trustcacerts -alias <AliasName> -file <certificateFile> -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass <Password>
Connecting Hazelcast members to Management Center
After you perform the above steps, make sure that http://localhost:8080/mancenter
is up.
Configure your Hazelcast members by adding the URL of your web application to your hazelcast.xml
. Hazelcast members will send their states to this URL.
<management-center enabled="true">
http://localhost:8080/mancenter
</management-center>
If you enabled TLS/SSL on Management Center, then you will need to configure the members with the relevant keystore & trustore. In that case you expand the above configuration as follows.
<management-center enabled="true">
<url>https://localhost:sslPortNumber/mancenter</url>
<mutual-auth>
<factory-class-name>
com.hazelcast.nio.ssl.BasicSSLContextFactory
</factory-class-name>
<properties>
<property name="keyStore">keyStore</property>
<property name="keyStorePassword">keyStorePassword</property>
<property name="protocol">TLS</property>
</properties>
</mutual-auth>
</management-center>
In the example above, Hazelcast's default SSL context factory (BasicSSLContextFactory) is used; you can also provide your own implementation of this factory.
Here are the descriptions for the properties:
- keystore: Path of your keystore file. Note that your keystore's type must be JKS.
- keyStorePassword: Password to access the key from your keystore file.
- keyManagerAlgorithm: Name of the algorithm based on which the authentication keys are provided.
- keyStoreType: The type of the keystore. Its default value is JKS.
- truststore: Path of your truststore file. The file truststore is a keystore file that contains a collection of certificates trusted by your application. Its type should be JKS.
- trustStorePassword: Password to unlock the truststore file.
- trustManagerAlgorithm: Name of the algorithm based on which the trust managers are provided.
- trustStoreType: The type of the truststore. Its default value is JKS.
-
protocol: Name of the algorithm which is used in your TLS/SSL. Its default value is TLS. Available values are:
- SSL
- SSLv2
- SSLv3
- TLS
- TLSv1
- TLSv1.1
- TLSv1.2
See the programmatic configuration example below:
Config config = new Config();
SSLContextFactory factory = new BasicSSLContextFactory();
MCMutualAuthConfig mcMutualAuthConfig = new MCMutualAuthConfig().setEnabled(true).setFactoryImplementation(factory)
.setProperty("keyStore", "/path/to/keyStore")
.setProperty("keyStorePassword", "password")
.setProperty("keyManagerAlgorithm", "SunX509")
.setProperty("trustStore", "/path/to/truststore")
.setProperty("trustStorePassword", "password")
.setProperty("trustManagerAlgorithm", "SunX509");
ManagementCenterConfig mcc = new ManagementCenterConfig()
.setEnabled(true)
.setMutualAuthConfig(mcMutualAuthConfig)
.setUrl("https://localhost:8443/mancenter");
config.setManagementCenterConfig(mcc);
HazelcastInstance hz = Hazelcast.newHazelcastInstance(config);
NOTE: All of the above algorithms support Java 6 and higher versions, except the TLSv1.2 supports Java 7 and higher versions. For the protocol property, we recommend you to provide SSL or TLS with its version information, e.g., TLSv1.2. Note that if you write only SSL or TLS, your application will choose the SSL or TLS version according to your Java version.
Now you can start your Hazelcast cluster, browse to http://localhost:8080/mancenter
or https://localhost:sslPortNumber/mancenter
(depending on installation) and setup your administrator account explained in the next section.
Configuring Update Interval
You can set a frequency (in seconds) for which Management Center will take information from the Hazelcast cluster, using the element update-interval
as shown below. update-interval
is optional and its default value is 3 seconds.
<management-center enabled="true" update-interval="3">
http://localhost:8080/mancenter
</management-center>
Configuring Logging
Management Center uses Logback for its logging. By default, it uses the following configuration:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<layout class="ch.qos.logback.classic.PatternLayout">
<Pattern>
%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n
</Pattern>
</layout>
</appender>
<root level="INFO">
<appender-ref ref="STDOUT"/>
</root>
</configuration>
To change the logging configuration, you can create a custom Logback configuration file and start Management Center with
the -Dlogback.configurationFile
option pointing to your configuration file.
For example, you can create a file named logback-custom.xml
with the following content and set logging level to DEBUG
.
To use this file as the logging configuration, you need to start Management Center with
-Dlogback.configurationFile=/path/to/your/logback-custom.xml
command line parameter:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<layout class="ch.qos.logback.classic.PatternLayout">
<Pattern>
%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n
</Pattern>
</layout>
</appender>
<root level="DEBUG">
<appender-ref ref="STDOUT"/>
</root>
</configuration>