1Installation and Configuration Guide 2==================================== 3:toc: left 4:icons: font 5 6//// 7 8 This file is part of the SOGo project. 9 10 See docinfo.xml for authors, copyright and license information. 11 12//// 13 14include::includes/global-attributes.asciidoc[] 15 16About this Guide 17---------------- 18 19This guide will walk you through the installation and configuration of 20the SOGo solution. It also covers the installation and configuration of 21SOGo ActiveSync support - the solution used to synchronize mobile 22devices with SOGo. 23 24The instructions are based on version {release_version} of SOGo. 25 26The latest version of this guide is available 27at http://sogo.nu/downloads/documentation.html. 28 29Introduction 30------------ 31 32SOGo is a free and modern scalable groupware server. It offers shared 33calendars, address books, and emails through your favourite Web browser 34and by using a native client such as Mozilla Thunderbird and Lightning. 35 36SOGo is standard-compliant. It supports CalDAV, CardDAV, GroupDAV, iMIP 37and iTIP and reuses existing IMAP, SMTP and database servers - making 38the solution easy to deploy and interoperable with many applications. 39 40SOGo features: 41 42* Scalable architecture suitable for deployments from dozens to many 43thousands of users 44* Rich Web-based interface that shares the look and feel, the features 45and the data of Mozilla Thunderbird and Lightning 46* Improved integration with Mozilla Thunderbird and Lightning by using 47the SOGo Connector and the SOGo Integrator 48* Native compatibility for Microsoft Outlook 2003, 2007, 2010, and 2013 49* Two-way synchronization support with any Microsoft ActiveSync-capable 50device, or Outlook 2013/2016 51 52SOGo is developed by a community of developers located mainly in North 53America and Europe. More information can be found at http://sogo.nu/ 54 55Architecture and Compatibility 56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 57 58image::images/architecture.png[System Architecture, 400, 964] 59 60Standard protocols such as CalDAV, CardDAV, GroupDAV, HTTP, IMAP and 61SMTP are used to communicate with the SOGo platform or its 62sub-components. Mobile devices supporting the Microsoft ActiveSync 63protocol are also supported. 64 65To install and configure the native Microsoft Outlook compatibility 66layer, please refer to the _SOGo Native Microsoft Outlook Configuration 67Guide_. 68 69System Requirements 70------------------- 71 72Assumptions 73~~~~~~~~~~~ 74 75SOGo reuses many components in an infrastructure. Thus, it requires the 76following: 77 78* Database server (MySQL, PostgreSQL or Oracle) 79* LDAP server (OpenLDAP, Novell eDirectory, Microsoft Active Directory 80and others) 81* SMTP server (Postfix, Sendmail and others) 82* IMAP server (Courier, Cyrus IMAP Server, Dovecot and others) 83 84If you plan to use ActiveSync, an IMAP server supporting the ACL, 85UIDPLUS, QRESYNC, ANNOTATE (or X-GUID) IMAP extensions is required, 86such as Cyrus IMAP version 2.4 or later, or Dovecot version 872.1 or later. If your current IMAP server does not support these 88extensions, you can use Dovecot's proxying capabilities. 89 90In this guide, we assume that all those components are running on the 91same server (i.e., `localhost` or `127.0.0.1`) that SOGo will be 92installed on. 93 94Good understanding of those underlying components and GNU/Linux is 95required to install SOGo. If you miss some of those required components, 96please refer to the appropriate documentation and proceed with the 97installation and configuration of these requirements before continuing 98with this guide. 99 100The following table provides recommendations for the required 101components, together with version numbers: 102 103|============================================= 104|Database server |PostgreSQL 7.4 or later 105|LDAP server |OpenLDAP 2.3.x or later 106|SMTP server |Postfix 2.x 107|IMAP server |Cyrus IMAP Server 2.3.x or later 108|============================================= 109 110More recent versions of the software mentioned above can also be used. 111 112Minimum Hardware Requirements 113~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 114 115The following table provides hardware recommendations for the server, 116desktops and mobile devices: 117 118[cols="2,8a"] 119|======================================================================= 120|Server 121|Evaluation and testing 122 123[options="compact"] 124* Intel, AMD, or PowerPC CPU 1 GHz 125* 512 MB of RAM 126* 1 GB of disk space 127 128Production 129 130[options="compact"] 131* Intel, AMD or PowerPC CPU 3 GHz 132* 2048 MB of RAM 133* 10 GB of disk space (excluding the mail store) 134 135|Desktop 136|General 137 138[options="compact"] 139* Intel, AMD, or PowerPC CPU 1.5 GHz 140* 1024x768 monitor resolution 141* 512 MB of RAM 142* 128 Kbps or higher network connection 143 144Microsoft Windows 145 146[options="compact"] 147* Microsoft Windows XP SP2 or Vista 148 149Apple Mac OS X 150 151[options="compact"] 152* Apple Mac OS X 10.2 or later 153 154Linux 155 156[options="compact"] 157* Your favourite GNU/Linux distribution 158 159 160|Mobile Device 161|Any mobile device which supports CalDAV, CardDAV or 162Microsoft ActiveSync. 163|======================================================================= 164 165Operating System Requirements 166~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 167 168The following 32-bit and 64-bit operating systems are currently 169supported by SOGo: 170 171* Red Hat Enterprise Linux (RHEL) Server 5, 6 and 7 172* Community ENTerprise Operating System (CentOS) 5, 6 and 7 173* Debian GNU/Linux 6.0 (Squeeze) to 8.0 (Jessie) 174* Ubuntu 12.04 (Precise) to 14.04 (Trusty) 175 176Make sure the required components are started automatically at boot time 177and that they are running before proceeding with the SOGo configuration. 178Also make sure that you can install additional packages from your 179standard distribution. For example, if you are using Red Hat Enterprise 180Linux 5, you have to be subscribed to the Red Hat Network before 181continuing with the SOGo software installation. 182 183NOTE: This document covers the installation of SOGo under RHEL 6. 184 185For installation instructions on Debian and Ubuntu, please refer 186directly to the SOGo website at http://www.sogo.nu/. 187Under the downloads section, you will find links for installation steps 188for Debian and Ubuntu. 189 190Note that once the SOGo packages are installed under Debian and Ubuntu, 191this guide can be followed in order to fully configure SOGo. 192 193Installation 194------------ 195 196This section will guide you through the installation of SOGo together 197with its dependencies. The steps described here apply to an RPM-based 198installation for a Red Hat or CentOS 6 distribution. Most of these steps 199should apply to all supported operating systems. 200 201Software Downloads 202~~~~~~~~~~~~~~~~~~ 203 204[NOTE] 205In order to access the production builds, you need a proper support contract 206from https://sogo.nu/support/index_new.html#support-plans[Inverse]. Continue 207with the configuration once you received your username and password. 208 209SOGo can be installed using the `yum` utility. To do so, first create 210the `/etc/yum.repos.d/inverse.repo` configuration file with the following 211content: 212 213---- 214[SOGo] 215name=Inverse SOGo Repository 216baseurl=https://<username>:<password>@packages.inverse.ca/SOGo/release/2/rhel/6/$basearch 217gpgcheck=0 218---- 219 220[NOTE] 221Any non-URL safe characters in username/password must be URL-encoded. For 222example, if your password is `so%go`, you must set the value in your 223configuration file to `so%25go` - where `%` is encoded to `%25`. 224 225Inverse signs its RPM packages with its GPG key. Integrity verification happens 226all by itself on package installation, all you need to do is first import the 227key into your rpm keychain: 228 229---- 230rpm --import "https://pgp.mit.edu/pks/lookup?op=get&search=0xCB2D3A2AA0030E2C" 231---- 232 233Software Installation 234~~~~~~~~~~~~~~~~~~~~~ 235 236Once the yum configuration file has been created, you are now ready to 237install SOGo and its dependencies. To do so, proceed with the following 238command: 239 240 yum install sogo 241 242This will install SOGo and its dependencies such as GNUstep, the SOPE 243packages and memcached. Once the base packages are installed, you need 244to install the proper database connector suitable for your environment. 245You need to install `sope49-gdl1-postgresql` for the PostgreSQL database 246system, `sope49-gdl1-mysql` for MySQL or `sope49-gdl1-oracle` for Oracle. 247The installation command will thus look like this: 248 249 yum install sope49-gdl1-postgresql 250 251Once completed, SOGo will be fully installed on your server. You are now 252ready to configure it. 253 254Configuration 255------------- 256 257In this section, you'll learn how to configure SOGo to use your existing 258LDAP, SMTP and database servers. As previously mentioned, we assume that 259those components run on the same server on which SOGo is being 260installed. If this is not the case, please adjust the configuration 261parameters to reflect those changes. 262 263GNUstep Environment Overview 264~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 265 266SOGo makes use of the GNUstep environment. GNUstep is a free software 267implementation of the OpenStep specification which provides many 268facilities for building all types of server and desktop applications. 269Among those facilities, there is a configuration API similar to the 270"Registry" paradigm in Microsoft Windows. In OpenSTEP, GNUstep and MacOS 271X, these are called the "user defaults". 272 273In SOGo, the user's applications settings are stored 274in `/usr/local/etc/sogo/sogo.conf`. You can use your favourite text editor to 275modify the file. 276 277The `sogo.conf` file is a serialized _property list_. This simple format 278encapsulates four basic data types: arrays, dictionaries (or hashes), 279strings and numbers. Numbers are represented as-is, except for booleans 280which can take the unquoted values `YES` and `NO`. Strings are not 281mandatorily quoted, but doing so will avoid you many problems. A 282dictionary is a sequence of key and value pairs separated in their 283middle with a `=` sign. It starts with a `{` and ends with a 284corresponding `}`. Each value definition in a dictionary ends with a 285semicolon. An array is a chain of values starting with `(` and ending 286with `)`, where the values are separated with a `,`. Also, the file 287generally follows a C-style indentation for clarity but this indentation 288is not required, only recommended. Block comments are delimited by `/*` 289and `*/` and can span multiple lines while line comments must start with 290`//`. 291 292The configuration must be contained in a root dictionary, thus be completely 293wrapped within curly brackets `{ [configuration] }`. If SOGo refuses to 294start due to syntax errors in its configuration file, `plparse` is helpful 295for finding these, as it indicates the line containing the problem. 296 297Preferences Hierarchy 298~~~~~~~~~~~~~~~~~~~~~ 299 300SOGo supports domain names segregation, meaning that you can separate 301multiple groups of users within one installation of SOGo. A user 302associated to a domain is limited to access only the users data from the 303same domain. Consequently, the configuration parameters of SOGo are 304defined on three levels: 305 306image::images/preferences-hierarchy.png[Preferences Hierarchy, 400, 400] 307 308Each level inherits the preferences of the parent level. Therefore, 309domain preferences define the defaults values of the user preferences, 310and the system preferences define the default values of all domains 311preferences. Both system and domains preferences are defined in 312the `/usr/local/etc/sogo/sogo.conf`, while the users preferences are configurable 313by the user and stored in SOGo's database. 314 315To identify the level in which each parameter can be defined, we use the 316following abbreviations in the tables of this document: 317 318[cols="^3,97"] 319|==================================================================== 320|S |Parameter exclusive to the system and not configurable per domain 321|D |Parameter exclusive to a domain and not configurable per user 322|U |Parameter configurable by the user 323|==================================================================== 324 325Remember that the hierarchy paradigm allow the default value of a 326parameter to be defined at a parent level. 327 328General Preferences 329~~~~~~~~~~~~~~~~~~~ 330 331The following table describes the general parameters that can be set: 332 333[cols="^3,47,50a"] 334|======================================================================= 335|S |WOWorkersCount 336|The amount of instances of SOGo that will be spawned 337to handle multiple requests simultaneously. When started from the init 338script, that amount is overriden by the `PREFORK` value 339in `/etc/sysconfig/sogo` or `/etc/default/sogo`. A value of 3 is a 340reasonable default for low usage. The maximum value depends on the CPU 341and IO power provided by your machine: a value set too high will 342actually decrease performances under high load. 343 344Defaults to 1 when unset. 345 346|S |WOListenQueueSize | 347This parameter controls the backlog size of the 348socket listen queue. For large-scale deployments, this value must be 349adjusted in case all workers are busy and the parent processes receives 350lots of incoming connections. 351 352Defaults to 5 when unset. 353 354|S |WOPort 355|The TCP listening address and port used by the SOGo 356daemon. The format is `ipaddress:port`. 357 358Defaults to `127.0.0.1:20000` when unset. 359 360|S |WOLogFile 361|The file path where to log messages. Specify `-` to log to 362the console. 363 364Defaults to `/var/log/sogo/sogo.log`. 365 366|S |WOPidFile 367|The file path where the parent process id will be written. 368 369Defaults to `/var/run/sogo/sogo.pid`. 370 371|S |WOWatchDogRequestTimeout 372|This parameter specifies the number of minutes after which a busy child 373process will be killed by the parent process. 374 375Defaults to 10 (minutes). 376 377Do not set this too low as child processes replying to clients on a slow 378internet connection could be killed prematurely. 379 380|S |WOMaxUploadSize 381|Parameter used to set the maximum allowed size for content being 382sent to SOGo using a PUT or a POST call. This can also limit the file 383attachment size being uploaded to SOGo when composing a mail. The 384value is in kilobyte. By default, the value is 0, or disabled so no 385limit will be set. 386 387|S |SxVMemLimit 388|Parameter used to set the maximum amount of memory (in 389megabytes) that a child can use. Reaching that value will force children 390processes to restart, in order to preserve system memory. 391 392Defaults to `384`. 393 394|S |SOGoMemcachedHost 395|Parameter used to set the hostname and optionally the port of the 396memcached server. 397 398A path can also be used if the server must be reached via a Unix socket. 399 400Defaults to `localhost`. 401 402See `memcached_servers_parse(3)` for details on the syntax. 403 404|S |SOGoCacheCleanupInterval 405|Parameter used to set the expiration (in seconds) of each object in the 406cache. 407 408Defaults to `300`. 409 410|S |SOGoAuthenticationType 411|Parameter used to define the way by which users will be authenticated. 412For C.A.S., specify `cas`. For SAML2, specify `saml2`. For anything 413else, leave that value empty. 414 415|S |SOGoTrustProxyAuthentication 416|Parameter used to set whether HTTP username should be trusted. 417 418Defaults to `NO` when unset. 419 420|S |SOGoEncryptionKey 421|Parameter used to define a key to encrypt the passwords of remote Web 422calendars when _SOGoTrustProxyAuthentication_ is enabled. 423 424|S |SOGoCASServiceURL 425|When using C.A.S. authentication, this specifies the base url for 426reaching the C.A.S. service. This will be used by SOGo to deduce the 427proper login page as well as the other C.A.S. services that SOGo will 428use. 429 430|S |SOGoCASLogoutEnabled 431|Boolean value indicating whether the "Logout" link is enabled when 432using C.A.S. as authentication mechanism. 433 434The "Logout" link will end up calling _SOGoCASServiceURL_/logout to 435terminate the client's single sign-on C.A.S. session. 436 437|S |SOGoAddressBookDAVAccessEnabled 438|Parameter controlling WebDAV access to the Contacts collections. 439This can be used to deny access to these resources from Lightning for 440example. 441 442Defaults to `YES` when unset. 443 444|S |SOGoCalendarDAVAccessEnabled 445|Parameter controlling WebDAV access to the Calendar collections. 446 447This can be used to deny access to these resources from Lightning for 448example. 449 450Defaults to `YES` when unset. 451 452|S |SOGoSAML2PrivateKeyLocation 453|The location of the SSL private key file on the filesystem that is used 454by SOGo to sign and encrypt communications with the SAML2 identity 455provider. This file must be generated for each running SOGo service 456(rather than host). Make sure this file is readable by the SOGo user. 457 458|S |SOGoSAML2CertiticateLocation 459|The location of the SSL certificate file. This file must be generated 460for each running SOGo service. Make sure this file is readable by the SOGo user. 461 462|S |SOGoSAML2IdpMetadataLocation 463|The location of the metadata file that describes the services available 464on the SAML2 identify provider. The content of this file is usually generated 465directly by your SAML 2.0 IdP solution. For example, using SimpleSAMLphp, you 466can get the metadata directly from https://MYSERVER/simplesaml/saml2/idp/metadata.php 467Make sure this file is readable by the SOGo user. 468 469|S |SOGoSAML2IdpPublicKeyLocation 470|The location of the SSL public key file on the filesystem that is used 471by SOGo to sign and encrypt communications with the SAML2 identity 472provider. This file should be part of the setup of your identity 473provider. Make sure this file is readable by the SOGo user. 474 475|S |SOGoSAML2IdpCertificateLocation 476|The location of the SSL certificate file. This file should be part of 477the setup of your identity provider. Make sure this file is readable by the SOGo user. 478 479|S |SOGoSAML2LoginAttribute 480|The attribute provided by the IdP to identify the user in SOGo. 481 482|S |SOGoSAML2LogoutEnabled 483|Boolean value indicated whether the "Logout" link is enabled when using 484SAML2 as authentication mechanism. When using this feature, SOGo will invoke 485the IdP to proceed with the logout procedure. When the user clicks on the logout 486button, a redirection will be made to the IdP to trigger the logout. 487 488|S |SOGoSAML2LogoutURL 489|The URL to which redirect the user after the "Logout" link is clicked. 490SOGoSAML2LogoutEnabled must be set to YES. If unset, the user will be 491redirected to a blank page. 492 493|D |SOGoTimeZone 494|Mandatory parameter used to set a default time zone for users. The default 495timezone is set to UTC. The Olson database is a standard database that 496takes all the time zones around the world into account and represents 497them along with their history. On GNU/Linux systems, time zone 498definition files are available under `/usr/share/zoneinfo`. Listing the 499available files will give you the name of the available time zones. 500This could be `America/New_York`, `Europe/Berlin`, `Asia/Tokyo` or 501`Africa/Lubumbashi`. 502 503In our example, we set the time zone to `America/Montreal`. 504 505|D |SOGoMailDomain 506|Parameter used to set the default domain name used by SOGo. SOGo uses 507this parameter to build the list of valid email addresses for users. 508 509In our example, we set the default domain to `acme.com`. 510 511|D |SOGoAppointmentSendEMailNotifications 512|Parameter used to set whether SOGo sends or not email notifications to 513meeting participants. Possible values are: 514 515[options="compact"] 516* `YES` - to send notifications 517* `NO` - to not send notifications 518 519Defaults to `NO` when unset. 520 521|D |SOGoFoldersSendEMailNotifications 522|Same as above, but the notifications are triggered on the creation of a 523calendar or an address book. 524 525|D |SOGoACLsSendEMailNotifications 526|Same as above, but the notifications are sent to the involved users of 527a calendar or address book's ACLs. 528 529|D |SOGoCalendarDefaultRoles 530|Parameter used to define the default roles when giving permissions to a 531user to access a calendar. Defaults roles are ignored for public 532accesses. Must be an array of up to five strings. Each string defining a 533role for an event category must begin with one of those values: 534 535[options="compact"] 536* `Public` 537* `Confidential` 538* `Private` 539 540And each string must end with one of those values: 541 542[options="compact"] 543* `Viewer` 544* `DAndTViewer` 545* `Modifier` 546* `Responder` 547 548The array can also contain one or many of the following strings: 549 550[options="compact"] 551* `ObjectCreator` 552* `ObjectEraser` 553 554Example: `SOGoCalendarDefaultRoles = ("ObjectCreator", "PublicViewer");` 555 556Defaults to no role when unset. Recommended values are `PublicViewer` 557and `ConfidentialDAndTViewer`. 558 559|D |SOGoContactsDefaultRoles 560|Parameter used to define the default roles when giving permissions to a 561user to access an address book. Defaults roles are ignored for public 562accesses. Must be an array of one or many of the following strings: 563 564[options="compact"] 565* ObjectViewer 566* ObjectEditor 567* ObjectCreator 568* ObjectEraser 569 570Example: `SOGoContactsDefaultRoles = ("ObjectEditor");` 571 572Defaults to no role when unset. 573 574|D |SOGoSuperUsernames 575|Parameter used to set which usernames require administrative privileges 576over all the users tables. For example, this could be used to post 577events in the users calendar without requiring the user to configure 578his/her ACLs. In this case you will need to specify those superuser's 579usernames like this: `SOGoSuperUsernames = (<username1>[, <username2>, ...]);` 580 581|U |SOGoLanguage 582|Parameter used to set the default language used in the Web interface 583for SOGo. Possible values are: 584 585[options="compact"] 586* `Arabic` 587* `Basque` 588* `BrazilianPortuguese` 589* `Catalan` 590* `ChineseTaiwan` 591* `Croatian` 592* `Czech` 593* `Danish` 594* `Dutch` 595* `English` 596* `Finnish` 597* `French` 598* `German` 599* `Hungarian` 600* `Icelandic` 601* `Italian` 602* `Lithuanian` 603* `Macedonian` 604* `NorwegianBokmal` 605* `NorwegianNynorsk` 606* `Polish` 607* `Portuguese` 608* `Russian` 609* `Slovak` 610* `Slovenian` 611* `SpanishArgentina` 612* `SpanishSpain` 613* `Swedish` 614* `TurkishTurkey` 615* `Ukrainian` 616* `Welsh` 617 618|D |SOGoNotifyOnPersonalModifications 619|Parameter used to set whether SOGo sends or not email receipts when 620someone changes his/her own calendar. Possible values are: 621 622[options="compact"] 623- `YES` - to send notifications 624- `NO` - to not send notifications 625 626Defaults to `NO` when unset. User can overwrite this from the calendar 627properties window. 628 629|D |SOGoNotifyOnExternalModifications 630|Parameter used to set whether SOGo sends or not email receipts when a 631modification is being done to his/her own calendar by someone else. 632Possible values are: 633 634[options="compact"] 635* `YES` - to send notifications 636* `NO` - to not send notifications 637 638Defaults to `NO` when unset. User can overwrite this from the calendar 639properties window. 640 641|D |SOGoLDAPContactInfoAttribute 642|Parameter used to specify an LDAP attribute that should be displayed 643when auto-completing user searches. 644 645|D |SOGoiPhoneForceAllDayTransparency 646|When set to `YES`, this will force all-day events sent over by iPhone 647OS based devices to be transparent. This means that the all-day events 648will not be considered during freebusy lookups. 649 650Defaults to `NO` when unset. 651 652|S |SOGoEnablePublicAccess 653|Parameter used to allow or not your users to share publicly (ie., 654requiring not authentication) their calendars and address books. 655 656Possible values are: 657 658[options="compact"] 659* `YES` - to allow them 660* `NO` - to prevent them from doing so 661 662Defaults to `NO` when unset. 663 664|S |SOGoPasswordChangeEnabled 665|Parameter used to allow or not users to change their passwords from 666SOGo. 667 668Possible values are: 669 670[options="compact"] 671* `YES` - to allow them 672* `NO` - to prevent them from doing so 673 674Defaults to `NO` when unset. 675 676For this feature to work properly when authenticating against AD or 677Samba4, the LDAP connection must use SSL/TLS. Server side restrictions 678can also cause the password change to fail, in which case SOGo will only 679log a 'Constraint violation (0x13)' error. These restrictions include 680password too young, complexity constraints not satisfied, user cannot 681change password, etc... Also note that Samba has a minimum password age 682of 1 day by default. 683 684|S |SOGoSupportedLanguages 685|Parameter used to configure which languages are available from SOGo's 686Web interface. Available languages are specified as an array of string. 687 688The default value is: `( "Arabic", "Basque", "Catalan", "Czech", "Dutch", "Danish", "Welsh", "English", "SpanishSpain", "SpanishArgentina", "Finnish", "French", "German", "Icelandic", "Italian", "Hungarian", "BrazilianPortuguese", "NorwegianBokmal", "NorwegianNynorsk", "Polish", "Russian", "Slovak", "Ukrainian", "Swedish" )` 689 690|D |SOGoHideSystemEMail 691|Parameter used to control if SOGo should hide or not the system email 692address (UIDFieldName@SOGoMailDomain). This is currently limited to 693CalDAV (calendar-user-address-set). 694 695Defaults to `NO` when unset. 696 697|D |SOGoSearchMinimumWordLength 698|Parameter used to control the minimum length to be used for the search 699string (attendee completion, address book search, etc.) prior triggering 700the server-side search operation. 701 702Defaults to `2` when unset - which means a search operation will be 703triggered on the 3rd typed character. 704 705|S |SOGoMaximumFailedLoginCount 706|Parameter used to control the number of failed login attempts required 707during _SOGoMaximumFailedLoginInterval_ seconds or more. If conditions 708are met, the account will be blocked for _SOGoFailedLoginBlockInterval_ 709seconds since the first failed login attempt. 710 711Default value is `0`, or disabled. 712 713|S |SOGoMaximumFailedLoginInterval 714|Number of seconds, defaults to `10`. 715 716|S |SOGoFailedLoginBlockInterval 717|Number of seconds, defaults to `300` (or 5 minutes). Note that 718_SOGoCacheCleanupInterval_ must be set to a value equal or higher than 719_SOGoFailedLoginBlockInterval_. 720 721|S |SOGoMaximumMessageSubmissionCount 722|Parameter used to control the number of email messages a user can send 723from SOGo's webmail interface, to _SOGoMaximumRecipientCount_, in 724_SOGoMaximumSubmissionInterval_ seconds or more. If conditions are met 725or exceeded, the user won't be able to send mails for 726_SOGoMessageSubmissionBlockInterval_ seconds. 727 728Default value is `0`, or disabled. 729 730|S |SOGoMaximumRecipientCount 731|Maximum number of recipients. Default value is `0`, or disabled. 732 733|S |SOGoMaximumSubmissionInterval 734|Number of seconds, defaults to `30`. 735 736|S |SOGoMessageSubmissionBlockInterval 737|Number of seconds, default to `300` (or 5 minutes). Note that 738_SOGoCacheCleanupInterval_ must be set to a value equal or higher than 739_SOGoFailedLoginBlockInterval_. 740 741|S |SOGoMaximumRequestCount 742|Parameter used to control the number of requests a user can send to the SOGo 743server in _SOGoMaximumRequestInterval_ seconds or more. If conditions are met 744or exceeded, the user will not be able to perform requests on the SOGo server 745for _SOGoRequestBlockInterval_ seconds and will receive 429 HTTP responses for 746any requests being made. Default value is 0, or disabled 747 748|S |SOGoMaximumRequestInterval 749|Number of seconds, defaults to `30`. 750 751|S |SOGoRequestBlockInterval 752|Number of seconds, defaults to 300 (or 5 minutes). Note that _SOGoCacheCleanupInterval_ 753must be set to a value equal or higher than _SOGoRequestBlockInterval_. 754 755|======================================================================= 756 757Authentication using LDAP 758~~~~~~~~~~~~~~~~~~~~~~~~~ 759 760SOGo can use a LDAP server to authenticate users and, if desired, to 761provide global address books. SOGo can also use an SQL backend for this 762purpose (see the section_Authentication using SQL_ later in this 763document). Insert the following text into your configuration file to 764configure an authentication and global address book using an LDAP 765directory server: 766 767---- 768SOGoUserSources = ( 769 { 770 type = ldap; 771 CNFieldName = cn; 772 IDFieldName = uid; 773 UIDFieldName = uid; 774 IMAPHostFieldName = mailHost; 775 baseDN = "ou=users,dc=acme,dc=com"; 776 bindDN = "uid=sogo,ou=users,dc=acme,dc=com"; 777 bindPassword = qwerty; 778 canAuthenticate = YES; 779 displayName = "Shared Addresses"; 780 hostname = "ldap://127.0.0.1:389"; 781 id = public; 782 isAddressBook = YES; 783 } 784); 785---- 786 787In our example, we use a LDAP server running on the same host where SOGo 788is being installed. 789 790You can also, using the filter attribute, restrict the results to match 791various criteria. For example, you could define, in your 792`.GNUstepDefaults` file, the following filter to return only entries 793belonging to the organization _Inverse_ with a _mail_ address and 794not _inactive_: 795 796 filter = "(o='Inverse' AND mail='*' AND status <> 'inactive')"; 797 798Since LDAP sources can serve as user repositories for authentication as 799well as address books, you can specify the following for each source to 800make them appear in the address book module: 801 802---- 803displayName = "<human identification name of the address book>"; 804isAddressBook = YES; 805---- 806 807For certain LDAP sources, SOGo also supports indirect binds for user 808authentication. Here is an example: 809 810---- 811SOGoUserSources = ( 812 { 813 type = ldap; 814 CNFieldName = cn; 815 IDFieldName = cn; 816 UIDFieldName = sAMAccountName; 817 baseDN = "cn=Users,dc=acme,dc=com"; 818 bindDN = "cn=sogo,cn=Users,dc=acme,dc=com"; 819 bindFields = (sAMAccountName); 820 bindPassword = qwerty; 821 canAuthenticate = YES; 822 displayName = "Active Directory"; 823 hostname = ldap://10.0.0.1:389; 824 id = directory; 825 isAddressBook = YES; 826 } 827); 828---- 829 830In this example, SOGo will use an indirect bind by first determining the 831user DN. That value is found by doing a search on the fields specified 832in `bindFields`. Most of the time, there will be only one field but it 833is possible to specify more in the form of an array (for example, 834`bindFields = (sAMAccountName, cn)`). When using multiple fields, only 835one of the fields needs to match the login name. In the above example, 836when a user logs in, the login will be checked against the 837`sAMAccountName` entry in all the user cards, and once this card is 838found, the user DN of this card will be used for checking the user's 839password. 840 841Finally, SOGo supports LDAP-based groups. Groups must be defined like 842any other authentication sources (ie., _canAuthenticate_ must be set 843to `YES` and a group must have a valid email address). In order for SOGo 844to determine if a specific LDAP entry is a group, SOGo will look for one 845of the following objectClass attributes: 846 847* `group` 848* `groupOfNames` 849* `groupOfUniqueNames` 850* `posixGroup` 851 852You can set ACLs based on group membership and invite a group to a 853meeting (and the group will be decomposed to its list of members upon 854save by SOGo). You can also control the visibility of the group from the 855list of shared address books or during mail autocompletion by setting 856the `isAddressBook` parameter to `YES` or `NO`. The following LDAP entry 857shows how a typical group is defined: 858 859---- 860dn: cn=inverse,ou=groups,dc=inverse,dc=ca 861objectClass: groupOfUniqueNames 862objectClass: top 863objectClass: extensibleObject 864uniqueMember: uid=alice,ou=users,dc=inverse,dc=ca 865uniqueMember: uid=bernard,ou=users,dc=inverse,dc=ca 866uniqueMember: uid=bob,ou=users,dc=inverse,dc=ca 867cn: inverse 868structuralObjectClass: groupOfUniqueNames 869mail: inverse@inverse.ca 870---- 871 872The corresponding _SOGoUserSources_ entry to handle groups like this one 873would be: 874 875---- 876{ 877 type = ldap; 878 CNFieldName = cn; 879 IDFieldName = cn; 880 UIDFieldName = cn; 881 baseDN = "ou=groups,dc=inverse,dc=ca”; 882 bindDN = "cn=sogo,ou=services,dc=inverse,dc=ca"; 883 bindPassword = zot; 884 canAuthenticate = YES; 885 displayName = “Inverse Groups”; 886 hostname = ldap://127.0.0.1:389; 887 id = inverse_groups; 888 isAddressBook = YES; 889} 890---- 891 892The following table describes the possible parameters related to a LDAP 893source: 894 895[cols="^3,>47,50a"] 896|======================================================================= 897.34+|D <|SOGoUserSources 898|Parameter used to set the LDAP and/or SQL sources used for 899authentication and global address books. Multiple sources can be 900specified as an array of dictionaries. A dictionary that defines an LDAP 901source can contain the following values: 902 903|type 904|The type of this user source, set to ldap` for an LDAP source. 905 906|id 907|The identification name of the LDAP repository. This must be unique - 908even when using multiple domains. 909 910|CNFieldName 911|The field that returns the complete name. 912 913|IDFieldName 914|The field that starts a user DN if bindFields is not used. This field 915must be unique across the entire SOGo domain. 916 917|UIDFieldName 918|The field that returns the login name of a user. 919 920The returned value *must be unique across the whole SOGo installation* 921since it is used to identify the user in the `folder_info` database 922table. 923 924|MailFieldNames 925|An array of fields that returns the user's email addresses (defaults to 926`mail` when unset). Note that SOGo will always automatically strip the 927protocol value from the attribute if the attribute name is `proxyAddresses`. 928 929|SearchFieldNames 930|An array of fields to to match against the search string when filtering 931users (defaults to `sn`, `displayName`, and `telephoneNumber` when 932unset). 933 934|IMAPHostFieldName (optional) 935|The field that returns either an URI to the IMAP server as described 936for SOGoIMAPServer, or a simple server hostname that would be used as a 937replacement for the hostname part in the URI provided by the 938_SOGoIMAPServer_ parameter. 939 940|IMAPLoginFieldName (optional) 941|The field that returns the IMAP login name for the user (defaults to 942the value of _UIDFieldName_ when unset). 943 944|SieveHostFieldName (optional) 945|The field that returns either an URI to the SIEVE server as described 946for _SOGoSieveServer_, or a simple server hostname that would be used as 947a replacement for the hostname part in the URI provided by the 948_SOGoSieveServer_ parameter. 949 950|baseDN 951|The base DN of your user entries. 952 953|KindFieldName (optional) 954|If set, SOGo will try to determine if the value of the field 955corresponds to either "group", "location" or "thing". If that's the 956case, SOGo will consider the returned entry to be a resource. 957 958For LDAP-based sources, SOGo can also automatically determine if it's a 959resource if the entry has the calendarresource objectClass set. 960 961|MultipleBookingsFieldName (optional) 962|The value of this attribute is the maximum number of concurrent events 963to which a resource can be part of at any point in time. 964 965If this is set to `0`, or if the attribute is missing, it means no 966limit. If set to `-1`, no limit is imposed but the resource will 967be marked as busy the first time it is booked. 968 969|filter (optional) 970|The filter to use for LDAP queries, it should be defined as an 971EOQualifier. The following operators are supported: 972 973[options="compact"] 974* `<>` - inequality operator 975* `=` - equality operator 976 977Multiple qualifiers can be joined by using `OR` and `AND`, they can also 978be grouped together by using parenthesis. Attribute values should be 979quoted to avoid unexpected behaviour. 980 981For example: `filter = "(objectClass='mailUser' OR objectClass='mailGroup') AND accountStatus='active' AND uid <> 'alice'";` 982 983|scope (optional) 984|Either `BASE`, `ONE` or `SUB`. 985 986|bindDN 987|The DN of the login name to use for binding to your server. 988 989|bindPassword 990|Its password. 991 992|bindAsCurrentUser 993|If set to `YES`, SOGo will always keep binding to the LDAP server using 994the DN of the currently authenticated user. If _bindFields_ is set, 995_bindDN_ and _bindPassword_ will still be required to find the proper DN 996 of the user. 997 998|bindFields (optional) 999|An array of fields to use when doing indirect binds. 1000 1001|hostname 1002|A space-delimited list of LDAP URLs or LDAP hostnames. 1003 1004LDAP URLs are specified in RFC 4516 and have the following general 1005format: 1006 1007`scheme://host:port/DN?attributes?scope?filter?extensions` 1008 1009Note that SOGo doesn't currently support DN, attributes, scope and 1010filter in such URLs. Using them may have undefined side effects. 1011 1012URLs examples: 1013 1014[options="compact"] 1015* `ldap://127.0.0.1:3389` 1016* `ldaps://127.0.0.1` 1017* `ldap://127.0.0.1/????!StartTLS` 1018 1019|port(deprecated) 1020|Port number of the LDAP server. 1021 1022A non-default port should be part of the ldap URL in the hostname 1023parameter. 1024 1025|encryption (deprecated) 1026|Either `SSL` or `STARTTLS` 1027 1028SSL should be specified as `ldaps://` in the LDAP URL. STARTTLS should 1029be specified as a LDAP Extension in the LDAP URL (e.g. 1030`ldap://127.0.0.1/????!StartTLS`) 1031 1032|userPasswordAlgorithm 1033|The algorithm used for password encryption when changing passwords 1034without Password Policies enabled. 1035 1036Possible values are: `none`, `plain`, `crypt`, `md5`, `md5-crypt`, 1037`sha256-crypt` and `sha512-crypt`, `smd5`, `cram-md5` and `sha`, `sha256`, 1038`sha512` and its ssha (e.g. `ssha` or `ssha256`) variants 1039(plus setting of the encoding with `.b64` or `.hex`). 1040 1041For a more detailed description see 1042http://wiki.dovecot.org/Authentication/PasswordSchemes. 1043 1044Note that `cram-md5` is not actually using cram-md5 (due to the lack of 1045challenge-response mechanism), its just saving the intermediate MD5 1046context as Dovecot stores in its database. 1047 1048Also note that `sha256-crypt` and `sha512-crypt` requires that your 1049operating system supports glibc 2.7 or more recent. 1050 1051|canAuthenticate 1052|If set to `YES`, this LDAP source is used for authentication 1053 1054|passwordPolicy 1055|If set to `YES`, SOGo will use the extended LDAP Password Policies 1056attributes. If you LDAP server does not support those and you activate 1057this feature, every LDAP requests will fail. Note that some LDAP servers 1058require LDAP/SSL for password policies to work. This is the case for 1059example with 389 Directory Server. 1060 1061|updateSambaNTLMPasswords 1062|If set to `YES`, SOGo will automatically update the sambaNTPassword 1063and sambaLMPassword attributes when changing passwords. The attributes 1064must be called sambaNTPassword and sambaLMPassword. You must also make 1065sure the correct ACL is set in your LDAP server to allow users to change 1066their own sambaNTPassword and sambaLMPassword password attributes. 1067Defaults to `NO` when unset. 1068 1069|isAddressBook 1070|If set to `YES`, this LDAP source is used as a shared address book 1071(with read-only access). Note that if set to `NO`, autocompletion will 1072not work for entries in this source and thus, freebusy lookups. 1073 1074|displayName (optional) 1075|If set as an address book, the human identification name of the LDAP 1076repository 1077 1078|ModulesConstraints (optional) 1079|Limits the access of any module through a constraint based on an LDAP 1080attribute; must be a dictionary with keys `Mail`, and/or `Calendar`, 1081and/or `ActiveSync` for example: 1082 1083---- 1084ModulesConstraints = { 1085 Calendar = { 1086 ou = employees; 1087 }; 1088}; 1089---- 1090 1091|mapping 1092|A dictionary that maps contact attributes used by SOGo to the LDAP 1093attributes used by the schema of the LDAP source. Each entry must have 1094an attribute name as key and an array of strings as value. This enables 1095actual fields to be mapped one after another when fetching contact 1096informations. 1097 1098See the LDAP Attribute Mapping section below for an example and a list 1099of supported attributes. 1100 1101|objectClasses 1102|When the _modifiers_ list (see below) is set, or when using LDAP-based 1103user addressbooks (see _abOU_ below), this list of object classes will 1104be applied to new records as they are created. 1105 1106|GroupObjectClasses 1107|A list (array) of names identifying groups within the LDAP source. If not 1108set, SOGo will use `group`, `groupofnames`, `groupofuniquenames` 1109and `posixgroup`. 1110 1111|modifiers 1112|A list (array) of usernames that are authorized to perform 1113modifications to the address book defined by this LDAP source. 1114 1115|abOU 1116|This field enables LDAP-based user addressbooks by specifying the value 1117of the address book container beneath each user entry, for example: 1118`ou=addressbooks,uid=username,dc=domain`. 1119|======================================================================= 1120 1121The following parameters can be defined along the other keys of each 1122entry of the SOGoUserSources, but can also defined at the domain and/or 1123system levels: 1124 1125[cols="3,47,50a"] 1126|======================================================================= 1127|D |SOGoLDAPContactInfoAttribute 1128|Parameter used to specify an attribute that should appear in 1129autocompletion of the web interface. 1130 1131|D |SOGoLDAPQueryLimit 1132|Parameter used to limit the number of returned results from the LDAP 1133server whenever SOGo performs a LDAP query (for example, during 1134addresses completion in a shared address book). 1135 1136|D |SOGoLDAPQueryTimeout 1137|Parameter to define the timeout of LDAP queries. The actual time limit 1138for operations is also bounded by the maximum time that the server is 1139configured to allow. 1140 1141Defaults to `0` (unlimited). 1142|======================================================================= 1143 1144LDAP Attributes Indexing 1145~~~~~~~~~~~~~~~~~~~~~~~~ 1146 1147To ensure proper performance of the SOGo application, the following LDAP 1148attributes must be fully indexed: 1149 1150* givenName 1151* cn 1152* mail 1153* sn 1154 1155Please refer to the documentation of the software you use in order to 1156index those attributes. 1157 1158LDAP Attributes Mapping 1159~~~~~~~~~~~~~~~~~~~~~~~ 1160 1161Some LDAP attributes are mapped to contacts attributes in the SOGo UI. 1162The table below list most of them. It is possible to override these by 1163using the _mapping_ configuration parameter. 1164 1165For example, if the LDAP schema uses the _fax_ attribute to store the 1166fax number, one could map it to the _facsimiletelephonenumber_ attribute 1167like this: 1168 1169---- 1170mapping = { 1171 facsimiletelephonenumber = ("fax", "facsimiletelephonenumber"); 1172}; 1173---- 1174 1175|=== 11762+h|Name 1177|First |givenName 1178|Last |sn 1179|DisplayName |displayName _or_ cn _or_ givenName + sn 1180|Nickname |mozillanickname 1181 11822+h|Internet 1183|Email |mail 1184|Secondary email |mozillasecondemail 1185|ScreenName |nsaimid 1186 11872+h|Phones 1188|Work |telephoneNumber 1189|Home |homephone 1190|Mobile |mobile 1191|Fax |facsimiletelephonenumber 1192|Pager |pager 1193 11942+h|Home 1195|Address |mozillahomestreet + mozillahomestreet2 1196|City |mozillahomelocalityname 1197|State/Province |mozillahomestate 1198|Zip/Postal Code |mozillahomepostalcode 1199|Country |mozillahomecountryname 1200|Web page |mozillahomeurl 1201 12022+h|Work 1203|Title |title 1204|Department |ou 1205|Organization |o 1206|Address |street + mozillaworkstreet2 1207|City |l 1208|State/Province |st 1209|Zip/Postal code |postalCode 1210|Country |c 1211|Web page |mozillaworkurl 1212 12132+h|Other 1214|Birthday |birthyear-birthmonth-birthday 1215|Note |description 1216|=== 1217 1218Authenticating using C.A.S. 1219~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1220 1221SOGo natively supports C.A.S. authentication. For activating C.A.S. 1222authentication you need first to make sure that 1223the _SOGoAuthenticationType_ setting is set to `cas` and that 1224the _SOGoCASServiceURL_ setting is configured appropriately. 1225 1226The tricky part shows up when using SOGo as a frontend interface to an 1227IMAP server as this imposes constraints needed by the C.A.S. protocol to 1228ensure secure communication between the different services. Failing to 1229take those precautions will prevent users from accessing their mails, 1230while still granting basic authentication to SOGo itself. 1231 1232The first constraint is that *the amount of workers that SOGo uses must 1233be higher than 1 in order to enable the C.A.S.* service to perform some 1234validation requests during IMAP authentication. A single worker alone 1235would not, by definition, be able to respond to the C.A.S. requests 1236while treating the user request that required the triggering of those 1237requests. You must therefore configure the _WOWorkersCount_ setting 1238appropriately. 1239 1240The second constraint is that *the SOGo service must be accessible and 1241accessed via https*. Moreover, the certificate used by the SOGo server 1242has to be recognized and trusted by the C.A.S. service. In the case of a 1243certificate issued by a third-party authority, there should be nothing 1244to worry about. In the case of a self-signed certificate, the 1245certificate must be registered in the trusted keystore of the C.A.S. 1246application. The procedure to achieve this can be summarized as 1247importing the certificate in the proper "keystore" using 1248the `keytool` utility and specifying the path for that keystore to the 1249Tomcat instance which provides the C.A.S. service. This is done by 1250tweaking the `javax.net.ssl.trustStore` setting, either in the 1251`catalina.properties` file or in the command-line parameters. On debian, 1252the SOGo certificate can also be added to the truststore as follows: 1253 1254---- 1255openssl x509 -in /etc/ssl/certs/sogo-cert.pem -outform DER \ 1256 -out /tmp/sogo-cert.der 1257keytool -import -keystore /etc/ssl/certs/java/cacerts \ 1258 -file /tmp/sogo-cert.der -alias sogo-cert 1259# The keystore password is 'changeit' 1260# tomcat must be restarted after this operation 1261---- 1262 1263*The certificate used by the CAS server must also be trusted by SOGo.* 1264In case of a self-signed certificate, this means exporting tomcat's 1265certificate using the `keytool` utility, converting it to PEM format and 1266appending it to the `ca-certificates.crt` file (the name and location of 1267that file differs between distributions). Basically: 1268 1269---- 1270# export tomcat's cert to openssl format 1271keytool -keystore /etc/tomcat7/keystore -exportcert -alias tomcat | \ 1272 openssl x509 -inform der >tomcat.pem 1273 1274Enter keystore password: tomcat 1275 1276# add the pem to the trusted certs 1277cp tomcat.pem /etc/ssl/certs 1278cat tomcat.pem >>/etc/ssl/certs/ca-certificates 1279---- 1280 1281If any of those constraints is not satisfied, the webmail interface of 1282SOGo will display an empty email account. Unfortunately, SOGo has no 1283possibility to detect which one is the cause of the problem. The only 1284indicators are log messages that at least pinpoint the symptoms: 1285 1286___________________________________________________ 1287_"failure to obtain a PGT from the C.A.S. service"_ 1288___________________________________________________ 1289 1290Such an error will show up during authentication of the user to SOGo. It 1291happens when the authentication service has accepted the user 1292authentication ticket but has not returned a "Proxy Granting Ticket". 1293 1294_______________________________________________ 1295_"a CAS failure occurred during operation...."_ 1296_______________________________________________ 1297 1298This error indicate that an attempt was made to retrieve an 1299authentication ticket for a third-party service such as IMAP or sieve. 1300Most of the time, this happens as a consequence to the problem described 1301above. To troubleshoot these issues, one should be tailing `cas.log`, 1302pam logs and sogo logs. 1303 1304Currently, SOGo will ask for a CAS ticket using the same CAS service 1305name for both IMAP and Sieve. *When CASifying sieve, this means that the 1306`-s` parameter of `pam_cas`should be the same for both IMAP and Sieve*, 1307otherwise the CAS server will complain: 1308 1309---- 1310ERROR [org.jasig.cas.CentralAuthenticationServiceImpl] - ServiceTicket 1311[ST-31740-hoV1brhhwMNfnBkSMVUw-ocas] with service [imap://myimapserver 1312does not match supplied service [sieve://mysieveserver:2000] 1313---- 1314 1315Finally, when using imapproxy to speed up the imap accesses, the 1316SOGoIMAPCASServiceName should be set to the actual imap service name 1317expected by pam_cas, otherwise it will fail to authenticate incoming 1318connection properly. 1319 1320Authenticating using SAML2 1321~~~~~~~~~~~~~~~~~~~~~~~~~~ 1322 1323SOGo natively supports SAML2 authentication. Please refer to the 1324documentation of your identity provider and the SAML2 configuration keys 1325that are listed above for proper setup. Once a SOGo instance is 1326configured properly, the metadata for that instance can be retrieved 1327from `http://<hostname>/SOGo/saml2-metadata` for registration with the 1328identity provider. SOGo will dynamically generate the metadata based on 1329the SOGoSAML2CertificateLocation's content and the SOGo server name. 1330 1331When using SimpleSAMLphp, make sure the convert OID to names by modifying your 1332`metadata/saml20-idp-hosted.php` to contain something like this: 1333 1334---- 1335 'attributes.NameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri', 1336 'authproc' => array( 1337 100 => array('class' => 'core:AttributeMap', 'oid2name'), 1338 ), 1339---- 1340 1341If you want to test the IdP-initiated logout using SimpleSAMLphp, you can do so by opening 1342the following URL: 1343 1344---- 1345https://idp.example.org/simplesaml/saml2/idp/SingleLogoutService.php?ReturnTo=www.sogo.nu 1346---- 1347 1348In order to relay authentication information to your IMAP server and if 1349you make use of the CrudeSAML SASL plugin, you need to make sure that 1350_NGImap4AuthMechanism_ is configured to use the `SAML` mechanism. If you 1351make use of the CrudeSAML PAM plugin, this value may be left empty. 1352 1353 1354Database Configuration 1355~~~~~~~~~~~~~~~~~~~~~~ 1356 1357SOGo requires a relational database system in order to store 1358appointments, tasks and contacts information. It also uses the database 1359system to store personal preferences of SOGo users. In this guide, we 1360assume you use PostgreSQL so commands provided the create the database 1361are related to this application. However, other database servers are 1362supported, such as MySQL and Oracle. 1363 1364First, make sure that your PostgreSQL server has TCP/IP connections 1365support enabled. 1366 1367[TIP] 1368=============================== 1369SOGo stores the database hostname together with table references inside 1370several database tables. To prevent possible future issues when moving 1371the database to another host, it is best practice to add a local alias name to 1372your `/etc/hosts` file, and using this in `/usr/local/etc/sogo/sogo.conf` instead of the 1373actual name of your server or localhost. When the database host name changes, 1374you can now simply change the hosts file instead of updating several table 1375columns replacing the old hostname. An example entry for `/etc/hosts` when 1376running the database on the same host, registering `127.0.0.1` not only for 1377`localhost`, but also the `db-alias` alias: 1378 1379 127.0.0.1 localhost db-alias 1380 1381In the SOGo configuration, use the alias name instead of the real IP address or 1382host name, for example 1383 1384---- 1385SOGoProfileURL = 1386 "postgresql://sogo:sogo@db-alias:5432/sogo/sogo_user_profile"; 1387---- 1388=============================== 1389 1390Create the database user and schema using the following commands: 1391 1392---- 1393su - postgres 1394createuser --no-superuser --no-createdb --no-createrole \ 1395 --encrypted --pwprompt sogo 1396(specify “sogo” as password) 1397createdb -O sogo sogo 1398---- 1399 1400You should then adjust the access rights to the database. To do so, 1401modify the configuration file `/var/lib/pgsql/data/pg_hba.conf` in order 1402to add the following line at the very beginning of the file: 1403 1404 host sogo sogo 127.0.0.1/32 md5 1405 1406Once added, restart the PostgreSQL database service. Then, modify the 1407SOGo configuration file (`/usr/local/etc/sogo/sogo.conf`) to reflect your database 1408settings: 1409 1410---- 1411SOGoProfileURL = 1412 "postgresql://sogo:sogo@localhost:5432/sogo/sogo_user_profile"; 1413OCSFolderInfoURL = 1414 "postgresql://sogo:sogo@localhost:5432/sogo/sogo_folder_info"; 1415OCSSessionsFolderURL = 1416 "postgresql://sogo:sogo@localhost:5432/sogo/sogo_sessions_folder"; 1417---- 1418 1419The following table describes the parameters that were set: 1420 1421[cols="3,47,50a"] 1422|======================================================================= 1423|S |SOGoProfileURL 1424|Parameter used to set the database URL so that SOGo can retrieve user 1425profiles. 1426 1427For MySQL, set the database URL to something like: 1428`mysql://sogo:sogo@localhost:3306/sogo/sogo_user_profile`. 1429 1430|S |OCSFolderInfoURL 1431|Parameter used to set the database URL so that SOGo can retrieve the 1432location of user folders (address books and calendars). 1433 1434For Oracle, set the database URL to something like: 1435`oracle://sogo:sogo@localhost:1526/sogo/sogo_folder_info`. 1436 1437|S |OCSSessionsFolderURL 1438|Parameter used to set the database URL so that SOGo can store and 1439retrieve secured user sessions information. For PostgreSQL, the database 1440URL could be set to something like: 1441`postgresql://sogo:sogo@localhost:5432/sogo/sogo_sessions_folder`. 1442 1443|S |OCSEMailAlarmsFolderURL 1444|Parameter used to set the database URL for email-based alarms (that can 1445be set on events and tasks). This parameter is relevant only if 1446_SOGoEnableEMailAlarms_ is set to `YES`. For PostgreSQL, the database 1447URL could be set to something like: 1448`postgresql://sogo:sogo@localhost:5432/sogo/sogo_alarms_folder` 1449 1450See the "EMail reminders" section in this document for more information. 1451|======================================================================= 1452 1453 1454[NOTE] 1455Any non-URL safe characters in username/password must be URL-encoded. 1456For example, if your SOGo database password is `so%go`, you must set 1457the value in your preferences to `so%25go` - where `%` is encoded 1458to `%25`. 1459 1460If you're using MySQL, make sure in your `my.cnf` file you have: 1461 1462---- 1463[mysqld] 1464... 1465character_set_server=utf8 1466character_set_client=utf8 1467 1468[client] 1469default-character-set=utf8 1470 1471[mysql] 1472default-character-set=utf8 1473---- 1474 1475Authentication using SQL 1476~~~~~~~~~~~~~~~~~~~~~~~~ 1477 1478SOGo can use a SQL-based database server for authentication. The 1479configuration is very similar to LDAP-based authentication. 1480 1481The following table describes all the possible parameters related to a 1482SQL source: 1483 1484[cols="3,47,50a"] 1485|======================================================================= 1486.18+|D |SOGoUserSources 1487|Parameter used to set the SQL and/or LDAP sources used for 1488authentication and global address books. Multiple sources can be 1489specified as an array of dictionaries. A dictionary that defines a SQL 1490source can contain the following values: 1491 1492|type 1493|The type of this user source, set to `sql` for a SQL source. 1494 1495|id 1496|The identification name of the SQL repository. This must be unique - 1497even when using multiple domains. 1498 1499|viewURL 1500|Database URL of the view used by SOGo. The view expects columns to be 1501present. Required columns are: 1502 1503[options="compact"] 1504* `c_uid`: will be used for authentication - it's a username or 1505 username@domain.tld 1506* `c_name`: will be used to uniquely identify entries - which can be 1507 identical to `c_uid` 1508* `c_password`: password of the user, plain text, crypt, md5 or sha 1509 encoded 1510* `c_cn`: the user's common name 1511* mail : the user's email address 1512 1513Other columns can exist and will actually be mapped automatically if 1514they have the same name as popular LDAP attributes (such as `givenName`, 1515`sn`, `department`, `title`, `telephoneNumber`, etc.). 1516 1517|userPasswordAlgorithm 1518|The default algorithm used for password encryption when changing 1519passwords. Possible values are: `none`, `plain`, `crypt`, `md5`, 1520`md5-crypt`, `smd5`, `cram-md5`, `ldap-md5`, and `sha`, `sha256`, 1521`sha512` and its ssha (e.g. `ssha` or `ssha256`) variants. Passwords can 1522have the scheme prepended in the form `{scheme}encryptedPass`. 1523 1524If no scheme is given, _userPasswordAlgorithm_ is used instead. The 1525schemes listed above follow the algorithms described in 1526http://wiki.dovecot.org/Authentication/PasswordSchemes. 1527 1528Note that `cram-md5` is not actually using cram-md5 (due to the lack of 1529challenge-response mechanism), its just saving the intermediate MD5 1530context as Dovecot stores in its database. 1531 1532|prependPasswordScheme 1533|The default behaviour is to store newly set passwords without the 1534scheme (default: `NO`). This can be overridden by setting to `YES` and 1535will result in passwords stored as `{scheme}encryptedPass`. 1536 1537|canAuthenticate 1538|If set to `YES`, this SQL source is used for authentication. 1539 1540|isAddressBook 1541|If set to `YES`, this SQL source is used as a shared address book 1542(with read-only access). Note that if set to `NO`, autocompletion will 1543not work for entries in this source and thus, freebusy lookups. 1544 1545|authenticationFilter (optional) 1546|A filter that limits which users can authenticate from this source. 1547 1548|displayName (optional) 1549|If set as an address book, the human identification name of the SQL 1550repository. 1551 1552|LoginFieldNames (optional) 1553|An array of fields that specifies the column names that contain valid 1554authentication usernames (defaults to `c_uid` when unset). 1555 1556|MailFieldNames (optional) 1557|Aan array of fields that specifies the column names that hold 1558additional email addresses (beside the `mail` column) for each user. 1559 1560|IMAPHostFieldName (optional) 1561|The field that returns the IMAP hostname for the user. 1562 1563|IMAPLoginFieldName (optional) 1564|The field that returns the IMAP login name for the user (defaults to 1565`c_uid` when unset). 1566 1567|SieveHostFieldName (optional) 1568|The field that returns the Sieve hostname for the user. 1569 1570|KindFieldName (optional) 1571|If set, SOGo will try to determine if the value of the field 1572corresponds to either "group", "location" or "thing". If that's the 1573case, SOGo will consider the returned entry to be a resource. 1574 1575|MultipleBookingsFieldName (optional) 1576|The value of this field is the maximum number of concurrent events to 1577which a resource can be part of at any point in time. 1578 1579If this is set to `0`, or if the attribute is missing, it means no 1580limit and the resource will always be marked as free. If set to `-1`, 1581no limit is imposed but the resource will be marked as busy the first 1582time it is booked. If greater than 0, the resource will get marked as 1583busy once it reaches the value. 1584 1585|DomainFieldName (optional) 1586|If set, SOGo will use the value of that field as the domain associated 1587to the user. 1588 1589See the _Multi-domains Configuration_ section in this document for more 1590information. 1591|======================================================================= 1592 1593Here is an example of an SQL-based authentication and address book 1594source: 1595 1596---- 1597SOGoUserSources = 1598( 1599 { 1600 type = sql; 1601 id = directory; 1602 viewURL = "postgresql://sogo:sogo@127.0.0.1:5432/sogo/sogo_view"; 1603 canAuthenticate = YES; 1604 isAddressBook = YES; 1605 userPasswordAlgorithm = md5; 1606 } 1607); 1608---- 1609 1610Certain database columns must be present in the view/table, such as: 1611 1612* `c_uid` - will be used for authentication - it's the username 1613or username@domain.tld 1614* `c_name` - which can be identical to `c_uid` - will be used to 1615 uniquely identify entries 1616* `c_password` - password of the user, plain-text, md5 or sha encoded 1617 for now 1618* `c_cn` - the user's common name - such as "John Doe" 1619* `mail` - the user's mail address 1620 1621Note that groups are currently not supported for SQL-based 1622authentication sources. 1623 1624SMTP Server Configuration 1625~~~~~~~~~~~~~~~~~~~~~~~~~ 1626 1627SOGo makes use of a SMTP server to send emails from the Web interface, 1628iMIP/iTIP messages and various notifications. 1629 1630The following table describes the related parameters. 1631 1632[cols="3,47,50a"] 1633|======================================================================= 1634|D |SOGoMailingMechanism 1635|Parameter used to set how SOGo sends mail messages. Possible values 1636are: 1637 1638[options="compact"] 1639* `sendmail` - to use the sendmail binary 1640* `smtp` - to use the SMTP protocol 1641 1642|D |SOGoSMTPServer 1643|The DNS name or IP address of the SMTP server used when 1644_SOGoMailingMechanism_ is set to `smtp`. 1645Supported formats are: `smtp://domain:port`, `smtps://domain`, 1646`domain:port`, `smtp://domain:port/?tls=YES`. Using the option 1647`tls=YES` will enforce using STARTTLS smtp connections. Thus, 1648`smtp://localhost:587/?tls=YES` would use the default MUA port 1649on localhost with STARTTLS enforced. 1650 1651|D |SOGoSMTPAuthenticationType 1652|Activate SMTP authentication and specifies which type is in use. 1653Current, only `PLAIN` is supported and other values will cause 1654the authentication to fail. 1655 1656|S |WOSendMail 1657|The path of the sendmail binary. 1658 1659Defaults to `/usr/lib/sendmail`. 1660 1661|D |SOGoForceExternalLoginWithEmail 1662|Parameter used to specify if, when logging in to the SMTP server, the 1663primary email address of the user will be used instead of the username. 1664Possible values are: 1665 1666[options="compact"] 1667* `YES` 1668* `NO` 1669 1670Defaults to `NO` when unset. 1671|======================================================================= 1672 1673IMAP Server Configuration 1674~~~~~~~~~~~~~~~~~~~~~~~~~ 1675 1676SOGo requires an IMAP server in order to let users consult their email 1677messages, manage their folders and more. 1678 1679The following table describes the related parameters. 1680 1681[cols="3,47,50a"] 1682|======================================================================= 1683|U |SOGoDraftsFolderName 1684|Parameter used to set the IMAP folder name used to store drafts 1685messages. 1686 1687Defaults to `Drafts` when unset. 1688 1689Use a `/` as a hierarchy separator if referring to an IMAP subfolder. 1690For example: `INBOX/Drafts`. 1691 1692|U |SOGoSentFolderName 1693|Parameter used to set the IMAP folder name used to store sent messages. 1694 1695Defaults to `Sent` when unset. 1696 1697Use a `/` as a hierarchy separator if referring to an IMAP subfolder. 1698For example: `INBOX/Sent`. 1699 1700|U |SOGoTrashFolderName 1701|Parameter used to set the IMAP folder name used to store deleted 1702messages. 1703 1704Defaults to `Trash` when unset. 1705 1706Use a `/` as a hierarchy separator if referring to an IMAP subfolder. 1707For example: `INBOX/Trash`. 1708 1709|U |SOGoJunkFolderName 1710|Parameter used to set the IMAP folder name used to store junk 1711messages. 1712 1713Defaults to `Junk` when unset. 1714 1715Use a `/` as a hierarchy separator if referring to an IMAP subfolder. 1716For example: `INBOX/Junk`. Also see the SOGoMailJunkSettings for 1717more options regarding junk/not-junk actions. 1718 1719|D |SOGoIMAPCASServiceName 1720|Parameter used to set the CAS service name (URL) of the imap service. 1721This is useful if SOGo is connecting to the IMAP service through a 1722proxy. When using `pam_cas`, this parameter should be set to the same 1723value as the `-s` argument of the imap pam service. 1724 1725|D |SOGoIMAPServer 1726|Parameter used to set the DNS name or IP address of the IMAP server 1727used by SOGo. You can also use SSL or TLS by providing a value using an 1728URL, such as: 1729 1730[options="compact"] 1731* `imaps://localhost:993` 1732* `imaps://localhost:143/?tls=YES` 1733 1734|D |SOGoSieveServer 1735|Parameter used to set the DNS name or IP address of the Sieve 1736(managesieve) server used by SOGo. You must use an URL such as: 1737 1738[options="compact"] 1739* `sieve://localhost` 1740* `sieve://localhost:2000` 1741* `sieve://localhost:2000/?tls=YES` 1742 1743Note that TLS is supported but SSL is not. 1744 1745|D |SOGoSieveFolderEncoding 1746|Parameter used to specify which encoding is used for IMAP folder names 1747in Sieve filters. Defaults to `UTF-7`. The other possible value is 1748`UTF-8`. 1749 1750|U |SOGoMailShowSubscribedFoldersOnly 1751|Parameter used to specify if the Web interface should only show 1752subscribed IMAP folders. Possible values are: 1753 1754[options="compact"] 1755* `YES` 1756* `NO` 1757 1758Defaults to `NO` when unset. 1759 1760|D |SOGoIMAPAclStyle 1761|Parameter used to specify which RFC the IMAP server implements with 1762respect to ACLs. Possible values are: 1763 1764[options="compact"] 1765* `rfc2086` 1766* `rfc4314` 1767 1768Defaults to `rfc4314` when unset. 1769 1770|D |SOGoIMAPAclConformsToIMAPExt 1771|Parameter used to specify if the IMAP server implements the Internet 1772Message Access Protocol Extension. Possible values are: 1773 1774[options="compact"] 1775* `YES` 1776* `NO` 1777 1778Defaults to `NO` when unset. 1779 1780|D |SOGoForceExternalLoginWithEmail 1781|Parameter used to specify if, when logging in to the IMAP server, the 1782primary email address of the user will be used instead of the username. 1783Possible values are: 1784 1785[options="compact"] 1786* `YES` 1787* `NO` 1788 1789Defaults to `NO` when unset. 1790 1791|D |SOGoMailSpoolPath 1792|Parameter used to set the path where temporary email drafts are 1793written. If you change this value, you must also modify the daily 1794cronjob `sogo-tmpwatch`. 1795 1796Defaults to `/var/spool/sogo`. 1797 1798|S |NGMimeBuildMimeTempDirectory 1799|Parameter used to set the path where temporary files will be stored 1800by SOPE when dealing with MIME messages. 1801 1802Defaults to `/tmp`. 1803 1804 1805|S |NGImap4DisableIMAP4Pooling 1806|Disables IMAP pooling when set to `YES`. Enable pooling by setting to 1807`NO` or using a caching proxy like imapproxy. 1808 1809The default value is `YES`. 1810 1811|S |NGImap4ConnectionStringSeparator 1812|Parameter used to set the IMAP mailbox separator. Setting this will 1813also have an impact on the mailbox separator used by Sieve filters. 1814 1815The default separator is `/`. 1816 1817|S |NGImap4AuthMechanism 1818|Trigger the use of the IMAP `AUTHENTICATE` command with the specified 1819SASL mechanism. Please note that feature might be limited at this time. 1820 1821|D |NGImap4ConnectionGroupIdPrefix 1822|Prefix to prepend to names in IMAP ACL transactions, to indicate the 1823name is a group name, not a user name. 1824 1825RFC4314 gives examples where group names are prefixed with `$`. Dovecot, 1826for one, follows this scheme, and will, for example, apply permissions 1827for `$admins` to all users in group `admins` in the absence of specific 1828permissions for the individual user. 1829 1830The default prefix is `$`. 1831|======================================================================= 1832 1833Web Interface Configuration 1834~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1835 1836The following additional parameters only affect the Web interface 1837behaviour of SOGo. 1838 1839[cols="3,47,50a"] 1840|======================================================================= 1841|S |SOGoPageTitle 1842|Parameter used to define the Web page title. 1843 1844Defaults to `SOGo` when unset. 1845 1846|U |SOGoLoginModule 1847|Parameter used to specify which module to show after login. Possible 1848values are: 1849 1850[options="compact"] 1851* `Calendar` 1852* `Mail` 1853* `Contacts` 1854 1855Defaults to `Calendar` when unset. 1856 1857|S |SOGoFaviconRelativeURL 1858|Parameter used to specify the relative URL of the site favion. 1859 1860When unset, defaults to the file `sogo.ico` under the default web 1861resources directory. 1862 1863|S |SOGoZipPath 1864|Parameter used to specify the path of the zip binary used to archive 1865messages. 1866 1867Defaults to `/usr/bin/zip` when unset. 1868 1869|D |SOGoSoftQuotaRatio 1870|Parameter used to change the quota returned by the IMAP server by 1871multiplying it by the specified ratio. Acts as a soft quota. Example: 1872`0.8`. 1873 1874|U |SOGoMailUseOutlookStyleReplies (not currently editable in Web interface) 1875|Parameter used to set if email replies should use Outlook's style. 1876 1877Defaults to `NO` when unset. 1878 1879|U |SOGoMailListViewColumnsOrder (not currently editable in Web 1880interface) 1881|Parameter used to specify the default order of the columns from the 1882SOGo webmail interface. The parameter is an array, for example: 1883 1884 SOGoMailListViewColumnsOrder = (Flagged, Attachment, Priority, From, Subject, Unread, Date, Size); 1885 1886|D |SOGoVacationEnabled 1887|Parameter used to activate the edition from the preferences window of a 1888vacation message. 1889 1890Requires Sieve script support on the IMAP host. 1891 1892Defaults to `NO` when unset. 1893 1894When enabling this parameter, one must also enable the associated 1895cronjob in `/etc/cron.d/sogo` in order to activate automatic vacation 1896message expiration. 1897 1898See the _Cronjob — Vacation messages expiration_ section below for 1899details. 1900 1901|D |SOGoForwardEnabled 1902|Parameter used to activate the edition from the preferences window of a 1903forwarding email address. Requires Sieve script support on the IMAP 1904host. 1905 1906Defaults to `NO` when unset. 1907 1908|D |SOGoForwardConstraints 1909|Parameter used to set constraints on possible addresses used when 1910automatically forwarding mails. When set to `0` (default), no constraint 1911is enforced. When set to `1`, only internal domains can be used. When 1912set to `2`, only external domains can be used. 1913 1914|D |SOGoSieveScriptsEnabled 1915|Parameter used to activate the edition from the preferences windows of 1916server-side mail filters. Requires Sieve script support on the IMAP 1917host. 1918 1919Defaults to `NO` when unset. 1920 1921|U |SOGoSieveFilters 1922|Parameter used to define initial Sieve scripts for users. The user 1923can still modify the scripts and the initial values will be written 1924to the Sieve server upon first login. 1925 1926|D |SOGoMailPollingIntervals 1927|Parameter used to define the mail polling intervals (in minutes) 1928available to the user. The parameter is an array that can contain the 1929following numbers: 1930 1931[options="compact"] 1932* `1` 1933* `2` 1934* `5` 1935* `10` 1936* `20` 1937* `30` 1938* `60` 1939 1940Defaults to the list above when unset. 1941 1942|U |SOGoMailMessageCheck 1943|Parameter used to define the mail polling interval at which the IMAP 1944server is queried for new messages. Possible values are: 1945 1946[options="compact"] 1947* `manually` 1948* `every_minute` 1949* `every_2_minutes` 1950* `every_5_minutes` 1951* `every_10_minutes` 1952* `every_20_minutes` 1953* `every_30_minutes` 1954* `once_per_hour` 1955 1956Defaults to `manually` when unset. 1957 1958|D |SOGoMailAuxiliaryUserAccountsEnabled 1959|Parameter used to activate the auxiliary IMAP accounts in SOGo. When 1960set to `YES`, users can add other IMAP accounts that will be visible 1961from the SOGo Webmail interface. 1962 1963Defaults to `NO` when unset. 1964 1965|U |SOGoDefaultCalendar 1966|Parameter used to specify which calendar is used when creating an event 1967or a task. Possible values are: 1968 1969[options="compact"] 1970* `selected` 1971* `personal` 1972* `first` 1973 1974Defaults to `selected` when unset. 1975 1976|U |SOGoDayStartTime 1977|The hour at which the day starts (`0` through `12`). 1978 1979Defaults to `8` when unset. 1980 1981|U |SOGoDayEndTime 1982|The hour at which the day ends (`12` through `23`). 1983 1984Defaults to `18` when unset. 1985 1986|U |SOGoFirstDayOfWeek 1987|The day at which the week starts in the week and month views (`0` 1988through `6`). `0` indicates Sunday. 1989 1990Defaults to `0` when unset. 1991 1992|U |SOGoFirstWeekOfYear 1993|Parameter used to defined how is identified the first week of the year. 1994Possible values are: 1995 1996[options="compact"] 1997* `January1` 1998* `First4DayWeek` 1999* `FirstFullWeek` 2000 2001Defaults to `January1` when unset. 2002 2003|U |SOGoTimeFormat 2004|The format used to display time in the timeline of the day and week 2005views. Please refer to the documentation for the date command or the 2006`strftime` C function for the list of available format sequence. 2007 2008Defaults to `%H:%M`. 2009 2010|U |SOGoCalendarCategories 2011|Parameter used to define the categories that can be associated to 2012events. This parameter is an array of arbitrary strings. 2013 2014Defaults to a list that depends on the language. 2015 2016|U |SOGoCalendarCategoriesColors 2017|Parameter used to define the colour of categories. This parameter 2018is a dictionary of category name/color. 2019 2020Defaults to `#F0F0F0` for all categories when unset. 2021 2022|U |SOGoCalendarEventsDefaultClassification 2023|Parameter used to defined the default classification for new events. 2024Possible values are: 2025 2026[options="compact"] 2027* `PUBLIC` 2028* `CONFIDENTIAL` 2029* `PRIVATE` 2030 2031Defaults to `PUBLIC` when unset. 2032 2033|U |SOGoCalendarTasksDefaultClassification 2034|Parameter used to defined the default classification for new tasks. 2035Possible values are: 2036 2037[options="compact"] 2038* `PUBLIC` 2039* `CONFIDENTIAL` 2040* `PRIVATE` 2041 2042Defaults to `PUBLIC` when unset. 2043 2044|U |SOGoCalendarDefaultReminder 2045|Parameter used to defined a default reminder for new events. Possible 2046values are: 2047 2048[options="compact"] 2049* `-PT5M` 2050* `-PT10M` 2051* `-PT15M` 2052* `-PT30M` 2053* `-PT45M` 2054* `-PT1H` 2055* `-PT2H` 2056* `-PT5H` 2057* `-PT15H` 2058* `-P1D` 2059* `-P2D` 2060* `-P1W` 2061 2062|D |SOGoFreeBusyDefaultInterval 2063|The number of days to include in the free busy information. The 2064parameter is an array of two numbers, the first being the number of days 2065prior to the current day and the second being the number of days 2066following the current day. 2067 2068Defaults to `(7, 7)` when unset. 2069 2070|U |SOGoBusyOffHours 2071|Parameter used to specify if off-hours should be automatically added to 2072the free-busy information. Off hours included weekends and periods 2073covered between _SOGoDayEndTime_ and _SOGoDayStartTime_. 2074 2075Defaults to `NO` when unset. 2076 2077|U |SOGoMailMessageForwarding 2078|The method the message is to be forwarded. Possible values are: 2079 2080[options="compact"] 2081* `inline` 2082* `attached` 2083 2084Defaults to `inline` when unset. 2085 2086|U |SOGoMailCustomFullName 2087|The string to use as full name when composing an email, if 2088_SOGoMailCustomFromEnabled_ is set in the user's domain defaults. 2089 2090When unset, the full name specified in the user sources for the user is 2091used instead. 2092 2093|U |SOGoMailCustomEmail 2094|The string to use as email address when composing an email, if 2095_SOGoMailCustomFromEnabled_ is set in the user's 2096domain defaults. When unset, the email specified in the user sources for 2097the user is used instead. 2098 2099|U |SOGoMailReplyPlacement 2100|The reply placement with respect to the quoted message. Possible values 2101are: 2102 2103[options="compact"] 2104* `above` 2105* `below` 2106 2107Defaults to `below`. 2108 2109|U |SOGoMailReplyTo 2110|The email address to use in the `reply-to` header field when the user 2111sends a message. 2112 2113Ignored when empty. 2114 2115|U |SOGoMailSignaturePlacement 2116|The placement of the signature with respect to the quoted message. 2117Possible values are: 2118 2119 2120[options="compact"] 2121* `above` 2122* `below` 2123 2124Defaults to `below`. 2125 2126|U |SOGoMailComposeMessageType 2127|The message composition format. Possible values are: 2128 2129* `text` 2130* `html` 2131 2132Defaults to `text`. 2133 2134|S |SOGoEnableEMailAlarms 2135|Parameter used to enable email-based alarms on events and tasks. 2136 2137Defaults to `NO` when unset. 2138 2139For this feature to work correctly, one must also set the 2140_OCSEMailAlarmsFolderURL_ parameter and enable the associated cronjob. 2141See the _Cronjob — EMail reminders_ section from this document for more 2142information. 2143 2144|U |SOGoContactsCategories 2145|Parameter used to define the categories that can be associated to 2146contacts. This parameter is an array of arbitrary strings. 2147 2148Defaults to a list that depends on the language. 2149 2150|D |SOGoUIAdditionalJSFiles 2151|Parameter used to define a list of additional JavaScript files loaded 2152by SOGo for all displayed web pages. This parameter is an array of 2153strings corresponding of paths to the arbitrary JavaScript files. The 2154paths are relative to the `WebServerResources` directory, which is 2155usually found under `/usr/lib/GNUstep/SOGo/.` 2156 2157|D |SOGoMailCustomFromEnabled 2158|Parameter used to allow or not users to specify custom "From" addresses 2159from SOGo's preferences panel. 2160 2161Defaults to `NO` when unset. 2162 2163|D |SOGoSubscriptionFolderFormat 2164|Parameter used to set the default formatting of a subscription folder 2165name. Available variables are: 2166 2167* `%{FolderName}` 2168* `%{UserName}` 2169* `%{Email}` 2170 2171Defaults to `%{FolderName} (%{UserName} <%{Email}>)` when unset. 2172 2173|D |SOGoUIxAdditionalPreferences 2174|Parameter used to enable an extra preferences tab using the content of 2175the template named `UIxAdditionalPreferences.wox`. This template should 2176be put under `~sogo/GNUstep/Library/SOGo/Templates/PreferencesUI/`. 2177 2178|D |SOGoMailJunkSettings 2179|Parameter used to enable email junk settings. The value is a dictionary 2180and the follow keys are supported: `vendor` (which must be set to "generic" 2181for now), `junkEmailAddress` which sets the email address to whom SOGo will 2182send junk mails to, `notJunkEmailAddress` which sets the email address to 2183whome SOGo will send non-junk mails to and `limit`, which is an integer value 2184and sets the maximum number of mails that will be attached to a 2185junk/not junk report sent by SOGo. Example: `SOGoMailJunkSettings = { 2186vendor = "generic"; junkEmailAddress = "spam@foo.com"; 2187notJunkEmailAddress = "ham@foo.com"; limit = 10; 2188};` 2189 2190|D |SOGoMailKeepDraftsAfterSend 2191|Parameter used to keep mails in the drafts folder once they have been 2192sent by SOGo. Defaults to `NO` when unset. 2193|======================================================================= 2194 2195SOGo Configuration Summary 2196~~~~~~~~~~~~~~~~~~~~~~~~~~ 2197 2198The complete SOGo configuration file `/usr/local/etc/sogo/sogo.conf` should look 2199like this: 2200 2201---- 2202{ 2203 SOGoProfileURL = 2204 "postgresql://sogo:sogo@localhost:5432/sogo/sogo_user_profile"; 2205 OCSFolderInfoURL = 2206 "postgresql://sogo:sogo@localhost:5432/sogo/sogo_folder_info"; 2207 OCSSessionsFolderURL = 2208 "postgresql://sogo:sogo@localhost:5432/sogo/sogo_sessions_folder"; 2209 SOGoAppointmentSendEMailNotifications = YES; 2210 SOGoCalendarDefaultRoles = ( 2211 PublicViewer, 2212 ConfidentialDAndTViewer 2213 ); 2214 SOGoLanguage = English; 2215 SOGoTimeZone = America/Montreal; 2216 SOGoMailDomain = acme.com; 2217 SOGoIMAPServer = localhost; 2218 SOGoDraftsFolderName = Drafts; 2219 SOGoSentFolderName = Sent; 2220 SOGoTrashFolderName = Trash; 2221 SOGoJunkFolderName = Junk; 2222 SOGoMailingMechanism = smtp; 2223 SOGoSMTPServer = "smtp://127.0.0.1"; 2224 SOGoUserSources = ( 2225 { 2226 type = ldap; 2227 CNFieldName = cn; 2228 IDFieldName = uid; 2229 UIDFieldName = uid; 2230 baseDN = "ou=users,dc=acme,dc=com"; 2231 bindDN = "uid=sogo,ou=users,dc=acme,dc=com"; 2232 bindPassword = qwerty; 2233 canAuthenticate = YES; 2234 displayName = "Shared Addresses"; 2235 hostname = localhost; 2236 id = public; 2237 isAddressBook = YES; 2238 port = 389; 2239 } 2240 ); 2241} 2242---- 2243 2244Multi-domains Configuration 2245~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2246 2247If you want your installation to isolate two groups of users, you must 2248define a distinct authentication source for each _domain_. Your domain keys 2249must have the same value as your email domain you want to add. Following is 2250the same configuration that now includes two domains (acme.com and 2251coyote.com): 2252 2253---- 2254{ 2255... 2256 domains = { 2257 acme.com = { 2258 SOGoMailDomain = acme.com; 2259 SOGoDraftsFolderName = Drafts; 2260 SOGoUserSources = ( 2261 { 2262 type = ldap; 2263 CNFieldName = cn; 2264 IDFieldName = uid; 2265 UIDFieldName = uid; 2266 baseDN = "ou=users,dc=acme,dc=com"; 2267 bindDN = "uid=sogo,ou=users,dc=acme,dc=com"; 2268 bindPassword = qwerty; 2269 canAuthenticate = YES; 2270 displayName = "Shared Addresses"; 2271 hostname = localhost; 2272 id = public_acme; 2273 isAddressBook = YES; 2274 port = 389; 2275 } 2276 ); 2277 }; 2278 coyote.com = { 2279 SOGoMailDomain = coyote.com; 2280 SOGoIMAPServer = imap.coyote.com; 2281 SOGoUserSources = ( 2282 { 2283 type = ldap; 2284 CNFieldName = cn; 2285 IDFieldName = uid; 2286 UIDFieldName = uid; 2287 baseDN = "ou=users,dc=coyote,dc=com"; 2288 bindDN = "uid=sogo,ou=users,dc=coyote,dc=com"; 2289 bindPassword = qwerty; 2290 canAuthenticate = YES; 2291 displayName = "Shared Addresses"; 2292 hostname = localhost; 2293 id = public_coyote; 2294 isAddressBook = YES; 2295 port = 389; 2296 } 2297 ); 2298 }; 2299 }; 2300} 2301---- 2302 2303The following additional parameters only affect SOGo when using multiple 2304domains. 2305 2306[cols="3,47,50a"] 2307|======================================================================= 2308|S |SOGoEnableDomainBasedUID 2309|Parameter used to enable user identification by domain. Users will be 2310able (without being required) to login using the form `username@domain`, 2311meaning that values of _UIDFieldName_ no longer have to be unique among 2312all domains but only within the same domain. Internally, users will 2313always be identified by the concatenation of their username and domain. 2314 2315Consequently, activating this parameter on an existing system implies 2316that user identifiers will change and their previous calendars and 2317address books will no longer be accessible unless a conversion is 2318performed. 2319 2320Defaults to `NO` when unset. 2321 2322|S |SOGoLoginDomains 2323|Parameter used to define which domains should be selectable from the 2324login page. This parameter is an array of keys from the `domains` 2325dictionary. 2326 2327Defaults to an empty array, which means that no domains appear on the 2328login page. If you prefer having the domain names listed, just use these 2329as keys for the the `domains` dictionary. 2330 2331|S |SOGoDomainsVisibility 2332|Parameter used to set domains visible among themselves. This parameter 2333is an array of arrays. 2334 2335Example: `SOGoDomainsVisibility = ((acme, coyote));` 2336 2337Defaults to an empty array, which means domains are isolated from each 2338other. 2339|======================================================================= 2340 2341Apache Configuration 2342~~~~~~~~~~~~~~~~~~~~ 2343 2344The SOGo configuration for Apache is located in 2345`/etc/httpd/conf.d/SOGo.conf`. 2346 2347Upon SOGo installation, a default configuration file is created which is 2348suitable for most configurations. 2349 2350You must also configure the following parameters in the SOGo 2351configuration file for Apache in order to have a working installation: 2352 2353---- 2354RequestHeader set "x-webobjects-server-port" "80" 2355RequestHeader set "x-webobjects-server-name" "yourhostname" 2356RequestHeader set "x-webobjects-server-url" "http://yourhostname" 2357---- 2358 2359You may consider enabling SSL on top of this current installation to 2360secure access to your SOGo installation. 2361 2362See http://httpd.apache.org/docs/2.2/ssl/ for details. 2363 2364You might also have to adjust the configuration if you have SELinux 2365enabled. 2366 2367The default configuration will use `mod_proxy` and `mod_headers` to 2368relay requests to the `sogod` parent process. This is suitable for small 2369to medium deployments. 2370 2371Starting Services 2372~~~~~~~~~~~~~~~~~ 2373 2374Once SOGo if fully installed and configured, start the services using 2375the following command: 2376 2377 service sogod start 2378 2379You may verify using thechkconfigcommand that the SOGo service is 2380automatically started at boot time. Restart the Apache service since 2381modules and configuration files were added: 2382 2383 service httpd restart 2384 2385Finally, you should also make sure that the `memcached` service is 2386started and that it is also automatically started at boot time. 2387 2388_Cronjob_ — EMail reminders 2389~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2390 2391SOGo allows you to set email-based reminders for events and tasks. To 2392enable this, you must enable the `SOGoEnableEMailAlarms` preference and 2393set the `OCSEMailAlarmsFolderURL` preference accordingly. 2394 2395Once you've correctly set those two preferences, you must create 2396a _cronjob_ that will run under the "sogo" user. This _cronjob_ should 2397be run every minute. 2398 2399A commented out example should have been installed in 2400`/etc/cron.d/sogo`, to enable it, simply uncomment it. 2401 2402As a reference, the _cronjob_ should de defined like this: 2403 2404---- 2405* * * * * /usr/sbin/sogo-ealarms-notify 2406---- 2407 2408If your mail server requires use of SMTP AUTH, specify a credential file 2409using `-p /path/to/credFile`. This file should contain the username and 2410password, separated by a colon (`username:password`) 2411 2412_Cronjob_ — Vacation messages expiration 2413~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2414 2415When vacation messages are enabled (see the parameter 2416_SOGoVacationEnabled_), users can set an expiration date to messages 2417auto-reply. For this feature to work, you must run a _cronjob_ under the 2418"sogo" user. 2419 2420A commented out example should have been installed in 2421`/etc/cron.d/sogo`. To work correctly this tool must login as an 2422administrative user on the sieve server. The required credentials must 2423be specified in a file by using `-p /path/to/credFile`. This file should 2424contain the username and password, separated by a colon 2425(`username:password`). 2426 2427The _cronjob_ should look like this: 2428 2429---- 24300 0 * * * sogo /usr/sbin/sogo-tool expire-autoreply -p /usr/local/etc/sogo/sieve.creds 2431---- 2432 2433Managing User Accounts 2434---------------------- 2435 2436Creating the SOGo Administrative Account 2437~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2438 2439First, create the SOGo administrative account in your LDAP server. The 2440following LDIF file (`sogo.ldif`) can be used as an example: 2441 2442---- 2443dn: uid=sogo,ou=users,dc=acme,dc=com 2444objectClass: top 2445objectClass: inetOrgPerson 2446objectClass: person 2447objectClass: organizationalPerson 2448uid: sogo 2449cn: SOGo Administrator 2450mail: sogo@acme.com 2451sn: Administrator 2452givenName: SOGo 2453---- 2454 2455Load the LDIF file inside your LDAP server using the following command: 2456 2457 ldapadd -f sogo.ldif -x -w qwerty -D cn=Manager,dc=acme,dc=com 2458 2459Finally, set the password (to the value `qwerty`) of the SOGo 2460administrative account using the following command: 2461 2462 ldappasswd -h localhost -x -w qwerty -D cn=Manager,dc=acme,dc=com uid=sogo,ou=users,dc=acme,dc=com -s qwerty 2463 2464Creating a User Account 2465~~~~~~~~~~~~~~~~~~~~~~~ 2466 2467SOGo uses LDAP directories to authenticate users. Use the following LDIF 2468file (`jdoe.ldif`) as an example to create a SOGo user account: 2469 2470---- 2471dn: uid=jdoe,ou=users,dc=acme,dc=com 2472objectClass: top 2473objectClass: inetOrgPerson 2474objectClass: person 2475objectClass: organizationalPerson 2476uid: jdoe 2477cn: John Doe 2478mail: jdoe@acme.com 2479sn: Doe 2480givenName: John 2481---- 2482 2483Load the LDIF file inside your LDAP server using the following command: 2484 2485 ldapadd -f jdoe.ldif -x -w qwerty -D cn=Manager,dc=acme,dc=com 2486 2487Finally, set the password (to the value `qwerty`) of the SOGo 2488administrative account using the following command: 2489 2490 ldappasswd -h localhost -x -w qwerty -D cn=Manager,dc=acme,dc=com uid=jdoe,ou=users,dc=acme,dc=com -s qwerty 2491 2492As an alternative to using command-line tools, you can also use LDAP 2493editors such as _Luma_ or _Apache Directory Studio_ to make your work 2494easier. These GUI utilities can make use of templates to create and 2495pre-configure typical user accounts or any standardized LDAP record, 2496along with the correct object classes, fields and default values. 2497 2498Microsoft Enterprise ActiveSync 2499------------------------------- 2500 2501SOGo supports the Microsoft ActiveSync protocol. 2502 2503ActiveSync clients can fully synchronize contacts, emails, events and 2504tasks with SOGo. Freebusy and GAL lookups are also supported, as well as 2505"Smart reply" and "Smart forward" operations. 2506 2507To enable Microsoft ActiveSync support in SOGo, you must install the 2508required packages. 2509 2510 yum install sogo-activesync libwbxml 2511 2512Once installed, simply uncomment the following lines from your SOGo 2513Apache configuration: 2514 2515---- 2516ProxyPass /Microsoft-Server-ActiveSync \ 2517 http://127.0.0.1:20000/SOGo/Microsoft-Server-ActiveSync \ 2518 retry=60 connectiontimeout=5 timeout=360 2519---- 2520 2521Restart Apache afterwards. 2522 2523The following additional parameters only affect SOGo when using 2524ActiveSync: 2525 2526[cols="3,47,50a"] 2527|======================================================================= 2528|S |SOGoMaximumPingInterval 2529|Parameter used to set the maximum amount of time, in seconds, SOGo will 2530wait before replying to a Ping command. 2531 2532If not set, it defaults to `10` seconds. 2533 2534|S |SOGoMaximumSyncInterval 2535|Parameter used to set the maximum amount of time, in seconds, SOGo will 2536wait before replying to a Sync command. 2537 2538If not set, it defaults to `30` seconds. 2539 2540|S |SOGoInternalSyncInterval 2541|Parameter used to set the maximum amount of time, in seconds, SOGo will 2542wait before doing an internal check for data changes (add, delete, and 2543update). This parameter must be lower than _SOGoMaximumSyncInterval_ and 2544_SOGoMaximumPingInterval_. 2545 2546If not set, it defaults to `10` seconds. 2547 2548|S |SOGoMaximumSyncResponseSize 2549|Parameter used to overwrite the maximum response size during 2550a Sync operation. The value is in kilobytes. Setting this to 512 2551means the response size will be of 524288 bytes or less. Note that 2552if you set the value too low and a mail message (or any other object) 2553surpasses it, it will still be synced but only this item will be. 2554 2555Defaults to `0`, which means no overwrite is performed. 2556 2557|S |SOGoMaximumSyncWindowSize 2558|Parameter used to overwrite the maximum number of items returned during 2559a Sync operation. 2560 2561Defaults to `0`, which means no overwrite is performed. 2562 2563Setting this parameter to a value greater than `512` will 2564have unexpected behaviour with various ActiveSync clients. 2565|S |SOGoEASDebugEnabled 2566|Parameter used to log the complete request and response of every single 2567EAS command. 2568 2569Defaults to `NO`, which means no logging is performed. 2570 2571|S |SOGoMaximumPictureSize 2572|Parameter used to overwrite the maximum number of bytes returned in the picture 2573for EAS Search operations in the GAL. 2574 2575If not set, it defaults to `102400` bytes, or 100 KB. 2576|======================================================================= 2577 2578Please be aware of the following limitations: 2579 2580* Outlook 2013/2016 does not search the GAL. One possible alternative 2581solution is to configure Outlook to use a LDAP server (over SSL) with 2582authentication. Outlook 2013/2016 also does not seem to support multiple 2583address books over ActiveSync. 2584* To successfully synchronize Outlook email categories, a corresponding 2585mail label (Preferences->Mail Options) has to be created manually in SOGo 2586for each label defined in Outlook. The name in SOGo and in Outlook must be 2587identical. 2588* Make sure you do not use a self-signed certificate. While this will 2589work, Outlook will work intermittently as it will raise popups for 2590certificate validation, sometimes in background, preventing the user to 2591see the warning and thus, preventing any synchronization to happen. 2592* ActiveSync clients keep connections open for a while. Each connection 2593will grab a hold on a sogod process so you will need a lot of processes 2594to handle many clients. Make sure you tune your SOGo server when having 2595lots of ActiveSync clients. 2596* Repetitive events with occurrences exceptions are currently not 2597supported. 2598* Outlook 2013/2016 Autodiscovery is currently not supported. 2599* Outlook 2013/2016 freebusy lookups are supported using the Internet 2600Free/Busy feature of Outlook 2013/2016. Please 2601see http://support.microsoft.com/kb/291621 for configuration 2602instructions. On the SOGo side, _SOGoEnablePublicAccess_ must be set to 2603`YES` and the URL to use must be of the following format: 2604`http://<hostname>/SOGo/dav/public/%NAME%/freebusy.ifb` 2605* If you have very large mail folders (thousands of messages), you will 2606need to adjust the word size of your IMAP server. In Dovecot, the parameter 2607to increase is "imap_max_line_length" while under Cyrus IMAP Server, the 2608parameter is "maxword". We suggest a buffer of 2MB. 2609* If you are using MySQL, make sure you set "max_allowed_packet" to a large value 2610since the EAS cache size can be large for mailboxes with thousands of messages. 2611A 64M or even 128M value is recommended. 2612 2613In order to use the SOGo ActiveSync support code in production 2614environments, you need to get a proper usage license from Microsoft. 2615Please contact them directly to negotiate the fees associated to your 2616user base. 2617 2618To contact Microsoft, please visit: 2619 2620http://www.microsoft.com/en-us/legal/intellectualproperty/ 2621 2622and send an email to iplicreq@microsoft.com 2623 2624Inverse inc. provides this software for free, but is not responsible for 2625anything related to its usage. 2626 2627Microsoft Enterprise ActiveSync Tuning 2628-------------------------------------- 2629 2630First of all, it is important to know that most EAS devices will keep 2631HTTP connections open to SOGo (and thus, Apache) for a long time. This 2632is required for "push" to work properly. Connections can stay open for 2633up to one hour, or 3600 seconds. 2634 2635The first parameter to check is related to Apache's proxying to 2636SOGo: 2637 2638---- 2639ProxyPass /Microsoft-Server-ActiveSync \ 2640 http://127.0.0.1:20000/SOGo/Microsoft-Server-ActiveSync \ 2641 retry=60 connectiontimeout=5 timeout=360 2642---- 2643 2644The above line sets a timeout for up to 360 seconds, or 6 minutes. If 2645you want to let EAS clients keep their HTTP connections open for up 2646to an hour, you must change the timeout parameter and set it to 3600. 2647 2648If you change this value, the WOWatchDogRequestTimeout parameter must be changed 2649accordingly in SOGo's configuration file (/usr/local/etc/sogo/sogo.conf). By default, 2650a SOGo child process is allowed to handle a request that can take up 2651to 10 minutes before it gets killed by its parent process. When using 2652EAS "push", the client expects to keep its connection open for up to one 2653hour - so the WOWatchDogRequestTimeout, which is set in minutes, 2654must be adjusted accordingly. 2655 2656EAS clients will keep HTTP connections open for a long time 2657during these two EAS commands: Ping and Sync. By default, SOGo will prevent 2658EAS clients from keeping connections for a long time. This is to avoid the 2659situation where all SOGo child processes would be monopolized by EAS clients - 2660rendering the SOGo web interface or DAV interface unavailable. The 2661default SOGo behavior is thus similar to disable EAS push entirely. 2662 2663Two SOGo configuration parameters are available to modify this behavior: 2664SOGoMaximumPingInterval (set by default to 10 seconds) and 2665SOGoMaximumSyncInterval (set by default to 30 seconds). If you want 2666connection to stay open for up to one hour, you should set these 2667slightly under 3600 seconds (say 3540 - or 59 minutes). During a 2668long-lived HTTP connection, the SOGo child process will perform 2669internal polling to detect changes and return them to the EAS client 2670if any changes are found. The parameter used to control this 2671is SOGoInternalSyncInterval. By default, polling is done every 10 2672seconds. This might generate too much load on large-scale system. 2673 2674The last configuration parameter to adjust is WOWorkersCount - which sets the 2675number of SOGo child process that will be used to handle requests. 2676You should have at least one child per EAS device configured to use 2677"push". You must also have more children than you have EAS devices 2678configured to use "push" - in order to handle normal SOGo requests to 2679its Web or DAV interfaces. 2680 2681Here are some usage examples for EAS devices using "push". In all 2682cases, the Apache timeout is set to 3600 and the 2683WOWatchDogRequestTimeout parameter is set to 60. 2684 2685Example 1 - 100 users, 10 EAS devices: 2686 2687---- 2688WOWorkersCount = 15; 2689SOGoMaximumPingInterval = 3540; 2690SOGoMaximumSyncInterval = 3540; 2691SOGoInternalSyncInterval = 30; 2692---- 2693 2694Example 2 - 1000 users, 100 EAS devices: 2695 2696---- 2697WOWorkersCount = 120; 2698SOGoMaximumPingInterval = 3540; 2699SOGoMaximumSyncInterval = 3540; 2700SOGoInternalSyncInterval = 60; 2701---- 2702 2703 2704Using SOGo 2705---------- 2706 2707SOGo Web Interface 2708~~~~~~~~~~~~~~~~~~ 2709 2710To acces the SOGo Web Interface, point your Web browser, which is 2711running from the same server where SOGo was installed, to the following 2712URL: http://localhost/SOGo. 2713 2714Log in using the "jdoe" user and the "qwerty" password. The underlying 2715database tables will automatically be created by SOGo. 2716 2717Mozilla Thunderbird and Lightning 2718~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2719 2720Alternatively, you can access SOGo with a GroupDAV and a CalDAV client. 2721A typical well-integrated setup is to use Mozilla Thunderbird and 2722Mozilla Lightning along with Inverse's _SOGo Connector_ plug in to 2723synchronize your address books and the Inverse's _SOGo Integrator_ plug 2724in to provide a complete integration of the features of SOGo into 2725Thunderbird and Lightning. Refer to the documentation of Thunderbird to 2726configure an initial IMAP account pointing to your SOGo server and using 2727the user name and password mentioned above. 2728 2729With the SOGo Integrator plug in, your calendars and address books will 2730be automatically discovered when you login in Thunderbird. This plug in 2731can also propagate specific extensions and default user settings among 2732your site. However, be aware that in order to use the SOGo Integrator 2733plug in, you will need to repackage it with specific modifications. 2734Please refer to the documentation published online: 2735 2736http://www.sogo.nu/downloads/documentation.html 2737 2738If you only use the SOGo Connector plug in, you can still easily access 2739your data. 2740 2741To access your personal address book: 2742 2743* Choose Go > Address Book. 2744* Choose File > New > Remote Address Book. 2745* Enter a significant name for your calendar in the Name field. 2746* Type the following URL in the URL field: 2747`http://localhost/SOGo/dav/jdoe/Contacts/personal/` 2748* Click on OK. 2749 2750To access your personal calendar: 2751 2752* Choose Go > Calendar. 2753* Choose Calendar > New Calendar. 2754* Select On the Network and click on Continue. 2755* Select CalDAV. 2756* Type the following URL in the URL field: 2757`http://localhost/SOGo/dav/jdoe/Calendar/personal/` 2758* Click on Continue. 2759 2760Apple Calendar and iOS 2761~~~~~~~~~~~~~~~~~~~~~~ 2762 2763Apple Calendar and Mac OS X and the calendar application on iOS can also be used 2764as a client application for SOGo. 2765 2766To configure the application so it works with SOGo, create a new account and specify, 2767as the Account URL, an URL such as: 2768 2769http://localhost/SOGo/dav/jdoe/ 2770 2771Note that the trailing slash is important for the old Apple iCal 3 application. 2772 2773Apple AddressBook 2774~~~~~~~~~~~~~~~~~ 2775 2776Since Mac OS X 10.6 (Snow Leopard), Apple AddressBook can be configured 2777to use SOGo. 2778 2779In order to make this work, you must add a new virtual host in your 2780Apache configuration file to listen on port 8800 and handle requests 2781coming from iOS devices. 2782 2783The virtual host should be defined like: 2784 2785---- 2786<VirtualHost *:8800> 2787 RewriteEngine Off 2788 ProxyRequests Off 2789 SetEnv proxy-nokeepalive 1 2790 ProxyPreserveHost On 2791 ProxyPassInterpolateEnv On 2792 ProxyPass /principals http://127.0.0.1:20000/SOGo/dav/ interpolate 2793 ProxyPass /SOGo http://127.0.0.1:20000/SOGo interpolate 2794 ProxyPass / http://127.0.0.1:20000/SOGo/dav/ interpolate 2795 2796 <Location /> 2797 Order allow,deny 2798 Allow from all 2799 </Location> 2800 <Proxy http://127.0.0.1:20000> 2801 RequestHeader set "x-webobjects-server-port" "8800" 2802 RequestHeader set "x-webobjects-server-name" "acme.com:8800" 2803 RequestHeader set "x-webobjects-server-url" "http://acme.com:8800" 2804 RequestHeader set "x-webobjects-server-protocol" "HTTP/1.0" 2805 RequestHeader set "x-webobjects-remote-host" "127.0.0.1" 2806 AddDefaultCharset UTF-8 2807 </Proxy> 2808 ErrorLog /var/log/apache2/ab-error.log 2809 CustomLog /var/log/apache2/ab-access.log combined 2810</VirtualHost> 2811---- 2812 2813This configuration is also required if you want to configure a CardDAV 2814account on an Apple iOS device (version 4.0 and later). 2815 2816Microsoft ActiveSync / Mobile Devices 2817~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 2818 2819You can synchronize contacts, emails, events and tasks from SOGo with 2820any mobile devices that support Microsoft ActiveSync. Microsoft Outlook 28212013 is also supported. 2822 2823The Microsoft ActiveSync server URL is generally something 2824like: `http://localhost/Microsoft-Server-ActiveSync`. 2825 2826Upgrading 2827--------- 2828 2829This section describes what needs to be done when upgrading to the 2830current version of SOGo from the previous release. 2831 2832[cols="100a"] 2833|======================================================================= 2834h|2.3.1 2835|The SOGoCalendarDefaultCategoryColor default has been removed. If you 2836want to customize the color of calendar categories, use the 2837SOGoCalendarCategories and SOGoCalendarCategoriesColors defaults. 2838 2839h|2.3.0 2840|Run the shell script `sql-update-2.2.17_to_2.3.0.sh` or 2841`sql-update-2.2.17_to_2.3.0-mysql.sh` (if you use MySQL). 2842 2843This will grow the "participant states" field of calendar quick tables to a larger 2844size and add the the "c_description" column to calendar quick tables. 2845 2846Moreover, if you are using a multi-domain configuration, make sure the keys for 2847your domains match the email domains you have defined. 2848 2849h|2.2.8 2850|The configuration configuration parameters were renamed: 2851 2852[options="compact"] 2853* _SOGoMailMessageCheck_ was replaced with _SOGoRefreshViewCheck_ 2854* _SOGoMailPollingIntervals_ was replaced with _SOGoRefreshViewIntervals_ 2855 2856Backward compatibility is in place for the old preferences values. 2857 2858h|2.0.5 2859|The configuration is now stored in /usr/local/etc/sogo/sogo.conf. Perform the following commands as root to migrate your previous user defaults: 2860 2861---- 2862install -d -m 750 -o sogo -g sogo /usr/local/etc/sogo 2863sudo -u sogo sogo-tool dump-defaults > /usr/local/etc/sogo/sogo.conf 2864chown root:sogo /usr/local/etc/sogo/sogo.conf 2865chmod 640 /usr/local/etc/sogo/sogo.conf 2866sudo -u sogo mv ~/GNUstep/Defaults/.GNUstepDefaults \ 2867 ~/GNUstep/Defaults/GNUstepDefaults.old 2868---- 2869 2870h|2.0.4 2871|The parameter _SOGoForceIMAPLoginWithEmail_ is now deprecated and is 2872replaced by _SOGoForceExternalLoginWithEmail_ (which extends the 2873functionality to SMTP authentication). Update your configuration if you 2874use this parameter. 2875 2876The sogo user is now a system user. For new installs, this means that 2877`su - sogo` won't work anymore. Please use `sudo -u sogo <cmd>` instead. 2878If used in scripts from cronjobs, `requiretty` must be disabled in 2879sudoers. 2880 2881h|1.3.17 2882|Run the shell script `sql-update-1.3.16_to_1.3.17.sh` or 2883`sql-update-1.3.16_to_1.3.17-mysql.sh` (if you use MySQL). 2884 2885This will grow the "cycle info" field of calendar tables to a larger 2886size. 2887 2888h|1.3.12 2889|Once you have updated and restarted SOGo, run the shell script 2890`sql-update-1.3.11_to_1.3.12.sh` or 2891`sql-update-1.3.11_to_1.3.12-mysql.sh` (if you use MySQL). 2892 2893This will grow the "content" field of calendar and addressbook tables to 2894a larger size and fix the primary key of the session table. 2895 2896h|1.3.9 2897|For Red Hat-based distributions, version 1.23 of GNUstep will be 2898installed. Since the location of the Web resources changes, the Apache 2899configuration file (`SOGo.conf`) has been adapted. Verify your Apache 2900configuration if you have customized this file. 2901|======================================================================= 2902 2903include::includes/additional-info.asciidoc[] 2904 2905include::includes/commercial-support.asciidoc[] 2906
