moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-12-22 23:58:51 -05:00
Code Issues Releases Wiki Activity
f99316c129
xeps/xep-0133.xml
Sam Whited af6aa0d6d0 0133: fix broken node in example
2017-07-15 17:16:12 -05:00

2654 lines
113 KiB
XML
Raw Blame History

<?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>
]]></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 User Statistics Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='user-stats-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#user-stats'
sessionid='user-stats:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Get User Statistics</title>
<instructions>Fill out this form to gather user statistics.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The Jabber ID for statistics'
type='jid-single'
var='accountjid'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits User Statistics Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='user-stats-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#user-stats'
sessionid='user-stats: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>iago@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='user-stats-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#user-stats'
sessionid='user-stats: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='ipaddresses'>
<value>127.0.0.1</value>
</field>
<field var='rostersize'>
<value>123</value>
</field>
<field var='onlineresources'>
<value>work</value>
<value>home</value>
</field>
<field var='stanzaspersecond'>
<value>3</value>
</field>
<field var='loginsperminute'>
<value>0.1</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Edit Blacklist' anchor='edit-blacklist'>
<p>The service may enable an administrator to define one or more service-wide blacklists (lists of entities that are blocked from communications to or from the service). For example, a multi-user chat service may forbid a certain user from joining any room on the service, or may block entire domains from accessing the service. An entity specified on the blacklist MAY be a JID of any form as specified in &rfc6120;; the order of JID matching SHOULD be that specified for privacy lists in &xep0016;.</p>
<p>A blacklist may prevent inbound communications, outbound communications, or both; whether to offer only bidirectional blocking or a more granular choice of inbound or outbound blocking is a matter of implementation or deployment policy. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#edit-blacklist" if blocking is bidirectional as shown below; "http://jabber.org/protocol/admin#add-to-blacklist-in" for inbound blocking only; and "http://jabber.org/protocol/admin#add-to-blacklist-out" for outbound blocking only.</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Editing of Blacklist'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='edit-blacklist-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#edit-blacklist'/>
</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 Edit Blacklist Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='edit-blacklist-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-blacklist'
sessionid='edit-blacklist:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Editing the Blacklist</title>
<instructions>
Fill out this form to edit the list of entities with whom
communications are disallowed.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The blacklist'
var='blacklistjids'>
<value>marlowe.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Edit Blacklist Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='edit-blacklist-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-blacklist'
sessionid='edit-blacklist:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='blacklistjids'>
<value>denmark.lit</value>
<value>france.lit</value>
<value>marlowe.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='edit-blacklist-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-blacklist'
sessionid='edit-blacklist:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Edit Whitelist' anchor='edit-whitelist'>
<p>The service may enable an administrator to define one or more service-wide whitelists (lists of entities that are allowed to communicate the service). For example, a publish-subscribe may allow only a select list of users to publish or subscribe to nodes hosted on the service. An entity added to a whitelist MAY be a JID of any form as specified in <cite>RFC 6120</cite>; the order of JID matching SHOULD be that specified for privacy lists in &xep0016;.</p>
<p>As with blacklists, a whitelist may prevent inbound communications, outbound communications, or both; whether to offer only bidirectional blocking or a more granular choice of inbound or outbound blocking is a matter of implementation or deployment policy. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#add-to-whitelist" if blocking is bidirectional; "http://jabber.org/protocol/admin#add-to-whitelist-in" for inbound blocking only; and "http://jabber.org/protocol/admin#add-to-whitelist-out" for outbound blocking only.</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Editing of Whitelist'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='edit-whitelist-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#edit-whitelist'/>
</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 Edit Whitelist Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='edit-whitelist-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-whitelist'
sessionid='edit-whitelist:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Editing the Whitelist</title>
<instructions>
Fill out this form to edit the list of entities with whom
communications are allowed.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The whitelist'
var='whitelistjids'>
<value>capulet.com</value>
<value>denmark.lit</value>
<value>england.lit</value>
<value>montague.net</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Edit Whitelist Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='edit-whitelist-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-whitelist'
sessionid='edit-whitelist:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='whitelistjids'>
<value>capulet.com</value>
<value>england.lit</value>
<value>montague.net</value>
<value>verona.it</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='edit-whitelist-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-whitelist'
sessionid='edit-whitelist:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Get Number of Registered Users' anchor='get-registered-users-num'>
<p>It may be helpful to enable an administrator to retrieve the number of registered users. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-registered-users-num".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Number of Registered Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-registered-users-num-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-registered-users-num'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD simply return the number of registered users.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-registered-users-num-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-registered-users-num'
sessionid='get-registered-users-num:20040408T0337Z'
status='completed'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The number of registered users'
var='registeredusersnum'>
<value>123</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Get Number of Disabled Users' anchor='get-disabled-users-num'>
<p>Given that admins may be able to disable user accounts, it may be helpful to enable an administrator to retrieve the number of disabled users. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-disabled-users-num".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Number of Disabled Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-disabled-users-num-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-disabled-users-num'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD simply return the number of disabled users.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-disabled-users-num-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-disabled-users-num'
sessionid='get-disabled-users-num:20040408T0337Z'
status='completed'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The number of disabled users'
var='disabledusersnum'>
<value>123</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Get Number of Online Users' anchor='get-online-users-num'>
<p>It may be helpful to enable an administrator to retrieve the number of registered users who are online at any one moment. By "online user" is meant any user or account that currently has at least one connected or available resource as specified in <cite>RFC 6120</cite> and <cite>RFC 6121</cite>, whether that user is actively sending XML stanzas or is idle. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-online-users-num".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Number of Online Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-online-users-num-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-online-users-num'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD simply return the number of online users.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-online-users-num-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-online-users-num'
sessionid='get-online-users-num: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 label='The number of online users'
var='onlineusersnum'>
<value>79</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Get Number of Active Users' anchor='get-active-users-num'>
<p>Some services may distinguish users who are online and actively using the service from users who are online but idle. Therefore it may be helpful to enable an administrator to retrieve the number of online users who are active at any one moment. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-active-users-num".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Number of Active Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-active-users-num-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-active-users-num'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD simply return the number of active users.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-active-users-num-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-active-users-num'
sessionid='get-online-users-num: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 label='The number of active users'
var='activeusersnum'>
<value>66</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Get Number of Idle Users' anchor='get-idle-users-num'>
<p>Some services may distinguish users who are online and actively using the service from users who are online but idle. Therefore it may be helpful to enable an administrator to retrieve the number of online users who are idle at any one moment. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-idle-users-num".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Number of Idle Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-idle-users-num-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-idle-users-num'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD simply return the number of idle users.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-idle-users-num-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-idle-users-num'
sessionid='get-online-users-num: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 label='The number of idle users'
var='idleusersnum'>
<value>13</value>
</field>
</x>
</command>
</iq>
]]></example>
</section2>
<section2 topic='Get List of Registered Users' anchor='get-registered-users-list'>
<p>On a server or service without many registered users, it may be helpful to enable an administrator to retrieve a list of all registered users. The service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-registered-users-list".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Registered Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-registered-users-list-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-registered-users-list'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD do one of the following:</p>
<ol>
<li>If there are not many registered users, the service MAY simply return the list of registered users.</li>
<li>However, the service MAY also return a form so that the admin can specify more detailed information about the search (e.g., number of users to show).</li>
</ol>
<example caption='Service Returns Get Registered Users Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='get-registered-users-list-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-registered-users-list'
sessionid='get-registered-users-list:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Requesting List of Registered Users</title>
<instructions>
Fill out this form to request the registered users
of this service.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Maximum number of items to show'
type='list-single'
var='max_items'>
<option label='25'><value>25</value></option>
<option label='50'><value>50</value></option>
<option label='75'><value>75</value></option>
<option label='100'><value>100</value></option>
<option label='150'><value>150</value></option>
<option label='200'><value>200</value></option>
<option label='None'><value>none</value></option>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Get Registered Users Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-registered-users-list-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-registered-users-list'
sessionid='get-registered-users-list:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='max_items'>
<value>100</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-registered-users-list-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-registered-users-list'
sessionid='get-registered-users:20040408T0337Z'
status='completed'>
<x xmlns='jabber:x:data' type='form'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The list of all users'
var='registereduserjids'>
<value>bernardo@shakespeare.lit</value>
<value>bard@shakespeare.lit</value>
<value>cordelia@shakespeare.lit</value>
<value>crone1@shakespeare.lit</value>
<value>emilia@shakespeare.lit</value>
<value>francisco@shakespeare.lit</value>
<value>goneril@shakespeare.lit</value>
<value>hag66@shakespeare.lit</value>
<value>hecate@shakespeare.lit</value>
<value>iago@shakespeare.lit</value>
<value>kingclaudius@shakespeare.lit</value>
<value>kinglear@shakespeare.lit</value>
<value>laertes@shakespeare.lit</value>
<value>macbeth@shakespeare.li</value>
<value>mercutio@shakespeare.lit</value>
<value>nestor@shakespeare.lit</value>
<value>northumberland@shakespeare.lit</value>
<value>painter@shakespeare.lit</value>
<value>regan@shakespeare.lit</value>
<value>timon@shakespeare.lit</value>
<value>wiccarocks@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2>
<section2 topic='Get List of Disabled Users' anchor='get-disabled-users-list'>
<p>It may be helpful to enable an administrator to retrieve a list of all disabled users. The service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-disabled-users-list".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Disabled Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-disabled-users-list-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-disabled-users-list'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD do one of the following:</p>
<ol>
<li>If there are not many disabled users, the service MAY simply return the list of disabled users.</li>
<li>However, the service MAY also return a form so that the admin can specify more detailed information about the search (e.g., number of users to show).</li>
</ol>
<example caption='Service Returns Get Disabled Users Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='get-disabled-users-list-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-disabled-users-list'
sessionid='get-disabled-users-list:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Requesting List of Disabled Users</title>
<instructions>
Fill out this form to request the disabled users
of this service.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Maximum number of items to show'
type='list-single'
var='max_items'>
<option label='25'><value>25</value></option>
<option label='50'><value>50</value></option>
<option label='75'><value>75</value></option>
<option label='100'><value>100</value></option>
<option label='150'><value>150</value></option>
<option label='200'><value>200</value></option>
<option label='None'><value>none</value></option>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Get Disabled Users Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-disabled-users-list-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-disabled-users-list'
sessionid='get-disabled-users-list:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='max_items'>
<value>100</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-disabled-users-list-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-disabled-users-list'
sessionid='get-disabled-users: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 label='The list of all disabled users'
var='disableduserjids'>
<value>bernardo@shakespeare.lit</value>
<value>iago@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2>
<section2 topic='Get List of Online Users' anchor='get-online-users-list'>
<p>It may be helpful to enable an administrator to retrieve a list of all online users. Because the number of online users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-online-users-list".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Online Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-online-users-list-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-online-users-list'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD do one of the following:</p>
<ol>
<li>If there are not many online users, the service MAY simply return the list of online users.</li>
<li>However, the service MAY also return a form so that the admin can specify more detailed information about the search (e.g., number of users to show).</li>
</ol>
<example caption='Service Returns Get Online Users Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='get-online-users-list-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-online-users-list'
sessionid='get-online-users-list:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Requesting List of Online Users</title>
<instructions>
Fill out this form to request the online users
of this service.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Maximum number of items to show'
type='list-single'
var='max_items'>
<option label='25'><value>25</value></option>
<option label='50'><value>50</value></option>
<option label='75'><value>75</value></option>
<option label='100'><value>100</value></option>
<option label='150'><value>150</value></option>
<option label='200'><value>200</value></option>
<option label='None'><value>none</value></option>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Get Online Users Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-online-users-list-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-online-users-list'
sessionid='get-online-users-list:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='max_items'>
<value>100</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-online-users-list-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-online-users-list'
sessionid='get-online-users: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 label='The list of all online users'
var='onlineuserjids'>
<value>bard@shakespeare.lit</value>
<value>cordelia@shakespeare.lit</value>
<value>crone1@shakespeare.lit</value>
<value>goneril@shakespeare.lit</value>
<value>hag66@shakespeare.lit</value>
<value>hecate@shakespeare.lit</value>
<value>kinglear@shakespeare.lit</value>
<value>macbeth@shakespeare.li</value>
<value>mercutio@shakespeare.lit</value>
<value>northumberland@shakespeare.lit</value>
<value>painter@shakespeare.lit</value>
<value>wiccarocks@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2>
<section2 topic='Get List of Active Users' anchor='get-active-users-list'>
<p>It may be helpful to enable an administrator to retrieve a list of all active users. Because the number of active users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-active-users".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Active Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-active-users-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-active-users'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD do one of the following:</p>
<ol>
<li>If there are not many active users, the service MAY simply return the list of active users.</li>
<li>However, the service MAY also return a form so that the admin can specify more detailed information about the search (e.g., number of users to show).</li>
</ol>
<example caption='Service Returns Get Active Users Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='get-active-users-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-active-users'
sessionid='get-active-users:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Requesting List of Active Users</title>
<instructions>
Fill out this form to request the active users
of this service.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Maximum number of items to show'
type='list-single'
var='max_items'>
<option label='25'><value>25</value></option>
<option label='50'><value>50</value></option>
<option label='75'><value>75</value></option>
<option label='100'><value>100</value></option>
<option label='150'><value>150</value></option>
<option label='200'><value>200</value></option>
<option label='None'><value>none</value></option>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Get Active Users Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-active-users-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-active-users'
sessionid='get-active-users:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='max_items'>
<value>100</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-active-users-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-active-users'
sessionid='get-active-users: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 label='The list of active users'
var='activeuserjids'>
<value>bard@shakespeare.lit</value>
<value>crone1@shakespeare.lit</value>
<value>hag66@shakespeare.lit</value>
<value>hecate@shakespeare.lit</value>
<value>wiccarocks@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2>
<section2 topic='Get List of Idle Users' anchor='get-idle-users-list'>
<p>It may be helpful to enable an administrator to retrieve a list of all idle users. Because the number of idle users may be quite large, the service may need to truncate the result-set, since it could be quite large (however, any ability to limit or page through the result-set is outside the scope of this document). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-idle-users".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests List of Active Users'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-idle-users-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-idle-users'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD do one of the following:</p>
<ol>
<li>If there are not many idle users, the service MAY simply return the list of idle users.</li>
<li>However, the service MAY also return a form so that the admin can specify more detailed information about the search (e.g., number of users to show).</li>
</ol>
<example caption='Service Returns Get Idle Users Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='get-idle-users-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-idle-users'
sessionid='get-idle-users:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Requesting List of Active Users</title>
<instructions>
Fill out this form to request the idle users
of this service.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Maximum number of items to show'
type='list-single'
var='max_items'>
<option label='25'><value>25</value></option>
<option label='50'><value>50</value></option>
<option label='75'><value>75</value></option>
<option label='100'><value>100</value></option>
<option label='150'><value>150</value></option>
<option label='200'><value>200</value></option>
<option label='None'><value>none</value></option>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Get Idle Users Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='get-idle-users-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#get-idle-users'
sessionid='get-idle-users:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='max_items'>
<value>100</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='get-idle-users-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-idle-users'
sessionid='get-active-users: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 label='The list of idle users'
var='activeuserjids'>
<value>cordelia@shakespeare.lit</value>
<value>goneril@shakespeare.lit</value>
<value>kinglear@shakespeare.lit</value>
<value>macbeth@shakespeare.li</value>
<value>mercutio@shakespeare.lit</value>
<value>northumberland@shakespeare.lit</value>
<value>painter@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<p>The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.</p>
<p>The service MAY specify additional fields that restrict the scope of the user list (e.g., regular expression matching for Jabber IDs), and such fields MAY be registered in the future with the XMPP Registrar; however, such fields are not defined herein.</p>
</section2>
<section2 topic='Send Announcement to Online Users' anchor='announce'>
<p>Administrators of some existing Jabber servers have found it useful to be able to send an announcement to all online users of the server (e.g., to announce a server shutdown); this concept can be extended to any service (such as a multi-user chat service or a gateway to a foreign IM service). The message shall be sent only to users who currently have a "session" with the service. Obviously there may be latency in sending the message if the number of active users is extremely large. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#announce".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Announcement'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='announce-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#announce'/>
</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 Announce Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='announce-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#announce'
sessionid='announce:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Making an Announcement</title>
<instructions>
Fill out this form to make an announcement to all
active users of this service.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Announcement'
type='text-multi'
var='announcement'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Announce Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='announce-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#announce'
sessionid='announce:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='announcement'>
<value>Attention! This service will be going down for</value>
<value>maintenance in 2 minutes. Please log off now!</value>
<value>We apologize for the inconvenience.</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='announce-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#announce'
sessionid='announce:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Set Message of the Day' anchor='set-motd'>
<p>Administrators of some existing Jabber servers have found it useful to be able to send a "message of the day" that is delivered to any user who logs in to the server that day (e.g., to announce service changes);
<note>Typically, a "message of the day" is an announcement that is sent once to all users of a server or a service until and unless the message is deleted; it can be thought of as a "standing announcement" as opposed to the "one-time announcement" sent to all online users in the previous use cases. The announcement is sent immediately to users who are online when the message is set, or after the next session initiation for other users (e.g., on server login or chatroom join).</note>
this concept can be extended to any service (such as a multi-user chat service or a gateway to a foreign IM service). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#set-motd".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Sets Message of the Day'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='set-motd-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#set-motd'/>
</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 MOTD Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='set-motd-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#set-motd'
sessionid='set-motd:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Setting the Message of the Day</title>
<instructions>
Fill out this form to set the message of the day.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Message of the Day'
type='text-multi'
var='motd'>
<required/>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits MOTD Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='set-motd-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#set-motd'
sessionid='set-motd:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='motd'>
<value>Don&apos;t forget: the grand re-opening of the</value>
<value>Globe Theatre will occur tomorrow night.</value>
<value>The festivities will begin right after tea</value>
<value>and extend far into the night. Don&apos;t miss it!</value>
<value>--The Globe Staff</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='set-motd-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#set-motd'
sessionid='set-motd:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Edit Message of the Day' anchor='edit-motd'>
<p>After setting a message of the day, an administrator may want to edit that message (e.g., in order to correct an error). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#edit-motd".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Edits Message of the Day'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='edit-motd-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#edit-motd'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form, which SHOULD include the current message of the day if one has already been set.</p>
<example caption='Service Returns MOTD Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='edit-motd-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-motd'
sessionid='edit-motd:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Editing the Message of the Day</title>
<instructions>
Fill out this form to edit the message of the day.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Message of the Day'
type='text-multi'
var='motd'>
<required/>
<value>Don&apos;t forget: the grand re-opening of the</value>
<value>Globe Theatre will occur tomorrow night.</value>
<value>The festivities will begin right after tea</value>
<value>and extend far into the night. Don&apos;t miss it!</value>
<value>--The Globe Stuff</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits MOTD Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='edit-motd-2'
to='shakespeare.lit'
type='edit'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-motd'
sessionid='edit-motd:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='motd'>
<value>Don&apos;t forget: the grand re-opening of the</value>
<value>Globe Theatre will occur tomorrow night.</value>
<value>The festivities will begin right after tea</value>
<value>and extend far into the night. Don&apos;t miss it!</value>
<value>--The Globe Staff</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='edit-motd-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-motd'
sessionid='edit-motd:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Delete Message of the Day' anchor='delete-motd'>
<p>Sometimes a previously-set "message of the day" is no longer appropriate and needs to be deleted. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#delete-motd".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Deletes Message of the Day'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='delete-motd-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-motd'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD simply delete the message of the day.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='delete-motd-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-motd'
sessionid='delete-motd:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Set Welcome Message' anchor='set-welcome'>
<p>Some existing Jabber servers send an informative "welcome message" to newly registered users of the server when they first log in; this concept can be extended to any service (such as a multi-user chat service or a gateway to a foreign IM service). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#set-welcome".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Sets Welcome Message'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='set-welcome-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#set-welcome'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD return the appropriate form, which SHOULD include the current welcome message if one has already been set.</p>
<example caption='Service Returns Welcome Message Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='set-welcome-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#set-welcome'
sessionid='set-welcome:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Setting Welcome Message</title>
<instructions>
Fill out this form to set the welcome message
for this service.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Welcome Message'
type='text-multi'
var='welcome'>
<required/>
<value>Welcome to Shakespeare.lit, your home for</value>
<value>instant messaging with a literary touch.</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Welcome Message Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='set-welcome-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#set-welcome'
sessionid='set-welcome:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='welcome'>
<value>Welcome to Shakespeare.lit, your home for</value>
<value>instant messaging with a literary touch.</value>
<value>For helpful information about this service,</value>
<value>hie thee to http://www.shakespeare.lit/</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='set-welcome-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#set-welcome'
sessionid='set-welcome:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Delete Welcome Message' anchor='delete-welcome'>
<p>Sometimes a previously-set "welcome message" is no longer appropriate and needs to be deleted. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#delete-welcome".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Deletes Welcome Message'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='delete-welcome-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-welcome'/>
</iq>
]]></example>
<p>Unless an error occurs (see the <link url='#errors'>Error Handling</link> section below), the service SHOULD simply delete the welcome message.</p>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='delete-welcome-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-welcome'
sessionid='delete-welcome:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Edit Admin List' anchor='edit-admin'>
<p>An administrator may want to directly edit the list of users who have administrative privileges. Whether there are distinctions between service-level administrators (e.g., owner, admin, moderator), and thus in what types of administrators are allowed to edit administrative privileges, is a matter for the implementation or local service policy and is not specified herein. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#edit-admin".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Editing of Admin List'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='edit-admin-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#edit-admin'/>
</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 Edit Admin List Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='edit-admin-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-admin'
sessionid='edit-admin:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Editing the Admin List</title>
<instructions>
Fill out this form to edit the list of entities who
have administrative privileges.
</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='The admin list'
type='jid-multi'
var='adminjids'>
<value>bard@shakespeare.lit</value>
<value>chris@marlowe.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Edit Admin List Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='edit-admin-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-admin'
sessionid='edit-admin:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='adminjids'>
<value>bard@shakespeare.lit</value>
<value>hecate@shakespeare.lit</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='edit-admin-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#edit-admin'
sessionid='edit-admin:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Restart Service' anchor='restart'>
<p>A service may allow an administrator to restart the service. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#restart".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Restart of Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='restart-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#restart'/>
</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 Restart Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='restart-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#restart'
sessionid='restart:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Restarting the Service</title>
<instructions>Fill out this form to restart the service.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Time delay before restarting'
type='list-single'
var='delay'>
<option label='30 seconds'><value>30</value></option>
<option label='60 seconds'><value>60</value></option>
<option label='90 seconds'><value>90</value></option>
<option label='2 minutes'><value>120</value></option>
<option label='3 minutes'><value>180</value></option>
<option label='4 minutes'><value>240</value></option>
<option label='5 minutes'><value>300</value></option>
</field>
<field label='Announcement'
type='text-multi'
var='announcement'/>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Restart Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='restart-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#restart'
sessionid='restart:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='delay'>
<value>120</value>
</field>
<field var='announcement'>
<value>The service will be restarted in 2 minutes!</value>
<value>Please log off now. --The Admins</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='restart-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#restart'
sessionid='restart:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
<section2 topic='Shut Down Service' anchor='shutdown'>
<p>A service may allow an administrator to shut down the service. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#shutdown".</p>
<p>A sample protocol flow for this use case is shown below.</p>
<example caption='Admin Requests Shut Down of Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='shutdown-1'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
action='execute'
node='http://jabber.org/protocol/admin#shutdown'/>
</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 Shut Down Form to Admin'><![CDATA[
<iq from='shakespeare.lit'
id='shutdown-1'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#shutdown'
sessionid='shutdown:20040408T0337Z'
status='executing'>
<x xmlns='jabber:x:data' type='form'>
<title>Shutting Down the Service</title>
<instructions>Fill out this form to shut down the service.</instructions>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field label='Time delay before shutting down'
type='list-single'
var='delay'>
<option label='30 seconds'><value>30</value></option>
<option label='60 seconds'><value>60</value></option>
<option label='90 seconds'><value>90</value></option>
<option label='2 minutes'><value>120</value></option>
<option label='3 minutes'><value>180</value></option>
<option label='4 minutes'><value>240</value></option>
<option label='5 minutes'><value>300</value></option>
</field>
<field label='Announcement'
type='text-multi'
var='announcement'/>
</x>
</command>
</iq>
]]></example>
<example caption='Admin Submits Shut Down Form to Service'><![CDATA[
<iq from='bard@shakespeare.lit/globe'
id='shutdown-2'
to='shakespeare.lit'
type='set'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#shutdown'
sessionid='shutdown:20040408T0337Z'>
<x xmlns='jabber:x:data' type='submit'>
<field type='hidden' var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<field var='delay'>
<value>120</value>
</field>
<field var='announcement'>
<value>The service will be shut down in 2 minutes!</value>
<value>Please log off now. --The Admins</value>
</field>
</x>
</command>
</iq>
]]></example>
<example caption='Service Informs Admin of Completion'><![CDATA[
<iq from='shakespeare.lit'
id='shutdown-2'
to='bard@shakespeare.lit/globe'
type='result'
xml:lang='en'>
<command xmlns='http://jabber.org/protocol/commands'
node='http://jabber.org/protocol/admin#shutdown'
sessionid='shutdown:20040408T0337Z'
status='completed'/>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Error Handling' anchor='errors'>
<p>Several error conditions are possible when an entity sends a command request to the service, as defined in the following table. If one of these error conditions occurs, the service MUST return an error stanza to the requesting entity.</p>
<table caption='Error Conditions'>
<tr>
<th>Condition</th>
<th>Cause</th>
</tr>
<tr>
<td>&conflict;</td>
<td>The command cannot be completed because of a data or system conflict (e.g., a user already exists with that username).</td>
</tr>
<tr>
<td>&feature;</td>
<td>The specific command is not supported (even though the ad-hoc commands protocol is).</td>
</tr>
<tr>
<td>&forbidden;</td>
<td>The requesting entity does not have sufficient privileges to perform the command.</td>
</tr>
<tr>
<td>&notallowed;</td>
<td>No entity is allowed to perform the command (e.g., retrieve the CEO's roster).</td>
</tr>
<tr>
<td>&unavailable;</td>
<td>The ad-hoc commands protocol is not supported.</td>
</tr>
</table>
<p>For the syntax of these errors, see &xep0086;. Naturally, other errors may be returned as well (e.g., &internalserver; if the service cannot be shut down).</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>The ability to complete the administrative tasks specified herein MUST NOT be granted to users who lack service-level administrative privileges.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>The &REGISTRAR; shall include the following information in its registries.</p>
<section2 topic='Protocol Namespaces' anchor='registrar-protocol'>
<p>The XMPP Registrar includes "http://jabber.org/protocol/admin" in its registry of protocol namespaces.</p>
</section2>
<section2 topic='Field Standardization' anchor='registrar-formtype'>
<p>&xep0068; defines a process for standardizing the fields used within Data Forms scoped by a particular namespace. The reserved fields for the 'http://jabber.org/protocol/admin' namespace are specified below.</p>
<code caption='Registry Submission'><![CDATA[
<form_type>
<name>http://jabber.org/protocol/admin</name>
<doc>XEP-0133</doc>
<desc>Forms used for administration of servers and components.</desc>
<field var='accountjid'
type='jid-single'
label='The Jabber ID of a single entity to which an operation applies'/>
<field var='accountjids'
type='jid-multi'
label='The Jabber ID of one or more entities to which an operation applies'/>
<field var='activeuserjids'
type='jid-multi'
label='The Jabber IDs associated with active sessions'/>
<field var='activeusersnum'
type='text-single'
label='The number of online entities that are active'/>
<field var='adminjids'
type='jid-multi'
label='A list of entities with administrative privileges'/>
<field var='announcement'
type='text-multi'
label='The text of an announcement to be sent to active users or all users'/>
<field var='blacklistjids'
type='jid-multi'
label='A list of entities with whom communication is blocked'/>
<field var='delay'
type='list-multi'
label='The number of seconds to delay before applying a change'/>
<field var='disableduserjids'
type='jid-multi'
label='The Jabber IDs that have been disabled'/>
<field var='disabledusersnum'
type='text-single'
label='The number of disabled entities'/>
<field var='email'
type='text-single'
label='The email address for a user'/>
<field var='given_name'
type='text-single'
label='The given (first) name of a user'/>
<field var='idleusersnum'
type='text-single'
label='The number of online entities that are idle'/>
<field var='ipaddresses'
type='list-multi'
label='The IP addresses of an account&apos;s online sessions'/>
<field var='lastlogin'
type='text-single'
label='The last login time (per XEP-0082) of a user'/>
<field var='loginsperminute'
type='text-single'
label='The number of logins per minute for an account'/>
<field var='max_items'
type='list-single'
label='The maximum number of items associated with a search or list'/>
<field var='motd'
type='text-multi'
label='The text of a message of the day'/>
<field var='onlineresources'
type='text-single'
label='The names of an account&apos;s online sessions'/>
<field var='onlineuserjids'
type='jid-multi'
label='The Jabber IDs associated with online users'/>
<field var='onlineusersnum'
type='text-single'
label='The number of online entities'/>
<field var='password'
type='text-private'
label='The password for an account'/>
<field var='password-verify'
type='text-private'
label='Password verification'/>
<field var='registereduserjids'
type='jid-multi'
label='A list of registered entities'/>
<field var='registeredusersnum'
type='text-single'
label='The number of registered entities'/>
<field var='rostersize'
type='text-single'
label='Number of roster items for an account'/>
<field var='stanzaspersecond'
type='text-single'
label='The number of stanzas being sent per second by an account'/>
<field var='surname'
type='text-single'
label='The family (last) name of a user'/>
<field var='welcome'
type='text-multi'
label='The text of a welcome message'/>
<field var='whitelistjids'
type='jid-multi'
label='A list of entities with whom communication is allowed'/>
</form_type>
]]></code>
</section2>
</section1>
<section1 topic='XML Schema'>
<p>Because the protocol defined here is a profile of <cite>XEP-0050: Ad-Hoc Commands</cite>, no schema definition is needed.</p>
</section1>
</xep>
Reference in New Issue View Git Blame Copy Permalink