git.gag.com Git - debian/amanda/blob - man/ampgsql.8

   1 '\" t
   2 .\"     Title: ampgsql
   3 .\"    Author: Nikolas Coukouma <atrus@zmanda.com>
   4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
   5 .\"      Date: 07/25/2012
   6 .\"    Manual: System Administration Commands
   7 .\"    Source: Amanda 3.3.2
   8 .\"  Language: English
   9 .\"
  10 .TH "AMPGSQL" "8" "07/25/2012" "Amanda 3\&.3\&.2" "System Administration Commands"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 ampgsql \- Amanda Application to interface with PostgreSQL
  32 .SH "DESCRIPTION"
  33 .PP
  34 Ampgsql is an Amanda Application API script\&. It should not be run by users directly\&. It implements on\-line backups of PostgreSQL databases in conjunction with WAL archiving\&.
  35 .if n \{\
  36 .sp
  37 .\}
  38 .RS 4
  39 .it 1 an-trap
  40 .nr an-no-space-flag 1
  41 .nr an-break-flag 1
  42 .br
  43 .ps +1
  44 \fBNote\fR
  45 .ps -1
  46 .br
  47 .PP
  48 Tablespaces are not currently supported\&.
  49 .sp .5v
  50 .RE
  51 .if n \{\
  52 .sp
  53 .\}
  54 .RS 4
  55 .it 1 an-trap
  56 .nr an-no-space-flag 1
  57 .nr an-break-flag 1
  58 .br
  59 .ps +1
  60 \fBNote\fR
  61 .ps -1
  62 .br
  63 .PP
  64 On versions of PostgreSQL earlier than 8\&.2, if the database is quiet during a full backup, then the backup may not complete until enough database activity takes place to trigger the archiving of the current WAL file\&. Consider adjusting the PG\-MAX\-WAL\-WAIT property from its default (60s) to compensate\&. Note that you will need to increase
  65 \fBdtimeout\fR
  66 on the server accordingly\&.
  67 .sp .5v
  68 .RE
  69 .SH "OPERATION"
  70 .PP
  71 This application implements the backup strategy described in
  72 http://www\&.postgresql\&.org/docs/current/static/continuous\-archiving\&.html\&. For a level zero (full) backup, ampgsql:
  73 .sp
  74 .RS 4
  75 .ie n \{\
  76 \h'-04'\(bu\h'+03'\c
  77 .\}
  78 .el \{\
  79 .sp -1
  80 .IP \(bu 2.3
  81 .\}
  82 execute PG_START_BACKUP()
  83 .RE
  84 .sp
  85 .RS 4
  86 .ie n \{\
  87 \h'-04'\(bu\h'+03'\c
  88 .\}
  89 .el \{\
  90 .sp -1
  91 .IP \(bu 2.3
  92 .\}
  93 dump the data directory
  94 .RE
  95 .sp
  96 .RS 4
  97 .ie n \{\
  98 \h'-04'\(bu\h'+03'\c
  99 .\}
 100 .el \{\
 101 .sp -1
 102 .IP \(bu 2.3
 103 .\}
 104 execute PG_STOP_BACKUP()
 105 .RE
 106 .sp
 107 .RS 4
 108 .ie n \{\
 109 \h'-04'\(bu\h'+03'\c
 110 .\}
 111 .el \{\
 112 .sp -1
 113 .IP \(bu 2.3
 114 .\}
 115 wait for the final WAL file to be archived
 116 .RE
 117 .sp
 118 .RS 4
 119 .ie n \{\
 120 \h'-04'\(bu\h'+03'\c
 121 .\}
 122 .el \{\
 123 .sp -1
 124 .IP \(bu 2.3
 125 .\}
 126 back up the required WAL files
 127 .RE
 128 .sp
 129 .RS 4
 130 .ie n \{\
 131 \h'-04'\(bu\h'+03'\c
 132 .\}
 133 .el \{\
 134 .sp -1
 135 .IP \(bu 2.3
 136 .\}
 137 optionally delete WAL files that are no longer necessary
 138 .RE
 139 .sp
 140 The two dumps are made with GNU Tar, to
 141 data_dir\&.tar
 142 and
 143 archive_dir, respectively\&. They are then combined into a single tar file\&.
 144 .PP
 145 A level N backup creates a single tar file containing all WAL files since the previous level N\-1 backup\&.
 146 .SH "PROPERTIES"
 147 .PP
 148 This section lists the
 149 \fBamanda.conf\fR(5)
 150 properties that control ampsql\*(Aqs functionality\&. See
 151 \fBamanda-applications\fR(7)
 152 for information on application properties and how they are configured\&.
 153 .PP
 154 ARCHIVEDIR
 155 .RS 4
 156 Directory that WAL segment files are archived to, as specified by the archive_command in PosgreSQL\*(Aqs postgresql\&.conf\&. The amanda user on the client must have at least read and execute permission on this directory, and preferably write\&. Without write permission, Amanda cannot clean up expired WAL and backup files\&.
 157 .RE
 158 .PP
 159 CLEANUPWAL
 160 .RS 4
 161 Whether or not to remove old WAL segment files during base backups\&. Defaults to yes\&.
 162 .RE
 163 .PP
 164 DB
 165 .RS 4
 166 Database to connect to\&. Defaults to "template1" (which exists by default)\&.
 167 .RE
 168 .PP
 169 DIRECTORY
 170 .RS 4
 171 For restore command only, the data is recoved in that directory\&. Must be a unix path\&.
 172 .RE
 173 .PP
 174 GNUTAR\-PATH
 175 .RS 4
 176 Path to the GNU tar executable\&. This option only has an effect during restore\&. The default is set when Amanda is built by the \-\-with\-gnutar configure option\&.
 177 .RE
 178 .PP
 179 HOST
 180 .RS 4
 181 Host to connect to\&. If it starts with "/" it will be interepreted as a directory that holds the socket file\&. PostgreSQL defaults to /tmp\&.
 182 .RE
 183 .PP
 184 MAX\-WAL\-WAIT
 185 .RS 4
 186 The maximum amount of time to wait for PG_STOP_BACKUP to archive a WAL file\&. In versions of PostgreSQL before 8\&.2, PG_STOP_BACKUP does not automatically archive the latest WAL file, so a quiet database may wait a very long time before archiving the WAL file\&. Default: 60 seconds\&. Set to 0 to wait forever\&.
 187 .RE
 188 .PP
 189 PASSFILE
 190 .RS 4
 191 Connect using the creditials in this file\&. Each line should have the format "hostname:port:database:username:password"\&. The permissions must permit it to be read only by the user, or the file will not be used\&. Only usable with Postgres 8\&.1 and up\&.
 192 .RE
 193 .PP
 194 PORT
 195 .RS 4
 196 The TCP port to connect to, or the suffix of the socket file\&. PostgreSQL defaults to 5432\&.
 197 .RE
 198 .PP
 199 PSQL\-PATH
 200 .RS 4
 201 Path to the psql binary\&. If not specified, the PATH environment variable will be searched\&.
 202 .RE
 203 .PP
 204 STATEDIR
 205 .RS 4
 206 Directory for saving state about backups already made\&. The default is set when Amanda is built by the \-\-with\-gnutar\-listdir configure option\&.
 207 .RE
 208 .PP
 209 TMPDIR
 210 .RS 4
 211 Directory to use for temporary files during the backup process\&. It should have enough space to store a complete copy of the database\&. The default is set when Amanda is built by the \-\-with\-tmpdir configure option\&.
 212 .RE
 213 .PP
 214 USER
 215 .RS 4
 216 User to connect as\&. It must be a superuser\&.
 217 .RE
 218 .SH "CLIENT PROPERTIES"
 219 .PP
 220 Client properties are deprecated\&. All properties should be set in the dumptype\&.
 221 .PP
 222 This section lists the
 223 \fBamanda-client.conf\fR(5)
 224 properties that control ampsql\*(Aqs functionality\&. If a property is prefixed with the diskname and an underscore, then it will be used when that diskname is being backed up\&. For example, if the properties PG\-DATADIR and foo\-PG\-DATADIR are set, the value of PG\-DATADIR will be used when bar and baz are being backed up, but foo\-PG\-DATADIR will be used when foo is being backed up\&. Disknames are specified in the
 225 \fBdisklist\fR(5)\&.
 226 .PP
 227 PG\-ARCHIVEDIR
 228 .RS 4
 229
 230 Directory that WAL segment files are archived to, as specified by the archive_command
 231 in PosgreSQL\*(Aqs postgresql\&.conf\&.  The amanda user on the client must have at least read
 232 and execute permission on this directory, and preferably write\&.  Without write permission,
 233 Amanda cannot clean up expired WAL and backup files\&.
 234 .RE
 235 .PP
 236 PG\-CLEANUPWAL
 237 .RS 4
 238
 239 Whether or not to remove old WAL segment files during base backups\&.
 240 Defaults to yes\&.
 241 .RE
 242 .PP
 243 PG\-DATADIR
 244 .RS 4
 245
 246 Cluster data directory
 247 .RE
 248 .PP
 249 PG\-DB
 250 .RS 4
 251
 252 Database to connect to\&. Defaults to "template1" (which exists by default)\&.
 253 .RE
 254 .PP
 255 PG\-HOST
 256 .RS 4
 257
 258 Host to connect to\&. If it starts with "/" it will be interepreted as a directory
 259 that holds the socket file\&. PostgreSQL defaults to /tmp\&.
 260 .RE
 261 .PP
 262 PG\-MAX\-WAL\-WAIT
 263 .RS 4
 264 The maximum amount of time to wait for PG_STOP_BACKUP to archive a WAL file\&. In versions of PostgreSQL before 8\&.2, PG_STOP_BACKUP does not automatically archive the latest WAL file, so a quiet database may wait a very long time before archiving the WAL file\&. Default: 60 seconds\&. Set to 0 to wait forever\&.
 265 .RE
 266 .PP
 267 PG\-PASSFILE
 268 .RS 4
 269
 270 Connect using the creditials in this file\&. Each line should have the format
 271 "hostname:port:database:username:password"\&. The permissions must
 272 permit it to be read only by the user, or the file will not be used\&.
 273 Only usable with Postgres 8\&.1 and up\&.
 274 .RE
 275 .PP
 276 PG\-PASSWORD
 277 .RS 4
 278
 279 Password to use when connecting\&. Deprecated in favor of passfiles\&.
 280 .RE
 281 .PP
 282 PG\-PORT
 283 .RS 4
 284
 285 The TCP port to connect to, or the suffix of the socket file\&. PostgreSQL
 286 defaults to 5432\&.
 287 .RE
 288 .PP
 289 PG\-USER
 290 .RS 4
 291
 292 User to connect as\&. It must be a superuser\&.
 293 .RE
 294 .PP
 295 PSQL\-PATH
 296 .RS 4
 297
 298 Path to the psql binary\&. If not specified, the PATH environment variable
 299 will be searched\&.
 300 .RE
 301 .SH "RECOVERY"
 302 .PP
 303 Read the postgres documentation carefully before attempting a recovery\&. This section is only a rough guide to the process\&.
 304 .PP
 305 The data recovered from a postgres backup consists of a data tarball and one or more archive tarballs\&. The data contains the state of the database at the time the full backup was performed, and the archive tarballs contain postgres WAL files that must be re\-run to generate a consistent state\&.
 306 .PP
 307 Ensure that the database server is shut down, and move the existing data directory aside\&. Untar the data tarball over this directory, and verify that ownership and permissions are correct\&. Untar all of the archive tarballs into a single directory \- the archive directory\&. Create a
 308 recovery\&.conf
 309 in the data directory, owned by the proper user and with proper permissions\&. Add a
 310 \fBrestore_command\fR
 311 to it, e\&.g\&.,
 312 .nf
 313 restore_command = \*(Aqcp /path/to/archive_dir/%f "%p"\*(Aq
 314 .fi
 315 .PP
 316 Start the database server, and examine the logs to track the process of the recovery\&. When the recovery is complete, the server will transition into a running state, and will move the
 317 recovery\&.conf
 318 file aside so that it will not attempt a recovery on the next invocation\&.
 319 .SH "SEE ALSO"
 320 .PP
 321 \fBamanda\fR(8),
 322 \fBamanda.conf\fR(5),
 323 \fBamanda-client.conf\fR(5),
 324 \fBamanda-applications\fR(7)
 325 .PP
 326 The Amanda Wiki:
 327 : http://wiki.zmanda.com/
 328 .SH "AUTHOR"
 329 .PP
 330 \fBNikolas Coukouma\fR <\&atrus@zmanda\&.com\&>
 331 .RS 4
 332 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
 333 .RE