Outdated documentation for template changes rollback, how to proceed?

User Support
1

Hi,

I would like to revert a bad change in my template, I wanted to follow the documentation here Template implementation | Qubes OS but /etc/xen/scripts/block-snapshot doesn’t exist.

I guess this documentation is outdated. Anyone would know how to rollback last template change? I will be happy to try it and update the documentation accordingly :slight_smile:

2

I think the solution is related to qvm-volume revert, but I can’t find how to use it :sweat:

[solene@dom0 ~]$ qvm-volume list --full gentoo-xfce
POOL:VOLUME                                 VMNAME       VOLUME_NAME  REVERT_POSSIBLE
linux-kernel:6.3.2-1.fc32                   gentoo-xfce  kernel       No
vm-pool:qubes_dom0/vm-gentoo-xfce-private   gentoo-xfce  private      No
vm-pool:qubes_dom0/vm-gentoo-xfce-root      gentoo-xfce  root         Yes
vm-pool:qubes_dom0/vm-gentoo-xfce-volatile  gentoo-xfce  volatile     No

But from here, I don’t understand the syntax for qvm-volume info or qvm-volume revert :frowning:

3

Ah, it was simple, but not very explicit from the output and documentation :exploding_head:

[solene@dom0 ~]$ qvm-volume info gentoo-xfce:root
pool               vm-pool
vid                qubes_dom0/vm-gentoo-xfce-root
rw                 True
source             
save_on_stop       True
snap_on_start      False
size               53687091200
usage              8960375521
revisions_to_keep  2
ephemeral          False
is_outdated        False
Available revisions (for revert):
  1686908017-back
  1686912475-back

[solene@dom0 ~]$ qvm-volume revert gentoo-xfce:root
4

The documentation does explain how to revert volumes.

5

ah thanks! I was focusing on the template documentation because the revert was mentionned there. So I suppose that whole section should be removed, or linked to the one you linked about “volume backup and revert” :+1:

6

I think not.
One is a user guide, flagged as intended for “advanced users”, the other
is part of the developer documentation, and marked as such.
They have different audiences, and different aims.

7

I’m not sure to understand, the procedure explaining in Template implementation | Qubes OS seems outdated. Why would you want to keep it?

8

Those aren’t supposed to be instructions that a user follows to achieve some goal. Rather, that’s supposed to be a description of how the system is actually implemented.

To oversimplify:

  • User docs tell users how to do stuff.
  • Dev docs describe how the system works.

The suggestion that we should just drop the latter and link to the former in this case conflates these two types of documentation, overlooking their distinct purposes and natures.

But if there’s actually some content that’s outdated (e.g., a certain path or file no longer exists, perhaps because it has been has been moved, renamed, or replaced), then of course that should be updated.

9

It is outdated, but I don’t know the right replacement to update it, and the repository GitHub - QubesOS/qubes-doc: Qubes documentation doesn’t allow reporting issues :frowning:

This path at the end of the sentence doesn’t exist anymore, which makes the procedure unusable: Prepare snapshot device with root-cow.img.old instead of root-cow.img (/etc/xen/scripts/block-snapshot prepare).

10

That’s because you’re supposed to report them to qubes-issues instead:

1 Like
11

thanks! I’ll do that

done: rollback template change documentation is outdated · Issue #8284 · QubesOS/qubes-issues · GitHub

1 Like