Tutorials

This chapter includes basic tutorials to help you set up your own grammm infrastructure.

Accessing grammm admin UI

After successfully installing the grammm ISO, 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 ISO, you can immediately use these credentials to login.

grammm login

To navigate through the UI, simply use the drawer on the left side of the page.

pic1 pic2

Dashboard

After a successfull login, you can see the dashboard with live data of the machine grammm runs on.

Antispam

Since grammm has its own antispam service, according data can be displayed in the Dashboard.

grammm antispam chart

Services

Antispam isn’t the only grammm service, in fact there are lots more. The current state of these services can be seen on the left side of the dashboard.

grammm services chart

You can stop, restart or start these services from here by clicking the action buttons of a service in the list.

CPU

grammm cpu chart

A live and history display of the CPU usage.

Memory

grammm memory chart

A live and history display of the memory usage.

Disks and swap

grammm disks chart

A live display of the disks and swap.

Load

grammm load chart

A display of the system load over the last 1, 5 and 15 minutes.

Domains

Click on Domain list in the drawer, which will redirect you to the list view of existing domains. If you just set up grammm, 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:

adding domain

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

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.

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

editing domain

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.

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 grammm or added the domain, the list will be empty.

Adding a user

To add a new user, click the blue NEW USER button to open the form dialog:

adding a user

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.

editing 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:

  • Status: Status of the user

  • Type: Type of user

  • Language: Language of the user

  • 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

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.

Roles

Roles of the user, which can be edited with the autocompleting textfield

editing a user

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.

editing a user

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.

editing a user

To add new fetchmail entry, click the circled plus-icon, which will open the following input form:

editing a user
  • 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

  • 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 grammm 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:

adding a folder

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.

editing 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 grammm 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.

grammm group tree

Adding a group

To add a new group, click the blue NEW GROUP button to open the form dialog:

adding a group

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

editing a group

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 grammm 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:

adding a mail list

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.

edit 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 grammm, 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:

adding a role

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.

editing 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 grammm, 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:

adding a role

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.

editing a role

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.

Settings

To change global settings, click on the User-icon and Settings

user icon

Currently you can only change

  • Language: Swap between English and German

  • Darkmode: Swap between light- and Darkmode

License

grammm license

To use the full potential of grammm you can upload your license by clicking Upload and selecting your purchased license. If you do not have a grammm license yet, but want to upgrade, you can click on Buy now.

The following license properties are display:

  • Product: Type of grammm subscription (Community, Business, etc…)

  • Created: Date on which the license was created

  • Expires: Lat 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

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.

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.

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

search ldap

There is the option to force the import. If checked, an existing user with this usename in the grammm database will be overwritten.

importing a user

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.

orphanbed 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

Adding a file

A useful example would be to configure a relayhost in postfix:

adding a file

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.

editing a file

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 grammm-dbconf

grammm-dbconf is an internal service, that will execute actions/commands when configs change. These actions can be specified for every service separately.

Adding a grammm-dbconf file

Actions to be executed when a config of a service <servicename> changes, need to be set in the file grammm-dbconf/<servicename>.

There are pre-made commands to set for either key-, file- or service-changes. Those can be found on the Commands tab

file commands

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:

adding dbconf

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 grammm/gromox services, which journalctl logs you can view here.

adding dbconf

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.