docs-xml/manpages/vfs_preopen.8.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <refentry id="vfs_preopen.8">
   4
   5 <refmeta>
   6         <refentrytitle>vfs_preopen</refentrytitle>
   7         <manvolnum>8</manvolnum>
   8         <refmiscinfo class="source">Samba</refmiscinfo>
   9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
  10         <refmiscinfo class="version">&doc.version;</refmiscinfo>
  11 </refmeta>
  12
  13 <refnamediv>
  14         <refname>vfs_preopen</refname>
  15         <refpurpose>Hide read latencies for applications reading numbered files</refpurpose>
  16 </refnamediv>
  17
  18 <refsynopsisdiv>
  19         <cmdsynopsis>
  20                 <command>vfs objects = preopen</command>
  21         </cmdsynopsis>
  22 </refsynopsisdiv>
  23
  24 <refsect1>
  25         <title>DESCRIPTION</title>
  26
  27         <para>This VFS module is part of the
  28         <citerefentry><refentrytitle>samba</refentrytitle>
  29         <manvolnum>7</manvolnum></citerefentry> suite.</para>
  30
  31         <para>This module assists applications that want to read numbered
  32         files in sequence with very strict latency requirements. One area
  33         where this happens in video streaming applications that want to read
  34         one file per frame.</para>
  35
  36         <para>When you use this module, a number of helper processes is
  37         started that speculatively open files and read a number of bytes to
  38         prime the file system cache, so that later on when the real
  39         application's request comes along, no disk access is necessary.</para>
  40
  41         <para>This module is stackable.</para>
  42
  43 </refsect1>
  44
  45
  46 <refsect1>
  47         <title>OPTIONS</title>
  48
  49         <variablelist>
  50
  51                 <varlistentry>
  52                 <term>preopen:posix-basic-regex = BOOL (default: no)</term>
  53                 <listitem>
  54                 <para>
  55                 <command>preopen:posix-basic-regex = yes</command> changes
  56                 the meaning of the <command>preopen:names</command> option.
  57                 Further details are described there.
  58                 </para>
  59                 </listitem>
  60                 </varlistentry>
  61
  62                 <varlistentry>
  63                 <term>preopen:names = /pattern1/pattern2/</term>
  64                 <listitem>
  65                 <para>
  66                 preopen:names specifies the file name pattern(s) which should
  67                 trigger the preopen helpers to do their work. We assume that
  68                 the files are numbered incrementally. So if your file names
  69                 are numbered FRAME00000.frm FRAME00001.frm and so on you would
  70                 list them as <command>preopen:names=/FRAME*.frm/</command>.
  71                 The default algorithm uses the first (at least 3) digits it finds
  72                 in order to calculate the name of the next frames.
  73                 </para>
  74
  75                 <para><command>preopen:posix-basic-regex = yes</command> changes
  76                 the meaning of the <command>preopen:names</command> option.
  77                 It means 'POSIX Basic Regular Expression' strings are used
  78                 as patterns. The key is each pattern requires exactly one
  79                 'subexpression' starting with '\(' and ending with '\)' in
  80                 order to specify the position of the digits representing
  81                 the incrementing frame numbers. Given a file names like
  82                 Movie7599Frame0v1234.txt, Movie7599Frame1v1234.txt, Movie7599Frame2v1234.txt
  83                 up to Movie7599Frame9v1234.txt you can use <command>preopen:names = /.*Frame\([0-9]\).*\.txt/</command>
  84                 in order to match just a single digits, this might not be a real world example,
  85                 but it shows the flexibility that is possible here.
  86                 </para>
  87
  88                 </listitem>
  89                 </varlistentry>
  90
  91                 <varlistentry>
  92                 <term>preopen:num_bytes = BYTES</term>
  93                 <listitem>
  94                 <para>
  95                 Specifies the number of bytes the helpers should speculatively
  96                 read, defaults to 1.
  97                 </para>
  98                 </listitem>
  99                 </varlistentry>
 100
 101                 <varlistentry>
 102                 <term>preopen:helpers = NUM-PROCS</term>
 103                 <listitem>
 104                 <para>
 105                 Number of forked helper processes, defaults to 1.
 106                 </para>
 107                 </listitem>
 108                 </varlistentry>
 109
 110                 <varlistentry>
 111                 <term>preopen:queuelen = NUM-FILES</term>
 112                 <listitem>
 113                 <para>
 114                 Number of files that should be speculatively opened. Defaults
 115                 to the 10 subsequent files.
 116                 </para>
 117                 </listitem>
 118                 </varlistentry>
 119
 120                 <varlistentry>
 121                 <term>preopen:nomatch_log_level = LOGLEVEL</term>
 122                 <listitem>
 123                 <para>
 124                 In order to debug or audit the usage of the preopen logic
 125                 you can use this option to specify at what log level details
 126                 about filenames not matching any pattern from '<command>preopen:names</command>'
 127                 are logged.
 128                 </para>
 129                 <para>
 130                 Defaults to the log level 5.
 131                 See also <citerefentry><refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 132                 in the '<smbconfoption name="log level"/>' section
 133                 for special handling of the 'preopen' debug class.
 134                 </para>
 135                 </listitem>
 136                 </varlistentry>
 137
 138                 <varlistentry>
 139                 <term>preopen:match_log_level = LOGLEVEL</term>
 140                 <listitem>
 141                 <para>
 142                 In order to debug or audit the usage of the preopen logic
 143                 you can use this option to specify at what log level details
 144                 about filenames actually matching a pattern from '<command>preopen:names</command>'
 145                 are logged.
 146                 </para>
 147                 <para>
 148                 See also '<command>preopen:founddigits_log_level</command>' and '<command>preopen:push_log_level</command>'.
 149                 </para>
 150                 <para>
 151                 Defaults to the log level 5.
 152                 See also <citerefentry><refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 153                 in the '<smbconfoption name="log level"/>' section
 154                 for special handling of the 'preopen' debug class.
 155                 </para>
 156                 </listitem>
 157                 </varlistentry>
 158
 159                 <varlistentry>
 160                 <term>preopen:nodigits_log_level = LOGLEVEL</term>
 161                 <listitem>
 162                 <para>
 163                 In order to debug or audit problems with the preopen configuration
 164                 you can use this option to specify at what log level details
 165                 about filenames actually matching a pattern from '<command>preopen:names</command>',
 166                 but at the same time don't contain the expected digits, are logged.
 167                 This is typically something the administrator wants to notice and
 168                 adjust the configuration in order to define more precisely where to
 169                 find the digits in the filename.
 170                 </para>
 171                 <para>
 172                 Defaults to the log level 1.
 173                 See also <citerefentry><refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 174                 in the '<smbconfoption name="log level"/>' section
 175                 for special handling of the 'preopen' debug class.
 176                 </para>
 177                 </listitem>
 178                 </varlistentry>
 179
 180                 <varlistentry>
 181                 <term>preopen:founddigits_log_level = LOGLEVEL</term>
 182                 <listitem>
 183                 <para>
 184                 In order to debug or audit the usage of the preopen logic
 185                 you can use this option to specify at what log level details
 186                 about filenames actually matching a pattern from '<command>preopen:names</command>',
 187                 and at the same time having valid expected digits, are logged. This means enough information is available
 188                 in order to queue preopens.
 189                 </para>
 190                 <para>
 191                 Defaults to the log level 3.
 192                 See also <citerefentry><refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 193                 in the '<smbconfoption name="log level"/>' section
 194                 for special handling of the 'preopen' debug class.
 195                 </para>
 196                 </listitem>
 197                 </varlistentry>
 198
 199                 <varlistentry>
 200                 <term>preopen:reset_log_level = LOGLEVEL</term>
 201                 <listitem>
 202                 <para>
 203                 If a matching filename belongs to a different pattern from '<command>preopen:names</command>',
 204                 a different parent directory or differs in a significant way from the last filename
 205                 that was found before, the module needs to reset it's internal queue state.
 206                 This means that no more preopens will be pushed to helper processes belonging to the
 207                 former queue state. In order to debug or audit such queue resets you can use this option to specify at what
 208                 log level details are logged.
 209                 </para>
 210                 <para>
 211                 Defaults to the log level 5.
 212                 See also <citerefentry><refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 213                 in the '<smbconfoption name="log level"/>' section
 214                 for special handling of the 'preopen' debug class.
 215                 </para>
 216                 </listitem>
 217                 </varlistentry>
 218
 219                 <varlistentry>
 220                 <term>preopen:push_log_level = LOGLEVEL</term>
 221                 <listitem>
 222                 <para>
 223                 In order to debug or audit the usage of the preopen logic
 224                 you can use this option to specify at what log level details
 225                 about filenames actually pushed to preopen helper processes are logged.
 226                 This means they will actually be preopened soon.
 227                 </para>
 228                 <para>
 229                 Defaults to the log level 3.
 230                 See also <citerefentry><refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 231                 in the '<smbconfoption name="log level"/>' section
 232                 for special handling of the 'preopen' debug class.
 233                 </para>
 234                 </listitem>
 235                 </varlistentry>
 236
 237                 <varlistentry>
 238                 <term>preopen:queue_log_level = LOGLEVEL</term>
 239                 <listitem>
 240                 <para>
 241                 In order to debug details about internal queue processing
 242                 you can use this option to specify at what log level the details are logged.
 243                 </para>
 244                 <para>
 245                 Defaults to the log level 10.
 246                 See also <citerefentry><refentrytitle>smb.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 247                 in the '<smbconfoption name="log level"/>' section
 248                 for special handling of the 'preopen' debug class.
 249                 </para>
 250                 </listitem>
 251                 </varlistentry>
 252
 253         </variablelist>
 254 </refsect1>
 255
 256 <refsect1>
 257         <title>VERSION</title>
 258         <para>This man page is part of version &doc.version; of the Samba suite.
 259         </para>
 260 </refsect1>
 261
 262 <refsect1>
 263         <title>AUTHOR</title>
 264
 265         <para>The original Samba software and related utilities
 266         were created by Andrew Tridgell. Samba is now developed
 267         by the Samba Team as an Open Source project similar
 268         to the way the Linux kernel is developed.</para>
 269
 270         <para>The PREOPEN VFS module was created with contributions from
 271         Volker Lendecke and the developers at IBM.
 272         </para>
 273 </refsect1>
 274
 275 </refentry>