Zmsoap

Zmsoap

   KB 2526        Last updated on 2015-07-13  




0.00
(0 votes)

Intro

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.

Usage

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
Usage:                                                                          
zmsoap [options] <path1> [<path2> ...]                                          
options                                                                         
  --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 
                              localconfig.                                      
  --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                  
                              https://host:port/service/admin/soap.                 
  --verbose (-v)              Print the SOAP request and other status           
                              information.                                      
  path [path ...]             Element or attribute path and value.  Roughly     
                              follows XPath syntax:                             
                              [/]element1[/element2][/@attr][=value].         

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.

ZCS8 SOAP API Reference

ZCS8 Examples

GetLoggerStatsRequest

SOAP API reference

Stat groups

Dumps available stat groups for the specified server.

zmsoap -z GetLoggerStatsRequest/hostname @hn="mbs1.zmb.moc"
Stat names

Dump available stat names for a specified stat group name.

zmsoap -z GetLoggerStatsRequest/hostname @hn="mbs1.zmb.moc" ../stats=1 @name="mysql.csv"

If the command results in

Exception in thread "main" java.lang.OutOfMemoryError: Java heap space

then increase the heap space available to zmjava in localconfig.

Check the current value

zmlocalconfig zimbra_zmjava_options
zimbra_zmjava_options = -Xmx256m -Djava.net.preferIPv4Stack=true

Set the new value

zmlocalconfig -e zimbra_zmjava_options="-Xmx512m -Djava.net.preferIPv4Stack=true"
MySQL uptime

Dump MySQL uptime statistics from mailbox host mbs1.zmb.moc.

SOAP request for MySQL uptime:

<GetLoggerStatsRequest xmlns="urn:zimbraAdmin">
  <hostname hn="mbs1.zmb.moc"/>
  <stats name="mysql.csv">
    <values>
      <stat name="Uptime"/>
    </values>
  </stats>
</GetLoggerStatsRequest>

To construct the zmsoap command, work from the deepest elements and attributes in the request to formulate the XPath from left to right.

zmsoap -z GetLoggerStatsRequest/hostname @hn="mbs1.zmb.moc" ../stats/values/stat @name="Uptime" ../../@name="mysql.csv"

Examples

FolderActionRequest

Folder Retention Policies

The zmsoap below sets a message disposal policy with a 90 day threshold on folder Id 2 (Inbox). This is the same as ZWC -> Right Click Folder -> Edit Properties -> Retention -> Check "Enable Message Disposal" for 90 days.

zmsoap -z -m user@domain.tld FolderActionRequest/action @id="2" @op="retentionpolicy" retentionPolicy/keep \
> ../purge/policy @lifetime="90d" @type="user"
<FolderActionResponse xmlns="urn:zimbraMail">
  <action id="2" op="retentionpolicy"/>

zmsoap generally follows XPath syntax. Each subsequent path is relative to the one previously specified. Since retentionPolicy/keep and retentionPolicy/purge are on the same level, it is necessary to prefix purge with "../" in order to set the path correctly.

GetGrantsRequest

Grantee

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)
Target

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.

GetAccountInfo

$ 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>
</GetAccountInfoRequest>

<GetAccountInfoResponse xmlns="urn:zimbraAdmin">
  <name>user1@cosmonaut.zimbra.com</name>
  <a n="zimbraId">decf3d72-623c-44d1-be34-23df4d285fb1</a>
  <a n="zimbraMailHost">cosmonaut.zimbra.com</a>
  <soapURL>http://server.zimbra.com:7070/service/soap/</soapURL>
  <adminSoapURL>https://server.zimbra.com:7071/service/admin/soap/</adminSoapURL>
</GetAccountInfoResponse>
$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>
  <id>decf3d72-623c-44d1-be34-23df4d285fb1</id>
  <name>user1@server.zimbra.com</name>
  <crumb>dace2c2c21df2009dc657b8f9e94b1cc</crumb>
  <lifetime>172799977</lifetime>
  <rest>http://server.zimbra.com:7070/home/user1</rest>
  <used>10775433</used>
  <prevSession>1211496468000</prevSession>

Search

$ 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>
  <c n="1" score="1.0" d="1211495060000" id="-525" f="u" sf="1211495060000">
    <su>Welcome to the Zimbra Collaboration Suite source!</su>

EmptyFolder

$ 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">
  <action>
    <op>empty</op>
    <id>1</id>
    <recursive>false</recursive>
  </action>
</FolderActionRequest>

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

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>
</DumpSessionsResponse>
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>
      </s>
    </zid>
    <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>
      </s>
    </zid>
  </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>
    </zid>
  </admin>
</DumpSessionsResponse>
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>
</DumpSessionsResponse>

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>
</DumpSessionsResponse>

GetSessionsRequest

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"/>
</GetSessionsResponse>

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>
  <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>
  </cn>

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>
</GetServerStatsResponse>

SearchDirectoryRequest

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.

COS

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=""

Currently, there is a zmsoap bug prohibiting the use of LDAP-style query strings on the command line. See bug 61862. Put the XML request in a file in a file if using a query string.

searchdirectory.request:

<SearchDirectoryRequest xmlns="urn:zimbraAdmin" offset="0" limit="25" sortBy="id" sortAscending="1" applyCos="false" applyConfig="false" attrs="cn,description" types="coses"><query>(|(cn=*default*))</query></SearchDirectoryRequest>
zmsoap -z -f searchdirectory.request
Domains
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=""
Accounts

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=""

SyncGalRequest

This request emulates the call made by the ZCO and ZDesktop clients for global address list sync. When issued against a server with a GAL sync account enabled, the result is an id list that can be used by a sync client to fetch contact fields with GetContactsRequest.

zmsoap -vv -m mailbox@domain.com -p thePassword -t account SyncGalRequest @idOnly="true"
    <SyncGalResponse>
      <cn id="59e3f5b1-6b61-4f7e-9166-ba631245d053:108287"/>
      <cn id="59e3f5b1-6b61-4f7e-9166-ba631245d053:108289"/>
    </SyncGalResponse>

59e3f5b1-6b61-4f7e-9166-ba631245d053 represents the zimbraId of the GAL sync account and 108289 represents the id of the contact in the account. mailbox@domain.com is any user account.

GetContactsRequest

A GetContactsRequest may be called by a sync client to resolve ids provided by SyncGalRequest.

zmsoap -vv -m mailbox@zimbra.com -p thePassword -t mail GetContactsRequest/cn @id="59e3f5b1-6b61-4f7e-9166-ba631245d053:108287"
<GetContactsResponse xmlns="urn:zimbraMail">
      <cn id="59e3f5b1-6b61-4f7e-9166-ba631245d053:108287" fileAsStr="Joe User" d="1314293590000" rev="1136194" l="59e3f5b1-6b61-4f7e-9166-ba631245d053:257">
        <a n="createTimeStamp">20110824064557.0Z</a>
        <a n="office">Ocean, LTL0045</a>
        <a n="lastName">User</a>
        <a n="workCity">San Francisco</a>
        <a n="objectClass">top</a>
        <a n="objectClass">person</a>
        <a n="objectClass">organizationalPerson</a>
        <a n="objectClass">user</a>
        <a n="photoFileName">joeuser.jpg</a>
        <a n="workPostalCode">94304</a>
        <a n="email">joe.user@domain.com</a>
        <a n="company">Domain Co.</a>
        <a n="fullName">Joe User</a>
        <a n="workState">CA</a>
        <a n="fileAs">8:Joe User</a>
        <a n="firstName">Joe</a>
        <a n="modifyTimeStamp">20110825155712.0Z</a>
        <a n="notes">Frank's 3rd staff engineer</a>
        <a n="jobTitle">Staff Engineer II</a>
      </cn>
    </GetContactsResponse>

SearchGalRequest

SearchGalRequest is used when searching the GAL or galsync account. See soap.txt for more attributes. The -m flag is the account to use when searching while the name element of the request specifies who to look for in the GAL.

zmsoap -z -t account -m peter.parker@domain.com SearchGalRequest @name=mary @type=account @domain=domain.com

<SearchGalResponse>
  <cn id="164d87e8-1cee-4d6d-9a14-fcce575b68b6:286" fileAsStr="Mary Jane Watson" d="1253926178000" rev="95" l="257" sf="1253926178000">
    <a n="createTimeStamp">20080513184733Z</a>
    <a n="lastName">Watson</a>
    <a n="workCity">New York</a>
    <a n="zimbraId">5960e2c4-af24-43bc-97c9-016c497b562f</a>
    <a n="objectClass">organizationalPerson</a>
    <a n="objectClass">zimbraAccount</a>
    <a n="objectClass">amavisAccount</a>
    <a n="email">mj@domain.com</a>
    <a n="fullName">Mary Jane Watson</a>
    <a n="workPhone">555-555-5555</a>
    <a n="modifyTimeStamp">20090411042723Z</a>
    <a n="fileAs">8:Mary Jane Watson</a>
    <a n="firstName">Mary Jane</a>
  </cn>
</SearchGalResponse>

Related

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

Verified Against: Zimbra Collaboration 7.0, 6.0 Date Created: 04/16/2014
Article ID: https://wiki.zimbra.com/index.php?title=Zmsoap Date Modified: 2015-07-13



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search