Skip to main content
Version: 4.9

CLI Admin Client

The CLI (Command Line Interface) client is used to perform BlueMind administration tasks in command line without having to create scripts.

When coupled with the bm-tick monitoring system, it can be used, among others, to manage it.

Installation​

The bm-cli client is installed by default in BlueMind.

Additional components can be installed to extend the tool's capabilities:

  • bm-plugin-cli-mapi : adds mapi management commands for Outlook
    NB: this package is installed automatically when mapi packages are installed.
  • bm-plugin-cli-setup : ajoute des commandes pour l'installation et la mise à jour de BlueMind

Getting help​

You can get help on a command or a sub-command and how to use them and what options are available using -help or -h.

For example, maintenance -h shows you the maintenance command and its various possible actions:

root@mail:~$ bm-cli maintenance -help
Usage: bm-cli maintenance [-hV] [COMMAND]
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  help                     Displays help information about the specified command
  generate-completion      Generate bash/zsh completion script for bm-cli.
  consolidateIndex         Consolidate a mailbox index
  dump-cache               Dump core caches to a json file
  flush-cache              Flush bm-core caches
  hsm-to-cyrus             Converts HSM snappy spool to a cyrus maildir folder
  list                     List directory entries
  read-cyrus-index         Read a cyrus index file
  repair                   Run repair maintenance operation
  ops                      List available maintenance operations
  full-replication-resync  Force a resync of all IMAP folders
  schema                   check database schema
  xfer                     xfer users from one backend to another backend
Exit Codes:
   0   Successful program execution
   1   Internal software error: an exception occurred when invoking the
         business logic of this command.
  51   Usage error: user input for the command was incorrect, e.g., the wrong
         number of arguments, a bad flag, a bad syntax in a parameter, etc.

For more details on a sub-command, simply type the sub-command – in this example to get help on index consolidation:

root@mail:~$ bm-cli maintenance consolidateIndex -help
Missing required parameter: '<target>'
Usage: bm-cli maintenance consolidateIndex [--no-progress] [--reset]
       [--match=<match>] [--workers=<workers>] <target>
Consolidate a mailbox index
      <target>              email address, domain name or 'all' for all domains
      --match=<match>       regex that entity must match, for example : [a-c].*
      --no-progress         don't display progress messages
      --reset               Reset the index (only the data belonging to the
                              target)
      --workers=<workers>   run with X workers

info

Commands are improved with every version of BlueMind. You may have more (or fewer) commands depending on your installation version.

Make sure you use "bm-cli help" to find out which commands are available.

Practical examples​

tip

Commands can be coupled, either with each other or with other common commands, and included in scripts to perform multiple operations at once.

BlueMind instance status​

The following command detects errors on the core nodes of a BlueMind instance:

bm-cli node status
Exemple d'erreurs remontées par bm-cli node status :
root@bm:~# bm-cli node status
Alerts for 3 days (some might be resolved)
  * [192.168.121.109] ES / elasticsearch-cluster-health: cluster is red @ Fri May 19 08:32:10 GMT 2023
  * [192.168.121.109] heartbeat: bm-hps heartbeats are slow @ Wed May 17 14:57:39 GMT 2023
  * [192.168.121.109] heartbeat: bm-ysnp heartbeats are slow @ Wed May 17 11:43:51 GMT 2023
  * [192.168.121.109] heartbeat: bm-hps heartbeats are slow @ Wed May 17 11:43:51 GMT 2023
  * [192.168.121.109] heartbeat: bm-ysnp heartbeats are slow @ Wed May 17 07:35:24 GMT 2023
  * [192.168.121.109] ES / elasticsearch-cluster-health: cluster is red @ Wed May 17 07:35:08 GMT 2023
  * [192.168.121.109] heartbeat: bm-ysnp heartbeats are slow @ Tue May 16 15:08:50 GMT 2023
  * [192.168.121.109] heartbeat: bm-ysnp heartbeats are slow @ Tue May 16 10:50:49 GMT 2023
  * [192.168.121.109] heartbeat: bm-hps heartbeats are slow @ Tue May 16 10:50:49 GMT 2023
Server 192.168.121.109 (bm-master 192.168.121.109 [mail/smtp, mail/imap, bm/es, bm/core, bm/hps, bm/xmpp, bm/ac, bm/cal, bm/webmail, bm/contact, bm/settings, bm/redirector, bm/nginx, bm/pgsql, bm/pgsql-data, metrics/influxdb]) OK
DMESG Fri May 19 08:31:19 GMT 2023: systemd-journald[266]: File /var/log/journal/1bda33e3d75246aaaa6d2b8bfafcbad6/system.journal corrupted or uncleanly shut down, renaming and replacing.
DMESG Fri May 19 08:31:19 GMT 2023: FAT-fs (vda15): Volume was not properly unmounted. Some data may be corrupt. Please run fsck.

:::info multi-node installation

In multi-node installations, this command should only be executed on a core node, to avoid unnecessary errors or warnings.

:::

Managing users​

Deleting archived (suspended) domain users​

E.g. the command below is used to look for the email addresses of suspended users:

bm-cli user get bluemind.loc --archived --display "email"

You can then couple this command with a "delete" command to remove all the users it returns:

bm-cli user get bluemind.loc --display "email" | jq -r '.[].email' > /tmp/archived.txt
while read account; do bm-cli user delete --dry $account ;done < /tmp/archived.txt

Apply a quota to all users who don't have one​

This operation is performed using several bm-cli and jq commands, which are combined into a single :

  1. Retrieve the list of users with their quotas:

    bm-cli user get bluemind.loc --display 'email quota'

  2. Filter this same command on users with a null quota:

    bm-cli user get bluemind.loc --display 'email quota' |grep null

  3. The "jq" tool then extracts the email for each row returned:

    jq -r '.email'

  4. Finally, the quota upgrade command (here an 80 Mb quota):

    bm-cli user update --quota "81920" $1

Thus, the final command to achieve this in a single line:

bm-cli user get bluemind.loc --display 'email quota' |grep null|jq -r '.email'| xargs -n1 bm-cli user update --quota

Operations on calendars​

Export/import all user calendars​

Use case: As part of a departure process, we want to export all a user's calendars so that they can be re-imported to other users.

  1. Export all the calendars of the user John Doe (username jdoe@bluemind.loc) to the folder /home/user/export/cals :
bm-cli calendar export --output-directory /home/user/export/cals jdoe@bluemind.loc
  1. Import a calendar to another user.
bm-cli calendar import --calendarUid calendar:Default:A1B2C3D4E5F6Z --ics-file-path /home/user/export/cals/jdoe_default.ics hannibal@bluemind.loc
tip

To import the entire set of calendars (exported as above, or from another source), you can include this command in a loop that traverses the export folder and the target user's calendars.

Export calendars for all users​

Use case: For migration or backup, we want to export and save all users' calendars in ICS format.

To do this, we run a loop through all the users, exporting as above:

bm-cli user get bluemind.loc --display 'email' | grep -v null | jq -r '.email' > /tmp/allUser.bluemind.loc
while read account; do bm-cli calendar export --output-directory /tmp/export/cals $account; done < /tmp/allUser.bluemind.loc

This loop exports all calendars, creating a folder for each user:

/tmp/export/cals/
    ./admin@bluemind.loc
       -admin.ics
    ./hannibal@bluemind.loc
       - John+Smith.ics
    ./jdoe@bluemind.loc
       - John+Doe.ics
       - Reunions.ics
    ./patreides@bluemind.loc
       - children.ics
       - on-call+duty.ics
       - Paul+Atreides.ics

Operations on contacts​

Use case: a user wishes to retrieve contacts collected in his personal address book

The procedure below can be used to clean a user's collected address book and transfer their contacts to their personal address book (and testing the import process beforehand):

root@mail:~# bm-cli contact list jdoe@bluemind.loc
{"owner":"05E25C2C-3643-4ED2-997C-4A4F39933D18","uid":"book:Contacts_05E25C2C-3643-4ED2-997C-4A4F39933D18","name":"My contacts"}
{"owner":"05E25C2C-3643-4ED2-997C-4A4F39933D18","uid":"book:CollectedContacts_05E25C2C-3643-4ED2-997C-4A4F39933D18","name":"Collected contacts"}
{"owner":"05E25C2C-3643-4ED2-997C-4A4F39933D18","uid":"408C741B-3FDC-44B6-B1FD-19E79404BFCF","name":"Perso"}
root@mail:~# bm-cli contact deduplicate jdoe@bluemind.loc --addressbook-uid book:CollectedContacts_05E25C2C-3643-4ED2-997C-4A4F39933D18
2 were removed out of 35
root@mail:~# bm-cli contact export jdoe@bluemind.loc --vcf-file-path /tmp/jdoe-collected.vcf --addressbook-uid book:CollectedContacts_05E25C2C-3643-4ED2-997C-4A4F39933D18
addressbook book:CollectedContacts_05E25C2C-3643-4ED2-997C-4A4F39933D18 of jdoe@bluemind.loc was exported
root@mail:~# bm-cli contact import jdoe@bluemind.loc --vcf-file-path /tmp/jdoe-collected.vcf --addressbook-uid 408C741B-3FDC-44B6-B1FD-19E79404BFCF --dry
DRY : AddressBook 408C741B-3FDC-44B6-B1FD-19E79404BFCF of jdoe@bluemind.loc was imported
root@mail:~# bm-cli contact import jdoe@bluemind.loc --vcf-file-path /tmp/jdoe-collected.vcf --addressbook-uid 408C741B-3FDC-44B6-B1FD-19E79404BFCF
AddressBook 408C741B-3FDC-44B6-B1FD-19E79404BFCF of jdoe@bluemind.loc was imported
root@mail:~# bm-cli contact reset jdoe@bluemind.loc --addressbook-uid book:CollectedContacts_05E25C2C-3643-4ED2-997C-4A4F39933D18
Addressbook book:CollectedContacts_05E25C2C-3643-4ED2-997C-4A4F39933D18 of jdoe@bluemind.loc was reset

Activating EAS logs​

bm-cli also enables you to activate or deactivate EAS logs to help manage connection or synchronization problems on cell phones. See Mobile synchronization problems for commands.

Administration & Maintenance​

Perform a global check&repair​

The following command is used to perform a "check and repair" operation on all domain users using 4 threads :

bm-cli maintenance repair domain.net --workers 4

Changing the admin0 password​

Pour diverses raisons, techniques ou pratiques (en cas de perte, par exemple), il peut être utile de modifier le mot de passe de l'utilisateur admin0 sans avoir à se loguer dans BlueMind.

The following command allows you to do this without knowing the old password:

bm-cli user update admin0@global.virt --password "NewPassword"

Updating BM-Tick configuration​

Once the Bm-Tick monitoring tool is installed, you can perform administrative tasks on it. For example, you can redeploy the configuration to all servers in the domain with the following command:

# bm-cli tick reconfigure
tip

Add --dry to test the command: the operation is merely simulated.

# bm-cli tick reconfigure --dry

User and index maintenance​

The bm-cli tool can be used to perform maintenance operations on users, e.g.:

# repair user user@bluemind.loc
bm-cli maintenance repair user@bluemind.loc
# repair all domain users using 4 threads
bm-cli maintenance repair bluemind.loc --numworkers 4
# consolidate user index user@bluemind.loc
bm-cli maintenance consolidateIndex user@bluemind.loc
# process first 100 users returned
bm-cli maintenance consolidateIndex bluemind.loc --from 0 --size 100
# processes the next 50 users
bm-cli maintenance consolidateIndex bluemind.loc --from 101 --size 50
# processes entities starting with a, b or c
bm-cli maintenance consolidateIndex bluemind.loc --match '[a-c].\*'

Installation and upgrade​

The subscription includes access to automatic BlueMind updates as well as additional bm-cli client operations.

info

These operations being sensitive and risky, they should be reserved for use by advanced administrators only.

To have access to these commands, you must install this plugin:

apt install bm-plugin-cli-setup

The additional command setup is available as soon as the plugin is installed:

# get help on available arguments and how to use them
bm-cli setup -h
# install BlueMind by passing the desired configuration parameters as arguments
bm-cli setup install --external-url bluemind.bluemind.loc --domain bluemind.loc --sw-pass Passw0rd
bm-cli setup install --external-url bluemind.bluemind.loc --domain bluemind.loc --sw-pass Passw0rd --set-contact admin@bluemind.loc --reinstall
  • --external-url : BlueMind's external url
  • --domain : domain
  • --set-contact : sets the default e-mail address for subscription expiry notifications
  • --sw-pass : sets the admin password for setupwizard

:::note command lines

For information on command-line options, see the dedicated page BlueMind Upgrade.

:::

Managing SSL certificates​

There are two ways of adding SSL certificates -- for a specific domain or the whole system:

  • by generating them using Let's Encrypt
  • by directly importing files

Commands​

bm-cli certificate file-cert --ca=certificate_authority.pem --cert=cert.pem --key=private_key.pem --domain=<domain>
bm-cli certificate manage-lets-encrypt --contact=no-reply@\<default-domain> --domain=<domain>

Managing Let's Encrypt certification​

You can use Let's Encrypt to generate certificates for a specific domain or for the whole system.

Activation​

To generate a first certificate with Let's Encrypt, use the following command:

bm-cli certificate manage-lets-encrypt --contact=no-reply@"default-domain" --domain="bluemind.loc"
  • --contact: is used to add an email address which will be used to notify when the certificate is about to expire.
    If no address is entered, the address "no-reply@"default-domain" will be used (prerequisite: the default domain must be populated).
  • --domain: the default value is global.virt if no domain is specified

Renewal​

If the domain already have a Let's Encrypt certificate, it can be updated using the following command:

bm-cli certificate manage-lets-encrypt --contact=no-reply@"default-domain" --domain="bluemind.loc"
  • --contact: can be used to edit the email address if necessary, otherwise the existing email address will be kept.
  • --domain: by default global.virt is used if no domain is specified

Manual import​

You can import an SSL certificate manually by adding 3 mandatory files using the following command:

bm-cli certificate file-cert --ca=certificate_authority.pem --cert=cert.pem --key=private_key.pem --domain="bluemind.loc"

  • --domain: by default global.virt is used if no domain is specified