README-2.0

MFS Tools version 2.0
by Steven Lang (Tiger on TiVo Community Forum www.tivocommunity.com)

This is the second major release of the MFS Tools.  MFS Tools is a set of
utilities for TiVo drive upgrades.  This includes MFS specific backup and
restore, as well as MFS volume expansion and shrinking.  However, there is
only one executable.  All the commands are embedded inside this executable.

To setup the command, either create link (Symbolic or hard) to the main
binary (mfstool) named after one of the tools.  (Currently backup, restore
or mfsadd.)  If the binary name is not a recognized utility, the first
argument is assumed to be the name of the utility, and the second argument
forward the parameters.



BACKUP AND RESTORE QUICKSTART

For the impatient, this should be enough to get you a usable backup, and be
able to restore it.  Start by taking the drive out of your TiVo and connecting
it to your computer as the secondary master.  Connect your DOS drive as the
primary master.  If the TiVo drive is a locked drive, follow the procedures
to unlock it as outlined in the hack FAQ.  Boot to DOS (Or whatever OS you
normally used)  Put the "mfstool" file on a floppy disk.  Reboot to Linux,
either through a normal Linux boot or a TiVo upgrade disk.  Mount the
floppy with the command:

mkdir /mnt
mkdir /mnt/floppy
mount /dev/fd0 /mnt/floppy

Next, mount your DOS drive, which is the first partition on the primary master,
with the command:

mkdir /mnt/dos
mount /dev/hda1 /mnt/dos

Now you are ready to backup.  To backup, issue the command:

/mnt/floppy/mfstool backup -o /mnt/dos/tivo.bak /dev/hdc

Go for a quick snack, and when you get back, you should be done, unless any
errors were reported.

To restore, follow the procedures above.  Instead of putting the TiVo drive
as secondary master, put the drive you are going to restore to as secondary
master.  Again mount with the above commands.  Then start the restore with:

/mnt/floppy/mfstool restore -i /mnt/dos/tivo.bak /dev/hdc

Now that is great, but lets say you have a brand new pair of 120 gig drives
you would like to shove into your TiVo so you can record a couple weeks worth
of Home Shopping Network.  However, after restoring you still only had
20 hours.  So instead, to restore you do the following with your 120 gig
drives connected to secondary master and slave:

/mnt/floppy/mfstool restore -x -i /mnt/dos/tivo.bak /dev/hdc /dev/hdd

Now read the rest of this document so you know what you are doing.



ALL UTILS

There are a few things common to all utilities.  When accessing MFS, the
drives used are /dev/hda and /dev/hdb if defaults are available.  This can
be overridden one of two ways.  Some utilities explicitly take an argument for
what the A and B drives are.  Others, this can be changed by setting the
environment variables MFS_HDA or MFS_HDB to point to the device (Or file) of
the drive.  This can also be done for individual partitions.  This is useful
if TiVo has modified dev entries.  For example, if TiVo thinks the partition
is /dev/hdb2 but it is really /dev/hda12, you could set MFS_HDB2=/dev/hda12
and it will read the proper drive.  Be warned, however, that MFS_HDA1 will
match for MFS_HDA10 as well, with a 0 appended on the end of the name.

To set this variable in bash (Or most TiVo boot disks)
export MFS_HDA=/dev/hdc
(Replace the A and c with appropriate letters, of course)

To set this variable in csh/tcsh
setenv MFS_HDA /dev/hdc
(Again replace the A and c with the appropriate letters)

Unlike past MFS utilities released by others, the MFS Tools package does not
require a special kernel or boot parameters.  In fact, it is quicker without
byte-swapping.  The MFS Tools themself recognize both swapped bytes and
the TiVo partition format.



BACKUP

The backup is completely non-destructive to the source drive/drives.  The
drives themselves are opened read-only, so no bug should be able to write to
them.  Of course, I could always be wrong, so use at your own risk. :)

The simplest method to do a backup, assuming you have a drive with enough
space free mounted on /mnt and your TiVo drive the secondary master, is to
issue the command:

mfstool backup -o /mnt/TiVo.bak /dev/hdc

This will create an uncompressed backup as /mnt/TiVo.bak.  Most people will
probably want something more like:

mfstool backup -6 -o /mnt/TiVo.bak /dev/hdc

This will create a compressed backup (Compression level 6) as /mnt/TiVo.bak.
The general use is:

mfstool backup [options] /dev/hdX [/dev/hdY]

Options are any of the below options, /dev/hdX is the device file for the
TiVo "A" drive, and /dev/hdY is the device file for the TiVo "B" drive.

The full list of available options for backup are:

-o file
	This tells backup where to write the backup.  For most uses, this
	will need about 200 megs of free space.  If - is specified, the
	backup will be written to stdout.

-1 .. -9
	Create a compressed backup.  Any number between 1 and 9 may be used.
	Lower numbers will be faster, while higher numbers will produce
	smaller backups.  Generally the difference is only a few megs.  So if
	you are impatient, -1 should be fine.  A nice trade-off is -6, and
	is recommended for everyone not impatient or pinching every bit.
-v
	Do not include /var in the backup.  Normally /var is included, since
	it makes other TiVo utilities that put stuff in /var easier to use.
	However, the TiVo is quite capable of re-creating it itself.  How
	nice of it.  This option will save anywhere from 1 to 128 megs in the
	size of the backup, depending on the contents of /var.

-s
	This will shrink the volume set in the backup to the smallest it
	can get, given the data being backed up.  This effectively divorces
	the backup, and can usually make the resulting image able to be
	restored on a drive as large as the A drive of the original.  (Or
	the A+B drive in the case of a dual drive 30hr)  This is useful for
	making backups of an upgraded system.  The resulting backup will
	most likely be effectively un-upgraded, but with everything else
	the same.  Any drives that have been added (This includes self
	upgrades and the second drive on UK TiVo and DirecTV with TiVo) will
	be removed, if no data on them is being backed up.
	* NOTE: USING THIS WITH SOME SOFTWARE VERSIONS (1.3 and earlier so far)
	  MAY RESULT IN ANY EXISTING SHOWS IN NOW SHOWING BEING UNABLE TO BE
	  PLAYED OR DELETED.  IF THIS HAPPENS, A FACTORY RESET, OR A SOFTWARE
	  UPGRADE IS REQUIRED TO CLEAR THESE SHOWS.

Expert options:
-f N
	When making the backup, include ALL streams (Videos) who's fsid
	is below N.  Most TiVos only require certain recordings for background
	animations.  Since these are so large, they are not included in
	software updates.  As a result, they all have very low fsids.  On
	TiVos that I have seen, this is below 2000.  In fact, 2000 is the
	default for this option.

-l N
	Another way to find which streams need to be backed up is by size.
	This will cause any stream less than N megs in size to be backed up.
	A value of 32 or 64 should be big enough.  This overrides the -f
	option.

-t
	When using the -l option, normally the streams are considered based on
	how many USED bytes they have.  This will cause the compare to be done
	against the TOTAL size taken up on the disk, which can be potentially
	larger.  This is usually more useful, since as of 2.0, recordings can
	take up multiple files.  So the end might only be a few megs, but have
	more allocated.  It would, therefore, be backed up with -l, and could
	prevent -s from working.  Usage with -i is undefined.

-T
	Like -t, but in addition to using the total size for comparison, the
	total size is also used to back up the stream.  Normally only the
	used size is backed up.  This will result in a larger backup.  This
	implies -t, with the exception that it can be used with -i as
	expected.

-a
	Backup ALL streams.  This is useful if you have a few recordings you
	want saved with your backup for whatever reason.



RESTORE

The restore works much the same way as the backup.  Except instead of reading
the drive and writing to a file, it reads a file and writes to a device.  BE
SURE YOU GIVE THE RIGHT DEVICE!

Even if your backup was not a single drive, you will not necessarily need
two drives to restore to.  The restore function of mfstool will automatically
shuffle the partitions around for the best fit.  This often means all
partitions on the first drive.  The first 11 partitions on the A drive can
not be moved, however.  The data is also updated to reflect the new location,
so TiVo will be able to find the drive now and in all foreseeable future
software versions without any extra help.

The simplest method of restore, assuming your backup is named TiVo.bak in
a filesystem mounted at /mnt, and the new drive is the secondary master, is:

mfstool restore /dev/hdc -i /mnt/TiVo.bak

This will restore the file /mnt/TiVo.bak onto the secondary Master.

Other options available:

-q
	Quiet operation mode.  The progress display will not be displayed.
	Given twice will cause only error messages to be displayed.

-i file
	Read backup from file.  If - is specified, backup will be read from
	stdin.

-x
	Extend the MFS volume to fill all the drives given for restore.  This
	will create extra partitions on the drive to fill the remaining space
	and add them to the usable space for the TiVo, even if the drive was
	not needed for the restore.  Note, however, that doing this could
	cause a backup to fail because it will leave room for the extra
	partitions, possibly making the backup not fit.

-r scale
	This option allows you to reduce the amount of RAM TiVo uses by
	increasing the block size for the media storage created with the -x
	option.  The acceptable values are 0 to 4, corresponding to 1, 2, 4,
	8 and 16 megabytes.  The larger the value, the less RAM will be used
	(and the faster menus will respond) but a (small) amount of storage
	will be wasted by some recordings.  At the extreme small end (-r 0)
	some PVRs with a large amount of storage may not be able to perform
	some tasks, such as self repair. (A.K.A. Green Screen)  The default
	is 2 (or 4 megabytes).  Any TiVo created partitions are created with
	a scale of 0 (or 1 megabyte).  It is best to leave this option alone.

-l
	Do not fill up the partition table.  This will cause restore to
	arrange the partitions such that there is enough room on either
	drive to add another pair.  This does not, however, garuntee
	that there will be any free space left on the A drive, nor does
	it garuntee that the MFS set will have room to add partitions.
	The -l option is implicit with the -x option.  Additionally, this
	changes the behavior of the partition layout to try to go for either
	a half full A drive or a completely full A drive, instead of just
	trying to completely fill the A drive.

-p
	Attempt to optimize the partition layout for TiVo's access patterns.
	This will imitate the partition layout of DirecTV TiVo receivers
	and newer standalone receivers.  The partition layout of the first
	drive will be such that the application data will be in the middle
	of the drive and the video on the outside, causing the head to have
	to seek less.

-v size
	Create the /var partition this size, in megabytes.  This is useful
	if you have a big drive, and want to create a little sand-box space
	in your /var to play around with.  Default 128.

-s size
	Create the swap partition this size, in megabytes.  This is useful
	if you are running a lot of programs on the TiVo, or have VERY large
	drives, and want to put in a little extra swap.  (fsfix REQUIRES this
	for drives totaling over 120 megs)  Default 64.  Values up to 511 are
	possible.

-b
	Disables auto-detection of byte swapping, and forces the restore to
	occur without byte-swapping.  This is required for the new AT&T and
	series 2 TiVo when restoring a backup made with an older version of
	MFS Tools.

-B
	Disables auto-detection of byte swapping, and forces the restore to
	occur with byte-swapping.

-z
	Zero out partitions not backed up.  This means the inactive bootstrap,
	kernel and root partitions, as well as the /var partition if it is
	not in use.  Swap is automatically re-created, and not zeroed out.
	This is a little slower (About half a minute) but safer.  It may
	become the default at some point.

Backup and restore do not need random access files.  Therefore, it is possible
to use this utility to copy a drive from one drive to another.  This would be
done by issuing a command similar to the following, assuming that the source
is the primary master, and the new drive is the secondary master:

mfstool backup -o - /dev/hda | mfstool restore -i - /dev/hdc

More useful would be the following, which copies all the files:

mfstool backup -Tao - /dev/hda | mfstool restore -i - /dev/hdc

This will copy /var as well as all streams, to the new drive.  Note that
compression is not needed for this, and will likely just slow it down, being
CPU bound.



MFSADD

The mfsadd utility is a standalone utility for expanding the MFS volume set.
Unlike other methods involving blessing the drive, there is not a limit
on the number of times this can be run.  However, there is a limit on
the number of partitions that MFS can utilize.  (12, or 6 pairs)  The mfsadd
utility can be used both to add existing partitions to the volume set, or
similar to the -x functionality of restore, creating partitions to fill a
drive.

The simplest and most useful method of running mfsadd, assuming the TiVo
A drive is the secondary master and there is no B drive, is:

mfstool mfsadd /dev/hdc -x

Or if there is a new B drive connected to the secondary slave as well:

mfstool mfsadd /dev/hdc /dev/hdd -x

The first command will fill the extra space on the A drive, creating new
partitions as needed.  It will be able to do this even if the partition
table does not reflect the true size of the drive, as would be the case
after a drive to drive copy with "dd".  The second command will do the same,
and will also create partitions on the B drive.  If the B drive is also a
copy of an existing TiVo drive, it will add new partitions.  If the drive
is not currently used by MFS, it will be initialized first.
WARNING: IF A "B" DRIVE IS BEING ADDED WITH MFSADD -x OPTION, ALL EXISTING
PARTITIONS WILL BE WIPED.  If you have data you want to save, create new
partitions by hand with pdisk.  Both partitions should be type MFS.  The
first should be about 1 meg, the second should be as big as you want it,
usually the rest of the drive.  You would then add the new partitions,
assuming they are partitions 4 and 5, as:

mfstool mfsadd /dev/hdc /dev/hdd4 /dev/hdd5

Options for mfsadd:

-x
	Extend the MFS volume to fill all the known drives.  This will
	create extra partitions on the drive to fill the remaining space
	and add them to the usable space for the TiVo.  If the B drive does
	not currently contain active MFS volumes (IE a new drive, DOS drive
	or another TiVo's A or B drive) the partition table will be created
	and all existing partitions and data will be lost.

-X drive
	Extend the MFS volume to fill the given drive.  This is like -x,
	except it only fills one drive, not all known drives.  Doing
	-X /dev/hda -X /dev/hdb (Assuming A and B drive are hda and hdb)
	is the same as -x.

-r scale
	This option allows you to reduce the amount of RAM TiVo uses by
	increasing the block size for the media storage.  The acceptable
	values are 0 to 4, corresponding to 1, 2, 4, 8 and 16 megabytes.
	The larger the value, the less RAM will be used (and the faster
	menus will respond) but a (small) amount of storage will be wasted
	by some recordings.  At the extreme small end (-r 0) some PVRs with
	a large amount of storage may not be able to perform some tasks,
	such as self repair. (A.K.A. Green Screen)  The default is 2 (or 4
	megabytes).  Any TiVo created partitions are created with a scale
	of 0 (or 1 megabyte).  It is best to leave this option alone.

NewApp NewMedia
	By giving a pair of partitions on the command line, the partitions
	are added to the MFS volume set directly.  The partitions must both
	exist and must be of type "MFS".



MFSINFO

The mfsinfo utility can be used to give a brief report of the status of the
MFS volume set.  This is most useful to find out how many times you can
upgrade your drive with the MFS Tools mfsadd tool, as well as finding out
how big your MFS volume set is.



FAQ

Q. Will this work with the series 2 or AT&T TiVo?

Absolutely.  Any backup made with MFS Tools 2.0 will be restored properly by
MFS Tools 2.0 such that no extra flags are required.  However, you may need
to specify -b on the restore command line when restoring a backup made with
MFS Tools 1.0.

Q. Will I still need ZapTiVo/ZapStream/dd/gzip with this?

No, MFS Tools replaces the functionality of all other Linux based backup
utilities.

Q. Will I need TiVoMad or BlessTiVo to get the most out of my drives?

You can certainly use them, but MFS Tools 2.0 is able to add space
to the TiVo directly instead of making TiVo do it.

Q. Does mfsadd work with UK TiVo, DirecTV TiVo, Series 2 TiVo, or 13
partition standalone TiVo?

Yes, yes, yes and yes.  The TiVo media storage is pretty much identical
for all existing configurations.  Since MFS Tools mfsadd does not rely on any
particular OS version, hardware or drive layout to work, it can work with
any existing TiVo, any drive configuration.

Q. I have already upgraded with a B drive or a larger A drive.  Now I want
to upgrade my other drive.  Do I have to start over?

Not any more.  You just have to copy your drive to the new larger drive
and use mfsadd -x on the drive.  To copy the drive you can use either a
backup/restore with the -a backup option, or a dd drive to drive copy.

Q. So is there any limit on how many times I can add a larger drive?

Yes and no.  There is not any arbitrary limit saying that you can only
upgrade once.  However, TiVo only supports 12 partitions in MFS, which
means realistically you can only upgrade 5 times at the most, with each
drive being expanded counting as an upgrade.  DirecTV TiVos and other 13
partition systems can only be upgraded 4 times.  Old DirecTV TiVos that had
2 drives can only be upgraded 3 times.  If you are unsure, MFS Tools will
tell you if you have reached the limit, or MFS Info will tell you how many
more times you can upgrade.

Q. What happens if I reach the limit of 12 partitions and mfsinfo says I can
not upgrade any more?

You will have to backup with -s and restore it to your new drive to upgrade
again.

Q. Does this require a serial or network connection to my TiVo?

All that is required is the same thing required in the past for backup or
drive upgrade.  A PC that you can hook up your TiVo drive to and boot into
Linux.

Q. What is the difference between the static and dynamic packages?

If you have to ask, chances are you want the static package.  The dynamic
package is most useful to those with full Linux installs, or those making
utility disks.  More technically, the static package is entirely self
contained.  The dynamic package depends on ld-linux.so, libc, and zlib.
People creating utility disks will probably also want to create symbolic
links named backup, restore and mls that point to mfstool, so the commands
can be run directly.

Q. Can I backup a dual drive and restore to a single drive?

Yes.  If the drive is large enough.  The MFS Tools restore automatically
tries to fill up the A drive before putting anything on the B drive.
However, failing fitting everything on the A drive, it will then try to
fit as much as it can on the A drive.

Q. Will this work with a dual drive TiVo, such as the 312, original UK TiVo,
60 hour standalone, or original DirecTV with TiVo receivers?

Absolutely.

Q. I have a drive with errors on it.  Both dd and Dolly fail to produce a good
backup image.

That was not a question.

Since MFS Tools does not read the entire drive, only the required data, the
chance that the bad block on the data surface is in the needed data is much
lower, so you may yet be able to produce a good backup.

Q. Can I restore my backups made with MFS Tools using dd or Dolly?

No.  MFS Tools uses a special format that condenses the information needed
for the backup, so no unnecessary data, even easily compressible, is backed
up.  This results in small and FAST backups.

Q. Can I restore my backups made with dd, Dolly or ghost with MFS Tools?

No.  You can use dd, Dolly or ghost to restore those.  However, if you have
a raw drive image as a file (And you have large file support) MFS Tools can
turn your existing drive image into an MFS Tools backup.  Just give MFS
Tools the filename instead of a device.

Q. When I use -s, can I restore to a smaller drive than my TiVo came with?

No.  The smallest drive you can restore to is (in most cases) the size of
your TiVo's original A drive, or (in the case of dual drive 30hr or 60hr
standalone) the size of both drives combined.  The -s option does not
actually change any sizes, it just removes partitions when it can.

Q. When I use -s, the size reported for the backup is the same as the base
size reported.

The -s option is only useful when you have space added, reported on a separate
line from the base size.  Furthermore, it only cuts it down to as small as it
can get without losing any data being backed up.  So if you use -s and -a
together, chances are -s will not be able to do much, unless you have just
added extra space and not recorded anything yet.

Q. Can I use -s and save my recordings?

Probably not.  See the above question.

Q. Can I use -s and save my season passes, thumbs, setup, etc?

Anything not a recording is always saved.  Always.

Q. The size claims I have over 40 hours, but I only have a 35 hour combo.

The size reports are calibrated to standalone.  Sorry, I do not have the
exact conversion ratio to get the size of a combo at this time.

Q. Can I use MFS Tools with Linux DMA transfer mode or byte swapping?

Absolutely.  DMA transfer mode is recommended as it makes access a lot faster.
Byte swapping is supported and MFS Tools will be able to adapt and operate
properly.  However, due to a bug in Linux, you can not use both.  When DMA
transfer mode is active, the kernel will not do byte swapping, but will
claim it still does.  MFS Tools will ask the kernel and believe the answer
it gets.  As a result, any backup, restore, or add will result in a not
working TiVo.

Q. How confident can I be in the backup made?

As confident as you want.  Feel free to test the backup before doing anything
to your source drive.  In fact, I encourage you to test your backup.  There
are a few instances I am still a little uncertain about.  Besides, it only
takes a few minutes to test.

Q. Is there a Windows version?

Not Yet.(TM)  A port should not be too hard, so I may work on one at some
point.  I will need help, not being too familiar with Windows API.
Specifically for accessing a hard disk as a raw device.  If you think you
can help, I would love to hear from you.

Q. I made a backup of my drive, then restored it to the same drive.  Now
I see extra free space that wasn't there before.  What is going on?

MFS Tools creates the partition sizes based on how much space TiVo says the
partition uses, not how much space the partition table says the partition
uses.  To simplify access, TiVo rounds off all partitions to even values of
a power of two.  Any space beyond that is wasted.  That is where the free
space came from.  The wasted space was merely collected.

Q. Okay, so what is this mls thing and how do I use it?

It is just a simply clone of the mls in tivosh.  It doesn't have any options
besides a directory.  However, if the directory is given without a trailing
slash, it will just list that entry instead of the directory contents.
If your TiVo A and B drive are not primary master and slave, you will need
to use MFS_HDA and MFS_HDB.

Q. What versions of the	TiVo software does MFS tools work with?

So far, it has worked 100% with versions up to 3.0.  It SHOULD continue to
work in the future.  However, I can not speak for that which has not been
created yet.

Q. Will data restored from these backups work for all future TiVo software
versions when the software is upgraded through the normal process?

No guarantees.  It works for all past versions I have tested, and I see no
reason it will not work with future versions.  However, the drive image does
not exactly match what TiVo will produce.  It should be a close enough
approximation for any foreseeable changes.  But I'm not (very) psychic, so
I won't predict the future.

Q. Does this help TiVo, Inc. at all?

Not directly.  However it is my hope that it will result in less MORON(TM)
behavior in the user community by making backups more convenient for all users.
It is also my hope that it will reduce load on the servers of TiVo, Inc. by
allowing people to create a new backup with each software version they receive,
instead of forcing them to restore their backup, upgrade, then re-create the
backup or re-upgrade, or forcing them to download the software again every
time they restore from a backup.

It is also my hope this will make the TiVo experience better for those who
own their own TiVo already, and turn them into better TiVangelists, producing
more sales for TiVo, Inc.

Q. Does this hurt TiVo, Inc. at all?

No worse than other programs already released in source form.

Q. Is this software sanctioned by TiVo, Inc.?

No.  Wow, I feel negative after those last few questions.  TiVo, Inc. can not
condone any activity involving opening up hardware produced by TiVo, Inc. or
their partners.  The hardware is not designed to be consumer upgradable,
and has dangerous exposed electronics.  Furthermore, opening of the TiVo
Customer Device by anyone other than a qualified service agent will void the
warranty and any rights you as a consumer have to any repair services.  In
other words, if you open your TiVo, and do something to break it, you are
stuck with both pieces.

Q. Will you be releasing the source to MFS Tools?

No.

Q. Please?

No.

Q. pretty pleez o plzz?!!!  i will be ur best friend!!! !!!!

Don't make me turn this car around.

Q. You are a disgrace to the open source movement!

Sorry, ESR, I love open source and free software and all that. I think both
concepts have good ideas behind them. But I also respect TiVo's wish to keep
some things out of the public eye, as they have made clear to me in past
exchanges. (Besides, what source is out there is already quite a bit)  So no
source.

Q. Why does this FAQ seem kind of contrived?

Because it is.  I haven't had a chance to see what sort of questions really
need answering.  Got any suggestions?



ACKNOWLEDGEMENTS

Most of this was written on my own, with some help from the other TiVo
underground, especially with encouragement in the beginning.  However,
compression was supplied through the use of the zlib compression library by
Jean-loup Gailly and Mark Adler, and is Copyrighted (C) 1995-1998 by
Jean-loup Gailly and Mark Adler.  For further documentation on zlib, see
/usr/share/doc/zlib* on most Linux distributions, or the official home-page at
http://www.cdrom.com/pub/infozip/zlib/.



LEGAL

MFS Tools are Copyrighted (C) 2000-2005 by Steven Lang, all rights reserved.

TiVo is a registered trademark of TiVo, Inc.

DirecTV is a registered trademark of DirecTV, Inc., a unit of Hughes Electronics Corp.

Some data included in backups is Copyright (C) TiVo, Inc., their partners, or
other broadcast stations.  Backups are for personal use only.  Please read
the software licensing agreement included in your TiVo manual to understand
the limits of your rights to use the TiVo copyrighted software and data.

MORON, MORON I, MORON II, MORON III and "Don't be a moron" are not registered
trademarks of Richard Bullwinkle.

All other trademarks, service marks, and logos are the property of their
respective owners.