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