JEP-0133: Service Administration

This JEP defines recommended best practices for service-level administration of servers and components using Ad-Hoc Commands.


NOTICE: This JEP is currently within Last Call or under consideration by the Jabber Council for advancement to the next stage in the JSF standards process. For further details, visit <http://www.jabber.org/council/queue.php>.


JEP Information

Status: Proposed
Type: Informational
Number: 0133
Version: 0.3
Last Updated: 2004-09-30
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, JEP-0050
Supersedes: None
Superseded By: None
Short Name: admin

Author Information

Peter Saint-Andre

Email: stpeter@jabber.org
JID: stpeter@jabber.org

Legal Notice

This Jabber Enhancement Proposal is copyright 1999 - 2004 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy <http://www.jabber.org/jsf/ipr-policy.php>. This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at <http://www.opencontent.org/openpub/>).

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core and XMPP IM specifications contributed by the Jabber Software Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocols defined in this JEP have been developed outside the Internet Standards Process and are to be understood as extensions to XMPP rather than as an evolution, development, or modification of XMPP itself.

Conformance Terms

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.


Table of Contents

1. Introduction
2. Requirements
3. Discovery
4. Use Cases
4.1. Add a User
4.2. Delete a User
4.3. Disable a User
4.4. Re-Enable a User
4.5. End a User's Session
4.6. Get a User's Password
4.7. Change a User's Password
4.8. Get a User's Roster
4.9. Get a User's Last Login Time
4.10. Blacklist an Entity
4.11. Whitelist an Entity
4.12. Edit the Blacklist
4.13. Edit the Whitelist
4.14. Get List of Active Users
4.15. Get List of All Users
4.16. Send an Announcement to Active Users
4.17. Set Message of the Day
4.18. Delete Message of the Day
4.19. Set Welcome Message
4.20. Delete Welcome Message
4.21. Grant Administrative Privileges
4.22. Revoke Administrative Privileges
4.23. Edit Admin List
4.24. Restart Service
4.25. Shut Down Service
5. Error Handling
6. Security Considerations
7. IANA Considerations
8. Jabber Registrar Considerations
8.1. Protocol Namespaces
8.2. Field Standardization
9. XML Schema
Notes
Revision History


1. Introduction

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 Multi-User Chat [1]), it makes sense to define a generic protocol for such interactions. This JEP describes such a protocol by specifying a profile of Ad-Hoc Commands [2], rather than by defining a specialized and distinct protocol.

2. Requirements

This JEP addresses the following requirements:

3. Discovery

A server or component MUST advertise any administrative commands it supports via Service Discovery [3] (as described in JEP-0050: Ad-Hoc Commands); such commands exist as well-defined discovery nodes associated with the service in question.

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.

4. Use Cases

This JEP defines a profile of JEP-0050: Ad-Hoc Commands that enables a service-level administrator to complete the following use cases:

  1. Add a User
  2. Delete a User
  3. Disable a User
  4. Re-Enable a User
  5. End a User's Session
  6. Get a User's Password
  7. Change a User's Password
  8. Get a User's Roster
  9. Get a User's Last Login Time
  10. Blacklist an Entity
  11. Whitelist an Entity
  12. Edit the Blacklist
  13. Edit the Whitelist
  14. Get List of All Users
  15. Get List of Active Users
  16. Send an Announcement to Active Users
  17. Set Message of the Day
  18. Delete Message of the Day
  19. Set Welcome Message
  20. Delete Welcome Message
  21. Grant Administrative Privileges
  22. Revoke Administrative Privileges
  23. Edit Admin List
  24. Restart Service
  25. Shut Down Service

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 JEP aims to define common use cases, an implementation or deployment MAY support additional commands not defined herein.

Note: The text that follows assumes that implementers have read and understood JEP-0050: Ad-Hoc Commands as well as Data Forms [4] (on which JEP-0050 depends).

4.1 Add a User

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

A sample protocol flow for this use case is shown below.

Example 1. Admin Requests to Add a User

<iq from='bill@shakespeare.lit/globe'
    id='add-user-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#add-user'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 2. Service Returns Add User Form to Admin

<iq from='shakespeare.lit'
    id='add-user-1'
    to='bill@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 this account'
             type='jid-single'
             var='jid'>
        <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='firstname'/>
      <field label='Family name'
             type='text-single'
             var='surname'/>
    </x>
  </command>
</iq>
    

Example 3. Admin Submits Add User Form to Service

<iq from='bill@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='jid'>
        <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='firstname'>
        <value>Juliet</value>
      </field>
      <field var='surname'>
        <value>Capulet</value>
      </field>
    </x>
  </command>
</iq>
    

Example 4. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='add-user-2'
    to='bill@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>
    

Notification of completion MAY include the processed data in a data form of type "result".

4.2 Delete a User

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

A sample protocol flow for this use case is shown below.

Example 5. Admin Requests to Delete a User

<iq from='bill@shakespeare.lit/globe'
    id='delete-user-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#delete-user'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 6. Service Returns Delete User Form to Admin

<iq from='shakespeare.lit'
    id='delete-user-1'
    to='bill@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 for this account'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 7. Admin Submits Delete User Form to Service

<iq from='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 8. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='delete-user-2'
    to='bill@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>
    

4.3 Disable a User

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

A sample protocol flow for this use case is shown below.

Example 9. Admin Requests to Disable a User

<iq from='bill@shakespeare.lit/globe'
    id='disable-user-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#disable-user'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 10. Service Returns Disable User Form to Admin

<iq from='shakespeare.lit'
    id='disable-user-1'
    to='bill@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 for this account'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 11. Admin Submits Disable User Form to Service

<iq from='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 12. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='disable-user-2'
    to='bill@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>
    

4.4 Re-Enable a User

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

A sample protocol flow for this use case is shown below.

Example 13. Admin Requests to Re-Enable a User

<iq from='bill@shakespeare.lit/globe'
    id='reenable-user-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#reenable-user'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 14. Service Returns Re-Enable User Form to Admin

<iq from='shakespeare.lit'
    id='reenable-user-1'
    to='bill@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 for this account'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 15. Admin Submits Re-Enable User Form to Service

<iq from='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 16. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='reenable-user-2'
    to='bill@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>
    

4.5 End a User's Session

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

A sample protocol flow for this use case is shown below.

Example 17. Admin Requests to End a User's Session

<iq from='bill@shakespeare.lit/globe'
    id='end-user-session-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#end-user-session'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 18. Service Returns End User Session Form to Admin

<iq from='shakespeare.lit'
    id='end-user-session-1'
    to='bill@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 for this account'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

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.

Example 19. Admin Submits End User Session Form to Service

<iq from='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 20. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='end-user-session-2'
    to='bill@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>
    

4.6 Get a User's Password

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

A sample protocol flow for this use case is shown below.

Example 21. Admin Requests to Get a User's Password

<iq from='bill@shakespeare.lit/globe'
    id='get-user-password-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#get-user-password'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 22. Service Returns Get User Password Form to Admin

<iq from='shakespeare.lit'
    id='get-user-password-1'
    to='bill@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 this account'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 23. Admin Submits Get User Password Form to Service

<iq from='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Naturally, the data form included in the IQ result will include the user's password.

Example 24. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='get-user-password-2'
    to='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
      <field var='password'>
        <value>R0m30</value>
      </field>
    </x>
  </completed>
</iq>
    

4.7 Change a User's Password

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

A sample protocol flow for this use case is shown below.

Example 25. Admin Requests to Change a User's Password

<iq from='bill@shakespeare.lit/globe'
    id='change-user-password-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#change-user-password'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 26. Service Returns Change User Password Form to Admin

<iq from='shakespeare.lit'
    id='change-user-password-1'
    to='bill@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 password for this account'
             type='text-private'
             var='password'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 27. Admin Submits Change User Password Form to Service

<iq from='bill@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='password'>
        <value>V3r0n4</value>
      </field>
    </x>
  </command>
</iq>
    

Example 28. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='change-user-password-2'
    to='bill@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>
    

4.8 Get a User's Roster

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

A sample protocol flow for this use case is shown below.

Example 29. Admin Requests to Get a User's Roster

<iq from='bill@shakespeare.lit/globe'
    id='get-user-roster-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#get-user-roster'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 30. Service Returns Get User Roster Form to Admin

<iq from='shakespeare.lit'
    id='get-user-roster-1'
    to='bill@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 for this account'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 31. Admin Submits Get User Roster Form to Service

<iq from='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

The data form included in the IQ result will include the user's roster, formatted according to the 'jabber:iq:roster' protocol defined in XMPP IM [5].

Example 32. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='get-user-roster-2'
    to='bill@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='jid'>
        <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>
  </completed>
</iq>
    

4.9 Get a User's Last Login Time

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

A sample protocol flow for this use case is shown below.

Example 33. Admin Requests to Get a User's Roster

<iq from='bill@shakespeare.lit/globe'
    id='get-user-lastlogin-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#get-user-lastlogin'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 34. Service Returns Get User Last Login Form to Admin

<iq from='shakespeare.lit'
    id='get-user-lastlogin-1'
    to='bill@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 for this account'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 35. Admin Submits Get User Last Login Form to Service

<iq from='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

The data form included in the IQ result will include the user's last login time.

Example 36. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='get-user-lastlogin-2'
    to='bill@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='jid'>
        <value>juliet@shakespeare.lit</value>
      </field>
      <field var='lastlogin'>
        <value>1234</value>
      </field>
    </x>
  </completed>
</iq>
    

4.10 Blacklist an Entity

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 added to a blacklist MAY be a JID of any form as specified in XMPP Core [6]; the order of JID matching SHOULD be that specified for privacy lists in Section 10 of XMPP IM. The act of blacklisting an entity adds it to the blacklist but does not otherwise change the blacklist.

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#add-to-blacklist" if blocking is bidirectional; "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.

A sample protocol flow for this use case is shown below.

Example 37. Admin Requests Blacklisting of an Entity

<iq from='bill@shakespeare.lit/globe'
    id='add-to-blacklist-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#add-to-blacklist'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 38. Service Returns Blacklist Form to Admin

<iq from='shakespeare.lit'
    id='add-to-blacklist-1'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#add-to-blacklist'
           sessionid='add-to-blacklist:20040408T0337Z'
           status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Blocking Communications With an Entity</title>
      <instructions>Fill out this form to block communications with an entity.</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/admin</value>
      </field>
      <field label='The entity to block'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 39. Admin Submits Blacklist Form to Service

<iq from='bill@shakespeare.lit/globe'
    id='add-to-blacklist-2'
    to='shakespeare.lit'
    type='set'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#add-to-blacklist'
           sessionid='add-to-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='jid'>
        <value>marlowe.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 40. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='add-to-blacklist-2'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#add-to-blacklist'
           sessionid='add-to-blacklist:20040408T0337Z'
           status='completed'/>
</iq>
    

4.11 Whitelist an Entity

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 XMPP Core; the order of JID matching SHOULD be that specified for privacy lists in Section 10 of XMPP IM. The act of whitelisting an entity adds it to the whitelist but does not otherwise change the whitelist. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#add-to-whitelist".

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.

A sample protocol flow for this use case is shown below.

Example 41. Admin Requests Whitelisting of an Entity

<iq from='bill@shakespeare.lit/globe'
    id='add-to-whitelist-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#add-to-whitelist'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 42. Service Returns Whitelist Form to Admin

<iq from='shakespeare.lit'
    id='add-to-whitelist-1'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#add-to-whitelist'
           sessionid='add-to-whitelist:20040408T0337Z'
           status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Allowing Communications With an Entity</title>
      <instructions>Fill out this form to allow communications with an entity.</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/admin</value>
      </field>
      <field label='The entity to allow'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Note: If the entity is an end user, the JID SHOULD be of the form <user@host>, not <user@host/resource>.

Example 43. Admin Submits Whitelist Form to Service

<iq from='bill@shakespeare.lit/globe'
    id='add-to-whitelist-2'
    to='shakespeare.lit'
    type='set'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#add-to-whitelist'
           sessionid='add-to-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='jid'>
        <value>england.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 44. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='add-to-whitelist-2'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#add-to-whitelist'
           sessionid='add-to-whitelist:20040408T0337Z'
           status='completed'/>
</iq>
    

4.12 Edit the Blacklist

An administrator may need to edit the blacklist rather than simply add an entity to it. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#edit-blacklist" if blocking is bidirectional; "http://jabber.org/protocol/admin#edit-blacklist-in" for inbound blocking only; and "http://jabber.org/protocol/admin#edit-blacklist-out" for outbound blocking only.

A sample protocol flow for this use case is shown below.

Example 45. Admin Requests Editing of Blacklist

<iq from='bill@shakespeare.lit/globe'
    id='edit-blacklist-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#edit-blacklist'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 46. Service Returns Edit Blacklist Form to Admin

<iq from='shakespeare.lit'
    id='edit-blacklist-1'
    to='bill@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'
             type='jid-multi'
             var='blacklist'>
        <value>marlowe.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 47. Admin Submits Edit Blacklist Form to Service

<iq from='bill@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='blacklist'>
        <value>denmark.lit</value>
        <value>france.lit</value>
        <value>marlowe.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 48. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='edit-blacklist-2'
    to='bill@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>
    

4.13 Edit the Whitelist

An administrator may need to edit the whitelist rather than simply add an entity to it. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#edit-whitelist" if blocking is bidirectional; "http://jabber.org/protocol/admin#edit-whitelist-in" for inbound blocking only; and "http://jabber.org/protocol/admin#edit-whitelist-out" for outbound blocking only.

A sample protocol flow for this use case is shown below.

Example 49. Admin Requests Editing of Whitelist

<iq from='bill@shakespeare.lit/globe'
    id='edit-whitelist-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#edit-whitelist'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 50. Service Returns Edit Whitelist Form to Admin

<iq from='shakespeare.lit'
    id='edit-whitelist-1'
    to='bill@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'
             type='jid-multi'
             var='whitelist'>
        <value>capulet.com</value>
        <value>denmark.lit</value>
        <value>england.lit</value>
        <value>montague.net</value>
      </field>
    </x>
  </command>
</iq>
    

Example 51. Admin Submits Edit Whitelist Form to Service

<iq from='bill@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='whitelist'>
        <value>capulet.com</value>
        <value>england.lit</value>
        <value>montague.net</value>
        <value>verona.it</value>
      </field>
    </x>
  </command>
</iq>
    

Example 52. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='edit-whitelist-2'
    to='bill@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>
    

4.14 Get List of Active Users

Administrators of some existing Jabber servers have found it useful to be able to retrieve a list of all online users of the server; this concept can be extended to any service (such as a multi-user chat service or a gateway to a foreign IM service). Obviously, the service may need to truncate the result-set, since it could be quite large; furthermore, any ability to limit or page through the result-set is outside the scope of this JEP. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-active-users".

A sample protocol flow for this use case is shown below.

Example 53. Admin Requests List of Active Users

<iq from='bill@shakespeare.lit/globe'
    id='get-active-users-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#get-active-users'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD simply return the list of active users.

Example 54. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='get-active-users-2'
    to='bill@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='form'>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/admin</value>
      </field>
      <field label='The list of active users'
             type='jid-multi'
             var='userlist'>
        <value>bill@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>
    

4.15 Get List of All Users

The concept of retrieving a list of active users can be extended even further to enable an administrator to retrieve a list of all users (not just active or online users). As with the previous use case, the service may need to truncate the result-set, since it could be quite large; furthermore, any ability to limit or page through the result-set is outside the scope of this JEP. The command node for this use case SHOULD be "http://jabber.org/protocol/admin#get-all-users".

A sample protocol flow for this use case is shown below.

Example 55. Admin Requests List of All Users

<iq from='bill@shakespeare.lit/globe'
    id='get-all-users-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#get-all-users'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the list of all users.

Example 56. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='get-all-users-2'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#get-all-users'
           sessionid='get-all-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'
             type='jid-multi'
             var='userlist'>
        <value>bernardo@shakespeare.lit</value>
        <value>bill@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>
    

4.16 Send an Announcement to Active Users

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

A sample protocol flow for this use case is shown below.

Example 57. Admin Requests Announcement

<iq from='bill@shakespeare.lit/globe'
    id='announce-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#announce'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 58. Service Returns Announce Form to Admin

<iq from='shakespeare.lit'
    id='announce-1'
    to='bill@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 59. Admin Submits Announce Form to Service

<iq from='bill@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 60. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='announce-2'
    to='bill@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>
    

4.17 Set Message of the Day

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); 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".

A sample protocol flow for this use case is shown below.

Example 61. Admin Sets Message of the Day

<iq from='bill@shakespeare.lit/globe'
    id='set-motd-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#set-motd'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form, which SHOULD include the current message of the day if one has already been set.

Example 62. Service Returns MOTD Form to Admin

<iq from='shakespeare.lit'
    id='set-motd-1'
    to='bill@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/>
        <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 63. Admin Submits MOTD Form to Service

<iq from='bill@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 64. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='set-motd-2'
    to='bill@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>
    

4.18 Delete Message of the Day

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

A sample protocol flow for this use case is shown below.

Example 65. Admin Deletes Message of the Day

<iq from='bill@shakespeare.lit/globe'
    id='delete-motd-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#delete-motd'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD simply delete the message of the day.

Example 66. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='delete-motd-2'
    to='bill@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>
    

4.19 Set Welcome Message

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

A sample protocol flow for this use case is shown below.

Example 67. Admin Sets Welcome Message

<iq from='bill@shakespeare.lit/globe'
    id='set-welcome-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#set-welcome'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form, which SHOULD include the current welcome message if one has already been set.

Example 68. Service Returns Welcome Message Form to Admin

<iq from='shakespeare.lit'
    id='set-welcome-1'
    to='bill@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 69. Admin Submits Welcome Message Form to Service

<iq from='bill@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 70. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='set-welcome-2'
    to='bill@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>
    

4.20 Delete Welcome Message

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

A sample protocol flow for this use case is shown below.

Example 71. Admin Deletes Welcome Message

<iq from='bill@shakespeare.lit/globe'
    id='delete-welcome-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#delete-welcome'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD simply delete the welcome message.

Example 72. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='delete-welcome-2'
    to='bill@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>
    

4.21 Grant Administrative Privileges

An administrator may want to grant administrative privileges to another user. Whether there are distinctions between service-level administrators (e.g., owner, admin, moderator), and thus which types of administrators are allowed to grant 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#grant-admin".

A sample protocol flow for this use case is shown below.

Example 73. Admin Requests to Grant Admin Privileges

<iq from='bill@shakespeare.lit/globe'
    id='grant-admin-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#grant-admin'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 74. Service Returns Grant Admin Privileges Form to Admin

<iq from='shakespeare.lit'
    id='grant-admin-1'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#grant-admin'
           sessionid='grant-admin:20040408T0337Z'
           status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Granting Administrative Privileges</title>
      <instructions>
          Fill out this form to grant administrative privileges 
          to another user.
      </instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/admin</value>
      </field>
      <field label='The Jabber ID of the new admin'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Example 75. Admin Submits Grant Admin Privileges Form to Service

<iq from='bill@shakespeare.lit/globe'
    id='grant-admin-2'
    to='shakespeare.lit'
    type='set'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#grant-admin'
           sessionid='grant-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='jid'>
        <value>hecate@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 76. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='grant-admin-2'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#grant-admin'
           sessionid='grant-admin:20040408T0337Z'
           status='completed'/>
</iq>
    

4.22 Revoke Administrative Privileges

An administrator may want to revoke another user's 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 revoke 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#revoke-admin".

A sample protocol flow for this use case is shown below.

Example 77. Admin Requests to Revoke Admin Privileges

<iq from='bill@shakespeare.lit/globe'
    id='revoke-admin-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#revoke-admin'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 78. Service Returns Revoke Admin Privileges Form to Admin

<iq from='shakespeare.lit'
    id='revoke-admin-1'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#revoke-admin'
           sessionid='revoke-admin:20040408T0337Z'
           status='executing'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Revoking Admin Privileges</title>
      <instructions>
          Fill out this form to revoke another user&apos; 
          administrative privileges.
      </instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>http://jabber.org/protocol/admin</value>
      </field>
      <field label='The Jabber ID of the soon-to-be former admin'
             type='jid-single'
             var='jid'>
        <required/>
      </field>
    </x>
  </command>
</iq>
    

Example 79. Admin Submits Revoke Admin Privileges Form to Service

<iq from='bill@shakespeare.lit/globe'
    id='revoke-admin-2'
    to='shakespeare.lit'
    type='set'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#revoke-admin'
           sessionid='revoke-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='jid'>
        <value>hecate@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 80. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='revoke-admin-2'
    to='bill@shakespeare.lit/globe'
    type='result'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           node='http://jabber.org/protocol/admin#revoke-admin'
           sessionid='revoke-admin:20040408T0337Z'
           status='completed'/>
</iq>
    

4.23 Edit Admin List

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

A sample protocol flow for this use case is shown below.

Example 81. Admin Requests Editing of Admin List

<iq from='bill@shakespeare.lit/globe'
    id='edit-admin-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#edit-admin'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 82. Service Returns Edit Admin List Form to Admin

<iq from='shakespeare.lit'
    id='edit-admin-1'
    to='bill@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='adminlist'>
        <value>bill@shakespeare.lit</value>
        <value>chris@marlowe.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 83. Admin Submits Edit Admin List Form to Service

<iq from='bill@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='adminlist'>
        <value>bill@shakespeare.lit</value>
        <value>hecate@shakespeare.lit</value>
      </field>
    </x>
  </command>
</iq>
    

Example 84. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='edit-admin-2'
    to='bill@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>
    

4.24 Restart Service

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

A sample protocol flow for this use case is shown below.

Example 85. Admin Requests Restart of Service

<iq from='bill@shakespeare.lit/globe'
    id='restart-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#restart'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 86. Service Returns Restart Form to Admin

<iq from='shakespeare.lit'
    id='restart-1'
    to='bill@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-multi'
             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>180</value></option>
        <option label='5 minutes'><value>180</value></option>
      </field>
      <field label='Announcement'
             type='text-multi'
             var='announcement'/>
    </x>
  </command>
</iq>
    

Example 87. Admin Submits Restart Form to Service

<iq from='bill@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 88. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='restart-2'
    to='bill@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>
    

4.25 Shut Down Service

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

A sample protocol flow for this use case is shown below.

Example 89. Admin Requests Shut Down of Service

<iq from='bill@shakespeare.lit/globe'
    id='shutdown-1'
    to='shakespeare.lit'
    type='get'
    xml:lang='en'>
  <command xmlns='http://jabber.org/protocol/commands' 
           action='execute'
           node='http://jabber.org/protocol/admin#shutdown'/>
</iq>
    

Unless an error occurs (see the Error Handling section below), the service SHOULD return the appropriate form.

Example 90. Service Returns Shut Down Form to Admin

<iq from='shakespeare.lit'
    id='shutdown-1'
    to='bill@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-multi'
             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>180</value></option>
        <option label='5 minutes'><value>180</value></option>
      </field>
      <field label='Announcement'
             type='text-multi'
             var='announcement'/>
    </x>
  </command>
</iq>
    

Example 91. Admin Submits Shut Down Form to Service

<iq from='bill@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 92. Service Informs Admin of Completion

<iq from='shakespeare.lit'
    id='shutdown-2'
    to='bill@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>
    

5. Error Handling

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.

Table 1: Error Conditions

Condition Cause
<conflict/> The command cannot be completed because of a data or system conflict (e.g., a user already exists with that username).
<feature-not-implemented/> The specific command is not supported (even though the ad-hoc commands protocol is).
<forbidden/> The requesting entity does not have sufficient privileges to perform the command.
<not-allowed/> No entity is allowed to perform the command (e.g., retrieve the CEO's roster).
<service-unavailable/> The ad-hoc commands protocol is not supported.

For the syntax of these errors, see Error Condition Mappings [7]. Naturally, other errors may be returned as well (e.g., <internal-server-error/> if the service cannot be shut down).

6. Security Considerations

The ability to complete the administrative tasks specified herein MUST NOT be granted to users who lack service-level administrative privileges.

7. IANA Considerations

This JEP requires no interaction with the Internet Assigned Numbers Authority (IANA) [8].

8. Jabber Registrar Considerations

The Jabber Registrar [9] shall include the following information in its registries.

8.1 Protocol Namespaces

Upon advancement of this JEP to a status of Active, the Jabber Registrar shall add "http://jabber.org/protocol/admin" to its registry of protocol namespaces.

8.2 Field Standardization

Field Standardization for Data Forms [10] 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.

Registry Submission

<form_type>
  <name>http://jabber.org/protocol/admin</name>
  <doc>JEP-0133</doc>
  <desc>Forms used for administration of servers and components.</desc>
  <field var='adminlist'
         type='jid-multi'
         var='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='blacklist'
         type='jid-multi'
         var='A list of entities with whom communication is blocked'/>
  <field var='delay'
         type='list-multi'
         var='The number of seconds to delay before applying a change'/>
  <field var='email'
         type='text-single'
         label='The email address for a user'/>
  <field var='firstname'
         type='text-single'
         label='The given (first) name of a user'/>
  <field var='jid'
         type='jid-single'
         label='The Jabber ID of a user or other entity'/>
  <field var='motd'
         type='text-multi'
         label='The text of a message of the day'/>
  <field var='password'
         type='text-private'
         label='The password for an account'/>
  <field var='password-verify'
         type='text-private'
         label='Password verification'/>
  <field var='surname'
         type='text-single'
         label='The family (last) name of a user'/>
  <field var='userlist'
         type='jid-multi'
         var='A list of registered entities'/>
  <field var='welcome'
         type='text-multi'
         label='The text of a welcome message'/>
  <field var='whitelist'
         type='jid-multi'
         var='A list of entities with whom communication is allowed'/>
</form_type>
    

9. XML Schema

Because the protocol defined here is a profile of JEP-0050: Ad-Hoc Commands, no schema definition is needed.


Notes

1. JEP-0045: Multi-User Chat <http://www.jabber.org/jeps/jep-0045.html>.

2. JEP-0050: Ad-Hoc Commands <http://www.jabber.org/jeps/jep-0050.html>.

3. JEP-0030: Service Discovery <http://www.jabber.org/jeps/jep-0030.html>.

4. JEP-0004: Data Forms <http://www.jabber.org/jeps/jep-0004.html>.

5. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://www.ietf.org/rfc/rfc3921.txt>.

6. RFC 3920: Extensible Messaging and Presence Protocol (XMPP): Core <http://www.ietf.org/rfc/rfc3920.txt>.

7. JEP-0086: Error Condition Mappings <http://www.jabber.org/jeps/jep-0086.html>.

8. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

9. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.

10. JEP-0068: Field Data Standardization for Data Forms <http://www.jabber.org/jeps/jep-0068.html>.


Revision History

Version 0.3 (2004-09-30)

Changed command naming requirement from MUST to SHOULD. (psa)

Version 0.2 (2004-07-22)

Added several more use cases; defined complete protocol flows; specified Jabber Registrar considerations. (psa)

Version 0.1 (2004-04-25)

Initial version. (psa)


END