This document specifies a file format for importing and exporting user data to and from XMPP-IM servers.
WARNING: This Standards-Track document is Experimental. Publication as an XMPP Extension Protocol does not imply approval of this proposal by the XMPP Standards Foundation. Implementation of the protocol described herein is encouraged in exploratory implementations, but production systems should not deploy implementations of this protocol until it advances to a status of Draft.
Series: XEP
Number: 0227
Publisher: XMPP Standards Foundation
Status:
Experimental
Type:
Standards Track
Version: 0.1
Last Updated: 2007-08-08
Approving Body: XMPP Council
Dependencies: XMPP IM, XEP-0049, XEP-0054
Supersedes: None
Superseded By: None
Short Name: TO BE ASSIGNED
Wiki Page: <http://wiki.jabber.org/index.php/Portable Import/Export Format for XMPP-IM Servers (XEP-0227)>
Email:
henoch@dtek.chalmers.se
JabberID:
legoscia@jabber.cd.chalmers.se
This XMPP Extension Protocol is copyright 1999 - 2007 by the XMPP Standards Foundation (XSF) and is in full conformance with the XSF's Intellectual Property Rights Policy <http://www.xmpp.org/extensions/ipr-policy.shtml>. This material may be distributed only subject to the terms and conditions set forth in the Creative Commons Attribution License (<http://creativecommons.org/licenses/by/2.5/>).
The preferred venue for discussion of this document is the Standards discussion list: <http://mail.jabber.org/mailman/listinfo/standards>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The following keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
1. Introduction
2. Requirements
3. Glossary
4. File format
4.1. Hosts
4.2. Users
4.3. Rosters
4.4. Offline Messages
4.5. Private XML Storage
4.6. vCards
5. Security Considerations
6. IANA Considerations
7. XMPP Registrar Considerations
7.1. Protocol Namespaces
8. XML Schema
Notes
Revision History
Different implementations of XMPP-IM servers store user data in various ways, and many implementations have more than one storage format. This leads to problems when a server administrator wants to switch to another implementation or storage format -- the implementation is as likely as not to have an import mechanism that can read the user data in its current form. This document attempts to solve that problem by defining a common file format for import and export of user data in XMPP-IM servers.
The following constraints are imposed on this standard:
The data is stored in a single file.
For the convenience of server administrators, a single file holds all relevant data.
The file format is XML-based.
XMPP-IM servers already have tools to process XML data. This also allows extension of the format using namespaces. Furthermore, some of the data that needs to be stored is by definition already in XML form.
All user data is stored, but no server configuration data.
User data has similar form throughout the XMPP world, but server configuration is implementation-specific. Therefore this specification does not attempt to transfer any aspects of the server configuration from one server to another.
Furthermore, the contents of MUC, Pubsub and other services are out of scope for this specification.
Multiple virtual hosts are supported.
Many server implementations can serve several hostnames in a single server instance. Thus this specification allows storing data from several virtual hosts.
Exporting server.
The XMPP-IM server writing its user data into a file, following this specification.
Importing server.
The XMPP-IM server reading data from such a file.
Data is contained in a single XML file, whose root element is <server-data/> qualified by the 'http://www.xmpp.org/extensions/xep-0227.html#ns' namespace (see Protocol Namespaces regarding issuance of one or more permanent namespaces).
<?xml version='1.0' encoding='UTF-8'?> <server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'> [ ... ] </server-data>
At any point in the file, an exporting server may put elements qualified by a namespace not mentioned in this specification. The exported data SHOULD be meaningful without the extensions. An importing server that encounters a namespace that it doesn't understand, or otherwise is unable to import all given data, SHOULD ignore the unknown data, SHOULD notify the operator, and MAY offer to terminate the process.
The child elements of the <server-data/> elements are <host/> elements. Each <host/> element describes a virtual host, and has a 'jid' attribute that contains its JID.
An importing server MAY automatically adjust its list of virtual hosts to fit the ones present in the data being imported. If it does not, it SHOULD notify the operator about any mismatch.
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
<host jid='capulet.com'>
[ ... ]
</host>
<host jid='montague.net'>
[ ... ]
</host>
</server-data>
Each user is represented by a <user/> element under the <host/> element. The <user/> element MUST have a 'name' attribute, which contains the node part of the user's JID, and SHOULD have a 'password' attribute, which contains the user's password.
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
[ ... ]
</user>
</host>
<host jid='montague.net'>
<user name='romeo' password='iLuvJuLi3T'>
[ ... ]
</user>
</host>
</server-data>
Each <user/> element SHOULD contain the user's roster in the form of a <query/> element qualified by the 'jabber:iq:roster' namespace. This element contains the user's roster in the same format as when retrieving the roster from the server, as described in section 7.3 of XMPP IM [1].
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<query xmlns='jabber:iq:roster'>
<item jid='romeo@montague.net'
name='Romeo'
subscription='both'>
<group>Friends</group>
</item>
</query>
</user>
</host>
</server-data>
If the exporting server stores messages received while the user was offline, it SHOULD include an <offline-messages/> element as a child of the <user/> element. This element contains all the stored messages to the user, if any, as <message/> elements qualified by the 'jabber:client' namespace, starting with the oldest.
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<offline-messages>
<message xmlns='jabber:client'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
type='chat'>
<body>Neither, fair saint, if either thee dislike.</body>
<delay xmlns='urn:xmpp:delay'
from='capulet.com'
stamp='1469-07-21T00:32:29Z'>
Offline Storage
</delay>
</message>
</offline-messages>
</user>
</host>
</server-data>
Private data stored by the server as specified in Private XML Storage [2] is represented in this format by including a <query/> element qualified by the 'jabber:iq:private' namespace as a child of the <user/> element. This <query/> element in turn contains all elements saved in private XML storage.
Example 6. Private XML Storage
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
<host jid='shakespeare.lit'>
<user name='hamlet' password='2b0Rnot2B'>
<query xmlns="jabber:iq:private">
<exodus xmlns="exodus:prefs">
<defaultnick>Hamlet</defaultnick>
</exodus>
</query>
</user>
</host>
</server-data>
By vcard-temp [3], users can store vCards on the server. In this specification, vCards are child elements of the <user/> element, namely a <vCard/> element qualified by the 'vcard-temp' namespace.
<?xml version='1.0' encoding='UTF-8'?>
<server-data xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'>
<host jid='capulet.com'>
<user name='juliet' password='s3crEt'>
<vCard xmlns='vcard-temp'>
<FN>Juliet Capulet</FN>
<vCard>
</user>
</host>
</server-data>
Exported data files are to be handled with care, since they contain data that users expect to be protected, in particular passwords. An exporting server SHOULD make sure that the generated file is not accessible to unauthorized persons, e.g. by enforcing strict file permissions.
This document requires no interaction with the Internet Assigned Numbers Authority (IANA).
Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0227.html#ns"; upon advancement of this specification, the XMPP Registrar [4] shall issue a permanent namespace in accordance with the process defined in Section 4 of XMPP Registrar Function [5].
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='http://www.xmpp.org/extensions/xep-0227.html#ns'
xmlns='http://www.xmpp.org/extensions/xep-0227.html#ns'
elementFormDefault='qualified'>
<xs:element name='server-data'>
<xs:complexType>
<xs:sequence>
<xs:element ref='host' maxOccurs='unbounded'/>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='host'>
<xs:complexType>
<xs:sequence>
<xs:element ref='user' maxOccurs='unbounded'/>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='jid' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='user'>
<xs:complexType>
<xs:sequence>
<xs:element ref='offline-messages' minOccurs='0' maxOccurs='1'/>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
<xs:attribute name='name' type='xs:string' use='required'/>
<xs:attribute name='password' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
<xs:element name='offline-messages'>
<xs:complexType>
<xs:sequence>
<xs:any namespace='##other' minOccurs='0' maxOccurs='unbounded'/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
1. RFC 3921: Extensible Messaging and Presence Protocol (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc3921>.
2. XEP-0049: Private XML Storage <http://www.xmpp.org/extensions/xep-0049.html>.
3. XEP-0054: vcard-temp <http://www.xmpp.org/extensions/xep-0054.html>.
4. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://www.xmpp.org/registrar/>.
5. XEP-0053: XMPP Registrar Function <http://www.xmpp.org/extensions/xep-0053.html>.
Initial published version.
(psa)Initial version.
(mh)END