Kopano Cheat Sheet

Table of Contents

Kopano Community Edition End of Life Announcement

08 March 2023

Kopano community edition has unfortunately been discontinued:

https://forum.kopano.io/topic/4069/statement-regarding-the-closure-of-the-kopano-community-forum-and-the-end-of-the-community-edition

In order to protect yourself, it’s best to get your clients off Kopano as soon as possible. Having said that, if you have stable installations and you’re clients are stable, you can continue running the system, but good luck finding help with new problems. Although we generally find Kopano to be quite stable provided it’s the newest release.

Commands failing with “No module name XYZ”

At times on legacy servers Kopano might fail for example the following:

# /usr/sbin/kopano-backup -u [email protected]
Traceback (most recent call last):
  File "/usr/sbin/kopano-backup", line 4, in <module>
    import kopano_backup
ModuleNotFoundError: No module named 'kopano_backup'

When you inspect the directory /usr/sbin/ etc you will find the file is actually there. The reason why it’s not working it because your command line interpreter is using a different version of Python and you have to prefix the command with the right version. The directories and version can be determined by looking at `/usr/lib/pythonX.Y/site-packages/kopano_presence/`. For example, in this case we had to do:

python3.8 /usr/sbin/kopano-backup -u [email protected]

Kopano Backup and Restore

Kopano has a very good backup utility simply called kopano-backup . By just running the utility without any parameters it will create a full backup in the current directory, so be careful. Instead we recommend this:

cd /root
mkdir backups

Now at least you’ll have everything in one place. You will notice the second time you run kopano-backup it will be very quick. The reason is the utility does incremental backups by default.

Restoring

It appears the user must already exist on the destination server. If not, create the user first.

To restore a Kopano backup, do this:

kopano-backup --restore [email protected]

Using SSHFS to simplify remote Kopano backups

Since kopano-backup backs up right there where it’s run, it’s useful to use a utility like SSHFS to do remote backups. Broadly the steps are:

zypper install sshfs
mkdir /mnt/destination
sshfs -p 22 -o allow_other,default_permissions [email protected]:/root/kopano-restores /mnt/destination
cd /mnt/destination
date; python3.8 /usr/sbin/kopano-backup; date;

Now you can script that and ensure your incremental backups are stored offsite every day.

Z-Push Utilities

Time Zone

# cat z-push.conf.php | grep -i timezone
define('TIMEZONE', 'Africa/Johannesburg');

Get Z-Push Version

dpkg -l|grep z-push
... z-push-... 2.6.4+0-0 all Z-Push ...

You should have at least: autodiscover, backup-kopano, common, config-apache, config-apache-autodiscover, ipc-sharedmemory, kopano

Unfortunately seems to be the latest:
https://download.kopano.io/zhub/z-push%3A/final/Ubuntu_20.04/

Check Kopano Outlook Sync Status

At times Kopano might decide to do a full sync back to Outlook, making messages not appear. To check on the server the status of such a sync, do this:

/usr/share/z-push/z-push-admin.php -a list -u [email protected]

You might have loops. You can kill them so:

/usr/share/z-push/z-push-admin.php -a clearloop -u [email protected] -d device_uuid

Kopano fsck

kopano-fsck -u [email protected]

You will need more flags if you get lots of errors.

How to set Kopano Out of Office

Kopano OOO troubleshooting

The kopano-dagent is responsible for delivery out of office messages. Some things you want to try:

Check in /usr/sbin/ if a file exists, kopano-autorespond. If not, there’s your problem. Find the version for your system, and good luck with that.
Check if service kopano-dagent status show which log file it’s using. I had a system whereby no log file was specified so I couldn’t turn up logging. The solution was in systemd start to include the cfg file and turn on logging. There you’ll see detailed output and also get commands that can be run on the command line to see errors.

Integrate Shared Calendar in Outlook

What is it? See here.

Download the plugin from here:

https://download.kopano.io/community/olextension%3A/

List all Users

kopano-admin -l

List all user and pipe output of just email

kopano-admin -l | awk -F'\t' '{print $2}' > emails.txt

How to renew a Let’s Encrypt SSL certificate on a Kopano Server

There is no one way to do this, but you could try this sequence:

service httpd stop;/usr/bin/certbot renew;service httpd start;service kopano-gateway restart

The above procedure:
- Stops the web server
- Runs the certbot renew command
- Restarts the web server
- Restarts the kopano-gateway service

How to block an email from a user using the Kopano Web App

Users can block emails from other users using the Kopano web application. Here are the steps:

1. Log in to https://domain.com/webapp/ with your username and password.
2. Got to “Settings” top right
3. Go to “Rules” and press “New”

On the rule form, do the following:

Fill in the “rule name” (can be anything for example delete all email from [email protected]
Underneath “When the Message…” choose “…is received from” and go to “Select one…” and type the errant email address (by From: at the botton)
At “Do the following…” choose “Delete the message”.

Save the rule.

How to reset a Kopano password

Kopano passwords are reset using the command line.

SSH to the server
Use this command

kopano-admin -u [email protected] -p NewSecret
User information updated.

If you have an older version of Kopano, as in ancient, do the below instead. All that’s difference is kopano-admin is replaced with zarafa-admin

zarafa-admin -u [email protected] -p NewSecret
User information updated.

Reference

https://documentation.kopano.io/kopanocore_administrator_manual/user_management.html#updating-user-information-with-db-plugin

How to create a new Kopano user

kopano-admin -c [email protected] -p secret -e [email protected] -f "Full Name"

How to update an existing user’s full name

kopano-admin -u [email protected] -f "New Full Name"

Deletions

How to delete a Kopano user

kopano-admin -d [email protected]

Deletions & Orphans & Database Fragmentation

During trial and error, we deleted around 60 users across three companies from one Kopano server. The server had 190 GB space in use. After the deletions, the server still had 190 GB space in use. It appears deleting information from Kopano isn’t trivial due to either soft deletions and / or orphans.

When you delete items, they are held in soft deletion for 30 days.
When you delete mailboxes, they are also held (forever?). Reference manual.
When you delete big data, you end up with big database files that need compacting
Using special scripts to remove orphaned attachments

You’ll need access to a couple of commands to remedy this situation:

Forcing soft deletion

In theory the system will take care of soft deletions in 30 days. But if you want to force it, do this:

kopano-admin --purge-softdelete X

X is the number of days, which can even be 0.

Listing orphaned stores

When you delete a user, it doesn’t get deleted. Instead, it’s stored become an orphan. You can see a list of orphaned stores and their last access time with this command:

kopano-admin --list-orphans

To prep a list of all stores for mass deletion, use this command to pipe the output:

kopano-admin --list-orphans > orphans-list.txt

To remove stores

You can use the following command to remove orphaned (or any) store:

kopano-admin --remove-store UUID

If you want to further prep a large list of stores for final deletion, use the following Bash command to cut the first parameter:

cut -f1 orphans-list.txt > orphans-uuid

Here is a handy script that will allow you to now append the store UUID to a deletion command:

# cat mass-delete.sh
while read -r line; do
   echo "kopano-admin --remove-store $line"
done < "orphans-uuid"

Compacting the database tables

In our experience the following tables will need compacting after deleting a lot of data:

changes
properties
tproperties

Use this command:

optimize table changes

Script to remove orphaned attachments

There is also a Perl script to remove orphaned attachments, but we’ve never seen it work so perhaps we never had any. This script is here:

https://github.com/Kopano-dev/kopano-core/blob/master/installer/linux/db-remove-orphaned-attachments

The syntax is something like:

perl db-remove-orphaned-attachments.pl server.cfg

Reference for deletions

https://forum.kopano.io/topic/1988/deleting-attachments-from-deleted-accounts/4

IMAP issues on a Mac with incoming on port 993

On a working Mac you might suddenly find that port 993 stops working. The error will manifest itself in the log file like below:

Oct 31 10:45:33 host kopano-gateway[1354141]: ECChannel::HrEnableTLS(): SSL_accept failed: 5
Oct 31 10:45:33 host kopano-gateway[1354141]: Unable to negotiate SSL connection with a.b.c.d:7145

Our solution was to change to port 143 and remove SSL and in advanced settings, allow insecure connections.

Restoring the Deleted Items folder

You might get this problem after an email migration:

Missing folders
The following required folder is missing in the hierarchy:
Deleted items
Not all functionality of WebApp might be working properly because of this.

To fix do this:

kopano-recreate-systemfolders --user '[email protected]' --create "Deleted Items" --systemfolder wastebasket

You’ll see this:

User([email protected])
Create tmp folder Deleted Items
Promote new folder to be a system folder

Reference: https://forum.kopano.io/topic/3525/folder-deleted-items-has-disappeared/2

Usage Summary Script That Emails

The script below will summarize email and website usage and email recipients with the information.

#!/bin/bash

totald1=`df -h | grep root | awk '{ print "Used:",$3, "| Available:",$4, "| Used: "$5"%"}'`
totald2=`df -h | grep mysql | awk '{ print "Used:",$3, "| Available:",$4, "| Used: "$5"%"}'`
cloud=`du -h --max-depth=1 /srv/www/htdocs/example.com/data/ | cut -d "/" -f 1,7`
users=`kopano-admin -l | grep "@" | awk '{print $1}'`
mail=`for i in $users; do echo $i; kopano-admin --details $i | grep "Current store size" | awk {'print $4}'; done`
d=`date +%m-%d-%Y`
echo "
==================
Total:
==================
$totald1
$totald2

==================
Cloud:
==================
$cloud

==================
Mail:
==================
$mail


" | mailx -r ServerUsage -s "Server Usage for $d" -b [email protected] [email protected]

Add the script to your CRONTAB to have regular usage updates.

Errors

Kopano-Gateway

Failed to read line: No such file or directory

At times you might see an error repeating often in /var/log/mail.log This error is sequential and typically takes on this form:

Jun  2 15:57:20 k2 kopano-gateway[430054]: > * 3108 FETCH (UID 1036473 FLAGS (\Seen))
Jun  2 15:57:20 k2 kopano-gateway[430054]: > * 3109 FETCH (UID 1036477 FLAGS (\Seen))
Jun  2 15:57:20 k2 kopano-gateway[430054]: > * 3110 FETCH (UID 1036481 FLAGS (\Seen))
Jun  2 15:57:20 k2 kopano-gateway[430054]: > * 3111 FETCH (UID 1036485 FLAGS (\Seen))
Jun  2 15:57:20 k2 kopano-gateway[430054]: > * 3112 FETCH (UID 1036489 FLAGS (\Seen))
Jun  2 15:57:20 k2 kopano-gateway[430054]: > 9 OK UID FETCH completed
Jun  2 15:57:20 k2 kopano-gateway[430054]: Failed to read line: No such file or directory
Jun  2 15:57:20 k2 kopano-gateway[430054]: Client A.B.C.D:51452 thread exiting

As you can see the sequence is 3111, 3112, OK UID FETCH and then this error. You will only see this exact sequence if the gateway logging level is on debug. The sequence above is a typical pattern. Although no know cause is known, it would be worthwhile investigating the IMAP folder structure for any obvious errors. We looked on the forum but it’s wholly inconclusive, e.g. here:
https://forum.kopano.io/topic/3969/failed-to-read-line-no-such-file-or-directory/6

At this point (May 2023) we also don’t know how serious it is but since the client thread exits we imagine there is actually some kind of issue.