KOPANO-SERVER(8)

📦 version 8.7.0, in ubuntu jammy

💖 KOPANO-SERVER 💖

okay bestie, gather round, because this is the manual page for kopano-server from the Kopano Core user reference, and it's genuinely iconic. no cap.

✨ NAME ✨

kopano-server — start the Kopano storage server. that's it, that's the whole vibe. she serves, she stores, she slays. 👑

🌸 SYNOPSIS 🌸

kopano-server [OPTION]

🦋 DESCRIPTION 🦋

So kopano-server is the Zafara storage server. She talks to a database server and then hands out services to Kopano clients like it's candy at a party. 🍓

The user base can come from an external source (hello, LDAP 👋) or you can set it up with its own separate list of users. either way, she's flexible, she's booked, she's busy.

Once she's up? She just keeps listening for connections on the configured TCP port and/or Unix socket. forever. like a loyal bestie. 🫶

💅 OPTIONS 💅

The storage server program takes the following configuration options, and yes we're going through every single one because we don't skip:

  • --config, -c file — tell her where the config file lives. default is /etc/kopano/server.cfg.
  • --dump-config — prints out the values of the server.cfg configuration parameters plus all the implied defaults. a little show-and-tell moment. ✨
  • --foreground, -F — run in the foreground. normally she'd daemonize and go live in the background like a mysterious girl, but this keeps her right there with you.
  • --restart-searches, -R — rebuild all search folders. this may take some time and you only need it when your search folders have become out-of-sync with the actual data in the database. the sync starts synchronously at the start of the server, so you literally have to wait for all searches to complete before you can connect to the server. patience, babe. 😭
  • --ignore-database-version-conflict — ignore version information from the database. normally Kopano will not start the server if the database has a newer version than the kopano-server binary, which is how she makes sure you can't downgrade your server binary while keeping the same database. if you know what you're doing, you can use this to bypass the start-up version check of the database. ⚠️
  • --ignore-attachment-storage-conflict — override the attachment storage option from the configuration file. if you change where attachments are stored after you've already started kopano-server once, that location will conflict, and attachments will not be found when they're stored in a different location. messy. 💀
  • --override-multiserver-lock — when you upgrade/downgrade from/to multiserver setups, the server will not start because of database differences. if you know what you're doing and want to circumvent this and start the server anyway, this is your girl.
  • --force-database-upgrade — forces kopano-server to do the normal upgrade as usual. she'll only daemonize once the upgrade is complete, and you can follow simple progress in the log output of the server.
  • -V — print the version and exit. short, sweet, iconic.

When invoked with no options at all, the server will search for a configuration file in /etc/kopano/server.cfg. If no configuration file is found, default values are used. See kopano-server.cfg(5) for all configuration options and their default values. 💖

🌈 USAGE 🌈

Starting the server with an alternative configuration:

kopano-server -c /path/to/server.cfg

You may also use the init.d scripts:

/etc/init.d/kopano-server [start| stop| restart]

(yes, that space after the pipe is exactly how she wrote it, we don't edit the queen 🎀)

🎀 FILES 🎀

  • /etc/kopano/server.cfg — the server configuration file.

Configuration options for user plugins are in their respective configuration file. The name of these files is set in the server.cfg file. See kopano-server.cfg(5) for information on the server.cfg settings.

🔍 DIAGNOSTICS 🔍

If you run into problems, check the log for any errors. If you made a mistake in the configuration of the log method, this will be reported on standard error. You can also restart the server with a higher log level. Also — and this is important, bestie — before starting the server, always make sure the database server is running at the right location and that no other server is listening on the configured TCP port.

For extended diagnostics, there are special extended log options available for enhanced debugging capabilities. The parameter log_level has special or-ed values which can be set to investigate different modules within the server process:

  • SQL: 0x00010000
  • User backend: 0x00020000
  • Server cache: 0x00040000
  • SOAP: 0x00100000
  • ICS: 0x00200000

For example, if you are using LDAP as the user plugin, you can set the log_level to 0x00020006 for extended LDAP logging (the last digit 6 enables extended verbose logging). To enable SQL and LDAP logging at the same time, set log_level to 0x00030006.

WARNING: The log options create huge amounts of log entries in production environments. This results in abnormal large logfiles which can fill up available disk space very fast. Only use this with extreme caution. 😭 she is not exaggerating, do not do this on prod for funsies.

🔒 SECURITY 🔒

The normal way for user clients to connect to the server is over TCP, either direct using the Kopano port, or over HTTP when Apache is setup as a proxy. Users can only login with their username and password. that's it, no shortcuts. 💅

The normal way for admin clients — like the spooler and admin tool — to connect to the server is through the Unix socket on Unix type servers. The admin clients are able to login when they are run as root or as the user the storage server process is running as. Most of the time this will be root only, since the storage server process runs as root by default. main character energy, but for root. 👑

As an exception for the dagent, a unix user can also connect to its own store without a password. Any other store cannot be accessed this way. one exception, that's all, don't get greedy.

Direct SSL connections are also possible. The server needs to be configured to accept SSL connections on a new port. Login via an SSL key is also possible. Please read the next section on how to setup SSL. 👇

🌸 SSL 🌸

To accept SSL connections directly by the server, the storage server will need to listen on a different port to separate the normal connections from the encrypted connections. This is set in the server_ssl_port setting in the configuration file.

Then, you must setup a signed SSL certificate. First, we'll create a Certificate Authority to be able to sign certificate requests. We provide a script which makes it easy to create certificates on any distribution. This script is located in /usr/share/kopano, called ssl-certificate.sh. Enter the following commands to create a certificate for the Kopano server:

mkdir -p /etc/kopano/ssl
cd /etc/kopano/ssl
sh /usr/share/kopano/ssl-certificate.sh server

Press enter twice to start the creation of a new CA, probably called demoCA. Enter a password when asked for. This is the password later used to sign certificate requests. Then enter your certificate information. Do not leave the Common Name field blank, otherwise the creation will fail. A good example for the Common Name field is your hostname. ✨

Now that we have a CA, we can create self-signed certificates. The script will automatically start the creation of this certificate. The CA certificate must be set in the server.cfg file in the server_ssl_ca_file setting. We need a signed certificate for the server to start with SSL support.

Enter a password for the request, and enter the certificate details. Some details need to be different from what you typed when creating the CA. Type at least a different name in the 'Organizational Unit Name' field. The challenge password at the end may be left empty.

The script will automatically continue with signing this certificate request. You will need to enter your CA certificate password again to sign this request. Then you must accept the new certificate into the CA.

After accepting, a new signed certificate is created, with the name server.pem. This file contains the private key, so keep this file safe. 🔐 for real, guard it with your life.

The script will ask if a public key should also be created. Since we're creating the certificate for the server, this is not needed. So enter 'n' and press enter.

The server.pem file should be set in the server.cfg file in the server_ssl_key_file option. See kopano-server.cfg(5) for information on the possible SSL settings. The password of this key needs to be set in the server_ssl_key_pass option. Do not forget this password in the server.cfg file, otherwise the kopano-server program will ask for this password when an SSL connection is accepted. 😭 please write it down somewhere.

To create a new certificate for a client service, run the script again. You can create one new certificate for all clients, or separate certificates for each client.

sh /usr/share/kopano/ssl-certificates.sh

When typing the certificate information, type at least a different 'Organizational Unit Name' field. When asked for a public key, type 'y' and enter to create the public key.

Install the new service.pem on the server that will be logging in. Install the service-public.pem file in the /etc/kopano/sslkeys directory:

mkdir /etc/kopano/sslkeys
mv service-public.pem /etc/kopano/sslkeys

The remote service, which has the service.pem private key, can now login with the certificate, because the known public key matches. slay. 💅✨

🦋 ADDRESSBOOK SORTING 🦋

With special chars (like umlauts) the sorting is working more the dictionary way according to DIN 5007-1, section 6.1.1.4.1. Depending on the behaviour wanted, the collation setting can be changed with the (not per default included) parameter default_sort_locale_id. When setting this parameter to de_DE@collation=phonebook for example, the sorting will be oriented to the DIN 5007-2, section 6.1.1.4.2 standard which is rather used in phonebooks and actually decomposes umlauts for sorting inline within non-umlaut based ASCII characters. so basically: umlaut girlies get sorted differently depending on your setting. iykyk. 📖

⭐ SIGNALS ⭐

The following signals can be sent to the storage server process:

  • HUP — when the HUP signal is received, some options from the configuration file are reloaded. The reloadable options are listed in the kopano-server.cfg(5) manual page. Also, when using log_method = file, the logfile will be closed and a new logfile will be opened. You can use this signal in your logrotate system. 🔄
  • TERM — to gracefully let the server exit, the normal TERM signal is used. Because of open sessions by clients it may take up to 60 seconds for the server to completely shutdown. give her a minute, she's finishing her sentence. 😭

👑 AUTHOR 👑

Written by Kopano.

🌈 SEE ALSO 🌈

okay that's the whole page bestie, you're officially certified 📜✨ this was Kopano 8, dated November 2016 — vintage, iconic, still serving. bye pookie, go start that server 💖🦋🎀

📦 where this page comes from