git.sur5r.net Git - contagged/blob - doc/README

   1 === ABOUT ===
   2
   3 ConTagged is a webbased address book for small companies. It features a public
   4 address book which is writable for all company staff and a personal address
   5 book for each staff member. ConTagged requires an already setup LDAP server to
   6 authenticate users and store it's data.
   7
   8 === REQUIREMENTS ===
   9
  10 You need to have a running LDAP Server with some users (objectClass=posixUser)
  11 in it. It is important that you already have these users because LDAPab uses
  12 them to authenticate.
  13
  14 You need a webserver (peferable Apache) with PHP (4.3 or higher). PHP needs to
  15 be compiled with LDAP support (compiled in or as extension)
  16
  17 === SETUP ConTagged ===
  18
  19 Copy the contents of the .tgz file to a directory below your webserver document
  20 root. Make sure the webserver is able to write to the cache directory which is
  21 used for the template engine's cache files. A 'chmod 777 cache' will do.
  22
  23 Copy the inc/config.phpi.dist file to inc/config.php file and open it in your
  24 favourite editor and edit the options according to your needs. Some knowlege
  25 about LDAP may come in handy.
  26
  27 If HTTP auth is wanted have a look at the provided _htaccess file, edit it as
  28 needed and rename it back to .htaccess
  29
  30 === SETUP THE LDAP SERVER ===
  31
  32 The following only describes what to do for open-ldap 2.0! If you use any
  33 other LDAP server you're left to our own.
  34
  35 You need to include the inetOrgPerson schema in you slapd.conf:
  36
  37   include /etc/ldap/schema/inetorgperson.schema
  38
  39 If you want to use the extended schema (needed for tagging) you need to copy the
  40 ldapab.schema file to /etc/ldap/schema/ and include it, too.
  41
  42   include         /etc/ldap/schema/ldapab.schema
  43
  44 If you don't use the extended schema, remove the contactPerson from the object
  45 classes array in the config.
  46
  47 To setup the access rights add the following statement to your slapd.conf. Of
  48 course you have to replace "o=cosmocode,c=de" with your own root DN. The first
  49 entry may have to adjusted also if your users aren't stored in a ou=people
  50 entry. Make sure you include these lines before other access control lists that
  51 match these parts of the ldap tree. If you are unsure have a look at the
  52 included slapd.example file
  53
  54   access  to dn.regex="(.*,)?ou=contacts,cn=([^,]+),ou=people,(.*)$"
  55           by dn.regex="cn=$2,ou=people,$3" write
  56           by * none
  57
  58   access to dn.subtree="ou=contacts,o=cosmocode,c=de"
  59          by users write
  60          by * read
  61
  62 After this modifications you have to restart the slapd server.
  63
  64 The last thing is to add the contacts leafs to your LDAP tree. You'll need to
  65 add a global contacts leaf at top.
  66
  67   eg: 'ou=contacts,o=cosmocode,c=de'
  68
  69 And a contacts leaf for every user.
  70
  71   eg: 'ou=contacts,cn=Joe Schmoe,ou=people,o=cosmocode,c=de'
  72
  73
  74 If you made everything correct you can point your webbrowser to the newly
  75 installed ConTagged and use it :-) If you encounter problems try to enable
  76 logging in your LDAP server to see what the problem is.
  77
  78 === USING DIFFERENT OBJECTCLASSES ===
  79
  80 This new version of ConTagged is very flexible in how your contacts should be
  81 stored in your LDAP directory. ConTagged uses internal field names which can be
  82 mapped to arbitrary LDAP attributes.
  83
  84 By default, all contacts are stored with the inetOrgPerson and contactPerson
  85 object classes. If you want to use different classes and attributes, you can
  86 add objectClasses in the 'oclasses' config option and custom fields in the
  87 'customFields' option. Also have a look at the inc/fields.php file to understand
  88 what additional mappings are available.
  89
  90 Note: your contacts should *always* use the inetOrgPerson objectclass at
  91 minimum, but you can add any other objectclasses. OXUserObject from OpenExchange
  92 and evolutionPerson from the Evolution software are set up in already and can
  93 simply be enabled by using the right config class in config.php.
  94
  95 If you want to add new internal field names, you need to adjust the templates
  96 accordingly. If you add support for new schemas, please send your changes to
  97 us for inclusion in a next release.
  98
  99 === FEEDBACK, PATCHES, SUPPORT ===
 100
 101 This software was developed to satisfy a need in our company. We give it to the
 102 public because it may be helpful to other companies with the same needs.
 103 However this is not a supported product. We like to get feedback and patches
 104 but we can't promise to answer, to fix bugs or include feature wishes. However
 105 don't hesitate to contact us but understand that our core business has priority
 106 over this project.
 107
 108 We prefer to receive bug reports and features wishes through the issue tracker
 109 at http://github.com/cosmocode/contagged/issues. If you want to otherwise
 110 contact us, send a mail to ldapab@cosmocode.de or visit our homepage at
 111 http://www.cosmocode.de
 112
 113 === KNOWN BUGS ===
 114
 115 ConTagged was only tested with open-ldap 2.1 - there may be problems with other
 116 LDAP Servers.
 117
 118 === LICENSE ===
 119
 120 ConTagged - An LDAP based Company Address Book
 121 Copyright 2004 - 2014 - CosmoCode GmbH
 122
 123 This program is free software; you can redistribute it and/or
 124 modify it under the terms of the GNU General Public License as
 125 published by the Free Software Foundation; either version 2 of
 126 the License, or (at your option) any later version.
 127
 128 This program is distributed in the hope that it will be useful,
 129 but WITHOUT ANY WARRANTY; without even the implied warranty of
 130 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 131 GNU General Public License for more details.
 132
 133 You should have received a copy of the GNU General Public License
 134 along with this program; if not, write to the Free Software
 135 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 136
 137 See COPYING for details