Template:DoveadmHTTPapi: Difference between revisions

From Open-Xchange
Line 116: Line 116:
submitting the command with curl:
submitting the command with curl:


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


command line equivalent
command line equivalent


doveadm reload
doveadm reload


=== successful response ===
=== successful response ===

Revision as of 07:15, 6 March 2017

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: 

# 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 update

{
    "command": "directorUpdate",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "host",
            "type": "string"
        },
        {
            "name": "vhostCount",
            "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 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"
        }
    ]
}

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
user String Show hashed status for individual user testuser001
tag String Show director status for tagged hosts only NewBackend
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

show director ring status

parameters: 


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

example: 

[
    [
        "directorRingStatus",
        {},
        "bb"
    ]
]

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

response: 


    [
        "doveadmResponse",
        [	
            {
                "director ip": "10.0.0.232",
                "last failed": "never",
                "port": "9143",
                "status": "synced",
                "type": "self"
            },
            {
                "director ip": "10.0.0.233",
                "last failed": "never",
                "port": "9143",
                "status": "",
                "type": ""
            }
        ],
        "bb"
    ]
]

CLI: doveadm director ring status

doveadm proxy

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

doveadm proxy list

list active connections in the dovecot proxy

parameters: 

{
    "command": "proxyList",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server

example: 

</nowiki>

[ 

   [
       "proxyList",
       {},
       "bb"
   ]

]

  1. curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response: 

[
    [
        "doveadmResponse",
        [	
            {
                "dest-ip": "127.0.0.1",
                "dest-port": "1143",
                "service": "imap",
                "src-ip": "10.0.0.153",
                "username": "samik"
            }
        ],
        "bb"
    ]
]

CLI: doveadm proxy list

doveadm proxy kick

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters: 

{
    "command": "proxyKick",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "user",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String userid to kick samik

example: 

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

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

response: 

[
    [
        "doveadmResponse",
        [
            {
                "count": "1"
            }
        ],
        "bb"
    ]
]

CLI: doveadm proxy kick samik

doveadm logs errors

fetch errors log

paraments: 


    "command": "logErrors",
    "parameters": [
        {
            "name": "since",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server

example: 

[
    [
        "logErrors",
        {},
        "a2"
    ]	
]

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

response: 

 [
    [
        "doveadmResponse",
        [
            {
                "prefix": "stats",
                "text": "Stats client input error: Invalid level",
                "timestamp": "Dec 09 16:24:00",
                "type": "Error"
            },
            {
                "prefix": "doveadm(127.0.0.1)",
                "text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
                "timestamp": "Dec 09 16:24:00",
                "type": "Fatal"
            },
            {	
                "prefix": "stats",
                "text": "Stats client input error: Invalid level",
                "timestamp": "Dec 09 16:24:22",
                "type": "Error"
            },
            {
                "prefix": "stats",
                "text": "Stats client input error: Invalid level",
                "timestamp": "Dec 09 16:27:48",
                "type": "Error"
            },
            {
                "prefix": "director",
                "text": "Empty server list",
                "timestamp": "Dec 09 16:29:13",
                "type": "Error"
            },
            {
                "prefix": "director",
                "text": "Invalid value for director_mail_servers setting",
                "timestamp": "Dec 09 16:29:13",
                "type": "Fatal"
            }
        ],
        "a2"
    ]
]

CLI: doveadm log errors

doveadm dict

doveadm dict get

get user key value from configured dictionary

parameters: 

{
    "command": "dictGet",
    "parameters": [
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "dictUri",
            "type": "string"
        },
        {
            "name": "key",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String uid of user to query samik
dictUri String optional URI for dictionary to query
key String key to query


doveadm dict set

set user key value in configured dictionary

parameters: 

{
    "command": "dictSet",
    "parameters": [
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "dictUri",
            "type": "string"
        },
        {
            "name": "key",
            "type": "string"
        },
        {
            "name": "value",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String uid of user to modify dictionary key samik
dictUri String optional URI for dictionary to modify
key String dictionary key to modify
value string value to set

doveadm dict unset

unset user key value in configured dictionary

parameters: 

{
    "command": "dictUnset",
    "parameters": [
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "dictUri",
            "type": "string"
        },
        {
            "name": "key",
            "type": "string"
        }
    ]
}

parameters:

Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String uid of user to modify dictionary key
dictUri String optional URI for dictionary to modify
key String dictionary key to unset

doveadm dict inc

increase users key value in dictionary

parameters: 

{
    "command": "dictInc",
    "parameters": [
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "dictUri",
            "type": "string"
        },
        {
            "name": "key",
            "type": "string"
        },
        {
            "name": "difference",
            "type": "integer"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String optional URI for dictionary to modify
key String dictionary key to increase
difference integer increment value

doveadm dict iter

list user keys in dictionary

parameters: 

{
    "command": "dictIter",
    "parameters": [
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "exact",
            "type": "boolean"
        },
        {
            "name": "recurse",
            "type": "boolean"
        },
        {
            "name": "noValue",
            "type": "boolean"
        },
        {
            "name": "dictUri",
            "type": "string"
        },
        {
            "name": "prefix",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String uid of user to modify dictionary key
dictUri String optional URI for dictionary to modify
exact Boolean list only exact matches
recurce Boolean do recursive search
noValue Boolean list also keys that have no value set
prefix String search only keys with given prefix

doveadm fs

doveadm fs get

get object from storage

parameters: 

{
    "command": "fsGet",
    "parameters": [
        {
            "name": "fsDriver",
            "type": "string"
        },
        {
            "name": "fsArgs",
            "type": "string"
        },
        {
            "name": "path",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
fsDriver String filesystem
fsArgs String filesystem driver arguments to use
path String object path in filesystem to fetch

doveadm fs put

put object to storage

parameters: 

{
    "command": "fsPut",
    "parameters": [
        {
            "name": "hash",
            "type": "string"
        },
        {
            "name": "fsDriver",
            "type": "string"
        },
        {
            "name": "fsArgs",
            "type": "string"
        },
        {
            "name": "inputPath",
            "type": "string"
        },
        {
            "name": "path",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
fsDriver String filesystem
fsArgs String filesystem driver arguments to use
inputPath String object path in filesystem to put

doveadm copy

copy object in storage

parameters: 

{
    "command": "fsCopy",
    "parameters": [
        {
            "name": "fsDriver",
            "type": "string"
        },
        {
            "name": "fsArgs",
            "type": "string"
        },
        {
            "name": "sourcePath",
            "type": "string"
        },
        {
            "name": "destinationPath",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
fsDriver String filesystem
fsArgs String filesystem driver arguments to use
sourcePathh String source object path
Destination path String destination object path in filesystem

doveadm fs stats

fetch fs driver statistics

parameters: 

{
    "command": "fsStat",
    "parameters": [
        {
            "name": "fsDriver",
            "type": "string"
        },
        {
            "name": "fsArgs",
            "type": "string"
        },
        {
            "name": "path",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
fsDriver String filesystem
fsArgs String filesystem driver arguments to use
path String object path in filesystem fetch statistics for

doveadm fs metadata

get filesystem object metadata

parameters: 

{
    "command": "fsMetadata",
    "parameters": [
        {
            "name": "fsDriver",
            "type": "string"
        },
        {
            "name": "fsArgs",
            "type": "string"
        },
        {
            "name": "path",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
fsDriver String filesystem
fsArgs String filesystem driver arguments to use
path String object path in filesystem fetch statistics for

doveadm fs delete

delete object from storage 

{
    "command": "fsDelete",
    "parameters": [
        {
            "name": "recursive",
            "type": "boolean"
        },
        {
            "name": "maxParallel",
            "type": "integer"
        },
        {
            "name": "fsDriver",
            "type": "string"
        },
        {
            "name": "fsArgs",
            "type": "string"
        },
        {
            "name": "path",
            "type": "array"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
fsDriver String filesystem
fsArgs String filesystem driver arguments to use
path String object path in filesystem fetch statistics for
recursive Boolean do a recursive delete of path
maxParallel integer max number of parallel workers

doveadm fs iter

list objects in given fs path

parameters: 

{
    "command": "fsIter",
    "parameters": [
        {
            "name": "fsDriver",
            "type": "string"
        },
        {
            "name": "fsArgs",
            "type": "string"
        },
        {
            "name": "path",
            "type": "string"
        }
    ]
}


Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
fsDriver String filesystem
fsArgs String filesystem driver arguments to use
path String path in filesystem to list

doveadm fs iter-dirs

parameters: 

{
    "command": "fsIterDirs",
    "parameters": [
        {
            "name": "fsDriver",
            "type": "string"
        },
        {
            "name": "fsArgs",
            "type": "string"
        },
        {
            "name": "path",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
fsDriver String filesystem
fsArgs String filesystem driver arguments to use
path String path in filesystem to list for subfolders

doveadm auth cache flush

flush authentication cache for one user or all users

parameters: 

{
    "command": "authCacheFlush",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "user",
            "type": "array"
        }
    ]
}
Parameter Type Description example
socketPath String Path to doveadm socket /var/run/dovecot/doveadm-server
user String array optional list of users in flush [“samik”,”samitest”]

example: 

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


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

response: 

[
    [
        "doveadmResponse",
        [
            {
                "entries": "0"
            }
        ],
        "bb"
    ]
]

CLI: doveadm auth cache flush samik

doveadm user

do a users lookup for an user 

{
    "command": "user",
    "parameters": [
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "authInfo",
            "type": "array"
        },
        {
            "name": "field",
            "type": "string"
        },
        {
            "name": "expandField",
            "type": "string"
        },
        {
            "name": "userdbOnly",
            "type": "boolean"
        },
        {
            "name": "userMask",
            "type": "array"
        }
    ]
}

parameters:

Parameter Type Description example
authInfo String array auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.

Possible names for the auth_info are: service The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp. lip The local IP address (server) for the test. rip The remote IP address (client) for the test. lport The local port, e.g. 143 rport The remote port, e.g. 24567

sevice=imap
field String fetch only one specified field instead of all
expandField String expand configuration variable with user specific values
userdbOnly Boolean only fetch from userdb lookup and don’t process passdb
userMask String array search filter

example: 

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


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

response: 

[
    [
        "doveadmResponse",
        {
            "samik": {
                "gid": "1000",
                "home": "/var/vmail/samik",
                "junkflag": "0",
                "mail": "Maildir:/mails/mails/samik/Maildir",
                "namespace/Junk/hidden": "no",
                "namespace/Junk/list": "yes",
                "uid": "1000"
            }
        },
        "bb"
    ]
]

CLI: doveadm user samik

doveadm mailbox

doveadm mailbox metadata set

set user mailbox. metadata

parameters: 

{
    "command": "mailboxMetadataSet",
    "parameters": [
        {
            "name": "allUsers",
            "type": "boolean"
        },
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "userFile",
            "type": "string"
        },
        {
            "name": "mailbox",
            "type": "string"
        },
        {
            "name": "key",
            "type": "string"
        },
        {
            "name": "value",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String path to doveadm socket /var/run/dovecot/doveadm-server
allUsers boolean apply operation to all users
user String uid to apply metadata set
userFile String optionally fetch usernames from file. One username per line
key String metadata key to set
value String metadata value to set

example: 

[
    [
        "mailboxMetadataSet",
        {
            "key": "/private/comment",
            "mailbox": "INBOX",
            "user": "samik",
            "value": "test"
        },
        "bb"
    ]
]


# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1

response: 

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

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test

doveadm mailbox metadata unset

unset user mailbox metadata

parameters: 

{
    "command": "mailboxMetadataUnset",
    "parameters": [
        {
            "name": "allUsers",
            "type": "boolean"
        },
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "userFile",
            "type": "string"
        },
        {
            "name": "mailbox",
            "type": "string"
        },
        {
            "name": "key",
            "type": "string"
        }
    ]
}

parameters:

Parameter Type Description example
socketPath String path to doveadm socket /var/run/dovecot/doveadm-server
allUsers boolean apply operation to all users
user String uid to apply metadata unset
userFile String optionally fetch usernames from file. One username per line
key String metadata key to unset

example: 

[
    [
        "mailboxMetadataUnset",
        {
            "key": "/private/comment",
            "mailbox": "INBOX",
            "user": "samik"
        },
        "bb"
    ]
]


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

response: 

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

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment

doveadm mailbox metadata get

get user mailbox metadata

parameters: 

{
    "command": "mailboxMetadataGet",
    "parameters": [
        {
            "name": "allUsers",
            "type": "boolean"
        },
        {
            "name": "socketPath",
            "type": "string"
        },
        {
            "name": "user",
            "type": "string"
        },
        {
            "name": "userFile",
            "type": "string"
        },
        {
            "name": "mailbox",
            "type": "string"
        },
        {
            "name": "key",
            "type": "string"
        }
    ]
}
Parameter Type Description example
socketPath String path to doveadm socket /var/run/dovecot/doveadm-server
allUsers boolean apply operation to all users
user String uid to apply metadata get
userFile String optionally fetch usernames from file. One username per line
key String metadata key to get

example: 

[
    [
        "mailboxMetadataGet",
        {
            "key": "/private/comment",
            "mailbox": "INBOX",
            "user": "samik"
        },
        "bb"
    ]
]

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

response 

[
    [
        "doveadmResponse",
        [
            {
                "value": "plaa"
            }
        ],
        "bb"
    ]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment

doveadm mailbox meta list

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