User's Guide

Quick Start

LFS is a standard Linux file-system. It is mounted as any other file-system and standard utilities like mkfs for managing it are provided. The following table presents a list of all support programs and their counterparts for the ext2 file-system for the convenience.

program	ext2	description
mkfs.lfs	mke2fs	Creates an empty file-system on a disk partition and fills it with an empty root directory.
lfs-gc	--	Garbage-collector that frees unused space. It is started automatically in the mount time.

Step-by-step

• First of all you need to create a partition on a disk. You can use the fdisk program. The partition should be at least 100MB large because smaller file-systems are not supported^3.1.

• After partitioning you have to create an empty file-system. For this purpose you have to use the mkfs.lfs program. In this example we use the default settings. Once a new partition has been created on /dev/hdb1 mkfs.lfs output looks like the following:

  # mkfs.lfs /dev/hdb1
  mkfs.lfs: version = 1.0
  mkfs.lfs: device         = /dev/hdb1
  mkfs.lfs: volume name    = LFS
  mkfs.lfs: device size    = 987966 kB (0.94 GB)
  mkfs.lfs: block size     = 4 kB
  mkfs.lfs: segment size   = 1024 kB = 256 blocks
  mkfs.lfs: reserved space = 1024 kB = 256 blocks (1 segments)
  writing data..... 
  
  ................................
  ifile has 15472 bytes
  addresses per indirect block : 512
  writing 0. super block at 0x0000000001000000 (checksum is 
  0xb29a8d3b) ... OK
  writing 1. super block at 0x000000000fc00000 (checksum is 
  0xb29a8d3b) ... OK
  writing 2. super block at 0x000000001e800000 (checksum is 
  0xb29a8d3b) ... OK
  writing 3. super block at 0x000000002d400000 (checksum is 
  0xb29a8d3b) ... OK
  syncing ...
  LFS successfully created on /dev/hdb1
  

• Finally, the file-system needs to be mounted (using mount) to some directory in your file-system. If you want to attach LFS to /mnt/lfs directory, the following command does the job :

  # mount -t lfs /dev/hdb1 /mnt/lfs
  

After successfully completing all steps, LFS can be used.

Snapshot

Snapshot is a special ability of LFS that has no counterpart in ext2-like file-systems. Sometime you want to make copy of frequently updated data or simply just to read them. The problem is that some data are changing to often and your copy would not be consistent. This problem is often encountered when one makes a backup copy. Solution is to stop all writing, so data are not change, while the copy is being made. Of course this solution has its disadvantages.

Solution provided by LFS is simple. Just mount file-system once more in a special snapshot-mode. Snapshot contains state of the whole file-system in the time of mount. It will never change even if the underlying LFS file-system does.

To take a snapshot you have to know an id of the mounted system. Because one file-system can be mounted to multiple places with different options we do not use a path (mount-point) as the identifier. Rather each LFS file-system has its own special id that can be used to reference it.

If you do not provide an id when mounting the file-system, an unused id is generated. You can check the /sys/filesystems/lfs/ directory for all LFS file-systems in use. Each mounted LFS has its own subdirectory, which name is equal to its id Files in this directory export various runtime data - mainly for debugging purposes. Generated ids have the format lfs%d. Identifier lfs0 is assigned to the first mounted LFS file-system.

Once you know the id of a file-system you can mount a snapshot, e.g. to /mnt/snap, using command:

#mount -t lfs-snap lfs0 /mnt/snap

To close snapshot just umount the snapshot file-system by:

#umount /mnt/snap

Kernel & Patches

LFS is developed for a patched 2.6.17.8 kernel. Patch is included in the distribution archive. Patch contains:

• Export of symbols of few kernel functions.
• Patch by David Howells dhowels@redhat.com which allows file-systems to register callback for handling page-faults. LFS can track when mmaped data are dirtied^3.2

Managing LFS

All programs described in this section have their manual pages that are included in lfs distribution archive. You can read them in the Appendix A.

Creating a file-system

Prior to mounting a file-system, it must be created on a device using the mkfs.lfs utility. Program first checks the size of the supplied device, it checks whether the device is large enough (the lower limit is 100MB) and prints out the file-system parameters (device size, segment size, block size, etc.)

mkfs.lfs cleans all segment summaries before any other data are written to the disk. This can take a while, depending on the device size. Program signals that the process wasn't finished yet by printing dots.

In the next stage, .ifile and the super blocks are written. After this, all the data must be written back from caches to the device. Since cleaning segment summaries means writing a lot of bytes for a large disks, flushing cashes takes some time as well.

Finally, message LFS successfully created on <device> signals that the file-system was successfully created and is ready to be used.

Mounting a file-system

File-system is mounted using standard UNIX mount utility. If the LFS module is not loaded you must add a type parameter -t lfs and module will be loaded automatically^3.3. If module is already loaded you need not specify its type. In that case kernel detects the type itself. LFS supports standard mount options (e.g., ro, rw, noatime ...) together with LFS specific ones:

• id=<lfs-id> sets id of mounted file-system. This can later be used for its identification. Without this option identifier is generated automatically (lfs0, lfs1 ...).
• gc=<lfs-gc> specifies program which will be run as a garbage collector.

If you do not specify noatime option it will be added. LFS cannot be mounted without this option.

Mounting a snapshot

Snapshot is mounted as a special read-only file-system. Its type is lfs-snap. Original file-system is synced during mounting the snapshot. Snapshot represents the LFS state after that sync. Snapshot file-system doesn't support any additional options.

The device used to mount a snapshot is always an id of the original file-system.

Once a snapshot is mounted all included data is still remaining on the disk. This means that if you delete a file from the live system, the space it was using is not freed until the snapshot is umounted. When you edit the file created before a snapshot was taken, a new version of this file will be stored on the disk along with the old one, consuming additional space. Notice that if a snapshot is mounted and the live file-system is being concurrently modified, all new data takes extra space even if old data is overwritten. On the other hand appending extra data to a file will not double the whole size of the file. Snapshot acts in the copy-on-write fashion.

After umount all obsolete (deleted or modified) data is freed and free space on disk increases.

Debugging a file-system

If you want to see on-disk data structures you can use dump.fs program. It shows super-blocks, inodes, segments, etc. To fully understand its output you read Chapter 4 On-disk Structures. dump.lfs has many options described in its manual page (see Appendix A). Following example shows how a super-block can be displayed :

$ dump.lfs /dev/hdb1 sb
fs.sb.@address                      = 0x01000000
fs.sb.s_segment_count               = 101
fs.sb.s_log_blocks_per_seg          = 8 (256)
fs.sb.s_reserved_segment            = 1
fs.sb.s_free_blocks_count           = 25600
fs.sb.s_free_seg_count              = 93
fs.sb.s_first_free_inode            = 3
fs.sb.s_used_inodes                 = 3
fs.sb.s_log_block_size              = 12 (4 KiB (4096 bytes))
fs.sb.s_ifile_addr                  = 0x00406000
fs.sb.s_next_block                  = 0x408
fs.sb.s_segment_counter             = 5
fs.sb.s_mtime                       = Sun Aug 20 18:26:56 2006
fs.sb.s_wtime                       = Sun Aug 20 18:29:50 2006
fs.sb.s_mnt_count                   = 0
fs.sb.s_max_mnt_count               = 0
fs.sb.s_magic                       = 0x1234
fs.sb.s_state                       = 0x00000000
fs.sb.s_errors                      = 0x00000000
fs.sb.s_minor_rev_level             = 0
fs.sb.s_lastcheck                   = Sun Aug 20 18:26:56 2006
fs.sb.s_checkinterval               = 0
fs.sb.s_rev_level                   = 0
fs.sb.s_feature_compat              = 0x00000000
fs.sb.s_feature_incompat            = 0x00000000
fs.sb.s_feature_ro_compat           = 0x00000000
fs.sb.s_volume_name                 = "LFS"
fs.sb.s_checksum                    = 0x02d4e8f7

Obtaining runtime information

Mounted LFS file system provide a a lot of of information about its internal state, which can be read through sysfs. There is a subdirectory for each mounted instance in /sys/filesystems/lfs. A comprehensive overview of all the files is shown in table 3.1. Please note that values prefixed with stat_ are not present if the LFS module is compiled without statistical data.

Table 3.1: Information exported via sysfs

File	Description
seg_count	file-system size in segments
seg_size	segment size in blocks
block_size	block size in bytes
seg_counter	actual segment counter value
free_space_max	maximal free space
free_space	actual free space
free_space_delay	amount of bytes, which will be added to free space after umounting the snapshot
free_segs	actual number of free segments
free_segs_max	maximal number of free segments
inodes_alloc	allocated inodes in the ifile
inodes_used	used inodes
stat_comm_segs	number of successfully written segments since the last mount
stat_comm_syncs	number of successfully written sync points since the last mount
stat_wq_len	length of the garbage collector work queue
stat_wq_req	number of request messages in the gc queue
stat_wq_inf	number of info messages in the gc queue
stat_gq_len	length of the garbage queue
stat_gq_mapping	number of mappings in the garbage queue
stat_gq_inode	number of inodes in the garbage queue
stat_gc_send	number of info messages send to gc
stat_gc_recv	number of gc requests received

Limitations

• O_DIRECT -- opening a file in the direct write mode is disabled. Direct operations does not comply with the LFS nature.
• noatime -- this flag is forced when mounting LFS because changing access time would result in frequent writes and a great performance loss.
• x86 -- file-system was developed and tested only on Intel 32bit platform. Even though LFS was designed as architecture independent, it was never tested elsewher so its functionality cannot be assured.