Zmsoap: Difference between revisions
No edit summary |
No edit summary |
||
(31 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
==Intro== | {{BC|Community Sandbox}} | ||
__FORCETOC__ | |||
<div class="col-md-12 ibox-content"> | |||
=Zmsoap= | |||
{{KB|{{Unsupported}}|{{ZCS 7.0}}|{{ZCS 6.0}}|}} | |||
{{WIP}}==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. | 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+ | |||
<pre> | <pre> | ||
$ zmsoap --help | $ zmsoap --help | ||
Line 26: | Line 33: | ||
--type (-t) type SOAP request type (mail, account, admin). | --type (-t) type SOAP request type (mail, account, admin). | ||
Default is admin. | Default is admin. | ||
--url (-u) http[s]://... Server hostname and optional port. | --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 | --verbose (-v) Print the SOAP request and other status | ||
information. | information. | ||
Line 32: | Line 42: | ||
follows XPath syntax: | follows XPath syntax: | ||
[/]element1[/element2][/@attr][=value]. | [/]element1[/element2][/@attr][=value]. | ||
</pre> | |||
===ZCS 6.0=== | |||
In 6.0 D2 -e is removed, and the following is added: | |||
<pre> | |||
--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. | |||
</pre> | |||
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. | |||
[http://files.zimbra.com/docs/soap_api/8.0/soapapi-zimbra-doc/api-reference/index.html ZCS8 SOAP API Reference] | |||
==ZCS8 Examples== | |||
====GetLoggerStatsRequest==== | |||
[http://files.zimbra.com/docs/soap_api/8.0/soapapi-zimbra-doc/api-reference/zimbraAdmin/GetLoggerStats.html SOAP API reference] | |||
=====Stat groups===== | |||
Dumps available stat groups for the specified server. | |||
<pre>zmsoap -z GetLoggerStatsRequest/hostname @hn="mbs1.zmb.moc"</pre> | |||
=====Stat names===== | |||
Dump available stat names for a specified stat group name. | |||
<pre>zmsoap -z GetLoggerStatsRequest/hostname @hn="mbs1.zmb.moc" ../stats=1 @name="mysql.csv"</pre> | |||
If the command results in | |||
<pre> | |||
Exception in thread "main" java.lang.OutOfMemoryError: Java heap space | |||
</pre> | |||
then increase the heap space available to zmjava in localconfig. | |||
Check the current value | |||
<pre>zmlocalconfig zimbra_zmjava_options | |||
zimbra_zmjava_options = -Xmx256m -Djava.net.preferIPv4Stack=true | |||
</pre> | |||
Set the new value | |||
<pre>zmlocalconfig -e zimbra_zmjava_options="-Xmx512m -Djava.net.preferIPv4Stack=true"</pre> | |||
=====MySQL uptime===== | |||
Dump MySQL uptime statistics from mailbox host mbs1.zmb.moc. | |||
SOAP request for MySQL uptime: | |||
<pre> | |||
<GetLoggerStatsRequest xmlns="urn:zimbraAdmin"> | |||
<hostname hn="mbs1.zmb.moc"/> | |||
<stats name="mysql.csv"> | |||
<values> | |||
<stat name="Uptime"/> | |||
</values> | |||
</stats> | |||
</GetLoggerStatsRequest> | |||
</pre> | |||
To construct the zmsoap command, work from the deepest elements and attributes in the request to formulate the XPath from left to right. | |||
<pre>zmsoap -z GetLoggerStatsRequest/hostname @hn="mbs1.zmb.moc" ../stats/values/stat @name="Uptime" ../../@name="mysql.csv" | |||
</pre> | </pre> | ||
==Examples== | ==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. | |||
<pre> | |||
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"/> | |||
</pre> | |||
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. | |||
<pre> | |||
zmsoap -z GetGrantsRequest/grantee=user1@zmb.moc @type=usr @by=name @all=1 | |||
</pre> | |||
Attributes '''''type''''', '''''by''''' and '''''all''''' are required for this request. If '''''grantee''''' does not have grants, then you will see this error: | |||
<pre> | |||
ERROR: service.INVALID_REQUEST (invalid request: invalid grantee) | |||
</pre> | |||
=====Target===== | |||
Dump grants for a specified target COS: | |||
<pre> | |||
zmsoap -z GetGrantsRequest/target=e00428a1-0c00-11d9-836a-000d93afea2a @type=cos @by=id | |||
</pre> | |||
See ''/opt/zimbra/doc/soap-right.txt'' for more options. | |||
====GetAccountInfo==== | ====GetAccountInfo==== | ||
Line 53: | Line 155: | ||
<adminSoapURL>https://server.zimbra.com:7071/service/admin/soap/</adminSoapURL> | <adminSoapURL>https://server.zimbra.com:7071/service/admin/soap/</adminSoapURL> | ||
</GetAccountInfoResponse> | </GetAccountInfoResponse> | ||
</pre> | |||
<pre> | |||
$zmsoap -z -t account -m user@domain.com -v GetInfoRequest | |||
</pre> | |||
<pre> | |||
$ zmsoap -m user1 -p test123 -u http://localhost:7070/service/soap --type account GetInfoRequest | head | $ zmsoap -m user1 -p test123 -u http://localhost:7070/service/soap --type account GetInfoRequest | head | ||
Line 119: | Line 226: | ||
====Active Server Sessions With DumpSessionsRequest==== | ====Active Server Sessions With DumpSessionsRequest==== | ||
Dump login sessions from one server | =====Dump login sessions from one server===== | ||
<pre> | <pre> | ||
$ zmsoap -z -t admin -v DumpSessionsRequest | $ zmsoap -z -t admin -v DumpSessionsRequest | ||
Line 132: | Line 239: | ||
</pre> | </pre> | ||
Dump login sessions by account | =====Dump login sessions by account===== | ||
<pre> | <pre> | ||
$ zmsoap -z -t admin -v -e DumpSessionsRequest @groupByAccount=1 @listSessions=1 | $ 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 | Sending admin auth request to https://localhost:7071/service/admin/soap | ||
Line 164: | Line 273: | ||
</pre> | </pre> | ||
Dump login sessions from ServerA and ServerB simultaneously | =====Dump login sessions from ServerA and ServerB simultaneously===== | ||
<pre> | <pre> | ||
$ echo -e "\nServer A $(date)"; zmsoap -z -t admin DumpSessionsRequest && \ | $ echo -e "\nServer A $(date)"; zmsoap -z -t admin DumpSessionsRequest && \ | ||
Line 184: | Line 293: | ||
</pre> | </pre> | ||
== | ====GetSessionsRequest==== | ||
[[ | <pre> | ||
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> | |||
</pre> | |||
====Check Account for Licensed Features==== | |||
Feature attribute can be any one of mapi, mobileSync or iSync. | |||
<pre> | |||
zmsoap -z -t account -m admin@zmb.moc -e CheckLicenseRequest feature=mapi | |||
CheckLicenseResponse xmlns="urn:zimbraAccount" status="ok"></CheckLicenseResponse> | |||
</pre> | |||
====Test GAL Auto-Complete==== | |||
<pre> | |||
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> | |||
</pre> | |||
====As a user==== | |||
<pre> | |||
zmsoap -a user@domain.com -p thePassword AutoCompleteGalRequest @name="name" @domain="domain.com" @limit="20" @type="resource" | |||
</pre> | |||
====Clear mailbox ranking table==== | |||
<pre> | |||
zmsoap -z -m user RankingActionRequest/action @op=reset | |||
</pre> | |||
====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===== | |||
<pre> | |||
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> | |||
... | |||
</pre> | |||
=====Specific counters===== | |||
<pre> | |||
zmsoap -z -t admin GetServerStatsRequest/stat @name=heap_used | |||
<GetServerStatsResponse xmlns="urn:zimbraAdmin"> | |||
<stat name="heap_used">428914224</stat> | |||
</GetServerStatsResponse> | |||
</pre> | |||
====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. | |||
<pre> | |||
zmsoap -z -v SearchDirectoryRequest @offset="0" @limit="25" @sortBy="id" @sortAscending="1" @applyCos="false" @applyConfig="false" @attrs="cn,description" @types="coses" query="" | |||
</pre> | |||
Currently, there is a zmsoap bug prohibiting the use of LDAP-style query strings on the command line. See bug [https://bugzilla.zimbra.com/show_bug.cgi?id=61862 61862]. Put the XML request in a file in a file if using a query string. | |||
'''searchdirectory.request:''' | |||
<pre><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></pre> | |||
<pre>zmsoap -z -f searchdirectory.request</pre> | |||
=====Domains===== | |||
<pre> | |||
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="" | |||
</pre> | |||
=====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 [https://bugzilla.zimbra.com/show_bug.cgi?id=60379 60379] and [https://bugzilla.zimbra.com/show_bug.cgi?id=60382 60382]. | |||
<pre> | |||
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="" | |||
</pre> | |||
====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. | |||
<pre> | |||
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> | |||
</pre> | |||
''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. | |||
<pre> | |||
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> | |||
</pre> | |||
====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. | |||
<pre> | |||
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> | |||
</pre> | |||
==Related== | |||
[[zmmailbox]] uses refined syntax & is the typical admin tool along with [[zmprov]] | |||
{{Article Footer|Zimbra Collaboration 7.0, 6.0|04/16/2014}} | |||
[[Category:Command Line Interface]] | [[Category:Command Line Interface]] |
Latest revision as of 15:18, 13 July 2015
Zmsoap
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 Examples
GetLoggerStatsRequest
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