synology_apm.sdk.models.protection_plan module

ProtectionPlan and all associated policy, config, task, and request models.

class synology_apm.sdk.models.protection_plan.ProtectionSchedule(frequency, start_time, weekdays=())

Bases: object

Backup schedule configuration.

Variables:

  • frequency (synology_apm.sdk.enums.ScheduleFrequency) – Schedule frequency (MANUAL / HOURLY / DAILY / WEEKLY / AFTER_BACKUP).

  • start_time (datetime.time | None) – Execution time. None for MANUAL / AFTER_BACKUP; time(0, run_minute) for HOURLY (only minute is meaningful — runs at that minute of every hour); full HH:MM for DAILY / WEEKLY.

  • weekdays (tuple[synology_apm.sdk.enums.WeekDay, ...]) – Days of the week to run (only meaningful for WEEKLY; at least one weekday is required for WEEKLY; always empty for other frequencies).

frequency: ScheduleFrequency
start_time: time | None
weekdays: tuple[WeekDay, ...] = ()
class synology_apm.sdk.models.protection_plan.GFSRetention(daily_versions, weekly_versions, monthly_versions, yearly_versions)

Bases: object

GFS (Grandfather-Father-Son) rotation retention policy details.

daily_versions: int
weekly_versions: int
monthly_versions: int
yearly_versions: int
class synology_apm.sdk.models.protection_plan.ProtectionRetentionPolicy(retention_type, days=None, versions=None, gfs=None)

Bases: object

Version retention policy for a Protection Plan.

retention_type: RetentionType
days: int | None = None
versions: int | None = None
gfs: GFSRetention | None = None
class synology_apm.sdk.models.protection_plan.ProtectionPlanPolicy(retention, schedule)

Bases: object

Combined schedule and retention policy for a backup or Backup Copy.

Variables:
retention: ProtectionRetentionPolicy
schedule: ProtectionSchedule | None
class synology_apm.sdk.models.protection_plan.PlanBackupCopyStatus(status, reason, pending_version_count=0, remaining_bytes=None, skipped_workload_count=0)

Bases: object

Backup copy status summary for a Protection Plan.

Variables:

  • status (synology_apm.sdk.enums.VersionCopyStatus) – Overall backup copy status for this plan; parallels WorkloadVersion.copy_status.

  • reason (synology_apm.sdk.enums.CopyReason | None) – Detail reason when status is SKIPPED, RETRY, or FAILED; NO_VERSIONS_TO_COPY when the plan has no versions eligible for copy; None otherwise.

  • pending_version_count (int) – Number of versions waiting to be copied (meaningful when WAITING, IN_PROGRESS, RETRY, or FAILED).

  • remaining_bytes (int | None) – Estimated bytes remaining for the pending copy; None when unavailable.

  • skipped_workload_count (int) – Number of workloads skipped in the last copy run (meaningful when SKIPPED).

status: VersionCopyStatus
reason: CopyReason | None
pending_version_count: int = 0
remaining_bytes: int | None = None
skipped_workload_count: int = 0
class synology_apm.sdk.models.protection_plan.BackupCopyPolicy(destination, retention, schedule)

Bases: object

Backup Copy configuration as read from a Protection Plan (read-only).

To modify Backup Copy settings, use BackupCopyConfig in create()/update() requests. To look up the full destination object for a new request, resolve destination.identifier via apm.backup_servers or apm.remote_storages.

Variables:
destination: LocationInfo
retention: ProtectionRetentionPolicy
schedule: ProtectionSchedule
class synology_apm.sdk.models.protection_plan.BackupCopyConfig(destination, retention, schedule)

Bases: object

Backup Copy configuration for create()/update() requests.

Variables:
destination: BackupServer | RemoteStorage
retention: ProtectionRetentionPolicy
schedule: ProtectionSchedule
class synology_apm.sdk.models.protection_plan.MachineVmConfig(enable_app_aware_bkp=True, enable_verification=False, verification_video_duration_seconds=120, enable_datastore_usage_detection=False, datastore_min_free_space_percent=10)

Bases: object

VM workload advanced settings.

Variables:

  • enable_app_aware_bkp (bool) – Application-consistent backup (quiesces VSS/VMware Tools).

  • enable_verification (bool) – Run backup verification after each backup.

  • verification_video_duration_seconds (int) – Length of the verification recording in seconds.

  • enable_datastore_usage_detection (bool) – Monitor datastore usage during backup.

  • datastore_min_free_space_percent (int) – Minimum free space (%) the datastore must maintain.

enable_app_aware_bkp: bool = True
enable_verification: bool = False
verification_video_duration_seconds: int = 120
enable_datastore_usage_detection: bool = False
datastore_min_free_space_percent: int = 10
class synology_apm.sdk.models.protection_plan.MachinePcConfig(shutdown_after_backup=False, wake_for_backup=False, prevent_sleep_during_backup=False)

Bases: object

PC workload advanced settings (Windows and macOS).

Variables:

  • shutdown_after_backup (bool) – Shut down the device after backup completes.

  • wake_for_backup (bool) – Wake the device from sleep before backup starts.

  • prevent_sleep_during_backup (bool) – Prevent the device from entering sleep during backup (Windows only).

shutdown_after_backup: bool = False
wake_for_backup: bool = False
prevent_sleep_during_backup: bool = False
class synology_apm.sdk.models.protection_plan.MachinePsConfig(enable_app_aware_bkp=True, enable_verification=False, verification_video_duration_seconds=120, shutdown_after_backup=False, wake_for_backup=False, prevent_sleep_during_backup=False)

Bases: object

Physical server workload advanced settings.

Variables:

  • enable_app_aware_bkp (bool) – Application-consistent backup (quiesces VSS).

  • enable_verification (bool) – Run backup verification after each backup.

  • verification_video_duration_seconds (int) – Length of the verification recording in seconds.

  • shutdown_after_backup (bool) – Shut down the server after backup completes.

  • wake_for_backup (bool) – Wake the server from sleep before backup starts.

  • prevent_sleep_during_backup (bool) – Prevent the server from entering sleep during backup (Windows only).

enable_app_aware_bkp: bool = True
enable_verification: bool = False
verification_video_duration_seconds: int = 120
shutdown_after_backup: bool = False
wake_for_backup: bool = False
prevent_sleep_during_backup: bool = False
class synology_apm.sdk.models.protection_plan.MachineDbConfig(action_on_error=DbActionOnError.CONTINUE, mssql_log_setting=MssqlLogSetting.DO_NOT_TRUNCATE, oracle_log_setting=OracleLogSetting.DO_NOT_DELETE)

Bases: object

Database processing configuration (applies when DB backup is enabled).

Variables:
action_on_error: DbActionOnError = 'continue'
mssql_log_setting: MssqlLogSetting = 'do_not_truncate'
oracle_log_setting: OracleLogSetting = 'do_not_delete'
class synology_apm.sdk.models.protection_plan.MachineBackupWindow(enabled, allowed_hours=<factory>)

Bases: object

Allowed time slots for backup execution.

Variables:

  • enabled (bool) – Whether the backup window restriction is active. When False, backup can run at any time.

  • allowed_hours (dict[synology_apm.sdk.enums.WeekDay, frozenset[int]]) – Weekday → set of allowed hours (0–23). Absent weekdays are fully blocked. Empty dict with enabled=True blocks all backup. Ignored when enabled is False.

enabled: bool
allowed_hours: dict[WeekDay, frozenset[int]]
class synology_apm.sdk.models.protection_plan.EventTriggerConfig(on_sign_out=False, on_lock=False, on_startup=False, min_interval=<factory>)

Bases: object

Event-triggered backup settings for PC/Mac tasks.

Variables:

  • on_sign_out (bool) – Back up when the user signs out.

  • on_lock (bool) – Back up when the screen locks.

  • on_startup (bool) – Back up on system startup.

  • min_interval (datetime.timedelta) – Minimum time between consecutive event-triggered backups. Sub-minute precision is not supported; values are rounded down to the nearest minute.

Raises:

  • ValueError – At least one of on_sign_out, on_lock, on_startup must be True.

  • ValueError – min_interval must be a positive duration.

on_sign_out: bool = False
on_lock: bool = False
on_startup: bool = False
min_interval: timedelta
class synology_apm.sdk.models.protection_plan.MachineTaskSchedule(time_schedule=None, event_trigger=None)

Bases: object

Per-task backup schedule for an individual task entry in a DEVICE plan.

Variables:
time_schedule: ProtectionSchedule | None = None
event_trigger: EventTriggerConfig | None = None
class synology_apm.sdk.models.protection_plan.MachineTaskConfig(workload_type, os_type, scope=None, custom_volumes=(), include_external_drives=False, include_boot_partition=True, use_main_schedule=True, schedule=None)

Bases: object

One backup scope/schedule entry in a DEVICE plan’s task array.

A plan always contains at least 6 entries — one for each mandatory (workload_type, os_type) pair. PC and PS pairs may have additional entries to back up different scopes independently. VM and FS are always exactly one entry each and do not support scope customization.

Variables:

  • workload_type (synology_apm.sdk.enums.MachineWorkloadType) – PC, PS, VM, or FS.

  • os_type (synology_apm.sdk.enums.MachineOsType) – OS for this entry. Must match the workload type: PC → WINDOWS or MAC; PS → WINDOWS or LINUX; VM/FS → NONE.

  • scope (synology_apm.sdk.enums.MachineTaskScope | None) – Backup scope; not applicable for VM and FS workloads.

  • custom_volumes (tuple[str, ...]) – Volume specifiers when scope=CUSTOM_VOLUME. Windows: drive letters (“C:”) or volume labels (“Volume_1”). macOS: volume labels or “$System_Volume”. Linux PS: mount paths (“/my/mount/point”).

  • include_external_drives (bool) – Include external drives when scope=ENTIRE_MACHINE. Ignored for SYSTEM_VOLUME and CUSTOM_VOLUME.

  • include_boot_partition (bool) – Include boot partition when scope=CUSTOM_VOLUME and the selection contains the system partition.

  • use_main_schedule (bool) – Follow the plan’s main schedule. When True, schedule is ignored.

  • schedule (synology_apm.sdk.models.protection_plan.MachineTaskSchedule | None) – Per-task schedule; only used when use_main_schedule=False.

workload_type: MachineWorkloadType
os_type: MachineOsType
scope: MachineTaskScope | None = None
custom_volumes: tuple[str, ...] = ()
include_external_drives: bool = False
include_boot_partition: bool = True
use_main_schedule: bool = True
schedule: MachineTaskSchedule | None = None
class synology_apm.sdk.models.protection_plan.ProtectionPlan(plan_id, name, category, policy=None, workload_count=None, description='', successful_workload_count=0, unsuccessful_workload_count=0, is_immutable=False, backup_copy_policy=None, backup_copy_status=None, run_schedule_by_controller_time=False, vm_config=None, pc_config=None, ps_config=None, db_config=None, backup_window=None, tasks=None)

Bases: object

Core configuration unit for a backup task.

Variables:
plan_id: str
name: str
category: WorkloadCategory
policy: ProtectionPlanPolicy | None = None
workload_count: int | None = None
description: str = ''
successful_workload_count: int = 0
unsuccessful_workload_count: int = 0
is_immutable: bool = False
backup_copy_policy: BackupCopyPolicy | None = None
backup_copy_status: PlanBackupCopyStatus | None = None
run_schedule_by_controller_time: bool = False
vm_config: MachineVmConfig | None = None
pc_config: MachinePcConfig | None = None
ps_config: MachinePsConfig | None = None
db_config: MachineDbConfig | None = None
backup_window: MachineBackupWindow | None = None
tasks: tuple[MachineTaskConfig, ...] | None = None
class synology_apm.sdk.models.protection_plan.MachinePlanCreateRequest(name, retention, schedule, description='', is_immutable=False, vm_config=None, pc_config=None, ps_config=None, db_config=None, backup_window=None, tasks=None, backup_copy=None, run_schedule_by_controller_time=False)

Bases: object

Parameters for creating a Machine (DEVICE) Protection Plan.

Variables:
Raises:

  • ValueError – schedule frequency cannot be AFTER_BACKUP.

  • ValueError – WEEKLY schedule requires at least one weekday.

  • ValueError – Immutable plans require KEEP_DAYS retention.

  • ValueError – tasks is missing a mandatory (workload_type, os_type) pair.

  • ValueError – tasks contains more than one FS or VM entry.

  • ValueError – tasks contains a duplicate MachineTaskConfig.

  • ValueError – A task’s os_type is invalid for its workload_type.

  • ValueError – A VM or FS task has a non-None scope.

  • ValueError – custom_volumes is non-empty when scope != CUSTOM_VOLUME.

  • ValueError – A task with use_main_schedule=False has no schedule.

  • ValueError – A non-PC task’s schedule has event_trigger set.

  • ValueError – A task schedule uses AFTER_BACKUP frequency.

  • ValueError – A task WEEKLY schedule has no weekdays.

name: str
retention: ProtectionRetentionPolicy
schedule: ProtectionSchedule
description: str = ''
is_immutable: bool = False
vm_config: MachineVmConfig | None = None
pc_config: MachinePcConfig | None = None
ps_config: MachinePsConfig | None = None
db_config: MachineDbConfig | None = None
backup_window: MachineBackupWindow | None = None
tasks: tuple[MachineTaskConfig, ...] | None = None
backup_copy: BackupCopyConfig | None = None
run_schedule_by_controller_time: bool = False
class synology_apm.sdk.models.protection_plan.M365PlanCreateRequest(name, retention, schedule, description='', is_immutable=False, backup_copy=None, run_schedule_by_controller_time=False)

Bases: object

Parameters for creating an M365 Protection Plan.

Variables:
Raises:

  • ValueError – schedule frequency cannot be AFTER_BACKUP.

  • ValueError – WEEKLY schedule requires at least one weekday.

  • ValueError – Immutable plans require KEEP_DAYS retention.

name: str
retention: ProtectionRetentionPolicy
schedule: ProtectionSchedule
description: str = ''
is_immutable: bool = False
backup_copy: BackupCopyConfig | None = None
run_schedule_by_controller_time: bool = False