<abstract>This document defines recommended best practices for service-level administration of servers and components using Ad-Hoc Commands.</abstract>
<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>
<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>
<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>
<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>
<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: 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>.</em></p>
<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>
<examplecaption='Admin Requests to Add a User'><![CDATA[
<p>Notification of completion MAY include the processed data in a data form of type "result".</p>
</section2>
<section2topic='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>
<examplecaption='Admin Requests to Delete a User'><![CDATA[
<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>
<examplecaption='Admin Requests to Disable a User'><![CDATA[
<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>
<examplecaption='Admin Requests to Re-Enable a User'><![CDATA[
<section2topic='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>
<examplecaption='Admin Requests to End a User's Session'><![CDATA[
<instructions>Fill out this form to end a user's session.</instructions>
<fieldtype='hidden'var='FORM_TYPE'>
<value>http://jabber.org/protocol/admin</value>
</field>
<fieldlabel='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 <user@host>, the service MUST end all of the user's sessions; if the JID is of the form <user@host/resource>, the service MUST end only the session associated with that resource.</p>
<examplecaption='Admin Submits End User Session Form to Service'><