diff --git a/doc/reference/instance_options.md b/doc/reference/instance_options.md index 29b421a6af..215e1ca270 100644 --- a/doc/reference/instance_options.md +++ b/doc/reference/instance_options.md @@ -304,32 +304,13 @@ Key | Type | Default :-- | :--- | :------ | :---------- | :---------- | :---------- `snapshots.schedule` | string | - | no | - | {{snapshot_schedule_format}} `snapshots.schedule.stopped` | bool | `false` | no | - | Controls whether to automatically snapshot stopped instances -`snapshots.pattern` | string | `snap%d` | no | - | Pongo2 template string which represents the snapshot name (used for scheduled snapshots and unnamed snapshots) -`snapshots.expiry` | string | - | no | - | Controls when snapshots are to be deleted (expects expression like `1M 2H 3d 4w 5m 6y`) +`snapshots.pattern` | string | `snap%d` | no | - | {{snapshot_pattern_format}}; see {ref}`instance-options-snapshots-names` +`snapshots.expiry` | string | - | no | - | {{snapshot_expiry_format}} -LXD supports scheduled snapshots which can be created at most once every minute. -There are three configuration options: +(instance-options-snapshots-names)= +### Automatic snapshot names -- `snapshots.schedule` takes a shortened cron expression: ` `. - If this is empty (default), no snapshots will be created. -- `snapshots.schedule.stopped` controls whether to automatically snapshot stopped instances. - It defaults to `false`. -- `snapshots.pattern` takes a Pongo2 template string to format the snapshot name. - To name snapshots with time stamps, the Pongo2 context variable `creation_date` can be used. - Be aware that you should format the date (e.g. use `{{ creation_date|date:"2006-01-02_15-04-05" }}`) in your template string to avoid forbidden characters in the snapshot name. - Another way to avoid name collisions is to use the placeholder `%d`. - If a snapshot with the same name (excluding the placeholder) already exists, all existing snapshot names will be taken into account to find the highest number at the placeholders position. - This number will be incremented by one for the new name. - The starting number if no snapshot exists will be `0`. - The default behavior of `snapshots.pattern` is equivalent to a format string of `snap%d`. - -Example of using Pongo2 syntax to format snapshot names with timestamps: - -```bash -lxc config set INSTANCE snapshots.pattern "{{ creation_date|date:'2006-01-02_15-04-05' }}" -``` - -This results in snapshots named `{date/time of creation}` down to the precision of a second. +{{snapshot_pattern_detail}} (instance-options-volatile)= ## Volatile internal data diff --git a/doc/reference/storage_btrfs.md b/doc/reference/storage_btrfs.md index dee1402287..50f6deb685 100644 --- a/doc/reference/storage_btrfs.md +++ b/doc/reference/storage_btrfs.md @@ -77,9 +77,11 @@ Key | Type | Condition | Default `security.unmapped` | bool | custom volume | same as `volume.security.unmapped` or `false` | Disable ID mapping for the volume `size` | string | appropriate driver | same as `volume.size` | Size/quota of the storage volume `snapshots.expiry` | string | custom volume | same as `volume.snapshots.expiry` | {{snapshot_expiry_format}} -`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d`| {{snapshot_pattern_format}} +`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d`| {{snapshot_pattern_format}} [^*] `snapshots.schedule` | string | custom volume | same as `volume.snapshots.schedule` | {{snapshot_schedule_format}} +[^*]: {{snapshot_pattern_detail}} + ### Storage bucket configuration To enable storage buckets for local storage pool drivers and allow applications to access the buckets via the S3 protocol, you must configure the `core.storage_buckets_address` server setting (see {ref}`server`). diff --git a/doc/reference/storage_ceph.md b/doc/reference/storage_ceph.md index ed3a6c9c60..2a42eb0870 100644 --- a/doc/reference/storage_ceph.md +++ b/doc/reference/storage_ceph.md @@ -107,5 +107,7 @@ Key | Type | Condition | Default `security.unmapped` | bool | custom volume | same as `volume.security.unmapped` or `false` | Disable ID mapping for the volume `size` | string | appropriate driver | same as `volume.size` | Size/quota of the storage volume `snapshots.expiry` | string | custom volume | same as `volume.snapshots.expiry` | {{snapshot_expiry_format}} -`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} +`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} [^*] `snapshots.schedule` | string | custom volume | same as `volume.snapshots.schedule` | {{snapshot_schedule_format}} + +[^*]: {{snapshot_pattern_detail}} diff --git a/doc/reference/storage_cephfs.md b/doc/reference/storage_cephfs.md index d0b92300d2..c41476cd8b 100644 --- a/doc/reference/storage_cephfs.md +++ b/doc/reference/storage_cephfs.md @@ -80,5 +80,7 @@ Key | Type | Condition | Default `security.unmapped` | bool | custom volume | same as `volume.security.unmapped` or `false` | Disable ID mapping for the volume `size` | string | appropriate driver | same as `volume.size` | Size/quota of the storage volume `snapshots.expiry` | string | custom volume | same as `volume.snapshots.expiry` | {{snapshot_expiry_format}} -`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} +`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} [^*] `snapshots.schedule` | string | custom volume | same as `volume.snapshots.schedule` | {{snapshot_schedule_format}} + +[^*]: {{snapshot_pattern_detail}} diff --git a/doc/reference/storage_dir.md b/doc/reference/storage_dir.md index f992408d07..4ec2a983b3 100644 --- a/doc/reference/storage_dir.md +++ b/doc/reference/storage_dir.md @@ -42,9 +42,11 @@ Key | Type | Condition | Default `security.unmapped` | bool | custom volume | same as `volume.security.unmapped` or `false` | Disable ID mapping for the volume `size` | string | appropriate driver | same as `volume.size` | Size/quota of the storage volume `snapshots.expiry` | string | custom volume | same as `volume.snapshots.expiry` | {{snapshot_expiry_format}} -`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} +`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} [^*] `snapshots.schedule` | string | custom volume | same as `volume.snapshots.schedule` | {{snapshot_schedule_format}} +[^*]: {{snapshot_pattern_detail}} + ### Storage bucket configuration To enable storage buckets for local storage pool drivers and allow applications to access the buckets via the S3 protocol, you must configure the `core.storage_buckets_address` server setting (see {ref}`server`). diff --git a/doc/reference/storage_lvm.md b/doc/reference/storage_lvm.md index 102106ebcf..d77bfe8c25 100644 --- a/doc/reference/storage_lvm.md +++ b/doc/reference/storage_lvm.md @@ -71,9 +71,11 @@ Key | Type | Condition | Default `security.unmapped` | bool | custom volume | same as `volume.security.unmapped` or `false` | Disable ID mapping for the volume `size` | string | appropriate driver | same as `volume.size` | Size/quota of the storage volume `snapshots.expiry` | string | custom volume | same as `volume.snapshots.expiry` | {{snapshot_expiry_format}} -`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} +`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} [^*] `snapshots.schedule` | string | custom volume | same as `volume.snapshots.schedule` | {{snapshot_schedule_format}} +[^*]: {{snapshot_pattern_detail}} + ### Storage bucket configuration To enable storage buckets for local storage pool drivers and allow applications to access the buckets via the S3 protocol, you must configure the `core.storage_buckets_address` server setting (see {ref}`server`). diff --git a/doc/reference/storage_zfs.md b/doc/reference/storage_zfs.md index 10497f1ac7..f26254cd2b 100644 --- a/doc/reference/storage_zfs.md +++ b/doc/reference/storage_zfs.md @@ -114,13 +114,15 @@ Key | Type | Condition | Default `security.unmapped` | bool | custom volume | same as `volume.security.unmapped` or `false` | Disable ID mapping for the volume `size` | string | appropriate driver | same as `volume.size` | Size/quota of the storage volume `snapshots.expiry` | string | custom volume | same as `volume.snapshots.expiry` | {{snapshot_expiry_format}} -`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} +`snapshots.pattern` | string | custom volume | same as `volume.snapshots.pattern` or `snap%d` | {{snapshot_pattern_format}} [^*] `snapshots.schedule` | string | custom volume | same as `snapshots.schedule` | {{snapshot_schedule_format}} `zfs.blocksize` | string | ZFS driver | same as `volume.zfs.blocksize` | Size of the ZFS block in range from 512 to 16 MiB (must be power of 2) - for block volume, a maximum value of 128 KiB will be used even if a higher value is set `zfs.remove_snapshots` | bool | ZFS driver | same as `volume.zfs.remove_snapshots` or `false` | Remove snapshots as needed `zfs.use_refquota` | bool | ZFS driver | same as `volume.zfs.use_refquota` or `false` | Use `refquota` instead of `quota` for space `zfs.reserve_space` | bool | ZFS driver | same as `volume.zfs.reserve_space` or `false` | Use `reservation`/`refreservation` along with `quota`/`refquota` +[^*]: {{snapshot_pattern_detail}} + ### Storage bucket configuration To enable storage buckets for local storage pool drivers and allow applications to access the buckets via the S3 protocol, you must configure the `core.storage_buckets_address` server setting (see {ref}`server`). diff --git a/doc/substitutions.yaml b/doc/substitutions.yaml index fc6e4b01be..f31b8dc1c5 100644 --- a/doc/substitutions.yaml +++ b/doc/substitutions.yaml @@ -2,7 +2,8 @@ {note_ip_addresses_CIDR: "LXD uses the [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) where network subnet information is required, for example, `192.0.2.0/24` or `2001:db8::/32`. This does not apply to cases where a single address is required, for example, local/remote addresses of tunnels, NAT addresses or specific addresses to apply to an instance.", snapshot_expiry_format: "Controls when snapshots are to be deleted (expects an expression like `1M 2H 3d 4w 5m 6y`)", snapshot_pattern_format: "Pongo2 template string that represents the snapshot name (used for scheduled snapshots and unnamed snapshots)", -snapshot_schedule_format: "Cron expression (` `), or a comma separated list of schedule aliases (`@hourly`, `@daily`, `@midnight`, `@weekly`, `@monthly`, `@annually`, `@yearly`)", +snapshot_pattern_detail: "The `snapshots.pattern` option takes a Pongo2 template string to format the snapshot name.\n\nTo add a time stamp to the snapshot name, use the Pongo2 context variable `creation_date`.\nMake sure to format the date in your template string to avoid forbidden characters in the snapshot name.\nFor example, set `snapshots.pattern` to `{{ creation_date|date:'2006-01-02_15-04-05' }}` to name the snapshots after their time of creation, down to the precision of a second.\n\nAnother way to avoid name collisions is to use the placeholder `%d` in the pattern.\nFor the first snapshot, the placeholder is replaced with `0`.\nFor subsequent snapshots, the existing snapshot names are taken into account to find the highest number at the placeholder's position.\nThis number is then incremented by one for the new name.", +snapshot_schedule_format: "Cron expression (` `), a comma-separated list of schedule aliases (`@hourly`, `@daily`, `@midnight`, `@weekly`, `@monthly`, `@annually`, `@yearly`), or empty to disable automatic snapshots (the default)", enable_ID_shifting: "Enable ID shifting overlay (allows attach by multiple isolated instances)", block_filesystem: "File system of the storage volume: `btrfs`, `ext4` or `xfs` (`ext4` if not set)", volume_configuration: "```{tip}\nIn addition to these configurations, you can also set default values for the storage volume configurations. See {ref}`storage-configure-vol-default`.\n```"}