Admin tool for running pymap instances.
Project description
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
login
Command
Sends login credentials and gets a bearer token. See Authentication for more information.
$ pymap-admin login -is user@example.com
user@example.com Password:
result {
response: ". OK Login completed."
}
bearer_token: "MDAwZWxvY2F0aW9uIAowMDMwaWRlbnRpZmllciA0ZmM4MD..."
ping
Command
Pings the running server and reports its version string.
$ pymap-admin ping
server_version: "0.14.1"
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: user@example.com
>
> 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 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 and update a username and its
password.
If using pymap as part of the slimta-docker configuration, see its Address Management documentation for additional options.
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 user@example.com
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 user@example.com
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
non-temporary location.
If -s
is not given, the bearer_token
value from the output can provided to
future pymap-admin
commands with --token
or $PYMAP_ADMON_TOKEN
.
Admin Role
The builtin pymap backends use a special key "role" to assign admin privileges
to existing users, authorizing them to run pymap-admin
commands on other
users.
$ pymap-admin set-user --param role=admin user@example.com
This role may only be assigned by users that already have it, or by authenticating using the admin token.
The MIT License (MIT)
Copyright (c) 2019 Ian Good
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pymap_admin-0.5.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8489cc6f8887dedf7f3cffdb9668d40b720e8f4886feeb65a868eee014a48606 |
|
MD5 | 5040de2c3523bd8f4bef968dad9469e8 |
|
BLAKE2b-256 | 71476a2fb0de3875841692d6b2fd455d8e4f70e8e48e695cc0ac874b590a73c9 |