doc/man-pages/pod1/fs_bypassthreshold.pod

   1 =head1 NAME
   2
   3 fs_bypassthreshold - get/set Cache Bypass file size threshold
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<fs bypassthreshold> S<<< [B<-size> <I<file size>>] >>> [B<-help>]
  11
  12 B<fs bypassthresh> S<<< [B<-s> <I<file size>>] >>> [B<-h>]
  13
  14 =for html
  15 </div>
  16
  17 =head1 DESCRIPTION
  18
  19 The B<fs bypassthreshold> command either changes the AFS client Cache
  20 Bypass file size threshold, or reports the current threshold. Normally,
  21 when an application tries to read data via the OpenAFS client, the client
  22 will fetch the required data from the fileserver, store the results in
  23 the local cache, and then serve the application request from the local
  24 cache. When the Cache Bypass feature is enabled, certain files will be
  25 read directly from the network, and the data will not be saved to the
  26 local cache. In some scenarios, this can provide a significant
  27 performance improvement, especially if the data is only read once.
  28
  29 Currently, the only way to specify which files should bypass the cache
  30 and which files should not, is by file size. In the future, different
  31 mechanisms may exist for specifying which files should bypass the local
  32 cache and which should not.
  33
  34 If B<-size> is not specified, B<fs bypassthreshold> just reports the
  35 current threshold and exits.
  36
  37 =head1 CAUTIONS
  38
  39 Cache Bypass is still considered an experimental feature. Even in stable
  40 releases of OpenAFS, it is not considered as stable as the rest of OpenAFS.
  41
  42 =head1 OPTIONS
  43
  44 =over 4
  45
  46 =item B<-size> <I<file size>>
  47
  48 Specifies how large a file must be in order to enable Cache Bypass mode.
  49 If a file is larger than the specified file size (in bytes), reading from
  50 that file will bypass the local cache and be read directly from the
  51 network. A file size of -1 indicates that Cache Bypass should be disabled
  52 complete, so no files will enable Cache Bypass mode, no matter how large
  53 they are.
  54
  55 By default, Cache Bypass is disabled.
  56
  57 =item B<-help>
  58
  59 Prints the online help for this command. All other valid options are
  60 ignored.
  61
  62 =back
  63
  64 =head1 OUTPUT
  65
  66 The output format is identical whether or not B<-size> was specified. If
  67 B<-size> is specified, the bypass threshold is changed, and the output
  68 represents the new, changed, threshold. Otherwise the output represents
  69 the current threshold.
  70
  71 =head1 EXAMPLES
  72
  73 The following example turns on Cache Bypass with a threshold of 4KiB:
  74
  75    % fs bypassthreshold 4096
  76    Cache bypass threshold 4096
  77
  78 The following example disables Cache Bypass:
  79
  80    % fs bypassthreshold -1
  81    Cache bypass threshold -1 (disabled)
  82
  83 The following example examines the current Cache Bypass threshold:
  84
  85    % fs bypassthreshold
  86    Cache bypass threshold 4096
  87
  88 =head1 PRIVILEGE REQUIRED
  89
  90 To set the bypass threshold, the issuer must be logged in as the local
  91 superuser C<root>. Otherwise, no privilege is required.
  92
  93 =head1 COPYRIGHT
  94
  95 Copyright 2012 Sine Nomine Associates
  96
  97 This documentation is covered by the BSD License as written in the
  98 doc/LICENSE file. This man page was written by Andrew Deason for
  99 OpenAFS.