A newer version of this documentation is available.

View the latest version

Management Center Configuration Tool

The Management Center Configuration Tool (MC-Conf) is a command line tool that allows you to update certain parts of the Management Center configuration by using its built-in tasks. You can use the mc-conf.sh or mc-conf.bat script to run the MC-Conf tool from the /bin/ folder.

You must run the MC-Conf tool on the same machine where the Management Center web application is deployed.
The Management Center must not be running when changes are made via MC-Conf.

Built-In Help

In order to see all available commands, run the MC-Conf script with no arguments as shown below.

./bin/mc-conf.sh

As the result, you should see an output similar to below.

Hazelcast Management Center Configuration Tool 4.0
Usage: mc-conf [-hV] COMMAND TASK
Command line tool for interacting with Hazelcast Management Center
configuration.

Global options are:
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  cluster           Manage Cluster Connection Configs
  user              Manage Default Security Provider Users
  ldap              Manage LDAP Security Provider
  active-directory  Manage Active Directory Security Provider
  jaas              Manage JAAS Security Provider
  security          General Security Provider management
  set               Change MC settings
  dev-mode          Manage DevMode Security Provider

When you choose a specific subcommand from the list above, you can see all tasks available for it. See the following example:

./mc-conf.sh user
Usage: mc-conf user [-hV] TASK
Manage Default Security Provider Users
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  create           Create a new user record in the default security provider.
                   *Important notice* Make sure that Management Center web
                     application is stopped (offline) before starting this
                     task.

  update-password  Change password for the given user record in the default
                     security provider.
                   *Important notice* Make sure that Management Center web
                     application is stopped (offline) before starting this
                     task.

You can also get specific help for any task by using the -h (or --help) command line option. See the following example:

./mc-conf.sh user create -h
Usage: mc-conf user create [-hvV] [-p[=<password>]] [-H=<homedir>]
                           -n=<username> -r=<role>
Create a new user record in the default security provider.
*Important notice* Make sure that Management Center web application is stopped
(offline) before starting this task.

  -H, --home=<homedir>   Optional path to Management Center home directory. By
                           default ~/hazelcast-mc/ is used.
  -n, --username=<username>
                         Username for the user record.
  -p, --password[=<password>]
                         Password for the user record. Provide value directly
                           or use without value to enter securely with
                           interactive prompt.
  -r, --role=<role>      Roles for the user record. Valid values: readonly,
                           readwrite, metricsonly, admin.
  -h, --help             Show this help message and exit.
  -V, --version          Print version information and exit.
  -v, --verbose          Enable full logging output. Use this option to see
                           full stack traces.

Configuring Cluster Connection

The cluster add task adds a new connection configuration for a cluster. Note that you must stop the Management Center web application before running this task.

You can use this task for various scripting purposes, and automatically configuring Management Center, without the need for a manual cluster connection configuration through UI.

If you have used a non-default Management Center home directory location, you must provide the path to the home directory with the -H (or --home) option.

Creating Users

The user create task creates a new user in the default security provider. Note that you must stop the Management Center web application before running this task.

You can use this task for various scripting purposes. See the Hazelcast Docker Code Samples repository for an example of Docker image for the Management Center container with a built-in user account.

If you have used a non-default Management Center home directory location, then you must provide the path to the home directory with the -H (or --home) option.
If you’re on Linux or MacOS devices and provide value directly to mc-conf, please enclose password in single quotes like: -p='mysecr3tp@s$word'

Changing User Password

The user update-password task resets the password of a specified user in the default security provider. Note that you must stop the Management Center web application before running this task.

You can use this task as a recovery mechanism for the Management Center’s administrator user account.

If you have used a non-default Management Center home directory location, you must provide the path to the home directory with the -H (or --home) option.
If you’re on Linux or MacOS devices and provide value directly to mc-conf, please enclose password in single quotes like: -p='mysecr3tp@s$word'

Configuring LDAP Security Provider

The ldap configure task configures the LDAP security provider. Note that you must stop the Management Center web application, before running this task.

You can use this task for various scripting purposes and automatically configuring Management Center without the need for a manual security provider configuration through UI.

You can encrypt the LDAP password before saving with this task. See the Variable Replacers section for more information.

As with the UI based LDAP configuration, you can also use keystore for secure password storage, by using the optional --key-store-* options, as shown in the examples below.

If you want to use the built-in Management Center managed keystore, you can add the following options: --ks-create --key-store=<hazelcast-mc directory>/mc.jceks --key-store-password=<password>. This creates a keystore in the default Management Center directory, and saves the LDAP password in it. If you want to customize the keystore name or Management Center directory when starting Management Center, you need to reflect that with the --key-store=<path> option.

If you want to use the existing externally managed keystore, you can use the following options: --key-store=<keystore path> --key-store-password=<password> [--key-store-type=<type> --key-store-provider=<provider>]. Note that if the keystore with such path doesn’t exist, task fails.

You still need to properly configure Management Center to use keystore. See LDAP Authentication section for details on using the built-in and existing keystores.
If you have used a non-default Management Center home directory location, then you must provide the path to the home directory with the -H (or --home) option.

Updating LDAP Password

The ldap update-password task updates the encrypted LDAP password stored in the keystore. It expects information about the keystore such as its location and password and the new LDAP password that you want to use. See the LDAP Authentication section for more information on the encrypted LDAP passwords. After updating the LDAP password, you need to click on the Reload Security Config button on the login page.

Configuring Active Directory Security Provider

The active-directory configure task configures the Active Directory security provider. Note that you must stop the Management Center web application before running this task.

You can use this task for various scripting purposes, and automatically configuring Management Center, without the need for a manual security provider configuration through UI.

If you have used a non-default Management Center home directory location, then you must provide the path to the home directory with the -H (or --home) option.

Configuring JAAS Security Provider

The jaas configure task configures the JAAS security provider. Note that you must stop the Management Center web application before running this task.

You can use this task for various scripting purposes, and automatically configuring Management Center, without the need for a manual security provider configuration through UI.

If you have used a non-default Management Center home directory location, then you must provide the path to the home directory with the -H (or --home) option.

Configuring Dev Mode Security Provider

The dev-mode configure task configures the Dev Mode security provider. Note that you must stop the Management Center web application before running this task.

You can use this task for various scripting purposes, and automatically configuring Management Center, without the need for a manual security provider configuration through UI.

If you have used a non-default Management Center home directory location, then you must provide the path to the home directory with the -H (or --home) option.

Resetting Security Provider

The security reset task resets current security provider used in the Management Center. For the default security provider it also deletes all built-in user accounts. Note that you must stop the Management Center web application before running this task.

You can use this task as a recovery mechanism for the Management Center deployment in case if a non-default security provider is configured. In case of the default security provider, you can also use the user create or user update-password task as the recovery mechanism.

If you have used a non-default Management Center home directory location, then you must provide the path to the home directory with the -H (or --home) option.

Enabling/Disabling Metrics Persistence

The set metrics-persistence-enabled task lets you choose whether metrics should be persisted to disk or not. Note that you must stop the Management Center web application before running this task.

Advanced Features

MC-Conf supports interactive options for secure processing of passwords. To use it, you need to use the password option without providing a value, i.e., instead of --password=<password> use --password. When you use this option without providing a value, you will get a prompt to enter a value on the console. An example of the interactive option usage is shown below.

./mc-conf.sh user update-password --username=admin --password
Enter value for --password (Password for the user record. Provide value directly,
or use without value to enter securely with interactive prompt.): ********
Successfully changed password for user 'admin'.

As you see in the above example, the password input is not echoed to the console since it is provided with the secure interactive mode.

Another advanced feature of MC-Conf is the support for argument files. When an argument beginning with the character @ is encountered, it is treated as a path leading to a text file. The contents of that file are automatically expanded into the current task. An example of the argument file usage is shown below.

./mc-conf.sh user update-password @arg-file.txt
Successfully changed password for user 'admin'.
cat arg-file.txt
--username=admin --password=mnb3c4s0