]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man9/VOP_SETLABEL.9
import nvi 2.2.0-3bbdfe4
[FreeBSD/FreeBSD.git] / share / man / man9 / VOP_SETLABEL.9
1 .\"-
2 .\" Copyright (c) 2021 Robert N. M. Watson
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\"    notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\"    notice, this list of conditions and the following disclaimer in the
12 .\"    documentation and/or other materials provided with the distribution.
13 .\"
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24 .\" SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD$
27 .\"
28 .Dd February 27, 2021
29 .Dt VOP_SETLABEL 9
30 .Os
31 .Sh NAME
32 .Nm VOP_SETLABEL
33 .Nd persistently store an updated MAC label on a vnode
34 .Sh SYNOPSIS
35 .In sys/param.h
36 .In sys/vnode.h
37 .In security/mac.h
38 .Ft int
39 .Fn VOP_SETLABEL "struct vnode *vp" "label *label"
40 .Sh DESCRIPTION
41 This vnode call is made by
42 .Xr mac 9
43 file relabeling operation has been authorized, and the filesystem must now be
44 updated.
45 .Ss Single-Label vs. Multi-Label Filesystems
46 Filesystems that do not implement per-file labels -- known as single-label
47 filesystems -- can simply leave the
48 .Xr vnode 9
49 operation undefined.
50 These filesystems must not set the
51 .Dv MNT_MULTLABEL
52 flag in their
53 .Vt struct mount .
54 .Pp
55 Filesystems that do implement per-vnode label storage -- known as multi-label
56 filesystems -- will set the
57 .Dv MNT_MULTILABEL
58 flag in their
59 .Vt struct mount .
60 The UFS filesystem uses a superblock flag to persisently configure whether a
61 specific filesystem implements a label for each
62 .Xr vnode 9 ,
63 and then keys various behaviors on whether that flag is set.
64 .Ss Extended Attributes
65 If the filesystem implements extended attributes, then the MAC Framework's
66 .Fn vop_stdsetlabel_ea
67 function can be used, and maps operations into a series of
68 .Xr VOP_OPENEXTATTR 9 ,
69 .Xr VOP_WRITEEXTATTR 9 ,
70 and
71 .Xr VOP_CLOSEEXTATTR 9 .
72 .Pp
73 Filesystems will also need to call
74 .Fn mac_vnode_create_extattr
75 when a new filesystem object is created, so that suitable extended attributes
76 can be written out, and
77 .Fn mac_vnode_associate_extattr
78 when a
79 .Xr vnode 9
80 is associated with a filesystem object for the first time.
81 These utility functions use
82 .Xr VOP_OPENEXTATTR 9 ,
83 .Xr VOP_READEXTATTR 9 ,
84 .Xr VOP_WRITEEXTATTR 9 ,
85 and
86 .Xr VOP_CLOSEEXTATTR 9
87 as required.
88 .Pp
89 .Ss Locking and Crash Safety
90 In all cases, it is important that exclusive
91 .Xr vnode 9
92 locks be held to prevent concurrent access when a MAC label may not yet be
93 initialized.
94 It is also important that operations are ordered so that a system crash does
95 not leave a file improperly labeled.
96 For example, the extended attribute for a newly created file must be written
97 to disk before the file is linked by its parent directory, so that there is
98 no opportunity for a crash to lead to an unlabeled file.
99 .Sh LOCKS
100 The vnode will be locked on entry and should remain locked on return.
101 .Sh RETURN VALUES
102 If the MAC label is successfully set, then zero is returned.
103 Otherwise, an appropriate error code is returned.
104 .Sh ERRORS
105 .Bl -tag -width Er
106 .It Bq Er EOPNOTSUPP
107 The file system does not support
108 .Fn VOP_SETLABEL .
109 .It Bq Er ENOSPC
110 The file system is out of space.
111 .It Bq Er EROFS
112 The file system is read-only.
113 .El
114 .Pp
115 Depending on the underlying implementation of
116 .Fn VOP_SETLABEL ,
117 other errors may also be possible.
118 .Sh SEE ALSO
119 .Xr VOP_CLOSEEXTATTR 9 ,
120 .Xr VOP_OPENEXTATTR 9 ,
121 .Xr VOP_READEXTATTR 9 ,
122 .Xr VOP_WRITEXTATTR 9 ,
123 .Xr mac 9 ,
124 .Xr mount 9 ,
125 .Xr vnode 9 ,
126 .Sh AUTHORS
127 This manual page was written by
128 .An Robert Watson .