Configuration settings

From Davical
Revision as of 17:19, 29 December 2016 by Fsfs (Talk | contribs) (typo)

Jump to: navigation, search

As well as reading the details below, also consider looking at Configuration/settings which is the index into the wiki pages listing each individual setting, and where these settings will be maintained more exhaustively in the future.

Mandatory Settings

pg_connect

Ex : $c->pg_connect[] = 'dbname=davical port=5432 user=general'

The application will attempt to connect to the database, successively applying connection parameters from the array in $c->pg_connect.

used in the web interface but also the caldav Server

$c->pg_connect[] = "dbname=davical user=davical_app";

As well as setting dbanme and user, PostgreSQL accepts values for port, host, password and maybe even more - check the PostgreSQL docs if you need something really odd.

Note: From version 0.9.9.4 there is an alternate syntax available (though the old one will continue to work) which is:

 $c->db_connect[] = array( 'dsn' => 'pgsql:dbname=davical port=5432 host=dbhost', 'dbuser' => 'davical_app', 'dbpass' => 'fred' );

Or, for a local DB on the default port with trustauthentication:

 $c->db_connect[] = array( 'dsn' => 'pgsql:dbname=davical', 'dbuser' => 'davical_app' );


Desirable

system_name

See here.

Domain Settings

See here.

Localization

/**
* The default locale will be "en";
* If you are in a non-English locale, you can set the default_locale
* configuration to one of the supported locales.
*
* Supported Locales (at present, see: "select * from supported_locales ;" for a full list)
*
* "de_DE", "en_NZ", "es_AR", "fr_FR", "nl_NL", "ru_RU"
*
* If you want locale support you probably know more about configuring it than me, but
* at this stage it should be noted that all translations are UTF-8, and pages are
* served as UTF-8, so you will need to ensure that the UTF-8 versions of these locales
* are supported on your system.
*
* People interested in providing new translations are directed to the Wiki:
*   http://rscds.sourceforge.net/moin/TranslatingRscds
**/
// $c->default_locale = "en_NZ";

hide_TODO

See here.

readonly_webdav_collections

See here.

admin_email

See here.

default_relationships

See here.

Probably Not Needed

enable_row_linking

default=true

If true the admin web interface will have link on name to access details

The "enable_row_linking" option controls whether javascript is used to make the entire row clickable in browse lists in the administration pages. Since this didn't work with Konqueror at some point in the past you may want to set this to false if people experience problems using the DAViCal administration pages.

$c->enable_row_linking = true;

local_styles

These should be an array of style sheets with a path specified relative to the root directory. These settings can be used for overriding display styles in the admin interface.

e.g. : $c->local_styles = array('/css/my.css');

$c->local_styles = array();
$c->print_styles = array();

home_calendar_name

See here.

Probably a Bad Idea

collections_always_exist

The "collections_always_exist" value defines whether a MKCALENDAR command is needed to create a calendar collection before calendar resources can be stored in it. This should not be required since each created user will have a calendar created for them. The default is 'false'.

// $c->collections_always_exist = true;

hide_alarm

See here.

allow_get_email_visibility

See here.

External Authentication Sources

To allow specifying another way to control access by authenticating the user against external authentication sources such as LDAP (the default is the PgSQL DB), $c->authenticate_hook['call'] should be set to the name of a user-defined function (usually included from one of the drivers_*.php files) that will be called like this: call_user_func( $c->authenticate_hook['call'], $username, $password )

This login mechanism is used in 2 places:

  • for the web interface in: index.php that calls DAViCalSession.php that extends Session.php (from AWL libraries)
  • for the caldav client in: caldav.php that calls BasicAuthSession.php

Both Session.php and BasicAuthSession.php check against the authenticate_hook['call'], although for BasicAuthSession.php this will be for every request. For Session.php this will only occur once during login.

$c->authenticate_hook['config'] should be set up with any configuration data needed by the authentication driver.

In case the login via the external authentication method is just optional (e.g. to allow access to users that are not covered by that method, but are manually created in davical), the method has to be marked as optional

$c->authenticate_hook['optional']=true;

AuthPlugins.php contains implementations of two example authentication hooks, auth_external (still used for BASIC auth) and auth_other_awl.

General Example

/*
 * Other AWL hook
 */
require_once('auth-functions.php');

$c->authenticate_hook['call'] = 'AuthExternalAwl';
$c->authenticate_hook['config'] = array(
  // A PgSQL database connection string for the database containing user records
  'connection' => 'dbname=wrms host=otherhost port=5433 user=general',
  // Which columns should be fetched from the database
  'columns'    => "user_no, active, email_ok, joined, last_update AS updated, last_used, username, password, fullname, email",
  // a WHERE clause to limit the records returned.
  'where'    => "active AND org_code=7"
);

LDAP / OpenLDAP

$c->authenticate_hook['call'] = 'LDAP_check';
$c->authenticate_hook['config'] = array(
  'host' => 'www.tennaxia.net', //host name of your LDAP Server
  'port' => '389',              //port

  /* For the initial bind to be anonymous leave bindDN and passDN
     commented out */
  // DN to bind to this server enabling to perform request
  'bindDN'=> 'cn=manager,cn=internal,dc=tennaxia,dc=net',
  // Password of the previous bindDN to bind to this server enabling to perform request
  'passDN'=> 'xxxxxxxx',

  'protocolVersion' => '3', //Version of LDAP protocol to use
  'baseDNUsers'=> 'dc=tennaxia,dc=net', //where to look at valid user
  'filterUsers' => 'objectClass=kolabInetOrgPerson', //filter which must validate a user according to RFC4515, i.e. surrounded by brackets
  'baseDNGroups' => 'ou=divisions,dc=tennaxia,dc=net', //not used ATM
  'filterGroups' => 'objectClass=groupOfUniqueNames', //not used ATM
   /** /!\ "username" should be set and "updated" must be set **/
  'mapping_field' => array("username" => "uid",
                           "updated" => "modifyTimestamp",
                           "fullname" => "cn" ,
                           "email" =>"mail"
                      ), //used to create the user based on his ldap properties
  /** used to set default value for all users, will be overcharged by ldap if defined also in mapping_field **/
  'default_value' => array("date_format_type" => "E","locale" => "fr_FR"),
  /** foreach key set start and length in the string provided by ldap
      example for openLDAP timestamp : 20070503162215Z **/
  'format_updated'=> array('Y' => array(0,4),'m' => array(4,2),'d'=> array(6,2),'H' => array(8,2),'M'=>array(10,2),'S' => array(12,2)),

  'startTLS' => 'yes',  // Require that TLS is used for LDAP?
   // If ldap_start_tls is not working, it is probably
   // because php wants to validate the server's
   // certificate. Try adding "TLS_REQCERT never" to the
   // ldap configuration file that php uses (e.g. /etc/ldap.conf
   // or /etc/ldap/ldap.conf). Of course, this lessens security!

  'scope' => 'subtree', // Search scope to use, defaults to subtree.
                        // Allowed values: base, onelevel, subtree.
);

include('drivers_ldap.php');

Apache Module does the Authentication

In this situation we just want to pull the username from the headers that Apache gives us. You can use this for Kerberos or many other forms of authentication just fine.

/*
 * Use Apache-supplied headers and believe them
 */
 $c->authenticate_hook['server_auth_type'] = 'Basic';
 include_once('AuthPlugins.php');

This will make the HTTP Basic Authentication from the webserver be used and trusted for authentication within both, the administration websites and CalDAV (i.e. caldav.php). Note: It seems that the "include_once('AuthPlugins.php');" is not necessary if this should only apply to the administration websites but not to CalDAV (i.e. caldav.php).

The server_auth_type setting must match the value provided by the webserver in the AUTH_TYPE environment variable. DAViCal will look for the username of the authenticated user in the REMOTE_USER (and beginning with 1.1.2 REDIRECT_REMOTE_USER) environment variable.

Note that this method does not pull any account details from anywhere, so you will still need to create an account in DAViCal for each username that will authenticate in this way - just that the password on that account will be ignored and authentication will happen through the authentication method that Apache is configured with.


When PHP is used as CGI/FastCGI with Apache and mod_ssl, then currently AUTH_TYPE remains unset, even when HTTP Basic Authentication (respectively mod_ssl fakeBasicAuth) was done by the server. This is a bug in Apache and/or limitation in the CGI specification. One workaround is an intermediate CGI wrapper, which sets AUTH_TYPE unconditionally to e.g. "Basic" (currently (see [1] and [2]) this is case-sensitive in contrast to the CGI spec).

Active Directory (AD)

/*
 * Use the following LDAP example if you are using Active Directory
 *
 * You will need to  change host, passDN and DOMAIN in bindDN and baseDNUsers.
 */
$c->authenticate_hook['call'] = 'LDAP_check';
$c->authenticate_hook['config'] = array(
  'host'              => 'ldap://ldap.example.net',
  'bindDN'            => 'auth@DOMAIN',
  'passDN'            => 'secret',
  'baseDNUsers'       => 'dc=DOMAIN,dc=local',
  'protocolVersion'   => 3,
  'optReferrals'      => 0,
  'filterUsers'       => '(&(objectcategory=person)(objectclass=user)(givenname=*))',
  'mapping_field'     => array("username" => "uid",
                               "fullname" => "cn" ,
                               "email"    => "mail"),
  'default_value'     => array("date_format_type" => "E","locale" => "en_NZ"),
  'format_updated'    => array('Y' => array(0,4),'m' => array(4,2),'d'=> array(6,2),'H' => array(8,2),'M'=>array(10,2),'S' => array(12,2))
);

include('drivers_ldap.php');

Pluggable Authentication Modules (PAM)

Allows directly authenticating existing system users. There are two options: PWauth or Squid.

Both methods require that the password is transmitted in plain-text. Requiring encrypted connections with TLS is strongly recommended. PWauth's wiki page on security risks is recommended reading before offering to authenticate system users.

Setting the email_base is required, but whether it is used or not depends on how accounts are authenticated on the system.


PWauth

Installing the Debian/Ubuntu package (available in each distribution's respective 'universe' repositories) will offer authentication against PAM out of the box.

/**
 * Authentication against PAM using the PWauth helper program.
 */
$c->authenticate_hook['call'] = 'PWAUTH_PAM_check';
$c->authenticate_hook['config'] =  array(
  'path' => '/usr/sbin/pwauth',
  'email_base' => 'example.com'
);

include('drivers_pwauth_pam.php');

Other distributions may have alternate paths to the helper program. Locate it using the whereis command after installing.

Squid

Requires that Squid is configured to offer PAM authentication. Not covered by this documentation.

/**
 * Authentication against PAM using the Squid helper script.
 */
$c->authenticate_hook['call'] = 'SQUID_PAM_check';
$c->authenticate_hook['config'] =  array(
  'script' => '/usr/bin/pam_auth',
  'email_base' => 'example.com'
);

include('drivers_squid_pam.php');