Wiki source code of Backup/Restore

Last modified by Thomas Mortagne on 2023/10/10

Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 It's crucial that you define a backup strategy for your wiki so that you don't lose any data in case of a problem with your wiki installation or in case you have issues upgrading your XWiki instance to a newer version.
6
7 There are several parts that need to be backed up:
8
9 * The database
10 * The XWiki WAR file
11 * The Permanent data (located in the [[XWiki permanent directory>>Documentation.AdminGuide.Configuration||anchor="HConfiguringDirectories"]])
12 * Log files (optional)
13
14 = Backup your database =
15
16 If you've installed XWiki using your own database then you'll need a backup tool for that database to back it up and to restore it. Moreover, if you're backing up a huge amount of data, we advise that you compress the dump files to save disk space (for example with [[7-zip>>http://www.7-zip.org/]]).
17
18 * **MySQL**:(((
19 Backup: {{code language='shell'}}mysqldump --add-drop-database --databases xwiki > xwiki.sql{{/code}} backs up the xwiki schema (use the option ##~-~-all-databases## instead of ##~-~-databases xwiki## if you want to backup the whole XWiki istance with all its subwikis).
20
21 {{warning}}
22 It's important that the backup is done with ##~-~-add-drop-database## since when you restore it it's important that tables that might have been created are removed. For example database migrations can create extra tables. If you want to cancel the migration and go back to your clean dump you'll need to have those tables removed as otherwise when you run the migration again later on you might have errors.
23 {{/warning}}
24 )))
25 * **PostgreSQL**: You can use {{code language='shell'}}pg_dump xwiki > xwiki.sql{{/code}} to backup the PostgreSQL database. In case of backing up the whole instance, use the binary ##pg_dumpall## instead.
26 * **Oracle**: Use ##exp## to export data.
27 * **HSQLDB**: Simply backup the HSQLDB directory. For the XWiki standalone packaging it's the ##data/## directory.
28
29 = Backup the XWiki WAR =
30
31 To be on the safe side you can and should backup the whole XWiki WAR file (that's the file that was expanded and deployed in your Servlet Container when XWiki was installed).
32
33 More specifically the WAR contains mostly static files that are not changed. However it also contains some configuration files for XWiki and you really want to backup those, as explained below.
34
35 == Configuration files ==
36
37 There are several configuration files you'll need to backup:
38
39 * ##WEB-INF/hibernate.cfg.xml## (Hibernate configuration)
40 * ##WEB-INF/xwiki.cfg## (old XWiki configuration file but still used)
41 * ##WEB-INF/xwiki.properties## (new XWiki Configuration file)
42 * ##WEB-INF/classes/logback.xml## (Logging configuration)
43 * ##WEB-INF/observation/*## (Cluster configuration)
44
45 To restore them simply copy them at the same location where you backed them up from.
46
47 In addition you may want to also backup any extra files you'll have installed in your XWiki installation such as JDBC drivers, extra plugins, etc.
48
49 == Custom filesystem Skins ==
50
51 If you have a custom skin that is stored on the filesystem, make sure you backup the corresponding folder located in the ##webapps/xwiki/skins/## directory.
52
53 = Backup Permanent Data =
54
55 XWiki generates & saves data in the [[permanent directory>>Documentation.AdminGuide.Configuration||anchor="HConfiguringDirectories"]] of XWiki and it's important that you back it up.
56
57 Notes:
58 * The ##cache## directory can be removed and does not necessarily need to be backed up. However if you don't back it up, XWiki will need to regenerate its content (e.g. the Solr seach indexes) and that can take a lot of time. It's thus recommended to back it up too.
59
60 = Backup Log files =
61
62 XWiki generates logs in the console by default and these will go where your Servlet container has been defined to save them. For Tomcat for example this usually goes in the ##TOMCAT_HOME/logs/catalina.out## file.
63
64 However this is fully [[configurable>>Documentation.AdminGuide.Logging]] and you may have configured XWiki to output log files elsewhere. If you want to keep those logs, don't forget to save them. Those logs are not needed by XWiki but you may want to save them to review them later on to diagnose issues that happened for example.
65
66 = Using the XWiki Export feature =
67
68 Since most XWiki data is saved in wiki pages one solution to backup a XWiki instance is to export all its pages using XWiki's [[Import/Export feature>>Documentation.AdminGuide.ImportExport]]. However note that this is quite a resource hungry operation and depending on the size of your wiki you may need a lot of memory. As a consequence the recommended backup strategy is to backup the databases. It's much better to use a specialized backup tool that'll backup the database, perform incremental backups, verify backup integrity, etc.
69
70 In addition you should know that currently the following information is not located in wiki pages and is thus not saved in a wiki export:
71
72 * Event stream data
73 * Statistics data
74 * Feed plugin data (if you use it)
75 * Deleted documents/attachments data
76 * XWiki Instance Id
77 * Mail Statuses
78 * User Notifications
79 * Page Likes
80 * Unprocessed mentions(waiting in the queue to be processed)
81 * The unique identifier of the XWiki instance in a cluster
82
83 Moreover this won't save configuration data or other Permanent Data mentioned above such as installed Extensions, Lucene/SOLR index files and Logs.
84
85 In practice the Import/Export feature should be reserved for the following use cases:
86
87 * move data across XWiki instances, including sharing of applications between separate instances
88 * move data to another wiki
89 * convert from one database to another
90
91 = Restore your data =
92
93 * **MySQL**: Assuming you have your ##xwiki.sql## file handy (obtained running ##mysqldump## as explained above), run the following from the command line (or a script). Examples below are for the Linux shell.(((
94 * Disable constraints check first: {{code language='shell'}}mysql -e "SET FOREIGN_KEY_CHECKS=0;"{{/code}} (restoring may fail with some cryptic error code, leaving the database in an inconsistent state, if you omit this step)
95 * Delete the existing ##xwiki## database if any: {{code language='shell'}}mysql -e "DROP DATABASE xwiki;"{{/code}} (better to start fresh)
96 * Recreate the ##xwiki## database: {{code language='shell'}}mysql -e "CREATE DATABASE IF NOT EXISTS xwiki DEFAULT CHARACTER SET utf8;"{{/code}}.
97 * Restore data from the dump file: {{code language='shell'}}mysql xwiki --user=root -p < xwiki.sql{{/code}}. Alternatively, you can omit the ##-p## by adding a section [mysqldump] in your ##.my.cnf## file (with a user and password line, same as for [mysql]).
98 * Re-enable constraints checks: {{code language='shell'}}mysql -e "SET FOREIGN_KEY_CHECKS=1;"{{/code}}
99
100 That is not all, now you need to restore the xwiki user rights (assuming the ##xwiki## user exists in MySQL).
101
102 * Update the xwiki user password from the (previously restored) hibernate configuration file(((
103 {{code language='none'}}
104 pass=$(cat /etc/xwiki/hibernate.cfg.xml | grep passw| head -1 | sed -e 's/^.*<prop.*password">//' | sed -e 's|</property>.*||')
105 mysql -e "SET PASSWORD FOR 'xwiki'@'localhost' = PASSWORD('$pass');"
106 {{/code}}
107 )))
108
109 Finally, restart you container, for example in Linux: {{code language='shell'}}service tomcat7 restart{{/code}}
110 )))
111 * **PostgreSQL**: {{code language='shell'}}psql -d xwiki -f xwiki.sql{{/code}} to restore your previously saved data. In full instance backup mode, use {{code language='shell'}}psql -d postgres -f xwiki.sql{{/code}} instead.
112 * **Oracle**: Use ##imp##.
113
114 = Tips in case you are using nginx =
115
116 Assuming you have a nginx configuration with a {{code language='shell'}}server_name{{/code}} entry that needs updating, the following script might be useful.
117
118 {{code language='bash'}}
119 #!/bin/bash
120 configfile="/etc/nginx/sites-available/xwiki-as-root.conf"
121 # The following line works for Amazon EC2 instances. Change accordingly to find this host's IP dynamically.
122 thisip=$(curl -s http://instance-data/latest/meta-data/public-ipv4)
123 if [ ! -f $configfile ]; then
124 echo "Missing file: $configfile"
125 exit 1
126 fi
127 echo backing-up $configfile
128 cp $configfile $configfile-old
129
130 echo Setting nginx server_name to $thisip
131 old=$(cat $configfile | grep '^\ *server_name' | awk '{print $2}' | sed -e 's/;//' | grep "$thipip" | head -1)
132 if [ $? -eq 0 ] ; then
133 echo Fixing server_name
134 cat $configfile | sed -e "s/$old/$thisip/" > $configfile-new
135 mv $configfile-new $configfile
136 fi
137
138 echo Done. New config file:
139 cat $configfile
140
141 echo restarting nginx
142 service nginx restart
143 {{/code}}
144
145 = Sample Backup Script =
146
147 {{code language='bash'}}
148 #!/bin/bash
149
150 #Space Separated List of Databases to Dump
151 #DATABASE="xwiki d1 d3"
152 DATABASE="xwiki"
153 DBUSER=root
154 DBPASS=*****
155
156 #XWIKI data folder
157 DATAFOLDER=/srv/tomcat6/data/
158 #Where is the webapps folder for your tomcat installation
159 # SLES 11 is located /srv/tomcat6/webapps
160 WEBAPPDIR=/srv/tomcat6/webapps
161 #What context (dir) does your application deploy to
162 DEPLOYCONTEXT=ROOT
163
164
165 ###~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166 DEPLOYDIR=${WEBAPPDIR}/${DEPLOYCONTEXT}
167 DATE=$(date '+%Y-%m-%d')
168 mkdir ./${DATE}
169
170 #backup mysql
171 echo "Backing up Mysql"
172 mysqldump -h 127.0.0.1 -u ${DBUSER} --password=${DBPASS} --max_allowed_packet=512m --add-drop-database --databases ${DATABASE} | /bin/gzip > ./${DATE}/${DATABASE}.sql.gz
173
174 echo "Backing up Data"
175 #Backup Exteral Data Storage
176 /bin/tar -C ${DATAFOLDER}/../ -zcf ./${DATE}/data.tar.gz data
177
178 #Backing Java Keystore
179 /bin/cp /srv/tomcat6/.keystore ./${DATE}/.keystore
180
181 echo "Backing up xwiki configuration"
182 /bin/cp ${DEPLOYDIR}/WEB-INF/hibernate.cfg.xml ./${DATE}/hibernate.cfg.xml
183 /bin/cp ${DEPLOYDIR}/WEB-INF/xwiki.cfg ./${DATE}/xwiki.cfg
184 /bin/cp ${DEPLOYDIR}/WEB-INF/xwiki.properties ./${DATE}/xwiki.properties
185
186 #Backup Deploy Context
187 echo "Backing UP deploy Context"
188 /bin/tar -C ${DEPLOYDIR}/../ -zcf ./${DATE}/ROOT.tar.gz ROOT
189
190 echo "DONE"
191 {{/code}}

Get Connected