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_metadatascript generates metadata for all directories under/home/usernameexcept/mailand/.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.