Configuration

OpenGroupware basic configuration

This section covers the basic concepts and utilities required to configure the OpenGroupware groupware server and its various services. This section does not include coverage of package installation as this is highly distribution specific. Installing the OpenGroupware packages is not significantly any different then installing packages for any other network service; you must be familiar with your distributions package management tools.

For the sake of simplicity the following items are assumed:

• The OpenGroupware system account is named “ogo”
• The “ogo” account has a home directory of “/var/opengroupware”
• The OpenGroupware packages are installed into “/usr/local”
• The PostgreSQL database used by the OpenGroupware services is named “OGo.”

If any of the above are different in your configuration you will need to compensate accordingly.

Configuration basics

The OpenGroupware server architecture descends from GNUstep and shares much in common with that platform. One similarity is the use of “defaults” for configuration. Defaults are a hierarchy of domains containing key value pairs, and almost all configuration of the OpenGroupware services is performed by setting, changing, and removing defaults. An individual setting within a domain is simply referred to as a “default”.

Defaults are modified using the command line utility “defaults” that is provided by the gnustep-base package. Simply running “defaults help” will produce a helpful enumeration of the various options; you will see that the defaults command can display defaults (read), create or modify defaults (write), as well as remove values (delete).

defaults help

will give you a short overview how it has to be used.

It is important to understand that defaults are per-user-context on the server. If you wish to edit defaults for the OpenGroupware service you must execute the defaults command as the same user the server process runs as. If your packages created the “OGo” user system account then you must su to that account in order to configure the OpenGroupware services. The domains managed by the defaults command are stored as plist1 files in a directory under the home directory of the current user. So if the home directory of the “OGo” user is “/var/opengroupware” then the plist files exist in the “/var/opengroupware/GNUstep/Defaults/” directory. While the plist files are merely structured XML files, they should always be modified and viewed using the defaults utility, and not by hand. There is one plist file for each domain, and the contents of that file are the defaults established for that domain.

Each OpenGroupware service is a defaults domain. So there is a domain for the web interface, ZideStore, etc... In addition to the domain for each service there is a global domain called “NSGlobalDomain”. Setting a default in the global domain makes that default apply to all services unless explicitly overridden in the application domain. Even the NSGlobalDomain is still specific to user account where the default was defined, it is global simply in the sense that it applies to all services that run as that user.

The service specific domains are the following:

• ogo-webui for the web interface
• ogo-xmlrpcd for the XML-RPC provider
• ogo-zidestore for the ZideStore integration service

If you execute “defaults read” as the the OpenGroupware system account you should see a list of all defined defaults for each domain with the contents of each domain enclosed in opening and closing curly braces. To view defaults within a specific domain the syntax of “Defaults read {domain}” syntax can be used; and to view the value of a specific default add the name of the default.

To modify or add a default you would execute: “defaults write domain-name default-name default-value”. If a default of the same name already exists in the specified domain it is overwritten, otherwise a new default is created. For instance, if you wanted to set a default called “LSUseBasicAuthentication” to a value of “YES” within the “ogo-webui” domain you would execute: “defaults write ogo-webui LSUseBasicAuthentication YES”. The default LSUseBasicAuthentication would be created in the ogo-webui domain if it was not already set, or it would overwrite the previous value of LSUseBasicAuthentication within the ogo-webui domain.

To read back the value of that particular default you would execute: “defaults read ogo-webui LSUseBasicAuthentication” and the command would return the output of “YES”. You can also list all the defaults contained in a specific domain by simply leaving out the default name: “defaults read ogo-webui” would display all the defaults in the “ogo-webui” domain. “defaults read” simply displays all the configured domains and all default values within each of those domains.

To delete a default use the “delete” option followed by the default's domain and the default's name. This will delete just that default. If you wish to delete an entire domain use the delete option followed by the domain's name and no default name, as in “defaults delete ogo-webui” which would delete the entire “ogo-webui” defaults domain.

Since the defaults are critical to the operation of the OpenGroupware services the plist files should be backed up before and after any significant change. The files can be found in ~ogo/GNUstep/Defaults/ directory.

Post-Installation Tasks

After installing OpenGroupware and its dependencies, there are a number of tasks to be performed to prepare the service for production deployment.

Setting The Administrative Password

After installation if you visit the web interface1 you will automatically be logged in as “root” without being prompted for a username or password2. The web interface operates in this manner until you set a password for the administrative account. Once you set a password for this account and logout you will be prompted for a username and password, and allowed to login as an ordinary user account.

Setting the skyrix_id

Each OpenGroupware server on a network has a unique name, which upon installation is defaulted to the host name. The server name is set by the “skyrix_id” default in the NSGlobalDomain. The value of “skyrix_id” should be a simple alphanumeric string with no whitespace.

Database connection configuration

The connection to the PostgreSQL database is established using the configuration stored in the contents of the “LSConnectionDictionary” default. For basic configuration your package manager will probably provide a workable default configuration; if you need to customize the configuration see the “Configuring The Database Connection” section of the “PostgreSQL” chapter.

Older versions of OpenGroupware used LATIN-1 encoding of the database,
more recent versions use a UTF-8 encoded database. If you need to migrate a LATIN-1 database to a current version of OpenGroupware you will need to migrate the database's encoding. For instructions on migrating the database see FAQ section of the “PostgreSQL” chapter.

Several values in the “postgresql.conf” file provided by your PostgreSQL packages are key to adequate performance. Especially the “shared_buffers” value. See the “Key Configuration Directives” section of the “PostgreSQL” chapter of this document for information on setting “shared_buffers” and other key directives to reasonable values.

Configuring IMAP Connectivity

If you do not have a centralized IMAP server with a unified user name space you do not need to configure anything in OpenGroupware concerning IMAP connectivity; OpenGroupware will prompt the user for the IMAP server host name, IMAP username, and their IMAP password when they attempt to access mail functionality. However, if you do have a centralized IMAP configuration you can specify the connection configuration on behalf of the user; such a configuration will make the integration with IMAP entirely seamless. See the “Configuring the IMAP Connection” section of the chapter entitled “Mail”.

Configuring Reminder Notification

Reminder e-mails concerning upcoming appointments are sent by the ogoaptnotify utility which is provided by the ogo-tools package. ogoaptnotify should be scheduled to run every five minutes. The simples way to accomplish this is to create a cron job with a command of 'su - ogo -c "/usr/local/bin/ogoaptnotify 2>/dev/null”'. If this cron job is executed as root su will be able to switch to the ogo user without a password. ogoaptnotify must execute in the same context as the server processes as it writes to log files and requires defaults.

The default configuration of ogoaptnotify contains, besides some others, six important defaults: “AptNotifyFromAddress”, “AptNotifySentResourcesFile”, “AptNotifyOGoPassword”, “AptNotifyOGoUser”, “AptNotifySendmailPath” and “AptNotifyVerbose”.

AptNotifyOGoUser and AptNotifyOGoPassword must be set to the OpenGroupware administrator's username and password, this allows the notification utility to see all appointments. If you change the password of the OpenGroupware administrator remember to update this default accordingly.

AptNotifyFromAddress is the address that appears in the “Return-Path” header of notification messages. Initially this is set to “ogo@local-host-name” which should be changed at least so the domain appears to users as the domain they typically associate with local mail.