NAME

mythtv-balance-expire - move recording files to balance multiple disks

SYNOPSIS

mythtv-balance-expire [--help | --man | options]
   --help       show these options and exit
   --man        show the full manual page and exit
   --files      balance by file count rather than by file size
   --delta=N    expiring file delta allowed between disks [10]
   --titles     append titles to all files, not just moving files
   --subtitles  append subtitles to titles
   --delete     delete older recordings from Deleted group
   --verbose    show the commands that would be run, or are being run:
   --go actually do the moves, else just show what would be done

DESCRIPTION

mythtv-balance-expire trades recording files between multiple local disks in a mythtv server to better balance the files over recorded time. Why would you want to do this you ask?

Say you have 6 months of recordings but your disk is full so you add another. The new disk now gets most new recordings since it has more free space. 6 months later both are full and recording new shows. But the original disk is now expiring files from 1 year ago while the new disk is expiring files only 6 months old. Mythtv's auto-expire list implies your are losing 1 year old recordings but this is misleading since the new disk must expire shows much younger.

Or, say you have a small disk and a large one, both full and recording via auto-expire. And you disable auto-expire on shows you really want to see someday to make sure you don't lose them to auto-expire. If you save a significant amount of shows this way, you can eventually have the small drive nearly full of saved files. So the auto-expire to record a new show is from just a few days ago, even if the large disk is expiring shows over a year old!

So, what you really need is for all disks to hold a similar amount of oldest expiring files. This does that by moving recordings among the disks.

Usage and output

Run with no arguments. This will take no actions and just show the expiring recordings and recommended moves.

The output shows expiring recordings in time sorted order. Sums are indented per disk, so each sum "column" is a different disk. The lines look like:

SUM DELTA GB CHAN_YYYYMMDDHHMMSS.ts /path/to/recording GROUP

SUM: Amount of expiring data so far on this recording path, before placing the current file. Each path is indented to a unique column.
DELTA: Current delta of the path with the most expiring content compared to the path with the least. When this value exceeds --delta, a move is triggered.
GB: Size in gigabytes of this expiring file.
CHAN_YYYYMMDDHHMMSS.ts: Recording file name: channel, time stamp and file extension. The lines are sorted by the YYYYMMDDHHMMSS time stamp of the recording.
/path/to/recording: Current path to the recording file.
GROUP [title]: Recording group of the file and optionally its --title and --subtitle

Suggested moves are shown when a file should move to produce a better balance. These lines look like this:

< GB expirefile /too/many/path -> /too/few/path XXX free < title
> GB keeperfile /too/few/path -> /too/many/path YYY free > title

The expiring file is delimited by < and shown with its size in gigabytes. It should move from the left path with too many to the right path with too few as shown by the arrow. The resulting file count and free space of the destination location is shown. Finally the recording group, title (and optionally --subtitle) of the moving file is displayed.

If the destination is now more full than the source, a trade is made. A file with auto-expire disabled (a permanent "keeper" file) is preferred. This keeper file is delimited by >. It is selected by size that would result in closest headroom on the disks. If no keepers are left, then a future expiring file is used for trade instead. When balancing to a disk with more free space, no trade is needed.

A footer is provided which shows the end state of each disk. A notice is given if nothing has actually happened yet, see --go.

If the suggested moves look correct, you can add --verbose to see the commands that will be run. For the successful copies, the original location will be removed. If this still looks good, simply add --go to actually do the given file moves. When using --go you must be root or the owner of the recording directories (perhaps mythtv) so that you have permission to move the files.

OPTIONS

--file: Balance by expiring file count rather than file size.
--delta N: Require each disk's expiring size or file count over time to be within N of all other disks. If a disk has > N more than another, this triggers a file move to maintain this delta <= N. Lower values produce a better balance while higher values need less moves. You can manipulate this value to see how many moves will be required and how they will affect disk headroom, before deciding to use --go. A high value like 9999 will simply show the current [im]balance with no moves. When used with --file, the units are file counts, otherwise the units are gigabytes. The default delta is 10.
--titles: Show titles of all recording files. Without this option, titles are shown only for files that are moving.
--subtitles: Append subtitles to all titles.
--delete: Old recordings found in the Deleted recording group are displayed with a note that --delete may be used to delete them. This could be needed for example when these recordings are no longer offered in the frontend due to a deletepending flag in the database. See: https://forum.mythtv.org/viewtopic.php?f=36&t=2888&p=14057 Once used, the MythTV backend will do the file removes over some time. This option has no effect if no old Deleted files are found.
--verbose: Show the commands that will be run, or are being run with --go. If STDOUT is a terminal, then rsync(1) will use its --progress option to show copy progress, even without this --verbose.
--go: Actually do the file moves with rsync(1), removing the original only if successful. This requires write permission to the local recording directories so you must be root or mythtv on the server. If this option is not given, then no actions are taken.

CAVEATS

You must have ~/.mythtv/config.xml configured to read your database and must be root or mythtv on the server for write permission to move the files. As shown in --verbose, rsync(1) is required.

This only works with local files and may be confused by multiple backends or remote paths. Patches welcome if you have such a setup.

Of course moving dozens of files will take a long time, so be patient when using --go. The initial --go will need to move more files than later runs. Rsync(1) --progress is shown on the terminal.

This does not update the database at all. Mythtv will automatically discover the new locations of the recordings. Allow time for this to happen between --go runs.

If your disks are different sizes, it may not be possible to balance recent time. This is normal - you will balance that time later when you run this again in the future. In fact, it is a good idea to run this periodically; I do so once a month. Once you trust the actions, you may crontab(1) this job with --go.

AUTHOR

Timothy D Witham <twitham@sbcglobal.net>

COPYRIGHT AND LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.