Product SiteDocumentation Site

Kolab Groupware 3.0

Architecture and Design

Edition 0

Christian Mollekopf

Kolab Systems Software Engineer

Jeroen van Meeuwen

Kolab Systems Systems Architect

Legal Notice

Copyright © 2011-2012 Kolab Systems AG This material may only be distributed subject to the terms and conditions set forth in the GNU Free Documentation License (GFDL), V1.2 or later (the latest version is presently available at http://www.gnu.org/licenses/fdl.txt).
Abstract
This document is the reference to version 3.0 of the Kolab Groupware Solution architecture and design considerations, specifications and implementation details.

Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Feedback
2.1. Reporting Bugs in Kolab
2.2. Mailing Lists
2.3. IRC
3. About Kolab Groupware
3.1. Free Software Components
3.2. Supported Platforms and System Requirements
3.3. Kolab Product Series
1. Groupware Overview
2. Kolab Server Overview
2.1. Functional Requirements of the Authentication & Authorization Database
2.2. Functional Requirements of the (Web) Administration
2.3. Functional Requirements of the Mail Exchanger
2.4. Functional Requirements of the IMAP Server
2.5. Functional Requirements for the (Web) Client
3. Kolab SMTP Access Policy
3.1. What the Kolab SMTP Access Policy is
3.2. What the Kolab SMTP Access Policy is not
3.3. When?
3.4. Kolab SMTP Access Policy in Action During Submission
4. Email
4.1. Content-filtering
4.1.1. Recipient Checking
4.1.2. Anti-Spam
4.1.3. Anti-Virus
4.1.4. White- and Blacklisting
4.1.5. Greylisting
4.1.6. Real-time DNS Blacklisting
4.1.7. Sender Address Verification
4.1.8. SPF Record Enforcement
4.2. Recipient Checking
4.3. Integration & Interoperability
4.3.1. Pretty Good Privacy & S/MIME
4.3.2. Email Routing
4.3.3. Shared Folders
4.3.4. Distribution Groups
4.3.5. See Also
5. Calendaring
6. Kolab Daemon
7. Kolab Content Filters
7.1. The Wallace Content Filter
7.1.1. Message Flow and Processing in Wallace
7.1.2. Module Spool Directories
7.1.3. Module API Requirements
7.1.4. Wallace Module Interfaces
7.1.5. List of Wallace Modules
7.1.6. Configuring the Wallace Content Filter
7.1.7. Security Enhanced Linux Considerations
8. Kolab Objects
8.1. Object Types
9. Authentication & Authorization
9.1. The User Supplied Login
9.2. LDAP
9.2.1. Username & Password Authentication
9.2.2. Kerberos Authentication
9.2.3. SSL Certificate Authentication
9.2.4. Kolab & LDAP
9.3. PAM
9.3.1. Username & Password Authentication
9.3.2. One-Time Passwords
9.3.3. Kerberos Authentication
9.3.4. SSL Certificate Authentication
9.3.5. Kolab & PAM
9.4. SASL Database
9.4.1. Username & Password Authentication
9.4.2. Kerberos Authentication
9.4.3. SSL Certificate Authentication
9.4.4. Kolab & SASL Database
9.5. SQL
9.5.1. SQL Technologies
9.5.2. Username & Password Authentication
9.5.3. Kerberos Authentication
9.5.4. SSL Certificate Authentication
9.5.5. Kolab & SQL
9.6. Password Supplements & Security
9.6.1. Simple Authentication Security Layer
9.6.2. "No plain text over the wire"
9.7. Authorization Through Groups
10. Integration & Interoperability
10.1. Authentication & Authorization
10.2. Auditing
10.3. Calendaring
10.4. Email
10.4.1. Content-filtering and 3rd Party Appliances
10.5. Recipient Checking
10.6. SSL Certificate Infrastructure
11. Configuration Management
11.1. Configuration Management Objects
11.2. Kolab Configuration File
11.2.1. [kolab]
11.2.2. [ldap]
11.2.3. A Base DN for Every Type
11.2.4. Use of Bind Credentials
12. Archiving & Discovery
12.1. Methodologies for Archiving
12.1.1. Blind Carbon Copy
12.1.2. Save to Archive
12.1.3. IMAP Server Replica Client
12.1.4. Backup with Delayed Delete and Expunge
12.2. Methodologies for Discovery
12.2.1. Analysis of the Telemetry Log
12.2.2. IMAP Server Replica Client
13. Akonadi for Integration and Caching
13.1. Server-Side Akonadi Architecture Overview
13.2. Procedural Descriptions
13.3. Notes from Design Sessions
13.3.1. Authentication to Akonadi Control Server
13.3.2. AMQP Capabilities for libakonadi
13.3.3. AMQP Capabilities for Akonadi
13.3.4. libakonadi Direct IMAP Connections
14. Free/Busy
15. Smart Clients
15.1. First-time Login
15.2. Consecutive Operations
15.3. Default Groupware Folders
15.4. Access Control, Shared Folders and User Interaction
15.4.1. More Advanced Display
16. Mobile Device Synchronization
16.1. SyncML
16.2. ActiveSync
17. Administration Panel
17.1. Configuration
17.2. Deployment
17.3. Web Administration Panel API
17.3.1. HTTP Method Convention
17.3.2. Service and Method Naming Convention
17.3.3. Standard Response Layout
17.3.4. Service Handlers
17.3.5. The domain Service
17.3.6. The domains Service
17.3.7. The form_value Service
17.3.8. The group Service
17.3.9. The system Service
17.3.10. The user Service
17.3.11. The user_types Service
17.3.12. The users Service
18. Enforcing Entitlements
18.1. Software Repositories Behind Lock and Key
18.2. Entitlements Files
18.3. Issuing Entitlement Files
18.4. Implementing Enforcement
19. Migration
A. Terminology
B. Feature FAQ
B.1. What Kolab Groupware Is (Not)
B.2. Detailed Questions
Index

Preface

1. Document Conventions

This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keycaps and key combinations. For example:
To see the contents of the file my_next_bestselling_novel in your current working directory, enter the cat my_next_bestselling_novel command at the shell prompt and press Enter to execute the command.
The above includes a file name, a shell command and a keycap, all presented in mono-spaced bold and all distinguishable thanks to context.
Key combinations can be distinguished from keycaps by the hyphen connecting each part of a key combination. For example:
Press Enter to execute the command.
Press Ctrl+Alt+F2 to switch to the first virtual terminal. Press Ctrl+Alt+F1 to return to your X-Windows session.
The first paragraph highlights the particular keycap to press. The second highlights two key combinations (each a set of three keycaps with each set pressed simultaneously).
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in mono-spaced bold. For example:
File-related classes include filesystem for file systems, file for files, and dir for directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose SystemPreferencesMouse from the main menu bar to launch Mouse Preferences. In the Buttons tab, click the Left-handed mouse check box and click Close to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
To insert a special character into a gedit file, choose ApplicationsAccessoriesCharacter Map from the main menu bar. Next, choose SearchFind… from the Character Map menu bar, type the name of the character in the Search field and click Next. The character you sought will be highlighted in the Character Table. Double-click this highlighted character to place it in the Text to copy field and then click the Copy button. Now switch back to your document and choose EditPaste from the gedit menu bar.
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
Mono-spaced Bold Italic or Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
To connect to a remote machine using ssh, type ssh username@domain.name at a shell prompt. If the remote machine is example.com and your username on that machine is john, type ssh john@example.com.
The mount -o remount file-system command remounts the named file system. For example, to remount the /home file system, the command is mount -o remount /home.
To see the version of a currently installed package, use the rpm -q package command. It will return a result as follows: package-version-release.
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
Publican is a DocBook publishing system.

1.2. Pull-quote Conventions

Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in mono-spaced roman and presented thus:
books        Desktop   documentation  drafts  mss    photos   stuff  svn
books_tests  Desktop1  downloads      images  notes  scripts  svgs
Source-code listings are also set in mono-spaced roman but add syntax highlighting as follows:
package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient
{
   public static void main(String args[]) 
       throws Exception
   {
      InitialContext iniCtx = new InitialContext();
      Object         ref    = iniCtx.lookup("EchoBean");
      EchoHome       home   = (EchoHome) ref;
      Echo           echo   = home.create();

      System.out.println("Created Echo");

      System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));
   }
}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note

Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.

Important

Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.

Warning

Warnings should not be ignored. Ignoring warnings will most likely cause data loss.

2. Feedback

We value feedback on our software as well as our documentation. Please find ways to contact us in this section.

2.1. Reporting Bugs in Kolab

Bug reports can be logged in our Bugzilla issue tracker. Please bear in mind registration is required to log bugs.
Before reporting a bug, please search the issue tracker for existing bugs that may report the same problem.
When reporting a bug, please prepare to provide the following information;
  • Your platform, and if applicable, your distribution and the distribution version.
  • The version(s) of the relevant Kolab component(s) you are using.
  • If a custom version is used, any options that may have specified during the build process.

2.2. Mailing Lists

Mailing lists are a quick way to get in touch with a large number of subscribers, who may know the answer to your question or can provide you with additional insight.
Announcement Mailing List
Kolab Groupware administrators and developers are strongly encouraged to subscribe to the moderated, low-volume announcement mailing list, to which important release announcements are submitted. We have the announcement mailing list available at https://lists.kolab.org/mailman/listinfo/kolab-announce. To subscribe to the list, either click the aforementioned link and fill out the information requested, or send an email to kolab-announce-subscribe@kolab.org.
User Mailing List
For users of Kolab software, we run a public mailing list at https://lists.kolab.org/mailman/listinfo/kolab-users. To subscribe to the list, either click the aforementioned link and fill out the information requested, or send an email to kolab-users-subscribe@kolab.org.
Development Mailing List
For developers of Kolab software, as well as general discussion on bugs and patches, we run a public mailing list at https://lists.kolab.org/mailman/listinfo/kolab-devel. To subscribe to the list and fill out the information requested, or send an email to kolab-devel-subscribe@kolab.org.

2.2.1. Archives

The archives of the announcement, user support and development discussion mailing lists are available through web archives.

2.3. IRC

Internet Relay Chat (IRC) is another way to get in touch with some of the people that develop and use Kolab Groupware. Use your favorite IRC client to connect to the FreeNode IRC Network, or use the web-based chat.
Once connected, join us in the #kolab IRC channel.

3. About Kolab Groupware

Kolab Groupware is a highly scalable, flexible, mutli-platform solution for Emails, Appointments, Contacts and more. It supports mixed client environments (Outlook/KDE) because of a well-defined, interoperable and open storage format. Any email client speaking standard protocols can be served.
The Kolab Groupware solution consists of many Free Software components, integrated by Kolab in order to build a groupware solution.

3.1. Free Software Components

Free Software components included with Kolab Groupware include;
  • Postfix
    Postfix attempts to be fast, easy to administer, and secure. The outside has a definite Sendmail-ish flavor, but the inside is completely different.
  • Cyrus IMAP
    Cyrus IMAP is a highly scalable enterprise mail system designed for use in enterprise environments of various sizes using standards based technologies. Cyrus IMAP technologies scale from independent use in email departments to a system centrally managed in a large enterprise.
  • OpenLDAP
    OpenLDAP Software is an open source implementation of the Lightweight Directory Access Protocol.
  • Roundcube
    Roundcube webmail is a browser-based multilingual IMAP client with an application-like user interface. It provides full functionality you expect from an e-mail client, including MIME support, address book, folder manipulation, message searching and spell checking.

3.2. Supported Platforms and System Requirements

Kolab Groupware is supported on the following platforms;

3.3. Kolab Product Series

Kolab Groupware consists of free software components, each of which are available from various upstream development and support project organizations, including Linux distributions.
The Kolab Groupware developers, community members and Kolab Systems engineering and support staff maintain many of the packages related to Kolab with the Linux distributions through which those packages are available.
The Kolab software repositories can therefor include only those software components, or those specific versions of software components, that differentiate from what is available through the upstream Linux distribution software repositories, and possibly recommended or required additional software repositories.
Product series are versioned, each of them created to provide a sustainable stream of updates to the individual software components included in that product serie.
The convention for Server Product Versioning is subject to the guidelines proposed and accepted as Kolab Enhancement Proposal #5 (KEP #5 for short).

3.3.1. Product Streams

Two different product streams exist, a community edition and an enterprise edition.
The differences between the community edition and the enterprise edition are as follows:
  1. No debuginfo sub-packages are made available through the repositories for the community edition. You typically need debuginfo sub-paclages in case stack traces need to be generated for binary compiled programs such as mysql, openldap, cyrus-imapd, php and others.
  2. The packages available through the repositories for the community edition are not signed with a PGP key, and therefor the authenticity of the packages cannot be verified.
  3. The repositories for the community edition are made available through HTTP only, while the enterprise edition's repositories are available over HTTPS only. For the community edition, the the authenticity cannot be verified.
  4. In the repositories for the community edition, no package builds other then the latest are made available. Rolling back a software update foo-1.0-2.el5 to a previously installed software version foo-1.0-1.el5 after a failed update is therefor not possible unless a copy of foo-1.0-1.el5 had been preserved.
  5. For the community edition, no security errata –other then for critical security issues– is sent out.
  6. The enterprise edition is supported for a longer term than the community edition.
  7. The software available in the enterprise edition is subjected to thorough quality assurance and certification before being made available.

3.3.2. Repository Stages

4 different repository stages exist, each of them indicating the expected level of stability, and point-in-time release.
The release and updates repositories contain the most stable software (community edition) which is supported (professionally in the enterprise edition).
The updates-testing repositories contain software that is being stabilized (through the collection of community feedback for the community edition) before being submitted to the updates repository.


[1] By reasonably recent versions of Linux, we intend to indicate the Kolab project can manage to keep up with the latest distribution release ear-marked stable.

Chapter 1. Groupware Overview

Groupware is collaborative software designed to allow people with a common task to achieve goals. Aspects in an infrastructure providing such functionality include;
  • Email,
  • Calendaring,
  • Task Management,
  • Journalling,
  • Contacts,
  • Address Books,
  • Notebooks & Notes
All of the former are capabilities provided by Kolab Groupware itself.
Technologies assisting collaborative efforts also include, however;
  • Voice- and Video Communications,
  • Message boards,

    Also known as bulletin boards, forums, news groups.

  • Knowledge bases,
  • Enterprise bookmarking,
  • Instant Messaging,
  • Document Management,
  • Project Management,
  • Work-flow Management
While each of the aforementioned aspects of groupware and collaboration is available as Free Software, integration is an entirely different topic.

Chapter 2. Kolab Server Overview

This chapter provides an overview of the architecture of the Kolab Groupware server. Figure 2.1, “Primary Components of the Kolab Server” illustrates the following primary functional components that make up a Kolab Groupware server deployment:
  • Authentication and Authorization Database
    The authentication database is the canonical source for information about users and groups, and is used to authenticate and authorize users –among other things. Traditionally, Kolab Groupware has been designed based on LDAP specific capabilities –more specifically, in fact, it has been based on OpenLDAP specific capabilities– but virtually any authentication and authorization method and/or technology is eligible to work for Kolab, including, but not limited to;
    • Kerberos (v5)
    • LDAP
    • MySQL
    • PAM
    • PostgreSQL
    • Shadow
    • SQLite(3)
  • (Web) Administration
    The optional web administration panel allows users and administrators to control certain aspects relevant to Kolab Groupware. For example, this includes folder subscriptions, authorization on folders, password management, mobile device management, and more.
    Most of the components in the web administration panel are subject to the user's authorization.
  • Mail Exchanger
    Mail exchangers are responsible for the exchange of email messages between nodes, as well as the exchange of email messages between services.
    Functionally, mail exchangers can be categorized using the following environment specific implementation characteristics;
    • Backend Mail Exchanger
      A backend mail exchanger typically installed on an IMAP backend server and is used for two primary purposes; to enable, having received a message for one or more recipients on the backend IMAP server in question, one-shot delivery through LMTP, and to generate the backscatter (non-delivery reports, LMTP related errors).
    • External Mail Exchanger
      An external mail exchanger is tasked with the exchange of email messages with external, 3rd parties. Typically, both email messages received from as well as sent to external sources passes through external mail exchangers.
    • Internal Mail Exchanger
      Internal mail exchangers are the core of an environment with multiple authentication- and/or authorization databases, and/or with multiple IMAP backend servers. Typically, internal mail exchangers relay email messages to the correct backend server, regardless of whether the backend server is a Microsoft Exchange SMTP bridgehead server, a Kolab IMAP backend server, or a external mail exchanger.
    The level in which each of the aforementioned types of mail exchangers are relevant functional components in a certain deployment scenario depends on the desired functionality of the architecture, as well as the available resources in order to implement such functionality.
  • IMAP Server
    The IMAP server is primarily responsible for mailbox storage, distribution and access control.
    To assist in the creation, modification and deletion of mailboxes, Kolab includes a daemon.
  • (Web) Client
    TODO

    (Web) Client does not include Smart Clients

    Although the (web) client software will need to have capabilities similar to those of a Smart Client, the distinction between (web) client software and smart clients like Kontact or Outlook is the latter two are not considered server components. There may be other server applications that act as a Kolab Groupware client.
Primary Components of the Kolab Server
Figure 2.1. Primary Components of the Kolab Server

2.1. Functional Requirements of the Authentication & Authorization Database

There is a certain minimal amount of information that Kolab requires to be available in any authentication database, such as the credentials that need to be supplied by a client in order to verify the identity of the user. Which details of those credentials are stored in the authentication database very much depends on the authentication technology used. For a Kerberos (v5) deployment for example, the username and realm would suffice (the ticket is verified with the KDC, and no password exchange is required). For an LDAP deployment however, any unique attribute value, or part thereof, within the search scope may be used in combination with the password needed for a fast-bind operation.
It is worth noting that ultimately, all authentication is based on one or more shared secrets. In Kerberos, those shared secrets are called keytabs, and with LDAP, MySQL and PAM for example, this is the user's password. As all authentication is based on the principle of sharing a secret, the exchange and verification of the shared secret is crucial to the architecture of an infrastructure using any of the aforementioned authentication technologies.
Authorization for a user can be separate from the authentication. For example, user john@doe.org can be authorized as john.doe@example.org, or even max.imum@example.org if necessary. Additionally, groups of users are often used as a simple way of authorizing larger numbers of users.

2.2. Functional Requirements of the (Web) Administration

TODO

2.3. Functional Requirements of the Mail Exchanger

TODO
  1. Positioning
  2. Role definition
  3. High Availability
  4. Load Balancing
  5. Efficient and cost-effective
  6. Free Software
  7. Content Filtering

2.4. Functional Requirements of the IMAP Server

TODO

2.5. Functional Requirements for the (Web) Client

TODO

Chapter 3. Kolab SMTP Access Policy

The Kolab SMTP Access Policy is a policy service for Postfix that applies mandatory recipient and sender address access controls using the Postfix SMTPD Policy.
It verifies envelope sender address used in the message against the authentication and authorization database.

3.1. What the Kolab SMTP Access Policy is

The policy service is the implementation of a fine-grained mandatory access control system, that allows delegates to be appointed authorization to use one's email address(es) as the envelope sender address for messages the delegates send, and/or allows an administrator –or individual, if you'll permit this through custom ACI– to configure a user account to be restricted access to receive from and/or send to only individual addresses, groups, group members, domain name spaces, and groups of domain name spaces.
As such, a corporate board or directors for example, may have a distribution group 'board@example.com' to which only the members of the board of directors are allowed to send messages, but no-one else.
Note that this is slightly different from a mailing list such as implemented with Majordomo or Mailman. While these technologies could require approved, subscription-based submission of messages even though in a more enhanced fashion, the subscribers list to such a mailing list is not based on LDAP group membership, organizational unit orientation, roles, queries or otherwise related to regular user provisioning and
Similarly, each of the board members may authorize assisting personal to respond to email using their own envelope sender address. Here's how that works:
Example 3.1. John Doe, the Chief Executive Officer
John has a lovely secretary called Lucy. John allows Lucy to read and write to John's Calendar, and opens up his INBOX folder to Lucy for read-only access.
John however, being a CEO and all that, tends to be unable to regularly read his email and take the time to respond. Internet is only free of charge half an hour a time, twice, at Schiphol. John would like Lucy to be able to respond on his behalf (especially to those invitations for random events a CEO has little interest in). John therefor authorizes Lucy to "send on behalf of". This is considered a Kolab Delegate -future enhancements notwithstanding.
In LDAP, this would look as follows:
dn: uid=doe,ou=People,dc=example,dc=com
cn: John Doe
(...)
mail: john.doe@example.com
(...)
kolabDelegate: uid=meier,ou=People,dc=example,dc=com
(...)

3.2. What the Kolab SMTP Access Policy is not

The Kolab SMTP Access Policy applies access control between senders and recipients on an individual, per-entity basis. It can be used to restrict an individual user from receiving from or sending to other recipients or senders, including entire domain name spaces, but it does not apply a global blacklist/whitelist mechanism.

3.3. When?

The Kolab SMTP Access Policy needs to be executed in desired points in a mail-flow.
A typical deployment executes the Kolab SMTP Access Policy upon receiving messages, or in other words, in smtpd and submission. The submission part is the most illustrative of why the Kolab SMTP Access Policy works the way it does.

3.4. Kolab SMTP Access Policy in Action During Submission

The submission of a new email by a user of Kolab Groupware has the following three interesting stages;
  1. MAIL FROM
    There is always one envelope sender address.
  2. RCPT TO
    There are one or more recipients for each message.
  3. DATA
    In the DATA SMTP protocol state, the envelope sender and all recipients are known. It is here that the Kolab SMTP Access Policy starts checking the policies that apply to the sender and recipients in one go.
Postfix allows for more and different restrictions to be configured to check the policy, but these are the interesting ones.
Using the Postfix sender restrictions allows the Kolab SMTP Access Policy to verify certain information, and otherwise block the mail early on. Note that the first policy request occurs in protocol state RCPT, and thus also the first recipient for the message is being supplied in the policy request. For the purpose of verifying the sender's authorization to use the envelope sender address access however, this is of little interest.
  • Is the sender authenticated?
  • Is the authenticated sender allowed to use the envelope sender address?
    Envelope sender addresses that a user is typically allowed to use include primary and secondary email addresses directly associated with the user's entity in the authentication and authorization database.
    Other address may include any of the email addresses the user has been made an authorized Kolab delegate for.
In case these checks are successful the Kolab SMTP Access Policy either continues with "checking" the recipient - please see notes later on.
If configured to not also check recipient (the default is to check recipients too) the Kolab SMTP Access Policy returns action DUNNO, which indicates to Postfix the policy service doesn't care about blocking nor accepting the message. Please see the notes later on for more information.
Using the Postfix recipient restrictions allows the Kolab SMTP Access Policy to aggregate all recipients to which the message is intended. The Kolab SMTP Access Policy has no interest in blocking at this stage, and will always return DUNNO.
It is not until the very last policy request in the DATA protocol state, that Postfix allows the Kolab SMTP Access Policy to iterate over the information received so far, and let's the Kolab SMTP Access Policy know the parts of the complete message submission that involves sender and one or more recipients is over.
It is therefor crucially important that the Kolab SMTP Access Policy process spawned by Postfix only exits after a complete message policy request has finished (DATA protocol state, at which all possible MAIL FROM and RCPT TO must have been submitted by the client), and it has given Postfix back to ultimate policy request result.
It is to this end, that the Kolab SMTP Access Policy reads policy requests, for as long as it can, until it reaches the DATA protocol state. Only then does the Kolab SMTP Access Policy actually check sender access policies and recipient access policies. During the RCPT TO protocol state, the policy service will return DUNNO using function ignore(_("No objections yet")).

Chapter 4. Email

This chapter addresses the email aspects of the Kolab Groupware Solution.

4.1. Content-filtering

Content-filtering is usually performed as close to the outer edge of the corporate network as possible. In reality, content-filtering is typically implemented on any or all of the following mail exchanger types, in order of likelihood;
Address content-filtering (where, when, what, enhance, control, audit, report, account).
Available Technologies
  • Amavisd
  • ClamAV
  • ClamAV Milter
  • Greylisting
  • Postfix' postscreen (version 2.8 and later)
  • Spamassassin
  • Spamassassin Milter
  • 3rd party appliances

4.1.1. Recipient Checking

As far as content-filtering is concerned, recipient address checking –verifying whether or not the recipient address exists in any of the groupware environments– is typically triggered as one of the first content-filtering defense mechanisms on an External Mail Exchanger —usually only those external mail exchangers of type Receiving.
By implementing recipient address checking as a defense mechanism too early, however, an organization exposes itself to recognaisance attacks; an attacker could, relatively quickly, discover which recipient addresses do and which do not exist.
There is a significant trade-off to implementing recipient address checking too late, however. All email could have to go through (and pass) the relatively processing intensive anti-spam and anti-virus content filters, offering an attacker opportunity to successfully execute Denial-of-Service attacks.
It is therefor strongly recommended to implement other defense mechanisms before recipient address checking is performed, such as blacklisting, greylisting, real-time DNS blacklisting and sender address and domain name space verification, and to implement recipient address checking before anti-spam and anti-virus content filtering.

4.1.2. Anti-Spam

When Kolab Groupware is configured to be responsible for anti-spam content filtering measures –the default– it will choose to use Apache's SpamAssassin software to do so.
Integration with SpamAssassin comes in different shapes and forms, depending on the technology used and the options chosen.
For example, anti-spam content filtering can be implemented inline, providing opportunity to not accept the email for delivery, inherently holding the sender MTA responsible for the non-delivery report.
Whether or not to use deployment-wide or per-user anti-spam content filtering preferences is another one of such options. This one, however, greatly impacts where exactly anti-spam content filtering may take place.
For a more complete reference to email anti-spam techniques, please see Wikipedia's article on Anti-Spam Techniques.

4.1.3. Anti-Virus

TODO

4.1.4. White- and Blacklisting

TODO

4.1.5. Greylisting

When implementing greylisting, recipient addresses are first rejected, before being accepted at a later time. To track which email has been greylisted before, and should thus be accepted when retried, a mail exchanger typically maintains an internal database recording three key pieces of information –a so-called triplet:
  1. The IP address of the sending mail exchanger,
  2. The envelope sender address,
  3. The envelope recipient address(es).
Naturally, for greylisting policies to work the internal database must also keep record of the timestamp for the delivery attempt rejected.
Greylisting requires the sender to retry delivery, which is not a RFC requirement until RFC 5321: "Simple Mail Transfer Protocol", which obsoleted RFC 821: "Simple Mail Transfer Protocol". RFC 821 had recommended (not required) retrying delivery. Older mailservers may not be in compliance with the new specifications in RFC 5321.
Greylisting introduces a delay in delivery for those "triplets" that do not have established use patterns. This may be contrary to what users expect, as most email delivery is virtually instantaneous. For greylisting to work effectively, whitelisting should be used extensively.
The former notwithstanding, trusted 3rd parties can be annotated as such by, for example, listing the 3rd party server IP addresses or DNS PTR entry record(s) (by CIDR or regex notation).

4.1.6. Real-time DNS Blacklisting

TODO

4.1.7. Sender Address Verification

TODO

4.1.8. SPF Record Enforcement

TODO

4.1.8.1. DNSSEC

TODO

4.2. Recipient Checking

recipient address checking

4.3. Integration & Interoperability

TODO

4.3.1. Pretty Good Privacy & S/MIME

Example, GPG signing without Exchange clients enabled to decrypt / verify signatures - same for S/MIME.

4.3.2. Email Routing

TODO - routing mtas as internal mtas. link with archiving and discovery. link with content-filtering. link with accounting.

4.3.3. Shared Folders

TODO - on shared folders on one groupware environment for clients configured against another groupware environment

4.3.4. Distribution Groups

TODO - distribution groups between multiple groupware environments, access control.

Chapter 5. Calendaring

This chapter addresses the calendaring aspects of the Kolab Groupware Solution.

Chapter 6. Kolab Daemon

The Kolab daemon is a multi-threaded daemon that synchronizes mutations made in the authentication and authorization database(s) with other components of a Kolab Groupware deployment.
This chapter describes how the Kolab daemon functions in detail, starting with Procedure 6.1, “Startup & Continued Operations of the Kolab Daemon”.
Procedure 6.1. Startup & Continued Operations of the Kolab Daemon
  1. Upon starting the Kolab daemon, a process kolabd obtains the primary authentication mechanism using the [kolab]/auth_mechanism setting in /etc/kolab/kolab.conf
  2. Subsequently, using the primary section related to the authentication mechanism (i.e. [ldap] or [sql]), it determines the list of (parent) domain name spaces this environment services. The Kolab daemon does so in an endless loop in the master process, and refreshes this list every 10 minutes.
    Related settings for LDAP include domain_root_dn, (kolab_)domain_filter, domain_name_attribute, domain_scope and domain_rootdn_attribute. Of impact as well, are ldap_uri, bind_dn, bind_pw.
  3. For each (parent) domain name space it finds, a new process is created. For more details on process operations, please see Procedure 6.2, “Kolab Daemon Domain Process Operations”.
  4. Processes are named after their parent domain name space's unique_attribute (entryUUID or nsuniqueid). Should a process die, it is removed from the pool of existing processes, and restarted on the next iteration of listing domains.
Procedure 6.2. Kolab Daemon Domain Process Operations
  1. Get from configuration the filter settings for the following objects, whichever applicable, and compose a single filter of them.
    Object Types
    • users,
    • groups,
    • shared folders,
    • roles,
    The configured filter is obtained by first attempting to get the 'kolab' type prefixed filter, i.e. 'kolab_user_filter', and falls back to the non-type specific filter, i.e. 'user_filter'.
    The composed search filter for users, groups and shared folders could look like:
    Example 6.1. Example users, groups and shared folders search filter
    (|(objectclass=kolabinetorgperson)(|(objectclass=kolabgroupofuniquenames)(objectclass=kolabgroupofurls))(objectclass=kolabsharedfolder))

  2. Create a search for object types relevant to domain. Here, the Kolab Daemon splits up depending on the supported controls on LDAP server technology, and the queries supported by SQL server technology.
Using the [ldap] domain_* settings, (domain_base_dn, domain_search_filter, domain_search_scope, domain_name_attribute, ...), the Kolab daemon determines the number of authentication databases for which to render service, as each domain name space may require either a switch in authn/authz technology, or different bind credentials.

Note

This functionality is currently limited to LDAP only.
To illustrate, one of its responsibilities is to make sure adding a new user is propagated in the form of a new mailbox.
The master process determines the number of domain name spaces served from different authentication and authorization sources.
For LDAP based deployments, this includes multiple domain name spaces served with different root dns.
It uses /etc/kolab/kolab.conf, section ldap, keys domain_base_dn, domain_rootdn_attribute, domain_filter, domain_name_attribute.

Chapter 7. Kolab Content Filters

Kolab Groupware ships with two content filters:
  1. Amavisd
    Amavisd is a popular, high-performance interface between an MTA and content checkers, such as anti-virus suite ClamAV and anti-spam suite SpamAssasin.
    Amavisd is commonly deployed on at least external mail exchangers, to make sure no virus and spam is received or sent out by Kolab users.
    In addition, especially within environments that run Windows clients, Amavisd is typically deployed to scan internal traffic as well, on the internal mail exchangers.

    Note

    Deploying Amavisd for virus-scanning on both the internal and external mail exchangers can cause virus-scanning to occur twice; once on the internal mail exchanger used by a Kolab user to send a message, and once on the external mail exchanger. (for outgoing messages).
    One way to circumvent the issue is to let Wallace sit in between the internal mail exchanger MTA, and the Amavisd service. Wallace can re-inject messages to be delivered locally back into the internal mail exchanger MTA, while injecting messages to be delivered remotely directly into the external mail exchanger MTA. Read more about Wallace in Section 7.1, “The Wallace Content Filter”.
    Such scenario however does not serve use-cases for messages that are sent to both internal as well as external recipients - the same message would still be scanned for virusses twice. It therefore makes no sense to split the message, and any message with any internal recipients are simply re-injected into the internal mail exchanger MTA.
  2. Wallace
    Wallace is a Kolab Groupware content filter, enabling Kolab Groupware to interrupt a message flow, perform complex and/or lengthy checks, data collection and processes, possibly altering the contents of the message's content or future flow.

7.1. The Wallace Content Filter

The Wallace content filter consists of a master framework, and a number of modules. Modules can be enabled through configuration in /etc/kolab/kolab.conf, by adding the name of the module to the comma-separated list of modules in section [wallace], key modules.
Example 7.1. Example Configuration Enabling Modules in Wallace
[kolab]
(...generic kolab settings...)

[wallace]
modules=conversations,optout
In this example, the conversations and optout modules are enabled.

For a list of modules available, please refer to Section 7.1.5, “List of Wallace Modules”.
Wallace is a multi-process, multi-threaded daemon. It runs a minimum of two processes:
  1. The first process accepts new messages and puts them in the 'incoming' queue.
    When this process starts, before this process accepts any new messages, it finds all messages inside the spool that are not already deferred (have not been deferred before), and executes the function(s) closest to the message's last known state.
  2. The second process picks up any messages in 'deferred' queues.
Wallace uses threading to allow a continuous stream of messages to be processed in parallel (rather then sequential). Each incoming message is written out to the main incoming queue, and subsequently dispatched for processing to such a thread.
Wallace uses thread throttling to prevent the application from overloading the system or any other systems and/or services the enabled modules need to consult in order to perform its job(s). The default maximum number of threads Wallace processes will spawn for each of the processes it runs is 25.

Note

The maximum number of threads per process is currently not configurable.

7.1.1. Message Flow and Processing in Wallace

A message delivered to Wallace is written to a master thread spool file in /var/spool/pykolab/wallace/. The use of tempfile.mktemp() ensures that the file created is unique.

Note

The base path used for the spool directories is currently not configurable.
For each incoming message successfully spooled to disk, Wallace creates a thread for processing. This thread is started right-away, in order to allow the master thread to continue to accept new incoming messages.
The processing thread (the thread created by the master thread in order to process an incoming message) only actually starts processing the message if the total number of threads is below the set threshold.
The processing thread, once starting to process the message, iterates over the list of modules configured.
Each module's execute function is called with the full path to the message file as a parameter, and is to return either of;
  1. A tuple containing the following:
    • (string) the module that was processing the file,
    • (string) full path to processed message file,
    When such tuple is returned, Wallace is to continue processing the message using the next module in the list of modules, if any.
    If no other modules are listed for further processing, the message is re-injected to the MTA as-is.
  2. None

7.1.2. Module Spool Directories

Modules maintain their own spool directories in order to be able to maintain state. The directory tree for a given module may look as follows:
/var/spool/pykolab/wallace/$module/
/var/spool/pykolab/wallace/$module/incoming/
/var/spool/pykolab/wallace/$module/ACCEPT/
/var/spool/pykolab/wallace/$module/DEFER/
/var/spool/pykolab/wallace/$module/DISCARD/
/var/spool/pykolab/wallace/$module/DUNNO/
/var/spool/pykolab/wallace/$module/HOLD/
/var/spool/pykolab/wallace/$module/REJECT/
This means a module is required to copy and/or move (part of) the message into the correct queue before placing a callback to Wallace. For example, when the optout is executed, the first thing it should to is pick up the message from /var/spool/pykolab/wallace/incoming/ and move the message file to /var/spool/pykolab/wallace/optout/incoming/.

7.1.3. Module API Requirements

A module requires the following in order to be eligible for execution as a Wallace module;
  • The module's (main) Python code file must live in the Wallace main directory, and have a filename that starts with module_, contains the module name, and ends with .py.
    Example 7.2. Example Wallace Module Python Code File Location
    An example location for a module named optout would be:
    /usr/lib/python2.7/site-packages/wallace/module_optout.py

  • The module file MUST contain a function init(*args, **kw).
    The init() function MUST call modules.register(module_name, execute_function[, description]), where module_name is the module name, and execute_function is the pointer to the function to execute when Wallace is to execute the module.
    Example 7.3. init() function for module optout
    def __init__():
        if not os.path.isdir(mybasepath):
            os.makedirs(mybasepath)
    
        modules.register('optout', execute, description=description())
    
    def description():
        return """Consult the opt-out service."""
    
    def execute(*args, **kw):
        (...abbreviated for clarity...)
        pass

  • The module file MUST contain a function to execute, separate from the init function. We strongly recommend calling this function execute to avoid confusion.

7.1.4. Wallace Module Interfaces

In a module's execute function, callbacks may be placed to indicate the message's processing has reached a certain state.
The following callbacks are available;
Available Wallace Module Callbacks
  • cb_action_ACCEPT(module, filepath[,final=False])
    Modules place a callback to this function to indicate they are accepting the message.
    The required parameter module is to contain the name of the module placing the callback. This allows hooks from other modules to be executed conditionally.
    The required parameter filepath is a string containing the full path to the message to be accepted.
    The optional parameter final is a boolean indicating the module's result is a final result or not. If the result is final (final == True), this callback function is to re-inject the message into the MTA for final delivery, and discard the message file. If the result is not final (final == False, the default), Wallace is to continue iterating the modules configured.
  • cb_action_DEFER(module,filepath)
    Modules place a callback to this function when a module could not successfully execute (a part of) its tasks. It is to be interpreted as a "try again later" callback.
    A callback to this function is always considered final.
  • cb_action_DISCARD(module,filepath)
    The message in filepath is to be discarded in its entirety. A callback to this function is placed when a message needs to be discarded only to allow other modules to hook in to this part of the process.
    A callback to this function is always considered final.
  • cb_action_DUNNO(module,filepath)
    A callback to this function is to indicate that the module placing the callback does not care what happens to the message in filepath. Since modules can apply rules that enable them to determine whether or not they need to be executed in full for a given message, this callback indicates that the module has found it should not be executed for the particular message.
    A callback to this function is never considered final.
  • cb_action_HOLD(module,filepath)
    A callback to this function puts the processing and delivery for the message in filepath on hold, awaiting (manual) review.
    Although Wallace will stop processing the message pending review, a callback to this function is never considered final. Review procedures could include inserting the message back into either of the configured modules, or accepting, rejecting or discarding (parts of) the message.
  • cb_action_REJECT(module,filepath)
    A callback to this function tells Wallace the message in filepath is to be rejected.
    A callback to this function is always considered final. A non-delivery report will be sent back to the original envelope sender as a result of placing a callback to this function, and the message will be discarded.

7.1.5. List of Wallace Modules

Modules for Wallace
  • bcc
    This module allows the execution of advanced, complex rules in order to determine whether a blind carbon copy (BCC) of the original message being processed needs to be sent to an alternate location, in addition to the originally intended recipient addresses.
    The module allows Wallace to conditionally send blind carbon copies based on any content, including headers, body contents and attachments, and do to so by attaching the original message to a new message, or otherwise.
    Additionally, the module provides hooks for other modules and hooks to be executed on action callbacks to again trigger sending a blind carbon copy conditional to the internal decisions and/or outcome of other modules.

    Note

    Please note that Postfix allows for lookup tables that can send a copy of a message to an additional recipient address as well. This is the preferred method to send blind carbon copies to additional recipient addresses.

    Note

    This module is not yet implemented.
  • conversations
    Organizations that consider electronic communications through Kolab Groupware subject to anti-spam laws and/or regulations, and/or want to prevent consumers from receiving electronic communications unless the conversation had been started by said consumer, could choose to enable the conversations module in order to allow messages sent from Kolab Groupware users to consumers (external recipient email addresses), which are part of a conversation initiated by said consumer.
    This module also provides hooks that other modules can use to query for existing conversations.

    Note

    This module is not yet implemented.
  • dlp
    Short for Data-Loss Prevention, this module enables Wallace to consult external, 3rd party applications, that perform checks on the contents of the message, including any attachments.
    Data-loss Prevention, in itself an ambiguous term that has little to do with loss of data, is generally applied to prevent users from leaking information that is considered private, confidential and/or proprietary. It is generally considered a protection mechanism to prevent intellectual property (copyrighted, trademarked and/or patented materials) from falling into the hands of people unauthorized to obtain such information.

    Note

    This module is not yet implemented.
  • Note

    This module is not yet implemented.
  • googletranslate
    This module enables Kolab Groupware to translate the body of a message to another language, using the Google Translate API.

    Note

    This module is not yet implemented.
  • freebusy
    The Free/Busy module can take iTip invitations, and RSVP automatically, based on a per-user policy.
    Additionally, this module allows for delegation, by copying in additional recipients of the iTip invitation.

    Note

    This module is not yet implemented.
  • optout
    Organizations that have external, 3rd party mass-mailing programs for commercial, promotional and/or marketing purposes, often allow consumers to 'opt-out' of such communications. This module allows Wallace to check a service that can consult these databases ("optout consult service", or OCS), apply business logic, and strip off the recipient email addresses that such OCS determines should not be receiving a copy of the original message.
  • resources
    When attempting to make reservations for a resource, such as a conference room, this module performs scheduling conflict detection and can automatically take action.

    Note

    This module is not yet implemented.
  • statistics
    For accounting purposes, this module can contain a variety of metadata about a message in a database.

    Note

    This module is not yet implemented.

7.1.5.1. The optout Module

The optout module for Wallace consults an external HTTP service that in turn is to determine whether or not to accept, hold or reject the message.
The optout module submits one or more POST requests to the configured URL, in succession. One request is made for each unique pair of the envelope sender address and a recipient address (meaning it iterates over the recipient addresses for the message and makes one request per recipient address). A single request contains the following information:
  • unique-message-id
    A unique identifier uniquely identifying the message.
  • envelope_sender
    The envelope sender address for the message.
  • recipient
    The recipient address.
The optout module encapsulates the payload in a JSON object.
It expects a result, again contained in a JSON object, that contains the same information as the request, and an additional "result".
A simplified example of such Opt-out Consult Service can be found at http://admin.klab.cc/~vanmeeuwen/optout/optout.phps.
The aforementioned example simply parses the recipient email address and attempts to find a particular action to take in the recipient address extension.

Note

The optout module has no purpose for results DISCARD and DUNNO, and is only interested in results ACCEPT, DEFER, HOLD and REJECT.
The optout module stores the results for all requests made, until it runs out of recipient addresses to consult the OCS for. When it is done, it splits the original message into the parts for which the result was ACCEPT, DEFER, HOLD and REJECT, if any. Each part of the message contains only the recipient addresses for which that specific action had to be taken.
Example 7.4. Opt-out Example
Using the example optout consult service available through http://admin.klab.cc/~vanmeeuwen/optout/optout.php (source code), the following is an example interation through the optout module.
  1. John.Doe@example.org sends a message with recipient address John.Doe+REJECT@example.org in the To: header, and recipient address John.Doe+ACCEPT@example.org in the CC: header.
  2. Wallace spools the message in /var/spool/pykolab/wallace/incoming/tmpASD890.
  3. Wallace executes the optout module for this message.
  4. The optout module immediately renames the message to /var/spool/pykolab/wallace/optout/incoming/tmpASD890.
  5. The optout module reads the message, and consults the OCS with the first pair. The request payload looks as follows:
    {
            "unique-message-id": "tmpASD890",
            "envelope_sender": "John.Doe@example.org",
            "recipient": "John.Doe+REJECT@example.org"
        }
  6. The OCS responds with the following result payload:
    {
            "unique-message-id": "tmpASD890",
            "envelope_sender": "John.Doe@example.org",
            "recipient": "John.Doe+REJECT@example.org",
            "result": "REJECT"
        }
  7. The optout module reads the message, and consults the OCS with the second pair. The request payload looks as follows:
    {
            "unique-message-id": "tmpASD890",
            "envelope_sender": "John.Doe@example.org",
            "recipient": "John.Doe+ACCEPT@example.org"
        }
  8. The OCS responds with the following result payload:
    {
            "unique-message-id": "tmpASD890",
            "envelope_sender": "John.Doe@example.org",
            "recipient": "John.Doe+ACCEPT@example.org",
            "result": "ACCEPT"
        }
  9. The optout module creates a new spool file /var/spool/pykolab/wallace/optout/ACCEPT/tmpQWE123 with the From: header intact, and the CC: header intact. It removes the To: header contents.
  10. The optout module calls callback function cb_action_ACCEPT('optout', /var/spool/pykolab/wallace/optout/ACCEPT/tmpQWE123).
  11. As a result, Wallace either continues with the next module, or re-injects the message into the MTA for final delivery.
  12. The optout module creates a new spool file /var/spool/pykolab/wallace/optout/REJECT/tmpGHJ456 with the From: header intact, and the To: header intact. It removes the CC: header contents.
  13. The optout module calls callback function cb_action_REJECT('optout', /var/spool/pykolab/wallace/optout/REJECT/tmpGHJ456).
  14. As a result, Wallace sends out an NDR for the message, and unlinks the message from the filesystem.

7.1.6. Configuring the Wallace Content Filter

para
Procedure 7.1. Adding Wallace After Amavisd
  • para

7.1.7. Security Enhanced Linux Considerations

Relabel port 10026 (Wallace) and port 10027 (Postfix re-injection).

Chapter 8. Kolab Objects

This chapter outlines the definition, specification and processing of objects relevant to the Kolab Groupware Solution.

8.1. Object Types

Object types are defined to distinguish objects with different, generic characteristics. In general, objects of the same type are processed similarly. Each of these object types requires a unique query definition resulting in a unique result set –or one object type will accidentally be treated as another object type.
  • Accounts
    Accounts include all accounts that are assigned to people, resources or services. The generic characteristic is that Accounts include authentication credentials.
    For example, Accounts would typically include all accounts for all people whom are to log in to a variety of services, but not Contacts.

    Not All Accounts are Kolab Accounts or Recipients

    Not all accounts are necessarily also Kolab accounts. For example, an account may simply hold the bind credentials for a service such as Postfix or Apache's HTTPd, in order for these services to be able to search for the bind distinguished name upon user login, verify authentication, and check authorization. These accounts would typically not be Kolab accounts.
    Minimal information to be included:
    1. givenName
      The account's given name, such as John, Joe or Apache.
    2. sn
      The account's surname, such as Doe, Sixpack or Webserver.
    3. cn
      The account's common name, such as John Doe, Joe Sixpack or Apache Webserver Service Account.
      Given a policy, can be composed of givenName and sn automatically.
    4. uid
      The account's user identifier, such as jdoe, jsixpack or apache.
      Given a policy, can be composed of givenName and sn automatically.

      uid MUST be unique

      Note the uid attribute MUST be globally unique on at least the most common authentication database implementations, when it is used in authentication.

      The Use of uid in Systems Not Sealed

      Also note that the uid is used as the username on systems that are not sealed, which has implications on the exact uid that can be used, as well as on the objectClasses required as well.
      Example 8.1. Example User Account using LDAP
      Suppose the following is the input:
      Given Name: John
      Surname: Doe
      The output could be, in LDIF, and implementing policies for the composition of the attributes for which no particular value has been specified:
      dn: uid=jdoe,dc=example,dc=org
      objectClass: top
      objectClass: inetOrgPerson
      objectClass: person
      objectClass: mailrecipient
      cn: Doe, John
      givenName: John
      sn: Doe
      mail: john.doe@example.org
      mailAlternateAddress: jdoe@example.org

    5. userPassword
      The account password.
    6. Base DN
      The base dn for the LDAP object, such as ou=People,dc=example,dc=org or ou=Employees,ou=Accounts,dc=example,dc=org.
      Given a configuration setting for the base dn, the location for this LDAP object is already known. If no such configuration setting is available, a location should be chosen by the administrator, or a default should be used.
    7. Naming Attribute
      Together with the base dn for the LDAP object, the naming attribute determines the full Distinguished Name for the LDAP object, such as uid=jdoe,ou=People,dc=example,dc=org or uid=jsixpack,ou=Employees,ou=Accounts,dc=example,dc=org.
      As he naming attribute is used to build the location for the LDAP object, it is commonly an attribute that is enforced to be globally unique by technology or by policy anyways.
    Optional information to be included:
    1. mail
      The email address associated with the account.
      Email Address, could be composed using recipient policy

      mail SHOULD be unique

      Certain very specific use-case exceptions notwithstanding, note the mail attribute SHOULD be globally unique.
  • Kolab Users
    Kolab users, with possibly a different base dn, search scope or filter to be used as opposed to Accounts. If not set however, should default to the same settings as Accounts.
    For example, while Accounts may be searched under ou=Accounts,dc=example,dc=org, perhaps Kolab Users are to be found under ou=Employees,ou=Accounts,dc=example,dc=org.
  • Contacts
    Contacts are mail-enabled users outside those on Kolab. Or; "A person who may be communicated with for information or assistance, esp. with regard to one's job".
  • Contact Lists
    Contact lists are different from Distribution List, in that they are considered persistent searches resulting in lists of contacts with one or more attributes in common. For example, a contact list could be composed of all people in a certain branch office. Such list then could be searched separately.
  • Domains
    As any single domain, stand-alone deployment is easily turned into a multi-domain deployment if not by simply adding a second domain name to the environment (domain alias), TODO FIXME.
  • Hosts
    TODO
    Include definition of roles in the environment, e.g. ext-mx-recv, ext-mx-send, ext-mx-trust, ext-mx-msa, ...
  • Networks
    TODO
  • Resources
    Resources include such as conference rooms, beamers, etc. They usually only include a calendar folder, and may or may not be administered by one or more users.
  • Service Accounts
    Service accounts are required for environments in which anonymous binds and searches are not allowed, and privileges are to be properly and restrictively delegated.
  • Groups
    Groups in general have a variety of purposes. Perhaps the members of the groups are to be expanded to when the group is selected in the To, CC or Bcc fields, or the group is to be used in access control in a third party, external application.
  • Distribution Groups
    Distribution groups are to be included in address books and to expand in the user's composer to its members.
  • Security Groups
    Security groups are to be used in access control within Kolab, and only as such, though naturally they may also be distribution groups.
  • Distribution List
    A distribution list is a named list, with a single recipient address, to which messages are sent and forwarded to list subscribers.
    Distribution list software includes, for example, mailman or majordomo.

Chapter 9. Authentication & Authorization

TODO

9.1. The User Supplied Login

The login username can take one of many forms:
  • user@realm
    map the realm
  • user@domain.tld
    Note that domain.tld is actually a realm in the context of authn. and authz.
  • user
    primary_domain, default realm, or something derived from other metadata (such as reverse lookup on connection IP address if available)
It is not uncommon to allow a user to login with either of a uid, mail or alias, each either qualified or unqualified (i.e. uid@domain.tld while 'uid' attribute value may only be 'uid').

9.2. LDAP

LDAP technologies typically contain a one-way hashed password in the userPassword attribute of the corresponding LDAP object. Authentication MAY be performed using any attribute that is globally unique, such as;
  • the uid attribute,
  • the Naming Attribute if enforced to be globally unique or used with search scope ONE,
  • any other attribute that is assumed and/or enforced to be globally unique and/or unique within the search scope.

9.2.1. Username & Password Authentication

The authentication routine against LDAP, when using a username and password, typically is;
Procedure 9.1. LDAP Authentication with Username & Password
  1. The client supplies its Authentication Credentials in the form of an Authentication Username and an Authentication Password.
  2. Dependent on the server-side settings, as well as the content of the Authentication Credentials supplied, the server could be configured to, amongst other things;
  3. The server issues an Mailfolder LDAP for the LDAP object using the configured Bind Credentials, Search Scope and Search Filter, and using the Distinguished Name of the LDAP object found, attempts to either bind() or fast_bind() using the distinguished name and the supplied Authentication Password.

TODO

Address fully qualified vs. unqualified, uid/mail, domain/realm. Also refer to auth mechanisms and ldap server side requirements.

9.2.2. Kerberos Authentication

TODO - since kerberos is an identity exchange protocol, and not a hmmm list of users and groups for kolab to consume, ...

9.2.3. SSL Certificate Authentication

TODO - since ssl infrastructure does not provide lists nor group authorization capabilities, kolab must have

9.2.4. Kolab & LDAP

TODO: for more information please see the integration part of this document.

9.3. PAM

TODO

9.3.1. Username & Password Authentication

TODO

9.3.2. One-Time Passwords

TODO

9.3.3. Kerberos Authentication

TODO

9.3.4. SSL Certificate Authentication

TODO - don't forget revocation lists - don't do this one

9.3.5. Kolab & PAM

TODO - getent gives listings

9.4. SASL Database

TODO

9.4.1. Username & Password Authentication

TODO

9.4.2. Kerberos Authentication

TODO

9.4.3. SSL Certificate Authentication

TODO - don't forget revocation lists

9.4.4. Kolab & SASL Database

TODO: for more information please see the integration part of this document.

9.5. SQL

TODO

9.5.1. SQL Technologies

sqlite, mysql, postgres, ...

9.5.2. Username & Password Authentication

TODO

9.5.3. Kerberos Authentication

TODO

9.5.4. SSL Certificate Authentication

TODO - don't forget revocation lists

9.5.5. Kolab & SQL

TODO: for more information please see the integration part of this document.

9.6. Password Supplements & Security

TODO

9.6.1. Simple Authentication Security Layer

TODO

9.6.1.1. PLAIN / LOGIN SASL Mechanism

TODO

9.6.1.2. CRAM-MD5 SASL Mechanism

TODO

9.6.1.3. DIGEST-MD5 SASL Mechanism

TODO

9.6.1.4. GSSAPI SASL Mechanism

TODO

9.6.1.5. (H)OTP SASL Mechanism

TODO

9.6.2. "No plain text over the wire"

TODO

9.7. Authorization Through Groups

TODO

Chapter 10. Integration & Interoperability

The following is a list of items that somehow, to some extent, relate to a groupware environment;

10.1. Authentication & Authorization

Integration and interoperability as it relates to authentication and authorization
  • technology agnosticity
  • multi-domain, multi-realm

10.2. Auditing

Integration and interoperability as it relates to auditing

10.3. Calendaring

Integration and interoperability as it relates to calendaring functionality, e.g. multiple (groupware) environments with different invitation, event definition and free/busy exchange methodologies and interfaces.
Include capabilities to integrate external calendars, e.g. Google Calendar, ...
Include capabilities to publish public and private urls to Kolab calendars, e.g. not unlike Google Calendar, ...

10.4. Email

TODO

10.4.1. Content-filtering and 3rd Party Appliances

TODO

10.5. Recipient Checking

Integration and interoperability as it relates to recipient checking, e.g. multiple source trees for available recipients throughout the environment.

10.6. SSL Certificate Infrastructure

TODO

Chapter 11. Configuration Management

Kolab Groupware includes configuration management, so that adjusting settings for your environment can be automatically deployed to the relevant configuration files, and the corresponding services can be reloaded or restarted.
To that end, Kolab Groupware employs a relational, object-oriented model.

11.1. Configuration Management Objects

  • node
    A node is a single operating system instance with a unique fully qualified domain name. It is the container for roles, as each node in a deployment can be assigned one or more roles.
    Additionally, a node is assigned an environment, in order to facilitate setups with pre-production environments.
  • role
    A role is a set of tasks to perform in a given environment. For example, a node can be an MTA, or an MTA of a particular type (internal, external).
    Adding the role "mta-internal" to a node tells the configuration management that certain packages need to be installed, certain configuration settings need to be applied to certain files, and certain services need to be started.
  • file
    A file is related to a service, and contains its configuration settings.
  • setting
    A setting is a single key-value pair of the augeas path and the desired contents. The contents can be specified as a value, or as the return value of a function to call.
    For example, the list of Cyrus IMAP administrator login names is contained within /etc/imapd.conf, setting admins. Its value is a space-separated list of login names.
    (...snip...)
    admins: cyrus-admin
    (...snip...)
    Adding a Cyrus IMAP administrator can be performed by;
    • Removing the setting from the management, and directly editing the setting in /etc/imapd.conf adding the login name for the new administrator to the space-seperated list.
    • Adding the new administrator to the list of login names returned by the function called to get to the value of the setting.
      By default, we consider a role cyrus-admins to exist in LDAP, and list the uid attribute values of the accounts with that role.
    Because a setting can contain a setting specific for a particular role, while contained within the same file, you can associate the setting with one or more roles and thereby restrict its application to nodes with these roles only.
    Additionally, settings can vary per environment. Set the environment property on a setting to only apply the setting to nodes in that environment.
  • service
    A service is a (set of) task(s) to perform in a role.
  • package
    para
  • task
    para
  • environment
    para

11.2. Kolab Configuration File

The main Kolab configuration file is /etc/kolab/kolab.conf.

TODO

This does not take into account using POSIX permissions for command-line users using the toolchain.
The format of the configuration file is the INI format, which consists of the following syntax:
[section]
; comment line

key1 = value
key2 = value
    continued value for key2
The configuration file has a mandatory section, [kolab], which controls much of the information to the base of the Kolab deployment.

11.2.1. [kolab]

The following is an overview of settings available in the [kolab] section:
  • auth_mechanism (ldap)
    The authentication and authorization database technology to use for the primary domain name space in this Kolab deployment. If not set, defaults to a value of 'ldap'.
    Possible options currently include: 'ldap'.
  • primary_domain (constants.domainname)
    The primary domain name space for this Kolab deployment. If not set, defaults to the value of the PyKolab constant domainname, which is derived from the system fully qualified domain name.
  • imap_backend (cyrus-imap)
    The IMAP backend technology used.
    Valid options currently include: cyrus-imap
  • default_quota (None)
    Default quota to apply to user mailboxes. Any integer representing a number of kilobytes will do. Defaults to 'None', which is actually to say, no default quota will be applied.
  • virtual_domains (userid)
    In which mode the IMAP 'virtual_domains' feature is enabled. Not in use yet.

11.2.2. [ldap]

The primary LDAP settings are contained within this section. The following settings are available:
  • ldap_uri (ldap://localhost:389)
    The URI to the LDAP server. Contains only the scheme ('ldap', 'ldaps'), the LDAP server connection address (an IP address or DNS name), and the port to use.
  • base_dn (None)
    This setting contains the absolute top-level that Kolab is allowed to use. While most commonly the same value as the root distinguished name (root dn) for the tree, dc=example,dc=org for example, this is not always the case.
    Despite the fact that Kolab can generate a domain-component oriented naming scheme base dn from the domain name space configured as or believed to be the primary domain, Kolab often requires the configuration of the overall base distinguished name (base dn) as LDAP trees may use a non-domain component oriented naming scheme, such as o=organization,c=nl, or use a different level of depth.
  • bind_dn (None)
    The distinguished name of the account to use for bind operations. This is part of a set of bind credentials used as a last resort only.
    If you have other, more functionally specific bind credentials configured as well, set this to the bind dn which has the least privileges (i.e. an anonymous user).
    If you have no other functionally more specific bind credentials configured, set this to the bind dn used to allow the most actions to be executed against the LDAP server, for example cn=Directory Manager.
    See Section 11.2.4, “Use of Bind Credentials” for more information on configuring functional specific bind credentials.
  • bind_pw (None)
    The password corresponding with the bind dn configured in bind_dn (None).
  • auth_attributes (mail)
    A comma- or comma-space separated list of entry attribute names of which the value is to be allowed as the login name during authentication.
    This enables an administrator to allow users to login with their entry's uid attribute value, in addition to their entry's mail attribute value.
    Common attribute names in this list include: alias, mail, mailAlternateAddress, uid.
  • quota_attribute (mailquota)
    The attribute to use for a user's mail quota.
  • mailserver_attribute (mailhost)
    The attribute to use for a user's mail server.
  • user_base_dn (%(base_dn)s)
    The base dn to use when searching for users.
    If not specified, the value of base_dn (None) is used.
  • user_filter ((objectClass=*))
    The filter to use when searching for users.
  • user_name_attribute (uid)
    The RDN attribute name (and value) to use. The value for this configuration setting should use a globally unique attribute.
  • user_scope (sub)
    The scope to use when searching for users.
  • kolab_user_base_dn (%(base_dn)s)
    The base dn to use when searching for users of type 'kolab'.
    If not specified, the value of user_base_dn (%(base_dn)s) is used.
  • kolab_user_filter ((objectClass=*))
    The filter to use when searching for users of type 'kolab'.
  • kolab_user_scope (sub)
    The scope to use when searching for users of type 'kolab'.
  • special_user_base_dn (%(base_dn)s)
    The base dn to use when searching for users of type 'special'.
  • special_user_filter ((objectClass=*))
    The filter to use when searching for users of type 'special'.
  • special_user_scope (sub)
    The scope to use when searching for users of type 'special'.
  • group_base_dn (%(base_dn)s)
    The base dn to use when searching for groups.
  • group_filter ((objectClass=*))
    The filter to use when searching for groups.
  • group_name_attribute (cn)
    The RDN attribute to use for groups. This should use a globally unique attribute.
  • group_scope (sub)
    The scope to use when searching for groups.
  • domain_base_dn (%(base_dn)s)
    The base dn to use when searching for domains.
  • domain_filter ((objectClass=*))
    The filter to use when searching for domains.
  • domain_scope (sub)
    The scope to use when searching for domains.
  • domain_name_attribute (associateddomain)
    The naming attribute for domains. Results in the first value of the list of values contained within the attribute values for a single entry to be used as the Relative Distinguished Name (RDN).
  • domain_rootdn_attribute (inetdomainbasedn)
    The attribute that contains a reference to the root dn to use for the domain.

11.2.3. A Base DN for Every Type

The configuration can hold a base distinguished name setting for every type of account or group available in the Kolab deployment.
When the configuration is used, the Kolab programs attempt to get user or group type specific settings first, and fall back onto the generic setting. When, for example, the base dn for Kolab users is needed, first the setting kolab_user_base_dn is obtained from the configuration, and should it not have been configured, it will fall back to using user_base_dn. Should that setting also not be available, the program will fall back to using base_dn.
The configuration for a particular type of user or group primarily serves large LDAP directories.

11.2.4. Use of Bind Credentials

The configuration can hold a series of bind credentials, ...;

Chapter 12. Archiving & Discovery

TODO

12.1. Methodologies for Archiving

12.1.1. Blind Carbon Copy

TODO

12.1.1.1. Deduplication with Suppress Duplicate Delivery

TODO

12.1.2. Save to Archive

TODO

12.1.3. IMAP Server Replica Client

TODO

12.1.4. Backup with Delayed Delete and Expunge

TODO

12.2. Methodologies for Discovery

12.2.1. Analysis of the Telemetry Log

TODO

12.2.2. IMAP Server Replica Client

TODO

Chapter 13. Akonadi for Integration and Caching

In introduction into using Akonadi as the integration and caching layer for server-side clients goes here.

13.1. Server-Side Akonadi Architecture Overview

Figure 13.1, “Local Akonadi Control Server Architecture Overview” provides an overview of a simple, single-server deployment with server-side Akonadi being used by the client applications Roundcube and ActiveSync.
Local Akonadi Control Server Architecture Overview
Figure 13.1. Local Akonadi Control Server Architecture Overview

Note that the storage for the Akonadi Server is the lightest of all database technologies, SQLite. Alternatively, a SQL database server can be used, as illustrated in Figure 13.4, “Multiple Networked Akonadi Control Servers Architecture”. Using a SQL database server would, at the same time, allow more than one Akonadi Control Server system to be deployed as well.
Local Akonadi Control Server Architecture with SQL Database Server
Figure 13.2. Local Akonadi Control Server Architecture with SQL Database Server

Networked Akonadi Control Server Architecture
Figure 13.3. Networked Akonadi Control Server Architecture

Multiple Networked Akonadi Control Servers Architecture
Figure 13.4. Multiple Networked Akonadi Control Servers Architecture

13.2. Procedural Descriptions

Procedure 13.1. Client Connections to Akonadi
  1. The client (Roundcube, ActiveSync) calls libakonadi API akonadi_open(username, password[, authorize_as=username][, imap_host=imap_host][, akonadi_session_id=akonadi_session_id]).
  2. On behalf of the client application, libakonadi establishes a connection to;
    1. The configured or discovered Akonadi Control Server, through a configured mechanism (AF_UNIX, AF_INET, AMQP MessageBus obtained location).
    2. The requested IMAP Server, if any.
  3. The call to akonadi_open() may be synchronous or asynchronous.
    For synchronous calls (using akonadi_open_s()), libakonadi refrains from returning a link identifier until after;
    1. It has fully established a successfully authenticated connection to the Akonadi Control Server, and the Akonadi Control Server has returned the Akonadi Session Identifier.
    2. It has fully established a successfully authenticated connection to the IMAP server, if any such had been requested.
    For asynchronous calls (using akonadi_open()), libakonadi immediately returns a link identifier. The connections to both the Akonadi Control Server and IMAP Server will be established, but will block subsequent access to synchronous calls, and/or queue subsequent asynchronous calls.
  4. The call returns a link identifier.
  5. Once the connection is established, authenticated successfully and has obtained a Session Identifier from the Akonadi Control Server, the session identifier is to be made available through API call:
    akonadi_session_id(link identifier)
Procedure 13.2. libakonadi Connections to Akonadi
  1. libakonadi, using the credentials supplied to it through the akonadi_open() call, authenticates itself to the Akonadi Control Server (ACS) using one of the credential exchange mechanisms advertised by the ACS in the initial greeting, such as PLAIN, LOGIN, CRAM-MD5, DIGEST-MD5.
    Note that we may have to consider the authentication mechanism allowed by the Akonadi Control Server to include GSSAPI and SSL certificate based authentication as well.
  2. After the connection has been successfully authenticated (and authorized, where appropriate), the ACS proxies through the connection to the Akonadi Server associated with the Akonadi Session.
Procedure 13.3. Akonadi Control Server Connection Handling
  1. Upon receiving a connection, the ACS identifies itself in a greeting (server_name) and includes its capabilities.
  2. Upon receiving an authentication request, should the authentication be successful, the ACS proxies through the connection to the Akonadi Server associated with the user account the connection is to be authorized as, or follows the following startup procedure;
    Procedure 13.4. ACS Akonadi Server and Agent Startup
    1. The client application user is associated with an Akonadi Session Identifier.
      It is NOT the client application session that is associated with an Akonadi Server.
    2. For each Akonadi Server and Akonadi Agent the ACS starts up, a public and private key-pair is generated and along with the Akonadi Session Identifier, handed over to the Akonadi Server or Agent.
    3. The private key is forgotten.
    4. The public key is maintained in a Akonadi Session Identifier.
    5. If successful, the Akonadi Session Identifier is passed back to the client (libakonadi).
    6. After initial discovery (IMAP Configuration folder), additional Akonadi Agents may need to be started up. For this procedure, please see
Procedure 13.5. Starting up Additional Akonadi Agents
  1. The following situations may cause a new Akonadi Agent to need to be started:
    • An Akonadi Agent has died unexpectedly.
    • Discovery of an IMAP Configuration folder with Kolab XML Format Configuration of secondary accounts requires new agents in order to handle said accounts (i.e. Twitter / Facebook / Gmail / ...).
    • Any other case.
    Additionally, the exchange of the original user credentials may be needed in the following scenario:
    • An Akonadi Agent has lost it's connection and no credentials had been cached, causing the agent to be unable to re-establish the connection.
  2. The exchange of user credentials happens over D-Bus.
  3. A request for the user credentials corresponding to the agent is made in a signed and encrypted fashion, sending the signed/encrypted payload containing the overall Akonadi Session Identifier over a D-Bus signal.
  4. The Akonadi Control Server responds with a signed/encrypted D-Bus signal containing the user credentials.

13.3. Notes from Design Sessions

13.3.1. Authentication to Akonadi Control Server

Authenticating to the Akonadi Control Server for each connection created by or on behalf of a client application is deemed to be the most secure, effective and standardized mechanism to establish session reliability, proxy authorization and the ability to have one client application use one set of credentials for a user over another set of credentials for a user.
Note that the client library, libakonadi needs to obtain the user credentials each time a new connection is requested, as a future direct IMAP connection can be used for interactions that are deemed more efficient to execute against the IMAP server directly, such as simple LIST and FETCH commands –for which libakonadi would be the intelligent broker.
A typical scenario for one user being able to use two or more different sets of credentials includes secondary passwords for mobile devices using ActiveSync, so loss of corporate credentials is less likely to occur.
Note that we are otherwise unlikely to be able to securely associate user session #1 in client application $x with user session #2 in client application $y passing both through to the same Akonadi Server.

13.3.2. AMQP Capabilities for libakonadi

AMQP capabilities for libakonadi would enable libakonadi to discover the Akonadi Control Server to use for the new or existing session, enabling one or more Akonadi Control Servers to be deployed with Kolab Groupware.
The underlying assumption is scaling up the concept of Akonadi Control Servers as the integration and caching layer for client applications will ultimately cause more than one Akonadi Control Server system to need to be added to the deployment.

13.3.3. AMQP Capabilities for Akonadi

AMQP capabilities for Akonadi in general would enable IMAP to push change notifications to Akonadi services including libakonadi even if that means the client library can only pick them up during the first interaction against the client application. Such notifications could include;
  • Folder change notifications (new calendar folder, folder dissappeared)
  • New and/or updated message content (update cache, Free/Busy, or more in general, act accordingly)
These notifications (from Cyrus IMAP) and notifications from Akonadi itself, can remain pending on the messagebus for libakonadi to pick up when users start interacting with client applications.
Using a push notification mechanism like this may prove crucial for ActiveSync PUSH mode, or continuously operating web application(s) (PHP FPM, FastCGI) with clients connected through web sockets.

13.3.4. libakonadi Direct IMAP Connections

In scenarios where de-duplication of data is important (i.e. many users, large mailboxes, etc.), the Akonadi Server and Agents would be configured to only obtain and insert into cache relevant metadata about folders and messages.
It is therefor assumed that, for example, a FETCH of a message is more efficiently executed against IMAP directly, and only complex queries that cannot be answered by IMAP servers efficiently are directed at the Akonadi Server.
Queries that do not need to be executed against an Akonadi Server but are very easily and very efficiently answered by an IMAP server are, for example:
  • LIST
  • LSUB
  • FETCH
The data for the aforelisted commands, which may be presumed to be among the largest amounts of data, does not need to descend client -> ACS -> AS (-> Cache -> AS) -> AA -> IMAP -> AA -> AS (-> Cache -> AS) -> client.
Commands that are more complex for the IMAP server to answer because of databases maintained on the IMAP server are less ideally suited to answer the command quickly, could include;
  • THREAD ALL UNDELETED
Commands that are complex for the client to compile an answer for because they would require a number of iterations in order to successfully compile the answer, could include;
  • All calendar items for month $x or weeek $y.
  • A list of all calendar folders (the user has write access to).

Chapter 14. Free/Busy

Free/Busy information can be generated from Event information from, or obtained from existing Free/Busy information in the following locations:
  • Kolab Groupware
    The Kolab Groupware environment –we'll call this the corporate Kolab environment.
    Each Kolab Calendar in the personal namespace may be classified as a personal or a corporate calendar (private, or work-related). That is to say, on a per calendar basis, other people within or outside of the Kolab environment may or may not be authorized to read the basic availability, or the details of each event as well.
    As a mechanism to authorize, we may use the Cyrus IMAP ACLs;
    • anonymous: l
      Allow anonymous users to view basic Free/Busy information generated from the calendaring contents of this folder.

      Security Consideration(s)

      Should the IMAP ACL be applied to the actual IMAP folder, and the IMAP server be allowed to connect to from the Internet, and the anonymous login mechanism be enabled, then everyone could lookup the existence of this IMAP folder.
    • anonymous: lr
      Allow anonymous users to view detailed Free/Busy information from the calendaring contents of this folder.

      Security Consideration(s)

      Should the IMAP ACL be applied to the actual IMAP folder, and the IMAP server be allowed to connect to from the Internet, and the anonymous login mechanism be enabled, then everyone could read the contents of this IMAP folder.
    • anyone: l
      Allow anyone authenticated to view basic Free/Busy information from the calendaring contents of this folder.
    • anyone: lr
      Allow anyone to view detailed Free/Busy information from the calendaring contents of this folder.
    • <userid>: l
      Allow the person authenticated and authorized as <userid> to view basic Free/Busy information from the calendaring contents of this folder.
    • <userid>: lr
      Allow the person authenticated and authorized as <userid> to view detailed Free/Busy information from the calendaring contents of this folder.

      Security Consideration(s)

      Note that those authorized as <userid>, using the IMAP ACLs, would actually be allowed to read the complete event message(s) contents.
    • group:<groupid>: l
      Allow individuals authenticated part of group <groupid> to view basic Free/Busy information from the calendaring contents of this folder.
    • group:<groupid>: lr
      Allow individuals authenticated part of group <groupid> to view detailed Free/Busy information from the calendaring contents of this folder.

      Security Consideration(s)

      Note that those authorized as <userid> part of group <groupid>, using the IMAP ACLs, would actually be allowed to read the complete event message(s) contents.
    To authenticate and authorize user accounts external to the Kolab Groupware environment (i.e., John's wife Jane Doe may see the corporate Free/Busy information, but no-one else may), we may choose to use a group including the contact entry for Jane Doe, for which a password has been set).
    Note that unless Jane Doe's identifier is a valid identifier to Cyrus IMAP ptloader, the ACL could not be enforced on the individual's basis.
    Note that unless the group is a valid group for Cyrus IMAP ptloader, the group ACL could not be enforced.
    Note that the Cyrus IMAP ptloader is configured using different settings than are used for authentication, as it concerns authorization.
  • Third-party Kolab Groupware
    A third-party Kolab Groupware environment, such as a private Kolab server.
    Between a private Kolab server and the corporate Kolab environment, the following options are available to the user:
    • Obtain the Free/Busy information from my private Kolab account and make it available within the corporate Kolab environment without event details.
    • Obtain the detailed Free/Busy information from my private Kolab account and make it available within the corporate Kolab environment with event details to those authorized, and without event details for those unauthorized.
  • Third-party Calendaring
    With read(/write) permissions on, for example, a Google Calendar.
    The configuration for any user's Google Calendar.
  • Third-party Free/Busy
    With read(/write) permissions on, for example, Google iCal as published.

Chapter 15. Smart Clients

Kolab Smart Clients speak standard protocols, conform to a variety of RFC specifications and implement the Kolab Groupware Information XML Storage Format as specified.

15.1. First-time Login

For smart clients that have a new Kolab account configured, and log in to the Kolab account for the first time, the following conditions may exist;
  1. The account has been used before, and contains groupware folders, in which case;
    1. The folder names may have been created using the localized name as opposed to a name suitable for the application of localization on the smart client side.
    2. The folders may have been created using a smart client that had more then one (Kolab) account configured, resulting in some groupware folder types not having a default folder for that type of groupware items.
  2. The account has been used before but does not contain all relevant groupware folders.
  3. The account has not been used before, and does not contain any folders.
The following Standard Operating Procedure has been defined.
Procedure 15.1. Smart Client First-time Login SOP
  1. Obtain the list of folders available within the user-specific namespace for the account (e.g. no shared folders from other users, nor shared folders from the shared/ namespace), along with their annotations.
  2. Determine if a default contact folder type exists. This folder would be marked with annotation /vendor/kolab/folder-type set to contact.default.
    1. If no default folder for contacts exists, and multiple folders have been marked as containing contacts, prompt the user to select the default folder for contacts.
    2. If no default folder for contacts exists, and no more then one folder has been marked as containing contacts, mark this folder as the default folder for contacts.
    3. If no default folder for contacts exists, and no folder has been marked as containing contacts, create a folder named 'Contacts' and mark this folder as the default folder for contacts.
  3. Lather, rinse and repeat for folder types event, journal, note and task.

15.2. Consecutive Operations

For the annotated folders in a Kolab account, the smart client will attempt to apply localization as if the original folder name were supplied using the en-US locale, using the target locale the smart client is supposed to operate in. Should this fail, the original folder name is to be displayed. Should this succeed, the localized folder name is to be displayed.
Should the user choose to delete the folder annotated as containing events, whether displayed as "Calendar" (en_US) or the localized "Agenda" (nl_NL), or "Kalender" (de_DE), to then create the folder "Agenda" (nl_NL) or "Kalender" (de_DE), no further localization is necessary as this has been the explicit wish of the user.
However, should a localized client be entitled to create folder names using the localized name, users may end up –by using different client configurations– with multiple groupware folders for the same type, in different localizations.

15.3. Default Groupware Folders

Groupware folders marked as default for a certain type should be treated as the default for the configured account and associated identities only, unless no other equivalent groupware folders exist on the smart client, and/or no other accounts have been configured on the smart client.

15.4. Access Control, Shared Folders and User Interaction

The smart clients will display the user friendly name configured as opposed to the value of the SASL Result Attribute or INBOX name. Additionally, smart clients will strip off qualifiers, or in other words, not display:
Other Users
    `- john
        `- Calendar@doe.org
Instead, smart clients should display:
<Localized "Other Users">
    `- <Display Name>
        `- <Localized Folder Name>
E.g., for example, should the Display Name for John be set to "Doe, John", and the user have his locale set to nl_NL;
Andere Gebruikers
    `- Doe, John
        `- Agenda
or, should the Display Name for John be set to "John Doe", and the user have his locale set to de_DE;
Andere Nutzer
    `- John Doe
        `- Kalender

15.4.1. More Advanced Display

Consider the following folder tree, sorting and displaying folders and shared folders by category:
Inbox
Calendar
    `- John Doe
Journal
    `- Max Imum
or, in locale nl_NL:
Inbox
Agenda
    `- John Doe
Dagboek
    `- Max Imum
For multiple shared folders from the same account:
Inbox
Agenda
    `- John Doe
        `- <Topic or Title>
Dagboek
    `- Max Imum

Chapter 16. Mobile Device Synchronization

TODO

16.1. SyncML

TODO

16.2. ActiveSync

TODO

Chapter 17. Administration Panel

The Kolab Groupware administration panel, a web interface to Kolab Groupware available for administrative purposes, will provide the functionality listed in this chapter.
The Kolab Groupware Web Administration Panel is split in two parts;
  1. A web client interface,
  2. An API backend interface.
The web client interface is nothing but a graphical representation of the API backend capabilities, allowing a user to navigate an interface to the administrative tasks the API backend exposes.
This design allows other system management and corporate products to trigger Kolab Groupware administration tasks on an equal footing, and without the need to (re-)implement all of the Kolab Groupware logic.

17.1. Configuration

  • Configuration of the Kolab Groupware Primary Domain
  • Configuration of the Kolab Groupware Administration Security Group
  • Configuration of Kolab Groupware Delegation Security Groups
    Including the assignment of privileges delegated to delegation security groups, including;
    • Reset Password
    • Create User, if applicable
    • Disable User, if applicable
    • (Re-)enable User, if applicable
    • Alter user attributes (common name, display name, surname), if applicable
    • Create, modify and/or delete distribution lists and/or security groups, if applicable
    • Create, modify and/or delete contact lists, if applicable
    • Create, modify and/or delete contacts, if applicable
    • Review logfiles, if applicable.
    • Create, modify and/or delete domain aliases and/or domains
    • Manage domain administrator groups

17.2. Deployment

TODO

17.3. Web Administration Panel API

The web administration panel comes with an API in order to allow different, third-party interfaces, as well as the Kolab tool-chain to Kolab Groupware, to execute tasks of an administrative nature. The API uses JSON to exchange information with the API client.
The calls to the Web API are made to a service handler, for its methods handle the request. A call therefore looks like <service>.<method>, which is a location beneath the base URL for the API.
Suppose https://kolab-admin.example.org/api/ is the API base URL, then a call to service method system.authenticate would be a POST HTTP/1.1 request to https://kolab-admin.example.org/api/system.authenticate.

17.3.1. HTTP Method Convention

Two HTTP methods are used: GET and POST. The GET method is generally(!) used for read-only operations, whereas the POST method is used for write operations.
For GET requests, the parameters (the payload) are appended to the URI requested, https://kolab-admin.example.org/api/domain.info?domain=example.org.

Note

This restricts GET requests to specifying key-value pairs of payload information only, even though a GET parameter key can be specified more then one, creating a list of values.
Some read-only operations, such as user.find_by_attributes require the request to pass along multiple attributes with, potentially, multiple search parameters. These types read-only requests are the exception to the rule of using GET for read-only requests, and use POST instead.
For POST requests, the payload is a JSON-encoded dictionary (array) of parameter keys and values. Only strings are allowed as keys. Values for the payload may contain lists, strings, dictionaries (arrays), integers, floats, etc.

17.3.2. Service and Method Naming Convention

In another rule-of-thumb we outline the naming convention for services and methods.
Service names consist of an object name either in singular or plural form. The singular form depicts actions are placed against a single instance of an object, such as object.add, or at most one result entry is expected, such as object.find.
The plural form depicts actions that are placed against multiple instances of an object, such as objects.list or objects.search, or expect zero, one or more result entries to be returned.
Method names often imply an action is placed against one or more objects in one request. Certain actions may be confusing though. For these we have the following rules;
  • Finding an object
    The method find is always executed against the service with the singular form of the object name. The target of calling a find method is to obtain exactly zero or one instance of an object. The method should fail if the result set contains any number of objects not zero or one.
  • Searching for objects
    The method search is always executed against the service with the plural form of the object name. The target of calling a search method is to obtain all matches, if any. The method should return any result set containing zero or more results.

17.3.3. Standard Response Layout

The standard response layout offers a location for the request status, an error code and the corresponding message, or a result.
The status is the first item in the JSON object. It has two possible values: OK or ERROR. Depending on the status of the request, the rest of the JSON output contains a result (OK) or the error details (ERROR).
The response to a successful request looks as follows:
{
    "status": "OK",
    "result": (...)
}
The reponse to a successful request that is expected to return a zero or one item, such as find methods, includes a result layout as follows:
{
    "status": "OK",
    "result": {
        (... entry data ...)
    }
}
The reponse to a successful request that is expected to return a list of zero, one or more items, such as list and search methods, includes a result layout as follows:
{
    "status": "OK",
    "result": {
        "list": (...),
        "count": <integer>
    }
}
A failed result however looks like:
{
    "status": "ERROR",
    "code": <integer>,
    "reason": "<string>"
}

17.3.4. Service Handlers

The following service handlers are available:
  • domain
    Domain operations, such as obtaining information for them, or adding, editing and deleting a domain.
    further description
  • domains
    short description
    further description
  • form_value
    Service handler for form values. Can be used to generate form values (such as passwords for new users), and compose form values for form fields for which the value is to be composed using existing field values from other form fields.
    further description
  • group
    short description
    further description
  • groups
    short description
    further description
  • group_types
    short description
    further description
  • resource
    short description
    further description
  • resources
    short description
    further description
  • resource_types
    short description
    further description
  • role
    short description
    further description
  • roles
    short description
    further description
  • role_types
    short description
    further description
  • system
    short description
    further description
  • user
    short description
    further description
  • users
    short description
    further description
  • user_types
    short description
    further description

17.3.5. The domain Service

The domain service makes available actions against a single domain entity, for example 'add' or 'delete'. For actions against multiple domain entities, such as 'list' and 'search', see Section 17.3.6, “The domains Service”.

17.3.5.1. domain.add Method

Depending on the technology used, quite the variety of things may need to happen when adding a domain to a Kolab Groupware deployment. This is therefore a responsbility for the API rather then the client.
Parameters
The following parameters MUST be specified with the domain.add API call:
  • associateddomain
    One or more domain name spaces to be added.
    If more than one domain name space is specified (i.e. associateddomain consists of a list or array), the remaining domain name spaces are added as aliases.
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
Example 17.1. Example domain.add API call in Python
The following is an example of a call to API service method domain.add:
import json
import httplib
import sys

from pykolab import utils

API_HOSTNAME = "kolab-admin.example.org"
API_PORT = "443"
API_SCHEME = "https"
API_BASE = "/api"

username = utils.ask_question("Login")
password = utils.ask_question("Password", password=True)

params = json.dumps({
                'username': username,
                'password': password
            })

if API_SCHEME == "http":
    conn = httplib.HTTPConnection(API_HOSTNAME, API_PORT)
elif API_SCHEME == "https":
    conn = httplib.HTTPSConnection(API_HOSTNAME, API_PORT)

conn.connect()
conn.request('POST', "%s/system.authenticate" %(API_BASE), params)
try:
    response_data = json.loads(conn.getresponse().read())
except ValueError, e:
    print e
    sys.exit(1)

# Check status here, using response_data['status']

if response_data.has_key('session_token'):
    session_id = response_data['session_token']

headers = { 'X-Session-Token': session_id }

params = json.dumps({
                'domain': utils.ask_question("Domain")
            })

conn.request('POST', "%s/domain.add" %(API_BASE), params, headers)
try:
    response_data = json.loads(conn.getresponse().read())
except ValueError, e:
    print e
    sys.exit(1)

Response
{
    "status":"OK"
}
Server-side Implementation Details
On the server-side, when a domain is added, an entry is added to the default authentication and authorization database, as configured through the setting auth_mechanism in the [kolab] section of /etc/kolab/kolab.conf.
The authentication database technology referred to has the necessary settings to determine how a new domain can be added. The related settings for LDAP are domain_base_dn, domain_scope, domain_filter, domain_name_attribute (used for the RDN to compose the DN).
After checking the domain does not already exist (using administrative credentials), the domain is added using the credentials for the logged in user. This is an access control verification step only; the logged in user must have 'add' rights on the Domain Base DN.
Additional steps when adding a (primary) domain name space is to create the databases and populate the root dn.
17.3.5.1.1. TODO
The following is a list of things that still need to be designed and/or implemented.
  • Adding an alias for a domain name space, such that "company.nl" can be specified as an alias domain name space for "company.com".
  • Designating an "owner" of a domain name space, possibly through nesting (LDAP) or assigning a owner_id (SQL).
  • Determining access to a domain name space for any particular set of credentials.
    It seems, for LDAP, the server-side getEffectiveRights control is not supported. An alternative may be to probe the root dn for the domain name space using the current session bind credentials, but this may not scale. Exceptions to the probing would need to be established to make sure the known DNs are not subjected to the extensive operation(s) (such as cn=Directory Manager).
  • Once a domain is added, we have to implement access control on top of it.

17.3.5.2. domain.delete Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.5.3. domain.edit Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.6. The domains Service

17.3.6.1. domains.list Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
The response consists of the following two toplevel keys, contained within a JSON object:
  1. status
  2. result
The result JSON object contains the following two primary keys:
  1. list
    The value represents the list of results. Languages in use today allow the counting of the list's keys, which should get a client application to be able to estimate the number of results contained within the list.
  2. count
    The value represents the total number of results, to allow for pagination on the client.

17.3.7. The form_value Service

17.3.7.1. form_value.generate Method

This API call allows access to routines that generate attribute values. It accepts data containing the names and values of other attribute values as input, which can be used to generate the new attribute value requested.
Parameters
The form_value.generate API call accepts the following parameters:
  • attribute
    The name of the attribute to generate the new value for.
  • data
    An array with key => value pairs containing the attribute name (key) and attribute value (value) to use to generate the new value for the attribute supplied in attribute.
    This parameter is required for certain attributes, such as cn, but not for other attributes, such as userPassword.
  • user_type_id
    An optional parameter to indicate to the API that the formation policy for users should be used.
    Supply an integer indicating the user type to use policies for that user type.
    Supply a boolean True to use a policy for users, allowing the use of policies not specific to any user type.
    Supply a boolean False to reject the use of any user policy.
    The default for this parameter is False.
  • group_type_id
    An optional parameter to indicate to the API that the formation policy for groups should be used.
    Supply an integer indicating the group type to use policies for that group type.
    Supply a boolean True to use a policy for groups, allowing the use of policies not specific to any group type.
    Supply a boolean False to reject the use of any group policy.
    The default for this parameter is False.

Important

The API call does not allow both the user_type_id and group_type_id to;
  • both be boolean False,
  • both be boolean True,
  • both be an integer reference to each respective type ID.
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
A client could choose to have a user's password generated by the API.
Example 17.2. Generate the User Password with the API
result = request('POST', 'form_value.generate_userpassword')
print result['userpassword']

Response
{
        "status": "OK",
        "result": {
                "password": "3SQLAdcW_KZL5vO"
            }
    }

17.3.7.2. form_value.list_options Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.7.3. form_value.validate Method

para
This API call allows access to routines that generate attribute values. It accepts data containing the names and values of other attribute values as input, which can be used to generate the new attribute value requested.
Parameters
The form_value.validate API call accepts the following parameters:
  • attribute
    The name of the attribute to validate the value for.
  • data
    The data to validate.
  • user_type_id
    An optional parameter to indicate to the API that the validation policy for users should be used.
    Supply an integer indicating the user type to use policies for that user type.
    Supply a boolean True to use a policy for users, allowing the use of policies not specific to any user type.
    Supply a boolean False to reject the use of any user policy.
    The default for this parameter is False.
  • group_type_id
    An optional parameter to indicate to the API that the validation policy for groups should be used.
    Supply an integer indicating the group type to use policies for that group type.
    Supply a boolean True to use a policy for groups, allowing the use of policies not specific to any group type.
    Supply a boolean False to reject the use of any group policy.
    The default for this parameter is False.

Important

The API call does not allow both the user_type_id and group_type_id to;
  • both be boolean False,
  • both be boolean True,
  • both be an integer reference to each respective type ID.
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.8. The group Service

17.3.8.1. group.info Method

para
Parameters
The following parameters are required:
  • group
    The group to return information for.

    Currently, we only allow the group to be searched by the email address associated with the group.

HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Response
{
        "status": "OK",
        "result": {
                "cn": "sysadmin-main",
                "objectclass": [
                        "top",
                        "groupofuniquenames",
                        "kolabgroupofuniquenames",
                        "posixgroup"
                    ],
                "gidnumber": "666",
                "uniquemember": [
                        "uid=vanmeeuwen,ou=people,dc=klab,dc=cc",
                        "uid=adomaitis,ou=people,dc=klab,dc=cc"
                    ],
                "mail":"sysadmin-main@klab.cc",
                "type_id":3,
                "id":"adf3ce81-088311e1-98bcc2f1-b2ae40b4"
            }
    }

17.3.8.2. group.members_list Method

The group.members_list service method lists the members of a group.
Parameters
The following parameters are required:
  • group
    The group to list the members for.
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
The response consists of the following two toplevel keys, contained within a JSON object:
  1. status
  2. result
The result JSON object contains the following two primary keys:
  1. list
    The value represents the list of results. Languages in use today allow the counting of the list's keys, which should get a client application to be able to estimate the number of results contained within the list.
  2. count
    The value represents the total number of results, to allow for pagination on the client.

17.3.9. The system Service

17.3.9.1. system.authenticate Method

Successful authentication is a prerequisite in order to be able to execute any other action against the system. Upon success, the system.authenticate API call returns a session token that MUST be supplied with all subsequent requests for the session, through the HTTP header X-Session-Token.
Parameters
The following parameters MUST be supplied with a call to system.authenticate:
The following parameters MAY be supplied with a call to system.authenticate:
  • domain
    With supplying the domain parameter in an authentication request,
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
Example 17.3. Example system.authenticate API call in Python
The following is an example of authentication against the API in Python:
import json
import httplib
import sys

from pykolab import utils

API_HOSTNAME = "kolab-admin.example.org"
API_PORT = "443"
API_SCHEME = "https"
API_BASE = "/api"

username = utils.ask_question("Login")
password = utils.ask_question("Password", password=True)

params = json.dumps({
                'username': username,
                'password': password
            })

if API_SCHEME == "http":
    conn = httplib.HTTPConnection(API_HOSTNAME, API_PORT)
elif API_SCHEME == "https":
    conn = httplib.HTTPSConnection(API_HOSTNAME, API_PORT)

conn.connect()
conn.request('POST', "%s/system.authenticate" %(API_BASE), params)
try:
    response_data = json.loads(conn.getresponse().read())
except ValueError, e:
    print e
    sys.exit(1)

# Check status here, using response_data['status']

if response_data.has_key('result'):
    if response_data['result'].has_key('session_token'):
        session_id = response_data['result']['session_token']

Response
The following is a response to a successful authentication request (with inserted line-breaks for readability):
{
    "status":"OK",
    "result": {
        "user":"cn=Directory Manager",
        "domain":"klab.cc",
        "session_token":"ndgu4ennb6t51i4b0dvkulhvk6"
    }
}
The following is a reponse to an unsuccessful call to system.authenticate (with inserted line-breaks for readability):
{
    "status":"ERROR",
    "code":500,
    "reason":"Internal error"
}

17.3.9.2. system.capabilities Method

For all service handlers registered, a method capabilities can be executed listing the methods available and access to them. The system.capabilities API call lists all of the registered service handlers' methods and access.
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.9.3. system.get_domain Method

The get_domain method returns the currently selected working domain.
Parameters
No parameters are available for this method.
HTTP Method(s)
GET, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
Example 17.4. Example system.get_domain API call in Python
The following is an example of a call to API service method system.get_domain:
import json
import httplib
import sys

from pykolab import utils

API_HOSTNAME = "kolab-admin.example.org"
API_PORT = "443"
API_SCHEME = "https"
API_BASE = "/api"

username = utils.ask_question("Login")
password = utils.ask_question("Password", password=True)

params = json.dumps({
                'username': username,
                'password': password
            })

if API_SCHEME == "http":
    conn = httplib.HTTPConnection(API_HOSTNAME, API_PORT)
elif API_SCHEME == "https":
    conn = httplib.HTTPSConnection(API_HOSTNAME, API_PORT)

conn.connect()
conn.request('POST', "%s/system.authenticate" %(API_BASE), params)
try:
    response_data = json.loads(conn.getresponse().read())
except ValueError, e:
    print e
    sys.exit(1)

# Check status here, using response_data['status']

if response_data.has_key('session_token'):
    session_id = response_data['session_token']

headers = { 'X-Session-Token': session_id }

conn.request('GET', "%s/system.get_domain" %(API_BASE), params, headers)
try:
    response_data = json.loads(conn.getresponse().read())
except ValueError, e:
    print e
    sys.exit(1)

Response
{
    "status":"OK",
    "result": {
        "domain":"example.org"
    }
}

17.3.9.4. system.quit Method

The quit method ends the session.
Parameters
params
HTTP Method(s)
GET, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.9.5. system.select_domain Method

Select the domain supplied as the current working domain. By default, users are logged in and have access to what they are authorized for in their own domain name space only. Certain users, such as cn=Directory Manager, have access to all domains. This API call allows such users to select the domain name space they are currently working on.
Parameters
params: domain name
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para
Server-side Implementation Details
On the server-side, when system.select_domain is called successfully, the selected domain is stored in $_SESSION['user']->current_domain. This is a private property, however, and the rest of the code is to use the public function $_SESSION['user']->get_domain():

17.3.10. The user Service

The user service ...

17.3.10.1. user.add Method

Parameters
A required parameter is the user_type_id (obtain from user_types.list). Further required parameters are the keys of the form_fields array for the user type with that id.
Example 17.5. Example set of required parameters
A simple user type could look as follows:
$id = 1;
$key = 'simple';
$description = 'A simple user type';
$attributes = Array(
        'auto_form_fields' => Array(),
        'form_fields' => Array(
                'cn' => Array(),
                'mail' => Array(),
            ),
        'fields' => Array(
                'objectclass' => Array(
                        'top'
                        'inetorgperson'
                    ),
            ),
    );
Additional required parameters for this user type (with ID 1) would include cn and mail.

Note

Note that keys of the array auto_form_fields may be submitted, but are honored only if admin_auto_fields_rw is set to true or 1. If this setting is not specified (the default), form field values are re-generated. The client interface should have disabled input for these form fields.
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
headers = { 'X-Session-Token': <token> }
params = { 'cn': 'John Doe', 'mail': 'john.doe@example.org' }
request('POST', 'user.add', params, headers)
Response
para

17.3.10.2. user.delete Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.10.3. user.disable Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.10.4. user.edit Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.10.5. user.enable Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.10.6. user.info Method

para
Parameters
The following parameter(s) MUST be supplied with a call to user.info:
  • user
    A string allowing the user the information needs to be obtained for to be uniquely identified.

    Note

    Currently, only the 'entryDN' and 'mail' attribute values are allowed as the username for an authentication request.
HTTP Method(s)
GET, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
The response to a user.info API call contains all information to a particular entry in the authentication and authorization database technology, that can be obtained using the bind credentials for the session user.
The output is normalized for abstraction, and looks as follows, with added line-breaks for clarity:
{
    u'status': 'OK',
    u'uid=vanmeeuwen,ou=People,dc=klab,dc=cc': {
            u'mailalternateaddress': [
                    u'vanmeeuwen@klab.cc',
                    u'j.vanmeeuwen@klab.cc'
                ],
            u'displayname': u'van Meeuwen, Jeroen',
            u'uid': u'vanmeeuwen',
            u'mailhost': u'imap.klab.cc',
            u'objectclass': [
                    u'top',
                    u'person',
                    u'inetOrgPerson',
                    u'organizationalPerson',
                    u'mailrecipient',
                    u'kolabInetOrgPerson',
                    u'posixAccount'
                ],
            u'loginshell': u'/bin/bash',
            u'userpassword': u'{SSHA}yGEm7rdOSrTDCd/h4F5q1fx5GTvSynHU',
            u'uidnumber': u'500',
            u'modifiersname': u'cn=directory manager',
            u'modifytimestamp': u'20111206153131Z',
            u'preferredlanguage': u'en_US',
            u'gidnumber': u'500',
            u'createtimestamp': u'20111119171559Z',
            u'sn': u'van Meeuwen',
            u'homedirectory': u'/home/vanmeeuwen',
            u'mail': u'jeroen.vanmeeuwen@klab.cc',
            u'givenname': u'Jeroen',
            u'creatorsname': u'cn=directory manager',
            u'cn': u'Jeroen van Meeuwen'
        }
}

17.3.10.7. user.search Method

para
Parameters
params
HTTP Method(s)
GET, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.11. The user_types Service

The user_types service ...

17.3.11.1. user_types.add Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.11.2. user_types.delete Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.11.3. user_types.edit Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

17.3.11.4. user_types.list Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
The response consists of the following two toplevel keys, contained within a JSON object:
  1. status
  2. result
The result JSON object contains the following two primary keys:
  1. list
    The value represents the list of results. Languages in use today allow the counting of the list's keys, which should get a client application to be able to estimate the number of results contained within the list.
  2. count
    The value represents the total number of results, to allow for pagination on the client.

17.3.11.5. Storage Format for user_type

The user types are backed by database entries, containing the following attributes per user type:
  • id
    Of type INT, this attribute is automatically assigned by the database backend, unless specifically supplied on insert.
  • key
    Of type VARCHAR(16), the key attribute is to hold a machine readable name.
  • name
    Of type VARCHAR(128), the name attribute is to be the human-readable name for the user type.
  • description
    Of type VARCHAR(256), the description attribute holds the description for the user type.
  • attributes
    Of type TEXT, the attributes contains a serialized JSON object with the information needed for the API and client interface to build queries and forms for the user type.
17.3.11.5.1. The attributes Attribute Value Format
The structure of the attributes attribute value is:
Array(
        "<form_field_type>" => Array(
                "<form_field_name>" => Array(
                            ['data' => Array(
                                    "<form_field_name>"[,
                                    "<form_field_name>"[,
                                    "<form_field_name>"],]
                                ),]
                            ['type' => "text|select|multiselect|...",]
                            ['values' => Array(
                                    "<value1>"[,
                                    "<value1>"[,
                                    "<value1>"],]
                                ),]
                    )
            )
    )
The attributes attribute to a user_type entry holds an array with any or all of the following <form_field_type> keys:
  • auto_form_fields
    The auto_form_fields key holds an array of form fields that correspond with attributes for which the value is to be generated automatically, using an API call.
    The key name for each key => value pair indicates the form field name for which the value is to be generated automatically.
    Each array key corresponds with a user attribute name, and it's value is an array containing the name of the form fields for which the value to submit as part of the API call.
    Example 17.6. A User's displayname
    Provided the user type's auto_form_fields contains an array key of displayname, the array value for this key could look as follows:
    Array(
            'auto_form_fields' => Array(
                    'displayname' => Array(
                            'data' => Array(
                                    'givenname',
                                    'sn'
                                ),
                        ),
                    (...)
                ),
            (...)
        );
    This indicates to the client that a form field named 'displayname' is to be populated with the information contained within the form fields named 'givenname' and 'sn'.
    If the client is capable of doing so, it should also update the form field named 'displayname' after the values for any of the form fields named 'givenname' or 'sn' have been changed.

    With a JSON object payload containing the values of the form fields for which the names are contained within the 'data' key, if any, the client should submit a POST request on change of these form fields, and will be returned the new value for the automatically generated form field.
  • form_fields
    The form_fields key holds an array of form fields that require user input.
    The key name for each key => value pair indicates the form field name for which the value is to be supplied by the user.
    Because some attributes can be multi-valued, or have a limited list of options, each defined form field in form_fields can hold an array with additional key => value pairs illustrating the type of form field that should be used, and what format to expect the result value in.
    Additional Information in form_fields
    • maxlength
      For a form field of type text or type list, this value holds the maximum length for a given item.
    • type
      The type is to indicate the type of form field. Options include;
      • text
        This is a regular input field of type text.
        This is the default.
        Additional parameters for a text form field include maxlength.
      • list
        A form field of type list is expecting a list of text input values.
        A client web interface could choose to display a textarea with the instructions to supply one item per line, or more advanced (better) equivalents, such as an add/delete widget.
        A client command-line interface could choose to prompt for input values until an empty value is supplied.
        Additional parameters for a list form field include maxlength, which holds the maximum length of each text value in the list.
      • multiselect
        This form field is a select list, where multiple options may be selected (as opposed to a select list, where only one option may be selected).
        A client interface MUST consult the form_value.list_options API call for options, described in Section 17.3.7.2, “form_value.list_options Method”.
      • select
        This form field is a selection list, of which one option may be selected.
        A client interface MUST consult the form_value.list_options API call for options, described in Section 17.3.7.2, “form_value.list_options Method”.
    • value_source
      para
    • values
      para
  • fields
    The fields key holds an array of form fields and values for said form fields, that are static. One example of such form fields is objectclass.

17.3.12. The users Service

The users service ...

17.3.12.1. users.list Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
The response consists of the following two toplevel keys, contained within a JSON object:
  1. status
  2. result
The result JSON object contains the following two primary keys:
  1. list
    The value represents the list of results. Languages in use today allow the counting of the list's keys, which should get a client application to be able to estimate the number of results contained within the list.
  2. count
    The value represents the total number of results, to allow for pagination on the client.

17.3.12.2. users.search Method

para
Parameters
params
HTTP Method(s)
POST, with an X-Session-Token HTTP/1.1 header.
Example Client Implementation
para
Response
para

Chapter 18. Enforcing Entitlements

Kolab Groupware is distributed in two different product streams. The community edition is the edition that is supported by the community only, and the enterprise edition, that prior to release has been subject to the necessary Quality Assurance, and is supported by Kolab Systems, for a longer term more appropriate for most businesses, to an extent dependent on the type of Service Level Agreement purchased.
Both product streams however are Free Software entirely. The enterprise edition however has restrictions, and is supported only for such and so many users, systems, domains, mailboxes, groups, and other groupware functionality, again depending on the type of Service Level Agreement that has been purchased.
This chapter explains how Kolab Systems enforces entitlements using the enterprise version of its software.
It is commonly understood that for Free Software to be released in a fashion that allows the enforcing of entitlements, a version must be released that either;
  1. Itself contains information that allows the program to verify entitlements given a license file. Such program would need to be binary compiled, randomized, and contain a key to unlock the lock on the license file. More importantly, however, the program would need to be proprietary (the Zarafa mechanism).
  2. Phone home, to verify its current status is within the boundaries configured for it, against a piece of infrastructure controlled by the vendor (the Red Hat Network mechanism).
At Kolab Systems, we don't like either of these options. We have come up with a solution that allows the software to remain Free Software, without requiring systems that have Kolab installed to need to phone home.

18.1. Software Repositories Behind Lock and Key

First, we create software repositories in a location that requires the consumer to have been issued a key to the lock. We do this through an SSL certificate infrastructure, for which each consumer that we provide access to the repositories is issued with an SSL Client Certificate.
This guarantees us anyone with access to the software repositories (for installation, but for updates as well) is a known customer, and has been issued a certificate with an expiry date, that we can revoke.

18.2. Entitlements Files

Example entitlements could be, the number of users or groups supported within a Kolab Groupware environment. The information for all of a customer's support entitlement purchases is contained within an entitlements file, which can be supplemented with more entitlements files so that the entitlements can be added up and thus easily extended.

18.3. Issuing Entitlement Files

Knowing each of the customer systems contains a Certificate Authority file, and an SSL Client Certificate, as otherwise the system would not have access to the software repositories for important updates, we can use these existing components to sign and encrypt an entitlement file specific to the customer.
  1. First, we sign the entitlement file using a Certificate Authority certificate, the same one used to issue and sign the SSL Client Certificate.
  2. Second, we encrypt the entitlement file using the SSL Client certificate we have issued to the customer.
This guarantees that the only those can read the contents of the entitlements file, that have obtained the SSL Client Certificate, for which we can verify the signature on the entitlements file.

18.4. Implementing Enforcement

The entire infrastructure can be replicated, by anyone, if all the information the system would have is a Certificate Authority, an SSL Client Certificate, and a signed and encrypted entitlements file. It may be relatively hard to reverse engineer the exact contents of the entitlements file, and update the binary compiled code to accept a new set of certificates, but it is certainly possible to achieve.
Therefor, the components that can enforce the entitlements (for example, the Kolab Daemon) can contain information about the certificates used in the SSL infrastructure. Not to function as a key to a lock, however, but to verify the other information available checks out against what it expects.
It is safe for software to contain such information, as it is not leaking any information that is not already known to the outside world. However the trick is to not allow this information to be altered or tampered with. More to the point, the trick is to not allow this information to be altered or tampered with in a way that can not be detected.
Our enterprise edition therefor ships a binary compiled version of the software that contains this information, so that checksums can be verified upon every support request, and to make it harder to both alter the codebase as well as maintain a patch-set.
Of course, it is relatively easy to write down any checksums for files right after installation, and run one's own version. However, running one's own version is still detectable through backtraces, and stack traces. If these are reproduced using an original version of the code, then the support issue is legitimate even if the day-to-day code running the environment is not the same.

Chapter 19. Migration

TODO

Terminology

Authentication Credentials
TODO
Authentication Domain
TODO
Authentication Password
TODO
Authentication Realm
TODO
Authentication Service Name
TODO
Authentication Username
TODO
Base DN
An LDAP Base DN, as opposed to the LDAP Root DN is the start position of an LDAP Search operation.
The search results will be limited to LDAP objects residing at or under the nesting level of the Base DN. A list of LDAP objects in ou=People,dc=example,dc=org can thus easily be obtained using the Base DN to restrict the search:
$ ldapsearch -x -b "ou=People,dc=example,dc=org"
Domain Base DN
The base dn used for domain name spaces.
Bind Credentials
Bind credentials are used with LDAP to elevate privileges beyond those typically associated with the term anonymous. Bind credentials usually add certain additional privileges to the connection, such as the modification of one's self attributes, possibly including one's LDAP object userPassword attribute.
Privileges associated with bind credentials can also make sure restrictions applied to normal users do not apply to service users. In large LDAP directory trees for example, Virtual List View Control can be used to browse the directory, and the credentials used by services may have been authorized to use the corresponding indexes and searches. Also, the LDAP object associated with the service's bind credentials may have been configured with a different search limit and/or search timeout.
Most LDAP implementations have specific Bind Credentials dedicated to server administration, often called Directory Manager, admin or, in case of OpenLDAP, confusingly rootdn referring to the Distinguished Name with 'root' privileges rather then the Root DN.
Distinguished Name
TODO
External Mail Exchanger
External Mail Exchangers are Internet facing mail exchangers. In other words, they send and/or receive mail to and/or from the Internet. Four sub-types (roles) exist for external mail exchangers: Receiving, Sending, Submission and Trusted.

Combined Roles

While an external mail exchanger is assigned at least one role, no one role is mutually exclusive with any other role. As such, all roles may be combined in to one or more external mail exchangers.
Additionally, the External Mail Exchanger role can be combined with the Internal Mail Exchanger role.

FIXME

The list below should be an ordered list, but Publican –at the time of this writing– does not align the formalpara title correctly.
External Mail Exchanger Types
  • Receiving
    External mail exchangers of type receiving receive email from the Internet, possibly including –not limited to– specific configuration reflecting;
    1. the corporate content-filtering policies,
    2. firewall configuration,
    3. archiving and discovery policies,
    4. ...
  • Sending
    External mail exchangers of type sending send email to the Internet, typically from known senders only, employing different policies including those for content-filtering.
  • Submission
    External mail exchangers of type submission are used by smart clients to submit email through the corporate infrastructure, to enable recipient mail exchangers to verify the canonical source of the sender email address and mail exchanger IP address and/or hostname against blacklists, whitelists, real-time DNS blacklists, greylists, SPF records and other content-filtering technologies employed at the receiving end.
    External mail exchangers of type submission include a Mail Submission Agent process listening on port 587/tcp (msa), enabling users with smart clients to circumvent the all too common restrictions on the usage of port 25/tcp (smtp) by many ISPs. These external mail exchangers have the Mail Submission Agent listener exposed to the Internet, and to prevent abuse require authentication before accepting the submission of email. Additionally, these MSA listener processes often require the use of Transport Layer Security (TLS).
  • Trusted
    External mail exchangers of type trusted have been configured to relay certain email to specific hosts, that may or may not be referred to as a mail exchangers for the given domain name space by traditional DNS. A scenario implementing this type of mail exchanger would typically have a two-way trust relationship with a third party.
    Example A.1. Two-way Organizational Trust Relationship Example
    A dedicated procurement provider may send and receive confidential information transported from one end to the other using email, and to that end be connected to the corporate (IP-)VPN through an external, dedicated (IP-)VPN cloud. The provider's receiving mail exchangers may, as such, not be listed as mail exchangers in any existing, available DNS zone, and require an explicit relay host entry in the configured transport for the consumer's external mail exchanger MTA(s).

Fully Qualified User Identifier
TODO
See also:
Internal Mail Exchanger
TODO
Kolab Groupware Primary Domain
All Kolab Groupware deployments require a primary domain name, used to form valid recipient email addresses with. The Kolab Groupware Primary Domain represents the primary domain name space for which the groupware deployment runs. Without such domain name space, no user would be able to send or receive email messages to or from the outside world (the Internet).
LDAP Access Control
TODO
Additionally, the results of an LDAP Search are subject to;
Mailbox
A mailbox is essentially a special type of mailfolder, as it is a top-level mail folder. The only level higher then the mailbox name is the prefix (user, shared, DELETED or news). For users, the mailbox corresponds with the user's INBOX. The first level of shared folders however does not truly correspond with a type of special folder like the user's INBOX does.
Mailfolder
TODO / Contrary to a mailbox, a mailfolder can be anywhere
Naming Attribute
TODO
Relative Distinguished Name
TODO
Root DN
TODO
Search Filter
TODO
Search Scope
Three search scopes exist:
  1. base
  2. one
  3. sub
Transport Layer Security (TLS)
TODO
Virtual List View Control
TODO
Unqualified User Identifier
TODO

Feature FAQ

Kolab Groupware receives many feature requests, questions about features, and questions as to whether one or the other thing would be possible.
This appendix answers, or at least gives some insight, on the questions asked most frequently regarding features and integration.

B.1. What Kolab Groupware Is (Not)

A couple of questions can be answered relatively quickly, by explaining what Kolab Groupware is, and what it is not.
Kolab Groupware provides the glue between a variety of components that enable users to electronically communicate through email, and manage their lives by providing Calendaring, Tasks, Notes and Journals. It also provides Address Books with specifically individual contact records and distribution lists.
It is not a document management system, not a work-flow management system, not an audio- nor video-communication platform, and does not include instant messaging nor microblogging capabilities.
That said, Kolab Groupware can be extended to include the functionality provided by third party applications.

B.2. Detailed Questions

Does Kolab have some sort of a centralized Address Book?
Kolab Groupware is strongly LDAP-based. For groups of users and organizations alike, including Kolab Groupware deployments for family, small, medium and large enterprises, LDAP often contains much of the information needed for a Global Address Book.
The information eligible to be contained within LDAP is tremendous, but Kolab Groupware also includes so-called Contact folders, which contain contacts. Since these folders are available over IMAP, they can be shared and restricted access to just like any other IMAP folder. At your option, you can create and maintain several address books, each (possibly) available to different groups of people.
Can I Import / Export data into/from Kolab?
Import and export of the data contained within Kolab Groupware is perfectly possible, as it storage format is Open. Our clients include interfaces for data to be imported into and/or exported from Kolab.
Can I have external sources for Contacts?
TDB.
Think Akonadi (server-side, client-side), SugarCRM connectors, Kolab, CardDAV, external directory trees (to import / synchronize with).
As a user, can I mark contacts as favorites?
TBD.
Can I mark contacts as favorite for groups of users?
TBD.
Does Kolab allow for context-aware integration of contacts into documents?
TBD.
There's currently no Free Software document editing software with an interface to integrate Kolab contacts (or other sources of contacts for that matter), let alone context-aware.
This seems to be an OLE based, Microsoft Active Directory and Microsoft Office specific feature.
Think Calligra w/ Nepomuk, or extending LibreOffice w/ plugin.
Can I search contacts with Kolab?
Yes.
Does Kolab allow me to define, enforce and provide forms for pre-defined and/or ad-hoc processes, procedures or workflows?
TBD.
Additionally, requests have been made to have workflow management include digital signatures for approval, and prevent the use of media other then digital - at least until processes have been completed.
Kolab should examine the opportunities to integrate these solutions.
Does Kolab allow to display a work-flow (in some digestible sense)?
TBD.
As mentioned before, Kolab does not do workflow management and may need an external application to provide such capabilities - it is therefore also the external application that would need to provide said functionality.
Can I have a personalized portal to the Groupware environment / contents / applications?
TDB.
Kontact allows for the customization of one's Summary page, as does Horde allow the user to position and add/remove widgets on it's main page. Roundcube however does not allow for such configuration, and perhaps nor does Kontact Touch.
Additional thoughts:
  • Display divisions by context and/or content, not application.
  • Links to actual documents instead of copies. Think also Document Management Systems. De-duplication.
Can I send electronic messages with Kolab?
Yes.
Can I attach files to electronic messages I send using/through/to/from Kolab?
Yes.
Is the layout for messages preserved when I send electronic messages using/through/to/from Kolab?
Yes.
Can Kolab issue signals for events that occur?
TBD.
Kolab 3.0 can issue signals for events that occur in IMAP, and will be able to issue signals for events that happen in its various server-side components as well.
Can Kolab ensure the creation of unique documents?
TBD.
Kolab is not a document editor (suite). It requires other components to do document creation and editing. It's possible ensuring the creation of unique documents is something best left to yet another component than is document creation/editing.
Can Kolab create, maintain and provide version control, change history and/or locks on documents?
TBD.
Kolab Groupware is not, nor does it currently integrate with, document creation/editing software nor management systems.
Can Kolab process, archive, secure documents, and provide an interface to such archive, if any?
TBD.
Kolab Groupware can process and archive contents contained within IMAP. As illustrated before, Kolab Groupware does not currently provide interfaces to nor integration with document creation/editing software, nor document management systems, and as such does also not currently process, archive nor have an interface to that data.
Does Kolab allow me to define a free structure in which to contain data?
Yes.
Using IMAP folders the possibilities are endless.
Can Kolab de-duplicate data (attachments, documents) across structures?
TBD.
The only de-duplication currently available is on initial message delivery (to the same IMAP server).
Can Kolab provide secure storage for sensitive data?
Yes.
Think SELinux, private annotations.
Does Kolab provide an interface to previously deleted email?
At your option, Kolab Groupware can be made to delete data from disk only after a certain period of time, including eternity.
Currently no interface exists that discloses the information on disk to a user.
We seek to implement Excellent Archiving and e-Discovery for this purpose (already named "Bonnie") instead.
Does Kolab provide integration of data sources, work-spaces and/or applications?
TBD.
Does Kolab provide the user with Calendaring?
Yes.
One or more calendar is available to the user, permissions can be set on each calendar individually.
In Kolab 3.0, calendars and events contained within each calendar can be displayed in Free/Busy under configurable conditions.
Can all users in Kolab see the calendars of all other users?
At your option, this can be made to happen. A user individually could set their calendar to be available to one or more users, one or more groups, or anyone authenticated to the system, provided they are permitted to 'administer' the calendar. The rights to edit access control on a folder could also be revoked, applying what could arguably be called 'mandatory access control'.
Can I restrict access to Calendars in Kolab?
Yes.
Can I mark events as private in Kolab?
Yes.
Kolab 3.0 can actually make the event details unreadable to other users, literally, while other groupware solutions have its clients respect a private flag (the data can still be read if the client only chooses to ignore the flag).
Can I have Calendars for groups in Kolab?
Yes.
How scalable are "Public Folders" or "Shared Folders" in Kolab Groupware?
As public folders or shared folders can be spread across multiple servers, there's no restriction on the number of, or size of, or number of transactions per second against, public or shared folders (other then int64_t).
Can I syncronize one Calendar with another Calendar?
TBD.
What is the use-case here? Read-only access is insufficient? Perhaps the number of calendars would otherwise convulate one's interface. We have no read-only nor linked (copied) events within a read-write calendar folder.
Is the Calendaring integrated into Kolab Groupware client interfaces?
Yes.
The way Kolab Groupware stores information related to events is through attachments contained within the same RFC822 message as the event. It currently has no linking / reference capabilities (to data contained within nor external to Kolab Groupware).
Does Kolab provide task management?
Yes.
Think basic Kolab Tasks folders containing individual tasks with sub-tasks, each of which can have an assignee, without or without \Seen state maintained in a fashion shared across all users, IMAP access control, etc.
For Kolab 3.0, also think Zanshin, conversations (and thus project management - but no reporting).
Can Task management be performed within Groups?
Yes.
Whether users are eligible to read/write tasks is (currently) a matter of IMAP folder permissions, not whether the user is the actual creator/assignee of any of the tasks contained within such a folder.
Read permissions on the IMAP folder currently include disclosure of the full task details. Think private annotations to render a Task private, though, but such happens on an individual user basis (i.e. not per permission group).
Can I structure tasks to have sub-tasks?
Yes.
Can I make one task depend on one or more other tasks?
TBD.
Does the task management allow for (estimated) durations / due dates / deadlines / reminders?
TDB.
I think yes, BTW.
Can tasks be linked to events in a Calendar?
TBD.
Linked, no. Associated (requires client capabilities to deal with it), yes (provided conversations or format extension/implementation).
The way Kolab Groupware stores information related to tasks is through attachments contained within the same RFC822 message as the event. It currently has no linking / reference capabilities (to data contained within nor external to Kolab Groupware).
Can I sort tasks?
Yes.
Can I categorize tasks?
Yes.
Can I tag tasks?
Yes.
Can I search tasks?
Yes.
Can I get overviews of tasks from multiple sources?
TBD.
The exact implementation details may be subject to the extent to which one or more of the "multiple sources" are external. If contained within Kolab, the answer is "yes".
Can I exchange (short) messages with Kolab?
TBD.
Think statusnet (identi.ca) software for microblogging, and/or XMPP/IRC for full chatting capabilities.
Can the communication channels be secured?
TBD.
Yes, for the most part. Statusnet though may not allow user/group access control for microblog-like short messages.
Can I send (short) messages to groups?
Yes.
Think statusnet '!' groups, or XMPP/IRC chat-rooms.
Does Kolab provide (real-time) user status/availability information?
TBD.
This is an instant messaging capability more so then a Kolab (IMAP) capability. Also relates to Voice and Video.
Can a user change / indicate their own status/availability information?
TBD.
Currently not a Kolab capability, more to instant messaging, voice and video.
Is the user's status / availability information visible in context?
TBD.
Currently not a Kolab capability, more to instant messaging, voice and video.
Can users send or make available documents outside of any application structure?
TBD.
We only deal with attachments at the moment, and we have little opportunity to strip attachments, make them available somewhere (through external storage), set the correct permissions on them, or check contents vs. access control policies (Data-Loss Prevention).
Can users send faxes with Kolab?
TBD.
Think mail-(attachment(s)-)to-fax asterisk interface.
Can users send text messages (SMS)?
TBD.
Think mail-to-sms asterisk interface.
Can users receive faxes?
TBD.
Think fax-to-mail asterisk interface.
Can users send over "print..." interface(s)?
TBD.
Can users send over email "send..." interface(s)?
Yes (provided mail-to-{fax,sms} asterisk interface or equivalent.
Can users receive SMS on mobile phones?
Euh, yes?
Can groups of users have video- and/or video-conference calls?
TBD.
Can users send video messages to other users?
TBD.
Do users have access to start video-based communication in the Address Book(s), Calendars, Websites, ...?
TBD.
Does Kolab provide users with telephony (internal and external)?
TBD.
Does Kolab integrate audio communication into Address Book(s), Calendaring, Websites, ...?
TBD.
p2p, conference, broadcast, ...?
TBD.
Voicemail?
TBD.
Voicemail to email?
TBD.
Does Kolab provide (de-)centralized resource management?
TBD.
Can users view details about the resources managed?
TBD.
Think read-only access to calendar, (extended) free/busy, ...
Keep in mind details may include a series of parameters to a resource or group of resources (car is automatic, beamer is HDMI/VGA/PAL, etc.).
Can Kolab manage acccess to resources?
TBD.
Probably a yes, but pictures or it didn't happen.
Does Kolab allow for resources to be bound to a specific location / physical proximity of the user?
TBD.
Does Kolab allow for centralized administration of user roles and permissions?
Yes.
Think also; mandatory access control plugins (LDAP Schema Extension, interface thereto, application to IMAP (and other resources)).
Does Kolab have support tools?
TBD.
Does Kolab allow for collaborative (joint) processing of components?
TBD.
Gobby? That other thing over SIP?
Does Kolab provide document versioning, approval, change notifications?
TBD.
Does Kolab provide easy to use, comprehensive and accurate search functionality?
TBD.
For those objects currently contained within IMAP, sure it does.
Does Kolab provide a coherent approach to information technology security?
TBD.
Does Kolab provide support for Public Key Infrastructure?
TBD.
Our PGP-based capabilities are not complete with Roundcube not yet supporting encryption/signing using PGP. Another topic is S/MIME.
Does Kolab provide the level of security integrity to comply with security standards and policies?
TBD.
Does Kolab provide means for Single-Signon?
TBD.

Index

F

feedback
contact information for this manual, Feedback