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