Document config file format (location, contents and syntax)

[bernd-wechner]

Is your feature request related to a problem? Please describe. I would like to use Timeshift on a headless server. Primarily to have consistency between my Mint desktops and the servers. It supports CLI use well, and installs fine on a headless Ubuntu server. But the config file, and its use, is poorly documented, and I don't see a comforting --dry-run option for example that might encourage experimenting to learn. So I'd be constrained to source code analysis to try and work it out (and may resort to this, and offer to document it, and may not - as with most of the FOSS world, I am stretched very thinly - but words of encouragement and easy ways to contribute said doc will increase the likelihood).

Describe the solution you'd like Clear documentation on the config file contents and format, for configuring timeshift by hand in headless environments.

Describe alternatives you've considered Source code analysis.

Additional context There is a lack of clarity in the internal docs that bothers me mildly. Note for example:

$ timeshift --help

Timeshift v21.09.1 by Tony George (teejeetech@gmail.com)

Syntax:

  timeshift --check
  timeshift --create [OPTIONS]
  timeshift --restore [OPTIONS]
  timeshift --delete-[all] [OPTIONS]
  timeshift --list-{snapshots|devices} [OPTIONS]

Options:

List:
  --list[-snapshots]         List snapshots
  --list-devices             List devices

Backup:
  --check                    Create snapshot if scheduled
  --create                   Create snapshot (even if not scheduled)
  --comments <string>        Set snapshot description
  --tags {O,B,H,D,W,M}       Add tags to snapshot (default: O)

Restore:
  --restore                  Restore snapshot
  --clone                    Clone current system
  --snapshot <name>          Specify snapshot to restore
  --target[-device] <device> Specify target device
  --grub[-device] <device>   Specify device for installing GRUB2 bootloader
  --skip-grub                Skip GRUB2 reinstall

Delete:
  --delete                   Delete snapshot
  --delete-all               Delete all snapshots

Global:
  --snapshot-device <device> Specify backup device (default: config)
  --yes                      Answer YES to all confirmation prompts
  --btrfs                    Switch to BTRFS mode (default: config)
  --rsync                    Switch to RSYNC mode (default: config)
  --debug                    Show additional debug messages
  --verbose                  Show rsync output (default)
  --quiet                    Hide rsync output
  --scripted                 Run in non-interactive mode
  --help                     Show all options

Examples:

timeshift --list
timeshift --list --snapshot-device /dev/sda1
timeshift --create --comments "after update" --tags D
timeshift --restore 
timeshift --restore --snapshot '2014-10-12_16-29-08' --target /dev/sda1
timeshift --delete  --snapshot '2014-10-12_16-29-08'
timeshift --delete-all 

Notes:

  1) --create will always create a new snapshot
  2) --check will create a snapshot only if a scheduled snapshot is due
  3) Use --restore without other options to select options interactively
  4) UUID can be specified instead of device name
  5) Default values will be loaded from app config if options are not specified

when I read:

--snapshot-device <device> Specify backup device (default: config)

I would like to see more clarity of "backup device" as it is never unambiguously clear if that's the device being backed up or the device being backed up to.

--grub[-device] <device> Specify device for installing GRUB2 bootloader

When I read this, I would like to understand what it does in a little more detail. It sounds mildly concerning that timeshift is installing a bootloader, and so warrants a note under Notes.

The config file it creates by default looks like:

$ cat /etc/timeshift/timeshift.json 
{
  "backup_device_uuid" : "",
  "parent_device_uuid" : "",
  "do_first_run" : "false",
  "btrfs_mode" : "false",
  "include_btrfs_home_for_backup" : "false",
  "include_btrfs_home_for_restore" : "false",
  "stop_cron_emails" : "true",
  "btrfs_use_qgroup" : "true",
  "schedule_monthly" : "false",
  "schedule_weekly" : "false",
  "schedule_daily" : "false",
  "schedule_hourly" : "false",
  "schedule_boot" : "false",
  "count_monthly" : "2",
  "count_weekly" : "3",
  "count_daily" : "5",
  "count_hourly" : "6",
  "count_boot" : "5",
  "snapshot_size" : "0",
  "snapshot_count" : "0",
  "date_format" : "%Y-%m-%d %H:%M:%S",
  "exclude" : [],
  "exclude-apps" : []
}

which is interesting on a few fronts:

1. A conspicuous lack of the snapshot-device config
2. lack of clarity around what seemingly critical configs like backup_device_uuid and parent_device_uuid mean.
3. No default excludes, when I read here that it would be sensible to exclude /dev, /tmp, /mnt, and /media (and would agree) and so a default would serve to both be a sensible default and convey the list syntax cleanly by way of example.

Timeshift rocks, Mint rocks, FOSS rocks, and as ever, we can take it to another level of rocking, by documenting the configs here a bit better. As noted above, time and encouragement and facilitation permitting I don't mind helping, but for now, use my time no note down, this wish to take timeshift to the next level of awesomeness.

[stephan-dev]

Words of encouragement ? Bernd, you are one of my Mint Forums hero. I don't remember the specifics, but I have spent countless hours on some "legendary" Gnu Linux Debian Ubuntu Mint bug, and with the power of Google, I found a post of yours in the forums where you had the guts to say exactly what I wanted to say. Or more precisely, you pointed out an inconsistency which allowed me to conclude, ok I was not crazy. (everyone else would dance around the issue, making it cryptic, probably for fear of hurting a moderator). And you always make sure to praise what does work, and sometimes remind the readers that you have contributed a lot to the open source community in your life. So yes, if it's not already done, please improve Timeshift documentation!

I'm here today after finding that there are 2 different configuration files in my version, /etc/timeshift.json and /etc/default/timeshift.json (this is not documented either, afaik). Details snipped because unrelated to that issue here.

[bernd-wechner]

Thanks Stephan. Alas I've lacked time to delve into Timeshift's code base. I remember sidestepping to backintime as a possibility, but not how far I got. It's a big to-do as I have a Nextcloud server that continually bugs me when something breaks after upgrading either the Nextcloud or Collabora. A turnkey one-step undo like Timeshift offers would be so desirable and save time in those situations. I have this love from my OpenWRT routers that use btrfs and the schnapps utility which works just like this. Keeps cheap, fast snapshots of the whole disk and takes one before every update. So undos are trivial. It goes one better. If the update broke even the boot cycle, there's a firmware that will rollback one snapshot each time you trigger it by holding the reset button down until the right number of LEDs on the front light up. That's been a lifesaver so often.

The problem we have in the modern world I find is the imperative to maintain up-to-date software for security reasons (with any internet facing machines experience endless hack and infiltration efforts - just open port 22 to the world for a few days and then look at your failed login logs!) but not quite as many and easily used turn-key snapshotting tools for servers and systems generally.

Timeshift in the Mint space was a genuine boon in that space! Be nice if headless use were a little better documented, is all. Can't blame Mint for that mind you as their focus is understandably desktop systems and not servers. But even on desktops I'd argue that headless use, in scripts, is a wonderful thing to support. Though I admit the market, from a Mint perspective, is small (people with the tech-savvy to actually pursue CLI and script solutions to their needs is a small part of the Mint user base - it's done so exceedingly well in the Desktop space to win over a large user base of lay users)

[stephan-dev]

Hey Bernd, so nice to have you in the Mint community, sorry for late reply. Short off-topic to begin. I now remember one of the Mint forum threads where I (after a search) liked what you said a lot, it was about the correct command to restart cinnamon (including from text TTY). That was making me crazy. You pointed out that more documentation was needed (so I realized even experienced users / contributers had similar questions). I realized the problem was with losing the polkit agent and wrote this issue https://github.com/linuxmint/cinnamon/issues/10804 and started a forum thread. Only one person replied and confirmed the bug (flatpaks disappear from Mint menu / mysterious screen freezes, actually waiting for TTY input), but that was precious encouragement, and now a good search would return my issue (=> documentation... sorta) that I closed myself with a pro-tip / workaround.

Yes, for security reasons we have to update all the time, it's crazy. It's nice that Mint is pushing hard for Timeshift use, with the orange warnings on updates, but Timeshift is hard to understand for beginners (backup Vs snapshots, rsync rules...). Sometimes (in general, when I finally understand something that is not documented) I want to start a forum thread asking a question I already have the answer to, but I'd prefer if there was a more legit way to do this, like a Mint wiki (I know about "tutorials" in the "community" site, but it's still another thing). (for example (that I finally didn't share) for weeks I thought I could use my brand new external BTRFS partition to make faster Timeshift snapshots of my... internal ext4 install of Mint... what an idiot! I'm sure I'm not the only one, many hours were lost thinking my BTRFS partition was not set up correctly)

I don't have a server that I'd administer myself (future goal...) so I can't comment on snapshotting servers without GUI. If linuxmint issues were more crowded I'd be more careful to avoid off-topic, but as discussion is usually slow, I allowed myself to drop in, as you mentioned the importance of encouragement! No problem if you didn't have time for this issue in particular!