14 commits - About_Kolab_Groupware/Makefile Administrator_Guide/en-US Administrator_Guide/Makefile Architecture_and_Design/en-US Architecture_and_Design/Makefile Deployment_Guide/Makefile Development_Manual/Makefile .gitignore Installation_Guide/en-US Installation_Guide/Makefile Makefile Release_Notes/Makefile site.cfg Testing_Reference/Makefile
Jeroen van Meeuwen
vanmeeuwen at kolabsys.com
Mon Dec 12 13:32:43 CET 2011
.gitignore | 2
About_Kolab_Groupware/Makefile | 8
Administrator_Guide/Makefile | 6
Administrator_Guide/en-US/Administrator_Guide.xml | 2
Administrator_Guide/en-US/Combatting_Spam.xml | 54
Administrator_Guide/en-US/part-Kolab_Server.xml | 1
Architecture_and_Design/Makefile | 10
Architecture_and_Design/en-US/Akonadi_for_Integration_and_Caching.xml | 562 ++++++++++
Architecture_and_Design/en-US/Free_Busy.xml | 214 +++
Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml | 162 ++
Architecture_and_Design/en-US/images/SSA_0a.png |binary
Architecture_and_Design/en-US/images/SSA_0b.png |binary
Architecture_and_Design/en-US/images/SSA_1a.png |binary
Architecture_and_Design/en-US/images/SSA_2a.png |binary
Architecture_and_Design/en-US/images/SSA_2b.png |binary
Architecture_and_Design/en-US/images/SSA_2c.png |binary
Deployment_Guide/Makefile | 6
Development_Manual/Makefile | 6
Installation_Guide/Makefile | 14
Installation_Guide/en-US/Kolab_Server_Installation.xml | 114 +-
Makefile | 2
Release_Notes/Makefile | 6
Testing_Reference/Makefile | 6
site.cfg | 6
24 files changed, 1148 insertions(+), 33 deletions(-)
New commits:
commit 853e1a43659ad2adc728bc4b2479bc4046d87ff4
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 12:32:17 2011 +0000
Start the outline of the Kolab SMTP Access Policy
diff --git a/Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml b/Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml
new file mode 100644
index 0000000..5b38b63
--- /dev/null
+++ b/Architecture_and_Design/en-US/Kolab_SMTP_Access_Policy.xml
@@ -0,0 +1,162 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Architecture_and_Design.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-Architecture_and_Design-Kolab_SMTP_Access_Policy">
+ <title>Kolab SMTP Access Policy</title>
+ <para>
+ The Kolab SMTP Access Policy is a policy service for Postfix that allows delegation, mandatory recipient and sender access controls to be applied, using the <ulink url="http://www.postfix.org/SMTPD_POLICY_README.html">Postfix SMTPD Policy</ulink>, and verifies envelope sender addresses used against the authentication and authorization database.
+ </para>
+ <section id="sect-Architecture_and_Design-Kolab_SMTP_Access_Policy-What_the_Kolab_SMTP_Access_Policy_is">
+ <title>What the Kolab SMTP Access Policy is</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ As such, a corporate board or directors for example, may have a distribution group 'board at example.com' to which only the members of the board of directors are allowed to send messages, but no-one else.
+ </para>
+ <para>
+ 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
+ </para>
+ <para>
+ 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:
+ </para>
+ <example id="exam-Architecture_and_Design-What_the_Kolab_SMTP_Access_Policy_is-John_Doe_the_Chief_Executive_Officer">
+ <title>John Doe, the Chief Executive Officer</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ In LDAP, this would look as follows:
+ </para>
+ <para>
+
+<screen>dn: uid=doe,ou=People,dc=example,dc=com
+cn: John Doe
+(...)
+mail: john.doe at example.com
+(...)
+kolabDelegate: uid=meier,ou=People,dc=example,dc=com
+(...)</screen>
+
+ </para>
+
+ </example>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-Kolab_SMTP_Access_Policy-What_the_Kolab_SMTP_Access_Policy_is_not">
+ <title>What the Kolab SMTP Access Policy is not</title>
+ <para>
+ 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.
+ </para>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-Kolab_SMTP_Access_Policy-When">
+ <title>When?</title>
+ <para>
+ The Kolab SMTP Access Policy needs to be executed in desired points in a mail-flow.
+ </para>
+ <para>
+ A typical deployment executes the Kolab SMTP Access Policy upon receiving messages, or in other words, in <application>smtpd</application> and <application>submission</application>. The submission part is the most illustrative of why the Kolab SMTP Access Policy works the way it does.
+ </para>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-Kolab_SMTP_Access_Policy-Kolab_SMTP_Access_Policy_in_Action_During_Submission">
+ <title>Kolab SMTP Access Policy in Action During Submission</title>
+ <para>
+ The submission of a new email by a user of Kolab Groupware has the following three interesting stages;
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ MAIL FROM
+ </para>
+ <para>
+ There is always one envelope sender address.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ RCPT TO
+ </para>
+ <para>
+ There are one or more recipients for each message.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ DATA
+ </para>
+ <para>
+ 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.
+ </para>
+
+ </listitem>
+
+ </orderedlist>
+
+ </para>
+ <para>
+ Postfix allows for more and different restrictions to be configured to check the policy, but these are the interesting ones.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Is the sender authenticated?
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Is the authenticated sender allowed to use the envelope sender address?
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ Other address may include any of the email addresses the user has been made an authorized Kolab delegate for.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ In case these checks are successful the Kolab SMTP Access Policy either continues with "checking" the recipient - please see notes later on.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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 <code>ignore(_("No objections yet"))</code>.
+ </para>
+
+ </section>
+
+
+</chapter>
+
commit 5f7adbe7f5e5aefde20f71fb71f2e9bfa7cce9d7
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 12:31:43 2011 +0000
Add some bits on combatting spam
diff --git a/Administrator_Guide/en-US/Administrator_Guide.xml b/Administrator_Guide/en-US/Administrator_Guide.xml
index bc08680..cec1fe3 100644
--- a/Administrator_Guide/en-US/Administrator_Guide.xml
+++ b/Administrator_Guide/en-US/Administrator_Guide.xml
@@ -4,10 +4,10 @@
%BOOK_ENTITIES;
]>
<book>
- <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="part-Kolab_Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <!-- <xi:include href="part-Kolab_Clients.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="part-Kolab_Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <xi:include href="part-Kolab_Clients.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <index />
</book>
diff --git a/Administrator_Guide/en-US/Book_Info.xml b/Administrator_Guide/en-US/Book_Info.xml
index d960cbb..4342fd0 100644
--- a/Administrator_Guide/en-US/Book_Info.xml
+++ b/Administrator_Guide/en-US/Book_Info.xml
@@ -4,28 +4,28 @@
%BOOK_ENTITIES;
]>
<bookinfo id="book-Administrator_Guide-Administrator_Guide">
- <title>Administrator Guide</title>
- <subtitle>short description</subtitle>
- <productname>Kolab Groupware</productname>
- <productnumber>2.4</productnumber>
- <edition>0</edition>
- <pubsnumber>0</pubsnumber>
- <abstract>
- <para>
- A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the description field of the book's RPM spec file.
- </para>
+ <title>Administrator Guide</title>
+ <subtitle>short description</subtitle>
+ <productname>Kolab Groupware</productname>
+ <productnumber>2.4</productnumber>
+ <edition>0</edition>
+ <pubsnumber>0</pubsnumber>
+ <abstract>
+ <para>
+ A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the description field of the book's RPM spec file.
+ </para>
- </abstract>
- <corpauthor>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/title_logo.png" format="PNG" />
- </imageobject>
+ </abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/title_logo.png" format="PNG" />
+ </imageobject>
- </inlinemediaobject>
+ </inlinemediaobject>
- </corpauthor>
- <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </corpauthor>
+ <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>
diff --git a/Administrator_Guide/en-US/Combatting_Spam.xml b/Administrator_Guide/en-US/Combatting_Spam.xml
index c4b766a..74c1c10 100644
--- a/Administrator_Guide/en-US/Combatting_Spam.xml
+++ b/Administrator_Guide/en-US/Combatting_Spam.xml
@@ -3,7 +3,7 @@
<!ENTITY % BOOK_ENTITIES SYSTEM "Administrator_Guide.ent">
%BOOK_ENTITIES;
]>
-<chapter id="chap-Administrator_Guide-Detailed_Kolab_Server_Overview">
+<chapter id="chap-Administrator_Guide-Combatting_Spam">
<title>Combatting Spam</title>
<para>
Kolab Groupware comes with SpamAssassin by default.
@@ -15,31 +15,40 @@
Optionally, find all folders named "Spam" or "Junk":
</para>
<para>
- <screen>$ <userinput>find /path/to/spool -type d -name "Spam" -o -name "Junk"</userinput></screen>
+
+<screen>$ <userinput>find /path/to/spool -type d -name "Spam" -o -name "Junk"</userinput></screen>
+
</para>
<note>
<para>
Finding all folders called "Spam" or "Junk" can potentially take a long time, depending on the size of the spool.
</para>
+
</note>
- <remark>
- We would like to do the very same through IMAP, with annotations / SPECIAL-USE.
- </remark>
- <para>
- <screen>$ <userinput>sa-learn --dbpath /var/lib/amavisd/.spamassassin --spam /path/to/folder/[0-9]*.</userinput></screen>
- </para>
- <section>
- <title>Expiring Messages from Spam/Ham (Shared) Folders</title>
- <para>
- When you share folders to which users can move or copy ham and/or spam messages, it is sensible to purge the contents of those folders regularly, or the folder size continues to increase indefinitely.
- </para>
- <para>
- To purge the contents of a mailfolder, run ipurge:
- </para>
- <para>
- <screen>$ <userinput>/usr/lib/cyrus-imapd/ipurge -d 1 user/folder/name at domain.tld</userinput>
+ <remark> We would like to do the very same through IMAP, with annotations / SPECIAL-USE. </remark>
+ <para>
+
+<screen>$ <userinput>sa-learn --dbpath /var/lib/amavisd/.spamassassin --spam /path/to/folder/[0-9]*.</userinput></screen>
+
+ </para>
+ <section id="sect-Administrator_Guide-Combatting_Spam-Expiring_Messages_from_SpamHam_Shared_Folders">
+ <title>Expiring Messages from Spam/Ham (Shared) Folders</title>
+ <para>
+ When you share folders to which users can move or copy ham and/or spam messages, it is sensible to purge the contents of those folders regularly, or the folder size continues to increase indefinitely.
+ </para>
+ <para>
+ To purge the contents of a mailfolder, run ipurge:
+ </para>
+ <para>
+
+<screen>$ <userinput>/usr/lib/cyrus-imapd/ipurge -d 1 user/folder/name at domain.tld</userinput>
(...output abbreviated...)
$ <userinput>/usr/lib/cyrus-imapd/ipurge -i -d 1 user/folder/name at domain.tld</userinput></screen>
-</para>
+
+ </para>
+
+ </section>
+
+
</chapter>
commit 660a7756112fb98052f80a2bf81efbd968f8fc5c
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 12:31:12 2011 +0000
Add some thoughts on Free/Busy
diff --git a/Architecture_and_Design/en-US/Free_Busy.xml b/Architecture_and_Design/en-US/Free_Busy.xml
new file mode 100644
index 0000000..286ce8f
--- /dev/null
+++ b/Architecture_and_Design/en-US/Free_Busy.xml
@@ -0,0 +1,214 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Architecture_and_Design.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-Architecture_and_Design-FreeBusy">
+ <title>Free/Busy</title>
+ <para>
+ Free/Busy information can be generated from Event information from, or obtained from existing Free/Busy information in the following locations:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-Kolab_Groupware">
+ <title>Kolab Groupware</title>
+ <para>
+ The Kolab Groupware environment –we'll call this the <emphasis>corporate</emphasis> Kolab environment.
+ </para>
+
+ </formalpara>
+ <para>
+ 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.
+ </para>
+ <para>
+ As a mechanism to authorize, we may use the Cyrus IMAP ACLs;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-anonymous_l">
+ <title>anonymous: l</title>
+ <para>
+ Allow anonymous users to view basic Free/Busy information generated from the calendaring contents of this folder.
+ </para>
+
+ </formalpara>
+ <note>
+ <title>Security Consideration(s)</title>
+ <para>
+ 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.
+ </para>
+
+ </note>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-anonymous_lr">
+ <title>anonymous: lr</title>
+ <para>
+ Allow anonymous users to view detailed Free/Busy information from the calendaring contents of this folder.
+ </para>
+
+ </formalpara>
+ <note>
+ <title>Security Consideration(s)</title>
+ <para>
+ 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.
+ </para>
+
+ </note>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-anyone_l">
+ <title>anyone: l</title>
+ <para>
+ Allow anyone authenticated to view basic Free/Busy information from the calendaring contents of this folder.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-anyone_lr">
+ <title>anyone: lr</title>
+ <para>
+ Allow anyone to view detailed Free/Busy information from the calendaring contents of this folder.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-userid_l">
+ <title><userid>: l</title>
+ <para>
+ Allow the person authenticated and authorized as <emphasis><userid></emphasis> to view basic Free/Busy information from the calendaring contents of this folder.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-userid_lr">
+ <title><userid>: lr</title>
+ <para>
+ Allow the person authenticated and authorized as <emphasis><userid></emphasis> to view detailed Free/Busy information from the calendaring contents of this folder.
+ </para>
+
+ </formalpara>
+ <note>
+ <title>Security Consideration(s)</title>
+ <para>
+ Note that those authorized as <userid>, using the IMAP ACLs, would actually be allowed to read the complete event message(s) contents.
+ </para>
+
+ </note>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-groupgroupid_l">
+ <title>group:<groupid>: l</title>
+ <para>
+ Allow individuals authenticated part of group <emphasis><groupid></emphasis> to view basic Free/Busy information from the calendaring contents of this folder.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-groupgroupid_lr">
+ <title>group:<groupid>: lr</title>
+ <para>
+ Allow individuals authenticated part of group <emphasis><groupid></emphasis> to view detailed Free/Busy information from the calendaring contents of this folder.
+ </para>
+
+ </formalpara>
+ <note>
+ <title>Security Consideration(s)</title>
+ <para>
+ 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.
+ </para>
+
+ </note>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ 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).
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ Note that unless the group is a valid group for Cyrus IMAP ptloader, the group ACL could not be enforced.
+ </para>
+ <para>
+ Note that the Cyrus IMAP ptloader is configured using different settings than are used for authentication, as it concerns authorization.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-Third_party_Kolab_Groupware">
+ <title>Third-party Kolab Groupware</title>
+ <para>
+ A third-party Kolab Groupware environment, such as a private Kolab server.
+ </para>
+
+ </formalpara>
+ <para>
+ Between a private Kolab server and the corporate Kolab environment, the following options are available to the user:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Obtain the Free/Busy information from my private Kolab account and make it available within the corporate Kolab environment without event details.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ 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.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-Third_party_Calendaring">
+ <title>Third-party Calendaring</title>
+ <para>
+ With read(/write) permissions on, for example, a Google Calendar.
+ </para>
+
+ </formalpara>
+ <para>
+ The configuration for any user's Google Calendar.
+ </para>
+
+ </listitem>
+ <listitem>
+ <formalpara id="form-Architecture_and_Design-FreeBusy-Third_party_FreeBusy">
+ <title>Third-party Free/Busy</title>
+ <para>
+ With read(/write) permissions on, for example, Google iCal as published.
+ </para>
+
+ </formalpara>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+</chapter>
+
commit e7c2d114b816e8e208e6c5918ba173d4ec7d4c56
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 12:30:35 2011 +0000
Add chapter on server-side Akonadi
diff --git a/Architecture_and_Design/en-US/Akonadi_for_Integration_and_Caching.xml b/Architecture_and_Design/en-US/Akonadi_for_Integration_and_Caching.xml
new file mode 100644
index 0000000..0c3cf09
--- /dev/null
+++ b/Architecture_and_Design/en-US/Akonadi_for_Integration_and_Caching.xml
@@ -0,0 +1,562 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Architecture_and_Design.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-Architecture_and_Design-Akonadi_for_Integration_and_Caching">
+ <title>Akonadi for Integration and Caching</title>
+ <para>
+ In introduction into using Akonadi as the integration and caching layer for server-side clients goes here.
+ </para>
+ <section id="sect-Architecture_and_Design-Akonadi_for_Integration_and_Caching-Server_Side_Akonadi_Architecture_Overview">
+ <title>Server-Side Akonadi Architecture Overview</title>
+ <para>
+ <xref linkend="figu-Architecture_and_Design-Server_Side_Akonadi_Architecture_Overview-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.
+ </para>
+ <figure id="figu-Architecture_and_Design-Server_Side_Akonadi_Architecture_Overview-Local_Akonadi_Control_Server_Architecture_Overview">
+ <title>Local Akonadi Control Server Architecture Overview</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/SSA_0a.png" format="PNG" scalefit="1" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </figure>
+ <para>
+ 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 <xref linkend="figu-Architecture_and_Design-Server_Side_Akonadi_Architecture_Overview-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.
+ </para>
+ <figure id="figu-Architecture_and_Design-Server_Side_Akonadi_Architecture_Overview-Local_Akonadi_Control_Server_Architecture_with_SQL_Database_Server">
+ <title>Local Akonadi Control Server Architecture with SQL Database Server</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/SSA_0b.png" format="PNG" scalefit="1" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </figure>
+ <figure id="figu-Architecture_and_Design-Server_Side_Akonadi_Architecture_Overview-Networked_Akonadi_Control_Server_Architecture">
+ <title>Networked Akonadi Control Server Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/SSA_1a.png" format="PNG" scalefit="1" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </figure>
+ <figure id="figu-Architecture_and_Design-Server_Side_Akonadi_Architecture_Overview-Multiple_Networked_Akonadi_Control_Servers_Architecture">
+ <title>Multiple Networked Akonadi Control Servers Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/SSA_2a.png" format="PNG" scalefit="1" width="444" />
+ </imageobject>
+
+ </mediaobject>
+
+ </figure>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-Akonadi_for_Integration_and_Caching-Procedural_Descriptions">
+ <title>Procedural Descriptions</title>
+ <procedure id="proc-Architecture_and_Design-Procedural_Descriptions-Client_Connections_to_Akonadi">
+ <title>Client Connections to Akonadi</title>
+ <step>
+ <para>
+ The client (Roundcube, ActiveSync) calls <application>libakonadi</application> API <code>akonadi_open(</code><emphasis>username</emphasis><code>, </code><emphasis>password</emphasis><code>[, authorize_as=</code><emphasis>username</emphasis><code>][, imap_host=</code><emphasis>imap_host</emphasis><code>][, akonadi_session_id=</code><emphasis>akonadi_session_id</emphasis><code>])</code>.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ On behalf of the client application, <application>libakonadi</application> establishes a connection to;
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The configured or discovered Akonadi Control Server, through a configured mechanism (AF_UNIX, AF_INET, AMQP MessageBus obtained location).
+ </para>
+ <para>
+ See also: <xref linkend="proc-Architecture_and_Design-Procedural_Descriptions-libakonadi_Connections_to_Akonadi" />.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ The requested IMAP Server, if any.
+ </para>
+
+ </listitem>
+
+ </orderedlist>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The call to <code>akonadi_open()</code> may be synchronous or asynchronous.
+ </para>
+ <para>
+ For synchronous calls (using <code>akonadi_open_s()</code>), <application>libakonadi</application> refrains from returning a link identifier until after;
+ </para>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ It has fully established a successfully authenticated connection to the Akonadi Control Server, and the Akonadi Control Server has returned the Akonadi Session Identifier.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ It has fully established a successfully authenticated connection to the IMAP server, if any such had been requested.
+ </para>
+
+ </listitem>
+
+ </orderedlist>
+
+ </para>
+ <para>
+ For asynchronous calls (using <code>akonadi_open()</code>), <application>libakonadi</application> 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.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The call returns a link identifier.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ 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:
+ </para>
+ <para>
+ <code>akonadi_session_id(</code><emphasis>link identifier</emphasis><code>)</code>
+ </para>
+
+ </step>
+
+ </procedure>
+
+ <procedure id="proc-Architecture_and_Design-Procedural_Descriptions-libakonadi_Connections_to_Akonadi">
+ <title><application>libakonadi</application> Connections to Akonadi</title>
+ <step>
+ <para>
+ <application>libakonadi</application>, using the credentials supplied to it through the <code>akonadi_open()</code> 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.
+ </para>
+ <para>
+ <remark>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. </remark>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ 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.
+ </para>
+
+ </step>
+
+ </procedure>
+
+ <procedure id="proc-Architecture_and_Design-Procedural_Descriptions-Akonadi_Control_Server_Connection_Handling">
+ <title>Akonadi Control Server Connection Handling</title>
+ <step>
+ <para>
+ Upon receiving a connection, the ACS identifies itself in a greeting (server_name) and includes its capabilities.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ 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;
+ </para>
+ <procedure id="proc-Architecture_and_Design-Akonadi_Control_Server_Connection_Handling-ACS_Akonadi_Server_and_Agent_Startup">
+ <title>ACS Akonadi Server and Agent Startup</title>
+ <step>
+ <para>
+ The client application user is associated with an Akonadi Session Identifier.
+ </para>
+ <para>
+ It is NOT the client application session that is associated with an Akonadi Server.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ 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.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The private key is forgotten.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The public key is maintained in a Akonadi Session Identifier.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ If successful, the Akonadi Session Identifier is passed back to the client (<application>libakonadi</application>).
+ </para>
+
+ </step>
+ <step>
+ <para>
+ After initial discovery (IMAP Configuration folder), additional Akonadi Agents may need to be started up. For this procedure, please see
+ </para>
+
+ </step>
+
+ </procedure>
+
+
+ </step>
+
+ </procedure>
+
+ <procedure id="proc-Architecture_and_Design-Procedural_Descriptions-Starting_up_Additional_Akonadi_Agents">
+ <title>Starting up Additional Akonadi Agents</title>
+ <step>
+ <para>
+ The following situations may cause a new Akonadi Agent to need to be started:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ An Akonadi Agent has died unexpectedly.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ 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 / ...).
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Any other case.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ Additionally, the exchange of the original user credentials may be needed in the following scenario:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ 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.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The exchange of user credentials happens over D-Bus.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ 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.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The Akonadi Control Server responds with a signed/encrypted D-Bus signal containing the user credentials.
+ </para>
+
+ </step>
+
+ </procedure>
+
+ <!-- <procedure>
+ <step>
+ <para>
+ The client identifies itself using a token that is a fully qualified, globally unique user identifier, plus a session-specific token, such as a PHP <code>$_SESSION['id']</code>.
+ </para>
+ <para>
+ The user identifier cannot be, for example, 'jdoe', as it is unqualified, and cannot be 'www01.example.org' as it is not tied to the user - it is recommended to use the primary mail address, such as 'jdoe at example.org'.
+ </para>
+ <para>
+ <remark> The aforementioned would require proper canonification to happen at the client application level, in order to allow users to login with their uid/mail/alias/mailAlternateAddress fully qualified or unqualified user identifier. </remark>
+
+ </para>
+ <para>
+ <remark>Also note that 'jdoe at example.org' or someone's primary email address is not necessarily persistent. When Jane.Gi at example.org marries John Doe, her primary email address may change to Jane.Doe at example.org, inherently invalidating the existing copy of one's cache; There are potentially persistent unique attributes out there such as <code>nsuniqueid</code> and SQL's 'user.id' if you will. This would require the client applications to be able to retrieve that information, however. </remark>
+
+ </para>
+ <para>
+ The Session Idenfifier is added to the initial greeting in order to allow the ACS to recognize the client application is a formerly authenticated and authorized client session. If this would not be included, client #2 (ActiveSync) could be associated with client #1's (Roundcube) Akonadi Server without intermediate authentication/authorization/verification.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ For the ASS process steps upon having received a greeting from the client identifying itself as one of potentially multiple sessions associated with a user, see <xref linkend="proc-Architecture_and_Design-Akonadi_for_Integration_and_Caching-Akonadi_Control_Server_Client_Connection_Handling" />.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The ASS returns a generated token to the client which the client MUST store and MUST supply with subsequent connection requests.
+ </para>
+ <para>
+ This token is an Akonadi Session Identifier.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ User credentials exchange.
+ </para>
+ <para>
+ <remark> Plaintext submission of user credentials should not be allowed, unless using local sockets (i.e. AF_UNIX). Plaintext submission of the user credentials is only allowed under explicit TLS, or implicit SSL. </remark>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The ASS spawns an Akonadi Server (AS), with a time of anticipated shutdown set 30 minutes from now, and proxies the client connection through to the socket created by the corresponding AS.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ The ASS supplies a plaintext version of the user credentials to the AS, of which the password MAY NOT be stored in plain text.
+ </para>
+
+ </step>
+ <step>
+ <para>
+ Upon the return of the greeting containing the encrypted version of the user password, the client MUST verify the ASS token
+ </para>
+
+ </step>
+
+ </procedure>
+
+ <procedure id="proc-Architecture_and_Design-Akonadi_for_Integration_and_Caching-Akonadi_Control_Server_Client_Connection_Handling">
+ <title>Akonadi Control Server Client Connection Handling</title>
+ <step>
+ <para>
+ Upon receiving the user and session identifiers, the ACS attempts to find an existing Akonadi Server associated with the user identifier using an internal table storing;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The user identifier
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ The user password
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ The D-Bus session ID
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ One or more client application session IDs.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ Public encryption keys to the Akonadi Server and one or more Akonadi Agent(s) for encrypted D-Bus payload.
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </step>
+ <step>
+ <para>
+ If no existing Akonadi Server exists, the ACS generates an asynchronous encryption key-pair and spawns the Akonadi Server with it, forgetting the private key, and repeats this exercise for all of one or more Akonadi Agent(s).
+ </para>
+
+ </step>
+
+ </procedure> -->
+ </section>
+
+ <section id="sect-Architecture_and_Design-Akonadi_for_Integration_and_Caching-Notes_from_Design_Sessions">
+ <title>Notes from Design Sessions</title>
+ <section id="sect-Architecture_and_Design-Notes_from_Design_Sessions-Authentication_to_Akonadi_Control_Server">
+ <title>Authentication to Akonadi Control Server</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ Note that the client library, <application>libakonadi</application> 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-Notes_from_Design_Sessions-AMQP_Capabilities_for_libakonadi">
+ <title>AMQP Capabilities for <application>libakonadi</application></title>
+ <para>
+ AMQP capabilities for <application>libakonadi</application> would enable <application>libakonadi</application> 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.
+ </para>
+ <para>
+ 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.
+ </para>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-Notes_from_Design_Sessions-AMQP_Capabilities_for_Akonadi">
+ <title>AMQP Capabilities for Akonadi</title>
+ <para>
+ AMQP capabilities for Akonadi in general would enable IMAP to push change notifications to Akonadi services including <application>libakonadi</application> even if that means the client library can only pick them up during the first interaction against the client application. Such notifications could include;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Folder change notifications (new calendar folder, folder dissappeared)
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ New and/or updated message content (update cache, Free/Busy, or more in general, act accordingly)
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ These notifications (from Cyrus IMAP) and notifications from Akonadi itself, can remain pending on the messagebus for <application>libakonadi</application> to pick up when users start interacting with client applications.
+ </para>
+ <para>
+ 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 <ulink url="http://en.wikipedia.org/wiki/WebSocket">web sockets</ulink>.
+ </para>
+
+ </section>
+
+ <section id="sect-Architecture_and_Design-Notes_from_Design_Sessions-libakonadi_Direct_IMAP_Connections">
+ <title><application>libakonadi</application> Direct IMAP Connections</title>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <command>LIST</command>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <command>LSUB</command>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <command>FETCH</command>
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ 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.
+ </para>
+ <para>
+ 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;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <command>THREAD ALL UNDELETED</command>
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ <para>
+ 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;
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ All calendar items for month $x or weeek $y.
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ A list of all calendar folders (the user has write access to).
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </section>
+
+
+ </section>
+
+
+</chapter>
+
commit e663ccc6babc947fd961156719bb96e7cfc325e4
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 12:30:27 2011 +0000
Add architecture images for server-side Akonadi
diff --git a/Architecture_and_Design/en-US/images/SSA_0a.png b/Architecture_and_Design/en-US/images/SSA_0a.png
new file mode 100644
index 0000000..78fc635
Binary files /dev/null and b/Architecture_and_Design/en-US/images/SSA_0a.png differ
diff --git a/Architecture_and_Design/en-US/images/SSA_0b.png b/Architecture_and_Design/en-US/images/SSA_0b.png
new file mode 100644
index 0000000..87326d4
Binary files /dev/null and b/Architecture_and_Design/en-US/images/SSA_0b.png differ
diff --git a/Architecture_and_Design/en-US/images/SSA_1a.png b/Architecture_and_Design/en-US/images/SSA_1a.png
new file mode 100644
index 0000000..c4f34b1
Binary files /dev/null and b/Architecture_and_Design/en-US/images/SSA_1a.png differ
diff --git a/Architecture_and_Design/en-US/images/SSA_2a.png b/Architecture_and_Design/en-US/images/SSA_2a.png
new file mode 100644
index 0000000..b7c601d
Binary files /dev/null and b/Architecture_and_Design/en-US/images/SSA_2a.png differ
diff --git a/Architecture_and_Design/en-US/images/SSA_2b.png b/Architecture_and_Design/en-US/images/SSA_2b.png
new file mode 100644
index 0000000..859a393
Binary files /dev/null and b/Architecture_and_Design/en-US/images/SSA_2b.png differ
diff --git a/Architecture_and_Design/en-US/images/SSA_2c.png b/Architecture_and_Design/en-US/images/SSA_2c.png
new file mode 100644
index 0000000..68645a4
Binary files /dev/null and b/Architecture_and_Design/en-US/images/SSA_2c.png differ
commit 46ec5e47c6d3baaf87a56e54e2ae95cea35fb0cb
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 12:29:22 2011 +0000
I always intended these packages to be listed in alphabetical order
diff --git a/Makefile b/Makefile
index ec1d42a..49b2da9 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,7 @@
SUBDIRS = \
About_Kolab_Groupware \
- Architecture_and_Design \
Administrator_Guide \
+ Architecture_and_Design \
Deployment_Guide \
Development_Manual \
Installation_Guide \
commit 665214c097020eef8aa65b0ae72bfe03c23cd1e9
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 11:58:25 2011 +0000
Add a chapter on combatting spam to the administrator guide
diff --git a/Administrator_Guide/en-US/Administrator_Guide.xml b/Administrator_Guide/en-US/Administrator_Guide.xml
index b07c352..bc08680 100644
--- a/Administrator_Guide/en-US/Administrator_Guide.xml
+++ b/Administrator_Guide/en-US/Administrator_Guide.xml
@@ -4,10 +4,10 @@
%BOOK_ENTITIES;
]>
<book>
- <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="part-Kolab_Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <!-- <xi:include href="part-Kolab_Clients.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <index />
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="part-Kolab_Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <xi:include href="part-Kolab_Clients.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> --> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <index />
</book>
diff --git a/Administrator_Guide/en-US/Book_Info.xml b/Administrator_Guide/en-US/Book_Info.xml
index 4342fd0..d960cbb 100644
--- a/Administrator_Guide/en-US/Book_Info.xml
+++ b/Administrator_Guide/en-US/Book_Info.xml
@@ -4,28 +4,28 @@
%BOOK_ENTITIES;
]>
<bookinfo id="book-Administrator_Guide-Administrator_Guide">
- <title>Administrator Guide</title>
- <subtitle>short description</subtitle>
- <productname>Kolab Groupware</productname>
- <productnumber>2.4</productnumber>
- <edition>0</edition>
- <pubsnumber>0</pubsnumber>
- <abstract>
- <para>
- A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the description field of the book's RPM spec file.
- </para>
+ <title>Administrator Guide</title>
+ <subtitle>short description</subtitle>
+ <productname>Kolab Groupware</productname>
+ <productnumber>2.4</productnumber>
+ <edition>0</edition>
+ <pubsnumber>0</pubsnumber>
+ <abstract>
+ <para>
+ A short overview and summary of the book's subject and purpose, traditionally no more than one paragraph long. Note: the abstract will appear in the front matter of your book and will also be placed in the description field of the book's RPM spec file.
+ </para>
- </abstract>
- <corpauthor>
- <inlinemediaobject>
- <imageobject>
- <imagedata fileref="images/title_logo.png" format="PNG" />
- </imageobject>
+ </abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="images/title_logo.png" format="PNG" />
+ </imageobject>
- </inlinemediaobject>
+ </inlinemediaobject>
- </corpauthor>
- <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ </corpauthor>
+ <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>
diff --git a/Administrator_Guide/en-US/Combatting_Spam.xml b/Administrator_Guide/en-US/Combatting_Spam.xml
new file mode 100644
index 0000000..c4b766a
--- /dev/null
+++ b/Administrator_Guide/en-US/Combatting_Spam.xml
@@ -0,0 +1,45 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "Administrator_Guide.ent">
+%BOOK_ENTITIES;
+]>
+<chapter id="chap-Administrator_Guide-Detailed_Kolab_Server_Overview">
+ <title>Combatting Spam</title>
+ <para>
+ Kolab Groupware comes with SpamAssassin by default.
+ </para>
+ <para>
+ Learning spam
+ </para>
+ <para>
+ Optionally, find all folders named "Spam" or "Junk":
+ </para>
+ <para>
+ <screen>$ <userinput>find /path/to/spool -type d -name "Spam" -o -name "Junk"</userinput></screen>
+ </para>
+ <note>
+ <para>
+ Finding all folders called "Spam" or "Junk" can potentially take a long time, depending on the size of the spool.
+ </para>
+ </note>
+ <remark>
+ We would like to do the very same through IMAP, with annotations / SPECIAL-USE.
+ </remark>
+ <para>
+ <screen>$ <userinput>sa-learn --dbpath /var/lib/amavisd/.spamassassin --spam /path/to/folder/[0-9]*.</userinput></screen>
+ </para>
+ <section>
+ <title>Expiring Messages from Spam/Ham (Shared) Folders</title>
+ <para>
+ When you share folders to which users can move or copy ham and/or spam messages, it is sensible to purge the contents of those folders regularly, or the folder size continues to increase indefinitely.
+ </para>
+ <para>
+ To purge the contents of a mailfolder, run ipurge:
+ </para>
+ <para>
+ <screen>$ <userinput>/usr/lib/cyrus-imapd/ipurge -d 1 user/folder/name at domain.tld</userinput>
+(...output abbreviated...)
+$ <userinput>/usr/lib/cyrus-imapd/ipurge -i -d 1 user/folder/name at domain.tld</userinput></screen>
+</para>
+</chapter>
+
diff --git a/Administrator_Guide/en-US/part-Kolab_Server.xml b/Administrator_Guide/en-US/part-Kolab_Server.xml
index 099115e..c4b7925 100755
--- a/Administrator_Guide/en-US/part-Kolab_Server.xml
+++ b/Administrator_Guide/en-US/part-Kolab_Server.xml
@@ -8,5 +8,6 @@
<xi:include href="Verifying_the_Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Configuring_the_Kolab_Server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Detailed_Kolab_Server_Overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Combatting_Spam.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</part>
commit a16668b26f3235a77cfc588ad6433405c9949fe1
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 11:58:11 2011 +0000
Update Makefiles
diff --git a/Administrator_Guide/Makefile b/Administrator_Guide/Makefile
index 04b2054..a86b675 100644
--- a/Administrator_Guide/Makefile
+++ b/Administrator_Guide/Makefile
@@ -1,7 +1,7 @@
PACKAGE = "Administrator_Guide"
all: clean clean_ids
- @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ @if [ -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
publican install_book --site_config=../site.cfg --lang=en-US; \
fi
diff --git a/Architecture_and_Design/Makefile b/Architecture_and_Design/Makefile
index e56f5fc..f71bd58 100644
--- a/Architecture_and_Design/Makefile
+++ b/Architecture_and_Design/Makefile
@@ -1,7 +1,7 @@
PACKAGE = "Architecture_and_Design"
all: clean clean_ids
- @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ @if [ -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
publican install_book --site_config=../site.cfg --lang=en-US; \
fi
diff --git a/Deployment_Guide/Makefile b/Deployment_Guide/Makefile
index cb1b5a7..699657a 100644
--- a/Deployment_Guide/Makefile
+++ b/Deployment_Guide/Makefile
@@ -1,7 +1,7 @@
PACKAGE = "Deployment_Guide"
all: clean clean_ids
- @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ @if [ -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
publican install_book --site_config=../site.cfg --lang=en-US; \
fi
diff --git a/Development_Manual/Makefile b/Development_Manual/Makefile
index bcb8701..cb7b59d 100644
--- a/Development_Manual/Makefile
+++ b/Development_Manual/Makefile
@@ -1,7 +1,7 @@
PACKAGE = "Development_Manual"
all: clean clean_ids
- @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ @if [ -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
publican install_book --site_config=../site.cfg --lang=en-US; \
fi
diff --git a/Release_Notes/Makefile b/Release_Notes/Makefile
index cdcca4d..4225189 100644
--- a/Release_Notes/Makefile
+++ b/Release_Notes/Makefile
@@ -1,7 +1,7 @@
PACKAGE = "Release_Notes"
all: clean clean_ids
- @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ @if [ -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
publican install_book --site_config=../site.cfg --lang=en-US; \
fi
diff --git a/Testing_Reference/Makefile b/Testing_Reference/Makefile
index 64d78fe..ea3439c 100644
--- a/Testing_Reference/Makefile
+++ b/Testing_Reference/Makefile
@@ -1,7 +1,7 @@
PACKAGE = "Testing_Reference"
all: clean clean_ids
- @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ @if [ -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
publican install_book --site_config=../site.cfg --lang=en-US; \
fi
commit 7358239bf6c8152d24116ba1d3508995a0905202
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 11:57:10 2011 +0000
Update Installation_Guide Makefile
diff --git a/Installation_Guide/Makefile b/Installation_Guide/Makefile
index 66442d8..c7ec007 100644
--- a/Installation_Guide/Makefile
+++ b/Installation_Guide/Makefile
@@ -1,12 +1,14 @@
PACKAGE = "Installation_Guide"
all: clean clean_ids
- @for audience in enterprise community; do \
- sed -r -i -e "s/^condition:.*/condition: $$audience/g" publican.cfg; \
- sed -r -i -e "s/^docname:.*/docname: $$(echo $${audience:0:1} | tr '[:lower:]' '[:upper:]')$${audience:1}_$(PACKAGE)/g" publican.cfg; \
- publican build --embedtoc --publish --langs=en-US --formats=html,html-single,pdf; \
- publican install_book --site_config=../site.cfg --lang=en-US; \
- done
+ @if [ -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ for audience in enterprise community; do \
+ sed -r -i -e "s/^condition:.*/condition: $$audience/g" publican.cfg; \
+ sed -r -i -e "s/^docname:.*/docname: $$(echo $${audience:0:1} | tr '[:lower:]' '[:upper:]')$${audience:1}_$(PACKAGE)/g" publican.cfg; \
+ publican build --embedtoc --publish --langs=en-US --formats=html,html-single,pdf; \
+ publican install_book --site_config=../site.cfg --lang=en-US; \
+ done; \
+ fi
@sed -r -i -e 's/^condition:.*/condition: community/g' publican.cfg
upload: clean clean_ids
commit a82618b88ad2e982187cbe4ef241bc82cb55f0d9
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 11:57:00 2011 +0000
Update Kolab_Server_Installation section
diff --git a/Installation_Guide/en-US/Kolab_Server_Installation.xml b/Installation_Guide/en-US/Kolab_Server_Installation.xml
index 93d7410..1a46920 100755
--- a/Installation_Guide/en-US/Kolab_Server_Installation.xml
+++ b/Installation_Guide/en-US/Kolab_Server_Installation.xml
@@ -139,7 +139,7 @@
</entry>
</row>
- <row>
+ <!-- <row>
<entry>
Fedora
</entry>
@@ -156,8 +156,7 @@
Q2, 2011
</entry>
- </row>
- <row>
+ </row> --> <row>
<entry>
Fedora
</entry>
@@ -177,6 +176,24 @@
</row>
<row>
<entry>
+ Fedora
+ </entry>
+ <entry>
+ Lovelock
+ </entry>
+ <entry>
+ 15
+ </entry>
+ <entry>
+ i386, amd64
+ </entry>
+ <entry>
+ Q2, 2012
+ </entry>
+
+ </row>
+ <row>
+ <entry>
Red Hat Enterprise Linux
</entry>
<entry>
@@ -222,7 +239,7 @@
<section id="sect-Community_Installation_Guide-Installation_with_RPM_Packages-Prerequisites">
<title>Prerequisites</title>
<para>
- Before the installation, it is necessary to add the Kolab repositories to have access to all needed packages.
+ Before the installation, it is necessary to install the configuration for the Kolab software repositories.
</para>
<section id="sect-Community_Installation_Guide-Prerequisites-CentOS">
<title>CentOS</title>
@@ -245,15 +262,38 @@
<section id="sect-Community_Installation_Guide-Prerequisites-Fedora">
<title>Fedora</title>
<para>
- TODO: is this correct? For full instructions on installing Kolab Groupware on Fedora, please refer to the instructions in <xref linkend="sect-Community_Installation_Guide-Prerequisites-Red_Hat_Enterprise_Linux" />.
+ To install Kolab Groupware on Fedora, additional Kolab Groupware software repositories are required.
</para>
+ <procedure id="proc-Community_Installation_Guide-Fedora-Installing_the_Kolab_Groupware_repositories_for_Fedora">
+ <title>Installing the Kolab Groupware repositories for Fedora</title>
+ <step>
+ <para>
+ Depending on the version of Fedora, install the following package:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ TODO
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+
+ </step>
+
+ </procedure>
+
</section>
<section id="sect-Community_Installation_Guide-Prerequisites-Red_Hat_Enterprise_Linux">
<title>Red Hat Enterprise Linux</title>
<para>
- The <ulink url="http://fedoraproject.org/wiki/EPEL">EPEL</ulink> repository is required for Kolab Groupware on Enterprise Linux 5. Install the EPEL repository using the following procedure:
+ The <ulink url="http://fedoraproject.org/wiki/EPEL">EPEL</ulink> repository is required for Kolab Groupware on Red Hat Enterprise Linux. Install the EPEL repository using the following procedure:
</para>
<procedure id="proc-Community_Installation_Guide-Red_Hat_Enterprise_Linux-Installing_the_epel_release_Package">
<title>Installing the <application>epel-release</application> Package</title>
@@ -297,7 +337,7 @@
</procedure>
<para condition="enterprise">
- For access to the Enterprise edition, you have been issued a SSL certificate by Kolab Systems. How to obtain, renew and use the SSL certificate to provide you with access to the Enterprise editions, please read <ulink url="https://support.kolabsys.com/Obtaining,_Renewing_and_Using_a_Client_SSL_Certificate" />.
+ For access to the Enterprise edition, you must have been issued a SSL certificate by Kolab Systems. How to obtain, renew and use the SSL certificate to provide you with access to the Enterprise editions, please read <ulink url="https://support.kolabsys.com/Obtaining,_Renewing_and_Using_a_Client_SSL_Certificate" />.
</para>
<para>
The Kolab software repositories for Red Hat Enterprise Linux ship two so-called <literal>-release</literal> packages:
@@ -306,7 +346,28 @@
<orderedlist>
<listitem condition="community">
<para>
- <literal>kolab-&PRODUCT_VERSION;-community-release</literal> <ulink url="http://mirror.kolabsys.com/pub/redhat/kolab-2.4/el5/development/x86_64/kolab-2.4-community-release-5-13.el5.kolab_2.4.noarch.rpm">kolab-2.4-community-release-5-13.el5.kolab_2.4.noarch.rpm</ulink>
+ <literal>kolab-&PRODUCT_VERSION;-community-release</literal>
+ </para>
+ <para>
+ Depending on the version of Red Hat Enterprise Linux, find the <literal>-release</literal> package at:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://mirror.kolabsys.com/pub/redhat/kolab-2.4/el5/release/i386/repoview/kolab-2.4-community-release.html">Red Hat Enterprise Linux 5 (Tikanga)</ulink>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://mirror.kolabsys.com/pub/redhat/kolab-2.4/el6/release/i386/repoview/kolab-2.4-community-release.html">Red Hat Enterprise Linux 6 (Santiago)</ulink>
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
</para>
</listitem>
@@ -314,18 +375,55 @@
<para>
<literal>kolab-&PRODUCT_VERSION;-enterprise-release</literal>
</para>
+ <para>
+ Depending on the version of Red Hat Enterprise Linux, find the <literal>-release</literal> package at:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="https://mirror.kolabsys.com/redhat/kolab-2.4/el5/release/i386/repoview/kolab-2.4-enterprise-release.html">Red Hat Enterprise Linux 5 (Tikanga)</ulink>
+ </para>
+
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="https://mirror.kolabsys.com/redhat/kolab-2.4/el6/release/i386/repoview/kolab-2.4-enterprise-release.html">Red Hat Enterprise Linux 6 (Santiago)</ulink>
+ </para>
+
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
</listitem>
<listitem condition="community">
<para>
<literal>kolab-&PRODUCT_VERSION;-community-release-development</literal>
</para>
+ <para>
+ You can install the <literal>kolab-&PRODUCT_VERSION;-community-release-development</literal> package using YUM, after having installed the <literal>kolab-&PRODUCT_VERSION;-community-release</literal> package;
+ </para>
+ <para>
+
+<screen># <userinput>yum install kolab-&PRODUCT_VERSION;-community-release-development</userinput></screen>
+
+ </para>
</listitem>
<listitem condition="enterprise">
<para>
<literal>kolab-&PRODUCT_VERSION;-enterprise-release-development</literal>
</para>
+ <para>
+ You can install the <literal>kolab-&PRODUCT_VERSION;-enterprise-release-development</literal> package using YUM, after having installed the <literal>kolab-&PRODUCT_VERSION;-enterprise-release</literal> package;
+ </para>
+ <para>
+
+<screen># <userinput>yum install kolab-&PRODUCT_VERSION;-enterprise-release-development</userinput></screen>
+
+ </para>
</listitem>
commit ebd8d9a124305987df52e79edc072cb003b25332
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Dec 12 11:53:23 2011 +0000
Update Makefile
diff --git a/About_Kolab_Groupware/Makefile b/About_Kolab_Groupware/Makefile
index c7df205..8fc349a 100644
--- a/About_Kolab_Groupware/Makefile
+++ b/About_Kolab_Groupware/Makefile
@@ -1,7 +1,7 @@
PACKAGE = "About_Kolab_Groupware"
all: clean clean_ids
- @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ @if [ -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
publican install_book --site_config=../site.cfg --lang=en-US; \
fi
commit 5608c49bf67d7776a7482fd25a44589850bf6a5a
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Fri Dec 9 12:20:26 2011 +0000
Advance Makefiles to be more efficient, and only build documents if there's actual changes after clean/clean_ids
diff --git a/About_Kolab_Groupware/Makefile b/About_Kolab_Groupware/Makefile
index d8bda32..c7df205 100644
--- a/About_Kolab_Groupware/Makefile
+++ b/About_Kolab_Groupware/Makefile
@@ -1,8 +1,10 @@
-PACKAGE = "Administrator_Guide"
+PACKAGE = "About_Kolab_Groupware"
all: clean clean_ids
- @publican build --publish --embedtoc --langs=all --formats=html-single
- @publican install_book --site_config=../site.cfg --lang=en-US
+ @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
+ publican install_book --site_config=../site.cfg --lang=en-US; \
+ fi
upload: all
@rsync -aHvz publish/home/ hosted.kolabsys.com:./public_html/kolab-docs/
diff --git a/Administrator_Guide/Makefile b/Administrator_Guide/Makefile
index 65fde70..04b2054 100644
--- a/Administrator_Guide/Makefile
+++ b/Administrator_Guide/Makefile
@@ -1,8 +1,10 @@
PACKAGE = "Administrator_Guide"
all: clean clean_ids
- @publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf
- @publican install_book --site_config=../site.cfg --lang=en-US
+ @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
+ publican install_book --site_config=../site.cfg --lang=en-US; \
+ fi
upload: all
@rsync -aHvz publish/en-US/ hosted.kolabsys.com:./public_html/kolab-docs/
diff --git a/Architecture_and_Design/Makefile b/Architecture_and_Design/Makefile
index 618f474..e56f5fc 100644
--- a/Architecture_and_Design/Makefile
+++ b/Architecture_and_Design/Makefile
@@ -1,8 +1,10 @@
PACKAGE = "Architecture_and_Design"
all: clean clean_ids
- @publican build --embedtoc --publish --langs=en-US --formats=html,html-single,pdf
- @publican install_book --site_config=../site.cfg --lang=en-US
+ @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
+ publican install_book --site_config=../site.cfg --lang=en-US; \
+ fi
upload: all
@rsync -aHvz publish/en-US/ hosted.kolabsys.com:./public_html/kolab-docs/
@@ -21,5 +23,5 @@ clean_ids:
`find en-US/ -type f -name "*.xml"`
# Additional quick build targets
-pdf:
- @publican build --langs=en-US --formats=pdf
+pdf: clean clean_ids
+ @publican build --embedtoc --publish --langs=en-US --formats=pdf
diff --git a/Deployment_Guide/Makefile b/Deployment_Guide/Makefile
index 790640a..cb1b5a7 100644
--- a/Deployment_Guide/Makefile
+++ b/Deployment_Guide/Makefile
@@ -1,8 +1,10 @@
PACKAGE = "Deployment_Guide"
all: clean clean_ids
- @publican build --embedtoc --publish --langs=en-US --formats=html,html-single,pdf
- @publican install_book --site_config=../site.cfg --lang=en-US
+ @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
+ publican install_book --site_config=../site.cfg --lang=en-US; \
+ fi
upload: all
@rsync -aHvz publish/en-US/ hosted.kolabsys.com:./public_html/kolab-docs/
diff --git a/Development_Manual/Makefile b/Development_Manual/Makefile
index 3e7c0f0..bcb8701 100644
--- a/Development_Manual/Makefile
+++ b/Development_Manual/Makefile
@@ -1,8 +1,10 @@
PACKAGE = "Development_Manual"
all: clean clean_ids
- @publican build --embedtoc --publish --langs=en-US --formats=html,html-single,pdf
- @publican install_book --site_config=../site.cfg --lang=en-US
+ @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
+ publican install_book --site_config=../site.cfg --lang=en-US; \
+ fi
upload: all
@rsync -aHvz publish/en-US/ hosted.kolabsys.com:./public_html/kolab-docs/
diff --git a/Release_Notes/Makefile b/Release_Notes/Makefile
index 7c43140..cdcca4d 100644
--- a/Release_Notes/Makefile
+++ b/Release_Notes/Makefile
@@ -1,8 +1,10 @@
PACKAGE = "Release_Notes"
all: clean clean_ids
- @publican build --embedtoc --publish --langs=en-US --formats=html,html-single,pdf
- @publican install_book --site_config=../site.cfg --lang=en-US
+ @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
+ publican install_book --site_config=../site.cfg --lang=en-US; \
+ fi
upload: all
@rsync -aHvz publish/en-US/ hosted.kolabsys.com:./public_html/kolab-docs/
diff --git a/Testing_Reference/Makefile b/Testing_Reference/Makefile
index 269f8fd..64d78fe 100644
--- a/Testing_Reference/Makefile
+++ b/Testing_Reference/Makefile
@@ -1,8 +1,10 @@
PACKAGE = "Testing_Reference"
all: clean clean_ids
- @publican build --embedtoc --publish --langs=en-US --formats=html,html-single,pdf
- @publican install_book --site_config=../site.cfg --lang=en-US
+ @if [ ! -z "`git status . 2>&1 | grep \"working directory clean\"`" ]; then \
+ publican build --embedtoc --publish --langs=all --formats=html,html-single,pdf; \
+ publican install_book --site_config=../site.cfg --lang=en-US; \
+ fi
upload: all
@rsync -aHvz publish/en-US/ hosted.kolabsys.com:./public_html/kolab-docs/
commit 3a1ecfbe0458ccb8be6bc7295ae9b8f2c9b52471
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Nov 14 14:06:34 2011 +0000
Ignore files for site
diff --git a/.gitignore b/.gitignore
index 45c2a09..1f51f8d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,4 +11,6 @@
!Common_Content/*/sect-Kolab_Product_Series.xml
!Common_Content/*/sect-Supported_Platforms_and_System_Requirements.xml
builds/
+site/
*~
+*.db
commit bb1c91fd335d909f9cb75ff9b72e928346a2073b
Author: Jeroen van Meeuwen (Kolab Systems) <vanmeeuwen at kolabsys.com>
Date: Mon Nov 14 14:05:51 2011 +0000
Update site.cfg
diff --git a/site.cfg b/site.cfg
new file mode 100644
index 0000000..3338262
--- /dev/null
+++ b/site.cfg
@@ -0,0 +1,6 @@
+# Config::Simple 4.59
+# Tue Oct 25 19:04:36 2011
+
+db_file: "../kolab-docs.db"
+toc_path: "../site"
+
More information about the commits
mailing list