Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Backup profile description (bak.toml)

This document defines the global operating parameters of the backup engine, including backup type and storage location, remote SSH, S3 compatible object storage, MySQL connection, backup encryption, recovery decryption, MySQL recovery target, and disaster recovery exercise workspace.

Configuration SegmentDescription
[public]Backup type, storage location, number of locally reserved copies, logs and queues
[remote]Remote SSH Connection (Remote Backup Scenario)
[object_storage]S3 Compatible Object Storage
[mysql]Backup source MySQL connection with tool path
[backup_encryption]Backup Encryption
[restore_encryption]Recover decryption private key
[restore.mysql]MySQL recovery target (independent of production [mysql])
[drill] / [drill.mysql]Disaster Preparedness Drill Workspace and Default Target Library

Configuration essentials

[public]

ParameterDescriptionExample
bak_typeBackup content: db, app_data, or db_and_app_data."app_data"
bak_location_typeStorage location, for example local or local_and_remote."local_and_remote"
history_bak_numNumber of local historical backup copies to retain.3
log_dir / local_bak_home / local_tmp_homeLog, backup, and temporary working directories.See the platform path examples below.
max_bak_queue_sizeNumber of backup jobs that run concurrently; 1 means sequential execution.1

peppykeep backup run --no-upload temporarily saves locally only; --upload temporarily performs an upload. Command-line arguments affect only that run and do not modify the configuration file.

Remote access, object storage, and backup source

Configuration SegmentKey fieldsDescription
[remote]ip、user、ssh_portSSH connection for remote backup scenarios.
[object_storage]enabled、provider、bucket、prefix、endpoint、region、path_styleS3-compatible object storage. Provide access credentials through managed configuration or the runtime environment; do not commit them to documentation, source repositories, or tickets.
[mysql]mysql_ip、mysql_port、mysql_user_name、mysql_pwd、mysqldump_path、skip_sslBackup-source MySQL connection and export tool. When docker_container_name is set, exports can run in the container through docker_cmd_path.

Encryption, recovery, and drills

Configuration SegmentKey fieldsDescription
[backup_encryption]enabled、algorithm、key_wrap_algorithm、public_key_file、delete_plain_after_encryptBackup encryption and public-key location.
[restore_encryption]private_key_file、private_key_passphrase_env、allow_promptDecryption private key and passphrase retrieval method.
[restore.mysql]execution_mode, connection parameters, mysql_client_path, workspace, and validation parametersRecovery target database; it must be independent of the production [mysql] configuration.
[drill] / [drill.mysql]Drill workspace, reports, default target database prefix, and validation parametersRecovery drills in an isolated environment.

With execution_mode = "native" in [restore.mysql], mysql_client_path points to the host’s mysql client. With container_exec, also configure the in-container mysql-client path plus container_runtime (docker or podman), container_runtime_path, and container_name. Recovery and drills must not overwrite the source database by default; change allow_restore_to_source_db and options that delete the target database only after confirmation.

Platform path and tool differences

Configuration sections and fields are identical; only local directories and executable locations differ. Use your actual installation paths rather than copying paths that do not exist.

local_bak_home is the backup artifact root. PeppyKeep does not use a fixed global backup path. Use the bak.toml generated during installation and configure an absolute path appropriate for your disk layout. The following table shows recommended examples; /data/backup and legacy ldbakutil paths are not ppk format requirements.

FieldWindows examplemacOS / Linux example
log_dir"C:\\Users\\<Username>\\AppData\\Local\\Temp\\logs\\peppykeep""/tmp/logs/peppykeep"
local_bak_home"D:\\PeppyKeep\\backup""/var/lib/peppykeep/backup"
local_tmp_home / workspace"C:\\Users\\<Username>\\AppData\\Local\\Temp\\peppykeep""/tmp/peppykeep"
mysqldump_path"C:\\Program Files\\MySQL\\MySQL Server 8.0\\bin\\mysqldump.exe""/usr/bin/mysqldump" or the actual Homebrew path
mysql_client_path"C:\\Program Files\\MySQL\\MySQL Server 8.0\\bin\\mysql.exe""/usr/bin/mysql" or the actual Homebrew path
docker_cmd_path / container_runtime_pathActual Docker or Podman executable path"/usr/bin/docker", "/usr/bin/podman", or the actual installation path

Backup Artifact Directory and Archive Structure

A regular backup run writes local backup files to:

<local_bak_home>/
└── <prj_key>/
    ├── <prj_key>-bak_<YYYYMMDD_HHMMSS>.ppk   # Unencrypted archive
    └── <prj_key>-bak_<YYYYMMDD_HHMMSS>.ppke  # When backup encryption is enabled

The .ppk archive produced by a backup uses ppk_data/ as its only standard root directory:

ppk_data/
├── data/    # Application data; may be empty if not backed up
└── sql/     # Database exports; may be empty if not backed up

Recovery and drills can read the legacy data/data/ and data/sql/ paths for compatibility. New backups, examples, and validation rules must use ppk_data/data/ and ppk_data/sql/. ppk pack is a general-purpose archiving command whose archive root follows the input file or directory name; it does not use the backup run artifact format.

Minimal example

The following examples show the common structure. Replace passwords, access keys, and real host addresses with secure, actual values. Commands such as peppykeep backup run and peppykeep restore mysql use the same arguments on Windows, macOS, and Linux; only the directories and tool paths in configuration need platform-specific changes.

macOS / Linux:

[public]
bak_type = "app_data"
bak_location_type = "local_and_remote"
history_bak_num = 3
log_dir = "/tmp/logs/peppykeep"
local_bak_home = "/var/lib/peppykeep/backup"
local_tmp_home = "/tmp/peppykeep"
max_bak_queue_size = 1

[object_storage]
enabled = true
provider = "s3"
bucket = "my-backup-bucket"
prefix = "peppykeep"
endpoint = "https://s3.example.com"
region = ""
path_style = false

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "backup_user"
mysql_pwd = "<provide-securely>"
mysqldump_path = "/usr/bin/mysqldump"
skip_ssl = true

[restore.mysql]
execution_mode = "native"
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "restore_user"
mysql_pwd = "<provide-securely>"
mysql_client_path = "/usr/bin/mysql"
workspace_home = "/tmp/ppk-restore-mysql"
allow_restore_to_source_db = false
drop_target_db_before_restore = false
default_check_sql_enabled = true
custom_check_sql_file = ""
keep_workspace_on_success = true
keep_workspace_on_failure = true

Windows:

[public]
bak_type = "app_data"
bak_location_type = "local_and_remote"
history_bak_num = 3
log_dir = "C:\\Users\\<Username>\\AppData\\Local\\Temp\\logs\\peppykeep"
local_bak_home = "D:\\PeppyKeep\\backup"
local_tmp_home = "C:\\Users\\<Username>\\AppData\\Local\\Temp\\peppykeep"
max_bak_queue_size = 1

[object_storage]
enabled = true
provider = "s3"
bucket = "my-backup-bucket"
prefix = "peppykeep"
endpoint = "https://s3.example.com"
region = ""
path_style = false

[mysql]
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "backup_user"
mysql_pwd = "<provide-securely>"
mysqldump_path = "C:\\Program Files\\MySQL\\MySQL Server 8.0\\bin\\mysqldump.exe"
skip_ssl = true

[restore.mysql]
execution_mode = "native"
mysql_ip = "127.0.0.1"
mysql_port = 3306
mysql_user_name = "restore_user"
mysql_pwd = "<provide-securely>"
mysql_client_path = "C:\\Program Files\\MySQL\\MySQL Server 8.0\\bin\\mysql.exe"
workspace_home = "C:\\Users\\<Username>\\AppData\\Local\\Temp\\ppk-restore-mysql"
allow_restore_to_source_db = false
drop_target_db_before_restore = false
default_check_sql_enabled = true
custom_check_sql_file = ""
keep_workspace_on_success = true
keep_workspace_on_failure = true
v26.10.2001+202610201530