218 lines
6.4 KiB
Groff
218 lines
6.4 KiB
Groff
.\" $NetBSD: extattrctl.8,v 1.5 2011/06/17 18:20:40 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2000-2001 Robert N. M. Watson
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This software was developed by Robert Watson for the TrustedBSD Project.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD: src/usr.sbin/extattrctl/extattrctl.8,v 1.24 2005/02/09 18:04:40 ru Exp $
|
|
.\"
|
|
.\" Developed by the TrustedBSD Project.
|
|
.\" Support for file system extended attribute.
|
|
.\"
|
|
.Dd June 17, 2011
|
|
.Dt EXTATTRCTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm extattrctl
|
|
.Nd manage UFS1 extended attributes
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Cm start
|
|
.Ar path
|
|
.Nm
|
|
.Cm stop
|
|
.Ar path
|
|
.Nm
|
|
.Cm initattr
|
|
.Op Fl f
|
|
.Op Fl p Ar path
|
|
.Ar attrsize
|
|
.Ar attrfile
|
|
.Nm
|
|
.Cm showattr
|
|
.Ar attrfile
|
|
.Nm
|
|
.Cm enable
|
|
.Ar path
|
|
.Ar attrnamespace
|
|
.Ar attrname
|
|
.Ar attrfile
|
|
.Nm
|
|
.Cm disable
|
|
.Ar path
|
|
.Ar attrnamespace
|
|
.Ar attrname
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility
|
|
is the management utility for extended attributes over the UFS1 file system.
|
|
It allows the starting and stopping of extended attributes on a file system,
|
|
as well as initialization of attribute backing files, and enabling and
|
|
disabling of specific extended attributes on a file system.
|
|
.Pp
|
|
The first argument on the command line indicates the operation to be
|
|
performed.
|
|
Operation must be one of the following:
|
|
.Bl -tag -width indent
|
|
.It Cm start Ar path
|
|
Start extended attribute support on the file system named using
|
|
.Ar path .
|
|
The file system must be a UFS1 file system, and the
|
|
.Dv UFS_EXTATTR
|
|
kernel option must have been enabled.
|
|
If
|
|
.Pa .attribute/user
|
|
and
|
|
.Pa .attribute/system
|
|
exist at the filesystem root, extended attributes backed by files
|
|
in these directories will be automatically enabled.
|
|
Note that extended attributes can be automatically started at mount
|
|
time by using the
|
|
.Cm -o extattr
|
|
option to
|
|
.Xr mount 8 .
|
|
.It Cm stop Ar path
|
|
Stop extended attribute support on the file system named using
|
|
.Ar path .
|
|
Extended attribute support must previously have been started.
|
|
.It Cm initattr Oo Fl f Oc Oo Fl p Ar path Oc Ar attrsize attrfile
|
|
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
|
|
.Ar attrsize ,
|
|
as well as the file where the attribute will be stored, using
|
|
.Ar attrfile .
|
|
.Pp
|
|
The
|
|
.Fl f
|
|
argument may be used to indicate that it is alright to overwrite an
|
|
existing attribute backing file; otherwise, if the target file exists,
|
|
an error will be returned.
|
|
.Pp
|
|
The
|
|
.Fl p Ar path
|
|
argument may be used to preallocate space for all attributes rather than
|
|
relying on sparse files to conserve space.
|
|
This has the advantage of guaranteeing that space will be available
|
|
for attributes when they are written, preventing low disk space conditions
|
|
from denying attribute service.
|
|
.Pp
|
|
This file should not exist before running
|
|
.Cm initattr .
|
|
.Pp
|
|
When a user attempts to set a
|
|
.Dq user
|
|
or
|
|
.Dq system
|
|
extended attribute that lacks a backing file,
|
|
the kernel will attempt to automatically create it, provided
|
|
.Pa .attribute/user
|
|
or
|
|
.Pa .attribute/system
|
|
exist and are writable by the requesting user.
|
|
.It Cm showattr Ar attrfile
|
|
Show the attribute header values in the attribute file named by
|
|
.Ar attrfile .
|
|
.It Cm enable Ar path attrnamespace attrname attrfile
|
|
Enable an attribute named
|
|
.Ar attrname
|
|
in the namespace
|
|
.Ar attrnamespace
|
|
on the file system identified using
|
|
.Ar path ,
|
|
and backed by initialized attribute file
|
|
.Ar attrfile .
|
|
Available namespaces are
|
|
.Dq user
|
|
and
|
|
.Dq system .
|
|
The backing file must have been initialized using
|
|
.Cm initattr
|
|
before its first use.
|
|
Attributes must have been started on the file system prior to the
|
|
enabling of any attributes.
|
|
.It Cm disable Ar path attrnamespace attrname
|
|
Disable the attributed named
|
|
.Ar attrname
|
|
in namespace
|
|
.Ar attrnamespace
|
|
on the file system identified by
|
|
.Ar path .
|
|
Available namespaces are
|
|
.Dq user
|
|
and
|
|
.Dq system .
|
|
The file system must have attributes started on it, and the attribute
|
|
most have been enabled using
|
|
.Cm enable .
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Dl extattrctl start /
|
|
.Pp
|
|
Start extended attributes on the root file system.
|
|
.Pp
|
|
.Dl extattrctl initattr 17 /.attribute/system/md5
|
|
.Pp
|
|
Create an attribute backing file in
|
|
.Pa /.attribute/system/md5 ,
|
|
and set the maximum size of each attribute to 17 bytes, with a
|
|
sparse file used for storing the attributes.
|
|
.Pp
|
|
.Dl extattrctl enable / system md5 /.attribute/system/md5
|
|
.Pp
|
|
Enable an attribute named md5 on the root file system, backed from the file
|
|
.Pa /.attribute/system/md5 .
|
|
.Pp
|
|
.Dl extattrctl disable / md5
|
|
.Pp
|
|
Disable the attribute named md5 on the root file system.
|
|
.Pp
|
|
.Dl extattrctl stop /
|
|
.Pp
|
|
Stop extended attributes on the root file system.
|
|
.Sh SEE ALSO
|
|
.Xr getextattr 1 ,
|
|
.Xr extattr_get_file 2 ,
|
|
.\" .Xr ffs 7 ,
|
|
.Xr extattr 9
|
|
.Sh HISTORY
|
|
Extended attribute support was developed as part of the TrustedBSD
|
|
Project, and introduced in
|
|
.Fx 5.0
|
|
and
|
|
.Nx 4.0 .
|
|
It was developed to support security extensions requiring additional
|
|
labels to be associated with each file or directory.
|
|
Backing file autocreation was added in
|
|
.Nx 6.0 .
|
|
.Sh AUTHORS
|
|
.An Robert N M Watson
|
|
.Sh BUGS
|
|
.Nm
|
|
works only on UFS1 file systems.
|
|
The kernel support for extended attribute backing files and this
|
|
control program should be generalized for any file system that
|
|
lacks native extended attribute support.
|