Sharded Balancer RunScript Hooks

Bacula Enterprise Only

This solution is only available for Bacula Enterprise. For subscription inquiries, please reach out to sales@baculasystems.com.

For sharded MongoDB backup and restore operations, the Bacula MongoDB Plugin connects through mongos and validates that the balancer is not moving chunks during the protected operation. The plugin does not permanently stop, start, or reconfigure the balancer. Balancer control remains an operator-side procedure because each MongoDB environment can have different maintenance windows, automation, change-control requirements, and Atlas or Kubernetes operator policies.

For this reason, stopping or disabling the balancer is normally handled by one of the following:

A manual MongoDB operating runbook before and after the Bacula job.
A site-specific automation script launched outside Bacula.
Bacula RunScript hooks configured on the MongoDB backup or restore job.

The MongoDB Plugin guardrail still applies: if the plugin detects that the balancer is active when a sharded backup or restore requires it to be stopped, the operation fails instead of continuing with an unsafe logical artifact.

Bacula Job Example

The following example runs a site-local script before the backup job to stop the balancer and another script after the job to restore the normal balancer state. Use FailJobOnError = yes for the pre-job hook so a failed balancer stop does not allow the backup to continue.

Bacula Job with sharded balancer hooks

Job {
   Name = "MongoDB-Sharded-Backup"
   Type = Backup
   Level = Full
   Client = mongodb-fd
   FileSet = "FS-MongoDB-Sharded"
   Schedule = "Nightly"
   Storage = File1
   Pool = Default
   Messages = Standard

   RunScript {
      RunsWhen = Before
      RunsOnClient = yes
      FailJobOnError = yes
      Command = "/opt/bacula/scripts/mongodb-stop-balancer.sh"
   }

   RunScript {
      RunsWhen = After
      RunsOnClient = yes
      RunsOnFailure = yes
      Command = "/opt/bacula/scripts/mongodb-start-balancer.sh"
   }
}

The restore job can use the same pattern when restoring into a sharded target. In that case, the scripts must point to the restore target mongos endpoint, not necessarily the original backup source.

Example Stop Script

The following script is a basic example for self-managed MongoDB deployments. It connects to mongos with mongosh, stops the balancer, and waits until no balancing round is active. Adjust the URI, credential source, TLS options, timeout, logging, and approval controls to match the local MongoDB operating procedure.

/opt/bacula/scripts/mongodb-stop-balancer.sh

#!/bin/sh
set -eu

MONGODB_URI="${MONGODB_URI:-mongodb://backup:secret@mongos1.example.com:27017/admin?authSource=admin}"
TIMEOUT_SECONDS="${TIMEOUT_SECONDS:-300}"

mongosh "${MONGODB_URI}" --quiet --eval "
const timeoutMs = ${TIMEOUT_SECONDS} * 1000;
const start = Date.now();

sh.stopBalancer();

while (sh.isBalancerRunning()) {
  if (Date.now() - start > timeoutMs) {
    throw new Error('Timed out waiting for MongoDB balancer to stop');
  }
  sleep(1000);
}

print('MongoDB balancer is stopped');
"

Example Start Script

The post-job script can re-enable the balancer after the Bacula job completes and after any site-required validation has run. Some environments prefer not to re-enable the balancer automatically, for example when a manual validation gate or a scheduled balancer window is required. In those cases, replace this script with the approved local procedure.

/opt/bacula/scripts/mongodb-start-balancer.sh

#!/bin/sh
set -eu

MONGODB_URI="${MONGODB_URI:-mongodb://backup:secret@mongos1.example.com:27017/admin?authSource=admin}"

mongosh "${MONGODB_URI}" --quiet --eval "
sh.startBalancer();
print('MongoDB balancer start requested');
"

Operational Notes

mongos is the remote MongoDB query router used as the sharded cluster endpoint. It is not a local executable run by the plugin.
mongosh is shown only in these operator-side example scripts. The MongoDB Plugin itself does not require mongosh for backup or restore.
Store script credentials according to the local security policy. Prefer protected files, environment injection, or a secret-management system over clear-text command lines.
Keep the balancer stopped for the whole backup or restore window. The plugin validates this state as a safety guardrail.
In managed environments, such as Atlas or Kubernetes operator deployments, use the vendor-supported method for pausing and resuming balancing instead of copying these scripts unchanged.