rt/docs/backups.pod

   1 =head1 BACKUPS
   2
   3 RT is often a critical piece of businesses and organizations.  Backups are
   4 absolutely necessary to ensure you can recover quickly from an incident.
   5
   6 Make sure you take backups.  Make sure they I<work>.
   7
   8 There are many issues that can cause broken backups, such as a
   9 C<max_allowed_packet> too low for MySQL (in either the client or server), or
  10 encoding issues, or running out of disk space.
  11
  12 Make sure your backup cronjobs notify someone if they fail instead of failing
  13 silently until you need them.
  14
  15 Test your backups regularly to discover any unknown problems B<before> they
  16 become an issue.  You don't want to discover problems with your backups while
  17 tensely restoring from them in a critical data loss situation.
  18
  19 =head2 DATABASE
  20
  21 You should backup the entire RT database, although for improved speed and space
  22 you can ignore the I<data> in the C<sessions> table.  Make sure you still get
  23 the C<sessions> schema, however.
  24
  25 Database specific notes and example backup commands for each database are
  26 below.  Adjust the commands as necessary for connection details such as
  27 database name (C<rt4> is the placeholder below), user, password, host, etc.
  28 You should put the example commands into a shell script for backup and setup a
  29 cronjob.  Make sure output from cron goes to someone who reads mail!  (Or into
  30 RT. :)
  31
  32 =head3 MySQL
  33
  34     ( mysqldump rt4 --tables sessions --no-data --single-transaction; \
  35       mysqldump rt4 --ignore-table rt4.sessions --single-transaction ) \
  36         | gzip > rt-`date +%Y%m%d`.sql.gz
  37
  38 The dump will be much faster if you can connect to the MySQL server over
  39 localhost.  This will use a local socket instead of the network.
  40
  41 If you find your backups taking far far too long to complete (this point should
  42 take quite a long time to get to on an RT database), there are some alternate
  43 solutions.  Percona maintains a highly regarded hot-backup tool for MySQL
  44 called L<XtraBackup|http://www.percona.com/software/percona-xtrabackup/>.  If
  45 you have more resources, you can also setup replication to a slave using binary
  46 logs and backup from there as necessary.  This not only duplicates the data,
  47 but lets you take backups without putting load on your production server.
  48
  49 =head4 Restoring from backups
  50
  51 =over
  52
  53 =item New Database Server (Catastrophic Failure)
  54
  55 If you are starting fresh with a new database server (because your old
  56 one no longer works or because you want to set up a dev machine to
  57 test on) you will need to create a fresh database and database user
  58 for RT to use.  RT can do that for you using:
  59
  60     /opt/rt4/sbin/rt-setup-database --action create,acl
  61
  62 By default, this will create an rt4 database and an rt_user user.  If
  63 you've specified a custom password in RT_SiteConfig.pm, RT will use
  64 that.  Once the database and user exist, you can restore from your
  65 backup using:
  66
  67     gunzip -c rt-20141014.sql.gz | mysql -uroot -p rt4
  68
  69 Changing -uroot -p as needed to access the database as a user with
  70 enough rights to handle creating tables.
  71
  72 =item Restore over an existing database
  73
  74 If something terrible happened this morning and you want to roll back to
  75 your backups, or if you want to update a dev server using your backups,
  76 this is straightforward on MySQL.
  77
  78     gunzip -c rt-20141014.sql.gz | mysql -uroot -p rt4
  79
  80 MySQL will drop any existing tables before recreating and repopulating
  81 them.  It will leave the database and the rt_user untouched.  This is
  82 not suitable for restoring on a fresh database install since there will
  83 be no rt4 database or rt_user user.
  84
  85 =back
  86
  87 =head3 PostgreSQL
  88
  89     ( pg_dump rt4 --table=sessions --schema-only; \
  90       pg_dump rt4 --exclude-table=sessions ) \
  91         | gzip > rt-`date +%Y%m%d`.sql.gz
  92
  93 =head4 Restoring from backups
  94
  95 =over
  96
  97 =item New Database Server (Catastrophic Failure)
  98
  99 If you are starting fresh with a new database server (because your old
 100 one no longer works or because you want to set up a dev machine to
 101 test on) you will need to create a fresh database and database user
 102 for RT to use.  RT can do part of that for you using:
 103
 104     /opt/rt4/sbin/rt-setup-database --action create
 105
 106 You will need to create the rt_user separately.
 107
 108     createuser -P rt_user
 109
 110 This will prompt you for a password.  You should ensure that it is the
 111 same password you have configured in RT_SiteConfig.pm or RT_Config.pm
 112 using C<$DatabasePassword>.
 113
 114 Once the database and user exist, you can restore from your backup which
 115 will create tables, insert data and configure rights for your rt_user
 116 user.
 117
 118     gunzip -c rt-20141014.sql.gz | psql rt4
 119
 120 This may need to be run as the postgres user or some other admin level
 121 user who can create tables.
 122
 123 =item Restore over an existing database
 124
 125 If something terrible happened this morning and you want to roll back to
 126 your backups, or if you want to update a dev server using your backups,
 127 you will need to drop your database and recreate a fresh one to restore
 128 into.  RT can drop and recreate the database for you using:
 129
 130     /opt/rt4/sbin/rt-setup-database --action drop
 131     /opt/rt4/sbin/rt-setup-database --action create
 132
 133 Remember that this will completely destroy the existing data and create
 134 a fresh database.  Your rt_user user will remain untouched.  Once this
 135 is complete, you can restore from your backup which will create tables
 136 and insert data and configure rights for the rt_user.
 137
 138     gunzip -c rt-20141014.sql.gz | psql rt4
 139
 140 =item After Restoring
 141
 142 Postgres will generally perform poorly after restoring from backups
 143 because it has outdated index statistics. You should run C<analyze>
 144 after your restore is complete. If you'd like to watch the progress, you
 145 can run C<analyze verbose>.
 146
 147 =back
 148
 149 =head2 FILESYSTEM
 150
 151 You will want to back up, at the very least, the following directories and files:
 152
 153 =over 4
 154
 155 =item /opt/rt4
 156
 157 RT's source code, configuration, GPG data, and plugins.  Your install location
 158 may be different, of course.
 159
 160 You can omit F<var/mason_data> and F<var/session_data> if you'd like since
 161 those are temporary caches.  Don't omit all of F<var/> however as it may
 162 contain important GPG data.
 163
 164 =item Webserver configuration
 165
 166 Often F</etc/httpd> or F</etc/apache2>.  This will depend on your OS, web
 167 server, and internal configuration standards.
 168
 169 =item /etc/aliases
 170
 171 Your incoming mail aliases mapping addresses to queues.
 172
 173 =item Mail server configuration
 174
 175 If you're running an MTA like Postfix, Exim, SendMail, or qmail, you'll want to
 176 backup their configuration files to minimize restore time.  "Lightweight" mail
 177 handling programs like fetchmail, msmtp, and ssmtp will also have configuration
 178 files, although usually not as many nor as complex.  You'll still want to back
 179 them up.
 180
 181 The location of these files is highly dependent on what software you're using.
 182
 183 =item Crontab containing RT's cronjobs
 184
 185 This may be F</etc/crontab>, F</etc/cron.d/rt>, a user-specific crontab file
 186 (C<crontab -l $USER>), or some other file altogether.  Even if you only have
 187 the default cronjobs in place, it's one less piece to forget during a restore.
 188 If you have custom L<< C<rt-crontool> >> invocations, you don't want to have to
 189 recreate those.
 190
 191 =back
 192
 193 Simply saving a tarball should be sufficient, with something like:
 194
 195     tar czvpf rt-backup-`date +%Y%m%d`.tar.gz /opt/rt4 /etc/aliases /etc/httpd ...
 196
 197 Be sure to include all the directories and files you enumerated above!
 198