Differences
This shows you the differences between two versions of the page.
|
specification:auto:backuprestore [2010/03/10 12:16] anthony |
specification:auto:backuprestore [2010/06/17 10:32] (current) anthony |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ====== Backup/restore OBM data ====== | ====== Backup/restore OBM data ====== | ||
| - | |||
| - | Status : **Draft** | ||
| ===== Purpose ===== | ===== Purpose ===== | ||
| - | Allow to backup/restore OBM data, in 2 ways : | + | Allow to backup OBM data, in 2 ways : |
| - | * global backup/restore | + | * global backup |
| - | * per entity backup/restore | + | * per entity backup |
| - | ==== Global ==== | + | Allow to restore OBM data per entity. |
| - | ==== Per entity ==== | + | Backup entities type : |
| - | + | ||
| - | Allow to backup/restore per entity OBM data. Not all entities need this backup/restore kind : | + | |
| ^ Entity ^ linked data ^ | ^ Entity ^ linked data ^ | ||
| Line 19: | Line 15: | ||
| | | calendar | | | | calendar | | ||
| | | contacts | | | | contacts | | ||
| - | | | ACLs (?) | | ||
| | mailshare | mailbox data | | | mailshare | mailbox data | | ||
| - | | | ACLs (?) | | ||
| ===== Backup ===== | ===== Backup ===== | ||
| Line 29: | Line 23: | ||
| Backup are stored in **/var/backup/obm/<obmDomainName>/<login>-<date>.tar.gz** on corresponding BAL IMAP back-end. | Backup are stored in **/var/backup/obm/<obmDomainName>/<login>-<date>.tar.gz** on corresponding BAL IMAP back-end. | ||
| - | If a FTP role host is attached to OBM domain, all backup archive are pushed on it. | + | If a [[specification:services#backup_service|backup FTP service]] is attached to OBM domain, backup archive are pushed on it. |
| Backups are a tar zipped archive containing : | Backups are a tar zipped archive containing : | ||
| - | * BAL in a tar zipped archive named **backupBal.tar.gz** | + | * Mailbox : **<login>@<realm>/mailbox/backupBal.tar.gz** |
| - | * Calendar in ICS form, store in named file **calendarExport.ics** | + | * Calendar in base64 encoded ICS form : **<login>@<realm>/ics/calendarExport.ics** |
| - | * Private contacts in VCard form, store in named file **privateContacts.csv** | + | * Private contacts in base64 encoded VCard form : **<login>@<realm>/vcard/privateContacts.vcf** |
| + | |||
| + | Backup report is send to **x-obm-backup@<realm>**, except if //sendMail// attribute is false. | ||
| ==== How it works ==== | ==== How it works ==== | ||
| Line 47: | Line 43: | ||
| | | realm : OBM entity corresponding domain name | | | | realm : OBM entity corresponding domain name | | ||
| | Method | PUT | | | Method | PUT | | ||
| - | | Content | [[#backup_xml_dtd_request_content|XML]] | | + | | Content | [[#backup_xml_schema_request_content|XML]] | |
| Example : | Example : | ||
| Line 57: | Line 53: | ||
| Global backup is done by a cron. This cron run [[#per_entity|per entity]] backup on all OBM domain entities. | Global backup is done by a cron. This cron run [[#per_entity|per entity]] backup on all OBM domain entities. | ||
| - | ==== Backup XML DTD request content ==== | + | === Miscellaneous === |
| + | |||
| + | * mail report is sent by default, except if //mailSend// attribute on //report// XML request element is set to **false** | ||
| + | * mail report is sent, at least to //x-obm-backup@<obm-domain-name>// and to each of //email// XML request element | ||
| + | * backup are uploaded to backup FTP server by default, except if //push// attribute on //ftp// XML request element is set to **false** | ||
| + | |||
| + | ==== Backup XML schema request content ==== | ||
| <code> | <code> | ||
| - | <!ELEMENT obmSatellite (privateContact?, calendar?)> | + | <?xml version="1.0" encoding="utf-8"?> |
| - | <!ATTLIST obmSatellite | + | <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> |
| - | module CDATA #FIXED "backupEntity" | + | <xsd:element name="obmSatellite"> |
| - | > | + | <xsd:complexType> |
| - | <!ELEMENT privateContact (#CDATA)> | + | <xsd:sequence> |
| - | <!ELEMENT calendar (#CDATA)> | + | <xsd:element minOccurs="0" name="options"> |
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" name="report"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" maxOccurs="unbounded" name="email" type="xsd:string" /> | ||
| + | </xsd:sequence> | ||
| + | <xsd:attribute name="sendMail" type="xsd:boolean" /> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | <xs:element minOccurs="0" name="ftp"> | ||
| + | <xs:complexType> | ||
| + | <xs:attribute name="push" type="xs:boolean" use="required" /> | ||
| + | </xs:complexType> | ||
| + | </xs:element> | ||
| + | </xsd:sequence> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | <xsd:element minOccurs="0" name="calendar" type="xsd:string" /> | ||
| + | <xsd:element minOccurs="0" name="privateContact"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element maxOccurs="unbounded" name="addressBook"> | ||
| + | <xs:simpleContent> | ||
| + | <xs:extension base="xs:string"> | ||
| + | <xs:attribute name="name" type="xs:string" use="required" /> | ||
| + | </xs:extension> | ||
| + | </xs:simpleContent> | ||
| + | </xsd:element> | ||
| + | </xsd:sequence> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | </xsd:sequence> | ||
| + | <xsd:attribute name="module" type="moduleType" use="required" /> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | |||
| + | <xs:simpleType name="moduleType"> | ||
| + | <xs:restriction base="xs:string"> | ||
| + | <xs:enumeration value="backupEntity";/>; | ||
| + | </xs:restriction> | ||
| + | </xs:simpleType> | ||
| + | </xsd:schema> | ||
| </code> | </code> | ||
| + | |||
| + | ===== Restore ===== | ||
| + | |||
| + | ==== Getting available backup file ==== | ||
| + | |||
| + | To get available backup file you can contact obmSatellite which run with **backupEntity** enabled module. | ||
| + | |||
| + | | Get available backup files URL | /availablebackup/<entity>/<login>@<realm> | | ||
| + | | | entity : possible backup entity type | | ||
| + | | | login : OBM entity login | | ||
| + | | | realm : OBM entity corresponding domain name | | ||
| + | | Method | GET | | ||
| + | | Content | | | ||
| + | |||
| + | Example : | ||
| + | |||
| + | * /availablebackup/user/toto@foo.org | ||
| + | * /availablebackup/mailshare/titi@foo.org | ||
| + | |||
| + | |||
| + | === Available backup file response XML === | ||
| + | |||
| + | If request done successfully, response content is XML : | ||
| + | <code> | ||
| + | <?xml version="1.0" encoding="utf-8"?> | ||
| + | <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
| + | <xsd:element name="obmSatellite"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" maxOccurs="unbounded" name="backupFile" type="xsd:string" /> | ||
| + | </xsd:sequence> | ||
| + | <xsd:attribute name="module" type="moduleType" use="required" /> | ||
| + | <xsd:attribute name="status" type="xsd:string" use="required" /> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | |||
| + | <xs:simpleType name="moduleType"> | ||
| + | <xs:restriction base="xs:string"> | ||
| + | <xs:enumeration value="backupEntity"/> | ||
| + | </xs:restriction> | ||
| + | </xs:simpleType> | ||
| + | </xsd:schema> | ||
| + | </code> | ||
| + | |||
| + | ==== Restore from archive ==== | ||
| + | |||
| + | To restore data from available backup file you can contact obmSatellite which run with **backupEntity** enabled module. | ||
| + | |||
| + | | Get available backup files URL | /restoreentity/<entity>/<login>@<realm>[/<data>] | | ||
| + | | | entity : possible backup entity type (//user|mailshare//) | | ||
| + | | | login : OBM entity login | | ||
| + | | | realm : OBM entity corresponding domain name | | ||
| + | | | data : backup data (//mailbox|contact|calendar//). If none were specified, all backup data were restore | | ||
| + | | Method | POST | | ||
| + | | Content | [[#restore_xml_schema_request_content|XML]] | | ||
| + | |||
| + | |||
| + | Example : | ||
| + | |||
| + | * /restoreentity/user/toto@foo.org | ||
| + | * /restoreentity/mailshare/titi@foo.org | ||
| + | |||
| + | === Restore XML schema request content === | ||
| + | |||
| + | <code> | ||
| + | <?xml version="1.0" encoding="utf-8"?> | ||
| + | <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
| + | <xsd:element name="obmSatellite"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" name="options"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" name="report"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" maxOccurs="unbounded" name="email" type="xsd:string" /> | ||
| + | </xsd:sequence> | ||
| + | <xsd:attribute name="sendMail" type="xsd:boolean" /> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | </xsd:sequence> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | <xsd:element name="backupFile" type="xsd:string" /> | ||
| + | </xsd:sequence> | ||
| + | <xsd:attribute name="module" type="moduleType" use="required" /> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | |||
| + | <xs:simpleType name="moduleType"> | ||
| + | <xs:restriction base="xs:string"> | ||
| + | <xs:enumeration value="backupEntity"/> | ||
| + | </xs:restriction> | ||
| + | </xs:simpleType> | ||
| + | </xsd:schema> | ||
| + | </code> | ||
| + | |||
| + | === Restore XML schema response content === | ||
| + | |||
| + | <code> | ||
| + | <?xml version="1.0" encoding="utf-8"?> | ||
| + | <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
| + | <xsd:element name="obmSatellite"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element name="calendar" type="xsd:string" /> | ||
| + | <xsd:element name="privateContact" type="xsd:string" /> | ||
| + | </xsd:sequence> | ||
| + | <xsd:attribute name="status" type="xsd:string" use="required" /> | ||
| + | <xsd:attribute name="module" type="moduleType" use="required" /> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | |||
| + | <xs:simpleType name="moduleType"> | ||
| + | <xs:restriction base="xs:string"> | ||
| + | <xs:enumeration value="backupEntity"/> | ||
| + | </xs:restriction> | ||
| + | </xs:simpleType> | ||
| + | </xsd:schema> | ||
| + | </code> | ||
| + | |||
| + | === Miscellaneous === | ||
| + | |||
| + | * mail report is sent by default, except if //mailSend// attribute on //report// XML request element is set to **false** | ||
| + | * mail report is sent, at least to //x-obm-backup@<obm-domain-name>// and to each of //email// XML request element | ||
| + | * backup are uploaded to backup FTP server by default, except if //push// attribute on //ftp// XML request element is set to **false** | ||
| + | |||
| + | ==== Retrieve archive from backup FTP server ==== | ||
| + | |||
| + | To retrieve available backups files from OBM domain backup FTP server, you can contact obmSatellite which run with **backupEntity** enabled module. | ||
| + | |||
| + | | Retrieve backups from backup FTP server | /retrievebackup/<entity>/<login>@<realm> | | ||
| + | | | entity : possible backup entity type | | ||
| + | | | login : OBM entity login | | ||
| + | | | realm : OBM entity corresponding domain name | | ||
| + | | Method | POST | | ||
| + | | Content | XML | | ||
| + | |||
| + | Example : | ||
| + | |||
| + | * /retrievebackup/user/toto@foo.org | ||
| + | * /retrievebackup/mailshare/titi@foo.org | ||
| + | |||
| + | === Retrieve archive XML schema request content === | ||
| + | |||
| + | <code> | ||
| + | <?xml version="1.0" encoding="utf-8"?> | ||
| + | <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
| + | <xsd:element name="obmSatellite"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" name="options"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" name="report"> | ||
| + | <xsd:complexType> | ||
| + | <xsd:sequence> | ||
| + | <xsd:element minOccurs="0" maxOccurs="unbounded" name="email" type="xsd:string" /> | ||
| + | </xsd:sequence> | ||
| + | <xsd:attribute name="sendMail" type="xsd:boolean" /> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | </xsd:sequence> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | </xsd:sequence> | ||
| + | <xsd:attribute name="module" type="moduleType" use="required" /> | ||
| + | </xsd:complexType> | ||
| + | </xsd:element> | ||
| + | |||
| + | <xs:simpleType name="moduleType"> | ||
| + | <xs:restriction base="xs:string"> | ||
| + | <xs:enumeration value="backupEntity"/> | ||
| + | </xs:restriction> | ||
| + | </xs:simpleType> | ||
| + | </xsd:schema> | ||
| + | </code> | ||
| + | |||
