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 vsnapshot_8273 <http://docbook.sf.net/>
   5 .\"      Date: 10/18/2010
   6 .\"    Manual: System Administration Commands
   7 .\"    Source: Amanda 3.2.0
   8 .\"  Language: English
   9 .\"
  10 .TH "AMPGSQL" "8" "10/18/2010" "Amanda 3\&.2\&.0" "System Administration Commands"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 ampgsql \- Amanda Application to interface with PostgreSQL
  23 .SH "DESCRIPTION"
  24 .PP
  25 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\&.
  26 .if n \{\
  27 .sp
  28 .\}
  29 .RS 4
  30 .it 1 an-trap
  31 .nr an-no-space-flag 1
  32 .nr an-break-flag 1
  33 .br
  34 .ps +1
  35 \fBNote\fR
  36 .ps -1
  37 .br
  38 .PP
  39 Tablespaces are not currently supported\&.
  40 .sp .5v
  41 .RE
  42 .if n \{\
  43 .sp
  44 .\}
  45 .RS 4
  46 .it 1 an-trap
  47 .nr an-no-space-flag 1
  48 .nr an-break-flag 1
  49 .br
  50 .ps +1
  51 \fBNote\fR
  52 .ps -1
  53 .br
  54 .PP
  55 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
  56 \fBdtimeout\fR
  57 on the server accordingly\&.
  58 .sp .5v
  59 .RE
  60 .SH "OPERATION"
  61 .PP
  62 This application implements the backup strategy described in
  63 http://www\&.postgresql\&.org/docs/current/static/continuous\-archiving\&.html\&. For a level zero (full) backup, ampgsql:
  64 .sp
  65 .RS 4
  66 .ie n \{\
  67 \h'-04'\(bu\h'+03'\c
  68 .\}
  69 .el \{\
  70 .sp -1
  71 .IP \(bu 2.3
  72 .\}
  73 execute PG_START_BACKUP()
  74 .RE
  75 .sp
  76 .RS 4
  77 .ie n \{\
  78 \h'-04'\(bu\h'+03'\c
  79 .\}
  80 .el \{\
  81 .sp -1
  82 .IP \(bu 2.3
  83 .\}
  84 dump the data directory
  85 .RE
  86 .sp
  87 .RS 4
  88 .ie n \{\
  89 \h'-04'\(bu\h'+03'\c
  90 .\}
  91 .el \{\
  92 .sp -1
  93 .IP \(bu 2.3
  94 .\}
  95 execute PG_STOP_BACKUP()
  96 .RE
  97 .sp
  98 .RS 4
  99 .ie n \{\
 100 \h'-04'\(bu\h'+03'\c
 101 .\}
 102 .el \{\
 103 .sp -1
 104 .IP \(bu 2.3
 105 .\}
 106 wait for the final WAL file to be archived
 107 .RE
 108 .sp
 109 .RS 4
 110 .ie n \{\
 111 \h'-04'\(bu\h'+03'\c
 112 .\}
 113 .el \{\
 114 .sp -1
 115 .IP \(bu 2.3
 116 .\}
 117 back up the required WAL files
 118 .RE
 119 .sp
 120 .RS 4
 121 .ie n \{\
 122 \h'-04'\(bu\h'+03'\c
 123 .\}
 124 .el \{\
 125 .sp -1
 126 .IP \(bu 2.3
 127 .\}
 128 optionally delete WAL files that are no longer necessary
 129 .RE
 130 .sp
 131 .RE
 132 The two dumps are made with GNU Tar, to
 133 data_dir\&.tar
 134 and
 135 archive_dir, respectively\&. They are then combined into a single tar file\&.
 136 .PP
 137 A level N backup creates a single tar file containing all WAL files since the previous level N\-1 backup\&.
 138 .SH "PROPERTIES"
 139 .PP
 140 This section lists the
 141 \fBamanda.conf\fR(5)
 142 properties that control ampsql\'s functionality\&. See
 143 \fBamanda-applications\fR(7)
 144 for information on application properties and how they are configured\&.
 145 .PP
 146 DIRECTORY
 147 .RS 4
 148
 149 For restore command only, the data is recoved in that directory\&. Must be a unix path\&.
 150 .RE
 151 .PP
 152 GNUTAR\-PATH
 153 .RS 4
 154
 155 Path to the GNU tar executable\&. This option only has an effect during restore\&.
 156 The default is set when Amanda is built by the \-\-with\-gnutar configure option\&.
 157 .RE
 158 .PP
 159 STATEDIR
 160 .RS 4
 161
 162 Directory for saving state about backups already made\&. The default is set
 163 when Amanda is built by the \-\-with\-gnutar\-listdir configure option\&.
 164 .RE
 165 .PP
 166 TMPDIR
 167 .RS 4
 168
 169 Directory to use for temporary files during the backup process\&. It should
 170 have enough space to store a complete copy of the database\&. The default is set
 171 when Amanda is built by the \-\-with\-tmpdir configure option\&.
 172 .RE
 173 .SH "CLIENT PROPERTIES"
 174 .PP
 175 This section lists the
 176 \fBamanda-client.conf\fR(5)
 177 properties that control ampsql\'s 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
 178 \fBdisklist\fR(5)\&.
 179 .PP
 180 PG\-ARCHIVEDIR
 181 .RS 4
 182
 183 Directory that WAL segment files are archived to, as specified by the archive_command
 184 in PosgreSQL\'s postgresql\&.conf\&.  The amanda user on the client must have at least read
 185 and execute permission on this directory, and preferably write\&.  Without write permission,
 186 Amanda cannot clean up expired WAL and backup files\&.
 187 .RE
 188 .PP
 189 PG\-CLEANUPWAL
 190 .RS 4
 191
 192 Whether or not to remove old WAL segment files during base backups\&.
 193 Defaults to yes\&.
 194 .RE
 195 .PP
 196 PG\-DATADIR
 197 .RS 4
 198
 199 Cluster data directory
 200 .RE
 201 .PP
 202 PG\-DB
 203 .RS 4
 204
 205 Database to connect to\&. Defaults to "template1" (which exists by default)\&.
 206 .RE
 207 .PP
 208 PG\-HOST
 209 .RS 4
 210
 211 Host to connect to\&. If it starts with "/" it will be interepreted as a directory
 212 that holds the socket file\&. PostgreSQL defaults to /tmp\&.
 213 .RE
 214 .PP
 215 PG\-MAX\-WAL\-WAIT
 216 .RS 4
 217 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\&.
 218 .RE
 219 .PP
 220 PG\-PASSFILE
 221 .RS 4
 222
 223 Connect using the creditials in this file\&. Each line should have the format
 224 "hostname:port:database:username:password"\&. The permissions must
 225 permit it to be read only by the user, or the file will not be used\&.
 226 Only usable with Postgres 8\&.1 and up\&.
 227 .RE
 228 .PP
 229 PG\-PASSWORD
 230 .RS 4
 231
 232 Password to use when connecting\&. Deprecated in favor of passfiles\&.
 233 .RE
 234 .PP
 235 PG\-PORT
 236 .RS 4
 237
 238 The TCP port to connect to, or the suffix of the socket file\&. PostgreSQL
 239 defaults to 5432\&.
 240 .RE
 241 .PP
 242 PG\-USER
 243 .RS 4
 244
 245 User to connect as\&. It must be a superuser\&.
 246 .RE
 247 .PP
 248 PSQL\-PATH
 249 .RS 4
 250
 251 Path to the psql binary\&. If not specified, the PATH environment variable
 252 will be searched\&.
 253 .RE
 254 .SH "RECOVERY"
 255 .PP
 256 Read the postgres documentation carefully before attempting a recovery\&. This section is only a rough guide to the process\&.
 257 .PP
 258 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\&.
 259 .PP
 260 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
 261 recovery\&.conf
 262 in the data directory, owned by the proper user and with proper permissions\&. Add a
 263 \fBrestore_command\fR
 264 to it, e\&.g\&.,
 265 .nf
 266 restore_command = \'cp /path/to/archive_dir/%f "%p"\'
 267 .fi
 268 .PP
 269 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
 270 recovery\&.conf
 271 file aside so that it will not attempt a recovery on the next invocation\&.
 272 .SH "SEE ALSO"
 273 .PP
 274 \fBamanda\fR(8),
 275 \fBamanda.conf\fR(5),
 276 \fBamanda-client.conf\fR(5),
 277 \fBamanda-applications\fR(7)
 278 .PP
 279 The Amanda Wiki:
 280 : http://wiki.zmanda.com/
 281 .SH "AUTHOR"
 282 .PP
 283 \fBNikolas Coukouma\fR <\&atrus@zmanda\&.com\&>
 284 .RS 4
 285 Zmanda, Inc\&. (http://www\&.zmanda\&.com)
 286 .RE