pymap-admin 0.12.1

Description:

pymapadmin 0.12.1

pymap-admin





The pymap-admin tool can be used to perform various admin functions against a
running pymap server. This is a separate grpc service using grpclib
listening on a socket.
API Documentation
Connections
By default, the pymap-admin command will attempt to interact with a pymap
admin server over a UNIX socket, typically in /tmp/pymap/pymap-admin.sock.
See the pymap-admin --help commands for other connection options.
Commands
save-args Command
When administering remote pymap servers, it can be cumbersome to always supply
connection arguments every time, such as --host. This command saves the
arguments it is given to a config file.
$ pymap-admin --host imap.example.com --port 50051 save-args
Config file written: /home/user/.config/pymap/pymap-admin.conf

login Command
Sends login credentials and gets a bearer token. See
Authentication for more information.
$ pymap-admin login -is [email protected]
[email protected] Password:
result {
response: ". OK Login completed."
}
bearer_token: "MDAwZWxvY2F0aW9uIAowMDMwaWRlbnRpZmllciA0ZmM4MD..."

ping Command
Pings the running server and reports its version string.
$ pymap-admin ping
pymap_version: "0.21.1"
pymap_admin_version: "0.5.2"

append Command
To append a message directly to a mailbox, without using IMAP, use the
append admin command. First, check out the help:
$ pymap-admin append --help

As a basic example, you can append a message to a like this:
$ cat <<EOF | pymap-admin append demouser
> From: [email protected]
>
> test message!
> EOF
mailbox: "INBOX"
validity: 1784302999
uid: 101

2.0.0 Message delivered

User Commands
These commands access and manipulate the users on the system:
$ pymap-admin set-user --help
$ pymap-admin change-password --help
$ pymap-admin get-user --help
$ pymap-admin delete-user --help

Passing a username to get-user will display that user's metadata, including
the (securely hashed) password string. A username can be deleted with
delete-user. The set-user command will create or overwrite a username, its
password, and other metadata. The change-password command can update only the
password of an existing username.
If using pymap as part of the slimta-docker configuration, see its
Address Management documentation for additional options.
Admin Role
The builtin pymap backends use a special role string "admin" to assign admin
privileges to existing users. Without the admin role, a user may only use
set-user to change their own password. A user with the admin role (or using
the admin token) can make any change to any user.
$ pymap-admin set-user --role admin [email protected]

Authentication
Every command except ping requires authentication to
perform. Most commands will send a macaroon token to authenticate, except
for login which uses the credentials provided.
When running pymap-admin and pymap on the same machine, a temporary file
containing an admin token is used by default, allowing unrestricted access to
all operations. This token is verified in-memory and is only valid for the
current pymap process.
To use this admin token on another machine, copy the PYMAP_ADMIN_TOKEN=...
line printed out on pymap startup and prefix it to pymap-admin calls, e.g.:
$ PYMAP_ADMIN_TOKEN=... pymap-admin get-user [email protected]

Permanent Tokens
For a token that is not tied to the current pymap process, use the
login with the credentials of a user in the system. The
resulting token can be used to authenticate as that user in the future.
$ pymap-admin login -is [email protected]

The -s flag will cause the token to be saved and used on future pymap-admin
commands. Use --token-file or $PYMAP_ADMIN_TOKEN_FILE to specify a
location, otherwise it is saved to ~/.pymap-admin.token.
If -s is not given, the bearer_token value from the output can provided to
future pymap-admin commands with $PYMAP_ADMON_TOKEN.