Client CLI pour l'administration

Le client CLI (« Command Line Interface » = Interface de lignes de commandes) permet d'effectuer des tâches d'administration de la plateforme BlueMind en ligne de commande, sans avoir à créer de scripts pour cela.

Couplé au système de monitoring bm-tick, il permet notamment des tâches d'administration de celui-ci. Pour plus d'informations, voir Découvrir et installer bm-tick.

Installation

Le client bm-cli est installé par défaut lors de l'installation de BlueMind.

Des composants additionnels peuvent être installés pour étendre les capacités de l'outil :

• bm-plugin-cli-mapi : ajoute des commandes de gestion de MAPI pour Outlook
  NB : ce paquet est installé automatiquement lors de l'installation des paquets mapi.
• bm-plugin-cli-setup : ajoute des commandes pour l'installation et la mise à jour de BlueMind

Obtenir de l'aide

À tout moment, vous pouvez obtenir de l'aide sur une commande ou une sous-commande, sur son usage et ses options au moyen de --help ou -h.

Par exemple, maintenance -h vous présente la commande maintenance et ses diverses actions possibles :

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.

Pour obtenir plus de détails sur une sous-commande, il vous suffit de taper la sous-commande à son tour, ici pour obtenir l'aide concernant l'opération de consolidation d'index :

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

Les commandes sont enrichies au fur et à mesure des versions de BlueMind. Il se peut donc que vous ayez plus (ou moins) de commandes et options selon la version de votre installation.

Il est donc important de se référer à la commande bm-cli --help afin de savoir quelles sont celles que vous pouvez utiliser.

Exemples pratiques

astuce

Les commandes peuvent être couplées, entre elles ou avec d'autres commandes habituelles, et incluses dans des scripts afin d'effectuer plusieurs opérations en une seule fois.

État de l'instance BlueMind

La commande suivante permet de détecter les erreurs sur les nœuds core d'une instance BlueMind :

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.

installation multi-nœuds

En cas d'installation multi-nœuds, cette commande ne doit être exécutée que sur un nœud core afin d'éviter l'apparition d'erreurs ou avertissements inutiles.

Gestion des utilisateurs

Supprimer les utilisateurs archivés (suspendus) du domaine

La commande ci-dessous recherche les adresses de messagerie des utilisateurs suspendus :

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

Il est alors possible de coupler le retour de cette commande avec une boucle et une commande delete afin de supprimer les utilisateurs retournés :

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

Appliquer un quota à tous les utilisateurs qui n'en ont pas

Cette opération se fait à l'aide de plusieurs commandes bm-cli et jq qui sont regroupées en une seule :

1. Récupérer la liste des utilisateurs avec leur quota :

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

2. Filtrer cette même commande sur les utilisateurs ayant un quota null :

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

3. L'outil jq permet ensuite d'extraire l'email de chaque ligne retournée :

   jq -r '.email'

4. Enfin, la commande de mise à jour du quota (ici un quota de 80 Mo) :

   bm-cli user update --quota "81920" username@bluemind.loc

Ainsi, la commande finale pour réaliser cela en une seule ligne :

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

Opérations sur les calendriers

Exporter/importer l'ensemble des calendriers d'un utilisateur

Cas d'usage : Dans le cadre d'un départ, en vue de pouvoir les réimporter chez d'autres utilisateurs, on veut exporter l'ensemble des calendriers d'un utilisateur.

1. Exporter l'ensemble des calendriers de l'utilisateur John Doe (identifiant jdoe@bluemind.loc) dans le dossier /home/user/export/cals :

   bm-cli calendar export --output-directory /home/user/export/cals jdoe@bluemind.loc

2. Importer le calendrier souhaité chez un autre utilisateur :

   bm-cli calendar import --calendarUid calendar:Default:A1B2C3D4E5F6Z --ics-file-path /home/user/export/cals/jdoe_default.ics hannibal@bluemind.loc

   💡 Pour importer l'ensemble des calendriers (exportés comme ci-dessus, ou provenant d'une autre source) on peut inclure cette commande dans une boucle parcourant le dossier d'export et les calendriers de l'utilisateur cible.

Exporter les calendriers de tous les utilisateurs

Cas d'usage : Dans une optique de migration ou de sauvegarde, on souhaite exporter et sauvegarder tous les calendriers de tous les utilisateurs au format ICS.

Pour cela, on réalise une boucle parcourant l'ensemble des utilisateurs et réalisant un export tel que ci-dessus :

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

Cette boucle exporte l'ensemble des calendriers en créant un dossier par utilisateur :

/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

Opérations sur les contacts

Cas d'usage : un utilisateur souhaite récupérer ses contacts collectés dans son carnet d'adresses personnel.

Pour cela, on va dans un premier temps éliminer les éventuels doublons du carnet des collectés de l'utilisateur, puis on transfèrera les contacts vers son carnet personnel (en testant au préalable l'import) :

# 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

Activation des logs EAS

bm-cli permet également d'activer ou désactiver les logs EAS afin de faciliter la gestion des problèmes de connexion ou de synchronisation sur mobile. Consulter la page Problèmes de synchronisation mobile pour voir les commandes.

Administration & Maintenance

Effectuer un check&repair global

La commande suivante permet d'effectuer l'opération "valider et réparer" sur l'ensemble des utilisateurs du domaine bluemind.loc en utilisant 4 threads :

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

Modifier le mot de passe admin0

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.

La commande suivante permet de le faire sans connaître l'ancien mot de passe :

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

Mettre à jour la configuration tick

Lorsque l'outil de monitoring Bm-Tick est installé (voir Découvrir et installer bm-tick), il est possible d'effectuer des tâches d'administration sur celui-ci. Par exemple, vous pouvez redéployer la configuration sur l'ensemble des serveurs du domaine avec la commande suivante :

bm-cli tick reconfigure

astuce

L'option --dry permet de tester la commande : l'opération est juste simulée

bm-cli tick reconfigure --dry

Maintenance des utilisateurs et index

L'outil bm-cli permet d'effectuer diverses opérations de maintenance sur les utilisateurs, par exemple :

# 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].\*'

Analyse des logs

L'outil Auditlog permet de connaitre les actions et modifications réalisées sur les entités BlueMind.

Pour plus d'informations, voir Logs - Configuration et analyse

Installation et mise à jour

La souscription donnant accès aux mises à jour automatisées de BlueMind, elle donne aussi accès à des opérations supplémentaires du client bm-cli pour celles-ci.

info

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

Pour disposer de ces commandes, il est nécessaire d'installer le plugin dédié :

Debian/Ubuntu

apt install bm-plugin-cli-setup

Redhat/CentOS

yum install bm-plugin-cli-setup

La commande supplémentaire setup est disponible dès l'installation du plugin :

# 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 : url externe du BlueMind
• --domain : domaine
• --set-contact : permet de positionner l'adresse de messagerie par défaut pour les notifications de l'expiration de la souscription
• --sw-pass : permet de positionner le mot de passe de l'admin pour le setupwizard

lignes de commande

Pour connaître les lignes de commandes, consulter la page dédiée Mise à jour de BlueMind.

Gestion des certificats SSL

L'ajout et le renouvellement des certificats SSL, pour un domaine donné ou pour le système global, peut se faire de deux façons :

• en les générant via Let's Encrypt
• en important directement les fichiers

Commandes utiles

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>

Utilisation de Let's Encrypt

Il est possible d'utiliser Let's Encrypt pour générer le certificat pour un domaine donné ou pour le système global.

Activation

Afin de lancer une première génération de certificat avec Let's Encrypt, il faut jouer la commande suivante :

bm-cli certificate manage-lets-encrypt --contact=no-reply@"default-domain" --domain="bluemind.loc"

• --contact : permet d'ajouter une adresse email qui permettra d'être informé lorsque l'expiration du certificat approchera.
  Si aucune adresse n'est renseignée l'adresse no-reply@"default-domain" sera utilisée (Pré-requis: le default domain devra être renseigné au préalable).
• --domain : par défaut global.virt si aucun domaine n'est spécifié

Renouvellement

Si le domaine possède déjà un certificat généré par Let's Encrypt, celui-ci pourra être mis à jour en jouant la commande suivante :

bm-cli certificate manage-lets-encrypt --contact=no-reply@"default-domain" --domain="bluemind.loc"

• --contact : permet de modifier l'adresse email, si besoin, sinon l'adresse précédemment renseignée sera conservée.
• --domain : par défaut global.virt si aucun domaine n'est spécifié

Import manuel

Il est possible d'importer manuellement un certificat SSL en ajoutant les trois fichiers obligatoires, grâce à la commande suivante :

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

• --domain : par défaut global.virt si aucun domaine n'est spécifié