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.
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.

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 Local 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 Local 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 Local 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 Local
                     security provider.
                   *Important notice* Make sure that Management Center web
                     application is stopped (offline) before starting this
                     task.

  issue-token      Issue a token for the given user in the Local security
                     provider.
                   *Important notice* Make sure that Management Center web
                     application is stopped (offline) before starting this
                     task.

  revoke-tokens    Revoke all auth tokens for the given user.
                   *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 Local 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.

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.

To add a cluster configuration, you can provide the client configuration (XML or YAML) as shown below (assuming you are in the Management Center installation directory on your terminal):

./bin/mc-conf.sh cluster add --client-config=./hazelcast-client.xml

Creating Users

The user create task creates a new user in the Local security provider.

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’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 Local security provider.

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

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'

Issuing User Auth Token

The user issue-token task issues an auth token for a specified user in the Local security provider. The token inherits authorities (roles) from the user. The created token is displayed in the output:

Successfully issued a token for user 'test_user'.
Token: 'mJMMDfaSWZ1MuqhmGhA8m4erCNZtPi_A4_VyR_y8eH0'
Label: 'test_user_2021-07-07T17:24 EEST'

There is an option to get the token in JSON format by specifying --output-format=json. The output looks like the following:

{"token":"Eh5stkVgdFy9pne6sf0M6a8q6B21wu5FM31eMTcROFg","username":"test_user","label":"test_user_2021-07-16T16:27 EEST"}

Revoking User Auth Tokens

The user revoke-tokens task revokes (deletes) all auth tokens for a specified user. This task works for users from all security providers, not only the Local one.

Configuring LDAP Security Provider

The ldap configure task configures the LDAP security provider.

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.

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.

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.

Configuring JAAS Security Provider

The jaas configure task configures the JAAS security provider.

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.

Configuring OpenID Connect Security Provider

The oidc configure task configures the OpenID Connect security provider.

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.

Configuring SAML Security Provider

The saml configure task configures the SAML security provider.

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.

Configuring Dev Mode Security Provider

The dev-mode configure task configures the Dev Mode security provider.

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.

Resetting Security Provider

The security reset task resets current security provider used in the Management Center. For the Local security provider it also deletes all the existing user accounts. It deletes all user auth tokens.

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

Enabling/Disabling Metrics Persistence

The set metrics-persistence-enabled task lets you choose whether metrics should be persisted to disk or not.

Hiding Sensitive Configuration Properties

The set sensitive-properties task configures the sensitive properties that must not be shown in plain text in Management Center. --hidden-properties is a comma-separated list of member properties to be hidden in the member properties. --masked-config-properties is a comma-separated list of XPath expressions in the member configuration to be masked.

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