Recent changes to Configuration

Configuration modified by Sebastian Reitenbach

Sebastian Reitenbach — Wed, 07 May 2014 13:28:18 -0000

--- v5
+++ v6
@@ -71,7 +71,7 @@

 ### 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/bin/ogoaptnotify >/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.
+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”.

Configuration modified by Sebastian Reitenbach

Sebastian Reitenbach — Wed, 07 May 2014 13:25:05 -0000

--- v4
+++ v5
@@ -71,7 +71,7 @@

 ### 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/bin/oogaptnotify >/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.
+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/bin/ogoaptnotify >/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”.

Configuration modified by Sebastian Reitenbach

Sebastian Reitenbach — Wed, 07 May 2014 13:12:26 -0000

--- v3
+++ v4
@@ -71,10 +71,10 @@

 ### Configuring Reminder Notification ###

-Reminder e-mails concerning upcoming appointments are sent by the skyaptnotify utility which is provided by the ogo-tools package.  skyaptnotify 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/bin/skyaptnotify >/dev/null”'.  If this cron job is executed as root su will be able to switch to the ogo user without a password.  skyaptnotify must execute in the same context as the server processes as it writes to log files and requires defaults.
+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/bin/oogaptnotify >/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 skyaptnotify contains five defaults: “AptNotifyFromAddress”, “AptNotifySentResourcesFile”, “AptNotifySkyrixPassword”, “AptNotifySkyrixUser”, and “AptNotifyVerbose”. 
+The default configuration of ogoaptnotify contains, besides some others, six important defaults: “AptNotifyFromAddress”, “AptNotifySentResourcesFile”, “AptNotifyOGoPassword”, “AptNotifyOGoUser”, “AptNotifySendmailPath” and “AptNotifyVerbose”. 

-AptNotifySkyrixUser and AptNotifySkyrixPassword 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.
+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.

WikiPage Configuration modified by Sebastian Reitenbach

Sebastian Reitenbach — Tue, 08 Jan 2013 18:41:39 -0000

--- v2
+++ v3
@@ -1,74 +1,80 @@
 OpenGroupware basic configuration
 =================================

-The general configuration of OGo is done as the previously created OGo user.
-All commands are assumed to be done as that user below.
-The configuration is done using the GNUstep defaults tool. 
+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.

-Database
---------
+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.

-    defaults write NSGlobalDomain LSConnectionDictionary '{ \
-        databaseName = OGo; \
-        hostName = "127.0.0.1"; \
-        password = ""; \
-        port = 5432; \
-        userName = OGo; \
-    }'
+The service specific domains are the following:

-LDAP Authentication
--------------------
+ * ogo-webui for the web interface
+ * ogo-xmlrpcd for the XML-RPC provider
+ * ogo-zidestore for the ZideStore integration service

-    defaults write NSGlobalDomain LDAPInitialBindSpecific YES
-    defaults write NSGlobalDomain LDAPLoginAttributeName uid
-    defaults write NSGlobalDomain LSAuthLDAPServerPort 389
-    defaults write NSGlobalDomain LSAuthLDAPServerRoot ou=People,dc=my-domain.de
-    defaults write NSGlobalDomain LSAuthLDAPServer 127.0.0.1
+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.

-Mail
-----
+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.

-    defaults write NSGlobalDomain imap_host 127.0.0.1
-    defaults write NSGlobalDomain UseSkyrixLoginForImap YES
-    defaults write NSGlobalDomain EnableSieveFilter YES
-    defaults write NSGlobalDomain WOSendMail /usr/local/sbin/sendmail
-    defaults write NSGlobalDomain EnableSSSortingForStringAttributes YES
+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.

-Other general configuration
----------------------------
+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.

-    defaults write NSGlobalDomain LSNewsImagesUrl /NewsImages
-    defaults write NSGlobalDomain LSNewsImagesPath /srv/www/htdocs/NewsImages
-    defaults write NSGlobalDomain LSAttachmentPath /var/opengroupware/documents
-    defaults write NSGlobalDomain WOMessageUseUTF8 YES
-    defaults write NSGlobalDomain WOParsersUseUTF8 YES
-    defaults write NSGlobalDomain NGUseUTF8AsURLEncoding YES
+### Setting The Administrative Password ###

-In case some tools may not be available in the default path:
+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.

-    defaults write NSGlobalDomain zip /usr/local/bin/zip
-    defaults write NSGlobalDomain unzip /usr/local/bin/unzip
-    defaults write NSGlobalDomain tar /usr/local/bin/gtar
-    defaults write NSGlobalDomain zipinfo /usr/local/bin/zipinfo
+### Setting the skyrix_id ###

-Some daemon specific configuration
-----------------------------------
-    defaults write ogo-webui WOPidFile /var/opengroupware/ogo-webui.pid
-    defaults write ogo-webui WOLogFile /var/log/opengroupware/ogo-webui.log
-    defaults write ogo-webui WOPort 20000
-    defaults write ogo-zidestore WOPidFile /var/opengroupware/ogo-zidestore.pid
-    defaults write ogo-zidestore WOLogFile /var/log/opengroupware/ogo-zidestore.log
-    defaults write ogo-zidestore WOPort 21000
-    defaults write ogo-xmlrpcd WOLogFile /var/log/opengroupware/ogo-xmlrpcd.log
-    defaults write ogo-xmlrpcd WOPidFile /var/opengroupware/ogo-xmlrpcd.pid
-    defaults write ogo-xmlrpcd WOPort 22000
+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 ###

-Cron Jobs
----------
+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 skyaptnotify utility which is provided by the ogo-tools package.  skyaptnotify 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/bin/skyaptnotify >/dev/null”'.  If this cron job is executed as root su will be able to switch to the ogo user without a password.  skyaptnotify must execute in the same context as the server processes as it writes to log files and requires defaults.
+
+The default configuration of skyaptnotify contains five defaults: “AptNotifyFromAddress”, “AptNotifySentResourcesFile”, “AptNotifySkyrixPassword”, “AptNotifySkyrixUser”, and “AptNotifyVerbose”. 
+
+AptNotifySkyrixUser and AptNotifySkyrixPassword 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.

WikiPage Configuration modified by Sebastian Reitenbach

Sebastian Reitenbach — Thu, 03 Jan 2013 14:25:21 -0000

--- v1
+++ v2
@@ -1,5 +1,14 @@
 OpenGroupware basic configuration
 =================================
+
+The general configuration of OGo is done as the previously created OGo user.
+All commands are assumed to be done as that user below.
+The configuration is done using the GNUstep defaults tool. 
+
+    defaults help
+
+will give you a short overview how it has to be used.
+

 Database
 --------

WikiPage Configuration modified by Sebastian Reitenbach

Sebastian Reitenbach — Thu, 03 Jan 2013 14:22:41 -0000

OpenGroupware basic configuration

Database

defaults write NSGlobalDomain LSConnectionDictionary '{ \
    databaseName = OGo; \
    hostName = "127.0.0.1"; \
    password = ""; \
    port = 5432; \
    userName = OGo; \
}'

LDAP Authentication

defaults write NSGlobalDomain LDAPInitialBindSpecific YES
defaults write NSGlobalDomain LDAPLoginAttributeName uid
defaults write NSGlobalDomain LSAuthLDAPServerPort 389
defaults write NSGlobalDomain LSAuthLDAPServerRoot ou=People,dc=my-domain.de
defaults write NSGlobalDomain LSAuthLDAPServer 127.0.0.1

Mail

defaults write NSGlobalDomain imap_host 127.0.0.1
defaults write NSGlobalDomain UseSkyrixLoginForImap YES
defaults write NSGlobalDomain EnableSieveFilter YES
defaults write NSGlobalDomain WOSendMail /usr/local/sbin/sendmail
defaults write NSGlobalDomain EnableSSSortingForStringAttributes YES

Other general configuration

defaults write NSGlobalDomain LSNewsImagesUrl /NewsImages
defaults write NSGlobalDomain LSNewsImagesPath /srv/www/htdocs/NewsImages
defaults write NSGlobalDomain LSAttachmentPath /var/opengroupware/documents
defaults write NSGlobalDomain WOMessageUseUTF8 YES
defaults write NSGlobalDomain WOParsersUseUTF8 YES
defaults write NSGlobalDomain NGUseUTF8AsURLEncoding YES

In case some tools may not be available in the default path:

defaults write NSGlobalDomain zip /usr/local/bin/zip
defaults write NSGlobalDomain unzip /usr/local/bin/unzip
defaults write NSGlobalDomain tar /usr/local/bin/gtar
defaults write NSGlobalDomain zipinfo /usr/local/bin/zipinfo

Some daemon specific configuration

defaults write ogo-webui WOPidFile /var/opengroupware/ogo-webui.pid
defaults write ogo-webui WOLogFile /var/log/opengroupware/ogo-webui.log
defaults write ogo-webui WOPort 20000
defaults write ogo-zidestore WOPidFile /var/opengroupware/ogo-zidestore.pid
defaults write ogo-zidestore WOLogFile /var/log/opengroupware/ogo-zidestore.log
defaults write ogo-zidestore WOPort 21000
defaults write ogo-xmlrpcd WOLogFile /var/log/opengroupware/ogo-xmlrpcd.log
defaults write ogo-xmlrpcd WOPidFile /var/opengroupware/ogo-xmlrpcd.pid
defaults write ogo-xmlrpcd WOPort 22000