175133Srwatson$FreeBSD: releng/11.0/sys/ufs/ufs/README.extattr 105417 2002-10-18 21:11:36Z rwatson $ 275133Srwatson 375133Srwatson UFS Extended Attributes Copyright 475133Srwatson 575133SrwatsonThe UFS Extended Attributes implementation is copyright Robert Watson, and 675133Srwatsonis made available under a Berkeley-style license. 775133Srwatson 875133Srwatson About UFS Extended Attributes 975133Srwatson 1075133SrwatsonExtended attributes allow the association of additional arbitrary 1175133Srwatsonmeta-data with files and directories. Extended attributes are defined in 1275133Srwatsonthe form name=value, where name is an nul-terminated string in the style 1375133Srwatsonof a filename, and value is a binary blob of zero or more bytes. The UFS 1475133Srwatsonextended attribute service layers support for extended attributes onto a 1575133Srwatsonbacking file, in the style of the quota implementation, meaning that it 1696755Strhodesrequires no underlying format changes in the filesystem. This design 1775133Srwatsonchoice exchanges simplicity, usability and easy deployment for 1875133Srwatsonperformance. When defined, extended attribute names exist in a series of 1975133Srwatsondisjoint namespaces: currently, two namespaces are defined: 2075133SrwatsonEXTATTR_NAMESPACE_SYSTEM and EXTATTR_NAMESPACE_USER. The primary 2175133Srwatsondistinction lies in the protection model: USER EAs are protected using the 2275133Srwatsonnormal inode protections, whereas SYSTEM EAs require privilege to access 2375133Srwatsonor modify. 2475133Srwatson 2575133Srwatson Using UFS Extended Attributes 2675133Srwatson 27105417SrwatsonSupport for UFS extended attributes is natively available in UFS2, and 28105417Srwatsonrequires no special configuration. For reliability, administrative, 29105417Srwatsonand performance reasons, if you plan to use extended attributes, it 30105417Srwatsonis recommended that you use UFS2 in preference to UFS1. 3175133Srwatson 32105417SrwatsonSupport for UFS extended attributes may be enabled for UFS1 by adding: 33105417Srwatson 3475133Srwatson options UFS_EXTATTR 3575133Srwatson 3696755Strhodesto your kernel configuration file. This allows UFS-based filesystems to 3775133Srwatsonsupport extended attributes, but requires manual administration of EAs 3875133Srwatsonusing the extattrctl tool, including the starting of EA support for each 3996755Strhodesfilesystem, and the enabling of individual attributes for the file 4075133Srwatsonsystem. The extattrctl utility may be used to initialize backing files 4196755Strhodesbefore first use, to start and stop EA service on a filesystem, and to 4275133Srwatsonenable and disable named attributes. The command lines for extattrctl 4375133Srwatsontake the following forms: 4475133Srwatson 4575133Srwatson extattrctl start [path] 4675133Srwatson extattrctl stop [path] 4775133Srwatson extattrctl initattr [-f] [-p path] [attrsize] [attrfile] 4875133Srwatson extattrctl enable [path] [attrnamespace] [attrname] [attrfile] 4975133Srwatson extattrctl disable [path] [attrnamespace] [attrname] 5075133Srwatson 5196755StrhodesIn each case, [path] is used to indicate the mounted filesystem on which 5275133Srwatsonto perform the operation. [attrnamespace] refers to the namespace in 5375133Srwatsonwhich the attribute is being manipulated, and may be "system" or "user". 5475133SrwatsonThe [attrname] is the attribute name to use for the operation. The 5575133Srwatson[attrfile] argument specifies the attribute backing file to use. When 5675133Srwatsonusing the "initattr" function to initialize a backing file, the maximum 5775133Srwatsonsize of attribute data must be defined in bytes using the [attrsize] 5875133Srwatsonfield. Optionally, the [-p path] argument may be used to indicate to 5975133Srwatsonextattrctl that it should pre-allocate space for EA data, rather than 6075133Srwatsoncreating a sparse backing file. This prevents attribute operations from 6175133Srwatsonfailing in low disk-space conditions (which can be important when EAs are 6275133Srwatsonused for security purposes), but pre-allocation will consume space 6375133Srwatsonproportional to the product of the defined maximum attribute size and 6496755Strhodesnumber of attributes on the specified filesystem. 6575133Srwatson 6675133SrwatsonManual configuration increases administrative overhead, but also 6796755Strhodesintroduces the possibility of race conditions during filesystem mount, if 6875133SrwatsonEAs are used to support other features, as starting the EAs manually is 6975133Srwatsonnot atomic with the mount operation. To address this problem, an 7075133Srwatsonadditional kernel option may be defined to auto-start EAs on a UFS file 7175133Srwatsonsystem based on special directories at mount-time: 7275133Srwatson 7375133Srwatson options UFS_EXTATTR_AUTOSTART 7475133Srwatson 7575133SrwatsonIf this option is defined, UFS will search for a ".attribute" 7696755Strhodessub-directory of the filesystem root during the mount operation. If it 7796755Strhodesis found, EA support will be started for the filesystem. UFS will then 7875133Srwatsonsearch for "system" and "user" sub-directories of the ".attribute" 7975133Srwatsondirectory for any potential backing files, and enable an EA for each valid 8075133Srwatsonbacking file with the name of the backing file as the attribute name. 8175133SrwatsonFor example, by creating the following tree, the two EAs, 8275133Srwatsonposix1e.acl_access and posix1e.acl_default will be enabled in the system 8396755Strhodesnamespace of the root filesystem, reserving space for attribute data: 8475133Srwatson 8587132Srwatson mkdir -p /.attribute/system 8675133Srwatson cd /.attribute/system 8787131Srwatson extattrctl initattr -p / 388 posix1e.acl_access 8887131Srwatson extattrctl initattr -p / 388 posix1e.acl_default 8975133Srwatson 9096755StrhodesOn the next mount of the root filesystem, the attributes will be 9175133Srwatsonautomatically started. 92