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 BlueMind installation and update
Usage
Run a command
To use the command-line tool, connect to the server via ssh and use the command bm-cli followed by the command and its options.
For example, to list the users of the domain:
bm-cli user get bluemind.loc
Controls can be coupled with each other or with other standard controls. They can also be included in scripts to perform several operations at once.
List existing orders
The bm-cli -h command lists all available commands:
bm-cli -h
auditlog
auditlog create create audit log datastream
auditlog acl get access control entries
auditlog get get auditlog data
auditlog calendar get calendar data
auditlog dir get directory data
auditlog global get global auditlog data
auditlog login get login data
auditlog mail get mail data
auditlog mailfilter get mail filter rule data
auditlog get-retention Get retention duration (days) for datastream
auditlog sysconf get system configuration and global setting data
auditlog set-retention set retention duration (days) for datastream
auth
auth reconfigure Delete & recreate keycloak realms for existing domains
auth get-conf Get domain authentication configurations
auth set-conf Set domain authentication configuration
auth-provider
auth-provider openid-list-provider List registered OpenId provider systems
auth-provider openid-register-provider Register an OpenID provider system
calendar
calendar log Pretty-Print an auditlog file
calendar delete-events-by-organizer Delete all events having a specific organizer
calendar export Export a calendar to an ICS file
calendar import import an ICS File
calendar list List user or whole domain calendars
calendar list-event-details-by-organizer List event details
calendar reset Reset a calendar
calendar resync Resync an event
calendar touch Increment the version of a calendar event
...
Commands are improved with every version of BlueMind. Depending on the version of BlueMind installed, more (or fewer) commands and options may be available.
It is therefore important to refer to the bm-cli -h command on the server.
The additional v parameter adds the complete help for each command to the listing:
bm-cli -hv
auditlog -h, --help
Affiche l'arbre complet des commandes.
-v, --verbose
Affiche aussi les arguments pour chaque commande de l'arbre.
[...]
calendar -h, --help
Affiche l'arbre complet des commandes.
-v, --verbose
Affiche aussi les arguments pour chaque commande de l'arbre.
calendar log Pretty-Print an auditlog file
--dataShow data
--show-ro
Show read-only data
--data-by-date
Show data only on a specific date (yyyy-MM-ddThh:mm:ss).
Matching also works with substrings of this pattern
--event-query
Event query string (Columns Action and Event)
--event-uid
Event UID query string
--calendar-query
Calendar query string (Column Calendar)
--filtered-actions
Comma-separated list of actions which should not appear
in the output
<file>Path to the auditlog file
calendar delete-events-by-organizer Delete all events having a specific organizer
--domain
domain
--dry
list events without deleting them
<email>
Organizer email
calendar export Export a calendar to an ICS file
--direntry-uid
Directory entry UID
--all-domains
All domains except global.virt
--workers
run with X workers (default: 1)
--match
regex that entity must match, for example : [a-c].*
--progress
display progress messages
--output-directory
The output directory path, files will be save in an email
named subdirectory
--dry Dry-run (do nothing)
--calendarUid
calendar uid, export all calendars if not specified
<target>
email address or domain name
[...]
setup -h, --help
Affiche l'arbre complet des commandes.
-v, --verbose
Affiche aussi les arguments pour chaque commande de l'arbre.
setup enable-mailapp Activate MailApp
--direntry-uid
Directory entry UID
--all-domains
All domains except global.virt
--workers
run with X workers (default: 1)
--match
regex that entity must match, for example : [a-c].*
--progress
display progress messages
--group
Adds the necessary role to this group (defaults to 'user')
<target>
email address or domain name
setup check-subscription Check subscription
setup install Install BlueMind
--domain
Set the default domain name.
--external-url
Set the External Url. Ex: bluemind.domain.tld
--sw-pass
Set setup wizard password.
--domain-admin-pass
Set domain administrator password.
--admin0-pass
Set admin0 password.
--reinstall
Force installation even if installed.
--set-contact
Set a subscription contact
--shard-ip
Provided shard server IP (deprecated, please use the
servers-map feature)
--server-map
Assign tags on the selected servers, can be
specified multiple times.
(List of tags in TagDescriptor from net.bluemind.server.
api)
Exemple:
* elasticsearch on 192.168.1.2
* storage servers on 192.168.1.3, 192.168.1.4
--server-map 192.168.1.2=bm/es \
--server-map 192.168.1.3=bm/pgsql-data,mail/imap \
--server-map 192.168.1.4=bm/pgsql-data,mail/imap
--lang Set admin0 language. (default 'fr')
setup upgrade_history Shows the Bluemind upgrade history
setup upgrade Upgrade BlueMind
-f, --force
force update, even if core reports the correct version
--backup
Backup Bluemind databases (pg-dump), may be very long.
--lang
Set admin0 language (en, fr...).
Help with an command
At any time, you can get help on a particular command by using --help or -h.
For example, maintenance -h presents the maintenance command and its various possible actions:
bm-cli maintenance -h
consolidateIndex Consolidate a mailbox index
dump-cache Dump core caches to a json file
flush-cache Flush bm-core caches
list List directory entries
orphan-body-repair delete orphan mail bodies
orphan-check check and delete orphan mailbox records
read-cyrus-index Read a cyrus index file
repair Run repair maintenance operation
ops List available maintenance operations
schema check database schema
sentry sentry setup
update-fw Update firewall rules
To find out more about a sub-command, simply type the sub-command in turn, here for help with the index consolidation operation:
bm-cli maintenance consolidateIndex -h
Usage: bm-cli maintenance consolidateIndex [--progress] [--reset]
[--match=<match>] [--workers=<workers>] (<target> |
--direntry-uid=<dirEntryUid> | --all-domains)
Consolidate a mailbox index
<target> email address or domain name
--all-domains All domains except global.virt
--direntry-uid=<dirEntryUid>
Directory entry UID
--match=<match> regex that entity must match, for example : [a-c].*
--progress display progress messages
--reset Reset the index (only the data belonging to the
target)
--workers=<workers> run with X workers (default: 1)
Entity management
Get the UID of an entity
The various commands for entities (user, contact, calendar)
Find a user's UID
To obtain a user's UID, use the bm-cli user get command, specifying the default mail address as the search character, or use grep to filter on another field:
bm-cli user get bluemind.loc --match=jdoe@bluemind.loc --display uid
{"uid":"9236AE27-9C2D-4BA7-84D3-C2067D515195"}
bm-cli user get bluemind.loc --display "uid familyNames"|grep "Doe"
{"uid":"9236AE27-9C2D-4BA7-84D3-C2067D515195","familyNames":"Doe"}
Find a group UID
To obtain a group's UID, use the bm-cli group get command, specifying the group name and the search domain:
bm-cli group get Direction@bluemind.loc
{"value":{"orgUnitUid":null,"emails":[{"address":"direction@bluemind.loc","allAliases":true,"isDefault":true}],"hidden":false,"archived":false,"system":false,"dataLocation":"bm-master","name":"Direction","description":null,"properties":{},"hiddenMembers":false,"mailArchived":true,"memberCount":2},"uid":"A48CF63E-C39F-46A9-9F85-3DF1459E8BDC","internalId":24,"version":53,"displayName":"Direction","externalId":null,"createdBy":"admin0_global.virt","updatedBy":"system","created":1758880480523,"updated":1758880493135,"flags":[]}
*NB: unlike the command for users, it is not possible here to filter the output to obtain only the UID.
Find the UID of an address book
The UID of an address book can be found using the bm-cli contact list command, which lists all the address books of a user, a domain or all domains.
For a user's address book, you can retrieve the complete list of address books and filter it using other commands (e.g. grep):
bm-cli contact list jdoe@bluemind.loc
For an address book, the --match parameter makes it easy to filter by name:
bm-cli contact list --match=Clients --all-domains
{"owner":"FDF64CCE-E957-423E-BB93-25990B2B13C9","uid":"FDF64CCE-E957-423E-BB93-25990B2B13C9","name":"Clients"}
Find a calendar UID
The UID of a calendar can be found using the bm-cli calendar list command, which lists all the calendars of a user, a domain or all domains.
For a user's calendar, you can retrieve the complete list of calendars and filter them using other commands (e.g. grep):
bm-cli calendar list jdoe@bluemind.loc
{"owner":"9236AE27-9C2D-4BA7-84D3-C2067D515195","uid":"calendar:Default:9236AE27-9C2D-4BA7-84D3-C2067D515195","name":"John Doe"}
For a domain calendar, the --match parameter makes it easy to filter on the name:
bm-cli calendar list --all-domains --match=Evenementiel
{"owner":"B835E391-FB8E-4879-A763-883C5489C0CA","uid":"B835E391-FB8E-4879-A763-883C5489C0CA","name":"Evenementiel"}
Find the UID of any entity
The maintenance list command is used to list all the entities in a domain or installation, whatever their type. This makes it possible to find information, including the UID, without knowing its type or if its type has no command of its own:
# rechercher l'UID d'une entité de l'installation, sans connaître son type ou son domaine, grâce à grep
bm-cli maintenance list --all-domains | grep contact
{"displayName":"contact","entryUid":"8D2FCA19-798A-4ACE-A88F-9E5693172FD9","accountType":null,"kind":"MAILSHARE","path":"7bbaaa6d.internal/mailshares/8D2FCA19-798A-4ACE-A88F-9E5693172FD9","email":"contact@bluemind.loc","hidden":false,"system":false,"archived":false,"emails":null,"orgUnitUid":null,"orgUnitPath":null,"dataLocation":"bm-master","minId":13}
# rechercher l'UID de la boîte partagée "contact" du domaine bluemind.loc
bm-cli maintenance list contact@bluemind.loc
{"displayName":"contact","entryUid":"8D2FCA19-798A-4ACE-A88F-9E5693172FD9","accountType":null,"kind":"MAILSHARE","path":"7bbaaa6d.internal/mailshares/8D2FCA19-798A-4ACE-A88F-9E5693172FD9","email":"contact@bluemind.loc","hidden":false,"system":false,"archived":false,"emails":null,"orgUnitUid":null,"orgUnitPath":null,"dataLocation":"bm-master","minId":13}
Note: the UID is returned in the entryUid field.
Managing users
Subscribe all users to an address book or calendar
use case: we want all users to subscribe to a domain address book. To avoid errors and simplify the procedure, an administrator can easily do this via the CLI.
First, you need to retrieve the UID of the desired address book or calendar (see above).
Then simply use the user subscribe command with the --users-all parameter to subscribe all users to the desired entity:
# abonnement des utilisateurs au carnet "Clients"
bm-cli user subscribe --subscribe-to "FDF64CCE-E957-423E-BB93-25990B2B13C9" --users-all --domain "bluemind.loc"
1/3:SUCCESS:user UID 9236AE27-9C2D-4BA7-84D3-C2067D515195 subscribed
2/3:SUCCESS:user UID D44D1825-E4DF-44FB-99CD-3E8AF564AED1 subscribed
3/3:SUCCESS:user UID 678D2A6D-D573-41A2-B73D-C32DEA1C4BC1 subscribed
---
Subscribe to 'FDF64CCE-E957-423E-BB93-25990B2B13C9' ending
0 subscriber(s) not found
0/3 subscription(s) in error
3/3 subscription(s) success
# abonnement des utilisateurs au calendrier "Evenementiel"
bm-cli user subscribe --subscribe-to "B835E391-FB8E-4879-A763-883C5489C0CA" --users-all --domain "bluemind.loc"
1/3:SUCCESS:user UID 9236AE27-9C2D-4BA7-84D3-C2067D515195 subscribed
2/3:SUCCESS:user UID D44D1825-E4DF-44FB-99CD-3E8AF564AED1 subscribed
3/3:SUCCESS:user UID 678D2A6D-D573-41A2-B73D-C32DEA1C4BC1 subscribed
---
Subscribe to 'B835E391-FB8E-4879-A763-883C5489C0CA' ending
0 subscriber(s) not found
0/3 subscription(s) in error
3/3 subscription(s) success
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 couple the return with a loop and a delete command in order 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:
-
Retrieve the list of users with their quotas:
bm-cli user get bluemind.loc --display 'email quota' -
Filtering this same command for users with a
nullquota:bm-cli user get bluemind.loc --display 'email quota' | grep null -
The
jqtool then extracts the email from each returned line:jq -r '.email' -
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.
-
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 -
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
Import contacts from one address book to another
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
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"
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
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"
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
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"
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
Administration & Maintenance
Status of the BlueMind instance
The following command detects errors on the core nodes of a BlueMind instance:
bm-cli node statusbm-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.
In multi-node installations, this command should only be executed on a core node, to avoid unnecessary errors or warnings.
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
Change 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
The --dry option is used to test the command: the operation is just 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 analysisActivating 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.
Install and upgrade BlueMind
The subscription giving access to automated BlueMind updates also provides access to additional operations of the bm-cli client for them.
To have access to these commands, you must install this plugin:
- Debian/Ubuntu
- Redhat/CentOS
apt install bm-plugin-cli-setup
yum install bm-plugin-cli-setup
The setup command is then available as soon as the add-on is installed, without rebooting.
Installation
To install BlueMind, use the install subcommand:
# 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
ℹ️ Parameters used here:
--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
The --server-map parameter lets you assign servers and install an entire instance in a single command.
For example:
--server-map 192.168.1.2=bm/es --server-map 192.168.1.3=bm/pgsql-data,mail/imap --server-map 192.168.1.4=bm/nginx-edge,mail/smtp-edge
For more detailed information on the available parameters, see the inline help for:
bm-cli setup install -h
Update
For information on upgrading BlueMind from the command line, 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 isglobal.virtif 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 defaultglobal.virtis 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 defaultglobal.virtis used if no domain is specified