usr.sbin/makefs/README

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