# Running a Backup - Firebird

To invoke gbak, either cd to the Firebird /bin directory where gbak is located or use an absolute root path. The entire command must be on a single line. In the following syntax patterns and examples, the wrapped portions of lines are shown as indented. POSIX:

$] ./gbak -b[ackup] <options> source target [n] or$] /opt/firebird/bin/gbak -b[ackup] <options> source target [n]

Windows:

C:Program FilesFirebirdFirebird_1_5in> gbak -b[ackup]<options> source target [n]

or

C:> C:Program FilesFirebird_1_5ingbak -b[ackup]<options> source target [n]

Arguments for gbak –b[ackup]

source is the full path and file name of a database to back up. In Firebird 1.5, it can be an alias. If backing up a multi-file database, use only the name of the first (primary) database file.

target is the full path and file name of a storage device or backup file to which the backed-up database is to be sent.

In the case that the backup is being output to multiple files, there will be multiple targets. The token n is an integer parameter, included with each output file except the last, to indicate the length of the file in (by default) bytes. A lowercase character can be appended to the number to specify that size is in kilobytes (k), megabytes (m), or gigabytes (g). Refer to the examples that follow.

On POSIX, target can also be stdout. In this case, gbak writes its output to the standard output (usually a pipe).

options can be a valid combination of switches from Table. The switches are case insensitive.

Backup Switches

Table lists and describes the switches that can be used with gbak when running backups.

gbak Switches for Backups

Transportable Backups

Accept the default –transportable switch if you operate in a multi-platform environment.
It writes data in the cross-platform standard eXternal Data Representation (XDR)3 format, allowing the file to be read by the gbak program on a platform different from the one on which it was backed up.

Cross-version Backups

The gbak program on servers with lower ODS than the Firebird server that created a database will generally not be able to restore from the higher ODS backup. In practice, however, the InterBase 5.x version of gbak appears to be capable of restoring most dialect 1 databases created with Firebird 1.0.x.

Backing Up to a Single File

For a simple local backup of a single-file or multiple-file database, use

gbak -b d:dataourdata.fdb d:dataackupsourdata.fbk

The source name is the same whether the database you are backing up is a single or a multiple-file database. When you are backing up a multi-file database, specify only the first file in the backup command. The paths to the second and subsequent files will be found by gbak in the database and file headers during the course of the backup. If you name the subsequent database files, they will be interpreted as backup file names.

The target file can have any name you wish, as long as it is valid on the filesystem to which it is being written.

Backing Up a Multi-file Database to Multiple Files

When you back up a multi-file database to multiple gbak files, there is no requirement to match the database file for file with the backup. If there is to be more than one target file, the names and sizes of the target files need to be specified for all except the last file in the set. By default, the file size (an integer) is taken to be in bytes. To modify that, append a lowercase character to tell gbak you intend the size to be in kilobytes (k), megabytes (m), or gigabytes (g).

The following command backs up a database to three backup files on different filesystem partitions and writes a verbose log. It is all one command; the indented portions are wrapped here for easier reading.

POSIX:

./gbak -b /data/accounts.fdb /backups/accounts.fb1 2g
/backups2/accounts.fb2 750m /backups3/accounts.fb3
-v -y /logs/backups/accounts.20040703.log
Windows: gbak -b d:dataaccounts.fdb e:ackupsaccounts.fb1 2g
f:ackups2accounts.fb2 750m g:ackups3accounts.fb3
-v -y d:dataackuplogsaccounts.20040703.log

Single-File Database to Multiple Targets

If you back up a single-file database to multiple targets, the syntax is identical. In fact, gbak is not interested in whether your source database is single- or multiple-file.

It is important to note the following points:

• The backup will fail if any designated target file is smaller than 2048 bytes. If you are logging, the reason will appear in the log.
• gbak fills the named target files in left-to-right order. It won’t begin the next file until the previous one has reached its designated capacity. In the preceding example, accounts.fb3 will not be created if accounts.fb2 is not filled.
• File paths for targets need not be physically controlled by the host but, if you are using the –service switch (refer to the section “Using gbak with the Firebird Service Manager”) on systems where file permissions are in force, your user profile must have the appropriate write permissions. In some v.1.5 installations, this may be the firebird user or group by default; in some v.1.0.x installations, it may be the interbase user by default.

A metadata-only backup is typically needed for creating an “empty” database when you are ready to deploy a system into production, load QA data, or reconstitute a database for the purpose of migrating. The following command does a metadata-only backup of our accounts database:

gbak -b -m d:dataaccounts.fdb e:QAaccounts.fbk

Remote Backups

If you run gbak from a remote client machine, it writes the backup files to the current directory or to a specified, fully qualified local path. If you specify a location for the backup file, it must be accessible by the machine where gbak is executing. The location can be any of the following:

• On a drive or partition that is local to the client machine
• On a drive that the local machine is mapping to (Windows)
• In a network filesystem (NFS) location (Linux/UNIX)

With the –se[rvice] switch, you can invoke the Firebird Service Manager on the remote server and have gbak delegate the execution of your command on the server itself. The database and backup file specifications must then refer to a location and file name local to the server machine. Locations local to where gbak is launched are not valid for a Service Manager backup. For more about Service Manager, see the upcoming section “Using gbak with the Firebird Service Manager.”

Security Considerations

It is a good precaution to set the read-only property on your backup files at thefilesystem level after creating them, to prevent them from being accidentally or maliciously overwritten.

You can protect your databases from being “kidnapped” on UNIX and on Windows NT/ 2000/ XP systems by placing the backup files in directories with restricted access.

Return Codes and Feedback

A backup run on Windows returns an error level of 0 on success and 1 on failure. If an error occurs, check the firebird.log file (interbase.log in v.1.0.x). For a full backup log file, use the –y and –v switches.