This chapter covers a short walkthrough which can be used as a check list to install and get grammm started.
Download the installation ISO from https://download.grammm.com/appliance/GRAMMM_Appliance.x86_64-latest.install.iso. The installation image is a hybrid installation image which also allows to be transferred to a USB-stick with USB imaging tools, such as https://rufus.ie.
Use the installation media from grammm to install and quickstart the configuration by walking through the following chapters.
Create or request TLS certificates for secure, encrypted operation of the main services.
Create the corresponding DNS records with a sane configuration (A, MX, TXT and CNAME records).
Configure the grammm appliance by running grammm-setup.
For the installation of grammm (or using the grammm Appliance), the following minimal requirements apply:
Server or virtual machine (VMware, Xen or Hyper-V) with at least:
4 CPU cores
6 GB RAM
Correctly configured DNS records, at least two, for example:
<FQDN>, for example mail.example.com
A TLS certificate with all included DNS names, alternatively a wildcard certificate for the entire domain. (Let’s Encrypt can be configured by grammm-setup.) If you already own a certificate, it can be re-used provided it is in PEM format, with one file containing the certificate chain and server certificate, as well as a separate key file.
It is strongly recommended to properly set up the corresponding autodiscover.example.com DNS entry, otherwise AutoDiscover will not be able to determine the server.
MX DNS records, for incoming mail delivery.
At the time of certificate generation by Let’s Encrypt, the accessibility of port 80 to all of the defined DNS records is a requirement.
Download of the bootable x86 image from download.grammm.com: https://download.grammm.com/appliance/GRAMMM_Appliance.x86_64-latest.install.iso
Load the file for installation into the server on which grammm should be installed on.
Run the installer and choose “Install GRAMMM_Appliance” from the boot menu to install the appliance.
Note that the installer asks for confirmation to delete and overwrite the installation target!
After the image has been copied to disk, the appliance is ready for setup.
After installation, the appliance displays the grammm console user interface (CUI).
The initial root password is unset (empty). When asked for password, just press “Enter”.
To configure grammm, proceed as follows:
Choose “Change Password” to set a new root password.
Choose “Network Configuration” to set up networking of the appliance.
Choose “grammm setup wizard” to guide through subsequent configuration interactively.
The “grammm setup wizard” invokes grammm-setup, which can be started from the CUI or any other terminal of the appliance.
SSH is enabled by default, therefore grammm-setup can also be executed from an SSH session. Note that a password must have been set before you can login via SSH.
To navigate within the grammm setup wizard (grammm-setup), use the following navigation hints:
<TAB> navigates through dialog elements
<ARROW-UP> or <ARROW-DOWN> naviate within form elements (such as when entering subscription details) or menu selections (during database setup)
<j> or <k> keys for scrolling longer content-heavy dialogs (as in the finalization dialog)
<ESC> to terminate grammm-setup at any given stage of the configuration
grammm-setup automatically supplies defaults for most dialogs; these can be overridden as desired. For example, grammm-setup automatically generates passwords which are also available after the installation in the grammm-setup logfile, /tmp/grammm-setup.log.
If the configuration fails for any reason, grammm-setup can be re-run. However, any re-configuration from scratch is destructive and will re-initialize the installation. If you intend to change any system-related parameters, use the grammm administation interface instead. Any re-run grammm-setup invocation will warn and ask for confirmation before deleting any data.
The installation process is logged in /tmp/grammm-setup.log. Note that this file has all instance configuration used to configure grammm-setup. As a subscription owner, you are entitled for support, where, for example, you can send the installation log to grammm if you need any help. (Password references should be removed.)
It is recommended after successful information to store the installation log in a safe place and delete it from the appliance. Alternatively, the installation log can be stored safely somewhere as reference of any credentials of your installation for later use.
grammm Admin User¶
During the process of grammm-setup, some accounts are automatically generated - such as a database account for user management and also for the initial grammm administrator (admin).
The admin user of grammm and the root user of the appliance are separated, non-synced users. The admin user is solely known to the grammm Administration framework and is (intentionally) not a system user. The credentials of both users are to be kept safe. The root user is the main system administrator while admin is the main grammm administrator. They can (and should) have different passwords, with the role concept of grammm it is even recommended not to work with these passwords in production, but instead create less privileged for regular tasks performed.
The password of the primary admin user can be changed anytime by using grammm-cui or by executing
grammm-admin passwd --password "PleaseChangeMe"
The interactive configuration tool grammm-setup requests subscription credentials during execution. If you own a valid subscription, enter your subscription details. Without a valid subscription, grammm-setup activates the community repositories, which are without support and contain non-quality-tested packages. With a valid subscription, your subscription repository is activated and delivers commercial-grade packages for the installation to keep up-to-date with latest features and fixes.
To receive a valid subscription, contact any of our partners or via our established communication channels at https://grammm.com
With grammm-setup, you are able to choose from multiple choices for certificate installation:
Creation of self-signed certificate
Creating your own self-signed certificate is the simplest option - Creating an own self-signed certificate will though show up as untrusted at first connect and needs to be trusted before continuing. This behavior is normal and is because any client that connects has no possibility validation if the certificate has a valid source. This setting is the default and does not require any preparation for certificate generation. grammm does not recommend this option for production environments, as this option requires any client to first trust the certificate in use. This option is the best for validation and demo installations of grammm.
Creation of own CA (certificate authority) and certificate
Creating your own certificate authority is an extended option which allows you to create self-signed certificates with an own certificate authority. This way, you can (manually) create further certificates under the umbrella of a own central authority with multiple server certificates to be signed by the same certificate authority generated by yourself. This option is the best for validation and demo installation of larger installations of grammm with multiple instances.
Import of an existing TLS certificate from files
Importing your own certificate allows any type of external certificate pair (PEM-encoded) to be used with your grammm installation. Note that it is recommended to either use SAN certificates with multiple domains or a wildcard certificate. With your choice of your own TLS certificates, you have the highest flexibility to either use a trusted CA or a publicly signed certificate by an offically trusted certification authority including, but not limited to, Thawte, Digicert, Comodo or others.
Automatic generation of certificates with Let’s Encrypt
Using this option allows the automatic certificate generation process with the Let’s Encrypt certificate authority. Using Let’s Encrypt certificates is free of charge, however the terms of service by Let’s Encrypt apply, which are referenced during installation. Using this option automatically requests the domains from the selection you made, and automatically starts the validation process. For this automated process to work successfully, Let’s Encrypt verifies _all_ defined domain names by creating a challenge on the appliance. For this to work, port 80 (HTTP) needs to be accessible from the Internet during this step of verification (and any subsequent automated renewal) with all the domains pointing to the appliance. This option is recommended for any simple installation and allows the most seamless installation experience if prepared correctly.
Any certificates so generated are placed in /etc/grammm/ssl and are automatically referenced by any services of the appliance.
For seamless operation, the grammm appliance opens different ports so that clients can access it. Note that all of the following ports are made available by default:
8443 (admin https), coming soon
Generally, it is recommended to only make available the ports that are required for service access. Note that grammm’s major protocols, RPC over HTTP, MAPI/HTTP, EWS (Exchange Web Services) and EAS (Exchange ActiveSync) are all accessed via port 443 (HTTPS).
When operating with proxies and load balancers, note that for successful operation of proxying RPC, special configuration needs to be in place. The required HTTP transport modes required to operate RPC over proxies are RPC_IN_DATA and RPC_OUT_DATA. Known supported proxy software to support these RPC data channels are: haproxy, squid, nginx and apache.