</listitem>
</itemizedlist></para>
</sect2>
+
+
+ <sect2 id="tuning-cache-configuration">
+ <title>Tuning Cache Configuration</title>
+
+ <indexterm>
+ <primary>cache</primary>
+ <secondary>tuning</secondary>
+ </indexterm>
+
+ <indexterm>
+ <primary>performance</primary>
+ <secondary>cache</secondary>
+ </indexterm>
+
+ <para>
+ Tuning the parameters of the OpenAFS cache for optimal performance
+ is highly dependent on the behavior of applications and users on a
+ client machine. The default options may perform poorly under
+ certain conditions.
+ </para>
+
+ <para>
+ The <emphasis role="bold">xstat_cm_test</emphasis> command is
+ useful for measuring how effectively the cache is operating. The
+ following procedure may be used to aide in tuning the parameters
+ for the data cache (dcache) and the stats cache (vcache):
+ <orderedlist>
+ <listitem>
+ <para>
+ Run the following command and replace "hostname" with the hostname of the machine to be measured:
+ <programlisting>
+ <emphasis role="bold">xstat_cm_test hostname 2 -onceonly</emphasis>
+ </programlisting>
+ </para>
+ <para>
+ Take note of the following fields: dcacheHits, dcacheMisses,
+ vcacheHits, and vcacheMisses. Saving the above command
+ output to a file or filtering it using grep is advised.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Using the noted fields, compute the miss ratios for the
+ dcache and vcache using the following formulas:
+ <programlisting>
+ <emphasis role="bold">
+ dcache miss ratio = dcacheMisses / ( dcacheMisses + dcacheHits )
+ </emphasis>
+ </programlisting>
+ <programlisting>
+ <emphasis role="bold">
+ vcache miss ratio = vcacheMisses / ( vcacheMisses + vcacheHits )
+ </emphasis>
+ </programlisting>
+ As a guideline, a miss ratio of 0.05 (5 percent) or less is
+ acceptable and a miss ratio of 0.01 (1 percent) or less is
+ recommended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If your dcache miss ratio is too large, then cache
+ performance is likely to improve if the data cache is made
+ larger. If the vcache miss ratio is too large, then increase
+ the size of the stat cache using
+ the <emphasis role="bold">-stat</emphasis> parameter
+ to <emphasis role="bold">afsd</emphasis> for a Unix-based
+ client or using the Control Panel or registry interfaces on
+ Microsoft Windows-based clients. The default size of the
+ stat cache is 10,000 entries on windows platforms and 300
+ entries on Unix platforms. There may be a significant
+ performance penalty when the vcache size is much smaller
+ than the working set of commonly accessed files. On the
+ fileserver, the number of callbacks should be more than the
+ size of the vcache of any client that connects to the
+ server. If the cache is too small or there aren't enough
+ callbacks (<emphasis role="bold">-cb</emphasis>) on the
+ fileserver, then the cached entries will be discarded
+ prematurely, causing thrashing.
+ <tip>
+ <para>
+ As an example of how the wrong vcache size can degrade
+ performance, one OpenAFS site had performance issues
+ with the Apache and mod_php software on a Unix web
+ server serving web pages directly out of AFS. During
+ peak times, the load on the server would spike with an
+ excess of Apache processes. After profiling, it was
+ found that Apache and PHP made lots
+ of <emphasis role="bold">stat()</emphasis> library calls
+ and that the default vcache size of 300 was too
+ small. After some experimentation, a vcache size of
+ 50,000 was found to improve performance. This size makes
+ sense in light of that fact that the total number of
+ files in the website exceeded 350,000, including 50,000
+ PHP files. The number of callbacks configured on the
+ fileserver was 1,500,000, so the vcache size was not too
+ large.
+ </para>
+ </tip>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ After changing your configuration appropriately and
+ restarting the AFS client service, wait until enough data
+ has been collected before changing the configuration
+ further. The sum of the hits and misses should be at least
+ five times the value of the configured parameter before
+ making further adjustments. Repeat this process until the
+ desired miss ratio is achieved. Take note that the numbers
+ from the <emphasis role="bold">xstat_cm_test</emphasis>
+ command only reset when the client is restarted. If multiple
+ samples are taken, then subtract the previous measurement
+ from the current measurement to accurately measure the
+ activity that happened between the samples.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </sect2>
</sect1>
+
<sect1 id="HDRWQ406">
<title>Maintaining Knowledge of Database Server Machines</title>
<primary>setuid programs</primary>
</indexterm>
- <para>A <emphasis>setuid program</emphasis> is one whose binary file has the UNIX setuid mode bit turned on. While a setuid
- program runs, the user who initialized it assumes the local identity (UNIX UID) of the binary file's owner, and so is granted
- the permissions in the local file system that pertain to the owner. Most commonly, the issuer's assumed identity (often referred
- to as <emphasis>effective UID</emphasis>) is the local superuser <emphasis role="bold">root</emphasis>.</para>
-
- <para>AFS does not recognize effective UID: if a setuid program accesses AFS files and directories, it uses the current AFS
- identity of the user who initialized the program, not of the program's owner. Nevertheless, it can be useful to store setuid
- programs in AFS for use on more than one client machine. AFS enables a client machine's administrator to determine whether the
- local Cache Manager allows setuid programs to run or not.</para>
-
- <para>By default, the Cache Manager allows programs from its home cell to run with setuid permission, but denies setuid
- permission to programs from foreign cells. A program belongs to the same cell as the file server machine that houses the volume
- in which the file resides, as specified in the file server machine's <emphasis role="bold">/usr/afs/etc/ThisCell</emphasis>
- file. The Cache Manager determines its own home cell by reading the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file
- at initialization.</para>
-
- <para>To change a cell's setuid status with respect to the local machine, become the local superuser <emphasis
- role="bold">root</emphasis> and issue the <emphasis role="bold">fs setcell</emphasis> command. To determine a cell's current
- setuid status, use the <emphasis role="bold">fs getcellstatus</emphasis> command.</para>
-
- <para>When you issue the <emphasis role="bold">fs setcell</emphasis> command, you directly alter a cell's setuid status as
- recorded in kernel memory, so rebooting the machine is not necessary. However, nondefault settings do not persist across reboots
- of the machine unless you add the appropriate <emphasis role="bold">fs setcell</emphasis> command to the machine's AFS
- initialization file.</para>
-
- <para>Only members of the <emphasis role="bold">system:administrators</emphasis> group can turn on the setuid mode bit on an AFS
- file or directory. When the setuid mode bit is turned on, the UNIX <emphasis role="bold">ls -l</emphasis> command displays the
- third user mode bit as an <emphasis role="bold">s</emphasis> instead of an <emphasis role="bold">x</emphasis>, but for an AFS
- file or directory, the <emphasis role="bold">s</emphasis> appears only if setuid permission is enabled for the cell in which the
- file resides. <indexterm>
- <primary>fs commands</primary>
-
- <secondary>getcellstatus</secondary>
- </indexterm> <indexterm>
- <primary>commands</primary>
-
- <secondary>fs getcellstatus</secondary>
- </indexterm></para>
+ <para>A <emphasis>setuid program</emphasis> is one whose binary file
+ has the UNIX setuid mode bit turned on. While a setuid program runs,
+ the user who initialized it assumes the local identity (UNIX UID) of
+ the binary file's owner, and so is granted the permissions in the
+ local file system that pertain to the owner. Most commonly, the
+ issuer's assumed identity (often referred to as <emphasis>effective
+ UID</emphasis>) is the local superuser <emphasis
+ role="bold">root</emphasis>.</para>
+
+ <para>AFS does not recognize effective UID: if a setuid program
+ accesses AFS files and directories, it uses the current AFS identity
+ of the user who initialized the program, not of the program's
+ owner. Nevertheless, it can be useful to store setuid programs in AFS
+ for use on more than one client machine. AFS enables a client
+ machine's administrator to determine and change whether the local
+ Cache Manager allows setuid programs to run or not.</para>
+
+ <para>By default, the Cache Manager ignores all setuid permissions in
+ AFS, but this can be changed by a client machine's administrator. Each
+ cell's setuid status is set independently of other cells. To change a
+ cell's setuid status with respect to the local machine, become the
+ local superuser <emphasis role="bold">root</emphasis> and issue the
+ <emphasis role="bold">fs setcell</emphasis> command. To determine a
+ cell's current setuid status, use the <emphasis role="bold">fs
+ getcellstatus</emphasis> command.</para>
+
+ <warning>
+ <para>Enabling support for the UNIX setuid bit for AFS programs is
+ not secure with the current AFS protocol. Enabling this capability
+ is not recommended except in very restricted environments on trusted
+ networks.</para>
+ </warning>
+
+ <para>When you issue the <emphasis role="bold">fs setcell</emphasis>
+ command, you directly alter a cell's setuid status as recorded in
+ kernel memory, so rebooting the machine is not necessary. However,
+ nondefault settings do not persist across reboots of the machine
+ unless you add the appropriate <emphasis role="bold">fs
+ setcell</emphasis> command to the machine's AFS initialization
+ file.</para>
+
+ <para>Only members of the <emphasis
+ role="bold">system:administrators</emphasis> group can turn on the
+ setuid mode bit on an AFS file or directory. When the setuid mode bit
+ is turned on, the UNIX <emphasis role="bold">ls -l</emphasis> command
+ displays the third user mode bit as an <emphasis
+ role="bold">s</emphasis> instead of an <emphasis
+ role="bold">x</emphasis>, but for an AFS file or directory, the
+ <emphasis role="bold">s</emphasis> appears only if setuid permission
+ is enabled for the cell in which the file resides.
+ <indexterm>
+ <primary>fs commands</primary>
+ <secondary>getcellstatus</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>commands</primary>
+ <secondary>fs getcellstatus</secondary>
+ </indexterm>
+ </para>
<sect2 id="Header_458">
<title>To determine a cell's setuid status</title>
</programlisting>
</sect2>
</sect1>
-</chapter>
\ No newline at end of file
+</chapter>
+
git://git.openafs.org / openafs.git / blobdiff