Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Include Page
_Version
_Version

Table of Contents
stylenone

Overview

The /usr/local/cpanel/scripts/backups_create_metadata script allows a user to create metadata files for all account backup types.

The backups_create_metadata script

To use the /usr/local/cpanel/scripts/backups_create_metadata script, run the following command as the root user:

Code Block
/usr/local/cpanel/scripts/backups_create_metadata [arguments] [inputs]

Arguments and inputs

Use the following arguments for the /usr/local/cpanel/scripts/backups_create_metadata script:

ArgumentsDescriptionInput valuesExample
--all

Creates metadata files for all backups.

Note
titleNote:

You cannot combine the --all argument with other arguments.


The backup directory's name./scripts/backups_create_metadata --all=/backup
--backup

Creates metadata files for the specified backup file.

The backup file's name./scripts/backups_create_metadata --backup=/backup/monthly/2017-03-01
--user=[user]

Combine this argument with the --backup argument to create metadata files for the specified user within the desired backup.

The cPanel account's username./scripts/backups_create_metadata --backup=/backup/monthly/2017-03-01 --user=abc1

Metadata for backups version 1.0

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. These smaller database entries provide a faster information-retrieval method than their source backup.

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:

Code Block
languagebash
linenumberstrue
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:

Code Block
languagebash
linenumberstrue
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
titleNote:

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

Anchor
details
details
Backup archive files' details

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

Note
titleNotes:
  • The backup resides on the disk.
  • The file details list the full path to the backup. The backup archive contains the backup's entire data.

Compressed and uncompressed backup file details

Section


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 details

Section


PartDescription
File sizeThe backup's size, in bytes.
Last modified dateThe date when the system last modified the backup.
The file's archive nameThe backup's name in the archive, stored in Base64 format.
The file's full path in the archiveThe full path to the backup 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.


Note
titleNotes:

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 backups inside the /backup directory in one of three different formats: compressed, uncompressed, and incremental. Each format uses a different filename extension.

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

The system distinguishes each backup, even if it stores the backup information under the same name, by its filepath. The filepath includes the backup directory where the backup 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

Localtab Group


Localtab
activetrue
titleSuggested documentation

Content by Label
showLabelsfalse
max5
showSpacefalse
cqllabel in ("backups","clidoc") and label = "whm" and space = currentSpace()


Localtab
titleFor cPanel users

Content by Label
showLabelsfalse
max5
showSpacefalse
cqllabel in ("backups","clidoc") and label = "cpanel" and space = currentSpace()


Localtab
titleFor WHM users

Content by Label
showLabelsfalse
max5
showSpacefalse
cqllabel in ("backups","clidoc") and label = "whm" and space = currentSpace()


Localtab
titleFor developers

Content by Label
showLabelsfalse
max5
showSpacefalse
cqllabel in ("backups","clidoc") and space = "SDK"