.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "FS_BYPASSTHRESHOLD 1"
.TH FS_BYPASSTHRESHOLD 1 2024-03-20 OpenAFS "AFS Command Reference"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
fs_bypassthreshold \- get/set Cache Bypass file size threshold
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBfs bypassthreshold\fR [\fB\-size\fR\ <\fIfile\ size\fR>] [\fB\-help\fR]
.PP
\&\fBfs bypassthresh\fR [\fB\-s\fR\ <\fIfile\ size\fR>] [\fB\-h\fR]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBfs bypassthreshold\fR command either changes the AFS client Cache
Bypass file size threshold, or reports the current threshold. Normally,
when an application tries to read data via the OpenAFS client, the client
will fetch the required data from the fileserver, store the results in
the local cache, and then serve the application request from the local
cache. When the Cache Bypass feature is enabled, certain files will be
read directly from the network, and the data will not be saved to the
local cache. In some scenarios, this can provide a significant
performance improvement, especially if the data is only read once.
.PP
Currently, the only way to specify which files should bypass the cache
and which files should not, is by file size. In the future, different
mechanisms may exist for specifying which files should bypass the local
cache and which should not.
.PP
If \fB\-size\fR is not specified, \fBfs bypassthreshold\fR just reports the
current threshold and exits.
.SH CAUTIONS
.IX Header "CAUTIONS"
Cache Bypass is still considered an experimental feature. Even in stable
releases of OpenAFS, it is not considered as stable as the rest of OpenAFS.
.SH OPTIONS
.IX Header "OPTIONS"
.IP "\fB\-size\fR <\fIfile size\fR>" 4
.IX Item "-size <file size>"
Specifies how large a file must be in order to enable Cache Bypass mode.
If a file is larger than the specified file size (in bytes), reading from
that file will bypass the local cache and be read directly from the
network. A file size of \-1 indicates that Cache Bypass should be disabled
complete, so no files will enable Cache Bypass mode, no matter how large
they are.
.Sp
By default, Cache Bypass is disabled.
.IP \fB\-help\fR 4
.IX Item "-help"
Prints the online help for this command. All other valid options are
ignored.
.SH OUTPUT
.IX Header "OUTPUT"
The output format is identical whether or not \fB\-size\fR was specified. If
\&\fB\-size\fR is specified, the bypass threshold is changed, and the output
represents the new, changed, threshold. Otherwise the output represents
the current threshold.
.SH EXAMPLES
.IX Header "EXAMPLES"
The following example turns on Cache Bypass with a threshold of 4KiB:
.PP
.Vb 2
\&   % fs bypassthreshold 4096
\&   Cache bypass threshold 4096
.Ve
.PP
The following example disables Cache Bypass:
.PP
.Vb 2
\&   % fs bypassthreshold \-1
\&   Cache bypass threshold \-1 (disabled)
.Ve
.PP
The following example examines the current Cache Bypass threshold:
.PP
.Vb 2
\&   % fs bypassthreshold
\&   Cache bypass threshold 4096
.Ve
.SH "PRIVILEGE REQUIRED"
.IX Header "PRIVILEGE REQUIRED"
To set the bypass threshold, the issuer must be logged in as the local
superuser \f(CW\*(C`root\*(C'\fR. Otherwise, no privilege is required.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2012 Sine Nomine Associates
.PP
This documentation is covered by the BSD License as written in the
doc/LICENSE file. This man page was written by Andrew Deason for
OpenAFS.