KOPANO-GATEWAY.CFG(5)

📦 version 8.7.0, in ubuntu jammy

💖 KOPANO-GATEWAY.CFG(5) 💖

Kopano Core user reference · KOPANO-GATEWAY.CFG(5)

okay bestie, pull up a chair, we're reading the manual page for kopano-gateway.cfg together and honestly? it's giving essential. let's go 🫶

✨ NAME ✨

kopano-gateway.cfg — the Kopano gateway configuration file. that's it, that's the name, she's iconic 💅

🌸 SYNOPSIS 🌸

gateway.cfg

🦋 DESCRIPTION 🦋

so gateway.cfg is the config file for the Kopano Gateway. inside it you'll find the instructions the software needs to set up its logging system, and to turn the POP3, POP3S, IMAP or IMAPS part of the service on or off. like, it's the gateway's whole personality file fr fr.

🎀 FILE FORMAT 🎀

ngl this part is lowkey the vibe check for the whole file. it's one big section, but you can group the parameters by functionality if that's your thing — no cap, do whatever helps you keep it cute.

parameters get written like this:

name = value

the file is line-based. every newline-terminated line is one of four things:

  • a comment
  • nothing (yes, blank lines are valid, she's resting 💤)
  • a parameter
  • a directive

a line that starts with # counts as a comment, and Kopano will just ignore it. parameter names are case sensitive, so Foo and foo are NOT the same girlie, do not play with her like that 😭

lines that start with ! are directives ✨

directives look like this:

!directive [argument(s)]

📜 the directives that exist 📜

🧚 include

include and process the argument. that's the whole job, and she does it flawlessly 👑

example:

!include common.cfg

that's part one bestie, we're not done yet — the rest is coming, don't go anywhere 💜

✨ EXPLANATION OF EACH PARAMETER ✨

Okay bestie, this is the big one — every single knob you can turn, in order, with defaults. Buckle up 💖

  • server_hostname — the hostname the server prints to a client in the logon greeting. Leave it empty and DNS gets to figure out the hostname for you. Default: (empty)
  • server_hostname_greeting — do we show the hostname in the logon greeting to clients, or not? This one is reloadable with the HUP signal, so you can flip it live without a restart. Slay. Default: no
  • imap_listen — a space-separated list of address:port specifiers telling the server where to listen for unencrypted and STARTTLS-ed IMAP connections. IPv6 addresses need to be wrapped in brackets (like [2001:db8::1]:236), and the asterisk is the multi-protocol address wildcard. Default: *:143
  • imaps_listen — a space-separated list of address:port specifiers for implicit-SSL IMAP connections, same idea as imap_listen. Normally you'd park this on port 993. Default: (empty)
  • pop3_listen — a space-separated list of address:port specifiers for where the server should listen for unencrypted and STARTTLS-ed POP3 connections. IPv6 addresses go in brackets (as in [2001:db8::1]:236), and the asterisk is the multi-protocol address wildcard. Default: *:110
  • pop3s_listen — a space-separated list of address:port specifiers for implicit-SSL POP3 connections, similar to pop3_listen. Normally on port 995. Default: (empty)
  • server_socket — the http address of the storage server. Default: http://localhost:236/
Lowkey important: it's not advised to specify the UNIX socket here — use the http address instead. In the default configuration the gateway will then be trusted by the storage server (as set in its local_admin_users configuration setting). And heads up: unless it's run as an untrusted user via run_as_user, the gateway always authenticates users even if they provide no or wrong credentials! 🫢
  • run_as_user — after starting correctly, the gateway process becomes this user, dropping root privileges. Note that the log file needs to be writeable by this user, and the directory too, so new logfiles can be created after logrotation. You can also achieve that by setting the correct group and permissions. Default value is empty, meaning the user is not changed after starting.
  • run_as_group — after starting correctly, the gateway process becomes this group, dropping root privileges. Default value is empty, meaning the group is not changed after starting.
  • pid_file — write the process ID number into this file. The init.d script uses it to correctly stop/restart the service. Default: /var/run/kopano/gateway.pid
  • running_path — change directory to this path when running in daemonize mode. When you use the -F switch to run in the foreground, the directory will not be changed. Default: /
  • coredump_enabled — when a crash occurs or an assertion fails, the system can generate a coredump file for use with a crash report. For the details, go read the kopano-coredump(5) manpage. Default: systemdefault
  • process_model — you can switch the process model between fork and thread. The forked model uses somewhat more resources, but if a crash is triggered, it only affects one user. In the threaded model, a crash means all users are affected and won't be able to use the service. Choose wisely 💅 Default: thread
  • bypass_auth — this parameter can be used to skip password verification when connecting over the UNIX socket. Connecting through the UNIX socket can give a big performance gain compared to the TCP socket of kopano-server. Since kopano-gateway is usually running as the user kopano (which is a local_admin_user in kopano-server), this would normally mean kopano-gateway only verifies usernames and no password (because it's running as an administrator). Setting it to no (the default value) forces verification of passwords, even when running as an administrator. For migrations you'll want to set yes. Default: no
  • imap_only_mailfolders — make the IMAP and IMAPS service show only the mailfolders. That's the default behaviour. When this option is set to 'no', you'll also be able to select your calendar and contacts and such — but those views will not contain all information, since these items can't be converted to an rfc-822 mail item. Default: yes
  • imap_public_folders — make the IMAP and IMAPS service also show the public store with subfolders. That's the default behaviour. When this option is set to 'no', IMAP clients will only see the user's folder. Default: yes
  • imap_capability_idle — let IMAP clients issue the IDLE command. When an IMAP client is idle, it may receive notifications from the server about changes to the selected folder. This may increase load on the server when many users are using the IMAP service. Default: yes
  • imap_max_messagesize — limit the maximum message size (in bytes) that an IMAP client can create. The maximum of this value is 4GB although this is not recommended. If the value is too high it will cause a segmentation fault. This value may contain a k, m or g multiplier. Default: 128M
  • imap_expunge_on_delete — normally when you delete an e-mail in an IMAP client, it's only marked as deleted and not removed from the folder. The client should send the EXPUNGE command to actually remove the item from the folder (where Kopano will place it in the soft-delete system). When this option is set to yes, kopano-gateway will issue the expunge command itself, directly after a 'mark as delete' command was received. Default: no
  • imap_max_fail_commands — maximum number of failed commands before the client's connection is forcibly closed. This makes sure a client that repeatedly fails on a specific connection (like opening folders over and over again that don't exist) doesn't affect the overall performance of the gateway process. With the default value set to 10, normal operation will work for most production environments. With IMAP migrations, this value should be set higher, because many traditional IMAP migration tools try to fetch folders which didn't necessarily exist before — so in a migration scenario, set this higher, at minimum to the number of folders to be migrated from the largest mailbox. Default: 10
  • imap_ignore_command_idle — some MUAs send commands via idle, causing the connection to reach imap_max_fail_commands and leaving the client in a broken state. Those clients include Apple Mail. If you experience problems, or you use Apple Mail, set this option to yes. Default: no
  • disable_plaintext_auth — disable all plaintext POP3 and IMAP authentications unless SSL/TLS is used (except for connections originating from localhost, to allow saslauthd with rimap). Obviously, this requires at least ssl_private_key_file and ssl_certificate_file to take effect. Default: no
  • ssl_private_key_file — the gateway uses this file as the private key for SSL TLS. The file can be created with:
openssl genrsa -out /etc/kopano/gateway/privkey.pem 2048

Default: /etc/kopano/gateway/privkey.pem

  • ssl_certificate_file — the gateway uses this file as the certificate for SSL TLS. A self-signed certificate can be created with:
openssl req -new -x509 -key /etc/kopano/gateway/privkey.pem -out /etc/kopano/gateway/cert.pem -days 1095

Default: /etc/kopano/gateway/cert.pem

  • ssl_verify_client — enable client certificate verification with the value yes. All other values disable the verification. Default: no
  • ssl_verify_file — the file to verify the clients' certificates with. Default: value not set.
  • ssl_verify_path — the path with the files to verify the clients' certificates with. Default: value not set.
  • ssl_protocols — a space-separated list of disabled or enabled protocol names. The supported protocol names depend on the system's SSL library; depending on version, one or more of the following are available: TLSv1.3, TLSv1.2, TLSv1.1, SSLv3, SSLv2. To disable a protocol, prefix the name with an exclamation mark. Default: !SSLv2 !SSLv3 !TLSv1 !TLSv1.1
  • ssl_ciphers — a colon-separated list of disabled or enabled SSL/TLS ciphers. The supported cipher names depend on the system's SSL library and are generally plentiful. To disable a cipher or cipher group, prefix the name with a minus or exclamation mark. The details and meaning of the syntax are described in ciphers(1). Default: DEFAULT:!LOW:!SSLv2:!SSLv3:!TLSv1.0:!TLSv1.1:!EXPORT:!DH:!PSK:!kRSA:!aDSS:!aNULL:+AES
  • ssl_prefer_server_ciphers — in SSLv3 and newer, the server side gets to make the ultimate cipher pick out of the set that both ends support. In doing so, it can either use the client preference list, or, if this directive is set to "yes", its own list (as determined by ssl_cipher). Default: yes
  • ssl_curves — ECDH curves to use for SSL. Default: X25519:P-521:P-384:P-256
  • log_method — the method that should be used for logging. Valid values are:
    • syslog — use the syslog service. Messages will be sent using the "mail" facility tag. See also journald.conf(5) or syslog.conf(5).
    • file — log to a file. The filename will be specified in log_file.
    • auto — autoselect mode: if log_file is set, that will be used. Else, syslog will be used if it looks like it is available. Else, stderr. Default: auto
  • log_file — when logging to a file, specify the filename in this parameter. Use - (minus sign) for stderr output. Default: -
  • log_level — the level of output for logging, in the range from 0 to 6. "0" means no logging, "1" for critical messages only, "2" for error or worse, "3" for warning or worse, "4" for notice or worse, "5" for info or worse, "6" debug. Default: 3
  • log_timestamp — specify whether to prefix each log line with a timestamp in 'file' logging mode. Default: 1
  • log_buffer_size — buffer logging in what sized blocks. The special value 0 selects line buffering. Default: 0

🔄 RELOADING 🔄

These options are reloadable by sending the kopano-gateway process a HUP signal:

  • log_level

That's it. That's the list. One icon. ✨

📁 FILES 📁

  • /etc/kopano/gateway.cfg — the Kopano gateway configuration file.

👑 AUTHOR 👑

Written by Kopano.

🌈 SEE ALSO 🌈

Kopano 8 🌸 November 2016 🦋 KOPANO-GATEWAY.CFG(5)

And that's a wrap bestie — go forth and configure, you absolute main character 💅🫶

📦 where this page comes from