sys/ufs/ufs/README.extattr

   1 $FreeBSD$
   2
   3   UFS Extended Attributes Copyright
   4
   5 The UFS Extended Attributes implementation is copyright Robert Watson, and
   6 is made available under a Berkeley-style license.
   7
   8   About UFS Extended Attributes
   9
  10 Extended attributes allow the association of additional arbitrary
  11 meta-data with files and directories.  Extended attributes are defined in
  12 the form name=value, where name is an nul-terminated string in the style
  13 of a filename, and value is a binary blob of zero or more bytes. The UFS
  14 extended attribute service layers support for extended attributes onto a
  15 backing file, in the style of the quota implementation, meaning that it
  16 requires no underlying format changes in the filesystem.  This design
  17 choice exchanges simplicity, usability and easy deployment for
  18 performance.  When defined, extended attribute names exist in a series of
  19 disjoint namespaces: currently, two namespaces are defined:
  20 EXTATTR_NAMESPACE_SYSTEM and EXTATTR_NAMESPACE_USER.  The primary
  21 distinction lies in the protection model: USER EAs are protected using the
  22 normal inode protections, whereas SYSTEM EAs require privilege to access
  23 or modify.
  24
  25   Using UFS Extended Attributes
  26
  27 Support for UFS extended attributes is natively available in UFS2, and
  28 requires no special configuration.  For reliability, administrative,
  29 and performance reasons, if you plan to use extended attributes, it
  30 is recommended that you use UFS2 in preference to UFS1.
  31
  32 Support for UFS extended attributes may be enabled for UFS1 by adding:
  33
  34         options UFS_EXTATTR
  35
  36 to your kernel configuration file.  This allows UFS-based filesystems to
  37 support extended attributes, but requires manual administration of EAs
  38 using the extattrctl tool, including the starting of EA support for each
  39 filesystem, and the enabling of individual attributes for the file
  40 system.  The extattrctl utility may be used to initialize backing files
  41 before first use, to start and stop EA service on a filesystem, and to
  42 enable and disable named attributes.  The command lines for extattrctl
  43 take the following forms:
  44
  45   extattrctl start [path]
  46   extattrctl stop [path]
  47   extattrctl initattr [-f] [-p path] [attrsize] [attrfile]
  48   extattrctl enable [path] [attrnamespace] [attrname] [attrfile]
  49   extattrctl disable [path] [attrnamespace] [attrname]
  50
  51 In each case, [path] is used to indicate the mounted filesystem on which
  52 to perform the operation.  [attrnamespace] refers to the namespace in
  53 which the attribute is being manipulated, and may be "system" or "user".
  54 The [attrname] is the attribute name to use for the operation. The
  55 [attrfile] argument specifies the attribute backing file to use. When
  56 using the "initattr" function to initialize a backing file, the maximum
  57 size of attribute data must be defined in bytes using the [attrsize]
  58 field.  Optionally, the [-p path] argument may be used to indicate to
  59 extattrctl that it should pre-allocate space for EA data, rather than
  60 creating a sparse backing file.  This prevents attribute operations from
  61 failing in low disk-space conditions (which can be important when EAs are
  62 used for security purposes), but pre-allocation will consume space
  63 proportional to the product of the defined maximum attribute size and
  64 number of attributes on the specified filesystem.
  65
  66 Manual configuration increases administrative overhead, but also
  67 introduces the possibility of race conditions during filesystem mount, if
  68 EAs are used to support other features, as starting the EAs manually is
  69 not atomic with the mount operation.  To address this problem, an
  70 additional kernel option may be defined to auto-start EAs on a UFS file
  71 system based on special directories at mount-time:
  72
  73         options UFS_EXTATTR_AUTOSTART
  74
  75 If this option is defined, UFS will search for a ".attribute"
  76 sub-directory of the filesystem root during the mount operation.  If it
  77 is found, EA support will be started for the filesystem.  UFS will then
  78 search for "system" and "user" sub-directories of the ".attribute"
  79 directory for any potential backing files, and enable an EA for each valid
  80 backing file with the name of the backing file as the attribute name.
  81 For example, by creating the following tree, the two EAs,
  82 posix1e.acl_access and posix1e.acl_default will be enabled in the system
  83 namespace of the root filesystem, reserving space for attribute data:
  84
  85   mkdir -p /.attribute/system
  86   cd /.attribute/system
  87   extattrctl initattr -p / 388 posix1e.acl_access
  88   extattrctl initattr -p / 388 posix1e.acl_default
  89
  90 On the next mount of the root filesystem, the attributes will be
  91 automatically started.