Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from space DA and version BM-3.5

...

Sv translation
languageen

Introduction

With BlueMind 3.5.10 you can install a CLI (Command Line Interface) which can be 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.

This page provides installation and use information, including practical examples. A dedicated sub-page provides more details on bm-cli command references.

Panel
borderWidth3

On this page:

Table of Contents
maxLevel2

Related:

Reference des commandes bm-cli

Installation

Note
titleVersions earlier than 3.5.14

If you haven't updated BlueMind to the latest published version, there may be a conflict between the packages installed because bm-cli will install its latest available version.

To avoid this, you can:

  • either update your BlueMind installation beforehand (recommended solution)
  • or force the version number in the subscription before installing bm-cli in the same version as your BlueMind.
    To do this, edit the file /etc/apt/sources.list.d/bm.list and remplace "3.5" by the version number you want to use in the url:

Code Block
#deb https://SUBSCRIPTION_USER:PASSWORD@pkg.bluemind.net/3.5/xenial/pkgs /
deb https://SUBSCRIPTION_USER:PASSWORD@pkg.bluemind.net/3.5.12-4/xenial/pkgs

Note: we recommend that you copy the command line – as above – and comment the first version by adding # at the beginning of the line. This will make going back easier.
when you do this, the version for your entire BlueMind installation is frozen. Once the packages are installed, remember to change the version number back to the generic number so that you can update BlueMind in due course.

The bm-cli client is installed through a dedicated package on the server – available from BlueMind 3.5.10:

Tabs group
borderall-sides
navcolornavy
Debian/UbuntuRedhat/CentOS
Info

No restart is required, the commands are effective immediately.

Using the client

Commands

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

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

Code Block
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

Note

Commands are improved with every version of BlueMind. You may have more or fewer commands depending on the version you have installed.

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

E.g.:

Code Block
# 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.

This installation – version 3.5.11 – includes calendar, contacts and user commands which did not exist in earlier versions.

You can get help on a command, sub-command, how to use it and its options using "help" at any time.

E.g. "help maintenance" shows the maintenance command and the actions it can perform:

Code Block
# 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 about a sub-command, type it to get help, e.g. about index consolidation:

Code Block
# 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
...

Practical examples

Administration and Maintenance

Performing a domain-wide check&repair

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

Code Block
bm-cli maintenance repair domain.net --numworkers 4

Changing the admin0 password

For multiple reasons – technical or practical, e.g. in case of loss -- you may need to change the admin0 user's password without logging into BlueMind.

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

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

Updating Tick configuration

When the Bm-Tick monitoring tool is installed, you can use it to perform administration tasks. E.g. you can roll out the configuration on all domain servers again using the following command:

Code Block
# bm-cli tick reconfigure
Tip

--dry is added to test the command: the operation is merely simulated

Code Block
# bm-cli tick reconfigure --dry

Operations on users

Deleting archived (suspended) domain users

Info
titleversion info

The "bm-cli user" command will be available from BlueMind 3.5.11.

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:

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

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

Code Block
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

Operations on calendars

Sharing all user calendars with one user

It may be useful for one user to have access privileges on 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:

Code Block
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):

Code Block
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

L'outil The bm-cli permet d'effectuer des opérations de maintenance sur les utilisateurs, comme par exemple tool is used to perform maintenance operations on users, e.g.:

Code Block
bm-cli maintenance repair user@domain.net			#repairs the 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 the user 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 next 50 users 
bm-cli maintenance consolidateIndex domain.net --match '[a-c].*' #processes the entities that startbegin fromwith a, b or c

Installation and upgrade

The subscription includes automatic BlueMind updates, as well as the related additional bm-cli client operations.

Warning

Ces opérations étant sensibles et risquées, ce sont des commandes à réserver à une utilisation par des administrateurs avancés.

To do this

These operations are sensitive and risky. Related commands should therefore be used by advanced administrators only.

To access these commands, you need to install the CLI plugin:

Code Block
apt install bm-plugin-cli-setup
Commandes

Commands

The additional "setup" command is then available:

Code Block
bm-cli help setup	#for 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#starts la procédure de mise à jour postthe post-installation enupdate lieuprocedure etinstead placeunrolling du déroulement de l'the browser-based url https://<domain.net>/setup via un navigateur
  • --external-url: BlueMind's external url 
  • --domain
  • --set-contact: sets the default email address for subscription expiry notifications
  • --sw-pass: sets the admin password for the setupwizard

Procédure de mise à jour

Pour réaliser une mise à jour de l'installation en ligne de commande au moyen de l'outil

Update procedure

To update the installation in command line using the bm-cli , la procédure suit le même déroulement que pour une mise à jour classique tool, the procedure is the same as for a standard update procedure:

  1. Preparing for the update:
    NB : cette commande est disponible à partir de la Note: this command is available from version 3.5.14
    La commande The "bm-cli setup" permet de paramétrer la version vers laquelle on souhaite mettre à jourcommand is used to set the version you want to update.
    • type the following command to update to the latest available version:

      Code Block
      bm-cli setup version latest
    • to update to a specific version, pass the version number as a parameter:

      Code Block
      bm-cli setup version 3.5.14-2

      Note: using a major version number (e.g. "3.5" or "4") will have the same result as the "latest" option: the latest minor available version will be installed

    • to freeze a version and prevent updates to above versions:

      Code Block
      bm-cli setup version current
  2. Update the packages:

    Note

    If you want to minimize service downtime, you can pass the update command with the "download-only" option, which enables you to download all the packages ahead of the update.

    This does not interrupt or slow down services, which means it can be done at any time of day or night.

    You can then run the "upgrade" command at a more convenient time and therefore reduce service downtime.

    Tabs group
    borderall-sides
    navcolornavy
    Debian/UbuntuRedhat/CentOS
  3. Lancer la procédure de mise à jour Launch the update procedure:

    Code Block
    bm-cli setup upgrade