API server - How it works

PROBLEM

How does the atmail API server work?

ENVIRONMENT

• atmail suite - API server

CAUSE

I want to further understand the API servers role within my atmail installation.

RESOLUTION

The atmail API server provides a level of abstraction above atmail suite installations. Think of the atmail API server as the traffic controller that is responsible for administrating all communication between services (SMTP, IMAP/POP, DAV, Anti-Spam, Anti-Virus, ManageSieve). The API server acts similar to a proxy as it receives and forwards requests to and from the corresponding modules within the installation.

To provide a real world example of the API servers role, this document will explore the interactions between the API server and the rest of the atmail suite that occur when a user is provisioned.

User Provisioning

The /etc/atmail/api/api.conf file contains configuration options that are used to initialize your apiserver.service. Within the api.conf, is the option for defining what service accounts (mail, contacts, calendar) will be provisioned upon creation of a user. The PROVISION= variable accepts a bitfield that defaults to 7. The integer set in the bitfield will determine what service accounts are to be automatically provisioned upon a users first login. The following integers are accepted:

• 7 all service accounts
• 6 contacts and calendar service accounts
• 5 mail and contact service accounts
• 4 contact service account
• 3 mail and calendar service account
• 2 calendar service account
• 1 mail service account

Example

Using the atmail mailserver, if we create a user called bob@atmail.com via the webadmin, only the atmail mailserver database will be populated with the appropriate values as seen below:

MariaDB [mailserver]> select * from accounts where username = 'bob@atmail.com'\G
*************************** 1. row ***************************
       accountId: 4
 createdByUserId: 1
        username: bob@atmail.com
        password: {SSHA256}diItlPkdWkA18C2u6tAkeX58S1wkmp2zxvjDxgSk0k2+cZ06mCoHNA+j+LZiHAxz3qZ0goVeCkSvc6AMNxgryw==
        domainId: 2
    dateModified: 2017-04-27 14:17:20
      dateCreate: 2017-04-27 14:17:20
      userStatus: 0
         homeDir: /var/atmail/users/c/a/d/bob@atmail.com/
         forward: NULL
       autoReply: NULL
           quota: 1024
       lastLogin: NULL
autoReplyEnabled: 0
autoReplySubject: 
  autoReplyStart: NULL
    autoReplyEnd: NULL
      mboxServer: 1
        mboxType: Maildir
         groupId: 1
       firstName: 
        lastName:

When bob@atmail.com logs in for the first time, the API reads its PROVISION=7 variable and begins assigning service account ID's. Below is the /var/log/atmail/api.log output of this occurring.

time="2017-04-27T14:47:01+10:00" level=info msg="checkUserProvisioning: OK" AccountID=3 
ID=4 IdentityID=3 Params={bob@atmail.com 192.168.10.236 test  false} ServiceAccountID 
(CALENDAR)=10 ServiceAccountID (CONTACTS)=9 ServiceAccountID (MAIL)=8

The above output can then be confirm by querying your API servers database as seen below:

MariaDB [apiserver]> select * from Accounts where Name = 'bob@atmail.com'\G
*************************** 1. row ***************************
        idAccount: 3
          idUsers: 4
             Name: bob@atmail.com
        IsPrimary: 1
           Active: 1
    idMailAccount: 8
 idContactAccount: 9
idCalendarAccount: 10
1 row in set (0.00 sec)

The API server has now successfully provisioned a user and the account now has mail, contact and calendar functionality.

The API server also has a command line tool that allows administration to be performed from the terminal. Information on this can be in our apiadmin - command line interface administration documentation.