usr/src/man/man1m/cfsadmin.1m

   1 '\" te
   2 .\"  Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH CFSADMIN 1M "Feb 21, 2004"
   7 .SH NAME
   8 cfsadmin \- administer disk space used for caching file systems with the Cache
   9 File-System (CacheFS)
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcfsadmin\fR \fB-c\fR [\fB-o\fR \fIcacheFS-parameters\fR] \fIcache_directory\fR
  14 .fi
  15
  16 .LP
  17 .nf
  18 \fBcfsadmin\fR \fB-d\fR {\fIcache_ID\fR | all} \fIcache_directory\fR
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBcfsadmin\fR \fB-l\fR \fIcache_directory\fR
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBcfsadmin\fR \fB-s\fR {\fImntpt1 ....\fR} | all
  29 .fi
  30
  31 .LP
  32 .nf
  33 \fBcfsadmin\fR \fB-u\fR [\fB-o\fR \fIcacheFS-parameters\fR] \fIcache_directory\fR
  34 .fi
  35
  36 .SH DESCRIPTION
  37 .sp
  38 .LP
  39 The \fBcfsadmin\fR command provides the following functions:
  40 .RS +4
  41 .TP
  42 .ie t \(bu
  43 .el o
  44 cache creation
  45 .RE
  46 .RS +4
  47 .TP
  48 .ie t \(bu
  49 .el o
  50 deletion of cached file systems
  51 .RE
  52 .RS +4
  53 .TP
  54 .ie t \(bu
  55 .el o
  56 listing of cache contents and statistics
  57 .RE
  58 .RS +4
  59 .TP
  60 .ie t \(bu
  61 .el o
  62 resource parameter adjustment when the file system is unmounted.
  63 .RE
  64 .sp
  65 .LP
  66 You must always supply an option for \fBcfsadmin\fR. For each form of the
  67 command except \fB-s\fR, you must specify a cache directory, that is, the
  68 directory under which the cache is actually stored. A path name in the front
  69 file system identifies the cache directory. For the \fB-s\fR form of the
  70 command, you must specify a mount point.
  71 .sp
  72 .LP
  73 You can specify a cache ID when you mount a file system with CacheFS, or you
  74 can let the system generate one for you. The \fB-l\fR option includes the cache
  75 ID in its listing of information. You must know the cache ID to delete a cached
  76 file system.
  77 .SH OPTIONS
  78 .sp
  79 .LP
  80 The following options are supported:
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fB-c\fR [ \fB-o\fR \fIcacheFS-parameters\fR ] \fIcache_directory\fR\fR
  85 .ad
  86 .sp .6
  87 .RS 4n
  88 Create a cache under the directory specified by \fIcache_directory\fR. This
  89 directory must not exist prior to cache creation.
  90 .RE
  91
  92 .sp
  93 .ne 2
  94 .na
  95 \fB\fB-d\fR { \fIcache_ID\fR | all } \fIcache_directory\fR\fR
  96 .ad
  97 .sp .6
  98 .RS 4n
  99 Remove the file system whose cache ID you specify and release its resources, or
 100 remove all file systems in the cache by specifying \fBall\fR. After deleting a
 101 file system from the cache, you must run the \fBfsck_cachefs\fR(1M) command to
 102 correct the resource counts for the cache.
 103 .sp
 104 As indicated by the syntax above, you must supply either a \fIcache_ID\fR or
 105 \fBall\fR, in addition to \fIcache_directory\fR.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB-l\fR \fIcache_directory\fR\fR
 112 .ad
 113 .sp .6
 114 .RS 4n
 115 List file systems stored in the specified cache, as well as statistics about
 116 them. Each cached file system is listed by cache ID. The statistics document
 117 resource utilization and cache resource parameters.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fB-s\fR { \fImntpt1\fR ... } | all\fR
 124 .ad
 125 .sp .6
 126 .RS 4n
 127 Request a consistency check on the specified file system (or all \fBcachefs\fR
 128 mounted file systems). The \fB-s\fR option only works if the cache file system
 129 was mounted with \fBdemandconst\fR enabled (see \fBmount_cachefs\fR(1M)). Each
 130 file in the specified cache file system is checked for consistency with its
 131 corresponding file in the back file system. Note that the consistency check is
 132 performed file by file as files are accessed. If no files are accessed, no
 133 checks are performed. Use of this option does not result in a sudden "storm" of
 134 consistency checks.
 135 .sp
 136 As indicated by the syntax above, you must supply one or more mount points, or
 137 \fBall\fR.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fB-u\fR [ \fB-o\fR \fIcacheFS-parameters\fR ] \fIcache_directory\fR\fR
 144 .ad
 145 .sp .6
 146 .RS 4n
 147 Update resource parameters of the specified cache directory. Parameter values
 148 can only be increased. To decrease the values, you must remove the cache and
 149 recreate it. All file systems in the cache directory must be unmounted when you
 150 use this option. Changes take effect the next time you mount any file system in
 151 the specified cache directory. The \fB-u\fR option with no \fB-o\fR option sets
 152 all parameters to their default values.
 153 .RE
 154
 155 .SS "CacheFS Resource Parameters"
 156 .sp
 157 .LP
 158 You can specify the following CacheFS resource parameters as arguments to the
 159 \fB-o\fR option. Separate multiple parameters with commas.
 160 .sp
 161 .ne 2
 162 .na
 163 \fB\fBmaxblocks=\fR\fIn\fR\fR
 164 .ad
 165 .RS 18n
 166 Maximum amount of storage space that CacheFS can use, expressed as a percentage
 167 of the total number of blocks in the front file system. If CacheFS does not
 168 have exclusive use of the front file system, there is no guarantee that all the
 169 space the \fBmaxblocks\fR parameter allows is available. The default is
 170 \fB90\fR.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBminblocks=\fR\fIn\fR\fR
 177 .ad
 178 .RS 18n
 179 Minimum amount of storage space, expressed as a percentage of the total number
 180 of blocks in the front file system, that CacheFS is always allowed to use
 181 without limitation by its internal control mechanisms. If CacheFS does not have
 182 exclusive use of the front file system, there is no guarantee that all the
 183 space the \fBminblocks\fR parameter attempts to reserve is available. The
 184 default is \fB0\fR.
 185 .RE
 186
 187 .sp
 188 .ne 2
 189 .na
 190 \fB\fBthreshblocks=\fR\fIn\fR\fR
 191 .ad
 192 .RS 18n
 193 A percentage of the total blocks in the front file system beyond which CacheFS
 194 cannot claim resources once its block usage has reached the level specified by
 195 \fBminblocks\fR. The default is \fB85\fR.
 196 .RE
 197
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fBmaxfiles=\fR\fIn\fR\fR
 202 .ad
 203 .RS 18n
 204 Maximum number of files that CacheFS can use, expressed as a percentage of the
 205 total number of inodes in the front file system. If CacheFS does not have
 206 exclusive use of the front file system, there is no guarantee that all the
 207 inodes the \fBmaxfiles\fR parameter allows is available. The default is
 208 \fB90\fR.
 209 .RE
 210
 211 .sp
 212 .ne 2
 213 .na
 214 \fB\fBminfiles=\fR\fIn\fR\fR
 215 .ad
 216 .RS 18n
 217 Minimum number of files, expressed as a percentage of the total number of
 218 inodes in the front file system, that CacheFS is always allowed to use without
 219 limitation by its internal control mechanisms. If CacheFS does not have
 220 exclusive use of the front file system, there is no guarantee that all the
 221 inodes the \fBminfiles\fR parameter attempts to reserve is available. The
 222 default is \fB0\fR.
 223 .RE
 224
 225 .sp
 226 .ne 2
 227 .na
 228 \fB\fBthreshfiles=\fR\fIn\fR\fR
 229 .ad
 230 .RS 18n
 231 A percentage of the total inodes in the front file system beyond which CacheFS
 232 cannot claim inodes once its usage has reached the level specified by
 233 \fBminfiles\fR. The default is \fB85\fR.
 234 .RE
 235
 236 .sp
 237 .ne 2
 238 .na
 239 \fB\fBmaxfilesize=\fR\fIn\fR\fR
 240 .ad
 241 .RS 18n
 242 Largest file size, expressed in megabytes, that CacheFS is allowed to cache.
 243 The default is \fB3\fR. You cannot decrease the block or inode allotment for a
 244 cache. To decrease the size of a cache, you must remove it and create it again
 245 with different parameters.
 246 .sp
 247 Currently \fBmaxfilesize\fR is ignored by \fBcachefs\fR, therefore, setting it
 248 has no effect.
 249 .RE
 250
 251 .SH OPERANDS
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fIcache_directory\fR\fR
 256 .ad
 257 .RS 19n
 258 The directory under which the cache is actually stored.
 259 .RE
 260
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fImntpt1\fR\fR
 265 .ad
 266 .RS 19n
 267 The directory where the CacheFS is mounted.
 268 .RE
 269
 270 .SH USAGE
 271 .sp
 272 .LP
 273 See \fBlargefile\fR(5) for the description of the behavior of \fBcfsadmin\fR
 274 when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
 275 .SH EXAMPLES
 276 .LP
 277 \fBExample 1 \fRCreating a Cache Directory
 278 .sp
 279 .LP
 280 The following example creates a cache directory named \fB/cache\fR:
 281
 282 .sp
 283 .in +2
 284 .nf
 285 example# cfsadmin -c /cache
 286 .fi
 287 .in -2
 288 .sp
 289
 290 .LP
 291 \fBExample 2 \fRCreating a Cache
 292 .sp
 293 .LP
 294 The following example creates a cache named \fB/cache1\fR that can claim a
 295 maximum of 60 percent of the blocks in the front file system, can use 40
 296 percent of the front file system blocks without interference by CacheFS
 297 internal control mechanisms, and has a threshold value of 50 percent. The
 298 threshold value indicates that after CacheFS reaches its guaranteed minimum, it
 299 cannot claim more space if 50 percent of the blocks in the front file system
 300 are already used.
 301
 302 .sp
 303 .in +2
 304 .nf
 305 example# cfsadmin \fB-c\fR \fB-o\fR maxblocks=60,minblocks=40,threshblocks=50 /cache1
 306 .fi
 307 .in -2
 308 .sp
 309
 310 .LP
 311 \fBExample 3 \fRChanging the \fBmaxfilesize\fR Parameter
 312 .sp
 313 .LP
 314 The following example changes the \fBmaxfilesize\fR parameter for the cache
 315 directory \fB/cache2\fR to 2 megabytes:
 316
 317 .sp
 318 .in +2
 319 .nf
 320 example# cfsadmin \fB-u\fR \fB-o\fR maxfilesize=2 /cache2
 321 .fi
 322 .in -2
 323 .sp
 324
 325 .LP
 326 \fBExample 4 \fRListing the Contents of a Cache Directory
 327 .sp
 328 .LP
 329 The following example lists the contents of a cache directory named
 330 \fB/cache3\fR and provides statistics about resource utilization:
 331
 332 .sp
 333 .in +2
 334 .nf
 335 example# cfsadmin \fB-l\fR /cache3
 336 .fi
 337 .in -2
 338 .sp
 339
 340 .LP
 341 \fBExample 5 \fRRemoving a Cached File System
 342 .sp
 343 .LP
 344 The following example removes the cached file system with cache ID \fB23\fR
 345 from the cache directory \fB/cache3\fR and frees its resources (the cache ID is
 346 part of the information returned by \fBcfsadmin \fR\fB-l\fR):
 347
 348 .sp
 349 .in +2
 350 .nf
 351 example# cfsadmin \fB-d\fR 23 /cache3
 352 .fi
 353 .in -2
 354 .sp
 355
 356 .LP
 357 \fBExample 6 \fRRemoving All Cached File Systems
 358 .sp
 359 .LP
 360 The following example removes all cached file systems from the cache directory
 361 \fB/cache3\fR:
 362
 363 .sp
 364 .in +2
 365 .nf
 366 example# cfsadmin \fB-d\fR all /cache3
 367 .fi
 368 .in -2
 369 .sp
 370
 371 .LP
 372 \fBExample 7 \fRChecking for Consistency in File Systems
 373 .sp
 374 .LP
 375 The following example checks for consistency all file systems mounted with
 376 \fBdemandconst\fR enabled. No errors are reported if no \fBdemandconst\fR file
 377 systems were found.
 378
 379 .sp
 380 .in +2
 381 .nf
 382 example# \fBcfsadmin\fR \fB-s\fR \fBall\fR
 383 .fi
 384 .in -2
 385 .sp
 386
 387 .SH EXIT STATUS
 388 .sp
 389 .LP
 390 The following exit values are returned:
 391 .sp
 392 .ne 2
 393 .na
 394 \fB\fB0\fR\fR
 395 .ad
 396 .RS 5n
 397 Successful completion.
 398 .RE
 399
 400 .sp
 401 .ne 2
 402 .na
 403 \fB\fB1\fR\fR
 404 .ad
 405 .RS 5n
 406 An error occurred.
 407 .RE
 408
 409 .SH SEE ALSO
 410 .sp
 411 .LP
 412 \fBcachefslog\fR(1M), \fBcachefsstat\fR(1M), \fBcachefswssize\fR(1M),
 413 \fBfsck_cachefs\fR(1M), \fBmount_cachefs\fR(1M), \fBattributes\fR(5),
 414 \fBlargefile\fR(5)