SOGo

https://www.sogo.nu/files/docs/
Admin
SOGo is a free, scalable groupware server providing shared calendars, address books, and emails...
Tokens:30,731
Snippets:169
Trust Score:9.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Starting and Managing SOGo Services

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Commands to start, check status, and restart the SOGo service and Apache web server. Ensures that SOGo and its dependencies are running and configured to start on boot.

```bash
systemctl start sogod.service
systemctl is-enabled sogod
systemctl restart httpd.service
```

--------------------------------

### SOGo Database URL Examples for Different Databases

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Provides example database URLs for SOGo configuration parameters when using MariaDB/MySQL and Oracle, in addition to PostgreSQL.

```ini
SOGoProfileURL = "mysql://sogo:sogo@127.0.0.1:3306/sogo/sogo_user_profile";
OCSFolderInfoURL = "oracle://sogo:sogo@127.0.0.1:1526/sogo/sogo_folder_info";
OCSSessionsFolderURL = "postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_sessions_folder";
OCSEMailAlarmsFolderURL = "postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_alarms_folder";
OCSStoreURL = "postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_store";
OCSAclURL = "postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_acl";
OCSCacheFolderURL = "postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_cache_folder";
```

--------------------------------

### LDAP Hostname Examples

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Shows examples of valid LDAP URLs and hostnames for the 'hostname' parameter in SOGo configuration. It includes examples for plain LDAP, LDAPS, and STARTTLS using RFC 4516 format.

```configuration
hostname = "ldap://127.0.0.1:3389";
```

```configuration
hostname = "ldaps://127.0.0.1";
```

```configuration
hostname = "ldap://127.0.0.1/????!StartTLS";
```

--------------------------------

### sogo-tool user-preferences Get Defaults Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Provides an example of using the 'sogo-tool user-preferences' command to retrieve the 'Forward' default setting for 'user1'. It shows the expected output when the value is found and the message returned if it's not set.

```bash
sogo-tool user-preferences get defaults user1 Forward
```

```text
Value for key "Forward" not found in defaults
```

```json
{"forwardAddress":["sogo-tests2@sogo.alinto"],"enabled":1,"keepCopy":1}
```

--------------------------------

### SOGo SQL Directory Source Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

An example configuration for an SQL-based address book source in SOGo. It specifies the database connection details, authentication method, and whether it serves as an address book.

```ini
SOGoUserSources = (
  {
    type = sql;
    id = directory;
    viewURL = "postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_view";
    canAuthenticate = YES;
    isAddressBook = YES;
    userPasswordAlgorithm = md5;
  }
);

```

--------------------------------

### Create SOGo User LDIF Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

An LDIF file example for creating a SOGo user account. This file defines the user's attributes and object classes within the LDAP directory.

```ldif
dn: uid=jdoe,ou=users,dc=acme,dc=com
objectClass: top
objectClass: inetOrgPerson
objectClass: person
objectClass: organizationalPerson
uid: jdoe
cn: John Doe
mail: jdoe@acme.com
sn: Doe
givenName: John
```

--------------------------------

### SOGoMailJunkSettings Configuration Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Example configuration for SOGoMailJunkSettings, specifying junk mail handling parameters. This includes the vendor, email addresses for junk and non-junk mail, and a limit for attached mails.

```Objective-C
SOGoMailJunkSettings = {
	vendor = "generic";
	junkEmailAddress = "spam@foo.com";
	...
}
```

--------------------------------

### SOGo Configuration with Database Alias

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Example of how to use the database alias in the SOGo configuration file (/etc/sogo/sogo.conf) for the SOGoProfileURL.

```ini
SOGoProfileURL =
    "postgresql://sogo:sogo@db-alias:5432/sogo/sogo_user_profile";
```

--------------------------------

### SOGo ModulesConstraints Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Example demonstrating how to limit module access based on LDAP attributes using the ModulesConstraints parameter. This is useful for role-based access control within SOGo.

```gconfig
ModulesConstraints = {
	Calendar = {
		ou = employees;
	};
};
```

--------------------------------

### LDAP Filter Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Provides an example of an LDAP filter definition for SOGo, showcasing the use of OR and AND operators, parentheses for grouping, and attribute value quoting. It demonstrates filtering based on objectClass, accountStatus, and uid.

```configuration
filter = "(objectClass='mailUser' OR objectClass='mailGroup') AND accountStatus='active' AND uid <> 'alice'";
```

--------------------------------

### Install SOGo

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Installs the SOGo package and its core dependencies, such as GNUstep, SOPE, and memcached, using the `yum install` command. This is a fundamental step after setting up the repository.

```bash
yum install sogo
```

--------------------------------

### SOGo ActiveSync Configuration

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

This section outlines the steps to enable Microsoft ActiveSync in SOGo, including package installation, Apache configuration, and a list of configurable parameters.

```APIDOC
## Enable Microsoft ActiveSync Support

### Description
SOGo supports the Microsoft ActiveSync protocol, allowing clients to synchronize contacts, emails, events, and tasks. It also supports Freebusy and GAL lookups, as well as 'Smart reply' and 'Smart forward' operations.

### Installation
To enable Microsoft ActiveSync support, install the required packages:

```bash
yum install sogo-activesync libwbxml
```

### Apache Configuration
Once installed, uncomment the following lines in your SOGo Apache configuration:

```apache
ProxyPass /Microsoft-Server-ActiveSync \
	http://127.0.0.1:20000/SOGo/Microsoft-Server-ActiveSync \
	retry=60 connectiontimeout=5 timeout=360
```

**Note:** Restart Apache after making these changes.

### Configuration Parameters
The following parameters can be adjusted to tune SOGo's ActiveSync behavior:

#### SOGoMaximumPingInterval
- **Type**: Integer
- **Description**: Maximum time in seconds SOGo will wait before replying to a Ping command. Defaults to `10` seconds.

#### SOGoMaximumSyncInterval
- **Type**: Integer
- **Description**: Maximum time in seconds SOGo will wait before replying to a Sync command. Defaults to `30` seconds.

#### SOGoInternalSyncInterval
- **Type**: Integer
- **Description**: Maximum time in seconds SOGo will wait before performing an internal check for data changes (add, delete, update). This value must be lower than `SOGoMaximumSyncInterval` and `SOGoMaximumPingInterval`. Defaults to `10` seconds.

#### SOGoMaximumSyncResponseSize
- **Type**: Integer (Kilobytes)
- **Description**: Overwrites the maximum response size during a Sync operation. A value of `512` means the response size will be 524288 bytes or less. Defaults to `0` (no overwrite).

#### SOGoMaximumSyncWindowSize
- **Type**: Integer
- **Description**: Overwrites the maximum number of items returned during a Sync operation. Defaults to `0` (no overwrite). Values greater than `512` may cause unexpected behavior with ActiveSync clients.

#### SOGoEASDebugEnabled
- **Type**: Boolean (YES/NO)
- **Description**: Enables logging of complete requests and responses for every EAS command. Defaults to `NO`.

#### SOGoMaximumPictureSize
- **Type**: Integer (Bytes)
- **Description**: Overwrites the maximum number of bytes returned for user pictures in EAS Search operations in the GAL. Defaults to `102400` bytes (100 KB).

#### SOGoEASSearchInBody
- **Type**: Boolean (YES/NO)
- **Description**: Enables EAS Search operations in all parts of a message. Defaults to `NO`, which searches only in Subject and From headers.

#### SOGoEASDisableUI
- **Type**: Boolean (YES/NO)
- **Description**: Disables EAS user interface options. Defaults to `NO`.

### Limitations

- **Outlook 2013/2016 GAL Search**: Does not search the GAL. Consider configuring Outlook to use a LDAP server.
- **Outlook 2013/2016 Multiple Address Books**: Does not seem to support multiple address books over ActiveSync.
- **Certificates**: Avoid self-signed certificates; they can cause intermittent Outlook issues.
- **ActiveSync Connections**: ActiveSync clients keep connections open, requiring sufficient `sogod` processes for many clients. Tune your SOGo server accordingly.
- **Repetitive Events**: Repetitive events with occurrence exceptions are not currently supported.
- **Outlook 2013/2016 Autodiscovery**: Not supported.
- **Outlook 2013/2016 Freebusy**: Supported via Internet Free/Busy feature. Requires `SOGoEnablePublicAccess` set to `YES` and a specific URL format: `http://<hostname>/SOGo/dav/public/%NAME%/freebusy.ifb`.
- **Large Mail Folders (IMAP)**: Adjust IMAP server settings (`imap_max_line_length` for Dovecot, `maxword` for Cyrus IMAP) to a buffer of 2MB if you have folders with thousands of messages.
- **Large Mail Folders (MariaDB/MySQL)**: Set `max_allowed_packet` to a large value (e.g., 64M or 128M) for EAS cache size with thousands of messages.
```

--------------------------------

### sogo-tool user-preferences Set Defaults with File Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Shows how to set the 'Forward' default for 'user1' by providing the JSON value in a separate file and using a credential file for authentication.

```bash
sogo-tool user-preferences set defaults user1 Forward -f /path/filename -p cred
```

--------------------------------

### Active Directory Indirect Bind Configuration

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Example configuration for SOGo to use Active Directory with an indirect bind for user authentication.

```APIDOC
## SOGo Active Directory Indirect Bind Configuration

### Description
This configuration demonstrates how to set up SOGo to authenticate users against an Active Directory domain using an indirect bind mechanism.

### Method
Configuration directive

### Endpoint
N/A (Configuration file setting)

### Parameters
#### Configuration Directives
- **SOGoUserSources** (Array) - An array of user source configurations.
  - **type** (String) - Must be set to `ldap`.
  - **id** (String) - A unique identifier for this LDAP source.
  - **CNFieldName** (String) - The LDAP field containing the common name (e.g., `cn`).
  - **IDFieldName** (String) - The LDAP field used to start a user DN if `bindFields` is not used. Must be unique.
  - **UIDFieldName** (String) - The LDAP field for the unique identifier (e.g., `sAMAccountName`).
  - **baseDN** (String) - The base distinguished name for LDAP searches in Active Directory (e.g., `"cn=Users,dc=acme,dc=com"`).
  - **bindDN** (String) - The distinguished name used to bind to the Active Directory server (e.g., `"cn=sogo,cn=Users,dc=acme,dc=com"`).
  - **bindFields** (Array) - An array of fields to search for the user DN during indirect bind (e.g., `(sAMAccountName)`).
  - **bindPassword** (String) - The password for the `bindDN`.
  - **canAuthenticate** (Boolean) - Set to `YES` to allow authentication.
  - **displayName** (String) - The name displayed for this address book.
  - **hostname** (String) - The Active Directory server hostname and port (e.g., `ldap://10.0.0.1:389`).
  - **isAddressBook** (Boolean) - Set to `YES` to include this source in the address book module.

### Request Example
```
SOGoUserSources = (
    {
        type = ldap;
        CNFieldName = cn;
        IDFieldName = cn;
        UIDFieldName = sAMAccountName;
        baseDN = "cn=Users,dc=acme,dc=com";
        bindDN = "cn=sogo,cn=Users,dc=acme,dc=com";
        bindFields = (sAMAccountName);
        bindPassword = qwerty;
        canAuthenticate = YES;
        displayName = "Active Directory";
        hostname = ldap://10.0.0.1:389;
        id = directory;
        isAddressBook = YES;
    }
);
```

### Response
N/A (Configuration applies on server restart or reload)

```

--------------------------------

### LDAP Group Configuration

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Example configuration for SOGo to manage LDAP-based groups for ACLs and invitations.

```APIDOC
## SOGo LDAP Group Configuration

### Description
This section details how to configure SOGo to recognize and utilize LDAP entries as groups. This allows for group-based access control (ACLs) and group invitations to meetings.

### Method
Configuration directive

### Endpoint
N/A (Configuration file setting)

### Parameters
#### Configuration Directives
- **SOGoUserSources** (Array) - An array of user source configurations.
  - **type** (String) - Must be set to `ldap`.
  - **id** (String) - A unique identifier for this LDAP group source.
  - **CNFieldName** (String) - The LDAP field containing the common name of the group (e.g., `cn`).
  - **IDFieldName** (String) - The LDAP field used to start a DN if `bindFields` is not used. Must be unique.
  - **UIDFieldName** (String) - The LDAP field for the unique identifier of the group (e.g., `cn`).
  - **baseDN** (String) - The base distinguished name for LDAP group searches (e.g., `"ou=groups,dc=inverse,dc=ca"`).
  - **bindDN** (String) - The distinguished name used to bind to the LDAP server for group lookups (e.g., `"cn=sogo,cn=services,dc=inverse,dc=ca"`).
  - **bindPassword** (String) - The password for the `bindDN`.
  - **canAuthenticate** (Boolean) - Set to `YES` to allow authentication for users within these groups.
  - **displayName** (String) - The name displayed for this group list.
  - **hostname** (String) - The LDAP server hostname and port (e.g., `ldap://127.0.0.1:389`).
  - **isAddressBook** (Boolean) - Set to `YES` to make groups visible in the address book.

*SOGo identifies group entries by looking for one of the following `objectClass` attributes: `group`, `groupOfNames`, `groupOfUniqueNames`, or `posixGroup`.*

### Request Example
```
{
    type = ldap;
    CNFieldName = cn;
    IDFieldName = cn;
    UIDFieldName = cn;
    baseDN = "ou=groups,dc=inverse,dc=ca";
    bindDN = "cn=sogo,cn=services,dc=inverse,dc=ca";
    bindPassword = zot;
    canAuthenticate = YES;
    displayName = "Alinto Groups";
    hostname = ldap://127.0.0.1:389;
    id = inverse_groups;
    isAddressBook = YES;
}
```

### Response
N/A (Configuration applies on server restart or reload)

```

--------------------------------

### Dynamic Base DN Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Illustrates how to use a dynamic base DN in SOGo configuration, allowing the base DN to be constructed from the user's domain during login. It also suggests setting UIDFieldName to 'mail' for domain extraction during backup/restore.

```configuration
baseDN = "ou=%d,ou=domains,dc=example,dc=com";
```

--------------------------------

### sogo-tool user-preferences

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Manages user preferences and settings for SOGo. Allows getting, setting, or unsetting user defaults or settings.

```APIDOC
## sogo-tool user-preferences

### Description
Manages user preferences and settings (defaults or settings) for a specified user. Supports getting, setting, or unsetting individual keys.

### Method
`sogo-tool` (Command-line utility)

### Endpoint
N/A (Command-line interface)

### Parameters
#### Command Arguments
- **action** (string) - Required - 'get', 'set', or 'unset'
- **type** (string) - Required - 'defaults' or 'settings'
- **user** (string) - Required - The username for the operation.
- **key** (string) - Required - The name of the parameter to act upon.
- **value** (string) - Optional (Required for 'set' if -f is not used) - The new value for the parameter.
- **-f filename** (string) - Optional (Required for 'set' if value is not provided) - Path to a file containing the value.
- **-p credentialFile** (string) - Optional - Path to a credential file for sieve script operations.
- **-F** (flag) - Optional - Force sieve script activation when used with '-p'.

### Request Example
#### Get Defaults
```
sogo-tool user-preferences get defaults user1 Forward
```

#### Unset Defaults (with credentials)
```
sogo-tool user-preferences unset defaults user1 Forward -p /etc/sogo/cred
```

#### Set Defaults (with value and credentials)
```
sogo-tool user-preferences set defaults user1 Forward '{"forwardAddress":["sogo-tests2@sogo.alinto"],"enabled":1,"keepCopy":0}' -p cred -F
```

#### Set Defaults (with file and credentials)
```
sogo-tool user-preferences set defaults user1 Forward -f /path/filename -p cred
```

### Response
#### Success Response
- **On get**: The JSON value of the key, or a 'not found' message.
- **On set/unset**: Typically no output on success, or a confirmation message.

#### Response Example (Get Defaults)
```json
{
  "forwardAddress": [
    "sogo-tests2@sogo.alinto"
  ],
  "enabled": 1,
  "keepCopy": 1
}
```

#### Error Response Example
```
Value for key "Forward" not found in defaults
```
```

--------------------------------

### GET /SOGoAPI/UserFolder

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Retrieves the CalDAV and CardDAV links for the authenticated user, along with their names.

```APIDOC
## GET /SOGo/SOGoAPI/UserFolder

### Description
Returns the CalDAV and CardDAV links of the authenticated user, along with their names.

### Method
GET

### Endpoint
<scheme>://<domain>/SOGo/SOGoAPI/UserFolder

### Parameters
#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **username** (string) - The UID of the user.
- **calendar** (array) - An array of calendar folder information.
  - **name** (string) - The name of the calendar folder.
  - **url** (string) - The DAV link of the calendar folder.
- **contact** (array) - An array of contact folder information.
  - **name** (string) - The name of the contact folder.
  - **url** (string) - The DAV link of the contact folder.

#### Response Example
```json
{
   "calendar":[
      {
         "name":"DidyShared",
         "url":"http://127.0.0.1/SOGo/dav/sogo-tests1@example.org/Calendar/12509-67F67D00-1-3105AF40"
      },
      {
         "name":"LocalDidy",
         "url":"http://127.0.0.1/SOGo/dav/sogo-tests1@example.org/Calendar/1BC38-67B60000-1-6E4B6880"
      },
      {
         "name":"Personal Calendar",
         "url":"http://127.0.0.1/SOGo/dav/sogo-tests1@example.org/Calendar/personal"
      }
   ],
   "username":"sogo-tests1@example.org",
   "contact":[
      {
         "name":"Personal Address Book",
         "url":"http://127.0.0.1/SOGo/dav/sogo-tests1@example.org/Contacts/personal"
      }
   ]
}
```
```

--------------------------------

### Add EPEL Repository and Configurations for RHEL/CentOS 9

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Installs the EPEL repository and updates the system for RHEL/CentOS 9 using `dnf`. It also installs `yum-utils` and enables the CRB (Code Ready Builder) repository.

```bash
dnf install -y epel-release && dnf update -y
dnf install -y yum-utils && dnf config-manager --set-enabled crb
```

--------------------------------

### LDAP Authentication and Address Book Configuration

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Example configuration for SOGo to use an LDAP server for user authentication and as a global address book.

```APIDOC
## SOGo LDAP User Sources Configuration

### Description
This section provides an example of the `SOGoUserSources` configuration for integrating with an LDAP server. It covers user authentication and the use of LDAP as a global address book.

### Method
Configuration directive

### Endpoint
N/A (Configuration file setting)

### Parameters
#### Configuration Directives
- **SOGoUserSources** (Array) - An array of user source configurations.
  - **type** (String) - Must be set to `ldap`.
  - **id** (String) - A unique identifier for this LDAP source.
  - **CNFieldName** (String) - The LDAP field containing the common name (e.g., `cn`).
  - **IDFieldName** (String) - The LDAP field used to start a user DN if `bindFields` is not used. Must be unique.
  - **UIDFieldName** (String) - The LDAP field for the unique identifier (e.g., `uid`).
  - **IMAPHostFieldName** (String, Optional) - The field containing the IMAP host information if needed.
  - **baseDN** (String) - The base distinguished name for LDAP searches (e.g., `"ou=users,dc=acme,dc=com"`).
  - **bindDN** (String) - The distinguished name used to bind to the LDAP server (e.g., `"uid=sogo,ou=users,dc=acme,dc=com"`).
  - **bindPassword** (String) - The password for the `bindDN`.
  - **canAuthenticate** (Boolean) - Set to `YES` to allow authentication.
  - **displayName** (String) - The name displayed for this address book.
  - **hostname** (String) - The LDAP server hostname and port (e.g., `"ldap://127.0.0.1:389"`).
  - **isAddressBook** (Boolean) - Set to `YES` to include this source in the address book module.
  - **filter** (String, Optional) - An LDAP filter to restrict results (e.g., `"(o='Alinto' AND mail='*' AND status <> 'inactive')"`).

### Request Example
```
SOGoUserSources = (
    {
        type = ldap;
        CNFieldName = cn;
        IDFieldName = uid;
        UIDFieldName = uid;
        IMAPHostFieldName = mailHost;
        baseDN = "ou=users,dc=acme,dc=com";
        bindDN = "uid=sogo,ou=users,dc=acme,dc=com";
        bindPassword = qwerty;
        canAuthenticate = YES;
        displayName = "Shared Addresses";
        hostname = "ldap://127.0.0.1:389";
        id = public;
        isAddressBook = YES;
    }
);
```

### Response
N/A (Configuration applies on server restart or reload)

```

--------------------------------

### sogo-tool user-preferences Set Defaults with Value Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Demonstrates setting the 'Forward' default for 'user1' directly with a JSON value and a credential file, including forcing sieve script activation.

```bash
sogo-tool user-preferences set defaults user1 Forward '{"forwardAddress":["sogo-tests2@sogo.alinto"],"enabled":1,"keepCopy":0}' -p cred -F
```

--------------------------------

### Install SOGo PostgreSQL Connector

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Installs the SOGo database connector for PostgreSQL. This command specifically installs the `sope49-gdl1-postgresql` package, which is required for SOGo to interact with a PostgreSQL database.

```bash
yum install sope49-gdl1-postgresql
```

--------------------------------

### Install SOGo ActiveSync Packages (yum)

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Installs the necessary packages for SOGo's Microsoft ActiveSync support using the yum package manager. Requires root privileges.

```bash
yum install sogo-activesync libwbxml
```

--------------------------------

### sogo-tool user-preferences Command Usage

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Demonstrates the general syntax for the sogo-tool user-preferences command, which allows getting, setting, or unsetting user defaults or settings. It outlines the required arguments such as action, parameter type, user, key, and optional value or filename, along with credential file usage.

```bash
user-preferences get|set|unset defaults|settings user key [value|-f filename] [-p credentialFile [-F]]
```

--------------------------------

### LDAP Group Definition Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

An example of an LDAP entry representing a group, including object classes and members. This format is used by SOGo to identify and manage groups.

```LDAP
dn: cn=inverse,ou=groups,dc=inverse,dc=ca
objectClass: groupOfUniqueNames
objectClass: top
objectClass: extensibleObject
uniqueMember: uid=alice,ou=users,dc=inverse,dc=ca
uniqueMember: uid=bernard,ou=users,dc=inverse,dc=ca
uniqueMember: uid=bob,ou=users,dc=inverse,dc=ca
cn: inverse
structuralObjectClass: groupOfUniqueNames
mail: inverse@inverse.ca
```

--------------------------------

### SOGoDayStartTime and SOGoDayEndTime Configuration

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Defines the start and end hours for the daily view in SOGo's calendar. These parameters control the visible time range within a day.

```text
U | SOGoDayStartTime |  The hour at which the day starts (`0` through `12`). Defaults to `8` when unset.
```

```text
U | SOGoDayEndTime |  The hour at which the day ends (`12` through `23`). Defaults to `18` when unset.
```

--------------------------------

### SOGo CAS Authentication Certificate Trust Setup

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Provides commands for establishing trust between SOGo and a CAS server, particularly when using self-signed certificates. It involves exporting SOGo's certificate, converting it, and importing it into the CAS keystore, and vice-versa.

```shell
openssl x509 -in /etc/ssl/certs/sogo-cert.pem -outform DER \
  -out /tmp/sogo-cert.der
keytool -import -keystore /etc/ssl/certs/java/cacerts  \
  -file /tmp/sogo-cert.der -alias sogo-cert
# The keystore password is 'changeit'
# tomcat must be restarted after this operation
```

```shell
# export tomcat's cert to openssl format
keytool -keystore /etc/tomcat7/keystore  -exportcert -alias tomcat | \
 openssl x509 -inform der >tomcat.pem

Enter keystore password:  tomcat
```

--------------------------------

### SQL User Source Configuration

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Configuration parameters for defining a SQL user source in SOGo.

```APIDOC
## SQL User Source Configuration

### Description
This section outlines the parameters required to configure a SQL database as a user source for authentication and address book features within SOGo.

### Parameters
#### SQL Source Parameters
- **type** (string) - Required - The type of the user source, must be set to `sql`.
- **id** (string) - Required - A unique identification name for the SQL repository.
- **viewURL** (string) - Required - The database URL for the SOGo view. Must include the following columns:
  - `c_uid` (string): Used for authentication (username or username@domain.tld).
  - `c_name` (string): Used for unique entry identification.
  - `c_password` (string): User's password (plain text, crypt, md5, sha encoded).
  - `c_cn` (string): User's common name.
  - `mail` (string): User's email address.
- **userPasswordPolicy** (array of dictionaries) - Optional - Defines password validation rules using regular expressions or predefined constants.
  - `label` (string): Description of the constraint.
  - `regex` (string): Regular expression for validation.
  - `value` (integer): Value for predefined policy constants.
- **userPasswordAlgorithm** (string) - Optional - Default password encryption algorithm. Supported values include `none`, `plain`, `crypt`, `md5`, `md5-crypt`, `smd5`, `csm-md5`, `ldap-md5`, `sha`, `sha256`, `sha256-crypt`, `sha512`, `sha512-crypt`, `ssha` variants, `blf-crypt`, `PBKDF2`, `sym-aes-128-cbc`, `argon2i`, `argon2id`, `argon2`. If a scheme is prepended to the password (e.g., `{scheme}encryptedPass`), it overrides this setting.
- **prependPasswordScheme** (string) - Optional - If set to `YES`, passwords will be stored with the scheme prefix (e.g., `{scheme}encryptedPass`). Defaults to `NO`. For `sym-aes-128-cbc`, this must be `NO`.
- **keyPath** (string) - Required for `sym-aes-128-cbc` - The full path to the global key file, which must be readable by the `sogo` user.
- **canAuthenticate** (string) - Optional - If set to `YES`, this SQL source can be used for authentication.
- **isAddressBook** (string) - Optional - If set to `YES`, this SQL source is used as a read-only shared address book. If `NO`, autocompletion and freebusy lookups will not work for this source.
- **authenticationFilter** (string) - Optional - A filter to limit which users can authenticate from this source.
- **displayName** (string) - Optional - The human-readable name of the SQL repository when used as an address book.
- **LoginFieldNames** (array of strings) - Optional - Column names containing valid authentication usernames. Defaults to `c_uid`.
- **MailFieldNames** (array of strings) - Optional - Column names holding additional email addresses for users. Values must be unique across all specified columns.
- **SearchFieldNames** (array of strings) - Optional - Columns to match against the search string for user filtering. Defaults to `c_cn` and `mail`.
- **IMAPHostFieldName** (string) - Optional - The column name that provides the IMAP hostname for the user.
```

--------------------------------

### sogo-tool user-preferences Unset Defaults Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Illustrates how to unset the 'Forward' default setting for 'user1' using the 'sogo-tool user-preferences' command, including the use of a credential file for authentication.

```bash
sogo-tool user-preferences unset defaults user1 Forward -p /etc/sogo/cred
```

--------------------------------

### SOGo Modules Constraints Configuration Example

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Example of how to limit module access in SOGo based on SQL column values. This snippet shows restricting Calendar access to users in the 'employees' organizational unit.

```ini
ModulesConstraints = {
	Calendar = {
		c_ou = employees;
	};
};

```

--------------------------------

### Create PostgreSQL Database User and Schema

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Commands to create a dedicated 'sogo' user with a password and a 'sogo' database schema owned by this user in PostgreSQL.

```bash
su - postgres
createuser --no-superuser --no-createdb --no-createrole \
	--encrypted --pwprompt sogo
(specify “sogo” as password)
createdb -O sogo sogo
```

--------------------------------

### SOGo REST API - Version

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Retrieves the current version of the SOGo server.

```APIDOC
## SOGo REST API - Version

### Description
Retrieves the current major, minor, and patch version of the SOGo server.

### Method
GET

### Endpoint
`/<scheme://<domain>/SOGo/SOGoAPI/Version>`

### Parameters
N/A

### Request Example
```
GET /SOGo/SOGoAPI/Version
```

### Authentication
No authentication needed.

### Response
#### Success Response (200)
- **major** (integer) - The major version number.
- **patch** (integer) - The patch version number.
- **minor** (integer) - The minor version number.

#### Response Example
```json
{
   "major":5,
   "patch":1,
   "minor":12
}
```

### Error Handling
If an error occurs, the response will be in JSON format:
```json
{
  "error": "message"
}
```
```

--------------------------------

### SOGo EAS Push Configuration Examples

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

These examples show how to configure SOGo parameters to support EAS push notifications effectively. They adjust WOWorkersCount, SOGoMaximumPingInterval, SOGoMaximumSyncInterval, and SOGoInternalSyncInterval based on the number of users and EAS devices. Key parameters like SOGoMaximumPingInterval and SOGoMaximumSyncInterval are set to 3540 seconds (59 minutes) to accommodate long-lived connections.

```ini
WOWorkersCount = 15;
SOGoMaximumPingInterval = 3540;
SOGoMaximumSyncInterval = 3540;
SOGoInternalSyncInterval = 30;
```

```ini
WOWorkersCount = 120;
SOGoMaximumPingInterval = 3540;
SOGoMaximumSyncInterval = 3540;
SOGoInternalSyncInterval = 60;
```

--------------------------------

### Database Configuration

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

This section details how to configure SOGo to use a PostgreSQL database, including setting up database users, schemas, and connection URLs.

```APIDOC
## Database Configuration

### Description
SOGo requires a relational database for storing appointments, tasks, contacts, and user preferences. This guide focuses on PostgreSQL but also supports MariaDB, MySQL, and Oracle.

### Database Setup Steps

1.  **Enable TCP/IP Connections for PostgreSQL**: Ensure your PostgreSQL server is configured to accept TCP/IP connections.
2.  **Configure `/etc/hosts` (Recommended Best Practice)**:
    To facilitate future database host migrations, it's recommended to add a local alias to your `/etc/hosts` file. This alias can then be used in `/etc/sogo/sogo.conf`.
    Example entry for a local database host:
    ```
    127.0.0.1	localhost db-alias
    ```
3.  **Create Database User and Schema**: Use the following commands as the `postgres` user:
    ```bash
    su - postgres
    createuser --no-superuser --no-createdb --no-createrole --encrypted --pwprompt sogo
    # Enter 'sogo' as the password when prompted
    createdb -O sogo sogo
    ```
4.  **Adjust Database Access Rights**: Modify the PostgreSQL access control file (`/var/lib/pgsql/data/pg_hba.conf`) by adding the following line at the beginning:
    ```
host	 sogo	 sogo	 127.0.0.1/32	 md5
    ```
5.  **Restart PostgreSQL Service**: Apply the changes by restarting the PostgreSQL database service.
6.  **Configure SOGo**: Update the SOGo configuration file (`/etc/sogo/sogo.conf`) with the database connection details.

### SOGo Configuration Parameters

SOGo uses several parameters in `sogo.conf` to define database connection URLs. Below are key parameters and their descriptions:

-   **SOGoProfileURL**: Sets the database URL for retrieving user profiles.
    *   PostgreSQL example: `postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_user_profile`
    *   MariaDB/MySQL example: `mysql://sogo:sogo@127.0.0.1:3306/sogo/sogo_user_profile`

-   **OCSFolderInfoURL**: Sets the database URL for retrieving user folder locations (address books, calendars).
    *   PostgreSQL example: `postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_folder_info`
    *   Oracle example: `oracle://sogo:sogo@127.0.0.1:1526/sogo/sogo_folder_info`

-   **OCSSessionsFolderURL**: Sets the database URL for storing and retrieving secured user session information.
    *   PostgreSQL example: `postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_sessions_folder`

-   **OCSEMailAlarmsFolderURL**: Sets the database URL for email-based alarms (requires `SOGoEnableEMailAlarms = YES`).
    *   PostgreSQL example: `postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_alarms_folder`

-   **SOGoEnableMailCleaning**: Enables cleaning of folders and mailboxes (removes mail older than X days). Default: `NO`.

-   **SOGoDisableOrganizerEventCheck**: Disables the organizer's calendar event check.

-   **OCSStoreURL**: Sets the database URL for storing all content data. Requires `OCSAclURL` and `OCSCacheFolderURL` to be set as well.
    *   PostgreSQL example: `postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_store`

-   **OCSAclURL**: Sets the database URL for storing all Access Control List (ACL) data. Requires `OCSStoreURL` and `OCSCacheFolderURL` to be set as well.
    *   PostgreSQL example: `postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_acl`

-   **OCSCacheFolderURL**: Sets the database URL for storing all cache data. Requires `OCSStoreURL` and `OCSAclURL` to be set as well.
    *   PostgreSQL example: `postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_cache_folder`

### Example SOGo Configuration Snippet

```
SOGoProfileURL = "postgresql://sogo:sogo@db-alias:5432/sogo/sogo_user_profile";
OCSFolderInfoURL = "postgresql://sogo:sogo@db-alias:5432/sogo/sogo_folder_info";
OCSSessionsFolderURL = "postgresql://sogo:sogo@db-alias:5432/sogo/sogo_sessions_folder";
```
```

--------------------------------

### SOGo Unicode Compliance Setting

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Adds a parameter to `sogo.conf` to enable complete Unicode compliance within SOGo.

```ini
MySQL4Encoding = "utf8mb4";
```

--------------------------------

### SOGo API Error Handling

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Details common error responses and their meanings for SOGo API actions.

```APIDOC
## SOGo API Error Handling

### Description
Provides information on common error responses encountered when interacting with the SOGo API.

### Error Responses

| Status | Message                                                | Description                                                                                                |
|--------|--------------------------------------------------------|------------------------------------------------------------------------------------------------------------|
| 400    | No backend API found for action: `<action>`            | The requested action does not exist.                                                                       |
| 500    | Can’t alloc and init class: `<classAction>`            | The requested action exists but failed to be instantiated. `<classAction>` is the class's name.          |
| 400    | Method `<method>` not allowed for action `<action>`    | The HTTP method used is not allowed for the specified action. `<method>` is the one used (GET, PUT, POST).
| 400    | Missing param `<param>` for action `<action>`          | A required parameter for the action was not found. `<param>` is the name of the missing parameter.         |
| 401    | No authorization header found for `<action>`           | No Authorization header was provided in the request.                                                       |
| 401    | Authorization method incorrect: `<auth>` for action `<action>` | The value of the Authorization header does not start with 'Basic' or 'Bearer'. `<auth>` is the full value. |
| 401    | User wrong login or not found for action `<action>`    | User authentication failed. This could be due to a wrong login, wrong password, or an expired token.       |
| 500    | Internal error during: `<action>`                    | An internal server error occurred while processing the action.                                             |

**Note**: To enable more detailed debugging logs, add `SOGoAPIDebugEnabled = YES;` to your `sogo.conf` file.
```

--------------------------------

### Exclude GNUstep and ytnef from EPEL

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Modifies the EPEL repository configuration file to exclude packages starting with `gnustep` and `ytnef`. This is necessary because SOGo requires specific versions of these packages provided by Alinto, not EPEL.

```bash
sed -i '/enabled=1/a exclude=gnustep* ytnef*' /etc/yum.repos.d/epel.repo
```

--------------------------------

### Download iOS/macOS Configuration Profile for SOGo Calendar

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Describes how to download and install a provisioning profile from SOGo to automatically configure calendar synchronization on Apple devices. This feature is available since SOGo 5.9.1.

```text
Navigate to SOGo calendar interface.
Click on the three dots button next to the calendar name.
Click on `Download iOS - MacOS configuration profile`.
On device: Settings / Profiles / Click on + / Continue.
Type SOGo account password and click install.
```

--------------------------------

### MariaDB/MySQL Basic Configuration for UTF-8

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Ensures MariaDB/MySQL server and client configurations are set to `utf8` for basic UTF-8 support.

```ini
[mysqld]
...
character_set_server=utf8
character_set_client=utf8

[client]
default-character-set=utf8

[mysql]
default-character-set=utf8
```

--------------------------------

### Install sogo-tool on RHEL/CentOS

Source: https://www.sogo.nu/files/docs/SOGoInstallationGuide

Command to install the sogo-tool utility on Red Hat Enterprise Linux (RHEL) or CentOS systems. This tool is used for database and sieve filter operations.

```bash
yum install sogo-tool
```
Tokens:
Raw