How to Manage Metadata Settings

This element (ia-generated) isn't supported, or may require an update to be displayed. You can try to refresh the app.

Overview

System administrators can manage whether to create metadata for backups. Every time that cPanel & WHM creates a backup, it creates metadata for that backup. You can also manually generate backup metadata with the  backups_create_metadata  script. There are several settings that disable metadata creation. You may want to disable metadata creation for testing, before an upgrade, or if your server experiences performance issues.
Note
The backups_create_metadata script will generate metadata for all directories under the /home/username directory, except for the /mail and /.cpanel directories.
Backups and metadata must exist on the local disk before users can access the following interfaces:
cPanel’s  File and Directory Restoration  interface (cPanel » Home » Files » File and Directory Restoration).
WHM’s  File and Directory Restoration  interface (WHM » Home » Backups » File and Directory Restoration).

Enable metadata creation

Every time that cPanel & WHM creates a backup, it creates metadata for that backup. The system stores that metadata as entries in a username.db database (where username represents the cPanel account’s username). Then, the system saves the database to the .meta directory under your configured backup directory. The metadata databases store the indexed information of their related backups. These smaller database entries provide a faster information-retrieval method than their source backup.

Metadata database tables

The following tables describe the fields of these smaller databases, the backup_paths table, the backups table, the file_changes table, the metadata table, and the seen_files table.

The backup_paths table

The backup_paths table lists the backup files’ paths.
Field
Type
Description
Possible values
Example
backup_path
string
The backup files’s filepath, relative to the configured backup directory.
A string value.
/backup/2018-04-12/accounts
backup_id
integer
The backup file’s identification number.
A positive integer. This value references the backup_id value in the backupstable.
1

The backups table

The backups table lists the backup files on the disk.
Field
Type
Description
Possible values
Example
backup_id
integer
The backup file’s identification number.
An automatically-incrementing positive integer.
1
timestamp
timestamp
The backup files’s creation date in  Universal Time Coordinated (UTC) .
An integer.
1523642274
does_exist
Boolean
Whether the backup file exists.
  • 1 — Exists.
  • 0 — Does not exist.
1

The file_changes table

The file_changes table lists backup file changes when any of the following actions occur:
  • The first time the system backs up the file.
  • The user modifies the file.
  • The user removes the file.
Field
Type
Description
Possible values
Example
seen_files_id
integer
The filepath’s identification number.
A positive integer. This value references the file_id value in the seen_files table.
1
backup_id
integer
The backup file’s identification number.
A positive integer. This value references the backup_id value in the backups table
1
size
integer
The backup file’s size, in bytes.
  • A file size value displays the file’s size.
  • A directory or a symlink displays a 0 file size.
660
mtime
integer
The date when the user last modified the file, in  UTC  format.
An integer.
1523642274
operation
integer
The change type.
  • 0 — The user created the backup file.
  • 1 — The user changed the file.
  • 2 — The user removed the file.
0
type
integer
The backup file’s type.
  • 0 — A file.
  • 1 — A directory.
  • 2 — A symlink
0

The metadata table

This table stores metadata keys and values.
Field
Type
Description
Possible values
Example
key
string
The metadata code type.
schema_version — The metadata schema’s type.
schema_version
value
string
The metadata code’s version number.
A string value.
3.1

The seen_files table

This table stores filenames.
Field
Type
Description
Possible values
Example
file_id
integer
The file’s identification number.
An automatically-incrementing positive integer.
1
path
string
The file’s filepath, relative to the /home/username directory.
A string value.
/public_html/

The master meta-file

he .master.meta file stores relevant data about cPanel user backups that is not stored in the metadata database tables. This information, unlike the information in the tables, doesn’t change.
Every accounts directory inside the daily, weekly, and monthly backup directories contains a .master.meta file.

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 format
Filename extension
Example
compressed
.tar.gz
username.tar.gz
uncompressed
.tar
username.tar
incremental
None
username
The system distinguishes each backup by its filepath, even if the system stores the backup information under the same name. 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 compressed backups. You can distinguish each backup type by its complete filepath. This filepath is the file’s full path. The system stores the metadata for this path in the backup_paths table, under the backup_path field.
The system also stores metafiles in the /backup directory and distinguished by their filepath. The system stores metafiles inside the /backup directory as entries in a username.db database (where username represents the cPanel account’s username).

Disable metadata creation

You can manually disable metadata with WHM’s  Backup Configuration  interface (WHM » Home » Backup » Backup Configuration). The following table shows which settings affect the management of metadata manually and the Backup Configuration interface. These settings function independently from one another.
Note
When you configure any of these settings to disable metadata creation, the following actions occur:
The system disables cPanel’s  File and Directory Restoration  interface (cPanel » Home » Files » File and Directory Restoration) and WHM’s  File and Directory Restoration  interface (WHM » Home » Backups » File and Directory Restoration). The interfaces display a notification that explains why the feature is unavailable.
You can disable metadata with the WHM API 1  backup_config_set  function.
Backup configuration file setting
Backup Configuration interface setting
Type
Description
Possible values
DISABLE_METADATA
None. You must manually configure this setting with the WHM API 1  backup_config_set  function.
string
Whether the Backup system creates metadata when a backup runs.
  • yes — Disables metadata creation.
  • no — Enables metadata creation.
BACKUPACCTS
Backup Accounts
string
Whether the system includes cPanel user accounts in the backup.
Note:
System administrators can select which cPanel user accounts they wish to include in the backup through the  Backup User Selection  interface (WHM » Home » Backup » Backup User Selection).
  • yes or selected checkbox — Include the cPanel user accounts in the backup and enable metadata creation.
  • no or deselected checkbox — Do not include the cPanel user accounts in the backup and disable metadata creation.
BACKUPENABLE
Backup Status
string
Whether the WHM System Administrator wants backups enabled.
  • yes or set toggle to Enable — Enables backup and metadata creation.
  • no or set toggle to Disable — Disables backup and metadata creation.
BACKUPMOUNT
Mount Backup Drive as Needed
Boolean
Whether the system mounts the backup directory as a mount point before a backups runs, then unmounts it when the run completes.
  • 1 or selected checkbox —Mount the backup directory and disable metadata creation.
  • 0 or deselected checkbox — Do not mount the backup directory and enable metadata creation.
KEEPLOCAL
Retain backups in the default backup directory
Boolean
Whether the system retains backups in the default local backup directory.
  • 1 or selected checkbox — Retains the backup and enable metadata creation.
  • 0 or deselected checkbox – Does not retain the backup and disable metadata creation.