Extended attribute interfaces
Robert Watson
rwatson at FreeBSD.org
Sun Jun 18 16:50:25 GMT 2000
(this message is CC'd to Marius Bendiksen, who is working on new file
system implementations, but is not subscribed to the POSIX.1e list, but
probably should be as we talk about a lot of file system feature issues
:-)
Sorry to all for the long delay in doing this -- Andreas and I have been
bantering around extended attribute interfaces for a while, and I dropped
the ball on getting back to him with further discussion. As he now has an
implementation, and we had the workshop at SGI, I figure now is a good
time to try and find the ball I dropped, and propose we discuss, and
preferably pseudo-standardize, interfaces for extended attribute access.
Having the same interface on relevant platforms will make a big
difference.
I've attached six manual pages for components of the FreeBSD extended
attribute interface. They are largely in sync with the implementation.
VOP_GETEXTATTR.9.txt Kernel VFS interface to get extended attributes
VOP_SETEXTATTR.9.txt Kernel VFS interface to set/remove ea's
extattr.9.txt Kernel VFS introduction to ea's
extattrctl.8.txt Userland FFS-specific ea initialization
getextattr.8.txt Userland generic ea-fetching tool
setextattr.8.txt Userland generic ea-setting tool
Notable missings from the list would be syscall man pages, which are not
yet written. However, here are the syscalls from the FreeBSD 5.0 syscall
definition file, used to dynamically build kernel and libc stubs:
355 STD BSD { int extattrctl(const char *path, int cmd, \
const char *attrname, char *arg); }
356 STD BSD { int extattr_set_file(const char *path, \
const char *attrname, struct iovec *iovp, \
unsigned iovcnt); }
357 STD BSD { int extattr_get_file(const char *path, \
const char *attrname, struct iovec *iovp, \
unsigned iovcnt); }
358 STD BSD { int extattr_delete_file(const char *path, \
const char *attrname); }
As before, extattrctl is FFS-specific, and used to prepare attribute
backing files for the current implementation.
extattr_set_file() accepts a path, null-terminate attribute name,
and scatter-gather iovec of data to set. As with the VOP, this call
replaces the current data present.
extattr_get_file() does much the same, except it gets the attribute
present.
extattr_delete_file() delets an attribute from a file.
Open points of discussion include:
1) Ability to retrieve list of attributes on a file or directory --
presumably something dirent-like, but I'd like to hear about what both
the SGI folk and Andreas implemented, as there are many ways to do this
(and I have implemented none of them :-). Retriving is useful for
backups (probably only in the application namespace, see below).
2) Error value for non-present extended attribute. Currently I'm using
ENOENT, which is blatently confusing and improper :-). There has been
discussion of introducing a new error value, probably EEXTATTR or
ENOATTR, both of which seem decent.
3) Namespace issues. The SGI implementation has two namespaces -- root
and user. Properly speaking, I feel it should be "system" and
"application", but I like the idea of seperate namespaces to
distinguish application use from system use (security labels, for
example). Ted also expressed concerns about exposing application
extended attributes to userland, and I agree that there is the
potential for some problems here. Seperate namespaces would allow,
say, the Linux community to only permit system attributes and return
an error for application ones :-). That said, the Trusted IRIX
programmer's guide suggests a good use of application extended
attributes for shared spool directories. Adding an additional
argument for namespace control would make sense. However, what does
this mean for file systems that don't currently have namespaces like
that (HPFS, for example). My feeling is that for backup, also,
backup programs should touch only the application namespace, retrieving
system namespace stuff through appropriate ACL, capability, etc, APIs.
Robert N M Watson
robert at fledge.watson.org http://www.watson.org/~robert/
PGP key fingerprint: AF B5 5F FF A6 4A 79 37 ED 5F 55 E9 58 04 6A B1
TIS Labs at Network Associates, Safeport Network Services
-------------- next part --------------
VOP_GETEXTATTR(9) FreeBSD Kernel Developer's Manual VOP_GETEXTATTR(9)
NNAAMMEE
VVOOPP__GGEETTEEXXTTAATTTTRR - Retrieve named extended attribute from a vnode
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssyyss//ppaarraamm..hh>>
##iinncclluuddee <<ssyyss//vvnnooddee..hh>>
##iinncclluuddee <<ssyyss//eexxttaattttrr..hh>>
_i_n_t
VVOOPP__GGEETTEEXXTTAATTTTRR(_s_t_r_u_c_t _v_n_o_d_e _*_v_p, _c_h_a_r _*_n_a_m_e, _s_t_r_u_c_t _u_i_o _*_u_i_o,
_s_t_r_u_c_t _u_c_r_e_d _*_c_r_e_d, _s_t_r_u_c_t _p_r_o_c _*_p)
DDEESSCCRRIIPPTTIIOONN
This vnode call may be used to retrieve a specific named extended at-
tribute from a file or directory.
Its arguments are:
_v_p the vnode of the file or directory
_n_a_m_e pointer to a null-terminated character string containing the at-
tribute name
_u_i_o the location of the data to be read or written
_c_r_e_d the user credentials to use in authorizing the request
_p the process requesting the extended attribute
The _c_r_e_d pointer may be NULL to indicate that access control checks are
not to be performed, of possible. This cred setting might be used to al-
low the kernel to authorize extended attribute retrieval that the active
process might not be permitted to do.
Extended attribute semantics may vary by file system implementing the
call. More information on extended attributes may be found in
extattr(9).
LLOOCCKKSS
No locks are required to call this vnode method, and any locks held on
entry will be held on exit.
RREETTUURRNN VVAALLUUEESS
On success, zero will be returned, and the uio structure will be updated
to reflect data read. Otherwise, an appropriate error code is returned.
EERRRROORRSS
[ENOENT] The attribute name is not defined for this vnode
[EACCES] Permission denied
[ENXIO] The request was not valid in this file system for the
specified vnode and attribute name.
[ENOMEM] Insufficient memory available to fulfill request
[EFAULT] The uio structure refers to an invalid userspace ad-
dress.
[EINVAL] The _n_a_m_e or _u_i_o argument is invalid.
[EOPNOTSUPP] The file system does not support VOP_GETEXTATTR
SSEEEE AALLSSOO
extattr(9), vnode(9), VOP_SETEXTATTR(9)
BSD December 23, 1999 2
-------------- next part --------------
VOP_SETEXTATTR(9) FreeBSD Kernel Developer's Manual VOP_SETEXTATTR(9)
NNAAMMEE
VVOOPP__SSEETTEEXXTTAATTTTRR - Set named extended attribute for a vnode
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssyyss//ppaarraamm..hh>>
##iinncclluuddee <<ssyyss//vvnnooddee..hh>>
##iinncclluuddee <<ssyyss//eexxttaattttrr..hh>>
_i_n_t
VVOOPP__SSEETTEEXXTTAATTTTRR(_s_t_r_u_c_t _v_n_o_d_e _*_v_p, _c_h_a_r _*_n_a_m_e, _s_t_r_u_c_t _u_i_o _*_u_i_o,
_s_t_r_u_c_t _u_c_r_e_d _*_c_r_e_d, _s_t_r_u_c_t _p_r_o_c _*_p)
DDEESSCCRRIIPPTTIIOONN
This vnode call may be used to set specific named extended attribute for
a file or directory.
Its arguments are:
_v_p the vnode of the file or directory
_n_a_m_e pointer to a null-terminated character string containing the at-
tribute name
_u_i_o the location of the data to be read or written
_c_r_e_d the user credentials to use in authorizing the request
_p the process setting the extended attribute
The uio structure is used in a manner similar to the argument of the same
name in VOP_WRITE. However, as extended attributes provide a strict
"name=value" semantic, non-zero offsets will be rejected.
The _u_i_o pointer may be NULL to indicate that the specified extended at-
tribute should be deleted.
The _c_r_e_d pointer may be NULL to indicate that access control checks are
not to be performed, of possible. This cred setting might be used to al-
low the kernel to authorize extended attribute changes that the active
process might not be permitted to make.
Extended attribute semantics may vary by file system implementing the
call. More information on extended attributes may be found in
extattr(9).
LLOOCCKKSS
The vnode will be locked on entry and should remain locked on return.
RREETTUURRNN VVAALLUUEESS
If the extended attribute is successfully set, then zero is returned.
Otherwise, an appropriate error code is returned.
EERRRROORRSS
[EACCES] Permission denied
[ENXIO] The request was not valid in this file system for the
specified vnode and attribute name.
[ENOMEM] Insufficient memory available to fulfill request
[EFAULT] The uio structure refers to an invalid userspace ad-
dress
[EINVAL] The name or uio argument is invalid
[EOPNOTSUPP] The file system does not support VOP_GETEXTATTR
[ENOSPC] The file system is out of space
[EROFS] The file system is read-only
SSEEEE AALLSSOO
extattr(9), vnode(9), VOP_GETEXTATTR(9)
AAUUTTHHOORRSS
This man page was written by Robert Watson.
BSD December 23, 1999 2
-------------- next part --------------
EXTATTR(9) FreeBSD Kernel Developer's Manual EXTATTR(9)
NNAAMMEE
eexxttaattttrr - virtual file system named extended attributes
SSYYNNOOPPSSIISS
##iinncclluuddee <<ssyyss//ppaarraamm..hh>>
##iinncclluuddee <<ssyyss//vvnnooddee..hh>>
##iinncclluuddee <<ssyyss//eexxttaattttrr..hh>>
DDEESSCCRRIIPPTTIIOONN
Named extended attributes allow additional meta-data to be associated
with vnodes representing files and directories. The semantics of this
additional data is that of a "name=value" pair, where a name may be de-
fined or undefined, and if defined, associated with zero or more bytes of
arbitrary binary data. Reads of this data may return specific contiguous
regions of the meta-data, in the style of VOP_READ(9), but writes will
replace the entire current "value" associated with a given name. As
there are a plethora of file systems with differing extended attributes,
availability and functionality of these functions may be limited, and
they should be used with awareness of the underlying semantics of the
supporting file system. Authorization schemes for extended attribute da-
ta may also vary by file system, as well as maximum attribute size, and
whether or not any or specific new attributes may be defined.
Extended attributes are named using a null-terminated character string.
Depending on file system semantics, this name may or may not be case-sen-
sitive. Appropriate vnode extended attribute calls are: VOP_GETEXTAT-
TR(9) and VOP_SETEXTATTR(9).
SSEEEE AALLSSOO
VFS(9), VOP_GETEXTATTR(9), VOP_SETEXTATTR(9).
AAUUTTHHOORRSS
This man page was written by Robert Watson.
BSD December 23, 1999 1
-------------- next part --------------
EXTATTRCTL(8) FreeBSD System Manager's Manual EXTATTRCTL(8)
NNAAMMEE
eexxttaattttrrccttll - manage FFS extended attributes
SSYYNNOOPPSSIISS
eexxttaattttrrccttll ssttaarrtt _p_a_t_h
eexxttaattttrrccttll ssttoopp _p_a_t_h
eexxttaattttrrccttll iinniittaattttrr _a_t_t_r_s_i_z_e _a_t_t_r_f_i_l_e
eexxttaattttrrccttll eennaabbllee _p_a_t_h _a_t_t_r_n_a_m_e _a_t_t_r_f_i_l_e
eexxttaattttrrccttll ddiissaabbllee _p_a_t_h _a_t_t_r_n_a_m_e
DDEESSCCRRIIPPTTIIOONN
eexxttaattttrrccttll is the management utility for extended attributes over the FFS
file system. eexxttaattttrrccttll allows the starting and stopping of extended at-
tributes on a file system, as well as initialization of attribute backing
files, and enabling and disabling of specific extended attributes on a
file system.
The first argument on the command line indicates the operation to be per-
formend. Operation must be one of the following:
ssttaarrtt _p_a_t_h
Start extended attribute support on the file system named using
_p_a_t_h. The file system must be an FFS file system, and the FFS_EX-
TATTR kernel option must have been enabled.
ssttoopp _p_a_t_h
Stop extended attribute support on the file system named using
_p_a_t_h. Extended attribute support must previously have been start-
ed.
iinniittaattttrr [--pp _p_a_t_h] [--rr [_k_r_o_a]] [--ww [_k_r_o_a]] _a_t_t_r_s_i_z_e _a_t_t_r_f_i_l_e
Create and initialize a file to use as an attribute backing file.
You must specify a maximum per-inode size for the attribute in
bytes in _a_t_t_r_s_i_z_e, as well as the file where the attribute will
be stored, using _a_t_t_r_f_i_l_e.
The --pp _p_a_t_h argument may be used to preallocate space for all at-
tributes rather than relying on sparse files to conserve space.
This has the advantage of guaranteeing that space will be avail-
able for attributes when they are written, preventing low disk
space conditions from denying attribute service.
The --rr and --ww options can be used to set the read and write per-
missions on the named attribute, respectively. There are four
levels possible for both read and write: ``k'' limits reading or
writing to the kernel, ``r'' limits activities to root, ``o''
limits activities to root and the owner of the file having the
attribute read or written, and ``q'' allows any user to perform
the attribute operation. The default is to limit activities to
the root user, or ``r''.
This file should not exist before running iinniittaattttrr..
eennaabbllee _p_a_t_h _a_t_t_r_n_a_m_e _a_t_t_r_f_i_l_e
Enable an attribute named _a_t_t_r_n_a_m_e on the file system identified
using _p_a_t_h, and backed by initialized attribute file _a_t_t_r_f_i_l_e.
The backing file must have been initialized using iinniittaattttrr before
its first use. Attributes must have been started on the file
system prior to the enabling of any attributes.
ddiissaabbllee _p_a_t_h _a_t_t_r_n_a_m_e
Disable the attributed named _a_t_t_r_n_a_m_e on the file system identi-
fied by _p_a_t_h. The file system must have attributes started on it,
and the attribute most have been enabled using eennaabbllee.
EEXXAAMMPPLLEESS
extattrctl start /
Start extended attributes on the root file system.
extattrctl initattr 17 /.attribute/md5
Create an attribute backing file in /.attribute/md5, and set the maximum
size of each attribute to 17 bytes. Sparse files are used for storing
the attributes, and the default permissions limiting access to the root
user are implied.
extattrctl enable / md5 /.attribute/md5
Enable an attribute named md5 on the root file system, backed from the
file /.attribute/md5.
extattrctl disable / md5
Disable the attribute named md5 on the root file system.
extattrctl stop /
Stop extended attributes on the root file system.
SSEEEE AALLSSOO
getextattr(8), setextattr(8), extattr(9)
HHIISSTTOORRYY
Extended attribute support was developed as part of the TrustedBSD Pro-
ject, and introduced in FreeBSD 5.0. It was developed to support securi-
ty extensions requiring additional labels to be associated with each file
or directory.
AAUUTTHHOORRSS
Robert N M Watson
BSD March 30, 2000 2
-------------- next part --------------
GETEXTATTR(8) FreeBSD System Manager's Manual GETEXTATTR(8)
NNAAMMEE
ggeetteexxttaattttrr - retrieve a named extended attribute
SSYYNNOOPPSSIISS
ggeetteexxttaattttrr [--llss] _a_t_t_r_n_a_m_e _f_i_l_e_n_a_m_e _._._.
DDEESSCCRRIIPPTTIIOONN
ggeetteexxttaattttrr is a user tool to retrieve a named extended attribute on a
file or directory. The _a_t_t_r_n_a_m_e argument should be the name of the at-
tribute, and _f_i_l_e_n_a_m_e a list of files and directories from which to re-
trieve attribute data.
The following options are available:
--ll Print attributes in the first column and file names in the sec-
ond. Can be used only in conjunction with the --ss option.
--ss Attempt to display the attribute data as a string, although the
results may not look pretty if the data is binary data. The
strvisx(3) function is used to generate the string, so control
sequences should be safely escaped. Otherwise, the attribute da-
ta will be represented as a series of two-digit hex numbers.
IIMMPPLLEEMMEENNTTAATTIIOONN NNOOTTEESS
In order for ggeetteexxttaattttrr to succeed, the attribute service must be avail-
able on the file system, and the attribute must of defined for the file
queried.
EEXXAAMMPPLLEESS
# getextattr md5 /kernel
/kernel:
61 61 33 62 39 39 66 65 31 35 35 32 31 62 65 32
62 36 38 36 62 31 66 39 63 64 33 39 35 36 36 31
# getextattr -s md5 /kernel
/kernel: "aa3b99fe15521be2b686b1f9cd395661"
Retrieve the ``md5'' extended attribute for the file _/_k_e_r_n_e_l.
SSEEEE AALLSSOO
extattrctl(8), setextattr(8), extattr(9)
HHIISSTTOORRYY
Extended attribute support was developed as part of the TrustedBSD Pro-
ject, and introduced in FreeBSD 5.0. It was developed to support securi-
ty extensions requiring additional labels to be associated with each file
or directory.
AAUUTTHHOORRSS
Robert N M Watson
BBUUGGSS
Only the first 2048 bytes of the extended attribute value are displayed
due to a hard-coded buffer limit.
BSD March 30, 2000 1
-------------- next part --------------
SETEXTATTR(8) FreeBSD System Manager's Manual SETEXTATTR(8)
NNAAMMEE
sseetteexxttaattttrr - set a named extended attribute
SSYYNNOOPPSSIISS
sseetteexxttaattttrr _a_t_t_r_n_a_m_e _f_i_l_e_n_a_m_e _a_t_t_r_v_a_l_u_e
DDEESSCCRRIIPPTTIIOONN
sseetteexxttaattttrr is a user tool to set a named extended attribute on a file or
directory to the provided string. The _a_t_t_r_n_a_m_e argument should be the
name of the attribute, _f_i_l_e_n_a_m_e the name of the file or directory to set
the attribute for, and _a_t_t_r_v_a_l_u_e a string to store in the attribute. ssee--
tteexxttaattttrr will store the string in the file's attribute. In order for ssee--
tteexxttaattttrr to succeed, the attribute service must be available on the file
system, and appropriate privilege may be required.
EEXXAAMMPPLLEESS
# setextattr md5 /kernel `md5 -q /kernel`
Set the ``md5'' extended attribute on the file /kernel to the string con-
taining the output of ``md5 -q /kernel''.
SSEEEE AALLSSOO
extattrctl(8), getextattr(8), extattr(9)
HHIISSTTOORRYY
Extended attribute support was developed as part of the TrustedBSD Pro-
ject, and introduced in FreeBSD 5.0. It was developed to support securi-
ty extensions requiring additional labels to be associated with each file
or directory.
AAUUTTHHOORRSS
Robert N M Watson
BBUUGGSS
sseetteexxttaattttrr can only be used to set attributes to strings.
BSD March 30, 2000 1
More information about the posix1e
mailing list