Difference between revisions of "Zmsoap"

Line 324: Line 324:
A SearchDirectoryRequest is performed, for example, by the admin console to generate a list of objects for the current view.
A SearchDirectoryRequest is performed, for example, by the admin console to generate a list of objects for the current view. See /opt/zimbra/docs/soap-admin.txt for more information on SearchDirectoryRequest.
This request queries the directory for all COS objects and returning the cn and description attributes.
This request queries the directory for all COS objects and returning the cn and description attributes.

Revision as of 22:40, 10 July 2011


Specify the request on the command line in an XPath-inspired syntax, and zmsoap takes care of authenticating, generating the envelope, sending the request, and writing the response to stdout.


ZCS 5.0

zmjava com.zimbra.common.soap.SoapCommandUtil got revamped, and a new launcher utility 'zmsoap' was added in 5.0.7+

$ zmsoap --help
zmsoap [options] <path1> [<path2> ...]                                          
  --help (-h)                 Print usage information.                          
  --mailbox (-m) name         Mailbox account name.  mail and account requests  
                              are sent to this account.  Also used for          
                              authentication if -a and -z are not specified.    
  --target name               Target account name to which requests will be     
                              sent.  Only used for non-admin sessions.          
  --admin (-a) name           Admin account name to authenticaste as.           
  --zadmin (-z)               Authenticate with zimbra admin name/password from 
  --password (-p) pass        Password.                                         
  --passfile (-P) path        Read password from file.                          
  --element (-e) path         Root element path.  If specified, all path        
                              arguments that don't start with a slash (/) are   
                              relative to this element.                         
  --type (-t) type            SOAP request type (mail, account, admin).         
                              Default is admin.                                 
  --url (-u) http[s]://...    Server hostname and optional port. 
                              SOAP service url, usually                            
                              http[s]://host:port/service/soap or                  
  --verbose (-v)              Print the SOAP request and other status           
  path [path ...]             Element or attribute path and value.  Roughly     
                              follows XPath syntax:                             

ZCS 6.0

In 6.0 D2 -e is removed, and the following is added:

  --type (-t) type         SOAP request type (mail, account, admin, im,         
                           mobile).  Default is admin.                          
  --verbose (-v)           Print the SOAP request and other status information. 
                           Specify twice for fully verbose output.              
  --no-op (-n)             Print the SOAP request only.  Don't send it.         
  --select path            Select element(s) or an attribute from the response. 
  --json                   Use JSON instead of XML.                             
  --file (-f) file-path    Read request from file.                              

Also discussions on AuthRequest being sent to adminSoapURL for a delegated token, while the payload of the mailbox/account request would get sent to SoapURL.

SOAP API Reference

Take a look in /opt/zimbra/docs on your Zimbra server for SOAP API documentation. There, you will find files named soap.txt, soap-admin.txt, and other soap-*.txt containing information on how to use the API.




Dump all grants for a specified grantee.

zmsoap -z GetGrantsRequest/grantee=user1@zmb.moc @type=usr @by=name @all=1

Attributes type, by and all are required for this request. If grantee does not have grants, then you will see this error:

ERROR: service.INVALID_REQUEST (invalid request: invalid grantee)

Dump grants for a specified target COS:

zmsoap -z GetGrantsRequest/target=e00428a1-0c00-11d9-836a-000d93afea2a @type=cos @by=id

See /opt/zimbra/doc/soap-right.txt for more options.


$ zmsoap -z -e GetAccountInfoRequest/account=user1 -v @by=name

Sending admin auth request to https://localhost:7071/service/admin/soap

<GetAccountInfoRequest xmlns="urn:zimbraAdmin">
  <account by="name">user1</account>

<GetAccountInfoResponse xmlns="urn:zimbraAdmin">
  <a n="zimbraId">decf3d72-623c-44d1-be34-23df4d285fb1</a>
  <a n="zimbraMailHost">cosmonaut.zimbra.com</a>
$zmsoap -z -t account -m user@domain.com -v GetInfoRequest
$ zmsoap -m user1 -p test123 -u http://localhost:7070/service/soap --type account GetInfoRequest | head

<GetInfoResponse xmlns="urn:zimbraAccount">
  <version>unknown unknown unknown unknown</version>


$ zmsoap -z -m user1 SearchRequest/query=in:inbox | head

<SearchResponse xmlns="urn:zimbraMail" offset="0" more="1" sortBy="dateDesc">
  <c f="u" score="1.0" id="-514" n="1" sf="1211495060000" d="1211495060000">
    <su>Goodmail test</su>
    <fr>Tastes great!</fr>
    <e d="goodmailbot42" a="goodmailbot42@aol.com" t="f"></e>
    <m id="514"></m>
  <c n="1" score="1.0" d="1211495060000" id="-525" f="u" sf="1211495060000">
    <su>Welcome to the Zimbra Collaboration Suite source!</su>


$ zmsoap -z -m user@domain.com -v -e FolderActionRequest/action op=empty id=1 recursive=false

Sending admin auth request to https://localhost:7071/service/admin/soap

<FolderActionRequest xmlns="urn:zimbraMail">

<FolderActionResponse xmlns="urn:zimbraMail">
  <action op="empty" id="1"></action>

Connectivity To Another Server

This command sends a GetServerRequest to mailbox1.domain.com and filters enabled services with grep.

$ zmsoap -z -v -u https://mailbox1.domain.com:7071/service/admin/soap/ -e GetServerRequest/server=mailbox2.domain.com @by=name | grep zimbraServiceEnabled
    <a n="zimbraServiceEnabled">antivirus</a>
    <a n="zimbraServiceEnabled">antispam</a>
    <a n="zimbraServiceEnabled">logger</a>
    <a n="zimbraServiceEnabled">mailbox</a>
    <a n="zimbraServiceEnabled">mta</a>
    <a n="zimbraServiceEnabled">stats</a>
    <a n="zimbraServiceEnabled">snmp</a>
    <a n="zimbraServiceEnabled">ldap</a>
    <a n="zimbraServiceEnabled">spell</a>
    <a n="zimbraServiceEnabled">imapproxy</a>

Active Server Sessions With DumpSessionsRequest

Dump login sessions from one server
$ zmsoap -z -t admin -v DumpSessionsRequest
Sending admin auth request to https://localhost:7071/service/admin/soap

<DumpSessionsRequest xmlns="urn:zimbraAdmin"/>

<DumpSessionsResponse xmlns="urn:zimbraAdmin" activeSessions="7">
  <imap activeSessions="2" activeAccounts="2"></imap>
  <admin activeAccounts="1" activeSessions="5"></admin>
Dump login sessions by account
$ zmsoap -z -t admin -v -e DumpSessionsRequest @groupByAccount=1 @listSessions=1
or later versions
$ zmsoap -z -v DumpSessionsRequest @groupByAccount=1 @listSessions=1
Sending admin auth request to https://localhost:7071/service/admin/soap

<DumpSessionsRequest xmlns="urn:zimbraAdmin" groupByAccount="1" listSessions="1"/>

<DumpSessionsResponse xmlns="urn:zimbraAdmin" activeSessions="7">
  <imap activeSessions="2" activeAccounts="2">
    <zid id="cb3136ab-ba07-447e-beeb-82b2b8072d62" name="user1@domain.com">
      <s cd="1229081559845" sid="22780" ld="1229110373411">
        <imap dirty="0" folder="INBOX" size="17" writable="1"></imap>
    <zid name="user2@domain.com" id="8acfc531-330b-49a3-b722-a0ef06f4f6c7">
      <s sid="22782" ld="1229110667123" cd="1229085464155">
        <imap dirty="0" writable="1" size="6352" folder="INBOX"></imap>
  <admin activeAccounts="1" activeSessions="5">
    <zid name="zimbra" id="e0fafd89-1360-11d9-8661-000a95d98ef2">
      <s ld="1229110825059" cd="1229110825059" sid="32914"></s>
      <s ld="1229110854718" sid="32915" cd="1229110854718"></s>
      <s cd="1229110854745" sid="32916" ld="1229110854745"></s>
      <s cd="1229110876252" sid="32917" ld="1229110876252"></s>
      <s cd="1229110876279" sid="32918" ld="1229110876279"></s>
Dump login sessions from ServerA and ServerB simultaneously
$ echo -e "\nServer A $(date)"; zmsoap -z -t admin DumpSessionsRequest && \
> echo -e "\nServer B $(date)"; zmsoap -z -a admin@zmb.moc -p zimbra -t admin -u https://ubu08.zmb.moc:7071/service/admin/soap/ DumpSessionsRequest

Server A Fri Dec 12 15:02:04 EST 2008

<DumpSessionsResponse xmlns="urn:zimbraAdmin" activeSessions="7">
  <imap activeAccounts="2" activeSessions="2"></imap>
  <admin activeSessions="5" activeAccounts="1"></admin>

Server B Fri Dec 12 15:02:06 EST 2008

<DumpSessionsResponse xmlns="urn:zimbraAdmin" activeSessions="6">
  <soap activeSessions="1" activeAccounts="1"></soap>
  <admin activeAccounts="1" activeSessions="5"></admin>


zmsoap -z -v GetSessionsRequest @type=soap @limit=5 @sortBy=accessedAsc

<GetSessionsRequest limit="5" type="soap" sortBy="accessedAsc" xmlns="urn:zimbraAdmin"/>
Sending admin auth request to https://localhost:7071/service/admin/soap

<GetSessionsResponse total="2" more="0" xmlns="urn:zimbraAdmin">
  <s sid="130" cd="1246992233580" ld="1246993445613" zid="36c41d5b-3387-458b-b460-20922649c94d" name="user@domain.com"/>
  <s sid="133" cd="1246992575537" ld="1246993486289" zid="36c41d5b-3387-458b-b460-20922649c94d" name="user@domain.com"/>

Check Account for Licensed Features

Feature attribute can be any one of mapi, mobileSync or iSync.

zmsoap -z -t account -m admin@zmb.moc -e CheckLicenseRequest feature=mapi

CheckLicenseResponse xmlns="urn:zimbraAccount" status="ok"></CheckLicenseResponse>

Test GAL Auto-Complete

zmsoap -z AutoCompleteGalRequest @name="name" @domain="domain.com" @limit="20" @type="resource"
<AutoCompleteGalResponse more="0" xmlns="urn:zimbraAdmin">
  <cn id="uid=offline_name,ou=people,dc=domain,dc=com">
    <a n="objectClass">organizationalPerson</a>
    <a n="objectClass">zimbraAccount</a>
    <a n="objectClass">amavisAccount</a>
    <a n="objectClass">zimbraCalendarResource</a>
    <a n="modifyTimeStamp">20090306042231Z</a>
    <a n="createTimeStamp">20070225054534Z</a>
    <a n="zimbraId">0c01af4c-5129-40a9-950d-33b46dfe2aac</a>
    <a n="fullName">The Name</a>
    <a n="zimbraCalResType">Equipment</a>
    <a n="email">offline_name@domain.com</a>
    <a n="lastName">Name</a>
  <cn id="uid=\23-name,ou=people,dc=domain,dc=com">
    <a n="objectClass">organizationalPerson</a>
    <a n="objectClass">zimbraAccount</a>
    <a n="objectClass">amavisAccount</a>
    <a n="objectClass">zimbraCalendarResource</a>
    <a n="modifyTimeStamp">20080731193821Z</a>
    <a n="createTimeStamp">20080205000649Z</a>
    <a n="zimbraId">d5840b21-a8b6-498d-b2d6-58da0fb0ab35</a>
    <a n="fullName">#-The Name</a>
    <a n="zimbraCalResType">Equipment</a>
    <a n="email">#-name@domain.com</a>
    <a n="lastName">Name</a>

As a user

zmsoap -a user@domain.com -p thePassword AutoCompleteGalRequest @name="name" @domain="domain.com" @limit="20" @type="resource"

Clear mailbox ranking table

zmsoap -z -m user RankingActionRequest/action @op=reset

Collect server stats

The data collected with GetServerStatsRequest corresponds to stats stored in /opt/zimbra/zmstat. See Server_Monitoring for more information on stats collection and chart generation.

All counters
zmsoap -z -t admin GetServerStatsRequest           
<GetServerStatsResponse xmlns="urn:zimbraAdmin">
  <stat name="account_cache_hit_rate">94.11</stat>
  <stat name="account_cache_size">64</stat>
  <stat name="bis_read">0</stat>
  <stat name="bis_seek_rate">0.00</stat>
  <stat name="calcache_hit">0.00</stat>
  <stat name="calcache_lru_size">0.00</stat>
  <stat name="calcache_mem_hit">0.00</stat>
  <stat name="cos_cache_hit_rate">92.38</stat>
Specific counters
zmsoap -z -t admin GetServerStatsRequest/stat @name=heap_used
<GetServerStatsResponse xmlns="urn:zimbraAdmin">
  <stat name="heap_used">428914224</stat>


A SearchDirectoryRequest is performed, for example, by the admin console to generate a list of objects for the current view. See /opt/zimbra/docs/soap-admin.txt for more information on SearchDirectoryRequest.


This request queries the directory for all COS objects and returning the cn and description attributes.

zmsoap -z -v SearchDirectoryRequest @offset="0" @limit="25" @sortBy="id" @sortAscending="1" @applyCos="false" @applyConfig="false" @attrs="cn,description" @types="coses" query=""
zmsoap -z -v SearchDirectoryRequest @offset="0" @limit="50" @sortBy="zimbraDomainName" @sortAscending="1" @applyCos="false" @applyConfig="false" \
@attrs="description,zimbraDomainName,zimbraDomainStatus,zimbraId,zimbraDomainType" @types="domains" query=""

In the query for accounts, we add maxResults=5000 to tell Java it is ok to ask LDAP for 5000 objects. See Zimbra bugs 60379 and 60382.

zmsoap -z -v SearchDirectoryRequest @offset="0" @limit="25" @sortBy="name" @sortAscending="1" @applyCos="false" @applyConfig="false" \
@attrs="displayName,zimbraId,zimbraAliasTargetId,cn,sn,zimbraMailHost,uid,zimbraCOSId,zimbraAccountStatus,zimbraLastLogonTimestamp, \
description,zimbraIsDelegatedAdminAccount,zimbraIsAdminAccount,zimbraIsSystemResource,zimbraAuthTokenValidityValue,zimbraMailStatus, \
zimbraIsAdminGroup,zimbraCalResType,zimbraDomainType,zimbraDomainName,zimbraDomainStatus,zimbraIsDelegatedAdminAccount,zimbraIsAdminAccount,zimbraIsSystemResource" \
@types="accounts" @maxResults="5000" query=""


zmmailbox uses refined syntax & is the typical admin tool along with zmprov

Jump to: navigation, search