You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

2654 lines
113 KiB

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Service Administration</title>
<abstract>This document defines recommended best practices for service-level administration of servers and components using Ad-Hoc Commands.</abstract>
&LEGALNOTICE;
<number>0133</number>
<status>Active</status>
<type>Informational</type>
<sig>Standards</sig>
<dependencies>
<spec>RFC 6120</spec>
<spec>XEP-0050</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>admin</shortname>
&stpeter;
<revision>
<version>1.2</version>
<date>2017-07-15</date>
<initials>XEP Editor: ssw</initials>
<remark>Fix broken node value in example.</remark>
</revision>
<revision>
<version>1.1</version>
<date>2005-08-19</date>
<initials>psa</initials>
<remark>Added use cases for getting list of idle users and of active users (where online = active + idle), getting number (rather than list) of registered/disabled/online/active/idle users, getting list of disabled users, getting user statistics.</remark>
</revision>
<revision>
<version>1.0</version>
<date>2004-12-09</date>
<initials>psa</initials>
<remark>Per a vote of the Jabber Council, advanced status to Active.</remark>
</revision>
<revision>
<version>0.8</version>
<date>2004-12-06</date>
<initials>psa</initials>
<remark>Addressed Council feedback: folded add blacklist use case into edit blacklist use case; folded add whitelist use case into edit whitelist use case; changed jid-single to jid-multi in many of the use cases; added accountjid field to change password use case; removed grant administrative privileges and revoke administrative privileges use cases (need edit admin list use case only); added max_items field to get active users and get registered users use case.</remark>
</revision>
<revision>
<version>0.7</version>
<date>2004-12-02</date>
<initials>psa</initials>
<remark>Added use case for editing message of the day.</remark>
</revision>
<revision>
<version>0.6</version>
<date>2004-11-19</date>
<initials>psa</initials>
<remark>Further clarified message of the day per list discussion.</remark>
</revision>
<revision>
<version>0.5</version>
<date>2004-11-17</date>
<initials>psa</initials>
<remark>Changed firstname to given_name.</remark>
</revision>
<revision>
<version>0.4</version>
<date>2004-11-02</date>
<initials>psa</initials>
<remark>Added note clarifying concept of message of the day.</remark>
</revision>
<revision>
<version>0.3</version>
<date>2004-09-30</date>
<initials>psa</initials>
<remark>Changed command naming requirement from MUST to SHOULD.</remark>
</revision>
<revision>
<version>0.2</version>
<date>2004-07-22</date>
<initials>psa</initials>
<remark>Added several more use cases; defined complete protocol flows; specified XMPP Registrar considerations.</remark>
</revision>
<revision>
<version>0.1</version>
<date>2004-04-25</date>
<initials>psa</initials>
<remark>Initial version.</remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>There exists a set of common service-level tasks that administrators often need to perform in relation to Jabber/XMPP servers and components. Examples include creating users, disabling accounts, and blacklisting domains for inbound or outbound communications. Because such tasks can be performed with respect to a server or with respect to many kinds of add-on components (e.g., a text conferencing component that conforms to &xep0045;), it makes sense to define a generic protocol for such interactions. This document describes such a protocol by specifying a profile of &xep0050; and associated &xep0004; fields, rather than by defining a specialized and distinct protocol.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>This document addresses the following requirements:</p>
<ul>
<li>Enable users with appropriate privileges to perform common administrative tasks with respect to Jabber/XMPP servers and components.</li>
<li>Re-use existing XMPP and Jabber protocols wherever possible.</li>
</ul>
</section1>
<section1 topic='Discovery' anchor='disco'>
<p>A server or component MUST advertise any administrative commands it supports via &xep0030; (as described in <cite>XEP-0050: Ad-Hoc Commands</cite>); such commands exist as well-defined discovery nodes associated with the service in question.</p>
<p>In order to interact with a particular component attached to a server, an administrator needs to first discover that component and the commands it support, then send the appropriate command to the component itself. A server SHOULD NOT process commands on behalf of associated components, just as it does not handle service discovery requests on behalf of such components.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<p>This document defines a profile of <cite>XEP-0050: Ad-Hoc Commands</cite> that enables a service-level administrator to complete the following use cases:</p>
<ol>
<li>Add User</li>
<li>Delete User</li>
<li>Disable User</li>
<li>Re-Enable User</li>
<li>End User Session</li>
<li>Get User Password</li>
<li>Change User Password</li>
<li>Get User Roster</li>
<li>Get User Last Login Time</li>
<li>Get User Statistics</li>
<li>Edit Blacklist</li>
<li>Edit Whitelist</li>
<li>Get Number of Registered Users</li>
<li>Get Number of Disabled Users</li>
<li>Get Number of Online Users</li>
<li>Get Number of Active Users</li>
<li>Get Number of Idle Users</li>
<li>Get List of Registered Users</li>
<li>Get List of Disabled Users</li>
<li>Get List of Online Users</li>
<li>Get List of Active Users</li>
<li>Get List of Idle Users</li>
<li>Send Announcement to Active Users</li>
<li>Set Message of the Day</li>
<li>Edit Message of the Day</li>
<li>Delete Message of the Day</li>
<li>Set Welcome Message</li>
<li>Delete Welcome Message</li>
<li>Edit Admin List</li>
<li>Restart Service</li>
<li>Shut Down Service</li>
</ol>
<p>Naturally, not all of these use cases apply to all service types (e.g., adding a user may not apply to a multi-user chat service). An implementation or deployment MAY support any subset of the use cases defined herein. In addition, although this document aims to define common use cases, an implementation or deployment MAY support additional commands not defined herein, which may or may not be publicly registered.</p>
<p><em>Note:</em> The text that follows assumes that implementors have read and understood <cite>XEP-0050: Ad-Hoc Commands</cite> and <cite>XEP-0004: Data Forms</cite>.</p>
<section2 topic='Add User' anchor='add-user'>
<p>A user is defined as any entity that has a persistent relationship with a service (most commonly through the creation a registered account with the service) and whose account is in some sense hosted by the service. Adding a user MUST result in the creation of an account, along with any implementation-specific data for such an account (e.g., database entries or a roster file). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#add-user".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to Add a User'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='add-user-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#add-user'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Add User Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='add-user-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#add-user'
sessionid='add-user:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Adding a User</title>
<instructions>Fill out this form to add a user.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID for the account to be added'
type='jid-single'
var='accountjid'>
<required/>
</field>
<field label='The password for this account'
type='text-private'
var='password'/>
<field label='Retype password'
type='text-private'
var='password-verify'/>
<field label='Email address'
type='text-single'
var='email'/>
<field label='Given name'
type='text-single'
var='given_name'/>
<field label='Family name'
type='text-single'
var='surname'/>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Add User Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='add-user-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#add-user'
sessionid='add-user:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjid'>
<value>juliet@shakespeare.lit</value>
</field>
<field var='password'>
<value>R0m30</value>
</field>
<field var='password-verify'>
<value>R0m30</value>
</field>
<field var='email'>
<value>juliet@capulet.com</value>
</field>
<field var='given_name'>
<value>Juliet</value>
</field>
<field var='surname'>
<value>Capulet</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='add-user-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#add-user'
sessionid='add-user:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
<p>Notification of completion MAY include the processed data in a data form of type "result".</p>
</section2>
<section2 topic='Delete User' anchor='delete-user'>
<p>An administrator may need to permanently delete a user account. Deleting a user SHOULD result in the termination of any active sessions for the user and in the destruction of any implementation-specific data for the account (e.g., database entries or a roster file). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#delete-user".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to Delete a User'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='delete-user-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#delete-user'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Delete User Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='delete-user-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#delete-user'
sessionid='delete-user:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Deleting a User</title>
<instructions>Fill out this form to delete a user.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID(s) to delete'
type='jid-multi'
var='accountjids'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<p>Note: If the entity is an end user, the JID SHOULD be of the form &lt;user@host&gt;, not &lt;user@host/resource&gt;.</p>
<example caption='Admin Submits Delete User Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='delete-user-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#delete-user'
sessionid='delete-user:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjids'>
<value>juliet@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='delete-user-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#delete-user'
sessionid='delete-user:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Disable User' anchor='disable-user'>
<p>An administrator may need to temporarily disable a user account. Disabling a user MUST result in the termination of any active sessions for the user and in the prevention of further user logins until the account is re-enabled (this can be thought of as "banning" the user). However, it MUST NOT result in the destruction of any implementation-specific data for the account (e.g., database entries or a roster file). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#disable-user".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to Disable a User'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='disable-user-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#disable-user'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Disable User Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='disable-user-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#disable-user'
sessionid='disable-user:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Disabling a User</title>
<instructions>Fill out this form to disable a user.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID(s) to disable'
type='jid-multi'
var='accountjids'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<p>Note: If the entity is an end user, the JID SHOULD be of the form &lt;user@host&gt;, not &lt;user@host/resource&gt;.</p>
<example caption='Admin Submits Disable User Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='disable-user-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#disable-user'
sessionid='disable-user:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjids'>
<value>juliet@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='disable-user-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#disable-user'
sessionid='disable-user:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Re-Enable User' anchor='reenable-user'>
<p>An administrator may need to re-enable a user account that had been temporarily disabled. Re-enabling a user MUST result in granting the user the ability to access the service again. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#reenable-user".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to Re-Enable a User'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='reenable-user-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#reenable-user'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Re-Enable User Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='reenable-user-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#reenable-user'
sessionid='reenable-user:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Re-Enable a User</title>
<instructions>Fill out this form to re-enable a user.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID(s) to re-enable'
type='jid-multi'
var='accountjids'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<p>Note: If the entity is an end user, the JID SHOULD be of the form &lt;user@host&gt;, not &lt;user@host/resource&gt;.</p>
<example caption='Admin Submits Re-Enable User Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='reenable-user-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#reenable-user'
sessionid='reenable-user:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjids'>
<value>juliet@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='reenable-user-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#reenable-user'
sessionid='reenable-user:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='End User Session' anchor='end-user-session'>
<p>An administrator may need to terminate one or all of the user's current sessions, but allow future logins (this can be thought of as "kicking" rather than "banning" the user). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#end-user-session".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to End a User&apos;s Session'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='end-user-session-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#end-user-session'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns End User Session Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='end-user-session-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#end-user-session'
sessionid='end-user-session:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Ending a User Session</title>
<instructions>Fill out this form to end a user&apos;s session.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID(s) for which to end sessions'
type='jid-multi'
var='accountjids'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<p>Note: If the JID is of the form &lt;user@host&gt;, the service MUST end all of the user's sessions; if the JID is of the form &lt;user@host/resource&gt;, the service MUST end only the session associated with that resource.</p>
<example caption='Admin Submits End User Session Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='end-user-session-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#end-user-session'
sessionid='end-user-session:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjids'>
<value>juliet@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='end-user-session-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#end-user-session'
sessionid='end-user-session:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Get User Password' anchor='get-user-password'>
<p>An administrator may need to retrieve a user's password. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-user-password".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to Get a User&apos;s Password'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-user-password-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#get-user-password'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Get User Password Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='get-user-password-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-password'
sessionid='get-user-password:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Getting a User's Password</title>
<instructions>Fill out this form to get a user&apos;s password.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID for which to retrieve the password'
type='jid-single'
var='accountjid'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<p>Note: If the entity is an end user, the JID SHOULD be of the form &lt;user@host&gt;, not &lt;user@host/resource&gt;.</p>
<example caption='Admin Submits Get User Password Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-user-password-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-password'
sessionid='get-user-password:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjid'>
<value>juliet@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>Naturally, the data form included in the IQ result will include the user's password.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-user-password-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-password'
sessionid='get-user-password:20040408T0337Z'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjid'>
<value>juliet@shakespeare.lit</value>
</field>
<field var='password'>
<value>R0m30</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Change User Password' anchor='change-user-password'>
<p>An administrator may need to change a user's password. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#change-user-password".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to Change a User&apos;s Password'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='change-user-password-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#change-user-password'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Change User Password Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='change-user-password-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#change-user-password'
sessionid='change-user-password:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Changing a User Password</title>
<instructions>Fill out this form to change a user&apos;s password.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID for this account'
type='jid-single'
var='accountjid'>
<required/>
</field>
<field label='The password for this account'
type='text-private'
var='password'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<p>Note: If the entity is an end user, the JID SHOULD be of the form &lt;user@host&gt;, not &lt;user@host/resource&gt;.</p>
<example caption='Admin Submits Change User Password Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='change-user-password-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#change-user-password'
sessionid='change-user-password:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjid'>
<value>juliet@shakespeare.lit</value>
</field>
<field var='password'>
<value>V3r0n4</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='change-user-password-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#change-user-password'
sessionid='change-user-password:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Get User Roster' anchor='get-user-roster'>
<p>An administrator may need to retrieve a user's roster (e.g., to help verify the user's ownership of the account before reminding the user of the password). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-user-roster".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to Get a User&apos;s Roster'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-user-roster-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#get-user-roster'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Get User Roster Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='get-user-roster-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-roster'
sessionid='get-user-roster:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Getting a User's Roster</title>
<instructions>Fill out this form to get a user&apos;s roster.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID(s) for which to retrieve the roster'
type='jid-multi'
var='accountjids'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<p>Note: If the entity is an end user, the JID SHOULD be of the form &lt;user@host&gt;, not &lt;user@host/resource&gt;.</p>
<example caption='Admin Submits Get User Roster Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-user-roster-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-roster'
sessionid='get-user-roster:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjids'>
<value>juliet@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The data form included in the IQ result will include the user's roster, formatted according to the 'jabber:iq:roster' protocol defined in &xmppim;.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-user-roster-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-roster'
sessionid='get-user-roster:20040408T0337Z'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjids'>
<value>juliet@shakespeare.lit</value>
</field>
<query xmlns='jabber:iq:roster'>
<item jid='romeo@example.net'
name='Romeo'
subscription='both'>
<group>Friends</group>
<group>Lovers</group>
</item>
<item jid='mercutio@example.org'
name='Mercutio'
subscription='from'>
<group>Friends</group>
</item>
<item jid='benvolio@example.org'
name='Benvolio'
subscription='both'>
<group>Friends</group>
</item>
</query>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Get User Last Login Time' anchor='get-user-lastlogin'>
<p>An administrator may need to retrieve a user's last login time (e.g., to help verify the user's ownership of the account before reminding the user of the password). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-user-lastlogin".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests to Get a User&apos;s Roster'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-user-lastlogin-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#get-user-lastlogin'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form.</p>
<example caption='Service Returns Get User Last Login Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='get-user-lastlogin-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-lastlogin'
sessionid='get-user-lastlogin:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Getting a User's Last Login Time</title>
<instructions>Fill out this form to get a user&apos;s last login time.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID(s) for which to retrieve the last login time'
type='jid-multi'
var='accountjids'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<p>Note: If the entity is an end user, the JID SHOULD be of the form &lt;user@host&gt;, not &lt;user@host/resource&gt;.</p>
<example caption='Admin Submits Get User Last Login Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-user-lastlogin-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-lastlogin'
sessionid='get-user-lastlogin:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjids'>
<value>juliet@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The data form included in the IQ result will include the user's last login time (which SHOULD conform to the DateTime profile specified in &xep0082;).</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-user-lastlogin-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-user-lastlogin'
sessionid='get-user-lastlogin:20040408T0337Z'
status='completed'>
<x xmlns='jabber:x:data' type='result'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='accountjids'>
<value>juliet@shakespeare.lit</value>
</field>
<field var='lastlogin'>
<value>2003-12-19T17:58:35Z</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Get User Statistics' anchor='get-user-stats'>
<p>An administrator may want to gather statistics about a particular user's interaction with the service (roster size, bandwidth usage, logins, IP address, etc.). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#user-stats".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests User Statistics'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='user-stats-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#user-stats'/>
</iq>