1. Home
  2. Docs
  3. ClusterControl
  4. User Guide (GUI)
  5. MongoDB
  6. Manage



Lists of hosts being managed by ClusterControl for the specific cluster. This includes:

  • ClusterControl node
  • MongoDB shards nodes (MongoDB replica set and sharded cluster)
  • MongoDB config nodes (MongoDB sharded cluster)
  • MongoDB mongos nodes (MongoDB sharded cluster)
  • MongoDB arbiter nodes (MongoDB replica set and sharded cluster)

To remove a host, just select the host and click on the Remove button.


We strongly recommend users avoid removing nodes from this page if they still hold a role inside ClusterControl.


Manages the configuration files of your database hosts. Note that ClusterControl will not perform any restart operation after modifying the configuration file. One has to schedule server reload/restart operation to load the changes into the server runtime.


ClusterControl does not store configuration changes history so there is no versioning at the moment. Only one version exists at one time. It imports the latest configuration files every 30 minutes and overwrites them in the CMON database. This limitation will be improved in the upcoming release where ClusterControl shall support configuration versioning with dynamic import interval.

Field Description
  • Save the changes that you have made and push them to the corresponding node.
  • Re-import configuration if you have:
    • Performed local configuration changes directly on the configuration files.
    • Restarted the MongoDB servers/performed a rolling restart after a configuration change.
  • ClusterControl will trigger a job to fetch the latest modification from each MongoDB node.

Starting from ClusterControl 1.9.7 (September 2023), ClusterControl GUI v2 is the default frontend graphical user interface (GUI) for ClusterControl. Note that the GUI v1 is considered a feature-freeze product with no future development. All new developments will be happening on ClusterControl GUI v2. See User Guide (GUI v2).

Base Template Files

All services configured by ClusterControl use a base configuration template available under /usr/share/cmon/templates on the ClusterControl node. You can directly modify the file to suit your deployment policy however, this directory will be replaced on every package upgrade.

To make sure your custom configuration template files persist across upgrades, store the files under /etc/cmon/templates a directory. When ClusterControl loads up the template file for deployment, files under /etc/cmon/templates will always have higher priority over the files under /usr/share/cmon/templates. If two files having identical names exist on both directories, the one located under /etc/cmon/templates will be used.

The following are template files provided by ClusterControl, related to MongoDB:

Filename Description
mongodb-2.6.conf.org MongoDB 2.x configuration template.
mongodb.conf.org MongoDB 3.x configuration template.
mongodb.conf.percona MongoDB 3.x configuration template for Percona Server for MongoDB.
mongos.conf.org Mongo router (mongos) configuration template.

Dynamic Variables

There are a number of configuration variables that are configurable dynamically by ClusterControl. These variables are represented with a capital letter enclosed by sign @, for example @DATADIR@. The following shows the list of variables supported by ClusterControl for MongoDB-based clusters:

Variable Description
@DATADIR@ Default is /var/lib/mongodb. Value specified during cluster deployment takes precedence.
@MONGODB_PORT@ Default is 27017, 27018, 27019 (depending on the cluster type). Value specified during cluster deployment takes precedence.
@LOGDIR@ Automatically configured based on vendor.
@HOST@ Automatically configured based on hostname/IP address.
@SMALLFILES@ Automatically configured based on disk space.
@PIDFILEPATH@ Automatically configured based on MongoDB data directory.
@REPLICASET_NAME@ Default is my_mongodb_N. Value specified during cluster deployment takes precedence.


Manages external processes that are not part of the cluster, e.g. a web server or an application server. ClusterControl will actively monitor these processes and make sure that they are always up and running by executing the check expression command.

To add a new process to be monitored by ClusterControl, click on Add Custom Managed Process.

Field Description
  • Select the managed host.
Process Name
  • Enter the process name. E.g: “Apache 2”.
Start Command
  • OS command to start the process. E.g: /usr/sbin/apache2 -DFOREGROUND.
  • Full path to the process identifier file. E.g: /var/run/apache2/apache2.pid.
GREP Expression
  • OS command to check the existence of the process. The command must return 0 for true, and everything else for false. E.g: pidof apache2.
  • Removes the managed process from the list of processes managed by ClusterControl.
  • Disables the selected process.


Performs minor software upgrades for database and load balancer software, for example from MongoDB 4.2.x to MongoDB 4.2.y in a rolling upgrade fashion. ClusterControl will perform the software upgrade based on what is available on the package repository for the particular vendor.

For a replica set setup, ClusterControl will only perform the upgrade on the slaves. Once the upgrading job on the slaves successfully completed, you shall promote an upgraded slave as the new master and repeat the same upgrade process once more for the former master (which already demoted as a slave). To promote a slave, go to Nodes→ pick an upgraded slave → Promote Slave.


Database major version upgrade is not supported by ClusterControl. Major version upgrade has to be performed manually as it involves some risky operations like database package removal, configuration compatibility concern, connectors compatibility, etc.

Field  Description
  • Upgrades are performed online on one node at a time. The node will be stopped, then the software will be updated, and then the node will be started again. If a node fails to upgrade, the upgrade process is aborted and manual intervention is required to recover or reinstall the node.
  • If the database-related software is installed from the package repository, clicking on this will trigger an upgrade job using the corresponding package manager.
  • Upgrades should only be performed when it is as little traffic as possible on the cluster.
Check for New Packages
  • Triggers a job to check for any new versions of database-related packages. It is recommended to perform this operation before performing an actual upgrade.
  • You should see a list of packages under the Available Packages, and the bold lines are the ones that can be updated.
Select Nodes to Upgrade
  • Toggle all nodes that you want to upgrade.

Developer Studio

Provides functionality to create Advisors, Auto Tuners, or Mini Programs right within your web browser based on ClusterControl DSL. The DSL syntax is based on JavaScript, with extensions to provide access to ClusterControl’s internal data structures and functions. The DSL allows you to execute SQL statements, run shell commands/programs across all your cluster hosts, and retrieve results to be processed for advisors/alerts or any other actions. Developer Studio is a development environment to quickly create, edit, compile, run, test, debug, and schedule your JavaScript programs.

Advisors in ClusterControl are powerful constructs; they provide specific advice on how to address issues in areas such as performance, security, log management, configuration, storage space, etc. They can be anything from simple configuration advice, warning on thresholds or more complex rules for predictions, or even cluster-wide automation tasks based on the state of your servers or databases.

ClusterControl comes with a set of basic advisors that include rules and alerts on security settings, system checks (NUMA, Disk, CPU), operations, WiredTiger, connections, and so on. The advisors are open source under MIT license, and publicly available at GitHub. Through the Developer Studio, it is easy to import new advisors as a JS bundle or export your own for others to try out.

Field Description
  • Name – Specify the file name including folders if you need them. E.g. shared/helpers/cmon.js will create all appropriate folders if they don’t exist yet.
  • File content:
    • Empty file – Create a new empty file.
    • Template – Create a new file containing skeleton code for monitoring.
    • Generic MySQL Template – Create a new file containing skeleton code for generic MySQL monitoring.
  • Exports the advisor’s directory to a .tar.gz format. The exported file can be imported to Developer Studio through the ClusterControl → Manage → Developer Studio → Import function.
  • Opens the Advisor list page. See Advisors.
  • Saves the file.
  • Moves the file around between different subdirectories.
  • Removes the script.
  • Compiles the script.
Compile and run
  • Compile and run the script. The output appears under the MessageGraph, or Raw response tab underneath the editor.
  • The arrow next to the Compile and Run button allows us to change settings for a script and for example, pass some arguments to the main() function.
Schedule Advisor
  • Schedules the script as an advisor.

For full documentation on ClusterControl Domain Specific Language, see ClusterControl DSL.



This feature is introduced in ClusterControl v1.8.2.

Use tags to allow filtering and searching for clusters. Each cluster can have zero or many tags to help keep the clusters organized. Note that special characters like spaces, tabs and dollar signs are not supported. The created tags can be filtered while looking up the clusters in the Database Cluster list page, by clicking on the magnifier glass icon on the top menu (next to the “Database Clusters” string).

To remove a tag, simply click on the x next to every created tag string.

Tags created here can also be used with ClusterControl CLI using the --with-tags or −−without-tags flag. See s9s-cluster.

Was this article helpful to you? Yes No