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-2002 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.