<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->
<modulesynopsis metafile="mod_bmx_vhost.xml.meta">

  <name>mod_bmx_vhost</name>
  <description>Basic Management Extension (BMX) virtual host summary</description>
  <status>External</status> <!-- For now... -->
  <sourcefile>mod_bmx_vhost.c</sourcefile>
  <identifier>bmx_vhost_module</identifier>
  <compatibility>Apache 2.0 and higher</compatibility>

  <summary>
    <p>The <module>mod_bmx_vhost</module> module provides operational tallies
    of activity in each specific virutal host, and aggregates these tallies
    for the entire server.</p>
 
    <p>The <module>mod_bmx</module> module is the core BMX module and 
    must be loaded in order to support any BMX plugins. It provides the
    base functionality for satisfying BMX queries. For basic configuration
    and use of <module>mod_bmx</module> and the plugin modules, refer to
    that module's manual page.</p>
  </summary>

  <!-- References to other documents or directives -->
  <seealso><module>mod_bmx</module></seealso>
  <seealso><module>mod_bmx_status</module></seealso>

  <section id="output">
    <title>mod_bmx_vhost output fields</title>
    <p>The resulting fields in the mod_bmx_vhost output will appear as;</p>
    <highlight language="json">
Name: mod_bmx_vhost:Type=forever,Host=example.com,Port=80
InBytesGET: 0
InBytesHEAD: 0
InBytesPOST: 0
InBytesPUT: 0
InRequestsGET: 27
InRequestsHEAD: 0
InRequestsPOST: 0
InRequestsPUT: 0
OutBytes200: 82438
OutBytes301: 0
OutBytes302: 0
OutBytes401: 0
OutBytes403: 212
OutBytes404: 418
OutBytes500: 1052
OutResponses200: 21
OutResponses301: 0
OutResponses302: 0
OutResponses401: 0
OutResponses403: 1
OutResponses404: 2
OutResponses500: 2
InLowBytes: 0
OutLowBytes: 85547
InRequests: 36
OutResponses: 36
StartDate: Tuesday, 17-Nov-2015 10:54:29 CST
StartTime: 1447779269518665
StartElapsed: 17484569829
    </highlight>
    <p>The available record types include the 'forever' (since the cache file
    was last manually purged), 'since-start' and 'since-restart' tallies.</p>

    <p>The available Host and Port will also include grand total summary
    <code>Host:_GLOBAL_,Port=_ANY_</code> records.  Be aware that the 
    specific Port number for individual virtual hosts will only display
    correctly if all <directive module="core">ServerName</directive> directives
    specify the port number (e.g. <code>ServerName example.com:80</code>),
    and will otherwise display a generic value, e.g. 
    <code>Host=example.com,Port=_ANY_</code>.</p>
  </section>

  <directivesynopsis>
    <name>BMXVHostLockFilename</name>
    <description>Semaphore for serializing access to the BMXVHostDBM file</description>
i   <syntax>BMXVHostLockFilename <em>filename</em></syntax>
    <default>BMXVHostLockFilename logs/bmx_vhost1.db.lock</default>
    <contextlist><context>server config</context></contextlist>

    <usage>
      <p>This configures the BMX vhost engine's file lock which is used for
      serializing access to the BMXVHostDBM file, and ensure that each record
      updated correctly tallies the work performed by all concurrent worker
      threads and processes. This directive can only be used in the global
      server context because it's only useful to have one global mutex.</p>

      <p>A portable physical (lock-)file and the <code>flock()</code> or
      <code>fcntl()</code> function are used as the Mutex, depending on the
      specific platform. Always use a local disk filesystem for
      <code>/path/to/mutex</code> and never a file residing on a NFS- or
      AFS-filesystem.</p>

      <example><title>Example</title>
          BMXVHostLockFilename /var/lock/httpd/bmx_vhost.lock
      </example>
    </usage>
  </directivesynopsis>

  <directivesynopsis>
    <name>BMXVHostDBMFilename</name>
    <description>Name of the inter-process virtual host activity tally</description>
    <syntax>BMXVHostLockFilename <em>file</em></syntax>
    <default>BMXVHostLockFilename logs/bmx_vhost1.db</default>
    <contextlist><context>server config</context></contextlist>

    <usage>
      <p>This configures the storage file for the global/inter-process
      BMX virtual host activity summary table.  This is necessary because
      multiple threads across multiple processes are satisfying requests
      in parallel against all of the virtual hosts, and the purpose of
      <module>mod_bmx_vhost</module> is to summarize the activity across
      all of these individual worker threads.</p>

      <p>This makes use of a DBM hash file which must be stored on local disk
      to sum the activity of each specific virtual host on a since-restart,
      since-start and 'forever' state (until this DBM accumulator file is
      manually purged).</p>

      <example><title>Example</title>
        BMXVHostDBMFilename /var/cache/httpd/bmx_vhost_activity<br />
      </example>

      <p>The default filename includes the digit '1' to designate that the
      file structure has changed since prior releases of mod_bmx. In the
      future, the authors expect to update that default to reflect a further
      change in data collection format. If a custom file name is specified,
      users are cautioned to purge the collection file during an upgrade of
      mod_bmx_vhost, or the accumulated 'forever' results may be either
      meaningless or can potentially cause the server to segfault.</p>
    </usage>
  </directivesynopsis>
</modulesynopsis>

