usr.sbin/makefs/README

   1 $NetBSD: README,v 1.3 2004/12/20 20:51:42 jmc Exp $
   2
   3 makefs - build a file system image from a directory tree
   4
   5 NOTES:
   6
   7     *   This tool uses modified local copies of source found in other
   8         parts of the tree.  This is intentional.
   9
  10     *   makefs is a work in progress, and subject to change.
  11
  12
  13 user overview:
  14 --------------
  15
  16 makefs creates a file system image from a given directory tree.
  17 the following file system types can be built:
  18         ffs     BSD fast file system
  19         cd9660  ISO 9660 file system
  20
  21 Support for the following file systems maybe be added in the future
  22         ext2fs  Linux EXT2 file system
  23         fat     MS-DOS `FAT' file system (FAT12, FAT16, FAT32)
  24
  25 Various file system independent parameters and contraints can be
  26 specified, such as:
  27         - minimum file system size (in KB)
  28         - maximum file system size (in KB)
  29         - free inodes
  30         - free blocks (in KB)
  31         - mtree(8) specification file containing permissions and ownership
  32           to use in image, overridding the settings in the directory tree
  33         - file containing list of files to specifically exclude or include
  34         - fnmatch(3) pattern of filenames to exclude or include
  35         - endianness of target file system
  36
  37 File system specific parameters can be given as well, with a command
  38 line option such as "-o fsspeccific-options,comma-separated".
  39 For example, ffs would allow tuning of:
  40         - block & fragment size
  41         - cylinder groups
  42         - number of blocks per inode
  43         - minimum free space
  44
  45 Other file systems might have controls on how to "munge" file names to
  46 fit within the constraints of the target file system.
  47
  48 Exit codes:
  49         0       all ok
  50         1       fatal error
  51         2       some files couldn't be added during image creation
  52                 (bad perms, missing file, etc). image will continue
  53                 to be made
  54
  55
  56 Implementation overview:
  57 ------------------------
  58
  59 The implementation must allow for easy addition of extra file systems
  60 with minimal changes to the file system independent sections.
  61
  62 The main program will:
  63         - parse the options, including calling fs-specific routines to
  64           validate fs-specific options
  65         - walk the tree, building up a data structure which represents
  66           the tree to stuff into the image. The structure will
  67           probably be a similar tree to what mtree(8) uses internally;
  68           a linked list of entries per directory with a child pointer
  69           to children of directories. ".." won't be stored in the list;
  70           the fs-specific tree walker should add this if required by the fs.
  71           this builder have the smarts to handle hard links correctly.
  72         - (optionally) Change the permissions in the tree according to
  73           the mtree(8) specfile
  74         - Call an fs-specific routine to build the image based on the
  75           data structures.
  76
  77 Each fs-specific module should have the following external interfaces:
  78
  79     prepare_options     optional file system specific defaults that need to be
  80                         setup before parsing fs-specific options.
  81
  82     parse_options       parse the string for fs-specific options, feeding
  83                         errors back to the user as appropriate
  84
  85     cleanup_options     optional file system specific data that need to be
  86                         cleaned up when done with this filesystem.
  87
  88     make_fs             take the data structures representing the
  89                         directory tree and fs parameters,
  90                         validate that the parameters are valid
  91                         (e.g, the requested image will be large enough),
  92                         create the image, and
  93                         populate the image
  94
  95 prepare_options and cleanup_options are optional and can be NULL.
  96
  97 NOTE: All file system specific options are referenced via the fs_specific
  98 pointer from the fsinfo_t strucutre. It is up to the filesystem to allocate
  99 and free any data needed for this via the prepare and cleanup callbacks.
 100
 101 Each fs-specific module will need to add it's routines to the dispatch array
 102 in makefs.c and add prototypes for these to makefs.h
 103
 104 All other implementation details should not need to change any of the
 105 generic code.
 106
 107 ffs implementation
 108 ------------------
 109
 110 In the ffs case, we can leverage off sbin/newfs/mkfs.c to actually build
 111 the image. When building and populating the image, the implementation
 112 can be greatly simplified if some assumptions are made:
 113         - the total required size (in blocks and inodes) is determined
 114           as part of the validation phase
 115         - a "file" (including a directory) has a known size, so
 116           support for growing a file is not necessary
 117
 118 Two underlying primitives are provided:
 119         make_inode      create an inode, returning the inode number
 120
 121         write_file      write file (from memory if DIR, file descriptor
 122                         if FILE or SYMLINK), referencing given inode.
 123                         it is smart enough to know if a short symlink
 124                         can be stuffed into the inode, etc.
 125
 126 When creating a directory, the directory entries in the previously
 127 built tree data structure is scanned and built in memory so it can
 128 be written entirely as a single write_file() operation.