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.

Installation​

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

An additional optional component for Outlook MAPI can be installed using the corresponding package:

$ aptitude install bm-plugin-cli-mapi
info

No restart is required, the commands can be used immediately.

Using the client​

Commands​

Commands are passed using a terminal straight onto the server, connected via ssh for instance.

For example, the command below can help you find a user's address books:

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

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

For example, "help maintenance" shows you the maintenance command and possible actions:

# bm-cli help maintenance
NAME
        bm-cli maintenance - maintenance task(s)

SYNOPSIS
        bm-cli maintenance
        bm-cli maintenance consolidateIndex [--workers <workers>]
        bm-cli maintenance list [--workers <workers>]
        bm-cli maintenance repair [--dry] [--workers <workers>]

COMMANDS
        With no arguments, List directory entries

        list
            List directory entries
...

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

# bm-cli help maintenance consolidateIndex
NAME
        bm-cli maintenance consolidateIndex - Consolidate a mailbox index

SYNOPSIS
        bm-cli maintenance consolidateIndex [--workers <workers>] [--] <target>

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

For example:

# bm-cli help
usage: bm-cli <command> [<args>]

The most commonly used bm-cli commands are:
    calendar      calendar task(s)
    contact       contact task(s)
    help          Display help information
    maintenance   maintenance task(s)
    tick          tick task(s)
    user          user task(s)

See 'bm-cli help <command>' for more information on a specific command.

In this installation – version 3.5.11 – you have calendar, contact and user commands which didn't exist in previous versions.

BlueMind supports the --help option – you can now get help by adding this option after a command:

~# 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
  hsm-to-cyrus         Converts HSM snappy spool to a cyrus maildir folder
  list                 List directory entries
  repair               Run repair maintenance operation
  ops                  List available maintenance operations
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.

Practical examples​

Administration & Maintenance​

Performing a domain-wide 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​

For multiple reasons – technical or practical, e.g. in case it is lost – you may need to change the admin0 user password without logging into 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, you can use it to perform administration tasks. E.g. you can roll out its configuration on all domain servers again using the following command:

# bm-cli tick reconfigure
tip

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

# bm-cli tick reconfigure --dry
Updating BlueMind​

If your subscription includes it, BlueMind can be updated in command line, without running the browser-based wizard:

aptitude update
aptitude upgrade && bm-cli setup upgrade

Managing users​

Deleting archived (suspended) domain users​

Commands can be coupled to perform several operations at once. 

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

bm-cli user get domain.net --archived --display "email"

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

bm-cli user get local.lan --display "email" | jq -r '.[].email' > /tmp/archived.txt
while read account; do bm-cli user delete --dry $account ;done < /tmp/archived.txt
Transferring accounts from one backend to another​
root@xfer-core:~# bm-cli maintenance xfer --help

Usage: bm-cli maintenance xfer [--dry] [--match=<match>]

                               [--source-backend=<sourceBackendId>]

                               --target-backend=<targetBackendId>

                               [--workers=<workers>] <target>

xfer users from one backend to another backend

      <target>              email address, domain name or 'all' for all domains

      --dry                 don't write antyhing, just print the todolist

      --match=<match>       regex that entity must match, for example : [a-c].\*

      --source-backend=<sourceBackendId>

                            xfer all matching users from specified backend only

                              (server uid, ip or name)

      --target-backend=<targetBackendId>

                            xfer all matching users to specified backend

                              (server uid, ip or name)

      --workers=<workers>   run with X workers

Operations on calendars​

Sharing all user calendars with one user​

It may be useful for one user to have permission to access all user calendars without being given an administrator role (e.g. a secretary might be able to view/create events for all other employees). To avoid having to go through each user's page to enable sharing, this can be done in command line.

This cannot be done with a single command, but you can create a loop which picks up all domain users and enables sharing for each of them:

bm-cli users get domain.net > /tmp/allUser.domain.net
while read account; do bm-cli calendar share $account « default » toto@domain.net r;done < /tmp/allUser.domain.net

Operations on contacts​

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

Maintenance​

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

bm-cli maintenance repair user@domain.net           #repairs user user@domain.net
bm-cli maintenance repair domain.net --numworkers 4 #repairs all domain users using 4 threads
bm-cli maintenance consolidateIndex user@domain.net #consolidates the index for user@domain.net
bm-cli maintenance consolidateIndex domain.net --from 0 --size 100 #processes the first 100 users returned
bm-cli maintenance consolidateIndex domain.net --from 101 --size 50 #processes the following 50 users
bm-cli maintenance consolidateIndex domain.net --match '[a-c].\*' # processes entities that start with a, b or c

Installation and update​

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

Commands​

An additional setup command is available as soon as you install the plugin:

bm-cli help setup   #get help on available arguments and how to use them
bm-cli setup install --external-url bluemind.domain.net --domain domain.net --sw-pass Passw0rd
bm-cli setup install --external-url bluemind.domain.net --domain domain.net --sw-pass Passw0rd --set-contact admin@domain.net --reinstall
bm-cli setup upgrade #lance la procédure de mise à jour post-installation en lieu et place du déroulement de l'url https://<domain.net>/setup via un navigateur
  • --external-url: BlueMind's external URL
  • --domain: domain
  • --set-contact: sets the default email address for subscription expiration notifications
  • --sw-pass: sets the admin password for the setupwizard

Update procedure​

To update your installation in command line using the bm-cli tool, the procedure is the same as for a standard update:

  1. Preparing for the update: The bm-cli setup command is used to set up the version you want to update.

    • type the following command to update to the lastest available version:
    bm-cli setup version latest
    • to update to a specific version, pass the version number as a parameter:
    bm-cli setup version 3.5.14-2

    Note: Using a major version number (e.g. "3.5" or "4") will have the same effect as using "latest": the latest minor version for that number will be installed

    • to block a version and prevent updates to above versions:
    bm-cli setup version current

  2. Updating packages:

    info

    If you want to minimize service downtime, you can pass the update command with the "download-only" option which first downloads the packages.

    As this doesn't interrupt or slow down services, this action can be performed at any time of day or night.

    You can then launch the "upgrade" command - which effectively updates the packages and whose impact on downtime is reduced - at a more appropriate time.

Operations possible on production server
aptitude update
aptitude --download-only upgrade
Puts the service in maintenance
aptitude update
  1. Launching the update procedure:
bm-cli setup 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 importing the files
# bm-cli help certificate

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>

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="domain"

  • --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="domain"

  • --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="domain"

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