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