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.

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.

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

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.

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

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.

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

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.

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.

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.

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

Naturally, the data form included in the IQ result will include the 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.

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

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

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.

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

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

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.

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

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

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.

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.

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.

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.

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.

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 an IM session, as specified in Section 3 of RFC 3921 or its equivalent (e.g., &xep0078;), 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.

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.

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.

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.