usr.sbin/extattrctl/extattrctl.8

   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 UFS1 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 The
  68 .Nm
  69 utility
  70 is the management utility for extended attributes over the UFS1 file system.
  71 It allows the starting and stopping of extended attributes on a file system,
  72 as well as initialization of attribute backing files, and enabling and
  73 disabling of specific extended attributes on a file system.
  74 .Pp
  75 The first argument on the command line indicates the operation to be
  76 performed.
  77 Operation must be one of the following:
  78 .Bl -tag -width indent
  79 .It Cm start Ar path
  80 Start extended attribute support on the file system named using
  81 .Ar path .
  82 The file system must be an UFS1 file system, and the UFS_EXTATTR kernel
  83 option must have been enabled.
  84 .It Cm stop Ar path
  85 Stop extended attribute support on the file system named using
  86 .Ar path .
  87 Extended attribute support must previously have been started.
  88 .It Xo
  89 .Cm initattr
  90 .Op Fl f
  91 .Op Fl p Ar path
  92 .Ar attrsize attrfile
  93 .Xc
  94 Create and initialize a file to use as an attribute backing file.
  95 You must specify a maximum per-inode size for the attribute in bytes in
  96 .Ar attrsize ,
  97 as well as the file where the attribute will be stored, using
  98 .Ar attrfile .
  99 .Pp
 100 The
 101 .Fl f
 102 argument may be used to indicate that it is alright to overwrite an
 103 existing attribute backing file; otherwise, if the target file exists,
 104 an error will be returned.
 105 .Pp
 106 The
 107 .Fl p Ar path
 108 argument may be used to preallocate space for all attributes rather than
 109 relying on sparse files to conserve space.
 110 This has the advantage of guaranteeing that space will be available
 111 for attributes when they are written, preventing low disk space conditions
 112 from denying attribute service.
 113 .Pp
 114 This file should not exist before running
 115 .Cm initattr .
 116 .It Cm showattr Ar attrfile
 117 Show the attribute header values in the attribute file named by
 118 .Ar attrfile .
 119 .It Cm enable Ar path attrnamespace attrname attrfile
 120 Enable an attribute named
 121 .Ar attrname
 122 in the namespace
 123 .Ar attrnamespace
 124 on the file system identified using
 125 .Ar path ,
 126 and backed by initialized attribute file
 127 .Ar attrfile .
 128 Available namespaces are "user" and "system".
 129 The backing file must have been initialized using
 130 .Cm initattr
 131 before its first use.
 132 Attributes must have been started on the file system prior to the
 133 enabling of any attributes.
 134 .It Cm disable Ar path attrnamespace attrname
 135 Disable the attributed named
 136 .Ar attrname
 137 in namespace
 138 .Ar attrnamespace
 139 on the file system identified by
 140 .Ar path .
 141 Available namespaces are "user" and "system".
 142 The file system must have attributes started on it, and the attribute
 143 most have been enabled using
 144 .Cm enable .
 145 .El
 146 .Sh EXAMPLES
 147 .Dl extattrctl start /
 148 .Pp
 149 Start extended attributes on the root file system.
 150 .Pp
 151 .Dl extattrctl initattr 17 /.attribute/system/md5
 152 .Pp
 153 Create an attribute backing file in /.attribute/system/md5, and set the maximum
 154 size of each attribute to 17 bytes, with a sparse file used for storing
 155 the attributes.
 156 .Pp
 157 .Dl extattrctl enable / system md5 /.attribute/system/md5
 158 .Pp
 159 Enable an attribute named md5 on the root file system, backed from the file
 160 /.attribute/system/md5.
 161 .Pp
 162 .Dl extattrctl disable / md5
 163 .Pp
 164 Disable the attribute named md5 on the root file system.
 165 .Pp
 166 .Dl extattrctl stop /
 167 .Pp
 168 Stop extended attributes on the root file system.
 169 .Sh SEE ALSO
 170 .Xr ffs 7 ,
 171 .Xr getextattr 8 ,
 172 .Xr setextattr 8 ,
 173 .Xr extattr 9
 174 .Sh HISTORY
 175 Extended attribute support was developed as part of the TrustedBSD Project,
 176 and introduced in
 177 .Fx 5.0 .
 178 It was developed to support security extensions requiring additional labels
 179 to be associated with each file or directory.
 180 .Sh AUTHORS
 181 Robert N M Watson