[pbs-devel] [PATCH v2 proxmox-backup] fix #6185: client/docs: explicitly mention archive name restrictions

[Christian Ebner]

On 2/21/25 14:51, Shannon Sterz wrote:
> On Thu Feb 20, 2025 at 4:56 PM CET, Christian Ebner wrote:
>> Mention in the docs and the api parameter description the limitations
>> for archive name labels. They must contain alphanumerics, hyphens and
>> underscores only to match the regex pattern.
>>
>> By setting this in the api parameter description, it will be included
>> in the man page for proxmox-backup-client.
>>
>> Fixes: https://bugzilla.proxmox.com/show_bug.cgi?id=6185
>> Signed-off-by: Christian Ebner <c.ebner at proxmox.com>
>> ---
>> changes since version 1:
>> - Avoid newline in output by formatting multi-line string with backslash.
>>
>>   docs/backup-client.rst                 |  1 +
>>   pbs-client/src/backup_specification.rs | 10 ++++++----
>>   proxmox-backup-client/src/main.rs      |  3 ++-
>>   3 files changed, 9 insertions(+), 5 deletions(-)
>>
>> diff --git a/docs/backup-client.rst b/docs/backup-client.rst
>> index 1c2a98ed8..e11c0142a 100644
>> --- a/docs/backup-client.rst
>> +++ b/docs/backup-client.rst
>> @@ -169,6 +169,7 @@ the client. The format is:
>>
>>       <archive-name>.<type>:<source-path>
>>
>> +The ``archive-name`` must contain alphanumerics, hyphens and underscores only.
>>   Common types are ``.pxar`` for file archives and ``.img`` for block
>>   device images. To create a backup of a block device, run the following command:
>>
>> diff --git a/pbs-client/src/backup_specification.rs b/pbs-client/src/backup_specification.rs
>> index b6fbc555c..e44d23d90 100644
>> --- a/pbs-client/src/backup_specification.rs
>> +++ b/pbs-client/src/backup_specification.rs
>> @@ -7,10 +7,12 @@ const_regex! {
>>       BACKUPSPEC_REGEX = r"^([a-zA-Z0-9_-]+\.(pxar|img|conf|log)):(.+)$";
>>   }
>>
>> -pub const BACKUP_SOURCE_SCHEMA: Schema =
>> -    StringSchema::new("Backup source specification ([<label>:<path>]).")
>> -        .format(&ApiStringFormat::Pattern(&BACKUPSPEC_REGEX))
>> -        .schema();
>> +pub const BACKUP_SOURCE_SCHEMA: Schema = StringSchema::new(
>> +    "Backup source specification ([<label>:<path>]), the specification \
>> +    'label' must contain alphanumerics, hyphens and underscores only.",
> 
> this description doesn't mention the extensions though and makes it
> sound like they should be included, even though the regex requires it.
> might make sense to indicate that like below here too?

Yes, good catch! This is currently not exposed anywhere user facing 
AFAIK but I do agree that it makes totally sense to include the 
extension in the backup source schemas description.

Will send a v3, thanks!