Template:DoveadmHTTPapi

From Open-Xchange
Revision as of 11:02, 28 February 2017 by Oskarikentta (talk | contribs)

doveadm http api

configuration

To be able to use doveadm http api it’s mandatory to configure either password for doveadm or a api key.

To configure password for doveadm service in /etc/dovecot/dovecot.conf:

doveadm_password = hellodoveadm

Or if preferred to use separate key for doveadm http api then it can be enabled by defining key in config:

doveadm_api_key = key

And to enable the doveadm http listener: 

 service doveadm {
  unix_listener doveadm-server {
    user = vmail
  }
  inet_listener {
   port = 2425
  }
  inet_listener http {
    port = 8080
    #ssl = yes # uncomment to enable https
  }
}

usage

connecting to endpoint can then be done by using standard http protocol and authentication headers. To get list the commands supported by the endpoint, the following example commands can be used:

X-Dovecot-API auth usage:

curl -H "Authorization: X-Dovecot-API <base64 dovecot_api_key>" http://host:port/doveadm/v1

Basic auth usage:

curl -H "Authorization: Basic <base64 doveadm:doveadm_password>" http://host:port/doveadm/v1

or by letting curl to form the base64 encoded authentication basig authentication header:

curl –u doveadm:password http://host:port/doveadm/v1

command usage

All commands sent to the API needs to be posted in json format using “Content-Type: application/json” in headers for the request type and the json content as payload in format: 


[
    [
        "command1",
        {
            "parameter1": "value",
            "parameter2": "value",
            "parameter3": "value"
        },
        "identifier"
    ]
]

Multiple commands can be submitted in one json payload: 

[
    [
        "command1",
        {
            "parameter1": "value",
            "parameter2": "value"
        },
        "identifier1"
    ],
    [
        "command2",
        {
            "parameter1": "value",
            "parameter2": "value"
        },
        "identifier2"
    ]
]

For now it is safest not to send multiple commands in one json payload, as some commands may kill the server in certain error conditions and leaving you without any response. Also it is not guaranteed that the commands will be processed in order.

All commands are case sensitive.

example usage

In the example we ask dovecot to reload configuration: 


son payload:

[
    [
        "reload",
        {},
        "a2"
    ]
]

submitting the command with curl:

  1. curl -v -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["reload",{},"a2"]]'

command line equivalent

doveadm reload


successful response


[
    [
        "doveadmResponse",
        [],
        "a2"
    ]
]

failure response


[
    [
        "error",
        {
            "exitCode": 68,
            "type": "exitCode"
        },
        "a2"
    ]

failure codes

2 Success but mailbox changed during operation
64 Invalid parameters
65 Data error
67 User does not exist
68 User does not have session
73 User out of quota
75 Temporary error
77 No permission
78 valid configuration

Supported commands

doveadm service

doveadm service stop

stop one or more dovecot services on target host 

{
    "command": "serviceStop",
    "parameters": [
        {
            "name": "service",
            "type": "array"
        }
    ]
}

parameters:

Parameter Type Description example
service string array Name of service to stop [“imap”,”imap-hibernate”]

example: 

[
    [
        "serviceStop",
        {
            "service": [
                "imap",
                "imap-hibernate"
            ]
        },
        "aa"
    ]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate

doveadm stop

stop dovecot on the target host 


{
    "command": "stop",
    "parameters": []
}


no parameters

example: 

[
    [
        "stop",
        {},
        "a1"
    ]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop

doveadm reload

reload dovecot configuration 

{
    "command": "reload",
    "parameters": []
}

example: 

[
    [
        "reload",
        {},
        "a2"
    ]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["reload",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm reload

doveadm stats

doveadm stats dump

dovecot collected dovecot statistics 

  {
     "command": "statsDump",
     "parameters": [
         {
             "name": "socketPath",
             "type": "string"
         },
         {
             "name": "type",
             "type": "string"
         },
         {
             "name": "filter",
             "type": "string"
         }
     ]
 }
parameters
Parameter Type Description example
socketPath string Path to doveadm socket /var/run/dovecot/dovearm-server
type string String Type of stats to dump global
filter String Dump filter last update 1483101542

Example: 

[
    [
        "statsDump",
        {
            "type": "global"
        },
        "aa"
    ]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1

response: 

[
    [
        "doveadmResponse",
        [
            {
                "auth_cache_hits": "0",
                "auth_cache_misses": "0",
                "auth_db_tempfails": "0",
                "auth_failures": "0",
                "auth_master_successes": "0",
                "auth_successes": "0",
                "clock_time": "0.0",
                "disk_input": "0",
                "disk_output": "0",
                "fscache_read": "0",
                "fscache_stat": "0",
                "fscache_write": "0",
                "idx_del": "0",
                "idx_iter": "0",
                "idx_read": "0",
                "idx_read_usecs": "0",
                "idx_wbytes": "0",
                "idx_write": "0",
                "idx_write_usecs": "0",
                "invol_cs": "0",
                "last_update": "0.000000",
                "mail_cache_hits": "0",
                "mail_lookup_attr": "0",
                "mail_lookup_path": "0",
                "mail_read_bytes": "0",
                "mail_read_count": "0",
                "maj_faults": "0",
                "min_faults": "0",
                "num_cmds": "0",
                "num_connected_sessions": "0",
                "num_logins": "0",
                "obox_copy": "0",
                "obox_del": "0",
                "obox_iter": "0",
                "obox_read": "0",
                "obox_read_usecs": "0",
                "obox_stat": "0",
                "obox_wbytes": "0",
                "obox_write": "0",
                "obox_write_usecs": "0",
                "read_bytes": "0",
                "read_count": "0",
                "reset_timestamp": "1483104199",
                "sys_cpu": "0.0",
                "user_cpu": "0.0",
                "vol_cs": "0",
                "write_bytes": "0",
                "write_count": "0"
            }
        ],
        "aa"
    ]
]

CLI: doveadm stats dump global

doveadm stats reset

reset dovecot statistics

{
    "command": "statsReset",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        }
    ]
}

parameters

Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server

example: 

[
    [
        "statsReset",
        {},
        "aa"
    ]
]

curl -v -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["statsReset",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm stats reset

doveadm penalty

show current penalties

{
    "command": "penalty",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "netmask",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath string Path to doveadm socket /var/run/dovecot-server
netmask string To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask) 10.0.0.0/24

example: 

[
    [
        "penalty",
        {},
        "aa"
    ]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty

doveadm kick

Kick user from dovecot. Applicable to session in dovecot backend only 

{    
    "command": "kick",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "force",
            "type": "boolean"
        },
        {
            "name": "mask",
            "type": "array"
        }
    ]
}

parameters:

Parameter Type Description example
socketPath string Path to doveadm socket /var/run/roveam-server
force Boolean Do a forced kick? 0
mask string Uid mask testuser001
Retrieved from "https://wiki.open-xchange.com/wiki/index.php?title=Template:DoveadmHTTPapi&oldid=22973"