Skip to main content

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. For further information, see Discovering and installing bm-tick.

Installation​

The bm-cli client is installed by default during the BlueMind installation.

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

  • bm-plugin-cli-mapi: adds MAPI management commands for Outlook Note: this package is automatically installed during the installation of the mapi packages.
  • bm-plugin-cli-setup: adds commands for installing and upgrading BlueMind

Getting help​

At any time, you can get help on a command or subcommand, its usage, and options 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.

It is important to refer to the bm-cli --help command to know which ones you can use.

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.

Status of the BlueMind instance​

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

bm-cli node status
Exemple d'erreurs remontées par cette commande :
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-ysnp 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
Server 192.168.121.109 (bm-master 192.168.121.109 [mail/smtp, mail/imap, bm/es, bm/core, 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.
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​

The following command searches for the e-mail addresses of suspended users:

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

It is then possible to pair the output of this command with a loop and a delete command to delete the returned users:

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 done using several bm-cli and jq commands that are grouped into one:

  1. Retrieve the list of users with their quotas:
bm-cli user get bluemind.loc --display 'email quota'
  1. Filtering this same command for users with a null quota:
bm-cli user get bluemind.loc --display 'email quota' | grep null
  1. The jq tool then extracts the email from each returned line:
jq -r '.email'
  1. Finally, the quota upgrade command (here an 80 Mb quota):
bm-cli user update --quota "81920" username@bluemind.loc

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 "81920"

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 the desired calendar from another user :
bm-cli calendar import --calendarUid calendar:Default:A1B2C3D4E5F6Z --ics-file-path /home/user/export/cals/jdoe_default.ics hannibal@bluemind.loc

💡 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 loop through all the users and export 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):

# recherche de l'uid des carnets de l'utilisateur
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"}
# nettoyage du carnet "Collected contacts"
root@mail:~$ bm-cli contact deduplicate jdoe@bluemind.loc --addressbook-uid book:CollectedContacts_05E25C2C-3643-4ED2-997C-4A4F39933D18
2 were removed out of 35
# export au format VCF
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
# import du carnet au format VCF dans le carnet personnel
## test grâce à l'option "dry"
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
## réalisation de l'import
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
# réinitialisation du carnet "Collected contacts"
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 allows you to enable or disable EAS logs to facilitate the management of connection or synchronization issues on mobile. Consult the page Synchronization issues with mobile devices to see the commands.

Administration & Maintenance​

Perform a global check&repair​

The following command allows you to perform the "validate and repair" operation on all users in the bluemind.loc domain using 4 threads:

bm-cli maintenance repair bluemind.loc --workers 4

Changing the admin0 password​

For various reasons, technical or practical (in case of loss, for example), it can be useful to change the password of the admin0 user without having to log in to 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​

When the Bm-Tick monitoring tool is installed (see Discovering and installing bm-tick), it is possible to perform administration 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 allows you to perform various maintenance operations on users, for example:

# réparer l'utilisateur user@bluemind.loc
bm-cli maintenance repair user@bluemind.loc
# réparer l'ensemble des utilisateurs du domaine en utilisant 4 threads
bm-cli maintenance repair bluemind.loc --numworkers 4
# consolider l'index de l'utilisateur user@bluemind.loc
bm-cli maintenance consolidateIndex user@bluemind.loc
# traite les 100 premiers utilisateurs retournés
bm-cli maintenance consolidateIndex bluemind.loc --from 0 --size 100
# traite les 50 utilisateurs suivants
bm-cli maintenance consolidateIndex bluemind.loc --from 101 --size 50
# traite les entités commencant par a, b ou c
bm-cli maintenance consolidateIndex bluemind.loc --match '[a-c].\*'

Log analysis​

The Auditlog tool keeps track of actions and modifications carried out on BlueMind entities.

For further information, see Logs - Configuration and analysis

Installation and update​

The subscription giving access to automated BlueMind updates also provides access to additional operations of the bm-cli client for them.

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:

# obtenir de l'aide sur les arguments disponibles et leur utilisation
bm-cli setup -h
# installer BlueMind en passant en argument les paramètres de configuration souhaités
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
command lines

For command lines, see the dedicated page Updating BlueMind.

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>

Use of Let's Encrypt.​

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
Last updated on