path: root/usr/src/man/man1m/cfsadmin.1m

'\" te
.\"  Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH CFSADMIN 1M "Feb 21, 2004"
.SH NAME
cfsadmin \- administer disk space used for caching file systems with the Cache
File-System (CacheFS)
.SH SYNOPSIS
.LP
.nf
\fBcfsadmin\fR \fB-c\fR [\fB-o\fR \fIcacheFS-parameters\fR] \fIcache_directory\fR
.fi

.LP
.nf
\fBcfsadmin\fR \fB-d\fR {\fIcache_ID\fR | all} \fIcache_directory\fR
.fi

.LP
.nf
\fBcfsadmin\fR \fB-l\fR \fIcache_directory\fR
.fi

.LP
.nf
\fBcfsadmin\fR \fB-s\fR {\fImntpt1 ....\fR} | all
.fi

.LP
.nf
\fBcfsadmin\fR \fB-u\fR [\fB-o\fR \fIcacheFS-parameters\fR] \fIcache_directory\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBcfsadmin\fR command provides the following functions:
.RS +4
.TP
.ie t \(bu
.el o
cache creation
.RE
.RS +4
.TP
.ie t \(bu
.el o
deletion of cached file systems
.RE
.RS +4
.TP
.ie t \(bu
.el o
listing of cache contents and statistics
.RE
.RS +4
.TP
.ie t \(bu
.el o
resource parameter adjustment when the file system is unmounted.
.RE
.sp
.LP
You must always supply an option for \fBcfsadmin\fR. For each form of the
command except \fB-s\fR, you must specify a cache directory, that is, the
directory under which the cache is actually stored. A path name in the front
file system identifies the cache directory. For the \fB-s\fR form of the
command, you must specify a mount point.
.sp
.LP
You can specify a cache ID when you mount a file system with CacheFS, or you
can let the system generate one for you. The \fB-l\fR option includes the cache
ID in its listing of information. You must know the cache ID to delete a cached
file system.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR [ \fB-o\fR \fIcacheFS-parameters\fR ] \fIcache_directory\fR\fR
.ad
.sp .6
.RS 4n
Create a cache under the directory specified by \fIcache_directory\fR. This
directory must not exist prior to cache creation.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR { \fIcache_ID\fR | all } \fIcache_directory\fR\fR
.ad
.sp .6
.RS 4n
Remove the file system whose cache ID you specify and release its resources, or
remove all file systems in the cache by specifying \fBall\fR. After deleting a
file system from the cache, you must run the \fBfsck_cachefs\fR(1M) command to
correct the resource counts for the cache.
.sp
As indicated by the syntax above, you must supply either a \fIcache_ID\fR or
\fBall\fR, in addition to \fIcache_directory\fR.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIcache_directory\fR\fR
.ad
.sp .6
.RS 4n
List file systems stored in the specified cache, as well as statistics about
them. Each cached file system is listed by cache ID. The statistics document
resource utilization and cache resource parameters.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR { \fImntpt1\fR ... } | all\fR
.ad
.sp .6
.RS 4n
Request a consistency check on the specified file system (or all \fBcachefs\fR
mounted file systems). The \fB-s\fR option only works if the cache file system
was mounted with \fBdemandconst\fR enabled (see \fBmount_cachefs\fR(1M)). Each
file in the specified cache file system is checked for consistency with its
corresponding file in the back file system. Note that the consistency check is
performed file by file as files are accessed. If no files are accessed, no
checks are performed. Use of this option does not result in a sudden "storm" of
consistency checks.
.sp
As indicated by the syntax above, you must supply one or more mount points, or
\fBall\fR.
.RE

.sp
.ne 2
.na
\fB\fB-u\fR [ \fB-o\fR \fIcacheFS-parameters\fR ] \fIcache_directory\fR\fR
.ad
.sp .6
.RS 4n
Update resource parameters of the specified cache directory. Parameter values
can only be increased. To decrease the values, you must remove the cache and
recreate it. All file systems in the cache directory must be unmounted when you
use this option. Changes take effect the next time you mount any file system in
the specified cache directory. The \fB-u\fR option with no \fB-o\fR option sets
all parameters to their default values.
.RE

.SS "CacheFS Resource Parameters"
.sp
.LP
You can specify the following CacheFS resource parameters as arguments to the
\fB-o\fR option. Separate multiple parameters with commas.
.sp
.ne 2
.na
\fB\fBmaxblocks=\fR\fIn\fR\fR
.ad
.RS 18n
Maximum amount of storage space that CacheFS can use, expressed as a percentage
of the total number of blocks in the front file system. If CacheFS does not
have exclusive use of the front file system, there is no guarantee that all the
space the \fBmaxblocks\fR parameter allows is available. The default is
\fB90\fR.
.RE

.sp
.ne 2
.na
\fB\fBminblocks=\fR\fIn\fR\fR
.ad
.RS 18n
Minimum amount of storage space, expressed as a percentage of the total number
of blocks in the front file system, that CacheFS is always allowed to use
without limitation by its internal control mechanisms. If CacheFS does not have
exclusive use of the front file system, there is no guarantee that all the
space the \fBminblocks\fR parameter attempts to reserve is available. The
default is \fB0\fR.
.RE

.sp
.ne 2
.na
\fB\fBthreshblocks=\fR\fIn\fR\fR
.ad
.RS 18n
A percentage of the total blocks in the front file system beyond which CacheFS
cannot claim resources once its block usage has reached the level specified by
\fBminblocks\fR. The default is \fB85\fR.
.RE

.sp
.ne 2
.na
\fB\fBmaxfiles=\fR\fIn\fR\fR
.ad
.RS 18n
Maximum number of files that CacheFS can use, expressed as a percentage of the
total number of inodes in the front file system. If CacheFS does not have
exclusive use of the front file system, there is no guarantee that all the
inodes the \fBmaxfiles\fR parameter allows is available. The default is
\fB90\fR.
.RE

.sp
.ne 2
.na
\fB\fBminfiles=\fR\fIn\fR\fR
.ad
.RS 18n
Minimum number of files, expressed as a percentage of the total number of
inodes in the front file system, that CacheFS is always allowed to use without
limitation by its internal control mechanisms. If CacheFS does not have
exclusive use of the front file system, there is no guarantee that all the
inodes the \fBminfiles\fR parameter attempts to reserve is available. The
default is \fB0\fR.
.RE

.sp
.ne 2
.na
\fB\fBthreshfiles=\fR\fIn\fR\fR
.ad
.RS 18n
A percentage of the total inodes in the front file system beyond which CacheFS
cannot claim inodes once its usage has reached the level specified by
\fBminfiles\fR. The default is \fB85\fR.
.RE

.sp
.ne 2
.na
\fB\fBmaxfilesize=\fR\fIn\fR\fR
.ad
.RS 18n
Largest file size, expressed in megabytes, that CacheFS is allowed to cache.
The default is \fB3\fR. You cannot decrease the block or inode allotment for a
cache. To decrease the size of a cache, you must remove it and create it again
with different parameters.
.sp
Currently \fBmaxfilesize\fR is ignored by \fBcachefs\fR, therefore, setting it
has no effect.
.RE

.SH OPERANDS
.sp
.ne 2
.na
\fB\fIcache_directory\fR\fR
.ad
.RS 19n
The directory under which the cache is actually stored.
.RE

.sp
.ne 2
.na
\fB\fImntpt1\fR\fR
.ad
.RS 19n
The directory where the CacheFS is mounted.
.RE

.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBcfsadmin\fR
when encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
.SH EXAMPLES
.LP
\fBExample 1 \fRCreating a Cache Directory
.sp
.LP
The following example creates a cache directory named \fB/cache\fR:

.sp
.in +2
.nf
example# cfsadmin -c /cache
.fi
.in -2
.sp

.LP
\fBExample 2 \fRCreating a Cache
.sp
.LP
The following example creates a cache named \fB/cache1\fR that can claim a
maximum of 60 percent of the blocks in the front file system, can use 40
percent of the front file system blocks without interference by CacheFS
internal control mechanisms, and has a threshold value of 50 percent. The
threshold value indicates that after CacheFS reaches its guaranteed minimum, it
cannot claim more space if 50 percent of the blocks in the front file system
are already used.

.sp
.in +2
.nf
example# cfsadmin \fB-c\fR \fB-o\fR maxblocks=60,minblocks=40,threshblocks=50 /cache1
.fi
.in -2
.sp

.LP
\fBExample 3 \fRChanging the \fBmaxfilesize\fR Parameter
.sp
.LP
The following example changes the \fBmaxfilesize\fR parameter for the cache
directory \fB/cache2\fR to 2 megabytes:

.sp
.in +2
.nf
example# cfsadmin \fB-u\fR \fB-o\fR maxfilesize=2 /cache2
.fi
.in -2
.sp

.LP
\fBExample 4 \fRListing the Contents of a Cache Directory
.sp
.LP
The following example lists the contents of a cache directory named
\fB/cache3\fR and provides statistics about resource utilization:

.sp
.in +2
.nf
example# cfsadmin \fB-l\fR /cache3
.fi
.in -2
.sp

.LP
\fBExample 5 \fRRemoving a Cached File System
.sp
.LP
The following example removes the cached file system with cache ID \fB23\fR
from the cache directory \fB/cache3\fR and frees its resources (the cache ID is
part of the information returned by \fBcfsadmin \fR\fB-l\fR):

.sp
.in +2
.nf
example# cfsadmin \fB-d\fR 23 /cache3
.fi
.in -2
.sp

.LP
\fBExample 6 \fRRemoving All Cached File Systems
.sp
.LP
The following example removes all cached file systems from the cache directory
\fB/cache3\fR:

.sp
.in +2
.nf
example# cfsadmin \fB-d\fR all /cache3
.fi
.in -2
.sp

.LP
\fBExample 7 \fRChecking for Consistency in File Systems
.sp
.LP
The following example checks for consistency all file systems mounted with
\fBdemandconst\fR enabled. No errors are reported if no \fBdemandconst\fR file
systems were found.

.sp
.in +2
.nf
example# \fBcfsadmin\fR \fB-s\fR \fBall\fR
.fi
.in -2
.sp

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 5n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 5n
An error occurred.
.RE

.SH SEE ALSO
.sp
.LP
\fBcachefslog\fR(1M), \fBcachefsstat\fR(1M), \fBcachefswssize\fR(1M),
\fBfsck_cachefs\fR(1M), \fBmount_cachefs\fR(1M), \fBattributes\fR(5),
\fBlargefile\fR(5)