Zmsoap

Revision as of 20:55, 12 October 2010 by Jason (talk | contribs)
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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.

Examples

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

Related

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

Jump to: navigation, search