Wiki source code of Backup/Restore

Last modified by Vincent Massol on 2024/12/17

Hide last authors
Thomas Steinbach 5.3 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
Ludovic Dubost 5.1 4
Vincent Massol 10.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.
Vincent Massol 1.1 6
Vincent Massol 22.3 7 There are several parts that need to be backed up:
Vincent Massol 1.1 8
Vincent Massol 22.2 9 * The database
10 * The XWiki WAR file
Thomas Mortagne 32.1 11 * The Permanent data (located in the [[XWiki permanent directory>>Documentation.AdminGuide.Configuration||anchor="HConfiguringDirectories"]])
Vincent Massol 22.2 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**:(((
Thomas Mortagne 34.1 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).
Vincent Massol 22.2 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 )))
Nikita Petrenko 34.2 25 * **PostgreSQL**: You can use {{code language="none"}}psql{{/code}} shell with the command {{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. Alternatively to the shell, you can use the GUI application pgAdmin by selecting the database and from the context menu selecting Backup.
Vincent Massol 22.2 26 * **Oracle**: Use ##exp## to export data.
Vincent Massol 26.1 27 * **HSQLDB**: Simply backup the HSQLDB directory. For the XWiki standalone packaging it's the ##data/## directory.
Vincent Massol 22.2 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
Vincent Massol 8.3 37 There are several configuration files you'll need to backup:
Ludovic Dubost 4.1 38
Vincent Massol 8.3 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)
Vincent Massol 1.1 44
Manuel Smeria 13.2 45 To restore them simply copy them at the same location where you backed them up from.
Vincent Massol 1.1 46
Vincent Massol 10.3 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.
Guillaume Fenollar 8.1 48
Vincent Massol 22.2 49 == Custom filesystem Skins ==
50
Vincent Massol 27.2 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.
Vincent Massol 22.2 52
Vincent Massol 10.1 53 = Backup Permanent Data =
Vincent Massol 1.1 54
Thomas Mortagne 32.1 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.
Marc Lijour 17.1 56
Vincent Massol 30.1 57 Notes:
Thomas Mortagne 34.1 58
Vincent Massol 30.1 59 * 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.
Vincent Massol 1.1 60
Vincent Massol 22.2 61 = Backup Log files =
62
Manuel Smeria 13.2 63 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.
Vincent Massol 10.1 64
Vincent Massol 30.4 65 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.
Vincent Massol 10.1 66
Vincent Massol 10.5 67 = Using the XWiki Export feature =
Vincent Massol 1.1 68
Vincent Massol 36.1 69 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, 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.
Vincent Massol 1.1 70
Vincent Massol 10.1 71 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:
Marc Lijour 17.1 72
Vincent Massol 30.2 73 * Event stream data
Vincent Massol 10.1 74 * Statistics data
75 * Feed plugin data (if you use it)
76 * Deleted documents/attachments data
Vincent Massol 21.1 77 * XWiki Instance Id
78 * Mail Statuses
Vincent Massol 33.1 79 * User Notifications & [[user notification settings>>https://jira.xwiki.org/browse/XWIKI-21300]]
Thomas Mortagne 34.1 80 * Rating (which include page likes)
Vincent Massol 31.1 81 * Unprocessed mentions(waiting in the queue to be processed)
82 * The unique identifier of the XWiki instance in a cluster
Ludovic Dubost 4.1 83
Vincent Massol 21.2 84 Moreover this won't save configuration data or other Permanent Data mentioned above such as installed Extensions, Lucene/SOLR index files and Logs.
Vincent Massol 10.1 85
Manuel Smeria 13.2 86 In practice the Import/Export feature should be reserved for the following use cases:
Marc Lijour 17.1 87
Vincent Massol 1.5 88 * move data across XWiki instances, including sharing of applications between separate instances
89 * move data to another wiki
Vincent Massol 14.1 90 * convert from one database to another
Marc Lijour 15.1 91
92 = Restore your data =
93
Vincent Massol 16.1 94 * **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.(((
Thomas Mortagne 34.1 95 * 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)
96 * Delete the existing ##xwiki## database if any: {{code language="shell"}}mysql -e "DROP DATABASE xwiki;"{{/code}} (better to start fresh)
97 * Recreate the ##xwiki## database: {{code language="shell"}}mysql -e "CREATE DATABASE IF NOT EXISTS xwiki DEFAULT CHARACTER SET utf8;"{{/code}}.
98 * 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]).
99 * Re-enable constraints checks: {{code language="shell"}}mysql -e "SET FOREIGN_KEY_CHECKS=1;"{{/code}}
Marc Lijour 15.1 100
Vincent Massol 16.1 101 That is not all, now you need to restore the xwiki user rights (assuming the ##xwiki## user exists in MySQL).
Marc Lijour 17.1 102
Vincent Massol 24.2 103 * Update the xwiki user password from the (previously restored) hibernate configuration file(((
Thomas Mortagne 34.1 104 {{code language="none"}}
Vincent Massol 16.2 105 pass=$(cat /etc/xwiki/hibernate.cfg.xml | grep passw| head -1 | sed -e 's/^.*<prop.*password">//' | sed -e 's|</property>.*||')
Marc Lijour 15.1 106 mysql -e "SET PASSWORD FOR 'xwiki'@'localhost' = PASSWORD('$pass');"
107 {{/code}}
Vincent Massol 16.1 108 )))
109
Thomas Mortagne 34.1 110 Finally, restart you container, for example in Linux: {{code language="shell"}}service tomcat7 restart{{/code}}
Marc Lijour 15.1 111 )))
Nikita Petrenko 35.1 112 * **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. As during backup, the GUI of pgAdmin here can be used after the xwiki database was created; from the context menu, select Restore, and in the explore window, locate the backup file where it was stored previously. Don't forget to select All files in order to see that file.
Vincent Massol 16.1 113 * **Oracle**: Use ##imp##.
Marc Lijour 15.1 114
Vincent Massol 16.2 115 = Tips in case you are using nginx =
116
Thomas Mortagne 34.1 117 Assuming you have a nginx configuration with a {{code language="shell"}}server_name{{/code}} entry that needs updating, the following script might be useful.
Marc Lijour 15.1 118
Thomas Mortagne 34.1 119 {{code language="bash"}}
Marc Lijour 15.1 120 #!/bin/bash
121 configfile="/etc/nginx/sites-available/xwiki-as-root.conf"
122 # The following line works for Amazon EC2 instances. Change accordingly to find this host's IP dynamically.
123 thisip=$(curl -s http://instance-data/latest/meta-data/public-ipv4)
124 if [ ! -f $configfile ]; then
Ecaterina Moraru (Valica) 25.4 125 echo "Missing file: $configfile"
126 exit 1
Marc Lijour 15.1 127 fi
128 echo backing-up $configfile
129 cp $configfile $configfile-old
130
131 echo Setting nginx server_name to $thisip
132 old=$(cat $configfile | grep '^\ *server_name' | awk '{print $2}' | sed -e 's/;//' | grep "$thipip" | head -1)
133 if [ $? -eq 0 ] ; then
Ecaterina Moraru (Valica) 25.4 134 echo Fixing server_name
135 cat $configfile | sed -e "s/$old/$thisip/" > $configfile-new
136 mv $configfile-new $configfile
Marc Lijour 15.1 137 fi
138
139 echo Done. New config file:
140 cat $configfile
141
142 echo restarting nginx
143 service nginx restart
144 {{/code}}
markgard 20.1 145
146 = Sample Backup Script =
Vincent Massol 22.2 147
Thomas Mortagne 34.1 148 {{code language="bash"}}
markgard 20.1 149 #!/bin/bash
150
151 #Space Separated List of Databases to Dump
152 #DATABASE="xwiki d1 d3"
153 DATABASE="xwiki"
154 DBUSER=root
155 DBPASS=*****
156
157 #XWIKI data folder
158 DATAFOLDER=/srv/tomcat6/data/
159 #Where is the webapps folder for your tomcat installation
160 # SLES 11 is located /srv/tomcat6/webapps
161 WEBAPPDIR=/srv/tomcat6/webapps
162 #What context (dir) does your application deploy to
163 DEPLOYCONTEXT=ROOT
164
165
166 ###~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167 DEPLOYDIR=${WEBAPPDIR}/${DEPLOYCONTEXT}
168 DATE=$(date '+%Y-%m-%d')
169 mkdir ./${DATE}
170
171 #backup mysql
172 echo "Backing up Mysql"
173 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
174
175 echo "Backing up Data"
176 #Backup Exteral Data Storage
177 /bin/tar -C ${DATAFOLDER}/../ -zcf ./${DATE}/data.tar.gz data
178
179 #Backing Java Keystore
180 /bin/cp /srv/tomcat6/.keystore ./${DATE}/.keystore
181
182 echo "Backing up xwiki configuration"
183 /bin/cp ${DEPLOYDIR}/WEB-INF/hibernate.cfg.xml ./${DATE}/hibernate.cfg.xml
184 /bin/cp ${DEPLOYDIR}/WEB-INF/xwiki.cfg ./${DATE}/xwiki.cfg
185 /bin/cp ${DEPLOYDIR}/WEB-INF/xwiki.properties ./${DATE}/xwiki.properties
186
187 #Backup Deploy Context
188 echo "Backing UP deploy Context"
189 /bin/tar -C ${DEPLOYDIR}/../ -zcf ./${DATE}/ROOT.tar.gz ROOT
190
191 echo "DONE"
192 {{/code}}

Get Connected