Template:DoveadmHTTPapi

From Open-Xchange
Revision as of 11:42, 1 March 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

example: 

 [
    [
        "kick",
        {
            "force": 0,
            "mask": "testuser001"
        },
        "aa"
    ]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001

response for succesfull kick:

[
    [
        "doveadmResponse",
        [
            {
                "result": "testuser001"
            }
        ],
        "aa"
    ]
]

response in case kick failed:

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

doveadm who

list active dovecot sessions


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

parameters

Parameter Type Description example
socketPath string Path to doveadm socket /var/run/dovecot/doveadm-server
separateConnections Boolean Show each user connection in separate entries 0
mask string array Uid mask testuser001

Example: 

[
    [
        "who",
        {
            "mask": "",
            "separateConnections": 0,
            "socketPath": ""
        },
        "aa"
    ]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who

response: 

[
    [
        "doveadmResponse",
        [
            {
                "connections": "1",
                "ips": "(127.0.0.1)",
                "pids": "(4999)",
                "service": "imap",
                "username": "testuser001"
            }
        ],
        "aa"
    ]
]

doveadm director

doveadm director status

Show backend statuses on directors. Available only in directors 

[
    {
        "command": "directorStatus",
        "parameters": [
            {
                "name": "socketPath",
                "type": "string"
            },
            {
                "name": "user",
                "type": "string"
            },
            {
                "name": "tag",
                "type": "string"
            }
        ]
    }
]

parameters:

Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String Show hashed status for individual user testuser001
tag String Show director status for Tagged hosts only NewBackend

example: 

[
    [
        "directorStatus",
        {},
        "bb"
    ]
]

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

response 

[
    [
        "doveadmResponse",
        [
            {
                "mail server ip": "10.0.0.234",
                "state": "up",
                "state-changed": "2016-12-15 08:31:37",
                "tag": "",
                "users": "1",
                "vhosts": "100"
            },
            {
                "mail server ip": "10.0.0.235",
                "state": "up",
                "state-changed": "2016-12-15 08:31:04",
                "tag": "",
                "users": "0",
                "vhosts": "100"
            }
        ],
        "bb"
    ]
]

CLI: doveadm director status

doveadm director map

list current user → host mappings. Applicable to director only 


    "command": "directorMap",
    "parameters": [
        {	
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "usersFile",
            "type": "string"
        },
        {
            "name": "hashMap",
            "type": "boolean"
        },
        {
            "name": "userMap",
            "type": "boolean"
        },
        {
            "name": "host",
            "type": "string"
        }
    ]
}

parameters

Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
usersFile String provide Path to users list. One username per line /etc/dovecot/userlist.txt
hashMap Boolean Output users as hashmap true
host String Show only mappings to given host 10.0.0.234

example: 

[
    [
        "directorMap",
        {},
        "bb"
    ]
]

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

response: 

[
    [
        "doveadmResponse",
        [
            {
                "expire time": "2016-12-30 14:52:56",
                "hash": "3853430566",
                "mail server ip": "10.0.0.235",
                "user": "samik"
            }
        ],
        "bb"
    ]
]

CLI: doveadm director map

doveadm director add

add backend to director ring 

{
    "command": "directorAdd",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "tag",
            "type": "string"
        },
        {
            "name": "host",
            "type": "string"
        },
        {
            "name": "vhostCount",
            "type": "string"
        }
    ]
}

parameters:

Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
tag String apply tag to backend /etc/dovecot/userlist.txt
host String backend ip to add 10.0.0.234
vhostCount String chost count to add 100

doveadm director up

{
    "command": "directorUp",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "host",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String Show hashed status for individual user testuser001
tag string Show director status for tagged hosts only NewBackend

doveadm director down

{
    "command": "directorDown",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "host",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String Show hashed status for individual user testuser001
tag string Show director status for tagged hosts only NewBackend

doveadm director remove

remove backend from director ring 

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

parameters:

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

example: 

[
    [
        "directorRemove",
        {
            "host": "10.0.0.234"
        },
        "aa"
    ]
]

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

response: 

[
    [
        "doveadmResponse",
        [],
        "aa"
    ]
]

CLI: doveadm director remove 10.0.0.234

doveadm director move

move user mapping from backend to another or create director mapping for an user

{
    "command": "directorMove",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "host",
            "type": "string"
        }
    ]
}

parameters


Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/director-admin
user String target backend ip as listed in doveadm director status 10.0.0.234

example: 

[
    [
        "directorMove",
        {
            "host": "10.0.234",
            "user": "samik"
        },
        "bb"
    ]
]


# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

response: 

[
    [
        "doveadmResponse",
        [],
        "bb"
    ]
]

CLI: doveadm director move samik 10.0.0.234

doveadm director kick


    "command": "directorKick",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },	
        {
            "name": "user",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/director-admin
user String uid of user to kick samik

example: 

[
    [
        "directorKick",
        {
            "user": "samik"
        },
        "bb"
    ]
]

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

response 

[
    [
        "doveadmResponse",
        [],
        "bb"
    ]
]

CLI: doveadm director kick samik

doveadm director flush

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters: 

{
    "command": "directorFlush",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "forceFlush",
            "type": "boolean"
        },
        {
            "name": "host",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/director-admin
forceFlush Boolean Flag to make flush forced true
host String Backend ip address from doveadm director director status list 10.0.0.234

example: 

[
    [
        "directorFlush",
        {
            "host": "10.0.0.234"
        },
        "aa"
    ]
]

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

response: 

[
    [
        "doveadmResponse",
        [],
        "aa"
    ]
]
CLI: doveadm director flush 10.0.234

doveadm director dump

Dumb the current director backend host configuration as commands 

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

parameters:
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/director-admin

example: 

[
    [
        "directorDump",
        {},
        "bb"
    ]
]

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

response: 

[
    [
        "doveadmResponse",
        [
            {
                "command": "add",
                "host": "10.0.0.234",
                "socket-path": "/var/run/dovecot/director-admin",
                "vhost_count": "100"
            },
            {
                "command": "add",
                "host": "10.0.0.235",
                "socket-path": "/var/run/dovecot/director-admin",
                "vhost_count": "100"
            }
        ],
        "bb"
    ]
]

CLI: doveadm director dump

doveadm director ring add

add new director to director ring

parameters: 

{
    "command": "directorRingAdd",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "ip",
            "type": "string"
        },
        {
            "name": "port",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/director-admin
ip String director ip address to add 10.0.0.233
port String port number to use if not default 9143

example: 

[
    [
        "directorRingAdd",
        {
            "ip": "10.0.0.233"
        },
        "bb"
    ]
]


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

response: 

[
    [
        "doveadmResponse",
        [],
        "bb"
    ]	
]

CLI: doveadm director ring add 10.0.0.233

doveadm director ring remove

remove director from director ring

parameters: 

{
    "command": "directorRingRemove",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "ip",
            "type": "string"
        },
        {
            "name": "port",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/director-admin
ip String director ip to remove 10.0.0.233
port String director service port if not default 9143

example: 

[
    [
        "directorRingRemove",
        {
            "ip": "10.0.0.233"
        },
        "bb"
    ]
]

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

response: 

[
    [
        "doveadmResponse",
        [],
        "bb"
    ]
]

CLI: doveadm director ring remove 10.0.0.233

doveadm director ring status

Retrieved from "https://wiki.open-xchange.com/wiki/index.php?title=Template:DoveadmHTTPapi&oldid=22980"