From 03eafcc00f36f9a840eb9d99c5f351d79219dd4b Mon Sep 17 00:00:00 2001 From: Nicolas Sebrecht Date: Wed, 14 Jan 2015 17:12:08 +0100 Subject: [PATCH] offlineimap.conf: normalize style and format - improve style and reading for the eyes - improve wording - add minor comments - remove on duplicate option - give location of each +1 section Signed-off-by: Nicolas Sebrecht --- offlineimap.conf | 701 +++++++++++++++++++++++++++++------------------ 1 file changed, 433 insertions(+), 268 deletions(-) diff --git a/offlineimap.conf b/offlineimap.conf index d953f0e..e0ef4f4 100644 --- a/offlineimap.conf +++ b/offlineimap.conf @@ -5,7 +5,8 @@ # More details can be found in the included user documention, which is # also available at: http://docs.offlineimap.org/en/latest/ -# NOTE: Settings generally support python interpolation. This means + +# NOTE 1: Settings generally support python interpolation. This means # values can contain python format strings which refer to other values # in the same section, or values in a special DEFAULT section. This # allows you for example to use common settings for multiple accounts: @@ -21,49 +22,58 @@ # # would set the trashfolder setting for your German Gmail accounts. -# NOTE2: This implies that any '%' needs to be encoded as '%%' +# NOTE 2: Above feature implies that any '%' needs to be encoded as '%%' -# NOTE3: Any variables that are subject to the environment variables +# NOTE 3: Any variable that is subject to the environment variables # ($NAME) and tilde (~username/~) expansions will receive tilde -# expansion first and only after this environment variables will be -# expanded in the resulting string. This behaviour is intentional +# expansion first and only after the environment variable will be +# expanded in the resulting string. This behaviour is intentional # as it coincides with typical shell expansion strategy. + ################################################## # General definitions ################################################## [general] -# This specifies where offlineimap is to store its metadata. +# This specifies where OfflineIMAP is to store its metadata. # This directory will be created if it does not already exist. # # Tilde and environment variable expansions will be performed. - +# #metadata = ~/.offlineimap -# This variable specifies which accounts are defined. Separate them -# with commas. Account names should be alphanumeric only. -# You will need to specify one section per account below. You may -# not use "general" for an account name. +# This option stands in the [general] section. +# +# This variable specifies which accounts are defined. Separate them with commas. +# Account names should be alphanumeric only. You will need to specify one +# section per account below. You may not use "general" for an account name. +# +# Always use ASCII characters only. +# accounts = Test -# Offlineimap can synchronize more than one account at a time. If you -# want to enable this feature, set the below value to something -# greater than 1. To force it to synchronize only one account at a -# time, set it to 1. -# -# Note: if you are using autorefresh and have more than one account, -# you must set this number to be >= to the number of accounts you have; -# since any given sync run never "finishes" due to a timer, you will never -# sync your additional accounts if this is 1. +# This option stands in the [general] section. +# +# Offlineimap can synchronize more than one account at a time. If you want to +# enable this feature, set the below value to something greater than 1. To +# force it to synchronize only one account at a time, set it to 1. +# +# NOTE: if you are using autorefresh and have more than one account, you must +# set this number to be >= to the number of accounts you have; since any given +# sync run never "finishes" due to a timer, you will never sync your additional +# accounts if this is 1. +# #maxsyncaccounts = 1 -# You can specify one or more user interface modules for OfflineIMAP -# to use. OfflineIMAP will try the first in the list, and if it -# fails, the second, and so forth. + +# This option stands in the [general] section. +# +# You can specify one or more user interface. OfflineIMAP will try the first in +# the list, and if it fails, the second, and so forth. # # The pre-defined options are: # Blinkenlights -- A fancy (terminal) interface @@ -75,22 +85,28 @@ accounts = Test # parsing. # # You can override this with a command-line option -u. - +# #ui = basic + +# This option stands in the [general] section. +# # If you try to synchronize messages to a folder which the IMAP server # considers read-only, OfflineIMAP will generate a warning. If you want # to suppress these warnings, set ignore-readonly to yes. Read-only # IMAP folders allow reading but not modification, so if you try to # change messages in the local copy of such a folder, the IMAP server # will prevent OfflineIMAP from propagating those changes to the IMAP -# server. Note that ignore-readonly is unrelated to the "readonly" +# server. Note that ignore-readonly is UNRELATED to the "readonly" # setting which prevents a repository from being modified at all. - +# #ignore-readonly = no + ########## Advanced settings +# This option stands in the [general] section. +# # You can give a Python source filename here and all config file # python snippets will be evaluated in the context of that file. # This allows you to e.g. define helper functions in the Python @@ -99,31 +115,36 @@ accounts = Test # # Tilde and environment variable expansions will be performed. # -# pythonfile = ~/.offlineimap.py -# +#pythonfile = ~/.offlineimap.py -# By default, OfflineIMAP will not exit due to a network error until -# the operating system returns an error code. Operating systems can sometimes -# take forever to notice this. Here you can activate a timeout on the -# socket. This timeout applies to individual socket reads and writes, -# not to an overall sync operation. You could perfectly well have a 30s -# timeout here and your sync still take minutes. + +# This option is in the [general] section. +# +# By default, OfflineIMAP will not exit due to a network error until the +# operating system returns an error code. Operating systems can sometimes take +# forever to notice this. Here you can activate a timeout on the socket. This +# timeout applies to individual socket reads and writes, not to an overall sync +# operation. You could perfectly well have a 30s timeout here and your sync +# still take minutes. # # Values in the 30-120 second range are reasonable. # # The default is to have no timeout beyond the OS. Times are given in seconds. # -# socktimeout = 60 +#socktimeout = 60 -# By default, OfflineIMAP will use fsync() to force data out to disk at -# opportune times to ensure consistency. This can, however, reduce -# performance. Users where /home is on SSD (Flash) may also wish to reduce -# write cycles. Therefore, you can disable OfflineIMAP's use of fsync(). -# Doing so will come at the expense of greater risk of message duplication -# in the event of a system crash or power loss. Default is fsync = true. -# Set fsync = false to disable fsync. + +# This option stands in the [general] section. # -# fsync = true +# By default, OfflineIMAP will use fsync() to force data out to disk at +# opportune times to ensure consistency. This can, however, reduce performance. +# Users where /home is on SSD (Flash) may also wish to reduce write cycles. +# Therefore, you can disable OfflineIMAP's use of fsync(). Doing so will come +# at the expense of greater risk of message duplication in the event of a system +# crash or power loss. Default is true. Set it to false to disable fsync. +# +#fsync = true + ################################################## # Mailbox name recorder @@ -131,7 +152,7 @@ accounts = Test [mbnames] -# offlineimap can record your mailbox names in a format you specify. +# OfflineIMAP can record your mailbox names in a format you specify. # You can define the header, each mailbox item, the separator, # and the footer. Here is an example for Mutt. # If enabled is yes, all six setting must be specified, even if they @@ -148,47 +169,46 @@ accounts = Test # # Tilde and environment variable expansions will be performed # for "filename" knob. +# +#enabled = no +#filename = ~/Mutt/muttrc.mailboxes +#header = "mailboxes " +#peritem = "+%(accountname)s/%(foldername)s" +#sep = " " +#footer = "\n" -enabled = no -filename = ~/Mutt/muttrc.mailboxes -header = "mailboxes " -peritem = "+%(accountname)s/%(foldername)s" -sep = " " -footer = "\n" -# You can also specify a folderfilter. It will apply to the -# *translated* folder name here, and it takes TWO arguments: -# accountname and foldername. In all other ways, it will -# behave identically to the folderfilter for accounts. Please see -# that section for more information and examples. +# This option stands in the [mbnames] section. # -# Note that this filter can be used only to further restrict mbnames -# to a subset of folders that pass the account's folderfilter. +# You can also specify a folderfilter. It will apply to the *translated* folder +# name here, and it takes TWO arguments: accountname and foldername. In all +# other ways, it will behave identically to the folderfilter for accounts. +# Please see the folderfilter option for more information and examples. # +# This filter can be used only to further restrict mbnames to a subset of +# folders that pass the account's folderfilter. # -# You can customize the order in which mailbox names are listed in the -# generated file by specifying a sort_keyfunc, which takes a single -# dict argument containing keys 'accountname' and 'foldername'. This -# function will be called once for each mailbox, and should return a -# suitable sort key that defines this mailbox' position in the custom -# ordering. +# You can customize the order in which mailbox names are listed in the generated +# file by specifying a sort_keyfunc, which takes a single dict argument +# containing keys 'accountname' and 'foldername'. This function will be called +# once for each mailbox, and should return a suitable sort key that defines this +# mailbox' position in the custom ordering. # -# This is useful with e.g. Mutt-sidebar, which uses the mailbox order -# from the generated file when listing mailboxes in the sidebar. +# This is useful with e.g. Mutt-sidebar, which uses the mailbox order from the +# generated file when listing mailboxes in the sidebar. # -# Default setting is -# sort_keyfunc = lambda d: (d['accountname'], d['foldername']) +# Default setting is: +#sort_keyfunc = lambda d: (d['accountname'], d['foldername']) ################################################## # Accounts ################################################## -# This is an account definition clause. You'll have one of these -# for each account listed in general/accounts above. +# This is an account definition clause. You'll have one of these for each +# account listed in the "accounts" option in [general] section (above). [Account Test] -########## Basic settings # These settings specify the two folders that you will be syncing. # You'll need to have a "Repository ..." section for each one. @@ -196,44 +216,58 @@ footer = "\n" localrepository = LocalExample remoterepository = RemoteExample + ########## Advanced settings -# You can have offlineimap continue running indefinitely, automatically -# syncing your mail periodically. If you want that, specify how -# frequently to do that (in minutes) here. You can also specify -# fractional minutes (ie, 3.25). +# This option stands in the [Account Test] section. +# +# You can have OfflineIMAP continue running indefinitely, automatically syncing +# your mail periodically. If you want that, specify how frequently to do that +# (in minutes) here. Fractional minutes (ie, 3.25) is allowed. +# +#autorefresh = 5 -# autorefresh = 5 -# OfflineImap can replace a number of full updates by quick -# synchronizations. It only synchronizes a folder if 1) a Maildir -# folder has changed, or 2) if an IMAP folder has received new messages -# or had messages deleted, ie it does not update if only IMAP flags have -# changed. Full updates need to fetch ALL flags for all messages, so -# this makes quite a performance difference (especially if syncing -# between two IMAP servers). -# Specify 0 for never, -1 for always (works even in non-autorefresh -# mode), or a positive integer to do quick updates before doing -# another full synchronization (requires autorefresh). Updates are -# always performed after minutes, be they quick or full. +# This option stands in the [Account Test] section. +# +# OfflineImap can replace a number of full updates by quick synchronizations. +# It only synchronizes a folder if +# +# 1) a Maildir folder has changed +# +# or +# +# 2) if an IMAP folder has received new messages or had messages deleted, ie +# it does not update if only IMAP flags have changed. +# +# Full updates need to fetch ALL flags for all messages, so this makes quite a +# performance difference (especially if syncing between two IMAP servers). +# +# Specify 0 for never, -1 for always (works even in non-autorefresh mode) +# +# A positive integer to do quick updates before doing another full +# synchronization (requires autorefresh). Updates are always performed after +# minutes, be they quick or full. +# +#quick = 10 -# quick = 10 -# You can specify a pre and post sync hook to execute a external command. -# In this case a call to imapfilter to filter mail before the sync process -# starts and a custom shell script after the sync completes. -# The pre sync script has to complete before a sync to the account will -# start. +# This option stands in the [Account Test] section. +# +# You can specify a pre and post sync hook to execute a external command. In +# this case a call to imapfilter to filter mail before the sync process starts +# and a custom shell script after the sync completes. +# +# The pre sync script has to complete before a sync to the account will start. +# +#presynchook = imapfilter -c someotherconfig.lua +#postsynchook = notifysync.sh -# presynchook = imapfilter -# postsynchook = notifysync.sh - -# You can also specify parameters to the commands -# presynchook = imapfilter -c someotherconfig.lua +# This option stands in the [Account Test] section. +# # OfflineImap caches the state of the synchronisation to e.g. be able to -# determine if a mail has been deleted on one side or added on the -# other. +# determine if a mail has been added or deleted on either side. # # The default and historical backend is 'plain' which writes out the # state in plain text files. On Repositories with large numbers of @@ -247,66 +281,92 @@ remoterepository = RemoteExample # #status_backend = plain + +# This option stands in the [Account Test] section. +# # If you have a limited amount of bandwidth available you can exclude larger -# messages (e.g. those with large attachments etc). If you do this it -# will appear to offlineimap that these messages do not exist at all. They -# will not be copied, have flags changed etc. For this to work on an IMAP -# server the server must have server side search enabled. This works with Gmail -# and most imap servers (e.g. cyrus etc) +# messages (e.g. those with large attachments etc). If you do this it will +# appear to OfflineIMAP that these messages do not exist at all. They will not +# be copied, have flags changed etc. For this to work on an IMAP server the +# server must have server side search enabled. This works with Gmail and most +# imap servers (e.g. cyrus etc) +# # The maximum size should be specified in bytes - e.g. 2000000 for approx 2MB - -# maxsize = 2000000 +# +#maxsize = 2000000 +# This option stands in the [Account Test] section. +# # When you are starting to sync an already existing account you can tell -# offlineimap to sync messages from only the last x days. When you do -# this messages older than x days will be completely ignored. This can -# be useful for importing existing accounts when you do not want to -# download large amounts of archive email. +# OfflineIMAP to sync messages from only the last x days. When you do this, +# messages older than x days will be completely ignored. This can be useful for +# importing existing accounts when you do not want to download large amounts of +# archive email. # -# Messages older than maxage days will not be synced, their flags will -# not be changed, they will not be deleted etc. For offlineimap it will -# be like these messages do not exist. This will perform an IMAP search -# in the case of IMAP or Gmail and therefore requires that the server -# support server side searching. This will calculate the earliest day -# that would be included in the search and include all messages from -# that day until today. e.g. maxage = 3 to sync only the last 3 days -# mail +# Messages older than maxage days will not be synced, their flags will not be +# changed, they will not be deleted, etc. For OfflineIMAP it will be like these +# messages do not exist. This will perform an IMAP search in the case of IMAP +# or Gmail and therefore requires that the server support server side searching. +# This will calculate the earliest day that would be included in the search and +# include all messages from that day until today. The maxage option expects an +# integer (for the number of days). # -# maxage = +#maxage = 3 +# This option stands in the [Account Test] section. +# # Maildir file format uses colon (:) separator between uniq name and info. # Unfortunatelly colon is not allowed character in windows file name. If you -# enable maildir-windows-compatible option, offlineimap will be able to store +# enable maildir-windows-compatible option, OfflineIMAP will be able to store # messages on windows drive, but you will probably loose compatibility with -# other programs working with the maildir +# other programs working with the maildir. # #maildir-windows-compatible = no + +# This option stands in the [Account Test] section. +# # Specifies if we want to sync GMail labels with the local repository. # Effective only for GMail IMAP repositories. # +# Non-ASCII characters in labels are bad handled or won't work at all. +# #synclabels = no + +# This option stands in the [Account Test] section. +# # Name of the header to use for label storage. Format for the header # value differs for different headers, because there are some de-facto -# standards set by popular clients: +# "standards" set by popular clients: +# # - X-Label or Keywords keep values separated with spaces; for these # you, obviously, should not have label values that contain spaces; +# # - X-Keywords use comma (',') as the separator. +# # To be consistent with the usual To-like headers, for the rest of header # types we use comma as the separator. # +# Use ASCII characters only. +# #labelsheader = X-Keywords + +# This option stands in the [Account Test] section. +# # Set of labels to be ignored. Comma-separated list. GMail-specific # labels all start with backslash ('\'). # +# Use ASCII characters only. +# #ignorelabels = \Inbox, \Starred, \Sent, \Draft, \Spam, \Trash, \Important - +# This option stands in the [Account Test] section. +# # OfflineIMAP can strip off some headers when your messages are propagated # back to the IMAP server. This option carries the comma-separated list # of headers to trim off. Header name matching is case-sensitive. @@ -315,23 +375,30 @@ remoterepository = RemoteExample # for GMail-based accounts is automatically added to this list, you don't # need to specify it explicitely. # +# Use ASCII characters only. +# #filterheaders = X-Some-Weird-Header - [Repository LocalExample] # Each repository requires a "type" declaration. The types supported for # local repositories are Maildir, GmailMaildir and IMAP. - +# type = Maildir + +# This option stands in the [Repository LocalExample] section. +# # Specify local repository. Your IMAP folders will be synchronized # to maildirs created under this path. OfflineIMAP will create the # maildirs for you as needed. - +# localfolders = ~/Test + +# This option stands in the [Repository LocalExample] section. +# # You can specify the "folder separator character" used for your Maildir # folders. It is inserted in-between the components of the tree. If you # want your folders to be nested directories, set it to "/". 'sep' is @@ -339,6 +406,9 @@ localfolders = ~/Test # #sep = . + +# This option stands in the [Repository LocalExample] section. +# # Some users may not want the atime (last access time) of folders to be # modified by OfflineIMAP. If 'restoreatime' is set to yes, OfflineIMAP # will restore the atime of the "new" and "cur" folders in each maildir @@ -349,7 +419,6 @@ localfolders = ~/Test #restoreatime = no - [Repository GmailLocalExample] # This type of repository enables syncing of Gmail. All Maildir @@ -362,43 +431,64 @@ localfolders = ~/Test # time OfflineIMAP runs with synclabels enabled, it will have to check # the contents of all individual messages for labels and this may take # a while. - +# type = GmailMaildir - [Repository RemoteExample] -# And this is the remote repository. We only support IMAP or Gmail here. +# The remote repository. We only support IMAP or Gmail here. +# type = IMAP + +# These options stands in the [Repository RemoteExample] section. +# # The following can fetch the account credentials via a python expression that # is parsed from the pythonfile parameter. For example, a function called # "getcredentials" that parses a file "filename" and returns the account # details for "hostname". -# remotehosteval = getcredentials("filename", "hostname", "hostname") -# remoteporteval = getcredentials("filename", "hostname", "port") -# remoteusereval = getcredentials("filename", "hostname", "user") -# remotepasseval = getcredentials("filename", "hostname", "passwd") +# +#remotehosteval = getcredentials("filename", "hostname", "hostname") +#remoteporteval = getcredentials("filename", "hostname", "port") +#remoteusereval = getcredentials("filename", "hostname", "user") +#remotepasseval = getcredentials("filename", "hostname", "passwd") + +# This option stands in the [Repository RemoteExample] section. +# # Specify the remote hostname. +# remotehost = examplehost + +# This option stands in the [Repository RemoteExample] section. +# # Whether or not to use SSL. -ssl = yes +# +#ssl = yes -# SSL Client certificate (optional) + +# This option stands in the [Repository RemoteExample] section. +# +# SSL Client certificate (optional). # # Tilde and environment variable expansions will be performed. +# +#sslclientcert = /path/to/file.crt -# sslclientcert = /path/to/file.crt -# SSL Client key (optional) +# This option stands in the [Repository RemoteExample] section. +# +# SSL Client key (optional). # # Tilde and environment variable expansions will be performed. +# +#sslclientkey = /path/to/file.key -# sslclientkey = /path/to/file.key +# This option stands in the [Repository RemoteExample] section. +# # SSL CA Cert(s) to verify the server cert against (optional). # No SSL verification is done without this option. If it is # specified, the CA Cert(s) need to verify the Server cert AND @@ -406,15 +496,18 @@ ssl = yes # The certificate should be in PEM format. # # Tilde and environment variable expansions will be performed. +# +#sslcacertfile = /path/to/cacertfile.crt -# sslcacertfile = /path/to/cacertfile.crt -# If you connect via SSL/TLS (ssl=true) and you have no CA certificate -# specified, offlineimap will refuse to sync as it connects to a server +# This option stands in the [Repository RemoteExample] section. +# +# If you connect via SSL/TLS (ssl = yes) and you have no CA certificate +# specified, OfflineIMAP will refuse to sync as it connects to a server # with an unknown "fingerprint". If you are sure you connect to the # correct server, you can then configure the presented server # fingerprint here. OfflineImap will verify that the server fingerprint -# has not changed on each connect and refuse to connect otherwise. +# has not changed on each connection and refuse to connect otherwise. # You can also configure this in addition to CA certificate validation # above and it will check both ways. # @@ -422,26 +515,41 @@ ssl = yes # # Fingerprints must be in hexadecimal form without leading '0x': # 40 hex digits like bbfe29cf97acb204591edbafe0aa8c8f914287c9. - +# #cert_fingerprint = [, ] -# SSL version (optional) + +# This option stands in the [Repository RemoteExample] section. +# +# SSL version (optional). +# # It is best to leave this unset, in which case the correct version will be # automatically detected. In rare cases, it may be necessary to specify a # particular version from: tls1, ssl2, ssl3, ssl23 (SSLv2 or SSLv3) +# +#ssl_version = ssl23 -# ssl_version = ssl23 +# This option stands in the [Repository RemoteExample] section. +# # Specify the port. If not specified, use a default port. -# remoteport = 993 +# +#remoteport = 993 + +# This option stands in the [Repository RemoteExample] section. +# # Specify the remote user name. +# remoteuser = username + +# This option stands in the [Repository RemoteExample] section. +# # Specify the user to be authorized as. Sometimes we want to # authenticate with our login/password, but tell the server that we # really want to be treated as some other user; perhaps server will -# allow us to do that (or, may be, not). Some IMAP servers migrate +# allow us to do that (or maybe not). Some IMAP servers migrate # account names using this functionality: your credentials remain # intact, but remote identity changes. # @@ -449,20 +557,23 @@ remoteuser = username # mechanism, so consider using auth_mechanisms to prioritize PLAIN # or even make it the only mechanism to be tried. # -# remote_identity = authzuser +#remote_identity = authzuser -# Specify which authentication/authorization mechanisms we should try -# and the order in which OfflineIMAP will try them. NOTE: any given -# mechanism will be tried only if it is supported by the remote IMAP -# server. + +# This option stands in the [Repository RemoteExample] section. # -# Due to the technical limitations, if you're specifying GSSAPI -# as the mechanism to try, it will be tried first, no matter where -# it was specified in the list. +# Specify which authentication/authorization mechanisms we should try and the +# order in which OfflineIMAP will try them. # -# Default value is -# auth_mechanisms = GSSAPI, CRAM-MD5, PLAIN, LOGIN -# ranged is from strongest to more weak ones. +# NOTE: any given mechanism will be tried ONLY if it is supported by the remote +# IMAP server. +# +# Default value is ranged is from strongest to more weak ones. Due to technical +# limitations, if GSSAPI is set, it will be tried first, no matter where it was +# specified in the list. +# +#auth_mechanisms = GSSAPI, CRAM-MD5, PLAIN, LOGIN + ########## Passwords @@ -507,9 +618,13 @@ remoteuser = username # This method can be used to design more elaborate setups, e.g. by # querying the gnome-keyring via its python bindings. + ########## Advanced settings -# Tunnels. There are two types: + +# These options stands in the [Repository RemoteExample] section. +# +# Tunnels. There are two types: # # - preauth: they teleport your connection to the remote system # and you don't need to authenticate yourself there; the sole @@ -521,57 +636,73 @@ remoteuser = username # IMAP server. # # Tunnels are currently working only with IMAP servers and their -# derivatives (currently, GMail). Additionally, for GMail accounts +# derivatives (GMail currently). Additionally, for GMail accounts # preauth tunnel settings are ignored: we don't believe that there # are ways to preauthenticate at Google mail system IMAP servers. # -# You must choose at most one tunnel type, be wise M'Lord. +# You must choose at most one tunnel type, be wise M'Lord! # -# preauthtunnel = ssh -q imaphost '/usr/bin/imapd ./Maildir' -# transporttunnel = openssl s_client -host myimap -port 993 -quiet +#preauthtunnel = ssh -q imaphost '/usr/bin/imapd ./Maildir' +#transporttunnel = openssl s_client -host myimap -port 993 -quiet -# Some IMAP servers need a "reference" which often refers to the "folder -# root". This is most commonly needed with UW IMAP, where you might -# need to specify the directory in which your mail is stored. The -# 'reference' value will be prefixed to all folder paths refering to -# that repository. E.g. accessing folder 'INBOX' with reference = Mail -# will try to access Mail/INBOX. Note that the nametrans and -# folderfilter functions will still apply the full path including the -# reference prefix. Most users will not need this. + +# This option stands in the [Repository RemoteExample] section. # -# reference = Mail +# Some IMAP servers need a "reference" which often refers to the "folder root". +# +# This is most commonly needed with UW IMAP, where you might need to specify the +# directory in which your mail is stored. The 'reference' value will be prefixed +# to all folder paths refering to that repository. E.g. accessing folder 'INBOX' +# with "reference = Mail" will try to access Mail/INBOX. +# +# The nametrans and folderfilter functions will apply to the full path, +# including the reference prefix. Most users will not need this. +# +#reference = Mail + +# This option stands in the [Repository RemoteExample] section. +# # In between synchronisations, OfflineIMAP can monitor mailboxes for new -# messages using the IDLE command. If you want to enable this, specify here -# the folders you wish to monitor. Note that the IMAP protocol requires a -# separate connection for each folder monitored in this way, so setting -# this option will force settings for: -# maxconnections - to be at least the number of folders you give -# holdconnectionopen - to be true -# keepalive - to be 29 minutes unless you specify otherwise +# messages using the IDLE command. If you want to enable this, specify here the +# folders you wish to monitor. IMAP protocol requires a separate connection for +# each folder monitored in this way, so setting this option will force settings +# for: +# +# - maxconnections: to be at least the number of folders you give +# - holdconnectionopen: to be true +# - keepalive: to be 29 minutes unless you specify otherwise # # This feature isn't complete and may well have problems. See the "Known Issues" # entry in the manual for more details. # # This option should return a Python list. For example # -# idlefolders = ['INBOX', 'INBOX.Alerts'] -# +#idlefolders = ['INBOX', 'INBOX.Alerts'] + +# This option stands in the [Repository RemoteExample] section. +# # OfflineIMAP can use a compressed connection to the IMAP server. # This can result in faster downloads for some cases. # #usecompression = yes + +# This option stands in the [Repository RemoteExample] section. +# # OfflineIMAP can use multiple connections to the server in order # to perform multiple synchronization actions simultaneously. # This may place a higher burden on the server. In most cases, # setting this value to 2 or 3 will speed up the sync, but in some # cases, it may slow things down. The safe answer is 1. You should # probably never set it to a value more than 5. - +# #maxconnections = 2 + +# This option stands in the [Repository RemoteExample] section. +# # OfflineIMAP normally closes IMAP server connections between refreshes if # the global option autorefresh is specified. If you wish it to keep the # connection open, set this to true. If not specified, the default is @@ -581,151 +712,185 @@ remoteuser = username # #holdconnectionopen = no -# If you want to have "keepalives" sent while waiting between syncs, -# specify the amount of time IN SECONDS between keepalives here. Note that -# sometimes more than this amount of time might pass, so don't make it -# tight. This setting has no effect if autorefresh and holdconnectionopen -# are not both set. -# -# keepalive = 60 -# Normally, OfflineIMAP will expunge deleted messages from the server. -# You can disable that if you wish. This means that OfflineIMAP will -# mark them deleted on the server, but not actually delete them. -# You must use some other IMAP client to delete them if you use this -# setting; otherwise, the messages will just pile up there forever. -# Therefore, this setting is definitely NOT recommended. +# This option stands in the [Repository RemoteExample] section. +# +# If you want to have "keepalives" sent while waiting between syncs, specify the +# amount of time IN SECONDS between keepalives here. Note that sometimes more +# than this amount of time might pass, so don't make it tight. This setting has +# no effect if autorefresh and holdconnectionopen are not both set. +# +#keepalive = 60 + + +# This option stands in the [Repository RemoteExample] section. +# +# Normally, OfflineIMAP will expunge deleted messages from the server. You can +# disable that if you wish. This means that OfflineIMAP will mark them deleted +# on the server, but not actually delete them. You must use some other IMAP +# client to delete them if you use this setting; otherwise, the messages will +# just pile up there forever. Therefore, this setting is definitely NOT +# recommended for a long term. # #expunge = no + +# This option stands in the [Repository RemoteExample] section. +# # Specify whether to process all mail folders on the server, or only # those listed as "subscribed". # #subscribedonly = no -# You can specify a folder translator. This must be a eval-able -# Python expression that takes a foldername arg and returns the new -# value. I suggest a lambda. This example below will remove "INBOX." from -# the leading edge of folders (great for Courier IMAP users) + +# This option stands in the [Repository RemoteExample] section. # -# See the user documentation for details and use cases. They are also -# online at: +# You can specify a folder translator. This must be a eval-able. +# +# Python expression that takes a foldername arg and returns the new value. A +# lambda function is suggested. +# +# WARNING: you MUST construct it so that it NEVER returns the same value for two +# folders, UNLESS the second values are filtered out by folderfilter below. +# Failure to follow this rule will result in undefined behavior. +# +# See the user documentation for details and use cases. They are also online at: # http://docs.offlineimap.org/en/latest/nametrans.html # -# WARNING: you MUST construct this such that it NEVER returns -# the same value for two folders, UNLESS the second values are -# filtered out by folderfilter below. Failure to follow this rule -# will result in undefined behavior +# This example below will remove "INBOX." from the leading edge of folders +# (great for Courier IMAP users). +# +#nametrans = lambda foldername: re.sub('^INBOX\.', '', foldername) # -# nametrans = lambda foldername: re.sub('^INBOX\.', '', foldername) - # Using Courier remotely and want to duplicate its mailbox naming # locally? Try this: # -# nametrans = lambda foldername: re.sub('^INBOX\.*', '.', foldername) +#nametrans = lambda foldername: re.sub('^INBOX\.*', '.', foldername) -# Determines if folderfilter will be invoked on each run -# (dynamic folder filtering) or filtering status will be determined -# at startup (default behaviour). + +# This option stands in the [Repository RemoteExample] section. # -# dynamic_folderfilter = False +# Determines if folderfilter will be invoked on each run (dynamic folder +# filtering) or filtering status will be determined at startup (default +# behaviour). +# +#dynamic_folderfilter = False -# You can specify which folders to sync using the folderfilter -# setting. You can provide any python function (e.g. a lambda function) -# which will be invoked for each foldername. If the filter function -# returns True, the folder will be synced, if it returns False, it. The -# folderfilter operates on the *UNTRANSLATED* name (before any nametrans + +# This option stands in the [Repository RemoteExample] section. +# +# You can specify which folders to sync using the folderfilter setting. You can +# provide any python function (e.g. a lambda function) which will be invoked for +# each foldername. If the filter function returns True, the folder will be +# synced, if it returns False, it. +# +# The folderfilter operates on the *UNTRANSLATED* name (before any nametrans # translation takes place). # # Example 1: synchronizing only INBOX and Sent. # -# folderfilter = lambda foldername: foldername in ['INBOX', 'Sent'] +#folderfilter = lambda foldername: foldername in ['INBOX', 'Sent'] # # Example 2: synchronizing everything except Trash. # -# folderfilter = lambda foldername: foldername not in ['Trash'] +#folderfilter = lambda foldername: foldername not in ['Trash'] # # Example 3: Using a regular expression to exclude Trash and all folders # containing the characters "Del". # -# folderfilter = lambda foldername: not re.search('(^Trash$|Del)', foldername) +#folderfilter = lambda foldername: not re.search('(^Trash$|Del)', foldername) # -# If folderfilter is not specified, ALL remote folders will be -# synchronized. +# If folderfilter is not specified, ALL remote folders will be synchronized. # -# You can span multiple lines by indenting the others. (Use backslashes -# at the end when required by Python syntax) For instance: +# You can span multiple lines by indenting the others. (Use backslashes at the +# end when required by Python syntax) For instance: # -# folderfilter = lambda foldername: foldername in -# ['INBOX', 'Sent Mail', 'Deleted Items', -# 'Received'] +#folderfilter = lambda foldername: foldername in [ +# 'INBOX', 'Sent Mail', +# 'Deleted Items', 'Received'] - -# You can specify folderincludes to include additional folders. It -# should return a Python list. This might be used to include a folder -# that was excluded by your folderfilter rule, to include a folder that -# your server does not specify with its LIST option, or to include a -# folder that is outside your basic reference. The 'reference' value -# will not be prefixed to this folder name, even if you have specified -# one. For example: -# folderincludes = ['debian.user', 'debian.personal'] +# This option stands in the [Repository RemoteExample] section. +# +# You can specify folderincludes to include additional folders. It should +# return a Python list. This might be used to include a folder that was +# excluded by your folderfilter rule, to include a folder that your server does +# not specify with its LIST option, or to include a folder that is outside your +# basic reference. +# +# The 'reference' value will not be prefixed to this folder name, even if you +# have specified one. For example: +# +#folderincludes = ['debian.user', 'debian.personal'] +# This option stands in the [Repository RemoteExample] section. +# # If you do not want to have any folders created on this repository, # set the createfolders variable to False, the default is True. Using # this feature you can e.g. disable the propagation of new folders to # the new repository. +# #createfolders = True -# You can specify 'foldersort' to determine how folders are sorted. -# This affects order of synchronization and mbnames. The expression -# should return -1, 0, or 1, as the default Python cmp() does. The two -# arguments, x and y, are strings representing the names of the folders -# to be sorted. The sorting is applied *AFTER* nametrans, if any. The -# default is to sort IMAP folders alphabetically -# (case-insensitive). Usually, you should never have to modify this. To -# eg. reverse the sort: +# This option stands in the [Repository RemoteExample] section. # -# foldersort = lambda x, y: -cmp(x, y) +# 'foldersort' determines how folders are sorted. +# +# This affects order of synchronization and mbnames. The expression should +# return -1, 0, or 1, as the default Python cmp() does. The two arguments, x +# and y, are strings representing the names of the folders to be sorted. The +# sorting is applied *AFTER* nametrans, if any. The default is to sort IMAP +# folders alphabetically (case-insensitive). Usually, you should never have to +# modify this. To eg. reverse the sort: +# +#foldersort = lambda x, y: -cmp(x, y) + +# This option stands in the [Repository RemoteExample] section. +# # Enable 1-way synchronization. When setting 'readonly' to True, this -# repository will not be modified during synchronization. Use to +# repository will not be modified during synchronization. Usefull to # e.g. backup an IMAP server. The readonly setting can be applied to any # type of Repository (Maildir, Imap, etc). # #readonly = False + [Repository GmailExample] -# A repository using Gmail's IMAP interface. Any configuration -# parameter of `IMAP` type repositories can be used here. Only -# `remoteuser` (or `remoteusereval` ) is mandatory. Default values -# for other parameters are OK, and you should not need fiddle with -# those. +# A repository using Gmail's IMAP interface. +# +# Any configuration parameter of "IMAP" type repositories can be used here. +# Only "remoteuser" (or "remoteusereval" ) is mandatory. Default values for +# other parameters are OK, and you should not need fiddle with those. +# +# The Gmail repository will use hard-coded values for "remotehost", +# "remoteport", "tunnel" and "ssl". Any attempt to set those parameters will be +# silently ignored. For details, see +# +# http://mail.google.com/support/bin/answer.py?answer=78799&topic=12814 +# +# To enable GMail labels synchronisation, set the option "synclabels" +# in the corresponding "Account" section. # -# The Gmail repository will use hard-coded values for `remotehost`, -# `remoteport`, `tunnel` and `ssl`. (See -# http://mail.google.com/support/bin/answer.py?answer=78799&topic=12814) -# Any attempt to set those parameters will be silently ignored. - type = Gmail + +# This option stands in the [Repository GmailExample] section. +# # Specify the Gmail user name. This is the only mandatory parameter. +# remoteuser = username@gmail.com -# The trash folder name may be different from [Gmail]/Trash -# for example on German Gmail, this setting should be -# -# trashfolder = [Gmail]/Papierkorb -# -# You should look for the localized names of the spam folder too: -# "spamfolder" tunable will help you to override the standard name. -# Enable 1-way synchronization. See above for explanation. +# This option stands in the [Repository GmailExample] section. # -#readonly = False +# The trash folder name may be different from [Gmail]/Trash due to localization. +# You should look for the localized names of the spam folder too: "spamfolder" +# tunable will help you to override the standard name. # -# To enable GMail labels synchronisation, set the option synclabels -# in the corresponding "Account" section. +# For example on German Gmail, this setting should be: +# +#trashfolder = [Gmail]/Papierkorb