1.\"- 2.\" Copyright (c) 2000-2001 Robert N. M. Watson 3.\" All rights reserved. 4.\" 5.\" This software was developed by Robert Watson for the TrustedBSD Project. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.\" Developed by the TrustedBSD Project. 31.\" Support for file system extended attribute. 32.\" 33.Dd March 30, 2000 34.Dt EXTATTRCTL 8 35.Os 36.Sh NAME 37.Nm extattrctl 38.Nd manage FFS extended attributes 39.Sh SYNOPSIS 40.Nm 41.Cm start 42.Ar path 43.Nm 44.Cm stop 45.Ar path 46.Nm 47.Cm initattr 48.Op Fl f 49.Op Fl p Ar path 50.Ar attrsize 51.Ar attrfile 52.Nm 53.Cm showattr 54.Ar attrfile 55.Nm 56.Cm enable 57.Ar path 58.Ar attrnamespace 59.Ar attrname 60.Ar attrfile 61.Nm 62.Cm disable 63.Ar path 64.Ar attrnamespace 65.Ar attrname 66.Sh DESCRIPTION 67.Nm 68is the management utility for extended attributes over the FFS file system. 69.Nm 70allows the starting and stopping of extended attributes on a file system, 71as well as initialization of attribute backing files, and enabling and 72disabling of specific extended attributes on a file system. 73.Pp 74The first argument on the command line indicates the operation to be 75performed. 76Operation must be one of the following: 77.Bl -tag -width indent 78.It Cm start Ar path 79Start extended attribute support on the file system named using 80.Ar path . 81The file system must be an FFS file system, and the FFS_EXTATTR kernel 82option must have been enabled. 83.It Cm stop Ar path 84Stop extended attribute support on the file system named using 85.Ar path . 86Extended attribute support must previously have been started. 87.It Xo 88.Cm initattr 89.Op Fl f 90.Op Fl p Ar path 91.Ar attrsize attrfile 92.Xc 93Create and initialize a file to use as an attribute backing file. 94You must specify a maximum per-inode size for the attribute in bytes in 95.Ar attrsize , 96as well as the file where the attribute will be stored, using 97.Ar attrfile . 98.Pp 99The 100.Fl f 101argument may be used to indicate that it is alright to overwrite an 102existing attribute backing file; otherwise, if the target file exists, 103an error will be returned. 104.Pp 105The 106.Fl p Ar path 107argument may be used to preallocate space for all attributes rather than 108relying on sparse files to conserve space. 109This has the advantage of guaranteeing that space will be available 110for attributes when they are written, preventing low disk space conditions 111from denying attribute service. 112.Pp 113This file should not exist before running 114.Cm initattr . 115.It Cm showattr Ar attrfile 116Show the attribute header values in the attribute file named by 117.Ar attrfile . 118.It Cm enable Ar path attrnamespace attrname attrfile 119Enable an attribute named 120.Ar attrname 121in the namespace 122.Ar attrnamespace 123on the file system identified using 124.Ar path , 125and backed by initialized attribute file 126.Ar attrfile . 127Available namespaces are "user" and "system". 128The backing file must have been initialized using 129.Cm initattr 130before its first use. 131Attributes must have been started on the file system prior to the 132enabling of any attributes. 133.It Cm disable Ar path attrnamespace attrname 134Disable the attributed named 135.Ar attrname 136in namespace 137.Ar attrnamespace 138on the file system identified by 139.Ar path . 140Available namespaces are "user" and "system". 141The file system must have attributes started on it, and the attribute 142most have been enabled using 143.Cm enable . 144.El 145.Sh EXAMPLES 146.Dl extattrctl start / 147.Pp 148Start extended attributes on the root file system. 149.Pp 150.Dl extattrctl initattr 17 /.attribute/md5 151.Pp 152Create an attribute backing file in /.attribute/md5, and set the maximum 153size of each attribute to 17 bytes, with a sparse file used for storing 154the attributes. 155.Pp 156.Dl extattrctl enable / system md5 /.attribute/md5 157.Pp 158Enable an attribute named md5 on the root file system, backed from the file 159/.attribute/md5. 160.Pp 161.Dl extattrctl disable / md5 162.Pp 163Disable the attribute named md5 on the root file system. 164.Pp 165.Dl extattrctl stop / 166.Pp 167Stop extended attributes on the root file system. 168.Sh SEE ALSO 169.Xr getextattr 8 , 170.Xr setextattr 8 , 171.Xr extattr 9 172.Sh HISTORY 173Extended attribute support was developed as part of the TrustedBSD Project, 174and introduced in 175.Fx 5.0 . 176It was developed to support security extensions requiring additional labels 177to be associated with each file or directory. 178.Sh AUTHORS 179Robert N M Watson 180