Administration¶
This chapter includes details on how to administrate components of grommunio with the available toolset.
grommunio admin UI (AUI)¶
After successfully installing the grommunio Appliance, you can access the UI through your browser on port 8080 (8443 with https soon).
Since you most likely set a password for admin UI while installing the Appliance, you can immediately use these credentials to login.
To navigate through the UI, simply use the drawer on the left side of the page.
Dashboard¶
After a successfull login, you can see the dashboard with live data of the machine grommunio runs on.
Antispam¶
Since grommunio has its own antispam service, according data can be displayed in the Dashboard.
Services¶
Antispam isn’t the only grommunio service, in fact there are lots more. The current state of these services can be seen on the left side of the dashboard.
You can stop, restart or start these services from here by clicking the action buttons of a service in the list.
Domains¶
Click on Domain list in the drawer, which will redirect you to the list view of existing domains. If you just set up grommunio, the table will be empty. If you want to show currently deactivated domains check the checkbox show deactivated.
Adding a domain¶
To add a new domain, click the blue NEW DOMAIN button to open the form dialog:
The following properties can be set:
- Domain (required): The name of the domain (cannot be changed afterwards)
- Status: Whether domain should be currently activated or deactivated
- Organization: Organization of the domain
- Maximum users (required): The maximum amount of users (e-mails) of this domain
- Title: Title of the domain
- Address: Address of the domain
- Administrator: Administrator of the domain
- Telephone: Hotline for problems
- Create domain admin role: Creates a role for users, who will be admins for this domain
- Create grommunio-chat team: Creates a new grommunio-chat team for this domain. If you want users of this domain to be able to log into grommunio-chat, this has to be checked.
Click Add to confirm or Cancel to cancel.
Editing a domain¶
To edit an existing domain, click on a domain in the list to open the detailed view of a domain.
Simply change attributes to your needs, then click Save on the bottom to save your changes.
To change the current password of the domain, click Change password next to the domain name. You will be prompted to set and repeat your new password.
Deleting a domain¶
To delete a domain, click on the trash icon of a domain in the domain list view.
The following flags can be set:
- Delete permanently: Checking this, will completely remove the domain out of the database, not just deactivate it
- Delete files: Only available if permanently deleting, will delete all files of this domain
Click Confirm to confirm or Cancel to cancel
Reactivating domains¶
If you didn’t delete a domain permanently, it will automatically be set to deactivated. To reactivate a domain, click on a domain in the list to get to the detailed view. Now change the status from deactivated to activated.
Users¶
If at least one domain exists in the database, users can be added to a domain. To show existing users of a domain, navigate to the domain view in the drawer (Domains tab).
Click on a domain to expand available sub-pages and click on Users, which will redirect you to the list of users of this domain. If you just installed grommunio or added the domain, the list will be empty.
Alternatively, to see all users across all domains, click on Global users in the drawer.
Adding a user¶
To add a new user, click the blue NEW USER button to open the form dialog:
The following properties can be set:
- Username (required): Username of the user
- Password (required): Password of the user
- Display name: Name to be displayed for this user
- Storage quota limit: Storage limit of the user
- Type: Type of user
Click Add to confirm or Cancel to cancel. If you need to further specify user properties, click Add and Edit to open the detailed view of this user.
Editing a user¶
To edit an existing user, click on a user in the list to open the detailed view of a user.
There are 6 main categories of user properties:
- Account: RPC/HTTP (Outlook Anywhere), MAPI/HTTP, IMAP, POP3 etc. configuration
- User: MAPI props
- Contact: Additional MAPI props
- Roles: Roles of the user
- SMTP: Additional e-mails for this user (aliases)
- Fetchmail: Configuration to fetch mails from other servers via fetchmail
Account¶
The following properties can be edited:
- Mode: Mailbox mode, toggle between a normal user and a shared mailbox
- Type: Type of user
- Language: Language of the user (does not effect the language of the UI)
- Used space
- Send quota limit: Maximum size of the mailbox before sending messages is blocked
- Receive quota limit: Maximum size of the mailbox before message reception is blocked
- Storage quota limit: Maximum size of the mailbox before storing (any kind of) objects is blocked
- Allow SMTP sending: Allows the user to send e-mails via SMTP
- Allow password changes: Allows the user to change his/her password
- Allow POP3/IMAP logins: Allows logins via POP3 or IMAP
- Create grommunio-chat user: Creates a grommunio-chat account for this user. If this checkbox is disabled, there is no grommunio-chat team for this domain.
- grommunio-chat admin permission: Gives administrative permissions for grommunio-chat to this user’s grommunio-chat account.
Note that, because a message first needs to be exist internally before it can be sent, the storage quota limit is also relevant for sending. Conversely, for reception, the storage quota limit must allow storing messages. (It follows that the storage quota should always be more than receive quota, and more than send quota.)
To change the current password of the user, click Change password next to the username. You will be prompted to set and repeat your new password.
User & Contact¶
Common MAPI props. These are self-explanatory.
SMTP¶
User aliases. Edit the textfield to edit an alias, click ADD E-MAIL to add or click the delete icon to delete an alias.
Delegates¶
Delegates of the user, which can send e-mails “on behalf of” the user.
In above example, the user steakie@grammm.com is a delegate for Victor Tesla, so steakie can send e-mails on behalf of Victor.
Permitted users¶
Permitted users are granted full access the user’s mailbox.
In above example, the user steakie@grammm.com has full access to Victor Tesla’s mailbox.
Fetchmail¶
It is possible to fetch e-mails from other mailserver via fetchmail. To configure this feature, you can add several e-mail servers and/or users to fetch mails from.
To add new fetchmail entry, click the circled plus icon, which will open the following input form:
- Source server (required): E-Mail server to fetch from
- Source user (required): E-Mail address to fetch from
- Source password (required): Password to the source users account (Hint: Single or double quotes are not supported)
- Source folder (required): Source folder to sync from
- Source auth: Type of authentication to use
- Protocol (required): Protocol to use
- SSL certifcate path (if Use SSL is checked): Path to local certificate directory or empty to use local default
- SSL fingerprint (if Use SSL is checked): Fingerprint of the server certificate
- Extra options: (if Use SSL is checked): Additional fetchmail options
- Active: Whether fetchmail is currently activated
- Use SSL: Whether to use SSL
- Fetch all: Whether to fetch seen mails
- Keep: Keep original e-mails
- SSL certificate check: Check ssl certificate
To edit these properties, click on a row in the table. To delete an entry, click the trash icon of a table row.
Important
Any changes will only be saved after clicking the click Save on the bottom of the page.
Deleting a user¶
To delete a user, click on the trash icon of a user in the user view.
The following flags can be set:
- Delete files: Will delete all files of this user
Click Confirm to confirm or Cancel to cancel.
Folders¶
If at least one domain exists in the database, folders can be added to a domain. To show existing folders of a domain, navigate to the domain view in the drawer.
Click on a domain to expand available sub-pages and click on Folders, which will redirect you to the list of folders of this domain. If you have just installed grommunio or added the domain, the list will be empty.
Adding a folder¶
To add a new folder, click the blue NEW FOLDER button to open the form dialog:
The following properties can be set:
- Folder name (required): Name of folder
- Container: Type of folder container
- Comment: Comment
- Owners: Owners of this folder (Multi-select of users in the database)
Click Add to confirm or Cancel to cancel.
Editing a folder¶
To edit an existing folder, click on a folder in the list to open the detailed view of a folder.
Simply change attributes to your needs, then click Save on the bottom to save your changes.
To add new owners, click the + next to “Owners”. Enter all users of database to be added as owner of this folder. To remove an owner, click trash icon next to the owner and confirm.
Deleting a folder¶
To delete a folder, click on the trash icon of a folder in the folder view. Click Confirm to confirm or Cancel to cancel.
Groups¶
If at least one domain exists in the database, groups can be added to a domain. To show existing groups of a domain, navigate to the domain view in the drawer.
Click on a domain to expand available sub-pages and click on Groups, which will redirect you to the list of groups of this domain. If you have just installed grommunio or added the domain, the list will be empty.
Groups have a hierarchical structure, but aren’t built like a tree, but like a directional, loop-free graph. Thus, groups can have multiple parent groups and child groups.
To simply show a list of groups click on the List tab. It is also possible to show a more advanced view of groups by clicking on the Tree tab. In order to simplify a potentially massive structure of groups, instead of a graph, different trees can be displayed here. By selecting a root group, a cut-out of the graph can be shown as a tree with the selected group as root node. All recursive children will be displayed.
Adding a group¶
To add a new group, click the blue NEW GROUP button to open the form dialog:
The following properties can be set:
- Groupname (required): Name of the group
- Parent groups: Which groups does this group inherit from?
- Members: Groupmembers
- Filters: See below
Either members of filters can be specified.
Group filters¶
A group can have a clause to filter users with. This could for example be username == exampleUser. In this case, all users that are named “exampleUser” are part of this group. To further specify, a CNF clause on properties can be written.
The UI uses Expansionpanels (EP) to visualize a conjunctive normal form (CNF) clause. Each EP symbolises a logical AND, so each EP must be true, for the entire clause to be true. Each EP also contains multiple textfields. One row of which represents an expression in the CNF (above: username == exampleUser). Each row is combined by a logical OR, so an EP is true, if at least one row (one expression) in the EP is true. That also means, that at least one expression in every EP of the filter must be true for a user to be part of the group.
Editing a group¶
To edit an existing group, you can either:
- Click on a group in the list
- Click on a node in the tree view
Simply change attributes to your needs, then click Save on the bottom to save your changes.
To quickly navigate through a group hierarchy, click a childgroup at the bottom or click a breadcrumb at the top.
Deleting a group¶
To delete a group, click on the trash icon of a group in the list view. Click Confirm to confirm or Cancel to cancel.
Mail lists¶
If at least one domain exists in the database, mail lists can be added to a domain. To show existing mail lists of a domain, navigate to the domain view in the drawer.
Click on a domain to expand available sub-pages and click on Mail lists, which will redirect you to the list of mail lists of this domain. If you have just installed grommunio or added the domain, the list will be empty.
Adding a mail list¶
To add a new mail list, click the blue NEW MAIL LIST button to open the form dialog:
The following properties can be set:
- Mail list name (required): Name of mail list
- Type: Type of mail list
- Privilege: Mail list privilege (not available if type=Domain)
- Recipients: Recipients of e-mails
- Senders: Senders of e-mails (only available if privilege=Specific)
Click Add to confirm or Cancel to cancel.
Editing a mail list¶
To edit an existing mail list, click on a mail list in the list to open the detailed view of a mail list.
Simply change attributes to your needs, then click Save on the bottom to save your changes.
Deleting a mail list¶
To delete a mail list, click on the trash icon of a mail list in the list view. Click Confirm to confirm or Cancel to cancel.
Roles¶
Click on Roles in the drawer, which will redirect you to the list view of existing roles. If you have just set up grommunio, the table will be empty.
By default, every time a domain is added, a new role with rights for the new domain will be added. Additionally, you can create your own roles to specify access rights for multiple domains.
Adding a role¶
To add a new role, click the blue NEW ROLE button to open the form dialog:
The following properties can be set:
- Name (required): Name of the role
- Users: Users to which this role will be assigned to
- Permissions:
- SystemAdmin: Permits any operation
- DomainAdmin: Permits operations on for specific domain
- DomainPurge: If present, grants permission to purge any writable domain
- OrgAdmin: Grants DomainAdmin permission to any domain with matching orgID
- Params: Domain/Organisation to get access to with this role
- Description: Role description
Click Add to confirm or Cancel to cancel.
Editing a role¶
To edit an existing role, click on a role in the list to open the detailed view of a role.
Simply change attributes to your needs, then click Save on the bottom to save your changes.
Deleting a role¶
To delete a role, click on the trash icon of a role in the list view. Click Confirm to confirm or Cancel to cancel.
Organizations¶
Click on Organizations in the drawer, which will redirect you to the list view of existing organizations. If you have just set up grommunio, the table will be empty.
Organizations are used to group domains, and give access to multiple domains in the system by using the OrgAdmin role. Every domain can be associated with at most one organization.
Adding an organization¶
To add a new organization, click the blue NEW ORGANIZATION button to open the form dialog:
The following properties can be set:
- Name (required): Name of the organization
- Description: Detailed description of the organization
Click Add to confirm or Cancel to cancel.
Editing an organization¶
To edit an existing organization, click on an organization in the list to open the detailed view of an organization.
Simply change attributes to your needs, then click Save on the bottom to save your changes.
Deleting an oranization¶
To delete an oranization, click on the trash icon of a role in the list view. Click Confirm to confirm or Cancel to cancel.
Defaults¶
To simplify the creation of domains and especially users, it is possible to set default create parameters. If set, the input masks for adding a domain or user will automatically be filled with these values.
Users with SystemAdmin permissions, can set global defaults by clicking on Defaults in the drawer.
These values can be overwritten for each domain in the domain overviews:
Settings¶
To change global settings, click on the User icon and Settings
Currently you can only change
- Language: Swap between English and German
- Darkmode: Swap between light- and Darkmode
License¶
To see details on your grommunio license, click on the License icon in the Topbar.
To use the full potential of grommunio you can upload your license by clicking Upload and selecting your purchased license. If you do not have a grommunio license yet, but want to upgrade, you can click on Buy now.
The following license properties are display:
- Product: Type of grommunio subscription (Community, Business, etc…)
- Created: Date on which the license was created
- Expires: Last day on which the license needs to be renewed
- Users: Current amount of users on this license
- Max users: Maximum amount of users that can be created with the current license
If you click on the expansion icon next to the users count, you can see what users are occupying user slots of the license.
LDAP¶
It it possible to synchronise users from external user directories using LDAP. To configure LDAP, click on LDAP in the drawer, which will redirect you to the LDAP configuration form.
Important
Please note that configuration changes are not automatically applied to the services already running. Make sure to restart the services to be able to pick up the LDAP authentication first.
After applying a new LDAP configuration, the services are intentionally not automatically restarted as this would result into possibly inconvenient downtime if existing internal users are already used by the authentication manager (authmgr). Services can either be restarted through admin UI in the dashboard section or via systemd directly:
systemctl restart gromox-{http,zcore,pop3,delivery,delivery-queue,midb,imap}
Availability¶
LDAP not available means the LDAP config isn’t set up correctly or the server can’t be reached. If you want to disable LDAP manually, flip the LDAP enabled switch.
Configuration¶
Through this form, you create a ldap.yaml file, which configures an LDAP connection.
Properties are split into the following categories:
- LDAP Server
- Attribute Configuration
- Custom Mapping
To save a configuration, click Save at the bottom or click Delete Config to delete the current configuration.
LDAP Server¶
The following properties are available:
- LDAP Server (server): Address of the LDAP server to connect to
- LDAP Bind User (bindUser): DN of the user to perform initial bind with
- StartTLS: Whether to utilize the StartTLS mechanism to secure the connection
- LDAP Base DN (baseDn): Base DN to use for user search
Authentication manager¶
Primary authentication mechanism
- Always MySQL (default): MySQL authentication
- Always LDAP: LDAP authentication
- Automatic: The choice between LDAP/MySQL occurs dynamically, depending on whether the user was imported from LDAP originally.
Attribute Configuration¶
The following properties are available:
LDAP Templates (templates): Template to prefill any fields below. Available are:
- OpenLDAP
- ActiveDirectory
LDAP Filter (filters): LDAP search filter to apply to user lookup
Unique Identifier Attribute (objectID): Name of an attribute that uniquely idetifies an LDAP object
LDAP Username Attribute (username): Name of the attribute that corresponds to the username (e-mail address)
LDAP Default Quota (defaultQuota): Storage quota of imported users if no mapping exists
LDAP Display Name Attribute (displayName): Name of the attribute that contains the name
LDAP Search Attributes¶
Controls which attributes the “Search in LDAP” functionality will look at when searching using an arbitrary search string.
Custom Mapping¶
LDAP attribute -> PropTag mapping to use for LDAP import. Any mappings specified take precendence over active templates.
You can create a list of (Name, Value) pairs
- Name: Name of the PropTag the attribute maps to
- Value: Value of the PropTag the attribute maps to
User import and synchronisation¶
To import/sync users from all domains, you have to have SystemAdmin permissions. If you do, click on IMPORT USERS or SYNC USERS. This will import/sync all users of all domains.
If you don’t have these permissions, you can import/sync users for your domain. To do that, navigate to the user list(s) of your domain(s).
Importing users will synchronise all already imported users and also import new ones. Synchronising will only do the first.
Domain user import and synchronisation¶
In the users list, you can either import/sync all users of this domain by clicking Import/Sync ldap users. If you want to import specific users, you can do the following:
User import¶
Click on Search in ldap to open a list view of ldap users. Simply enter a username at the searchbar and click the import icon of a user to import.
There is the option to force the import. If checked, an existing user with this usename in the grommunio database will be overwritten.
You can sync these specific users by clicking on them in the list view and clicking the Sync button in the detailed view (only for LDAP users).
Detaching a user¶
If you want to modify an ldap user, you need to detach it from ldap. You can achieve this by clicking Detach in the detailed user view. This essentially removes the synchronisation until forcefully overwritting the user via another import.
Removing orphaned users¶
If a user was removed from the ldap directory, the imported user will be orphaned. To show and/or delete currently orphaned users, click on Check ldap users.
DB Configuration¶
It is possible to create config files in the database to manage services. Every config file manages exactly one file and includes lines of (key, value) pairs.
This creates a hierarchical structure:
- ServiceA
- FileA
- foo=bar
- FileB
- test=example
- test2=example2
- ServiceB
- FileC
- key=value
Editing a file¶
To edit a file, click on the service the file belongs to. This will open a detailed view of the service with a list of its files. Click on a file to open its detailed view and edit the (key, value) pairs to your needs.
Click Save to confirm or Cancel to discard your changes.
Deleting a file¶
To delete a file, click on the service the file belongs to. This will open a detailed view of the service with a list of its files. Click on the trash icon of a file to delete it and confirm.
Configuring grommunio-dbconf¶
grommunio-dbconf is an internal service, that will execute actions/commands when configs change. These actions can be specified for every service separately.
Adding a grommunio-dbconf file¶
Actions to be executed when a config of a service <servicename> changes, need to be set in the file grommunio-dbconf/<servicename>.
There are pre-made commands to set for either key, file or service changes. Those can be found on the Commands tab.
If a command doesn’t exist, the next lower level command will be executed (service -> file -> key).
For example, you could configure postfix changes like this:
This will, among else, restart the service if the service config changes.
Logs¶
Click on Logs in the drawer, which will redirect you to the list of available logs. Usually, you will see a list of grommunio/gromox services, which journalctl logs you can view here.
Click on the uparrow to show previous logs. Click on the the refresh button to fetch new logs or toggle the autorefresh switch to automatically refresh logs of the selected service every 5 seconds. Click on a log line to fetch every log after the timestap of the clicked line.
Mail queue
These lists will update automatically every 10 seconds.
Mobile devices¶
Click on Mobile devices in the drawer, which will redirect you to the list of synchronised mobile devices. This view is a recreation of the grommunio-sync-top CUI.
The view will update the devices every 2 seconds. On the top, you can specify filters for the table, like text-based search or activity of devices.
Sync policies¶
The synchronisation behavior of devices is specified by the sync policies, which are a set of rules. When a user logs into an account, these policies will be applied to the device and updated as soon as the policy is changed. It is not possible to change the policies globally, but per domain (all users of a domain) or per user. To change the policy for all users of a domain, navigate to the list of domains and click on the domain for which you want to change the policy. Under the Sync policy tab, you can see the current rules.
Blue checkboxes, sliders or textfields indicate deviations from the default policy, grey ones match it.
To specify specific rules for a user, navigate to list of users and click on the user for whom you want to change the policy. Just like domain-specific policies, current rules are displayed under the Sync policy tab. Again, blue checkboxes, sliders or textfields indicate deviations from the domain policy of this user, grey ones match it.
Live Status¶
Click on Live Status in the drawer, which will redirect you to the live, realtime view of the grommunio web services. Any HTTP request shows up in live status, including MAPI/HTTP, EAS, EWS and other requests made. All connections other than grommunio Groupware, e.g. Chat and Files are also viewable and can be tracked by the entrypoint URL in the list.
At the top you can select one of the available vhosts and the update interval.
grommunio admin CLI (ACLI)¶
grommunio-admin¶
grommunio-admin is the command line interface tool of the grommunio Admin
API. grommunio-admin is a low level administrative tool for grommunio
configuration and provides a large number of subcommands to administrate
grommunio accordingly.
grommunio-admin also provides bash completion functionality and an interactive shell, with the following subcommands available:
| config | Show or check configuration. See grommunio-admin-config. |
| connect | Connect to remote CLI. See grommunio-admin-connect. |
| dbconf | Database-stored configuration management. See grommunio-admin-dbconf. |
| domain | Domain management. See grommunio-admin-domain. |
| fetchmail | Fetchmail management for retrieval of remote mails. See grommunio-admin-fetchmail. |
| fs | Filesystem operations. See grommunio-admin-fs. |
| ldap | LDAP/Active Directory configuration, diagnostics and synchronization. See grommunio-admin-ldap. |
| mconf | Managed configurations manipulation. See grommunio-admin-mconf. |
| mlist | Mailing/distribution list management. See grommunio-admin-mlist. |
| passwd | Internal user password management. See grommunio-admin-passwd. |
| run | Run the REST API. See grommunio-admin-run. |
| shell | Start interactive shell. See grommunio-admin-shell. |
| taginfo | Print information about MAPI property tags. See grommunio-admin-taginfo. |
| user | User management. See grommunio-admin-user. |
| version | Show version information. See grommunio-admin-version. |
grommunio-admin-config¶
Name¶
grommunio-admin config — grommunio-admin config introspection
Synopsis¶
Commands¶
check¶
dump, get¶
sync.defaultPolicy)trace¶
files), showing which parts of
a file are actually used, or by value (values), showing which file each
value originates from.termcolor package is advised for a more
readable output. See section Tracing for more information.Options¶
KEY- Only view specified key.
-s,--show-history- Display more value history (see section Tracing for more information)
Tracing¶
By-File¶
- +, green: The value is part of the final configuration
- x, red: The value is overwritten by a later file
- *, yellow: The object or list is extended by a later file
- ~, grey: The value is overwritten with the same value
By-Value¶
grommunio-admin-connect¶
Name¶
grommunio-admin connect — Connect to remote CLI
Synopsis¶
grommunio-admin connect [-c COMMAND] [–no-verify] [–redirect-fs [–auto-save (local|remote|discard|print)]] [-v] [HOST [USER [PASSWORD]]]
Description¶
SystemAdminPermission.Note that the remote CLI currently uses a REST interface which does not provide a standard input, rendering commands that rely on user interaction useless.
Options¶
HOST- Host to connect to, in the format protocol://hostname:port, where protocol is either http or https. If omitted, the protocol is auto-detected, with https taking precedence over http. If no port is specified, the default ports 8080 (http) and 8443 (https) are used. hostname can either be a resolvable host name, an IPv4 address or an IPv6 address in brackets. The default hostname is localhost.
PASSWORD- Password to use for authentication. Default is to prompt.
USER- User to use for authentication. Default is admin.
--auto-save ACTIONChoose automatic action for received files when filesystem redirection is enabled. Possible actions are:
discard - discard any received filelocal - save at local pathprint - print file contents to stdout and discardremote - save at path reported from remote server-c,--command- Execute command on remote server and exit instead of starting an interactive shell.
--no-verify- Continue with https even if the TLS certificate presented by the server is invalid. Required if the server uses a self-signed certificate that is not installed on the system. Use with caution.
-p,--password- Prompt for password even when connecting to localhost.
--redirect-fs- Redirect CLI initiated file operations to local filesystem. See section Filesystem Emulation for details.
-v,--verbose- Print more detailed information about the connection process.
Filesystem Emulation¶
When the –redirect-fs option is given, CLI initiated file operations are performed in an emulated filesystem and written files are sent back to the client.
Note that this does only apply to files which are opened by CLI operations, while module-level operations (e.g. loading of configurations) are unaffected.
Files received from the remote server can then be viewed or saved locally.
grommunio-admin-dbconf¶
Name¶
grommunio-admin dbconf — Database-stored configuration management.
Synopsis¶
Description¶
Configurations consist of key/value pairs organized in files, grouped by service. Each service can have an arbitrary number of configuration files, which in turn can contain an arbitrary number of unique keys.
Commands¶
commit- Trigger commit hook for service, file or key
delete- Delete service, file or key
get- Get file or single key
list- List available services, files or keys
set- Set a configuration key
Options¶
SERVICE- Name of the service to configure
FILE- Name of the configuration file
KEY- Name of the configuration key
VALUE- Value to store in the key
--- Indicate that all options have been specified and only names follow
-b,--batch- Do not auto-commit
-i,--init- Only set if configuration key does not exist yet
grommunio-admin¶
The grommunio-admin API and CLI are also dbconf consumers. This allows system adiministrators to change certain configurations without filesystem access and the need to restart the API.
The following files and keys are meaningful when placed under the grommunio-admin service:
multi-server¶
policy- Server selection policy for newly created users and domains in multi-server environments. Possible values are balanced, first, last, random and round-robin. Default is round-robin.
Commit Hooks¶
When modifying values, potential consumers can be notified of this change via commit hooks, for example by restarting the service using the configuration. For security reasons only a few white-listed commands are available (see section AVAILABLE COMMIT COMMANDS).
Commit hooks can be defined on key, file or service level.
set operations always trigger commits at key level, while the commit
command can directly trigger key or service level hooks depending on
whether a file or key is specified.
If no hook is defined for a specific trigger level, it automatically falls through to the next lower level, in the order key > file > service.
Commit hooks for a service can be defined by setting commit_key,
commit_file and commit_service keys under
grommunio-dbconf/<service> to a valid command (see below).
Available Commit Commands¶
The following commands are available:
Key¶
postconf -e $ENTRY
File¶
There are currently no file-level commands.
Service¶
systemctl reload $SERVICEsystemctl restart $SERVICECommand Variable Expansion¶
Commands can contain $-prefixed variables that are expanded before execution. The literal $$ can be used to generate a single $.
The following variables are valid:
ENTRY- Expands to
$KEY=$VALUE(key level only) FILE- Complete content of the modified file as newline separated key=value entries (file level only)
FILENAME- Name of the modified file (key and file level)
KEY- The modified key (key level only)
SERVICE- Name of the modified service
VALUE- New value of the modified key (key level only)
grommunio-admin-domain¶
Name¶
grommunio-admin domain — Domain management
Synopsis¶
Description¶
Subcommand to show and manipulate domains.
Commands¶
create- Create a new domain
delete- Soft-delete a domain
list- List domains
modify- Modify domain
purge- Permanently delete domain
query- Query domain attributes
recover- Recover a soft-deleted domain
show- Show detailed information about a domain
Options¶
ATTRIBUTEAttributes to query. Available attributes are ID, activeUsers, address, adminName, chat, displayname, domainStatus, domainname, endDay, inactiveUsers, maxUser, orgID, tel and title
If no attributes are specified, ID, domainname and domainStatus are shown.
DOMAINNAME- Complete name of the domain
DOMAINSPEC- Domain name prefix or domain ID
--create-role- Automatically create a domain administrator role for the new domain
--files- Also delete files from disk
-f FIELD=<value>,--filter FIELD=<value>- Filter expression in the form of ‘field=value’. Can be specified multiple times to refine filter
--format FORMAT- Output format. Can be one of csv, json-flat, json-structured and pretty. Default is pretty.
- `` –homeserver HOMESERVER``
- ID of the homeserver to place the domain on
--no-defaults- Do not apply configured default values
--separator SEPARATOR- String to use for column separation (csv and pretty only). Must have length 1 if format is csv. Default is “,” for csv and ” ” for pretty.
-s FIELD,--sort FIELD- Sort by field. Can be given multiple times
-y,--yes- Assume yes instead of prompting
Fields¶
--address ADDRESS- Content of address field
--adminName ADMINNAME- Name of the domain administrator or primary contact
--endDay ENDDAY- Date of domain expiration in YYYY-MM-DD format
--orgID ID- ID of the organization to assign the domain to
--tel TEL- Telephone number of domain administrator or primary contact
-u MAXUSER,--maxUser MAXUSER- Maximum number of users in the domain
grommunio-admin-exmdb¶
Name¶
grommunio-admin exmdb — User or domain store management
Synopsis¶
Description¶
Subcommand to access and modify a domain’s or user’s store via exmdb protocol.
Commands¶
Folder subcommand¶
find- Find folders with given name
grant- Grant permissions on this folder to a user
list- List subfolders of a folder. If no folder ID is specified, list subfolders of root folder.
revoke- Revoke permissions on this folder from a user. If not permission is specified, revoke all permissions.
Store subcommand¶
delete- Delete properties
get- Get store properties
set- Set store properties
Options¶
ID- ID of the folder
NAME- Name of the folder
PERMISSION- Name or numeric value of the permission
PROPSPEC- Name or numeric value of the property
TARGET- Name of the domain or e-mail address of the user
USERNAME- E-Mail address of a user
-f,--force- Grant permissions to non-existing user
--format FORMAT- Set output format. Valid values are csv, json-flat, json-tree, pretty and table. Default is pretty.
-r,--recursive- Apply recursively to subfolders
-x,--exact- Only match exact folder names instead of case-insensitive substrings
Notes¶
- Folder IDs and permissions can be given in decimal, hexadecimal (0x-prefix), octal (0-prefix) or binary (0b-prefix).
- Currently, the permission value echoed by the grant and revoke commands is the one sent to the server and might differ from the value actually assigned.
- The find and list commands operate on the IPMSUBTREE folders (0x2 for users, 0x9 for domains) by default, which can be overridden by the ID parameter.
grommunio-admin-fetchmail¶
Name¶
grommunio-admin fetchmail — Manage fetchmail settings and generate rc file
Synopsis¶
Description¶
Subcommand to show and manipulate fetchmail entries and generate fetchmailrc file.
Commands¶
create- Create a new fetchmail entry
delete- Delete fetchmail entry
list- List fetchmail entries
modify- Modify fetchmail entry
print- Print fetchmail configuration line generated by the entry
show- Show detailed information about fetchmail entry
write-rc- Write fetchmail configuration file (fetchmailrc)
Options¶
MAILBOX- E-Mail address of the local mailbox to deliver the mails to. Defaults to e-mail address of the specified user
MBSPEC- Mailbox prefix or ID of the fetchmail entry
USERSPEC- Username prefix or ID of the user to attach the entry to
-f FIELD=<value>,--filter FIELD=<value>- Filter expression in the form of ‘field=value’. Can be specified multiple times to refine filter
--force- Write rc file even if no entries were changed since the last write
-o,--out-file- Path to write configuration to. Default is /etc/fetchmailrc
--password- Print the source password
-p,--print- Additionally print rc file to stdout
-q,--quiet- Do not print additional info
-s FIELD,--sort FIELD- Sort by field. Can be given multiple times
-t,--time- Time in minutes since the last write. Default is to autodetect by file mtime
-v,--verbose- Be more verbose
-y,--yes- Delete multiple entries without prompting
Fields¶
--active STATE- Whether the entry is active. STATE can be one of 0, 1, yes or no. Default is 1
--extraOptions EXTRAOPTIONS- Space separated list of options to write into the fetchmailrc
--fetchall STATE- Whether to fetch mails marked as seen on the source server. STATE can be one of 0, 1, yes or no. Default is 0
--keep STATE- Whether to keep fetched mails on the source server. STATE can be one of 0, 1, yes or no. Default is 1
--protocol PROTOCOL- Protocol to use for fetching. Can be one of POP3, IMAP, POP2, ETRN or AUTO. Default is IMAP
--srcAuth AUTH- Authentication method to use. Can be one of password, kerberos_v5, kerberos, kerberos_v4, gssapi, cram-md5, otp, ntlm, msn, ssh, any. Default is password
--srcFolder FOLDER- Source folder to fetch from
--srcPassword PASSWORD- Password of the source user. Single (‘) and double (“) quotes are automatically removed.
--srcServer SERVER- Source server to fetch from
--srcUser USER- Source user to fetch mails from
--sslCertCheck STATE- Whether to force SSL certificate check. STATE can be one of 0, 1, yes or no. Default is 0
--sslCertPath SSLCERTPATH- Path to a directory containing trusted certificates or empty to use system default
--useSSL STATE- Enable SSL
grommunio-admin-fs¶
Name¶
grommunio-admin fs — Filesystem operations
Synopsis¶
Description¶
Show space used by user and domain home directories or remove unused files.
Unused files may remain when users or domains are deleted without removing their files.
Commands¶
clean- Remove directories and files that are not used by any domain or user.
du- Show data usage statistics
Options¶
PARTITION- Apply only to selected partition. Can be either domain or user
-d,--dryrun- Do not delete anything, just print what would be deleted
-s,--nostat- Do not collect disk usage statistics of deleted files
grommunio-admin-ldap¶
Name¶
grommunio-admin ldap — LDAP tools
Synopsis¶
Description¶
The grommunio admin ldap module provides functions for configuring and testing the LDAP connection and downloading or updating users.
Commands¶
check- Check if the LDAP objects imported users are linked to can still be found, optionally removing orphaned users
configure- Interactively configure or modify LDAP connection
downsync- Synchronize or import users from LDAP
dump- Print LDAP object
info- Show connection status
reload- Reload the LDAP configuration and reconnect
search- Search for users
Options¶
USER- LDAP object ID or search string
-a,--auto- Never prompt, exit with error on conflicts. Implies -y.
-c,--complete- Import or update all users from the LDAP tree
-f,--force- Force update users that are linked to a different or no LDAP object
-l,--lang- Set language for imported users. Default is to not set any language.
-p PAGE_SIZE,--page-size PAGE_SIZE- Set batch size for paged search. Can be decreased when running into timeout errors with slow LDAP servers. Default is 1000.
-m,--remove-maildirs- Also remove user files from disk
-n MAX_RESULTS,--max-results MAX_RESULTS- Maximum number of results or 0 to disable limit (default 0). Note that the actual number of results may exceed the limit due to paging and filtering.
-r,--remove- Remove imported users of which the linked LDAP object could not be found
-y,--yes- Do not prompt for confirmation, assume yes
grommunio-admin-mconf¶
Name¶
grommunio-admin mconf — Managed configuration manipulation
Synopsis¶
Description¶
grommunio managed configuration (mconf) offers the possibility to manipulate configuration files used by gromox.
Commands¶
dump- Print configuration file that would be generated from internal state
modify- Modify internal configuration state
print- Print internal configuration state
reload- Reload configuration from disk
save- Save configuration file to disk
Options¶
ACTIONModification action:
add - Add entry to listremove - Remove entry from listset - Add keyunset - Remove keyCONFIG- Configuration file, either authmgr or ldap
KEY- Configuration key
VALUE- Configuration value for numeric or boolean values use -b and -i respectively
-b,--bool- Convert value to boolean, valid values are y, n, yes, no, true, false, 1, 0
-c,--censor- Hide confidential information
-i,--int- Convert value to integer, octal (0o) and hexadecimal (0x) prefixes are supported
grommunio-admin-mlist¶
Name¶
grommunio-admin mlist — Mailing/distribution list management
Synopsis¶
Description¶
Create, modify or delete mailing lists.
Commands¶
add- Add sender or recipient to list
create- Create a new mailing list
delete- Delete mailing list
list- List mailing lists
modify- Modify mailing list
remove- Remove sender or recipient from list
show- Show detailed information about mailing list
Options¶
-c CLASS,--class CLASS- ID of the associated class (class type only)
-p PRIVILEGE,--privilege PRIVILEGE- Set who is allowed to send mails to the list, one of all, domain, internal, outgoing or specific
-f FIELD=<value>,--filter FIELD=<value>- Filter expression in the form of ‘field=value’. Can be specified multiple times to refine filter
-s FIELD,--sort FIELD- Sort by field. Can be given multiple times
-t TYPE,--type TYPE- List type (recipient selection), one of normal, domain or class
grommunio-admin-passwd¶
Name¶
grommunio-admin passwd — Set user password
Synopsis¶
grommunio-admin passwd [-a] [-l LENGTH] [-p PASSWORD] [USER]
Description¶
Options¶
USER- User to set password for (default admin)
-a,--auto- Automatically generate a password
-l LENGTH,--length LENGTH- Length of the automatically generated password (default 16)
-p PASSWORD,--password PASSWORD- Password to set (do not prompt)
grommunio-admin-run¶
Name¶
grommunio-admin run — Start a stand-alone HTTP server
Synopsis¶
grommunio-admin run [-d] [-i IP] [–no-config-check] [-p PORT]
Description¶
Run REST API in a stand-alone HTTP server.
Options¶
-d,--debug- Enable debug mode
-i IP,--ip IP- Host address to bind to (default ::)
--no-config-check- Skip configuration check
-p PORT,--port PORT- Host port to bind to (default 5001)
grommunio-admin-server¶
Name¶
grommunio-admin server — Multi-server management
Synopsis¶
Description¶
Subcommand to show and manipulate server entries.
If at least one server is specified, newly created users and domains will be associated with one of the servers. The destination server may be specified explicitly, or is chosen automatically according to options.serverPolicy.
Commands¶
create- Register a new server
delete- Soft-delete a server
list- List domains
modify- Modify server
show- Show detailed information about a server
Options¶
SERVERSPEC- Server hostname or ID
-f FIELD=<value>,--filter FIELD=<value>- Filter expression in the form of ‘field=value’. Can be specified multiple times to refine filter
-s FIELD,--sort FIELD- Sort by field. Can be given multiple times
Fields¶
-H HOSTNAME,--hostname HOSTNAME- Internal hostname of the server
`-e EXTNAME,--extname EXTNAME- External hostname (e.g. FQDN) of the server.
grommunio-admin-service¶
Name¶
grommunio-admin service — grommunio-admin external service interface control
Synopsis¶
Description¶
UNLOADED- The service has not been loaded yet. It will be loaded automatically when needed.
LOADED- The service has been initialized successfully.
UNAVAILABLE- An error occurred that indicates that the service is not available, but might become available in the future. No reload is necessary to reconnect.
SUSPENDED- Àn error occurred that indicates that the service is not available, but might become available in the future. The service will be reloaded automatically on next usage.
ERROR- The service is not available either because initialization failed or because to man errors occurred. It will remain unavailable until reloaded manually.
DISABLED- The service has been manually disabled (either by configuration or command).
Commands¶
disable¶
load¶
status¶
Options¶
SERVICE- Name of the service.
-r,--reload- Force reload of service.
-v,--verbose- Show more information.
Services¶
The following services are currently connected via the service interface:
chat- grommunio chat. Connected via REST interface.
exmdb- gromox exmdb provider (gromox-http). Connected via custom TCP protocol.
ldap- External LDAP service. Connected via LDAP(s).
redis- Redis instance (used by grommunio sync). Connected via redis driver (TCP).
systemd- Systemd shell execution.
grommunio-admin-shell¶
Name¶
grommunio-admin shell — Start interactive shell
Synopsis¶
grommunio-admin shell [-d] [-n] [-x]
Description¶
The interactive shell mode allows execution of multiple (new line separated) commands in a single session. Command syntax is identical to the CLI arguments, with addition of the exit command which ends the interactive shell.
If possible, typed history will be saved in ~/.grommunio-admin.history.
Options¶
-d,--debug- Enable more verbose debug output
-n,--no-history- Disable loading/saving of the typed history
-x,--exit- Exit immediately if a command results in a non-zero exit code
grommunio-admin-taginfo¶
Name¶
grommunio-admin taginfo — Show information about proptags
Synopsis¶
grommunio-admin taginfo TAG [TAG …]
Description¶
Options¶
TAG- Decimal or hexadecimal (with 0x prefix) Tag ID or grommunio tag name
grommunio-admin-user¶
Name¶
grommunio-admin user — User management
Synopsis¶
Description¶
Subcommand to show and delete users.
No functionality for adding or modifying users is implemented at the moment.
Commands¶
create- Create a new user
delete- Delete user
list- List users Deprecated. Use query instead.
modify- Modify a user
query- Query user attributes
show- Show detailed information about a user
Options¶
ATTRIBUTEAttributes to query. Available attributes are ID, aliases, changePassword, chat, chatAdmin, domainID, forward, homeserverID, lang, ldapID, maildir, pop3_imap, privArchive, privChat, privFiles, privVideo, publicAddress, smtp, status and username.
If no attributes are specified, ID, username and status are shown.
USERNAME- E-Mail address of the user
USERSPEC- User name prefix or user ID
-c,--keep-chat- Deactivate but do not permanently delete chat user
--delete-chat-user- Permanently delete chat user
-f FIELD=<value>,--filter FIELD=<value>- Filter expression in the form of ‘field=value’. Can be specified multiple times to refine filter
--format FORMAT- Output format. Can be one of csv, json-flat, json-structured and pretty. Default is pretty.
-k,--keep-files- Do not delete user files from disk
--no-defaults- Do not apply configured default values
--no-ldap- Detach user from LDAP object
--remove-alias ALIAS- Remove ALIAS from user (can be given multiple times)
--remove-property PROPSPEC- Remove property from user (can be given multiple times)
--remove-storeprop PROPSPEC- Remove property from user’s store (can be given multiple times)
--separator SEPARATOR- String to use for column separation (csv and pretty only). Must have length 1 if format is csv. Default is “,” for csv and ” ” for pretty.
-s FIELD,--sort FIELD- Sort by field. Can be given multiple times
-y,--yes- Assume yes instead of prompting
Fields¶
--changePassword <bool>- Whether the user can change the password
--chat <bool>- Whether to create a chat user
--chatAdmin <bool>- Whether the user has chat admin privileges
--homeserver ID- ID of the home server or 0 for local user
--lang LANG- User store language
--ldapID LDAPID- Identifier of the LDAP object linked to the user
--pop3-imap <bool>- Whether the user has the POP3/IMAP privilege
--privArchive <bool>- Whether the user has the archiving privilege
--privChat <bool>- Whether the user has the chat privilege
--privFiles <bool>- Whether the user has the files privilege
--privVideo <bool>- Whether the user has the video privilege
--public-address <bool>- Whether the user has the public address privilege
--smtp <bool>- Whether the user has the SMTP privilege
--status STATUS- User address status. Either numeric value or one of normal, suspended, out-of-date, deleted or shared.
--alias ALIAS- Add alias
--property propspec=value- Set property defined by propspec to value
--storeprop propspec=value- Set store property defined by propspec to value
grommunio-admin-version¶
Name¶
grommunio-admin version — Show backend and/or API version
Synopsis¶
grommunio-admin version [-a] [-b] [-c]
Description¶
If multiple options are given, each requested version is printed on a separate line. The order is always API – backend – combined.
Options¶
-a,--api- Print API version
-b,--backend- Print backend version
-c,--combined- Print combined version