Child pages
  • Metadata for Backups
Skip to end of metadata
Go to start of metadata

Overview

Every time cPanel & WHM creates a backup, it also generates a backup metadata file that maps the contents of that backup's directory. The metadata lists files and directories in the backup and stores the information in CSV format. You can also manually generate a backup metadata file with the backups_create_metadata script.

Metadata files store indexed information of their related backup file. Because they are smaller in size, they provide a faster information-retrieval method than their source backup file.

Backup metadata format

A backup metadata file, or metafile, has two sections. The first section contains the metafile's meta attributes and appears above a dotted line. The second section provides details of the backup archive's files and appears below the dotted line.

Compressed and uncompressed backups metafile example

A metafile for compressed and uncompressed backups will resemble the following example:

server,example.cpanel.net
uid,2183
gid,2186
username,abc1
metaversion,1
date,2017-02-28
epoch,1488261600
archive_size,653824
uncompressed_size,531748
pkgacct_version,10
archive_version,3
file_count,108
-------------------------------------------------
720,"2017-01-30 09:16",YWJjMS9jcC9hYmMx,/backup/2017-02-28/accounts/abc1.tar,0,2186
4221,"2017-03-01 09:11",YWJjMS9kbnN6b25lcy9hYmMxLnRsZC5kYg==,/backup/2017-02-28/accounts/abc1.tar,0,0
1731,"2017-03-01 09:11",YWJjMS9kbnN6b25lcy9hZGQxYWJjMS50bGQuZGI=,/backup/2017-02-28/accounts/abc1.tar,0,0
1675,"2017-01-16 07:44",YWJjMS9kb21haW5rZXlzL3ByaXZhdGUvYWJjMS50bGQ=,/backup/2017-02-28/accounts/abc1.tar,0,12
....

Incremental backups metafile example

A metafile for incremental backups will resemble the following example:

server,example.cpanel.net
uid,2183
gid,2186
username,abc1
metaversion,1
date,2017-03-22
epoch,1490158800
archive_size,836
uncompressed_size,533260
pkgacct_version,10
archive_version,3
file_count,110
-------------------------------------------------
39,"2017-03-22 11:54",L2JhY2t1cC8yMDE3LTAzLTIyL2FjY291bnRzL2FiYzEvdmVyc2lvbg==,FILE,0,0
11,"2017-03-22 11:54",L2JhY2t1cC8yMDE3LTAzLTIyL2FjY291bnRzL2FiYzEvaG9tZWRpcl9wYXRocw==,FILE,0,0
0,"2017-03-22 11:54",L2JhY2t1cC8yMDE3LTAzLTIyL2FjY291bnRzL2FiYzEvaGFzX3NzbHN0b3JhZ2U=,FILE,0,0
8,"2017-03-22 11:54",L2JhY2t1cC8yMDE3LTAzLTIyL2FjY291bnRzL2FiYzEvc3NsZG9tYWlu,FILE,0,0

Meta attributes

The meta attributes section displays backup archive values, in CSV format, and uses a attribute name, attribute value convention. 

AttributeDescriptionExample
server

The server's hostname.

example.cpanel.net
uid

The system user's identification number on the server.

2183
gid

The user's file's group identification number.

2186
usernameThe system user that owns the backed-up files.abc1
metaversionThe metafile's format version.1
dateThe date when the system backed up the file.2017-02-28
epoch

The date in Unix epoch time.

1488261600
archive_size

The archive's size, in bytes. For example, the size of the abc1.tar.gz file.

653824
uncompressed_sizeAn uncompressed archive's size, in bytes.531748
pkgacct_version

The package account script's version.

Note:

cPanel & WHM uses the pkgacct script to create the archives.

10
archive_versionThe program version that the system uses to prepare the backup archive.3
file_countThe number of files in the backup archive.108

Backup archive files' details

This section displays backup file details in CSV format. The format uses two conventions: one for compressed and uncompressed backup files, and one for incremental backup files.

Notes:

  • The backup file resides on the disk.
  • The file details list the full path to the backup file. The backup archive contains the entire backup file.

Compressed and uncompressed backup file details

PartDescription
File sizeThe backup file's size, in bytes.
Last modified dateThe date when the system last modified the file.
The file's archive nameThe file's name in the archive, stored in Base64 format.
The file's full path in the archiveThe full path to the file in the archive.
UIDThe system user's user identification number on the server.
GIDThe user's file's group identification number.


Incremental backup file details

PartDescription
File sizeThe backup file's size, in bytes.
Last modified dateThe date when the system last modified the file.
The file's archive nameThe file's name in the archive, stored in Base64 format.
The file's full path in the archiveThe full path to the file in the archive.
The archived file's type

One of these archived file types:

  • FILE — A file.
  • DIR — A directory.
  • SYMLINK — A symlink.
UIDThe system user's identification number.
GIDThe user's file's group identification number.

Notes:

The system can only store the system backup (/backup/.../system) as a compressed or uncompressed backup file. The system cannot store a system backup as an incremental backup file. This condition creates a limitation when you configure a remote destination for your backups in the Additional Destinations section in WHM's Backup Configuration interface (WHM >> Home >> Backup >> Backup Configuration). Because the system can only store system backup files as compressed or uncompressed files, the system copies the system backup file to the destination.

Metafiles and the /backup directory structure

The system stores backup files inside the /backup directory in one of three different formats: compressed, uncompressed, and incremental. Each file format uses a different filename extension.

Backup formatFilename extensionExample
compressed.tar.gzusername.tar.gz
uncompressed.tarusername.tar
incrementalNoneusername

The system distinguishes each backup file, even if it stores the files under the same name, by its filepath. The filepath includes the backup directory where the backup file resides. The following example shows the layout and structure of a /backup directory. This directory includes daily, monthly, and weekly uncompressed backups. You can distinguish each backup type by its complete filepath. This filepath is the file's full path shown in the metafile's backup file details.

The system also stores metafiles in the /backup directory and distinguished by their filepath. The system stores metafiles inside the /backup directory as username-=-meta, where username represents the system user's name.

Additional documentation