[GH-ISSUE #82] Documentation unclear about exclusions in vmid parameter and missing other parameters

kerem commented

2026-02-26 17:44:17 +03:00

Owner

Originally created by @meyergru on GitHub (Oct 19, 2023).
Original GitHub issue: https://github.com/Corsinvest/cv4pve-autosnap/issues/82

What happened?

What is a little time-consuming is that the documentation is somewhat unclear.

In the README, it says that there are "exclusions" like "-105". If you take that verbosely and specify it like that to exclude just one vmid, you will get an error that hides the fact that this does not work, stating something about missing permissions. You have to specify 'all,-105' for that. The error messages show:

----- VMs with '-105' NOT FOUND -----
----- POSSIBLE PROBLEM PERMISSION 'VM.Audit' -----
----- POSSIBLE PROBLEM PERMISSION 'Datastore.Audit' -----

Some parameters are not documented at all, like '--only-running' or '--script', even if example scripts are provided,

Expected behavior

Better documentation.

Relevant log output

No response

Proxmox VE Version

8.0.4

Version (bug)

1.14.8

Version (working)

none

On what operating system are you experiencing the issue?

Linux

Pull Request

I would like to do a Pull Request

Originally created by @meyergru on GitHub (Oct 19, 2023). Original GitHub issue: https://github.com/Corsinvest/cv4pve-autosnap/issues/82 ### What happened? What is a little time-consuming is that the documentation is somewhat unclear. 1. In the README, it says that there are "exclusions" like "-105". If you take that verbosely and specify it like that to exclude just one vmid, you will get an error that hides the fact that this does not work, stating something about missing permissions. You have to specify 'all,-105' for that. The error messages show: ``` ----- VMs with '-105' NOT FOUND ----- ----- POSSIBLE PROBLEM PERMISSION 'VM.Audit' ----- ----- POSSIBLE PROBLEM PERMISSION 'Datastore.Audit' ----- ``` 2. Some parameters are not documented at all, like '--only-running' or '--script', even if example scripts are provided, ### Expected behavior Better documentation. ### Relevant log output _No response_ ### Proxmox VE Version 8.0.4 ### Version (bug) 1.14.8 ### Version (working) none ### On what operating system are you experiencing the issue? Linux ### Pull Request - [ ] I would like to do a Pull Request

kerem

2026-02-26 17:44:17 +03:00

closed this issue
added the
needs investigation
label

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@franklupo commented on GitHub (Oct 19, 2023):

Hi,
can you write the command line you use? Best regards
Best regards

@franklupo commented on GitHub (Oct 19, 2023): Hi, can you write the command line you use? Best regards Best regards

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@meyergru commented on GitHub (Oct 19, 2023):

cv4pve-autosnap --host="127.0.0.1" --api-token='snapshot@pam!snapshot=f026fff0-37a2-43fe-b717-373d60ecfea8' --vmid="-105" snap --only-running --label="once" --keep=1

whereas

cv4pve-autosnap --host="127.0.0.1" --api-token='snapshot@pam!snapshot=f026fff0-37a2-43fe-b717-373d60ecfea8' --vmid="all,-105" snap --only-running --label="once" --keep=1

works fine.

@meyergru commented on GitHub (Oct 19, 2023): `cv4pve-autosnap --host="127.0.0.1" --api-token='snapshot@pam!snapshot=f026fff0-37a2-43fe-b717-373d60ecfea8' --vmid="-105" snap --only-running --label="once" --keep=1` whereas `cv4pve-autosnap --host="127.0.0.1" --api-token='snapshot@pam!snapshot=f026fff0-37a2-43fe-b717-373d60ecfea8' --vmid="all,-105" snap --only-running --label="once" --keep=1` works fine.

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@franklupo commented on GitHub (Oct 31, 2023):

I'm checking the problem

Best regards

@franklupo commented on GitHub (Oct 31, 2023): I'm checking the problem Best regards

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@franklupo commented on GitHub (Oct 31, 2023):

Hi,
for parameters '--only-running' or '--script' if you execute

cv4pve-autosnap snap --help

show help sub command.

@franklupo commented on GitHub (Oct 31, 2023): Hi, for parameters '--only-running' or '--script' if you execute ```sh cv4pve-autosnap snap --help ``` show help sub command.

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@franklupo commented on GitHub (Oct 31, 2023):

----- VMs with '-105' NOT FOUND -----
----- POSSIBLE PROBLEM PERMISSION 'VM.Audit' -----
----- POSSIBLE PROBLEM PERMISSION 'Datastore.Audit' -----

The result of that setting is no vm found, so it could be a permissions issue.

Btest regards

@franklupo commented on GitHub (Oct 31, 2023): ```txt ----- VMs with '-105' NOT FOUND ----- ----- POSSIBLE PROBLEM PERMISSION 'VM.Audit' ----- ----- POSSIBLE PROBLEM PERMISSION 'Datastore.Audit' ----- ``` The result of that setting is no vm found, so it could be a permissions issue. Btest regards

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@meyergru commented on GitHub (Oct 31, 2023):

No, it is just a follow-up error because of the --vmid="-105" which in itself does not find a VM. I also thought it was a permission issue but if you correctly specify --vmid "all,-105", the problem goes away. So, if no VM is found, there should be no misleading additional errors.

@meyergru commented on GitHub (Oct 31, 2023): No, it is just a follow-up error because of the --vmid="-105" which in itself does not find a VM. I also thought it was a permission issue but if you correctly specify --vmid "all,-105", the problem goes away. So, if no VM is found, there should be no misleading additional errors.

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@meyergru commented on GitHub (Oct 31, 2023):

About the "show help sub": I talked about the Readme.md and the examples. I only found these parameters because someone else had referenced them.

@meyergru commented on GitHub (Oct 31, 2023): About the "show help sub": I talked about the Readme.md and the examples. I only found these parameters because someone else had referenced them.

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@franklupo commented on GitHub (Oct 31, 2023):

If no VM is found, it may be a user permissions error.

@franklupo commented on GitHub (Oct 31, 2023): > If no VM is found, it may be a user permissions error.

kerem commented

2026-02-26 17:44:18 +03:00

Author

Owner

@franklupo commented on GitHub (Oct 31, 2023):

About the "show help sub": I talked about the Readme.md and the examples. I only found these parameters because someone else had referenced them.

ok, so I have to explain all the parameters and print all the help?

@franklupo commented on GitHub (Oct 31, 2023): > About the "show help sub": I talked about the Readme.md and the examples. I only found these parameters because someone else had referenced them. ok, so I have to explain all the parameters and print all the help?

kerem commented

2026-02-26 17:44:19 +03:00

Author

Owner

@meyergru commented on GitHub (Oct 31, 2023):

If no VM is found, it may be a user permissions error.

For the 3rd time: No, it is NOT a user permissions error. Only the error message is strongly misleading. The root cause is that I used --vmid="-105", which is inherently suggested by the help text, but does not function in itself. In order to exclude just one VM, you have to first say "all", THEN exclude a specific VM, like "all,-105". "-105" will never find any VM at all, resulting in that erroneous error message. If at all there should be a message pointing to the "possible" cause of no VM found, it should be that excluding a VM in itself can never find any VM, even if others do in fact exist.

You asked for an example, I gave it. Just try for yourself: Use --vmid="-105" (regardless if you have a VM with that number). If you expect to snapshot all the other VMs, you are mistaken and will get exactly these error messages about permissions.

@meyergru commented on GitHub (Oct 31, 2023): > > > > If no VM is found, it may be a user permissions error. For the 3rd time: No, it is NOT a user permissions error. Only the error message is strongly misleading. The root cause is that I used --vmid="-105", which is inherently suggested by the help text, but does not function in itself. In order to exclude just one VM, you have to first say "all", THEN exclude a specific VM, like "all,-105". "-105" will never find any VM at all, resulting in that erroneous error message. If at all there should be a message pointing to the "possible" cause of no VM found, it should be that excluding a VM in itself can never find any VM, even if others do in fact exist. You asked for an example, I gave it. Just try for yourself: Use --vmid="-105" (regardless if you have a VM with that number). If you expect to snapshot all the other VMs, you are mistaken and will get exactly these error messages about permissions.

kerem commented

2026-02-26 17:44:19 +03:00

Author

Owner

@meyergru commented on GitHub (Oct 31, 2023):

About "having to explain all the parameters" (and in a clear way): documentation is IMHO a means to convey the features of a piece of software to spare others the act of doing software archeology. I have lost hours of poking around with just the issues I mentioned.

It is like writing a book: You put much more effort into writing a book than to read it. Why? Because you are only one person and probably (hopefully) many people will read it. Therefore, time spent to make it easier on them one time is beneficial in the grand perspective.

So, if you want your software to be put to good use, take the time and make it easier for others to use it.

@meyergru commented on GitHub (Oct 31, 2023): About "having to explain all the parameters" (and in a clear way): documentation is IMHO a means to convey the features of a piece of software to spare others the act of doing software archeology. I have lost hours of poking around with just the issues I mentioned. It is like writing a book: You put much more effort into writing a book than to read it. Why? Because you are only one person and probably (hopefully) many people will read it. Therefore, time spent to make it easier on them one time is beneficial in the grand perspective. So, if you want your software to be put to good use, take the time and make it easier for others to use it.

kerem commented

2026-02-26 17:44:19 +03:00

Author

Owner

@franklupo commented on GitHub (Oct 31, 2023):

About "having to explain all the parameters" (and in a clear way): documentation is IMHO a means to convey the features of a piece of software to spare others the act of doing software archeology. I have lost hours of poking around with just the issues I mentioned.

It is like writing a book: You put much more effort into writing a book than to read it. Why? Because you are only one person and probably (hopefully) many people will read it. Therefore, time spent to make it easier on them one time is beneficial in the grand perspective.

So, if you want your software to be put to good use, take the time and make it easier for others to use it.

What do you propose?

@franklupo commented on GitHub (Oct 31, 2023): > About "having to explain all the parameters" (and in a clear way): documentation is IMHO a means to convey the features of a piece of software to spare others the act of doing software archeology. I have lost hours of poking around with just the issues I mentioned. > > It is like writing a book: You put much more effort into writing a book than to read it. Why? Because you are only one person and probably (hopefully) many people will read it. Therefore, time spent to make it easier on them one time is beneficial in the grand perspective. > > So, if you want your software to be put to good use, take the time and make it easier for others to use it. What do you propose?

kerem commented

2026-02-26 17:44:19 +03:00

Author

Owner

@franklupo commented on GitHub (Oct 31, 2023):

If no VM is found, it may be a user permissions error.

For the 3rd time: No, it is NOT a user permissions error. Only the error message is strongly misleading. The root cause is that I used --vmid="-105", which is inherently suggested by the help text, but does not function in itself. In order to exclude just one VM, you have to first say "all", THEN exclude a specific VM, like "all,-105". "-105" will never find any VM at all, resulting in that erroneous error message. If at all there should be a message pointing to the "possible" cause of no VM found, it should be that excluding a VM in itself can never find any VM, even if others do in fact exist.

You asked for an example, I gave it. Just try for yourself: Use --vmid="-105" (regardless if you have a VM with that number). If you expect to snapshot all the other VMs, you are mistaken and will get exactly these error messages about permissions.

the result is no vm, it could be due to the exclusion of all, or because you don't have permissions. I don't know which of the two brings no result. The fact is that specifying an exclude '-105' without specifying what to include is an operator error, and generates no result in the program.
I hope I have explained myself.

Best regards

@franklupo commented on GitHub (Oct 31, 2023): > > > > > > > > > If no VM is found, it may be a user permissions error. > > For the 3rd time: No, it is NOT a user permissions error. Only the error message is strongly misleading. The root cause is that I used --vmid="-105", which is inherently suggested by the help text, but does not function in itself. In order to exclude just one VM, you have to first say "all", THEN exclude a specific VM, like "all,-105". "-105" will never find any VM at all, resulting in that erroneous error message. If at all there should be a message pointing to the "possible" cause of no VM found, it should be that excluding a VM in itself can never find any VM, even if others do in fact exist. > > You asked for an example, I gave it. Just try for yourself: Use --vmid="-105" (regardless if you have a VM with that number). If you expect to snapshot all the other VMs, you are mistaken and will get exactly these error messages about permissions. the result is no vm, it could be due to the exclusion of all, or because you don't have permissions. I don't know which of the two brings no result. The fact is that specifying an exclude '-105' without specifying what to include is an operator error, and generates no result in the program. I hope I have explained myself. Best regards

kerem commented

2026-02-26 17:44:19 +03:00

Author

Owner

@meyergru commented on GitHub (Oct 31, 2023):

My proposal would be:

Clarify how excluding works. Now it reads: "-vmid or -name exclude (e.g. -200,-TestUbuntu)", so you exactly give a non-working example in the parentheses, thus forcing this "operator error" by using a bad example. Better would be to explain it like: "-vmid or -name exclude from list, e.g.: 'all,-200,-301' or "all,-TestUbuntu", but not '-200' alone"
If you have "potential" error messages, add "POSSIBLE PROBLEM VMID specification should be 'all,-vmid' instead of '-vmid'. You could even find that specific operator problem because a valid VMID specification must never start with '-'.
Include the missing parameters in the Readme.md, you do not have to explain them in detail, just mention their existence.

@meyergru commented on GitHub (Oct 31, 2023): My proposal would be: 1. Clarify how excluding works. Now it reads: "-vmid or -name exclude (e.g. -200,-TestUbuntu)", so you exactly give a non-working example in the parentheses, thus forcing this "operator error" by using a bad example. Better would be to explain it like: "-vmid or -name exclude from list, e.g.: 'all,-200,-301' or "all,-TestUbuntu", but not '-200' alone" 2. If you have "potential" error messages, add "POSSIBLE PROBLEM VMID specification should be 'all,-vmid' instead of '-vmid'. You could even find that specific operator problem because a valid VMID specification must never start with '-'. 3. Include the missing parameters in the Readme.md, you do not have to explain them in detail, just mention their existence.

kerem commented

2026-02-26 17:44:19 +03:00

Author

Owner

@denes44 commented on GitHub (Nov 8, 2023):

If you want to exclude something from a set of things, you need to specify the set of things first of which you want to exclude something. That is common sense.
So by explaining the syntax how you can exclude one thing (-200), does not mean you can use that syntax by it's own.
"-200" means you want to exclude 200 from nothing, which will be less than nothing, and it doesn't makes any sense.
"all-200" means you want to exclude 200 from all the things.

@denes44 commented on GitHub (Nov 8, 2023): If you want to exclude something from a set of things, you need to specify the set of things first of which you want to exclude something. That is common sense. So by explaining the syntax how you can exclude one thing (-200), does not mean you can use that syntax by it's own. "-200" means you want to exclude 200 from nothing, which will be less than nothing, and it doesn't makes any sense. "all-200" means you want to exclude 200 from all the things.

kerem commented

2026-02-26 17:44:19 +03:00

Author

Owner

@Neurrone commented on GitHub (Dec 28, 2024):

I just lost half an hour trying to figure out how to get the all parameter to work. Really agree with the suggestions above about defining how all works, I tried using @all as described but based on the comments above, it should just be --vmid=all

@Neurrone commented on GitHub (Dec 28, 2024): I just lost half an hour trying to figure out how to get the all parameter to work. Really agree with the suggestions above about defining how `all` works, I tried using `@all` as described but based on the comments above, it should just be `--vmid=all`

kerem commented

2026-02-26 17:44:19 +03:00

Author

Owner

@franklupo commented on GitHub (Dec 28, 2024):

All Is for compatibility. The correct value Is @all

@franklupo commented on GitHub (Dec 28, 2024): All Is for compatibility. The correct value Is @all

Rows
Columns

[GH-ISSUE #82] Documentation unclear about exclusions in vmid parameter and missing other parameters #76

What happened?

Expected behavior

Relevant log output

Proxmox VE Version

Version (bug)

Version (working)

On what operating system are you experiencing the issue?

Pull Request