How to Manage Metadata Settings in cPanel & WHM

How to Manage Metadata Settings

Valid for versions 76 through the latest version

Version: 76
Last modified: January 28, 2026

Overview

WHM administrators can manage metadata creation using WHM’s Backup Configuration interface:

WHM » Home » Backup » Backup Configuration

By default, cPanel & WHM generates metadata every time a backup is created. You may want to disable metadata creation for testing, before an upgrade, or when troubleshooting performance issues.

Notes:

• The backups_create_metadata script generates metadata for all directories under /home/username except /mail and /.cpanel.
• You must have at least one backup and metadata entry stored locally for the following interfaces to appear:
• cPanel » Home » Files » File and Directory Restoration
• WHM » Home » Backups » File and Directory Restoration

Metadata Databases

Each time a backup is created, cPanel & WHM generates metadata and stores it in a username.db database, where username is the cPanel account name.

The system saves this database inside the .meta directory under the configured backup directory. These metadata databases store indexed information in smaller, searchable files, allowing faster retrieval compared to scanning full backup archives.

Metadata Database Tables

The metadata database contains the following tables:

• backup_paths — Lists backup file locations.
• backups — Lists backup files stored on disk.
• file_changes — Tracks changes to files across backups.
• metadata — Stores schema type and version.
• seen_files — Tracks filenames included in backups.

backup_paths Table

Field	Type	Description	Example
backup_path	string	Filepath relative to backup directory	/backup/2018-04-12/accounts
backup_id	integer	References backups.backup_id	1

backups Table

Field	Type	Description	Example
backup_id	integer	Unique ID	1
timestamp	timestamp	UTC creation time	1523642274
does_exist	Boolean	Whether the backup exists	1

file_changes Table

Field	Type	Description	Example
seen_files_id	integer	References seen_files.file_id	1
backup_id	integer	References backups.backup_id	1
size	integer	File size in bytes	660
mtime	integer	Last modified time (UTC)	1523642274
operation	integer	Change type (0=create, 1=modify, 2=remove)	0
type	integer	File type (0=file, 1=directory, 2=symlink)	0

metadata Table

Field	Type	Description	Example
key	string	Metadata schema type	schema_version
value	string	Schema version	3.1

seen_files Table

Field	Type	Description	Example
file_id	integer	Unique file ID	1
path	string	Path relative to /home/username	/public_html/

The Master Meta File

The .master.meta file stores static information about user backups that does not change. Every account directory inside daily, weekly, and monthly backup folders contains a .master.meta file.

Backup Directory Structure

Backups are stored in /backup using one of three formats:

Format	Extension	Example
Compressed	.tar.gz	username.tar.gz
Uncompressed	.tar	username.tar
Incremental	None	username

The system distinguishes backups by their full filepath. Metadata for each backup is stored in the backup_paths table.

Disable Metadata Creation

You can disable metadata creation using WHM’s Backup Configuration interface or by modifying configuration settings directly.

Important: When metadata is disabled:

• cPanel’s File and Directory Restoration interface becomes unavailable.
• WHM’s File and Directory Restoration interface becomes unavailable.
• A notification explains why the feature is disabled.

You can also disable metadata using the WHM API 1 backup_config_set function.

Metadata-Related Settings

Config File Setting	Interface Setting	Description	Values
DISABLE_METADATA	None (API only)	Enables or disables metadata creation	yes / no
BACKUPACCTS	Backup Accounts	Include cPanel accounts in backups	yes / no
BACKUPENABLE	Backup Status	Enable or disable backups	yes / no
BACKUPMOUNT	Mount Backup Drive as Needed	Mount backup directory before backup runs	1 / 0
KEEPLOCAL	Retain backups in default directory	Keep local backups	1 / 0

Conclusion

Metadata plays a crucial role in enabling fast file restoration and efficient backup indexing in cPanel & WHM. Understanding how metadata is stored and how to enable or disable it helps administrators optimize performance, troubleshoot issues, and manage backup behavior more effectively.