=======================================================================
Quantum Linear Tape File System (LTFS)
=======================================================================

Files in this download contain Licensed Materials, property of Quantum,
(C) Copyright 2010, 2015 Quantum Corporation.

Files in this download contain Licensed Materials, property of HP,
(C) Copyright 2010, 2014 Hewlett Packard Development Company, L.P.

Files in this download also contain Licensed Materials, property of IBM,
(C) Copyright IBM Corp. 2010, 2014  All Rights Reserved.  

The Quantum LTFS software application is an open-source tape file system
implemented on dual partition tape drives.

This file is part of the Quantum Linear Tape File System package.  Quantum LTFS is
free software; you can redistribute it and/or modify it under the terms
of the GNU Lesser General Public License as published by the Free Software
Foundation, version 2.1 of the License.

Quantum LTFS is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
or download the license from <http://www.gnu.org/licenses/>.

See the Licensing agreement (COPYING.LIB) when LTFS is downloaded.

Further details on Quantum's LTFS implementation can be found at
 http://www.quantum.com/ltfs/
=======================================================================
Supported Operating Systems
=======================================================================

LTFS is supported for the following operating systems:
 RHEL 5 Update 4 or later, 32-bit and 64-bit
 SLES 11 Service Pack 1 or later, 32-bit and 64-bit
 Mac OS 10.6 (Snow Leopard) or later

=======================================================================
LTFS usage
=======================================================================

1. Build and/or install the LTFS application

   For Linux:
    Information on how to install from binary RPMs is in 
    doc/INSTALLING.linux.
    Information on how to build from source is in doc/BUILDING.linux.

   For Mac OS X:
    Information on how to install from a binary package is in 
    doc/INSTALLING.macosx.
    Information on how to build from source is in doc/BUILDING.macosx.

2. Ensure that /usr/local/bin/ is in your command search path

   For example:
     $ export PATH="$PATH:/usr/local/bin"

3. Format the tape cartridge in LTFS format

   For Linux:
     $ mkltfs -d /dev/st0
   
   For Mac OS X:
     $ mkltfs -d 0
  
   mkltfs options:
      -d, --device=<name>       Tape device (required).
				For Linux, use the device name such as /dev/st0
				For Mac OS X, use the instance number of the tape drive,
				 assigned sequentially by the system starting from 0.
				The system profiler can be used to verify the device name. 
      -s, --tape-serial=<id>    Tape serial number (6 alphanumeric ASCII chars)
      -n, --volume-name=<name>  Tape volume name (empty by default)
      -r, --rules=<rules>       Rules for choosing files to write to the index
				 partition. The syntax of the rule argument is:
                                    size=1M
                                    size=1M/name=pattern
                                    size=1M/name=pattern1:pattern2:pattern3
                                A file is written to the index partition if it
                                 is no larger than the given size AND matches
                                 at least one of the name patterns (if specified).
                                The size argument accepts K, M and G suffixes.
                                Name patterns may contain the special characters
                                 '?' (match any single character) and 
                                 '*' (match zero or more characters).
      -o, --no-override         Disallow mount-time data placement policy changes
      -w, --wipe                Restore the LTFS medium to an un-partitioned medium.
                                 (format to a legacy scratch medium)
      -q, --quiet               Suppress progress information and general messages
      -f, --force               Force reformat of existing LTFS volume
                                 (normally disallowed)
      -t, --trace               Enable function call tracing
      -h, --help                This help
      -p, --advanced-help       Full help, including advanced options

4. Mount the formatted tape cartridge
     $ mkdir /mnt/ltfs
     $ ltfs /mnt/ltfs

   ltfs options:
      -o devname=<dev>          Tape device (required if not using the default
                                 device: /dev/st0 for Linux, 0 for Mac OS X)
      -o work_directory=<dir>   LTFS work directory (default: /tmp/ltfs/)
      -o trace                  Enable function call tracing.
      -o eject                  Eject the cartridge after unmount
      -o sync_type=<type>       Specify sync type (default: time@5)
                                <type> should be specified as follows
                                time@min: LTFS attempts to write an index
				  every min minutes.  min should be a decimal
			      	  number from 1 to MAX_INT (default: min=5)
                                close:    LTFS attempts to write an index 
                                  whenever a file is closed
                                unmount:  LTFS attempts to write an index 
                                  only when the medium is ummounted
      -o force_mount_no_eod     Skip EOD existence check when mounting (read-only mount)
                                Only use this option for a cartridge with corrupted CM
      -o rollback_mount=<gen>   Attempt to mount on previous index generation (read-only mount)
      -o release_device         Clear device reservation (should be specific with -o devname)
      -o symlink_type=<type>    Specific symbolic link type (default: posix) <type> should
                                be specified with one of the following values:
                                  posix: LTFS behavior is the same as stardard symbolic link
                                  live: LTFS replaces mount point path by current mount point
      -a                        Advanced help, including standard FUSE options
      -V, --version             Output version information and exit
      -h, --help                Display this help and exit  
   FUSE options:
      -o umask=M                Set file permissions (octal)
      -o uid=N                  Set file owner
      -o gid=N                  Set file group

5. Write files to the LTFS volume
    For example:
     $ cp -RL /home/user1  /mnt/ltfs/

6. Unmount the tape cartridge
    This flushes the data buffer of the file system to the tape cartridge,
    and prepares for eject.

     $ umount /mnt/ltfs
       OR
     $ fusermount -u /mnt/ltfs  (Linux only)

7.  If at some time in the future you wish to remove the LTFS format from
     the cartridge so that it can be reused for a different purpose, use
     the unltfs utility.  Note that this will IRRETRIEVABLY DESTROY all
     contents of the cartridge, so use it only when you are sure that you
     wish to erase the LTFS volume.

     $ unltfs -d /dev/st0

     unltfs options:
	-d, --device=<name> specifies the tape drive to use
	-y, --justdoit      omits normal verification steps, reformats without
                            further prompting
	-e  --eject         eject tape after operation completes successfully
	-q, --quiet         suppresses all progress output
	-t, --trace         displays detailed progress
	-h, --help          shows this help
	-i, --config=<file> overrides the default config file
	-b, --backend       specifies a different tape backend subsystem
	-x, --fulltrace     displays debug information (verbose)

Changes from version v2.1.3 to 2.2.0:
======================================
    - Added support for LTFS format specification 2.1.0
	- Added support for MAM Barcode attribute
	- Added support for ICU version 50.1.2
	- Added support for RHEL 7.0
	- Added support for MacOSX 10.10
	- Removed support for MacOSX 10.6
	- Added 'interactive mode' for mkltfs utility.
	- The default 'mkltfs' behavior modified to avoid user confirmation.
	- The '--quiet' option in 'mkltfs' and 'unltfs' utilities now does not imply '--force'
	- Implemented ability to list rollback points of a cartridge without EOD marker (--salvage-rollback-points)
	- Defects fixed in Mac GUI and Mac Installer
	- Defects fixed in LTFS core application
	
Changes from version v2.1.2 to 2.1.3:
======================================
	- Fix Mac OS X creation date always shown as Dec 31 16:00 1969
	
Changes from version v2.1.1 to 2.1.2:
======================================
	- Enabled support for non-Quantum drives.

Changes from version v2.1.0 to 2.1.1:
======================================
	- Error fixes in windows installer to support upgrade
	- Fix to accept the index rules correctly when supplied using the LTFSConfigurator
	- Fix in ltfsck when run with --deep-recovery option
	- Fix to mount full tapes as read-only
	- Fix to clear the EWSTATE flag when a full tape is rolled back with --erase-history option
	- Fixed memory leaks

Changes from version v2.0.0 to 2.1.0:
======================================

  - Enhanced LTFS driver for small file support(Improve file creation/listing time 
    when a directory has many small files)
  - Enhanced support for LTO CM attributes 
  - Added support LTFS format specifications 2.1.0
  - Added support for symbolic link for Linux and Mac
  - Added support for rollback mount/read-only mount
  - Added support to save the current index as a xml file on unmount or when 'ltfsck' is run.
  - Application can run in background now in Mac.
  - Rollback of index is now possible only by specifying the generation number of the index,
    rollback using timespec of the index is disabled.
  - Implemented signal handlers to handle kill/interrupt signals and unmount the volume even when 
    the mount is being done.
  - Tape can be unformatted by specifying -w option to mkltfs  


Changes from version v1.2.1 to v2.0.0:
======================================

  New Drive Support:
    - Added support for LTO-6 tape drives. 

  New Platform Support:
    - Added support for Mac OS X 10.7 Lion and Mac OS X 10.8 Mountain Lion,
      either in 32-bit or 64-bit kernel mode, with OSXFUSE 2.6.1 or later as the
      replacement for MacFUSE

  RAS enhancements:
    - Improved the handling of a cartridge that was not unmounted properly
    - Improved the handling of a full data cartridge
    - Improved the process for storing a file on the index partition when the
      data placement policy is specified
    - Fixed a problem in ltfsck when trying to list rollback points and a corrupt
      index is encountered

  Usability enhancements:
    - Added the unltfs utility, which reformats an LTFS cartridge as a
      single-partition cartridge (permanently deleting all files in the
      process)
    - Added support for the -f option with the mkltfs command to prevent the
      user from overwriting the LTFS-formatted cartridge by accident
    - Added four new virtual extended attributes (VEAs) for identifying the
      software version information from the command line
       - ltfs.softwareVendor, ltfs.softwareProduct, ltfs.softwareVersion,
         ltfs.softwareFormatSpec
    - Modified to update the change time of a file or directory when
      ltfs.modifyTime VEA is written
    - Improved message reporting for advisory conditions that previously were
      being reported as error conditions

  MAC OS X enhancements:
    - Changed to display the cartridge's volume name below its icon, as
      specified by the -n option of the mkltfs command
    - Added ability for LTFS to run in the background, the same as Linux
      version, if -f option is not specified

  Fixes:
    - Fixed the problem that ltfs.mediaStorageAlert VEA is cleared when other
      VEA is read
    - Added a check for a write-protected cartridge in mkltfs

Changes from version v1.2.0 to v1.2.1:
================================================
  - Support tapes written with IBM LTFS 1.0.0, which had a block size of 1 MB
  - Installer on Mac OS X now tries to create the drive trace directory, if it
    doesn't already exist.
  - Display volume information at mount time.

Changes from version v1.0.0 to v1.2.0:
================================================

  - Conforms with new LTFS Format Specification 2.0.0
    - Backward compatibility with Version 1.0 formated tapes, and built-in
      automatic migration mechanism to Version 2.0.0 format
    - Improved the parsing and handling of the index information
    - Supports standardized virtual extended attribute (VEA) names.
      VEA names used in previous release of LTFS become obsolete and
      no longer available.
    - See Important Note below
  - Enhanced the ability to recover the tapes in inconsistent state,
    which was caused by unexpected power outage.
  - Added a new function to flush the in-memory user data to the tape medium
    at pre-defined timing; either sync at file close or sync periodically.
    The default behaviour is now to sync the index every five minutes.
  - Changed the command line syntax of ltfs and mkltfs command for
    specifying the data placement rules
  - Check for incompatible media and report problems in a helpful way
  - Various minor corrections and updates


Important Note:
===============

Earlier versions of the Quantum LTFS application supported the original 1.0 LTFS
format specification; version v1.2.0 and later supports the updated 2.0.0 LTFS
format specification.  LTFS volumes created with application v1.2.0 will not
be readable in older versions of the LTFS application, as shown in the
following table:

                      Cartridge written by    Cartridge written by
LTFS application       v1.1.0 or earlier       v1.2.0 or later
--------------------  ----------------------  ----------------------
v1.1.0 or earlier      Read/Write ok           Cannot be mounted

v1.2.0 or later        Readable ok; will       Read/Write ok
                       automatically be 
                       converted to new
                       format if written


Quantum recommends that all instances of Quantum LTFS should be updated to v1.2.0 or
later to avoid these compatibility issues. 

If for some reason it is important to maintain cartridges readable by
previous versions of the Quantum LTFS application, care should be taken to avoid
writing to those cartridges with the new version of the application.  This
may be accomplished by mounting the volume as read-only, or by using the
cartridge write-protect tab to prevent cartridge updates.  However this
should be regarded as a temporary measure until all the application instances
can be updated to v1.2.0.


Limitations:
============
  1. The Quantum LTFS application utilizes a block size of 512 KiB.  If the
     Host Bus Adapter which is connected to the LTO tape drive does not
     support this block size, it will not be possible to create or mount an 
     LTFS volume.

  2. Tape activity may continue for several minutes after unmounting an LTFS
     volume.  Do not attempt to eject the tape cartridge, or power down the
     tape drive or the system it is attached to, until the tape drive Ready LED
     stops flashing.  Doing so may corrupt the most recent backup.  If this
     happens, the ltfsck program may be used to return the volume to a useable
     state, but this will cause all data from the most recent backup to be
     deleted.
  
  3. When the tape cartridge is almost full, further write operations will
     be prevented.  The free space on the tape (e.g. from the df command)
     will indicate that there is still some capacity available, but that
     is reserved for updating the index when the tape is unmounted.

  4. Future mounts of a cartridge that is almost full (has passed the
     point at which "early warning" is reported) will mount as Read Only,
     to prevent further modifications which may not fit on tape.  This 
     status is cleared when a cartridge is reformatted (using mkltfs) or
     when the volume is rolled back erasing history (using ltfsck).

  5. (Mac OS X)  The ltfs program will currently always run in the
     foreground (equivalent to passing -f option).  This is done 
     automatically and may be changed in future releases.
  
  6. (Mac OS X)  LTFS does not support moving a folder within LTFS.
     Any attempt to move a folder in such a manner will result in an 
     "operation not permitted" error, and the operation will be ignored.
     The user can still move a file within LTFS, and the user can also move
     a folder from LTFS to non-LTFS file system or vice versa.

  7. (Mac OS X)  Mac OS X's Spotlight will not display the files 
     on LTFS as a result of search.

  8. LTO tape drives are optimized for high speed data transfer.  For best
     results, when copying data to or from an LTFS volume, utilize a device
     which can sustain a transfer rate of at least 50 MB/s.

