This page moved to GitLab Wiki space

https://gitlab.gnome.org/GNOME/evolution/-/wikis/Autoconfig-Sources

Contents

  1. Autoconfig Sources
    1. Settings
    2. Creating the templates
    3. Debugging
    4. Examples
      1. CalDAV calendar
      2. IMAP
      3. Signatures
      4. Exchange Web Services

Autoconfig Sources

Apart of the mail account Autoconfig, the evolution-source-registry supports auto-configuration on the account definition bases, the "low-level" source files. The source files are stored in ~/.config/evolution/sources/ with an extension .source. The name serves two purposes, a) it's a unique identificator (UID) of the source; b) it can be referenced by other sources by this name (without the extension). Whenever a new account, address book, calendar, ... is created a new .source file (one or more) is added to this directory. The source files are ini-like files with sections and keys describing their purpose. The evolution-source-registry verifies on each start all the sources with section [Autoconfig] whether corresponding file in the configured shared directory did not change its Revision. When it did, it's replaced with the content from the shared directory.

Settings

There are two keys in the GSettings at the org.gnome.evolution-data-server scheme, which can be used:

  • autoconfig-directory - a full path to a directory where .source files with preconfigured options can be stored; apart of this directory also those listed in XDG_CONFIG_DIRS, with appended evolution-data-server/autoconfig, are searched for;

  • autoconfig-variables - a list of variables which can be part of the autoconfig .source files; each item of the array is expected to be of the form: name=value. These variables are checked before environment variables, but after the predefined USER, REALNAME and HOST variables

Creating the templates

Let the sources for autoconfig be named templates. The easiest way to create such is to run Evolution on one of the machines and configured the desired account. Check which files had been created in ~/.config/evolution/sources/ and copy them elsewhere, say into /mnt/share/eds-autoconfig. Edit the files and replace any value with a variable reference, like in case of the [Authentication] User=bob with [Authentication] User=${USER}, which will replace the ${USER} with the logged in user name on the user machine. Similarly 

[Mail Identity]
Address=bob@example.com
Name=Bob Doe

might be replaced with 

[Mail Identity]
Address=${USER}@example.com
Name=${REALNAME}

Note that only Mail sources contain the [Mail Identity] section, you should not add it to the .source file when it was not there before. Also note this example expects the user login matches the email address and the real name on the machines matches what the mail identity should use.

There can be more sections and keys to be changed, depending on what account information is preconfigured.

After this add to each file these lines: 

[Autoconfig]
Revision=1

They are important, the evolution-source-registry recognizes the preconfigured sources with them and the Revision is used for the comparison. The revision itself is not interpreted in any way, it can be anything. The code only verifies whether it's the same or a different value. The revision is also unique for its file, thus an account with three .source files can have each file with a different revision.

That's basically it. Once the user machines are configured to look into the directory with the preconfigured sources (for example through the settings' autoconfig-directory) and the evolution-source-registry is restarted, it'll check the preconfigured sources and it'll add the changed or new sources to the user's configuration files.

Note the [Data Source] DisplayName= contains the name of the account, how it'll be shown in the applications. It's not necessary to use the same display name in all the files.

Debugging

The evolution-source-registry can be started from a terminal as: 

   $ ESR_DEBUG=1 /usr/libexec/evolution-source-registry

(the actual path can differ in some distributions). Search for the messages containing Autoconfig:, which should be near the top, to see what it does.

Examples

Below are few examples. Let the preconfigured sources be saved into /mnt/share/eds-autoconfig directory. That means each user machine will have auto-mounted this directory before login (or at least before the evolution-source-registry is started) and this directory is set for the autoconfig into the settings, for example by running this command on each user machine: gsettings set org.gnome.evolution-data-server autoconfig-directory "/mnt/share/eds-autoconfig"

CalDAV calendar

The calendar .source file looks like this: 

[Autoconfig]
Revision=1

[Data Source]
DisplayName=${REALNAME} calendar
Enabled=true
Parent=caldav-stub

[Security]
Method=tls

[Authentication]
Host=caldav.example.com
Method=plain/password
Port=443
ProxyUid=system-proxy
RememberPassword=true
User=${USER}
CredentialName=
IsExternal=false

[Refresh]
Enabled=true
IntervalMinutes=60

[WebDAV Backend]
AvoidIfmatch=false
CalendarAutoSchedule=false
Color=
DisplayName=${REALNAME} calendar
EmailAddress=${USER}@example.com
ResourcePath=/remote.php/caldav/${USER}/calendar/
ResourceQuery=

[Calendar]
BackendName=caldav
Color=#73d216
Selected=true

It can be named anyhow, it only should be a unique name. Either the one generated by the evolution-data-server can be used, or some human-descriptive, like caldav.example.com.source, can be used.

IMAP

Mail accounts are more complicated, they use three different files, which are referenced by each other. The reference is there multiple times. If careful, the files can be renamed too.

Let the first file be named 0-ac-001.source with this content: 

[Autoconfig]
Revision=005

[Data Source]
DisplayName=Company Account
Enabled=true
Parent=

[Offline]
StaySynchronized=false

[Refresh]
Enabled=true
IntervalMinutes=100

[Authentication]
Host=imap.example.com
Method=none
Port=993
RememberPassword=true
User=${USER}
ProxyUid=system-proxy
LimitTlsVersion=-1
CredentialName=

[Mail Account]
BackendName=imapx
IdentityUid=0-ac-002
ArchiveFolder=folder://0-ac-001/INBOX/Archive
NeedsInitialSetup=false

[Security]
Method=ssl-on-alternate-port

[Imapx Backend]
FilterInbox=true
BatchFetchCount=500
CheckAll=false
CheckSubscribed=true
ConcurrentConnections=7
FetchOrder=ascending
FilterAll=false
FilterJunk=false
FilterJunkInbox=false
MobileMode=false
Namespace=Templates/
RealJunkPath=INBOX/Spam
RealTrashPath=INBOX/Trash
ShellCommand=ssh -C -l %u %h exec /usr/sbin/imapd
UseIdle=true
UseNamespace=false
UseQresync=true
UseRealJunkPath=false
UseRealTrashPath=false
UseShellCommand=false
UseSubscriptions=true
IgnoreOtherUsersNamespace=false
IgnoreSharedFoldersNamespace=false
StoreChangesInterval=3
UseMultiFetch=false

It describes settings for the IMAP account on host imap.example.com. Note of the [Mail Account] IdentityUid=0-ac-002, which references the second file, 0-ac-002.source with this content: 

[Autoconfig]
Revision=003

[Data Source]
DisplayName=Company Account
Enabled=true
Parent=0-ac-001

[Mail Composition]
Bcc=
Cc=
DraftsFolder=folder://0-ac-001/Drafts
SignImip=true
TemplatesFolder=folder://0-ac-001/Templates
ReplyStyle=default

[Mail Identity]
Address=${USER}@example.com
Name=${REALNAME}
Organization=
ReplyTo=
SignatureUid=autogenerated
Aliases=

[Mail Submission]
SentFolder=folder://0-ac-001/INBOX/atest
TransportUid=0-ac-003
RepliesToOriginFolder=false

[Pretty Good Privacy (OpenPGP)]
AlwaysTrust=false
EncryptToSelf=true
KeyId=
SigningAlgorithm=
SignByDefault=false
EncryptByDefault=false
PreferInline=false

[Message Disposition Notifications]
ResponsePolicy=ask

[Secure MIME (S/MIME)]
EncryptionCertificate=
EncryptByDefault=false
EncryptToSelf=true
SigningAlgorithm=
SigningCertificate=
SignByDefault=false

This file references 0-ac-003 in the [Mail Submission] TransportUid= key and also the folders from the IMAP account (0-ac-001). The last file serves as a transport definition, aka how the messages should be sent. Its name is 0-ac-003.source and it contains the following: 

[Autoconfig]
Revision=003

[Data Source]
DisplayName=Company Account
Enabled=true
Parent=0-ac-001

[Mail Transport]
BackendName=smtp

[Authentication]
Host=smtp.example.com
Method=plain/password
Port=465
RememberPassword=true
User=${USER}
ProxyUid=system-proxy
CredentialName=

[Security]
Method=tls

These three files together define an IMAP account for the user.

Signatures

A company might have a company wide signature to be used for each company communication. The IMAP account from the above uses [Mail Identity] SignatureUid=autogenerated in the 0-ac-002.source file. A signature definition requires two files, one is the signature definition, the other is the signature itself. The signature definition is a .source file as well. Let it be 0-sig-001.source. Its content is: 

[Autoconfig]
Revision=001

[Data Source]
DisplayName=Company signature
Enabled=true
Parent=

[Mail Signature]
MimeType=text/plain

and the signature file is 0-sig-001.signature (note only the extension changed, the file name is the same as the .source file) containing: 

Example Company Inc.                        www.example.com
${REALNAME}                             ${USER}@example.com

Copy these two files into the directory with the preconfigured sources and the signature will be added. To have it automatically used by the above IMAP account open the 0-ac-002.source file and change [Mail Identity] SignatureUid=autogenerated to [Mail Identity] SignatureUid=0-sig-001. Remeber to change the [Autoconfig] Revision= too, in case any of the users have the account added already.

Whenever the 0-sig-001.signature is updated, change the 0-sig-001.source's [Autoconfig] Revision= as well.

Exchange Web Services

The Exchange Web Services (EWS) accounts are similar to mail accounts, but there is one more file, a collection source, which is the parent of all the accounts. Let it be called 0-ews-outlook-001.source. It will reference an @outlook.com account. Its content is: 

[Autoconfig]
Revision=001

[Data Source]
DisplayName=Outlook.com Account
Enabled=true
Parent=

Populated=false

[Offline]
StaySynchronized=false

[Authentication]
Host=outlook.office365.com
Method=PLAIN
Port=443
ProxyUid=system-proxy
RememberPassword=true
User=${USER}@outlook.com
CredentialName=

IsExternal=false

[Collection]
BackendName=ews
CalendarEnabled=true
ContactsEnabled=true
Identity=${USER}@outlook.com
MailEnabled=true
CalendarUrl=
ContactsUrl=

[Security]
Method=none

[Ews Backend]
FilterInbox=false
StoreChangesInterval=3
LimitByAge=false
LimitUnit=years
LimitValue=1
CheckAll=false
ListenNotifications=true
Email=${USER}@outlook.com
FilterJunk=false
FilterJunkInbox=false
GalUid=
Hosturl=https://outlook.office365.com/EWS/Exchange.asmx
Oaburl=
OabOffline=false
OalSelected=
Timeout=120
UseImpersonation=false
ImpersonateUser=
OverrideUserAgent=false
UserAgent=Microsoft Office/14.0 (Windows NT ,5.1; Microsoft Outlook 14.0.4734; Pro)
OverrideOauth2=true
Oauth2Tenant=common
Oauth2ClientId=
Oauth2RedirectUri=

The second file 0-ews-outlook-002.source is: 

[Autoconfig]
Revision=001

[Data Source]
DisplayName=Outlook.com Account
Enabled=true
Parent=0-ews-outlook-001

Populated=true

[Refresh]
Enabled=false
IntervalMinutes=60

[Mail Account]
BackendName=ews
IdentityUid=0-ews-outlook-003
ArchiveFolder=
NeedsInitialSetup=false
MarkSeen=inconsistent
MarkSeenTimeout=1500

[Exchange Web Services Folder]
ChangeKey=
Id=
Foreign=false
ForeignSubfolders=false
ForeignMail=
FreebusyWeeksBefore=1
FreebusyWeeksAfter=5
Public=false
UsePrimaryAddress=false
FetchGalPhotos=false

The third file 0-ews-outlook-003.source is: 

[Autoconfig]
Revision=001

[Data Source]
DisplayName=Outlook.com Account
Enabled=true
Parent=0-ews-outlook-001
Populated=false

[Mail Composition]
Bcc=
Cc=
DraftsFolder=folder://0-ews-outlook-002/Drafts
ReplyStyle=default
SignImip=true
TemplatesFolder=folder://local/Templates
StartBottom=inconsistent
TopSignature=inconsistent
Language=

[Mail Identity]
Address=${USER}@outlook.com
Aliases=
Name=${REALNAME}
Organization=
ReplyTo=
SignatureUid=autogenerated

[Mail Submission]
SentFolder=folder://0-ews-outlook-002/Sent%20Items
TransportUid=0-ews-outlook-004
RepliesToOriginFolder=false
UseSentFolder=true

[Pretty Good Privacy (OpenPGP)]
AlwaysTrust=false
EncryptToSelf=true
KeyId=
SigningAlgorithm=
SignByDefault=false
EncryptByDefault=false
PreferInline=false

[Message Disposition Notifications]
ResponsePolicy=ask

[Secure MIME (S/MIME)]
EncryptionCertificate=
EncryptByDefault=false
EncryptToSelf=true
SigningAlgorithm=
SigningCertificate=
SignByDefault=false

Finally, the fourth file 0-ews-outlook-004.source is: 

[Autoconfig]
Revision=001

[Data Source]
DisplayName=Outlook.com Account
Enabled=true
Parent=0-ews-outlook-001

Populated=true

[Mail Transport]
BackendName=ews

Apps/Evolution/AutoconfigSources (last edited 2024-03-07 12:46:41 by MilanCrha)