KOPANO-ADMIN(8)

📦 version 8.7.0, in ubuntu jammy

🌸 KOPANO-ADMIN(8) 🌸

Kopano Core user reference — and also, lowkey, the manual page that runs your whole user-management life. Bestie, this is kopano-admin. 💅

✨ NAME ✨

kopano-admin — manages Kopano users and stores. That's the vibe. It's the tool that makes users exist, makes them not exist, and keeps their storage situation cute. 🎀

🦋 SYNOPSIS 🦋

kopano-admin ACTION [OPTION...]

💖 DESCRIPTION 💖

Okay so here's the tea. ☕ This tool can be used to create the public store and to add, update and remove users from Kopano. And bestie, the storage server must be running for kopano-admin to work. No server, no slay. That's just how it is. 🫶

If no action is given, a listing of the possible parameters is printed. Helpful! When invalid actions or not enough options for an action are given, an error message is printed. Also helpful, just in a harsher tone. 😭

When using LDAP as the users source, create, modify and delete actions are done in the LDAP tree and not using the kopano-admin tool. So don't come for this program, it's not its job. Please see the EXTERNAL USERS() section for more information. 📖

👑 ACTIONS 👑

kopano-admin needs an action command with the appropriate options. Valid actions are:

  • -s — Create a public store. No other options are needed. Only one public store can be created, and successive calls will fail. So like, one and done, periodt. 💀
  • -c username — Create a new user. The -p, -f and -e options are required, and -a and -n parameters are optional. To set a password using a password prompt, use the -P option in stead of -p. (Password prompt version = the secure little icon. 🔐)
  • -d username — Delete a user. No other options are needed. The deleted store of the user will be marked as orphan store and can be restored with --hook-store. So it's not gone gone, it's just ✨emotionally unavailable✨. 🍓
  • -u username — Update user information. Valid parameters are: [-p|-P], -f, -e, -a, -n and -U to update user information. Use --qo, --qw, --qs or --qh to set quota levels. Use 0 with quota options to set as 'unlimited'.

--enable-feature and --disable-feature to enable or disable specific features for users.

This action is also required for all options to control the autoaccept of meeting requests. See the --mr-accept, --mr-decline-conflict and --mr-decline-recurring options.

  • -g groupname — Create a new group. Valid parameters are: -e.
  • --update-group groupname — Update group information. Valid parameters are: -e.
  • -G groupname — Delete a group. No other options are needed. bye bestie 👋
  • -b username — Add a user to a group. Use the -i to set the groupname.
  • -B username — Remove a user from a group. Use the -i to set the groupname.
  • -l, --list-users — List all users available in Kopano. When using an external user source, this action will implicitly synchronize all users in the external source, creating, updating and/or removing users and stores. Big main-character energy, it does a lot. 🔥
  • -L, --list-groups — List all groups available in Kopano. When using an external user source, this action will implicitly synchronize all groups in the external source, creating updating and/or removing groups and memberships.
  • --list-companies — List all tenans available in Kopano. When using an external user source, this action will implicitly synchronize all tenants in the external source, creating updating and/or removing companies.

This option is only available in multi-tenancy Kopano. 🌈

  • --details name — Show all the details of a user, showing the fullname, e-mailaddress, active state, administator state, group memberships and quota settings. Optionally use --type to indicate for what kind of object the details are being requested.
Note: This function does not synchronize with the external user plugin. Thus changes from e.g. LDAP will not be set during this function. 🙈
  • --type type — Additional argument for --details. The argument with this option indicates for what type of object the details are being requested. Allowed values are 'user', 'group' or 'company'. When this option is not used, it defaults to 'user'.
  • --create-company companyname — Create a new tenant space.

Use: --qo, --qw, --qs, --qh to set quota levels for the tenant.

Use: --udqo, --udqw, --udqs, --udqh to set the default quota levels for the users inside the tenant.

This option is only available in multi-tenancy Kopano. 🌈

  • --update-company companyname — Update an existing tenant space.

Use: --qo, --qw, --qs, --qh to set quota levels for the tenant.

Use: --udqo, --udqw, --udqs, --udqh to set the default quota levels for the users inside the tenant.

This option is only available in multi-tenancy Kopano. 🌈

  • --delete-company companyname — Delete company space.

This option is only available in multi-tenancy Kopano. 🌈

  • --set-system-admin companyname — Set system administrator for the tenant specified by -I.

Please be aware that this option does not provide the user with administrator privileges. The system administrator is considered the main contact person for a company, it will for example be used as default sender for quota warning emails. 📧

This option is only available in multi-tenancy Kopano. 🌈

  • --add-to-viewlist companyname — Add tenant 'companyname' to remote-view list of company specified by -I. After this command the 'companyname' is capable of viewing all members of the company specified by -I. 👀

This option is only available in multi-tenancy Kopano. 🌈

  • --del-from-viewlist companyname — Delete company 'companyname' from remote-view list of tenant specified by -I. After this command the 'companyname' is no longer capable of viewing all members of the tenant specified by -I. 🚫👀

This option is only available in multi-tenancy Kopano. 🌈

  • --list-view — List all tenants in the remote-view list of the tenant specified by -I. The tenants in this list are able to view all members of the specified tenant in their Address Book.

This option is only available in multi-tenancy Kopano. 🌈

  • --add-to-adminlist username — Add user 'username' to remote-admin list of tenant specified by -I. This is the administrator list for remote administrators, as such it only manages administrators from a different tenant. Users who should be administrator over their own tenant are managed by updating (-u) the user and specifying the -a argument.

Users can only be administrator over a different company when they have also been granted view privileges, can be granted by using the --add-to-viewlist.

This option is only available in multi-tenancy Kopano. 🌈

  • --del-from-adminlist username — Delete user 'username' from remote-admin list of company specified by -I. This is the administrator list for remote administrators, as such it only manages administrators from a different tenant. Users who should be administrator over their own tenant are managed by updating (-u) the user and specifying the -a argument.

This option is only available in multi-tenancy Kopano. 🌈

  • --list-admin — List all users in the remote-admin list of the tenant specified by -I. This is the administrator list for remote administrators, as such it only manages administrators from a different tenant. Users who should be administrator over their own tenant are managed by updating (-u) the user and specifying the -a argument.

Users can only be administrator over a different tenant when they have also been granted view privileges, can be granted by using the --add-to-viewlist.

This option is only available in multi-tenancy Kopano. 🌈

  • --add-userquota-recipient user — Add 'user' as recipient to userquota warning emails. You can optionally use -I to set the tenant space to apply the recipient action on.
  • --del-userquota-recipient user — Delete 'user' as recipient to userquota warning emails. You can optionally use -I to set the tenant space to apply the recipient action on.
  • --list-userquota-recipients — List all additional recipients for a userquota warning email. Use -I to request the recipient list for a particular tenant space.
  • --add-companyquota-recipient user — Add 'user' as recipient to tenant quota warning emails. You can optionally use -I to set the tenant space to apply the recipient action on.
  • --del-companyquota-recipient user — Delete 'user' as recipient to tenant quota warning emails. You can optionally use -I to set the tenant space to apply the recipient action on.
  • --list-companyquota-recipients — List all additional recipients for a tenant quota warning email. Use -I to request the recipient list for a particular tenant space.
  • --list-sendas user — List all users who are able to directly send an email as user. This has been set in the LDAP server, or with the --add-sendas command for Unix and DB plugins. Optionally use --type to indicate for what kind of object the sendas details are being requested. 📨
  • --clear-cache — Clears the server's caches. All data cached inside the kopano-server is cleared. Although this can never cause any data loss, it can affect the performance of your server, since any data requested after the cache is cleared needs to be re-requested from the database or LDAP server. Normally this option is never needed; it is mostly used as a diagnostics tool. 🧹

Optionally use --clear-cache= to specify a set of purge options. The following options can be used:

  • 0x0000 — Release no longer used memory back to the kernel
  • 0x0001 — Purge the quota cache
  • 0x0002 — Purge the quota default cache
  • 0x0004 — Purge the object cache
  • 0x0008 — Purge the store cache
  • 0x0010 — Purge the ACL cache
  • 0x0020 — Purge the cell cache
  • 0x0040 — Purge the index1 cache
  • 0x0080 — Purge the index2 cache
  • 0x0100 — Purge the indexproperty cache
  • 0x0200 — Purge the user object cache
  • 0x0400 — Purge the externid cache
  • 0x0800 — Purge the userdetails cache
  • 0x1000 — Purge the server cache
  • --purge-softdelete days — Starts a softdelete purge on the server, removing all soft-deleted items which have been deleted days days ago, or earlier. 🗑️
  • --purge-deferred — The server has an optimization in which changes to the tproperties table are not writted directly, but delayed for a more efficient write at a later time. The server auto-purges these regularly. This command allows you to purge all changes pending. It may be useful to run this during low I/O load of your server (eg at night). 🌙
  • --list-orphans — When a user is removed, the store becomes orphaned. This option shows a list of stores that are not hooked to a user. You can use the --remove-store and --hook-store from this list. 🧚
  • --hook-store store-guid — okay so bestie, sometimes a store gets orphaned (no user attached, just vibing alone 😭) and you can hook it back onto an existing user so you can actually get in there again. Use -u username to say which user you're hooking it to.

You can also copy an orphaned store over to the public store — just pass --copyto-public and it gets copied to the public folder named 'Admin/deleted stores'. Heads up: that folder is only visible to users with Kopano admin privileges 👑

Wanna hook a public store? Use --type group/company to influence the name type in the -u switch. Wanna hook an archive store? Use --type archive. Easy.

  • --remove-store store-guid — this action removes the store from the database. Ngl it's not actually gone-gone: the store just gets marked as deleted, so the softdelete system can come through later and remove it from the database for real. 💅
  • --create-store username — this one creates a store for a freshly created user, and it's normally called through the createuser script. So if --list-orphans showed you users with no store, you can build them a shiny new one with this. ✨
  • --unhook-store username — you can unhook a store from a user, so you're free to remove the store and make a new one.

Wanna unhook a public store? Use the --type group/company option to influence the name type in the username argument. Use a company name with type company, or 'Everyone' with type group, to unhook the public.

Wanna unhook an archive store? Use --type archive.

  • --force-resync usernames — when the data is out of sync, you can force a resync of cached profiles. You can name one or more usernames. If you don't give any usernames at all, then all offline profiles get resynced.
  • --reset-folder-count username — resets the counters on all folders in username's store. Fresh start energy. 🧼
  • --user-count — shows an overview of user counts per type of user. Stats girlies rise 🫶

✨ OPTIONS ✨

The options used by actions are as follows, bestie — buckle up, there's a lot, but they're all here:

  • --verbose level — set the verbosity level (0=critical, ..., 6=debug).
  • -v — increases the verbosity level by one, all the way up to the max of 6. Spam that -v if you love details 📈
  • -U 'new username' — use this parameter to rename a user. This option is only valid with the -u update action.
  • -p, --password password — set the password for a user. This option is only valid with the -c create or -u update action.
  • -P, --password-prompt — set the password for a user, but this time you type it at the password prompt. The password will not be shown (privacy queen 🔒). This option is only valid with the -c create or -u update action.
  • -f, --fullname 'full name' — specify the full user name. Wrap it in single quotes so it gets passed as a single parameter. This option is only valid with the -c create or -u update action.
  • -e, --email 'email address' — specify the email address. This address sets the 'From' email address in outgoing email messages. Wrap it in single quotes so it passes as one parameter. This option is only valid with the -c create or -u update action.
  • -a [yes|y|1|2 / no|n|0] — make the user an administrator by passing 'yes'. Pass 'no' and their admin rights get revoked. This option is only valid with the -c create or -u update action.

Oh and you can also pass 2 as the administrator level — that makes the user a system administrator who can create/modify/delete companies. Big power 👑

  • -n [yes|y|1 / no|n|0] — specify a non-active user. This user can't log in, but email can still be delivered, and the store can be opened by users with the correct rights. So: no login, still gets mail 📬
  • --qo [yes|y|1 / no|n|0] — override the default server quota settings for this user. User-specific quota levels will be used. The default value of this option is 'no', meaning it always uses the server quota levels. This option is only valid with the -c create or -u update action.
  • --qw value in Mb — set the warning quota level for a user. They may receive a warning email when this level is reached. Peep kopano-monitor(8) for warning emails. This option is only valid with the -c create or -u update action.
  • --qs value in Mb — set the soft quota level for a user. At this point the user will be unable to receive new emails, and the email gets bounced back to the sender. This option is only valid with the -c create or -u update action.
  • --qh value in Mb — set the hard quota level for a user. The user will be unable to receive and create new emails. This option is only valid with the -c create or -u update action.
  • --udqo [yes|y|1 / no|n|0] — override the default server quota settings for all users within the specified tenant. The default value of this option is 'no', always using the server quota levels.
  • --udqw value in Mb — set the warning quota level for all users within the specified tenant. The user may receive a warning email when this level is reached. See kopano-monitor(8) for warning emails.
  • --udqs value in Mb — set the soft quota level for all users within the specified tenant. The user will be unable to receive new emails, bouncing the email back to the sender. See kopano-monitor(8) for warning emails.
  • --udqh value in Mb — set the hard quota level for all users within the specified tenant. The user will be unable to receive and create new emails. See kopano-monitor(8) for warning emails.
  • -i groupname — sets the groupname for the -b and -B actions.
  • -I companyname — sets the companyname for all user, group and tenant commands. This option is only available for multi-tenancy Kopano.
  • --mr-accept [yes|y|1 / no|n|0] — says that meeting requests should automatically be accepted for a user. So when a meeting request is sent to this user while they're specified as being a 'resource', the request gets honoured directly and written to the calendar. Heads up: this is a client-side action, so this setting does not affect actual meeting requests being delivered via kopano-dagent. The user to operate on is selected with the -u switch.
  • --mr-decline-conflict [yes|y|1 / no|n|0] — this option only does anything when --mr-accept=yes is in effect. With --mr-decline-conflict, meeting requests that conflict with an existing meeting get declined. The user to operate on is selected with the -u switch.
  • --mr-decline-recurring [yes|y|1 / no|n|0] — this option only does anything when --mr-accept=yes is in effect. With --mr-decline-recurring, meeting requests that are recurring get declined. The user to operate on is selected with the -u switch.
  • --add-sendas sender — add user sender to the list of senders you're updating as a 'send as' user. Now the sender can send mails under the updated user's name — unless the updated user sets the sender as a delegate. And when the sender is a delegate, the mail gets sent with 'On behalf of' markings in the email. This option is only valid with the -u and --update-group update action.
  • --del-sendas sender — remove user sender from the list of senders you're updating as a 'send as' user. This option is only valid with the -u and --update-group update action.
  • --lang language — use language when creating new stores; that means the folders in the new store will be in the language you specified. Only valid in combination with --create-store. When this option isn't specified, the system default gets picked according to the LC_* and LANG environment variables, depending on your OS. 🌍
  • --utf8 — force the current locale to UTF-8. ✨

Other options to control the connection to the kopano-server are:

  • --host, -h path — connect to the storage server through path, e.g. file:///path/to/socket. Default: file:///var/run/kopano/server.sock. This option can always be specified.
  • --node name — execute the command on cluster node namereplaceable>
  • --config file — use a configuration file. See the CONFIG() section for more information.

Default: /etc/kopano/admin.cfg

🌸 CONFIG 🌸

Normally, no configuration file is used or required. But if the file /etc/kopano/admin.cfg exists, it's used as the configuration file — and ngl, no error checking is performed. That's actually kinda the point though: this way you can use any config file from a kopano program, e.g. kopano-spooler or kopano-dagent, to load SSL settings. 💅

The following options can be set in the configuration file:

  • server_socket — Unix socket to find the connection to the Kopano server.

Default: file:///var/run/kopano/server.sock

  • sslkey_file — use this file as key to logon to the server. This is only used when server_socket is set to an HTTPS transport. Peep the kopano-server(8) manual page on how to setup SSL keys.

Default: value not set.

  • sslkey_pass — the password of the SSL key file that is set in sslkey_file.

Default: value not set.

💖 EXAMPLES 💖

For creating a user:

kopano-admin -c loginname -p password -f 'Firstname Lastname' -e
f.lastname@tenant.com

For creating a non-login store:

kopano-admin -c loginname -p password -f 'Firstname Lastname' -e
f.lastname@tenant.com -n 1

For modifying the password and e-mail address:

kopano-admin -u loginname -p newpass -e fistname@tenant.com

For deleting a user:

kopano-admin -d loginname

For adding a user to a group:

kopano-admin -b loginname -i groupname

For setting a specific quota level for a user. Warning level to 80 Mb, soft level to 90 Mb and hard level to 100 Mb:

kopano-admin -u loginname --qo yes --qw 80 --qs 90 --qh 100

For automatically accepting meeting requests for a user or resource:

kopano-admin -u loginname --mr-accept y --mr-decline-conflict y
--mr-decline-recurring n

💖 EXTERNAL USERS 💖

Okay bestie, so here's the tea: when your users live in an external database, and the storage server is set up to use those users, then honestly a lot of the commands in kopano-admin just... stop making sense? Like they're giving unemployed. The example of an external database — and rn the only option, periodt — is an LDAP database. 🦋

The following actions can still be used, no problem. Every other command? Not you touching it — those get automatically triggered when the values change in the LDAP server. The server handles it, she's got main character energy. ✨

  • -s — create public store. 💅
  • -l — list users known to Kopano.
  • -L — list groups known to Kopano.
  • --details username — show user details. 👀
  • --sync — trigger a full synchronization for users and groups from the external source. 🔥

Now, when the users change in the external source, the Kopano server instantly synchronizes to those changes. Iconic, no notes. But there are two exceptions that need some extra attention, and those are when users are created or deleted. 🙈

When a user is created, the createuser_script from the kopano-server.cfg(5) will be started to create a store for a user. Likewise, when deleting a user, the deleteuser_script from the kopano-server.cfg(5) will be started to delete a store from a user. Same energy for creating and deleting a group and tenant, starting the creategroup_script/createcompany_script and deletegroup_script/deletecompany_script scripts respectively. So many scripts, but they're all doing their lil jobs. 🎀

🩺 DIAGNOSTICS 🩺

Could not create user/store/public store.

When you get this error, bestie, make sure the storage server and database server are running. That's it, that's the vibe check. 💀

👑 AUTHOR 👑

Written by Kopano.

🌈 SEE ALSO 🌈

And that's the whole page, babe — this was Kopano 8, dated November 2016, and you read every last word of it. Slay. 💖✨🎀

📦 where this page comes from