%ents; ]>
Service Administration This document defines recommended best practices for service-level administration of servers and components using Ad-Hoc Commands. &LEGALNOTICE; 0133 Active Informational Standards RFC 3920 XEP-0050 admin &stpeter; 1.2pre1 in progress, last updated 2008-06-10 psa

Added use cases for deleting logs and emptying cache.

1.1 2005-08-19 psa

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.

1.0 2004-12-09 psa

Per a vote of the Jabber Council, advanced status to Active.

0.8 2004-12-06 psa

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.

0.7 2004-12-02 psa

Added use case for editing message of the day.

0.6 2004-11-19 psa

Further clarified message of the day per list discussion.

0.5 2004-11-17 psa

Changed firstname to given_name.

0.4 2004-11-02 psa

Added note clarifying concept of message of the day.

0.3 2004-09-30 psa

Changed command naming requirement from MUST to SHOULD.

0.2 2004-07-22 psa

Added several more use cases; defined complete protocol flows; specified XMPP Registrar considerations.

0.1 2004-04-25 psa

Initial version.

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.

This document addresses the following requirements:

A server or component MUST advertise any administrative commands it supports via &xep0030; (as described in XEP-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.

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

  1. Add User
  2. Delete User
  3. Disable User
  4. Re-Enable User
  5. End User Session
  6. Get User Password
  7. Change User Password
  8. Get User Roster
  9. Get User Last Login Time
  10. Get User Statistics
  11. Edit Blacklist
  12. Edit Whitelist
  13. Get Number of Registered Users
  14. Get Number of Disabled Users
  15. Get Number of Online Users
  16. Get Number of Active Users
  17. Get Number of Idle Users
  18. Get List of Registered Users
  19. Get List of Disabled Users
  20. Get List of Online Users
  21. Get List of Active Users
  22. Get List of Idle Users
  23. Send Announcement to Active Users
  24. Set Message of the Day
  25. Edit Message of the Day
  26. Delete Message of the Day
  27. Set Welcome Message
  28. Delete Welcome Message
  29. Edit Admin List
  30. Restart Service
  31. 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 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.

Note: The text that follows assumes that implementors have read and understood XEP-0050: Ad-Hoc Commands and XEP-0004: Data Forms.

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.

]]>

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

Adding a User Fill out this form to add a user. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin juliet@shakespeare.lit R0m30 R0m30 juliet@capulet.com Juliet Capulet ]]> ]]>

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

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.

]]>

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

Deleting a User Fill out this form to delete a user. http://jabber.org/protocol/admin ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit ]]> ]]>

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.

]]>

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

Disabling a User Fill out this form to disable a user. http://jabber.org/protocol/admin ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit ]]> ]]>

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.

]]>

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

Re-Enable a User Fill out this form to re-enable a user. http://jabber.org/protocol/admin ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit ]]> ]]>

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.

]]>

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

Ending a User Session Fill out this form to end a user's session. http://jabber.org/protocol/admin ]]>

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.

http://jabber.org/protocol/admin juliet@shakespeare.lit ]]> ]]>

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.

]]>

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

Getting a User's Password Fill out this form to get a user's password. http://jabber.org/protocol/admin ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit R0m30 ]]>

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.

]]>

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

Changing a User Password Fill out this form to change a user's password. http://jabber.org/protocol/admin ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit V3r0n4 ]]> ]]>

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.

]]>

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

Getting a User's Roster Fill out this form to get a user's roster. http://jabber.org/protocol/admin ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit ]]>

The data form included in the IQ result will include the user's roster, formatted according to the 'jabber:iq:roster' protocol defined in &rfc3921;.

http://jabber.org/protocol/admin juliet@shakespeare.lit Friends Lovers Friends Friends ]]>

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.

]]>

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

Getting a User's Last Login Time Fill out this form to get a user's last login time. http://jabber.org/protocol/admin ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit ]]>

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

http://jabber.org/protocol/admin juliet@shakespeare.lit 2003-12-19T17:58:35Z ]]>

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

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

]]>

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

Get User Statistics Fill out this form to gather user statistics. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin iago@shakespeare.lit ]]> http://jabber.org/protocol/admin 127.0.0.1 123 work home 3 0.1 ]]>

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 &rfc3920;; the order of JID matching SHOULD be that specified for privacy lists in Section 10 of RFC 3921.

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.

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

]]>

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

Editing the Blacklist Fill out this form to edit the list of entities with whom communications are disallowed. http://jabber.org/protocol/admin marlowe.lit ]]> http://jabber.org/protocol/admin denmark.lit france.lit marlowe.lit ]]> ]]>

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 RFC 3920; the order of JID matching SHOULD be that specified for privacy lists in Section 10 of RFC 3921.

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.

]]>

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

Editing the Whitelist Fill out this form to edit the list of entities with whom communications are allowed. http://jabber.org/protocol/admin capulet.com denmark.lit england.lit montague.net ]]> http://jabber.org/protocol/admin capulet.com england.lit montague.net verona.it ]]> ]]>

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

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

]]>

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

http://jabber.org/protocol/admin 123 ]]>

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

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

]]>

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

http://jabber.org/protocol/admin 123 ]]>

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 active or connected resource as defined in &rfc3920bis; and &rfc3921bis; (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".

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

]]>

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

http://jabber.org/protocol/admin 79 ]]>

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

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

]]>

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

http://jabber.org/protocol/admin 66 ]]>

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

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

]]>

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

http://jabber.org/protocol/admin 13 ]]>

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

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

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD do one of the following:

  1. If there are not many registered users, the service MAY simply return the list of registered users.
  2. 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).
Requesting List of Registered Users Fill out this form to request the registered users of this service. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin 100 ]]> http://jabber.org/protocol/admin bernardo@shakespeare.lit bard@shakespeare.lit cordelia@shakespeare.lit crone1@shakespeare.lit emilia@shakespeare.lit francisco@shakespeare.lit goneril@shakespeare.lit hag66@shakespeare.lit hecate@shakespeare.lit iago@shakespeare.lit kingclaudius@shakespeare.lit kinglear@shakespeare.lit laertes@shakespeare.lit macbeth@shakespeare.li mercutio@shakespeare.lit nestor@shakespeare.lit northumberland@shakespeare.lit painter@shakespeare.lit regan@shakespeare.lit timon@shakespeare.lit wiccarocks@shakespeare.lit ]]>

The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.

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.

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

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

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD do one of the following:

  1. If there are not many disabled users, the service MAY simply return the list of disabled users.
  2. 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).
Requesting List of Disabled Users Fill out this form to request the disabled users of this service. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin 100 ]]> http://jabber.org/protocol/admin bernardo@shakespeare.lit iago@shakespeare.lit ]]>

The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.

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.

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

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

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD do one of the following:

  1. If there are not many online users, the service MAY simply return the list of online users.
  2. 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).
Requesting List of Online Users Fill out this form to request the online users of this service. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin 100 ]]> http://jabber.org/protocol/admin bard@shakespeare.lit cordelia@shakespeare.lit crone1@shakespeare.lit goneril@shakespeare.lit hag66@shakespeare.lit hecate@shakespeare.lit kinglear@shakespeare.lit macbeth@shakespeare.li mercutio@shakespeare.lit northumberland@shakespeare.lit painter@shakespeare.lit wiccarocks@shakespeare.lit ]]>

The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.

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.

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

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

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD do one of the following:

  1. If there are not many active users, the service MAY simply return the list of active users.
  2. 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).
Requesting List of Active Users Fill out this form to request the active users of this service. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin 100 ]]> http://jabber.org/protocol/admin bard@shakespeare.lit crone1@shakespeare.lit hag66@shakespeare.lit hecate@shakespeare.lit wiccarocks@shakespeare.lit ]]>

The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.

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.

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

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

]]>

Unless an error occurs (see the Error Handling section below), the service SHOULD do one of the following:

  1. If there are not many idle users, the service MAY simply return the list of idle users.
  2. 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).
Requesting List of Active Users Fill out this form to request the idle users of this service. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin 100 ]]> http://jabber.org/protocol/admin cordelia@shakespeare.lit goneril@shakespeare.lit kinglear@shakespeare.lit macbeth@shakespeare.li mercutio@shakespeare.lit northumberland@shakespeare.lit painter@shakespeare.lit ]]>

The service MAY return an error (rather than a list) if the number of items is excessive or the max_items value is unnacceptable.

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.

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.

]]>

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

Making an Announcement Fill out this form to make an announcement to all active users of this service. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin Attention! This service will be going down for maintenance in 2 minutes. Please log off now! We apologize for the inconvenience. ]]> ]]>

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

]]>

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

Setting the Message of the Day Fill out this form to set the message of the day. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin Don't forget: the grand re-opening of the Globe Theatre will occur tomorrow night. The festivities will begin right after tea and extend far into the night. Don't miss it! --The Globe Staff ]]> ]]>

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

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

]]>

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.

Editing the Message of the Day Fill out this form to edit the message of the day. http://jabber.org/protocol/admin Don't forget: the grand re-opening of the Globe Theatre will occur tomorrow night. The festivities will begin right after tea and extend far into the night. Don't miss it! --The Globe Stuff ]]> http://jabber.org/protocol/admin Don't forget: the grand re-opening of the Globe Theatre will occur tomorrow night. The festivities will begin right after tea and extend far into the night. Don't miss it! --The Globe Staff ]]> ]]>

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.

]]>

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

]]>

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.

]]>

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.

Setting Welcome Message Fill out this form to set the welcome message for this service. http://jabber.org/protocol/admin Welcome to Shakespeare.lit, your home for instant messaging with a literary touch. ]]> http://jabber.org/protocol/admin Welcome to Shakespeare.lit, your home for instant messaging with a literary touch. For helpful information about this service, hie thee to http://www.shakespeare.lit/ ]]> ]]>

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.

]]>

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

]]>

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.

]]>

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

Editing the Admin List Fill out this form to edit the list of entities who have administrative privileges. http://jabber.org/protocol/admin bard@shakespeare.lit chris@marlowe.lit ]]> http://jabber.org/protocol/admin bard@shakespeare.lit hecate@shakespeare.lit ]]> ]]>

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.

]]>

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

Restarting the Service Fill out this form to restart the service. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin 120 The service will be restarted in 2 minutes! Please log off now. --The Admins ]]> ]]>

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.

]]>

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

Shutting Down the Service Fill out this form to shut down the service. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin 120 The service will be shut down in 2 minutes! Please log off now. --The Admins ]]> ]]>

A service may allow an administrator to delete a log related to the service (e.g., a server log, a personal conversation log, or a discussion log from a multi-user chat room). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#deletelog".

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

]]>

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

Deleting a Log Fill out this form to delete logs. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin 20080610 ]]> ]]>

A service may allow an administrator to empty cached information related to a service (e.g., the history of a chat room). The command node for this use case SHOULD be "http://jabber.org/protocol/admin#emptycache".

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

]]>

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

Emptying the Cache Fill out this form to empty the cache. http://jabber.org/protocol/admin ]]> http://jabber.org/protocol/admin someroom ]]> ]]>

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.

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; 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.
¬allowed; No entity is allowed to perform the command (e.g., retrieve the CEO's roster).
&unavailable; The ad-hoc commands protocol is not supported.

For the syntax of these errors, see &xmppcore;. Naturally, other errors may be returned as well (e.g., &internalserver; if the service cannot be shut down).

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

This document requires no interaction with &IANA;.

The ®ISTRAR; shall include the following information in its registries.

The XMPP Registrar includes "http://jabber.org/protocol/admin" in its registry of protocol namespaces.

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

http://jabber.org/protocol/admin XEP-0133 Forms used for administration of servers and components. ]]>

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