imip-agent

README.txt

757:53408cd94020
2015-09-19 Paul Boddie Normalised attendees to allow reliable testing; fixed attendee removal to prevent attendees being marked for removal due to the actual removal of ones earlier in the list. imipweb-client-simplification
     1 imip-agent
     2 ==========
     3 
     4 This software implements an agent that can interpret e-mail messages
     5 containing calendar information, maintain availability records for scheduling
     6 participants, act on behalf of resources and other entities that need to
     7 participate in scheduling, and support user interfaces for end-users whose
     8 e-mail programs do not understand calendar data.
     9 
    10 Getting Started
    11 ===============
    12 
    13 Eventually, this information should be incorporated into packages for various
    14 operating system distributions, and these instructions should be largely
    15 superfluous for most users.
    16 
    17 System User and Filesystem Access
    18 =================================
    19 
    20 The data handled by imip-agent needs to be accessible to other software,
    21 notably mail handling software and Web server software. Two approaches are
    22 described here: LMTP delivery and local SMTP delivery.
    23 
    24 LMTP Delivery
    25 -------------
    26 
    27 Here, imip-agent's programs run in a way that permits LMTP delivery (requiring
    28 suitable local privileges to communicate with the mail storage solution)
    29 whilst allowing the Web server to read data written by those programs.
    30 
    31 A system group needs to be created for LMTP delivery and for certain users to
    32 share resources:
    33 
    34   addgroup lmtp
    35 
    36 This group should be employed for LMTP delivery by systems like Cyrus and
    37 Dovecot. See the section on configuring mail systems for delivery for more
    38 information.
    39 
    40 A system user needs to be created and to belong to certain groups in order to
    41 deliver messages to mail stores and to publish resources on the Web:
    42 
    43   useradd -d /var/lib/imip-agent -m -U -G lmtp,www-data -r imip-agent
    44 
    45 Store details and published resources need to be accessible by the imip-agent
    46 and www-data users. Thus, www-data also needs to belong to the lmtp group:
    47 
    48   adduser www-data lmtp
    49 
    50 Stored and published data is then initialised using the tools/init.sh script.
    51 The script employs the setgid flag on the directories initialised for stored
    52 and published data so that new files and directories have the appropriate
    53 group associated with them.
    54 
    55 It should be possible to omit all arguments to the init.sh script, but it is
    56 also worth reading the help message:
    57 
    58   tools/init.sh --help
    59 
    60 Fixing ownership can be done using the tools/fix.sh script, in case some form
    61 of modification has altered the ownership or membership of the created files
    62 and directories.
    63 
    64 Local SMTP Delivery
    65 -------------------
    66 
    67 Here, imip-agent's programs run in a way that permits local SMTP delivery
    68 (which merely needs the ability to connect to a local network service) whilst
    69 allowing the Web server to read data written by those programs.
    70 
    71 A system user needs to be created and to belong to certain groups in order to
    72 deliver messages to mail stores and to publish resources on the Web:
    73 
    74   useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent
    75 
    76 Again, the tools/init.sh script will initialise directories for stored and
    77 published data. For example:
    78 
    79   tools/init.sh imip-agent www-data
    80 
    81 Installing the Software
    82 =======================
    83 
    84 The tools/install.sh script should install the software in appropriate
    85 locations. See the prerequisites below for other software that will be
    86 required.
    87 
    88 Configuring Other Software
    89 ==========================
    90 
    91 The conf directory contains subdirectories for different systems:
    92 
    93   apache        Apache 2 site configuration for publishing resources
    94   cron          Cron command scheduling for free/busy updates
    95   exim          Exim 4 routing and transport configuration
    96   postfix       Postfix routing and transport configuration
    97 
    98 Either Exim or Postfix can be chosen as a mail system supporting the agent.
    99 
   100 Configuring Mail Systems for the Agent
   101 --------------------------------------
   102 
   103 The essential aspect of mail system configuration involves mail transports and
   104 the integration of agent programs into the mail processing pipeline. Thus, the
   105 following files are of particular interest:
   106 
   107 For Exim (in conf/exim)...
   108 
   109   30_exim4-config_people                Integration of agent programs
   110   30_exim4-config_people_outgoing       ...
   111   30_exim4-config_resources             ...
   112 
   113 For Postfix (in conf/postfix)...
   114 
   115   master.cf.items                       Integration of agent programs (for
   116                                         inclusion in master.cf)
   117   transport                             Configuration of agent transports
   118   virtual                               Configuration of outgoing mail routing
   119 
   120 Such files need adjusting for the deployment environment so that, for example,
   121 the example.com domain would be replaced with a suitable value.
   122 
   123 Where $lmtp_socket is employed, a suitable filesystem path is required; see
   124 below for a discussion of LMTP and mail delivery.
   125 
   126 Configuring Mail Systems for Mail Recipients
   127 --------------------------------------------
   128 
   129 The software should operate independently of the way mail recipients are
   130 identified in any given mail system, and thus does not dictate things such as
   131 routing or account querying. However, example configuration files are provided
   132 that demonstrate the use of LDAP to identify mail recipients:
   133 
   134 For Exim (in conf/exim)...
   135 
   136   010_exim4-config_people_outgoing          Defines recipients and outgoing
   137                                             mail routing
   138   890_exim4-config_ldap_people              ...
   139   890_exim4-config_ldap_resources           ...
   140 
   141 For Postfix with LDAP (in conf/postfix/ldap)...
   142 
   143   main.cf.example                           Defines recipients and outgoing
   144                                             mail routing (for inclusion in
   145                                             main.cf)
   146 
   147   virtual_alias_maps_people.cf              Defines recipients and outgoing
   148   virtual_alias_maps_people_outgoing.cf     mail routing
   149   virtual_alias_maps_resources.cf           ...
   150 
   151 Since the use of LDAP can be somewhat challenging and also excessive in some
   152 situations, examples of maintaining recipient information using a simpler
   153 approach are provided:
   154 
   155 For Postfix without LDAP (in conf/postfix/simple)...
   156 
   157   main.cf.example                           Defines recipients and outgoing
   158                                             mail routing (for inclusion in
   159                                             main.cf)
   160 
   161   virtual_alias_maps                        Defines recipients and outgoing
   162   virtual_alias_maps_people_outgoing        mail routing
   163 
   164 In this simpler environment, recipient details must be manually edited in the
   165 virtual alias map files, but this permits a very transparent way of
   166 administering the system. To add support for delivery to local mailboxes, the
   167 following alternative to virtual_alias_maps is provided as an example:
   168 
   169   virtual_alias_maps_local                  Defines recipients and local users
   170 
   171 Naturally, the above recipient identification configuration examples can be
   172 disregarded in favour of other ways of defining mail recipients, subject to
   173 the needs of any given environment.
   174 
   175 LDAP Representations for Mail Recipients
   176 ----------------------------------------
   177 
   178 Relevant LDAP resources for structuring recipient information include the
   179 following:
   180 
   181   RFC 4524                                  Defines the mail attribute
   182   http://tools.ietf.org/html/rfc4524
   183 
   184   RFC 2798                                  Defines the inetOrgPerson object
   185   http://tools.ietf.org/html/rfc2798        class
   186 
   187   RFC 2739                                  Defines the calEntry object class
   188   https://tools.ietf.org/html/rfc2739       supporting calFBURL
   189 
   190 An additional draft RFC describes the mailRecipient object class:
   191 
   192   https://tools.ietf.org/html/draft-lachman-ldap-mail-routing-03
   193 
   194 Resource schemas for LDAP are not effectively standardised for the purposes of
   195 this software. A useful object class, inetResource, was defined for the
   196 iPlanet Calendar Server:
   197 
   198   http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqrf/index.html#anocg
   199   http://docs.oracle.com/cd/E19566-01/819-4437/6n6jckqr8/index.html
   200 
   201 Although Kolab maintains notions of resources, they are tied up with the
   202 notion of a shared folder and the kolabSharedFolder object class, although the
   203 mailRecipient object class is employed by resources in Kolab.
   204 
   205 Configuring Mail Systems for Mail Delivery
   206 ------------------------------------------
   207 
   208 The agent software assumes that delivery of mail to recipients may be
   209 performed using LMTP to a suitable mailbox provider. This is largely beyond
   210 the scope of this document, but systems such as Cyrus and Dovecot can be
   211 configured to provide a Unix domain socket offering support for LMTP
   212 connections.
   213 
   214 For Cyrus, the following bug report is pertinent:
   215 
   216 https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=494746
   217 
   218 A permanent change in permissions on the Cyrus LMTP socket is therefore
   219 required to make delivery available to the lmtp group:
   220 
   221   dpkg-statoverride --force --update --add \
   222     cyrus lmtp 750 /var/run/cyrus/socket
   223 
   224 Configuring Cron for Free/Busy Updates
   225 --------------------------------------
   226 
   227 The periods occupied by recurring events are not expanded beyond a certain
   228 window of time by imip-agent. As a consequence, free/busy collections need to
   229 be progressively expanded over time to include periods occupied by such events
   230 that were not previously recorded in those collections.
   231 
   232 The conf/cron/cron.daily/imip-agent file contains commands that update
   233 free/busy collections for all known users, and this should be copied to the
   234 appropriate destination. For example:
   235 
   236 cp conf/cron/cron.daily/imip-agent /etc/cron.daily/
   237 
   238 Where frequency-specific directories are not supported by cron on a system, a
   239 crontab entry of the appropriate format is required instead.
   240 
   241 Configuring Web Servers for Free/Busy Publishing
   242 ------------------------------------------------
   243 
   244 Each user may request the publishing of their free/busy information by
   245 configuring certain settings. The conf/apache/imip-agent.conf file provides a
   246 configuration file for deployment with the Apache Web server software that
   247 exposes a directory for Web publishing containing the published free/busy
   248 information.
   249 
   250 Access to free/busy information may not be moderated, but Web server
   251 directives can be introduced to impose access controls. Mail programs that
   252 wish to consult the free/busy information may have problems in dealing with
   253 authentication mechanisms, however, and it may be regarded as acceptable in
   254 certain environments to expose such information publicly or with
   255 network-specific access constraints.
   256 
   257 Configuring Web Servers for the Calendar Management Interface
   258 -------------------------------------------------------------
   259 
   260 A calendar management interface is provided to allow users to view and
   261 interact with their calendars through the Web. The
   262 conf/apache/imip-manager.conf file provides a configuration file for
   263 deployment with the Apache Web server software that enables this interface.
   264 
   265 Since such access to calendars should only be performed by identified
   266 users, access controls are suggested in the configuration file.
   267 
   268 Prerequisites
   269 =============
   270 
   271 Depending on the mail transport agent (MTA) chosen, the following packages are
   272 required for this software to work on Debian systems:
   273 
   274   Exim:    exim4-daemon-heavy
   275   Postfix: postfix postfix-ldap
   276 
   277 The software itself requires the following packages:
   278 
   279   pytz:    python-tz
   280 
   281 The management Web interface requires the following packages:
   282 
   283   Babel:   python-babel