Scheduled jobs
Unattended host backup jobs. Two creation models: a new independent job with its own schedule, or a job attached to an existing PVE vzdump task that inherits that task's schedule and retention. Both produce archives identical to the interactive flow.
The two scheduled-job models
A scheduled job can be created following one of two models:
- •New independent job — ProxMenux defines the job schedule itself with its own systemd timer, independent of any other task on the host. Compatible with all three destinations: Local, PBS and Borg.
- •Attach to an existing PVE vzdump task — the job has no schedule of its own; it runs automatically whenever the parent PVE vzdump task that already backs up the VMs and LXCs on this host fires. Inherits the schedule and retention from the parent task. Compatible with Local and PBS (Borg is not supported because PVE has no native scheduler for Borg).
Attach mode — recommended when a PVE vzdump task already exists
When a PVE vzdump backup task is already configured for the VMs and LXCs on this node, attaching the host backup to that task guarantees the host configuration is captured in the same window as the guests. On restore, the guest configs come from the host backup (they live under /etc/pve), and the guest disks come from the vzdump backup taken alongside — both sets are consistent with each other, so a full-node recovery can reproduce the host and re-attach every guest without version drift.
Recommended frequency
To maximise compatibility between a host backup and its future restore, run host backups frequently. The closer the backup is to the current state of the host, the less configuration, package and component drift the restore has to reconcile.
The two modes
| Mode | Backends | Schedule | Retention |
|---|---|---|---|
| New scheduled job | Local, PBS, Borg | Own OnCalendar expression (systemd calendar syntax — e.g. daily, Mon..Fri 03:00). | Prompted separately: keep-last, keep-hourly, keep-daily, keep-weekly, keep-monthly, keep-yearly. Applied by the runner after each successful backup. |
| Attach to a PVE vzdump job | Local, PBS (Borg has no PVE-side scheduler) | Inherited from the parent PVE job. No systemd timer is installed on the ProxMenux side. | Inherited from the parent's prune-backups configuration (mapped one-to-one to the runner's KEEP_* variables via hb_pve_prune_to_keep_env). |
How attach mode works
PVE writes vzdump tasks to /etc/pve/jobs.cfg — one stanza per task, each pointing at a storage where the VM and LXC dumps land. Attach mode requires that storage to be a backend ProxMenux understands (Local or PBS); when the task fires, ProxMenux runs alongside it.
| # | Detail |
|---|---|
| 1 | During job creation, ProxMenux lists compatible parent PVE tasks via hb_pve_list_vzdump_jobs_for_backend. The operator picks one. |
| 2 | The job's .env is written with PVE_PARENT_JOB, PVE_STORAGE and the inherited KEEP_* values; no systemd timer is created. |
| 3 | hb_install_vzdump_hook registers a script-hook in /etc/vzdump.conf. When PVE runs any vzdump task, the hook script fires; if the $STOREID passed to it matches an attached job's PVE_STORAGE, the runner is invoked for that job. |
| 4 | The archive lands in the same storage the vzdump dumps just wrote to: path/dump/ for Local, or the PBS repository configured on the PVE storage entry. |
Attach mode has one operational implication: disabling or deleting the parent PVE task also disables the host backup — there is no timer of its own to fall back on. The job entry stays on disk so it can be re-attached later.
Files that make up a job
Every scheduled job is fully described by three or four files on disk. Reading them gives the full configuration of the job without relying on the interface.
| Path | Content |
|---|---|
| /var/lib/proxmenux/backup-jobs/JOB_ID.env | Backend, backup ID or destination, schedule (New mode) or PVE parent (Attach mode), enabled flag, retention KEEP_* values, credentials pointers. |
| /var/lib/proxmenux/backup-jobs/JOB_ID.paths | One absolute path per line — the frozen selection resolved from the profile at job-creation time. Editing the file re-runs the job with the new selection on the next timer fire. |
| /etc/systemd/system/proxmenux-backup-JOB_ID.timer + .service | New mode only. The service invokes run_scheduled_backup.sh JOB_ID. The timer schedules it with Persistent=true (missed fires run at next boot) and a small RandomizedDelaySec=120 to spread load when multiple jobs share the same OnCalendar expression. |
| /etc/vzdump.conf script-hook | Attach mode only. Installed once by hb_install_vzdump_hook; matches every attached job's PVE_STORAGE against the $STOREID PVE passes to the hook script. |
What a job does when it fires
Every job — whether new-model or attached — runs the same three-step sequence:
- Prepare the backup. Reads the job configuration (destination, profile, paths) and assembles the archive tree exactly the same way the interactive flow does. The result is the same archive a manual backup with those settings would produce.
- Write to the destination. Uploads or writes the archive to the configured destination — a local
.tar.zstfile, a PBS backup, or a Borg archive — using exactly the same tools and credentials a manual backup to the same destination would use. - Apply retention. Removes old backups from the destination, keeping the
keep-last/keep-daily/keep-weeklycounts configured on the job. Pruning is performed by the destination itself: PBS applies its own retention, Borg runsborg prune, and for Local ProxMenux deletes the files that fall outside thekeep-lastwindow.
Managing jobs
The scheduler menu (Scripts TUI) and the Monitor Backups tab expose the same actions on any job.
| Action | Detail |
|---|---|
| Run now | Invokes the runner immediately, bypassing the timer / vzdump hook. Useful to verify a job configuration without waiting for the next scheduled fire. |
| Enable / Disable | New mode: systemctl enable/disable --now the timer. Attach mode: flips the ENABLED flag in the job env — the hook script honours it on the next PVE fire. |
| Edit | Reopens the destination, schedule, profile and retention prompts and rewrites the job files. Preserves the job ID. |
| Delete | Removes the job env, paths file, systemd timer + service (New mode), and disables the hook binding (Attach mode). Does not touch archives already on the destination. |
| View log | Streams /var/log/proxmenux/backup-jobs/JOB_ID-YYYYMMDD_HHMMSS.log — one log file per run. The runner also emits a compact status line to journald under the systemd service. |
Notifications
Every scheduled run fires the same hb_notify_lifecycle events as the interactive flow (start, complete, fail). If notification channels are configured in the Monitor, unattended jobs surface their results the same way manual backups do — an operator does not need to check the log to know whether a job succeeded.
Where to go next
- Creating backups — the interactive flow that shares the backend with the scheduler.
- Destinations — per-backend configuration used by both the interactive flow and the scheduler.
- Restoring — the flow that consumes what jobs produce.