vcl-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r845507 [17/17] - in /websites/staging/vcl/trunk/content: ./ confluence_export/
Date Tue, 08 Jan 2013 16:38:17 GMT
Added: websites/staging/vcl/trunk/content/confluence_export/vmware-configuration.html
==============================================================================
--- websites/staging/vcl/trunk/content/confluence_export/vmware-configuration.html (added)
+++ websites/staging/vcl/trunk/content/confluence_export/vmware-configuration.html Tue Jan  8 16:38:15 2013
@@ -0,0 +1,537 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+    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.
+-->
+
+  <link href="/css/vcl.css" rel="stylesheet" type="text/css">
+  <link href="/css/code.css" rel="stylesheet" type="text/css">
+  <title>Apache VCL - VMware Configuration</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+
+<body>
+  <div id="sitetitle">
+    <table width="100%" border="0" cellspacing="0" cellpadding="5">
+      <tr>
+         <td><a href="/index.html"><img src="/img/vcl-logo.png" height="100" align="left" alt="Apache VCL logo"></a></td>
+         <td><a href="http://www.apache.org"><img src="/img/asf-logo.png" align="right" alt="Apache Software Foundation logo"></a></td>
+      </tr>
+    </table>
+  </div>
+
+  <div id="navigation"> 
+  <ul>
+<li>Information<ul>
+<li><a href="/info/about.html">What is VCL?</a></li>
+<li><a href="/info/features.html">Features</a></li>
+<li><a href="/info/architecture.html">Architecture</a></li>
+<li><a href="/info/use-cases.html">Use Cases</a></li>
+<li><a href="/downloads/download.cgi">Download</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html">License</a></li>
+<li><a href="/info/faq.html">FAQ</a></li>
+</ul>
+</li>
+<li><a href="/docs/index.html">Documentation</a><ul>
+<li><a href="/docs/using-vcl.html">Using VCL</a></li>
+<li><a href="/docs/image-creation.html">Image Creation</a></li>
+<li><a href="/docs/administration.html">Administration</a></li>
+<li><a href="/docs/installation.html">Installation</a></li>
+<li><a href="/docs/deployment-planning.html">Deployment Planning</a></li>
+</ul>
+</li>
+<li><a href="/comm/index.html">Community</a><ul>
+<li><a href="/comm/index.html#getInvolved">Getting Involved</a></li>
+<li><a href="/comm/index.html#mail-list">Mailing Lists</a></li>
+<li><a href="/comm/index.html#how-do-i-join-the-project">How can I Join</a></li>
+<li><a href="/comm/wiki.html">Wiki</a></li>
+<li><a href="/dev/index.html">Development</a><ul>
+<li><a href="/dev/jira.html">Issue Tracking</a></li>
+<li><a href="/dev/code-documentation.html">Code Documentation</a></li>
+<li><a href="/dev/roadmap.html">Roadmap</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="http://www.apache.org">Apache Software Foundation</a><ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+</ul>
+</li>
+</ul>
+  </div>
+  
+  <div id="content">
+    <h1 class="title">VMware Configuration</h1>
+    <p><a name="VMwareConfiguration-Terminology"></a></p>
+<h2 id="terminology">Terminology</h2>
+<p><a name="VMwareConfiguration-VMHost"></a></p>
+<h4 id="vm-host">VM Host</h4>
+<ul>
+<li>A VM host is a physical computer running a VMware hypervisor</li>
+<li>A VCL computer entry must be added for each VM
+host&nbsp;({color:#000000}{<em>}Manage Computers &gt; Edit Computer
+Information)</em>{color}</li>
+<li>{color:#000000}After the computer has been added to VCL, it is designated
+as a VM host by changing the computer state to vmhostinuse{color}
+{color:#000000}<em>(Manage Computers &gt; Computer Utilities)</em>{color}</li>
+</ul>
+<p><a name="VMwareConfiguration-VM"></a></p>
+<h4 id="vm">VM</h4>
+<ul>
+<li>A VM is a virtual machine managed by VCL</li>
+<li>A computer entry must be added to VCL for each VM
+({color:#000000}{<em>}Manage Computers &gt; Edit Computer Information)</em>{color}</li>
+<li>{color:#000000}Each VM must be assigned to a VM host{color}
+{color:#000000}<em>(Virtual Hosts &gt; VM Hosts tab &gt; Configure Host)</em>{color}</li>
+<li>VMs do not need to be created manually in VMware, VCL automatically
+creates and deletes VMs</li>
+</ul>
+<p><a name="VMwareConfiguration-VMHostProfile"></a></p>
+<h4 id="vm-host-profile">VM Host Profile</h4>
+<ul>
+<li>A VM host profile contains&nbsp;several parameters which describe how a
+VM host is configured so that VCL knows how to manage it</li>
+<li>Each VM host is assigned a VM host profile</li>
+<li>A VM host profile may be assigned to multiple VM hosts if they are
+configured identically</li>
+<li>VM host profiles may be added or modified via <em>Virtual Hosts &gt; VM Host
+Profiles tab</em></li>
+</ul>
+<p><a name="VMwareConfiguration-VMwareProductsSupported"></a></p>
+<h2 id="vmware-products-supported">VMware Products Supported</h2>
+<ul>
+<li>VMware Server 2.x</li>
+<li>VMware ESX 3.5 - 4.x</li>
+<li>VMware ESXi 4.x</li>
+<li>VMware ESXi 5.x</li>
+</ul>
+<p><a name="VMwareConfiguration-VMHost&nbsp;ManagementOptions"></a></p>
+<h3 id="vm-hostwzxhzdk12management-options">VM Host&nbsp;Management Options</h3>
+<p>&nbsp;The VCL&nbsp;management node must be able to control the VM host and
+the VMs running on it.&nbsp; VMware provides several different&nbsp;ways of
+doing this.&nbsp; VCL currently supports the following methods for remote
+VM host management:
+<em> VMware vSphere SDK
+</em> Use SSH to execute&nbsp;commands directly on the VM (<em>not officially
+supported by VMware</em>)</p>
+<p>The vSphere SDK can only&nbsp;be used if management is not&nbsp;restricted
+due to the VMware license key installed on the host.&nbsp; This mainly
+affects hosts running the free version of ESXi.&nbsp; Remote management
+using any of the&nbsp;methods supported by VMware&nbsp;is restricted once a
+free license key is entered.</p>
+<p>If remote management is restricted, the VM host can be managed if SSH is
+enabled on it.&nbsp; VCL will execute vim-cmd and other commands on the VM
+host via SSH.&nbsp;</p>
+<p><a name="VMwareConfiguration-HowtoenableSSHontheVMhost:"></a></p>
+<h4 id="how-to-enable-ssh-on-the-vm-host">How to enable SSH on the VM host:</h4>
+<p><a name="VMwareConfiguration-VMwareServer2.x"></a></p>
+<h5 id="vmware-server-2x">VMware Server 2.x</h5>
+<p>Enable the SSH daemon and configure identity key authentication according
+to the underlying VM host OS</p>
+<p><a name="VMwareConfiguration-ESX/ESXi3.5&4.0"></a></p>
+<h5 id="esxesxi-35-40">ESX/ESXi 3.5 &amp; 4.0</h5>
+<ul>
+<li>Connect to the console of the ESX/ESXi host</li>
+<li>Press <em>ALT-F1</em> - you should see a black screen with the VMware product
+name at the top</li>
+<li>Type the word <em>unsupported</em> and press <em>Enter</em> (you won't see the letters
+appear as you type them)</li>
+<li>You should see a password prompt, type&nbsp;in the <em>root
+password</em>&nbsp;and press <em>Enter</em></li>
+<li>Edit the file: <em>vi /etc/inetd.conf</em></li>
+<li>Uncomment the first line beginning with <em>#ssh</em> by deleting the #
+character</li>
+<li>Save the file - press <em>Esc</em> and then <em>:wq</em></li>
+<li>Kill the inetd process
+<strong> Determine the PID of the inetd process: <em>ps \| grep inetd</em>
+You should see a line that looks like: <em>5065 5065 busybox inetd</em></strong> Kill the process (enter the PID from the output of the previous
+command): <em>kill -HUP 5065</em></li>
+</ul>
+<p><a name="VMwareConfiguration-ESXi4.1"></a></p>
+<h5 id="esxi-41">ESXi 4.1</h5>
+<p>Beginning with <em>ESXi 4.1</em>, SSH&nbsp;can be enabled using the vSphere
+Client:
+<em> Select the ESXi host
+</em> Select the <em>Configuration</em> tab
+<em> Select&nbsp;</em>Security Profile<em> under Software
+</em> Click <em>Properties</em>
+<em> Select </em>Remote Tech Support (SSH)<em>
+</em> Click <em>Options</em>
+<em> Select </em>Start automatically<em>
+</em> Click <em>Start</em>
+<em> Click </em>OK*</p>
+<p><a name="VMwareConfiguration-ESX5.0"></a></p>
+<h5 id="esx-50">ESX 5.0</h5>
+<p>In the case of <em>ESX 5.0</em>:
+<em> Select the ESXi host
+</em> Select the <em>Configuration</em> tab
+<em> Select&nbsp;</em>Security Profile<em> under Software
+</em> Click <em>Properties</em>
+<em> Select </em>SSH Server<em>
+</em> Click <em>Options</em>
+<em> Confirm that </em>Start automatically<em> is selected
+</em> Click <em>OK</em></p>
+<p><a name="VMwareConfiguration-HowtoconfigureESX/ESXitouseSSHidentitykeyauthentication:"></a></p>
+<h4 id="how-to-configure-esxesxi-to-use-ssh-identity-key-authentication">How to configure ESX/ESXi to use SSH identity key authentication:</h4>
+<p>SSH identity key authentication&nbsp;must be configured if SSH is used to
+manage the VM host.
+<em> Create an SSH key pair on the management node (or use a key you
+previously created):
+{tip}
+ssh-keygen -t rsa -f /etc/vcl/vcl.key -N '' -b 1024 -C 'VCL root
+account'
+{tip}
+</em> Log into the ESX host via SSH (password authentication should work) and
+create the directory:
+{tip}
+ssh <ESXi host> 'mkdir /.ssh'
+{tip}
+<em> Copy the public key to the ESXi host:
+ESXi 4.x:
+{tip}
+scp /etc/vcl/vcl.key.pub <ESXi host>:/.ssh/authorized_keys
+{tip}
+ESXi 5.x:
+{tip}
+scp /etc/vcl/vcl.key.pub <ESXi host>:/etc/ssh/keys-root/authorized_keys
+{tip}
+</em> Test making an SSH connection using the key:
+{tip}
+ssh -i /etc/vcl/vcl.key <ESXi host>
+{tip}</p>
+<p>{color:#ff0000}{<em>}IMPORTANT:</em>{color} Under ESXi 4.x, the authorized_keys
+file is erased when the ESXi VM host is rebooted.&nbsp;Complete the
+following steps to&nbsp;make&nbsp;the authorized_keys file&nbsp;persistent:</p>
+<p><em>Note: VCL will perform these steps automatically when the 1st reservation
+assigned to the host is processed.</em></p>
+<ul>
+<li>Create a compressed tarball file containing the /.ssh directory:
+{tip}
+tar -C / -czf bootbank/vcl.tgz .ssh
+{tip}</li>
+<li>Edit the /bootbank/boot.cfg file and append <em><em>' --- vcl.tgz'</em></em> to
+modules line as shown in the following example:
+{panel}
+kernel=b.z
+kernelopt=
+modules=k.z --- s.z --- c.z --- oem.tgz --- license.tgz --- m.z ---
+state.tgz --- vcl.tgz
+build=4.1.0-260247
+updated=2
+bootstate=0
+{panel}
+{tip}
+Optionally you can run the following two commands:
+tar -C / -czf vcl.tgz .ssh
+BootModuleConfig.sh --add=vcl.tgz --verbose
+{tip}</li>
+</ul>
+<p><a name="VMwareConfiguration-VMHostProfileParameters"></a></p>
+<h2 id="vm-host-profile-parameters">VM Host Profile Parameters</h2>
+<p><a name="VMwareConfiguration-GeneralParameters"></a></p>
+<h3 id="general-parameters">General Parameters</h3>
+<p><a name="VMwareConfiguration-"></a></p>
+<h4></h4>
+<p><a name="VMwareConfiguration-*Name*"></a></p>
+<h5 id="name"><em>Name</em></h5>
+<ul>
+<li>Descriptive name of the VM host&nbsp;profile</li>
+</ul>
+<p><a name="VMwareConfiguration-*Type*_(deprecated)_"></a></p>
+<h5 id="type-deprecated"><em>Type</em> <em>(deprecated)</em></h5>
+<ul>
+<li>Removed in VCL 2.3</li>
+</ul>
+<p><a name="VMwareConfiguration-*Image*_(optional)_"></a></p>
+<h5 id="image-optional"><em>Image</em> <em>(optional)</em></h5>
+<ul>
+<li>VCL hypervisor image installed on VM host computers using xCAT
+{info}{<em>}xCAT is not required. &nbsp;VM host computers may be installed
+manually or by some other means.</em>{info}</li>
+<li>If xCAT is not used, select "No Image"</li>
+<li>VCL has the ability to install a hypervisor image on bare-metal computers
+using xCAT. &nbsp;If the image property is configured, the image is
+installed when a computer's state is changed to vmhostinuse via <em>Manage
+Computers &gt; Computer Utilities</em></li>
+</ul>
+<p><a name="VMwareConfiguration-*Username/Password*_(optional)_"></a></p>
+<h5 id="usernamepassword-optional"><em>Username/Password</em> <em>(optional)</em></h5>
+<ul>
+<li>Name and password&nbsp;of the&nbsp;administrative or root user residing
+on the VM host</li>
+<li>This account is used to manage the VM host and VMs assigned to the host</li>
+<li>The username and password are currently only used if the vSphere SDK is
+used to manage the VM host and VMs</li>
+</ul>
+<p><a name="VMwareConfiguration-StorageParameters"></a></p>
+<h3 id="storage-parameters">Storage Parameters</h3>
+<p>{anchor:resource}</p>
+<p><a name="VMwareConfiguration-ResourcePath_(optional)_"></a></p>
+<h5 id="resource-path-optional">Resource Path <em>(optional)</em></h5>
+<p>Resource Path only needs to be configured if VMware vCenter is used. It
+defines the location where VMs will be created in the vCenter inventory
+tree. The inventory tree contains at least one Datacenter, and may also
+contain Folders, Clusters, and Resource Pools.
+Example: /DatacenterA/Folder1/Cluster2/ResourcePool3</p>
+<p>{anchor:repository}</p>
+<p><a name="VMwareConfiguration-*RepositoryPath*_(optional)_"></a></p>
+<h5 id="repository-path-optional"><em>Repository Path</em> <em>(optional)</em></h5>
+<ul>
+<li>Path where master copies of images are stored which are&nbsp;used to
+transfer images to VM host datastores or to other repositories:
+<strong> If a reservation is assigned to a host but the image does not  exist in
+that host's datastore, it is copied from the repository to the virtual disk
+path when the VM is loaded
+</strong> If the VCL environment contains multiple management nodes and the  image
+does not exist in the repository or the host's datastore, the  image will
+be retrieved from another management node's repository by  copying it via
+SCP</li>
+<li>The Repository Path parameter does not need to be configured if the  VCL
+environment contains a single management node and all VM hosts  share the
+same Virtual Disk Path</li>
+<li>Example:&nbsp;<em>/vmfs/volumes/nfs-repository1</em></li>
+<li>VMs do not run directly off of the images stored in the repository</li>
+<li>Setting the Repository Path parameter determines whether or not an 
+additional copy of an image is created when an image is captured
+<strong> If repository path is not configured then only a single copy of the
+image will exist in the virtual disk path after an image is captured
+</strong> If repository path is configured then two copies of the image will 
+exist after an image is captured - one in the virtual disk path and one in
+the  repository</li>
+<li>Repository Path location can refer to and be mounted on either the
+management node or VM host
+<strong> It is highly recommended that the repository be mounted on the VM host
+</strong>* When mounted on the VM host, vmdk operations can be done directly on
+the VM host in a single step</li>
+<li>Images in the repository are stored in the 2 GB sparse vmdk format
+<strong> The size of the vmdk files will approximately be equal to the  amount of
+actual data saved in the image regardless of the size of the  VM's hard
+drive
+</strong> Storing images in the 2 GB sparse format is necessary to allow  images
+to be transferred via SCP without having to transfer data equal  to the
+entire size of the VM's hard drive</li>
+</ul>
+<p><a name="VMwareConfiguration-RepositoryImageType"></a></p>
+<h5 id="repository-image-type">Repository Image Type</h5>
+<p>Virtual disk file format for images stored in the repository.
+{anchor:datastore}</p>
+<p><a name="VMwareConfiguration-*VirtualDiskPath(previouslyDatastorePath)*"></a></p>
+<h5 id="virtual-disk-path-previously-datastore-path"><em>Virtual Disk Path (previously Datastore Path)</em></h5>
+<ul>
+<li>Location where master copies of images are stored which are used by
+running VMs</li>
+<li>Example:&nbsp;<em>/vmfs/volumes/nfs-datastore1</em>
+{info}For ESXi, the path configured in the profile may simply be the short
+datastore name as it appears in the vSphere Client: nfs-datastore1{info}</li>
+<li>Storage location should be large enough to store all of the images which
+may be loaded on the VM host <em>(from 100's of GB to several TB)</em></li>
+<li>VCL creates a directory for each image in the Virtual Disk Path</li>
+<li>Images are stored in the <a href="http://www.sanbarrow.com/vmdk-basics.html">vmfs thin vmdk format</a></li>
+<li>Virtual Disk Path may either reside on local or network storage</li>
+<li>Multiple VM hosts can share the same datastore if network storage is used
+<strong> A single datastore may be used by all VM hosts if performance is
+adequate
+</strong> Multiple VMs on different hosts may access the same Virtual Disk Path
+image at the same time
+<strong> It is recommended that datastores are shared among hosts so that fewer
+copies of each image have to be stored
+</strong> The underlying storage hardware and network connectivity from the hosts
+to the storage must be adequate
+** Storage where the datastore is located should be optimized for read
+performance</li>
+<li>VCL configures VMs to access images stored in the Virtual Disk Path in
+read-only mode
+** Changes made to the VM's hard drive are written to delta files located
+in the VM Working Directory Path dedicated for the VM</li>
+</ul>
+<p><a name="VMwareConfiguration-VirtualDiskImageType"></a></p>
+<h5 id="virtual-disk-image-type">Virtual Disk Image Type</h5>
+<p>Virtual disk file format for images stored in the virtual disk path.</p>
+<p><a name="VMwareConfiguration-VirtualDiskMode(previously*VMDisk)*"></a></p>
+<h5 id="virtual-disk-mode-previously-vm-disk">Virtual Disk Mode (previously <em>VM Disk)</em></h5>
+<ul>
+<li>Defines whether the storage where the VM host's Virtual Disk Path 
+resides is dedicated to a single host or shared among multiple hosts:
+<strong> dedicated (previously localdisk)
+<strong><em> The VM host's Virtual Disk Path&nbsp;is located on local disks or
+dedicated network storage
+</em></strong> The VM host is the only host which accesses the Virtual Disk Path
+<strong><em> Repository Path must be configured
+** shared (previously networkdisk)
+</em></strong> The VM host's Virtual Disk Path&nbsp;is located on network storage
+which is shared by other VM hosts
+</strong>* Repository Path is optional</li>
+</ul>
+<p>{note}
+The Virtual Disk Mode (VM Disk) parameter does <em>not</em> determine whether or
+not:
+...images are copied from the datastore to the repository during image
+capture
+...images are copied from the repository to the datastore during image load
+These are determined by whether or not Repository Path is configured in the
+profile
+{note}</p>
+<p>{anchor:vmpath}</p>
+<p><a name="VMwareConfiguration-VMWorkingDirectoryPath_(optional)_(previously*VMPath*)"></a></p>
+<h5 id="vm-working-directory-path-optional-previously-vm-path">VM Working Directory Path <em>(optional)</em> (previously <em>VM Path</em>)</h5>
+<ul>
+<li>Defines path on VM host where VM working directories will reside
+(contains .vmx, delta, .vswp, nvram files)</li>
+<li>If not configured, the Virtual Disk Path location will be used</li>
+<li>VCL creates a directory under the VM Working Directory Path for each VM
+it creates
+<strong> Contains the .vmx file which defines the VM
+</strong> Contains delta vmdk files which are written to as changes are made to
+the VM's hard drive</li>
+<li>VM Working Directory Path may either reside on local or network storage</li>
+<li>Location should be dedicated for each VM host
+<strong> Multiple VM hosts should not share the same VM Working Directory Path
+location for performance and image safety reasons
+</strong> VM Working Directory Paths of multiple hosts may reside on the same
+volume but a subdirectory should be created for each host</li>
+<li>Storage where the VM Working Directory Path is located should be
+optimized for read-write performance</li>
+</ul>
+<p><a name="VMwareConfiguration-"></a></p>
+<h5></h5>
+<p><a name="VMwareConfiguration-NetworkingParameters"></a></p>
+<h4 id="networking-parameters">Networking Parameters</h4>
+<p><a name="VMwareConfiguration-*VMNetwork(previouslyVirtualSwitch)*"></a></p>
+<h5 id="vm-network-previously-virtual-switch"><em>VM Network (previously Virtual Switch)</em></h5>
+<ul>
+<li>VM Network 0 (previously Virtual Switch 0) - private VCL
+management&nbsp;network</li>
+<li>
+<p>VM Network 1 (previously Virtual Switch 1) - public network used by user
+making reservation&nbsp;to access the VMs</p>
+</li>
+<li>
+<p>The VM Network parameters should match the network names configured on
+the VM host
+** For ESXi, the <em>VM Network</em> parameters must match the <em>Virtual Machine
+Port Group Network Labels</em> configured in the vSphere Client, example:
+<strong><em> VM Network 0: Public
+</em></strong> VM Network 1: Private
+&nbsp; !vmware-network-labels.gif|border=1!</p>
+</li>
+<li>
+<p>For VMware Server 2.x, the <em>VM Network</em> parameters must match the
+<em>Network Names</em> configured&nbsp;by running&nbsp;vmware-config.pl</p>
+</li>
+</ul>
+<p><a name="VMwareConfiguration-*Generateeth0/eth1MAC*"></a></p>
+<h5 id="generate-eth0eth1-mac"><em>Generate eth0/eth1 MAC</em></h5>
+<ul>
+<li>New in VCL 2.3</li>
+<li>Determines whether VMs are assigned MAC addresses defined in the VCL
+database or if random MAC addresses should be assigned</li>
+</ul>
+<p><a name="VMwareConfiguration-ConfigurationExamples"></a></p>
+<h2 id="configuration-examples">Configuration Examples</h2>
+<p><a name="VMwareConfiguration-LocalDiskOnly-RepositoryMountedviaNFS"></a></p>
+<h3 id="local-disk-only-repository-mounted-via-nfs">Local Disk Only - Repository Mounted via NFS</h3>
+<p><a name="VMwareConfiguration-!local-only-nfs.gif!"></a></p>
+<h3 id="local-only-nfsgif">!local-only-nfs.gif!</h3>
+<p>The diagram above shows a simple VCL configuration with 1 management node
+and 2 VMware ESXi hosts.&nbsp; Network storage is not used.
+The local disks on the VM hosts are used to store all of the files used by
+running VMs including the VM's working directory and the master vmdk image.</p>
+<p>A directory on the local disk on the management node is used to as the
+image repository.&nbsp;  This directory is exported via NFS.&nbsp; VM hosts
+mount this directory  as a datastore named "repository".&nbsp; Mounting the
+repository directly on  the VM hosts allows the vmkfstools utility to be
+used on the VM hosts to  copy and convert images directly from the
+repository to the local  datastore in a single step.</p>
+<p>If an image is to be loaded on a VM host and that image does not already
+exist in the VM host's local datastore (Virtual Disk Path), it is
+automatically copied from the repository to the VM host's local datastore
+(Virtual Disk Path) at the beginning of the load process.</p>
+<p>During image capture, images are automatically copied to from the VM host's
+local datastore (Virtual Disk Path) to the repository.&nbsp; This allows
+images captured on a VM host to be loaded on any other VM host.</p>
+<p>The VM host profile Virtual Disk Mode parameter is set to dedicated.&nbsp;
+This indicates to the load process that the VM host's Virtual Disk Path is
+dedicated to the VM host and not shared by other VM hosts.&nbsp; This
+allows images to be deleted from the VM host's local datastore (Virtual
+Disk Path) if another image must be copied from the repository and not
+enough space is available.</p>
+<p><a name="VMwareConfiguration-LocalDiskOnly-RepositoryNotAvailableviaNFS"></a></p>
+<h3 id="local-disk-only-repository-not-available-via-nfs">Local Disk Only - Repository Not Available via NFS</h3>
+<p>!local-only-scp.gif!</p>
+<p>This example is identical to the one above except that the repository
+located on the management node's local disk is not exported via NFS.&nbsp;
+Because of this, images must be transferred using SCP instead of
+vmkfstools.&nbsp; This is less desirable than mounting the repository
+directly on the VM hosts because images cannot be copied and converted in a
+single step.&nbsp; Images are stored in the repository in the 2GB sparse
+format.&nbsp; This allows the images to be copied via SCP while only
+transferring the data stored in the image, not the entire size of the hard
+drive stored in the image.&nbsp; VMware ESXi cannot run VMs using vmdk
+images stored in the 2GB sparse format.&nbsp; Images are converted to the
+vmfs thin format so that they can be loaded on VMware ESXi.&nbsp; This adds
+extra time to the load process if an image does not exist in the VM's local
+datastore (Virtual Disk Path) and must be copied from the repository.&nbsp;
+It also requires additional space in the VM host's local datastore (Virtual
+Disk Path) becuase 2 copies of the image exist while it is being converted.
+Note that the VM host profile Repository Path parameter is set to the path
+on the management node's hard drive.&nbsp; The code first checks if the
+path exists on the VM host.&nbsp; If not, it assumes the repository is not
+mounted directly on the VM host and the Repository Path value refers to a
+location on the management node.</p>
+<p><a name="VMwareConfiguration-NetworkStorageOnly-NoRepository"></a></p>
+<h3 id="network-storage-only-no-repository">Network Storage Only - No Repository</h3>
+<p>!network-only-no-repo.gif!</p>
+<p>This is an example of a simple configuration where the network storage is
+used.</p>
+<p>A repository is not used in this configuration. &nbsp;This implies that all
+VM hosts which will ever be added to this VCL environment will need to be
+able to connect to the network storage.</p>
+<p>A datastore to be used as the Virtual Disk Path named "datastore" is
+mounted on every VM host. &nbsp;Each of these mounts points to the same
+location on the network storage. &nbsp;The datastore will contain the
+master vmdk images. &nbsp;VMs loaded on the VM hosts will read from these
+master vmdk images.</p>
+<p>A datastore to be used as the VM Working Directory Path named "vmpath" is
+also mounted on each VM host. &nbsp;However, the location to which each VM
+host points should be different. &nbsp;In the example above, vmhost-a-01
+points to th the /vmpath01 directory on the network storage and vmhost-a-02
+points to the /vmpath02 directory. &nbsp;These locations may be different
+network storage filesystems or may be different directories on the same
+network filesystem. &nbsp;Even though the mounts on the VM hosts point to
+different locations, the datastore names configured under ESXi are
+identical. &nbsp;This allows you to use the same VCL VM host profile for
+all of the VM hosts.</p>
+<p>The VM host profile Virtual Disk Mode parameter is set to shared.&nbsp;
+This indicates to the load process that the VM host's Virtual Disk Path is
+shared by other VM hosts.</p>
+  </div>
+  
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2012 The Apache Software Foundation, Licensed under 
+        the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+        <br />
+        Apache and the Apache feather logo are trademarks of The Apache Software Foundation.
+      </p>
+    </div>
+  </div>
+  
+</body>
+</html>

Added: websites/staging/vcl/trunk/content/confluence_export/vmware-provisioning-module-information.html
==============================================================================
--- websites/staging/vcl/trunk/content/confluence_export/vmware-provisioning-module-information.html (added)
+++ websites/staging/vcl/trunk/content/confluence_export/vmware-provisioning-module-information.html Tue Jan  8 16:38:15 2013
@@ -0,0 +1,171 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+    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.
+-->
+
+  <link href="/css/vcl.css" rel="stylesheet" type="text/css">
+  <link href="/css/code.css" rel="stylesheet" type="text/css">
+  <title>Apache VCL - VMware Provisioning Module Information</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+
+<body>
+  <div id="sitetitle">
+    <table width="100%" border="0" cellspacing="0" cellpadding="5">
+      <tr>
+         <td><a href="/index.html"><img src="/img/vcl-logo.png" height="100" align="left" alt="Apache VCL logo"></a></td>
+         <td><a href="http://www.apache.org"><img src="/img/asf-logo.png" align="right" alt="Apache Software Foundation logo"></a></td>
+      </tr>
+    </table>
+  </div>
+
+  <div id="navigation"> 
+  <ul>
+<li>Information<ul>
+<li><a href="/info/about.html">What is VCL?</a></li>
+<li><a href="/info/features.html">Features</a></li>
+<li><a href="/info/architecture.html">Architecture</a></li>
+<li><a href="/info/use-cases.html">Use Cases</a></li>
+<li><a href="/downloads/download.cgi">Download</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html">License</a></li>
+<li><a href="/info/faq.html">FAQ</a></li>
+</ul>
+</li>
+<li><a href="/docs/index.html">Documentation</a><ul>
+<li><a href="/docs/using-vcl.html">Using VCL</a></li>
+<li><a href="/docs/image-creation.html">Image Creation</a></li>
+<li><a href="/docs/administration.html">Administration</a></li>
+<li><a href="/docs/installation.html">Installation</a></li>
+<li><a href="/docs/deployment-planning.html">Deployment Planning</a></li>
+</ul>
+</li>
+<li><a href="/comm/index.html">Community</a><ul>
+<li><a href="/comm/index.html#getInvolved">Getting Involved</a></li>
+<li><a href="/comm/index.html#mail-list">Mailing Lists</a></li>
+<li><a href="/comm/index.html#how-do-i-join-the-project">How can I Join</a></li>
+<li><a href="/comm/wiki.html">Wiki</a></li>
+<li><a href="/dev/index.html">Development</a><ul>
+<li><a href="/dev/jira.html">Issue Tracking</a></li>
+<li><a href="/dev/code-documentation.html">Code Documentation</a></li>
+<li><a href="/dev/roadmap.html">Roadmap</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="http://www.apache.org">Apache Software Foundation</a><ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+</ul>
+</li>
+</ul>
+  </div>
+  
+  <div id="content">
+    <h1 class="title">VMware Provisioning Module Information</h1>
+    <p><a name="VMwareProvisioningModuleInformation-VMwareProvisioningModule"></a></p>
+<h2 id="vmware-provisioning-module">VMware Provisioning Module</h2>
+<ul>
+<li>Source file: managementnode/lib/VCL/Module/Provisioning/VMware/VMware.pm</li>
+</ul>
+<p><a name="VMwareProvisioningModuleInformation-SupportedVMwareProducts"></a></p>
+<h4 id="supported-vmware-products">Supported VMware Products</h4>
+<ul>
+<li>VMware Server 2.0</li>
+<li>VMware ESX/ESXi 3.5</li>
+<li>VMware ESX/ESXi 4.0</li>
+</ul>
+<p><a name="VMwareProvisioningModuleInformation-SupportedVMware&nbsp;APIs,SDKs,&CLIs"></a></p>
+<h4 id="supported-vmwarewzxhzdk6apis-sdks-clis">Supported VMware&nbsp;APIs, SDKs, &amp; CLIs</h4>
+<p>There are several different methods to control VMware hosts and virtual
+machines.&nbsp; The main VMware.pm module should remain as
+SDK/API/CLI-agnostic as possible.&nbsp; All code which interacts with a
+VMware remote control method should reside in utility modules located in
+the lib/VCL/Module/Provisioning/VMware directory.
+<em> vSphere SDK - lib/VCL/Module/Provisioning/VMware/vSphere_SDK.pm
+<strong> Provides full VM and VM host remote access functionality
+</strong> Provides VM host datastore file access
+<strong> Can only be used if the VMware&nbsp;host is not running with a
+restricted license
+</strong> SSH access is not required to the VM host
+<strong> Installed by default on ESX/ESXi hosts
+</strong> Can be installed on Server 2.0 hosts
+</em> -VIX API - lib/VCL/Module/Provisioning/VMware/VIX_API.pm-
+<em>Although a utility module has been written to use the VIX API, it is not
+supported and will not be maintained.&nbsp; Everything that the VIX API can
+do can be done by the vim-cmd CLI and SSH access to the VM host is required
+for both methods.&nbsp; Therefore, there is no benefit to maintain&nbsp;the
+VIX API module.</em>
+<strong> -Provides basic VM control functions-
+</strong> -Does not provide any file access-
+<strong> -SSH access is required to the VM host in order to manipulate the file
+system-
+</strong> -Can only be used if the VMware&nbsp;host is not running with a
+restricted license-
+<strong> -Installed by default on Server 2.0 hosts-
+* vim-cmd CLI via SSH - lib/VCL/Module/Provisioning/VMware/VIM_SSH.pm
+</strong> Provides full VM host remote access functionality
+<strong> Does not provide file access
+</strong> SSH access is required to the VM host in order to manipulate the file
+system
+** Can be used if the the VMware host is running with a restricted license</p>
+<p><a name="VMwareProvisioningModuleInformation-RequiredUtilityModuleSubroutines"></a></p>
+<h3 id="required-utility-module-subroutines">Required Utility Module Subroutines</h3>
+<ul>
+<li>get_registered_vms</li>
+<li>vm_register</li>
+<li>vm_unregister</li>
+<li>get_vm_power_state</li>
+<li>vm_power_on</li>
+<li>vm_power_off</li>
+<li>copy_virtual_disk</li>
+<li>move_virtual_disk</li>
+<li>get_virtual_disk_controller_type</li>
+<li>get_virtual_disk_hardware_version</li>
+<li>get_virtual_disk_type</li>
+</ul>
+<p><a name="VMwareProvisioningModuleInformation-RequiredOSModuleSubroutines"></a></p>
+<h3 id="required-os-module-subroutines">Required OS Module Subroutines</h3>
+<ul>
+<li>find_files</li>
+<li>copy_file</li>
+<li>copy_file_to</li>
+<li>copy_file_from</li>
+<li>delete_file</li>
+<li>move_file</li>
+<li>file_exists</li>
+<li>get_available_space</li>
+<li>create_directory</li>
+<li>get_file_contents</li>
+<li>get_file_size</li>
+</ul>
+  </div>
+  
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2012 The Apache Software Foundation, Licensed under 
+        the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+        <br />
+        Apache and the Apache feather logo are trademarks of The Apache Software Foundation.
+      </p>
+    </div>
+  </div>
+  
+</body>
+</html>

Added: websites/staging/vcl/trunk/content/confluence_export/web-code-installation.html
==============================================================================
--- websites/staging/vcl/trunk/content/confluence_export/web-code-installation.html (added)
+++ websites/staging/vcl/trunk/content/confluence_export/web-code-installation.html Tue Jan  8 16:38:15 2013
@@ -0,0 +1,281 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+    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.
+-->
+
+  <link href="/css/vcl.css" rel="stylesheet" type="text/css">
+  <link href="/css/code.css" rel="stylesheet" type="text/css">
+  <title>Apache VCL - Web Code Installation</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+
+<body>
+  <div id="sitetitle">
+    <table width="100%" border="0" cellspacing="0" cellpadding="5">
+      <tr>
+         <td><a href="/index.html"><img src="/img/vcl-logo.png" height="100" align="left" alt="Apache VCL logo"></a></td>
+         <td><a href="http://www.apache.org"><img src="/img/asf-logo.png" align="right" alt="Apache Software Foundation logo"></a></td>
+      </tr>
+    </table>
+  </div>
+
+  <div id="navigation"> 
+  <ul>
+<li>Information<ul>
+<li><a href="/info/about.html">What is VCL?</a></li>
+<li><a href="/info/features.html">Features</a></li>
+<li><a href="/info/architecture.html">Architecture</a></li>
+<li><a href="/info/use-cases.html">Use Cases</a></li>
+<li><a href="/downloads/download.cgi">Download</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html">License</a></li>
+<li><a href="/info/faq.html">FAQ</a></li>
+</ul>
+</li>
+<li><a href="/docs/index.html">Documentation</a><ul>
+<li><a href="/docs/using-vcl.html">Using VCL</a></li>
+<li><a href="/docs/image-creation.html">Image Creation</a></li>
+<li><a href="/docs/administration.html">Administration</a></li>
+<li><a href="/docs/installation.html">Installation</a></li>
+<li><a href="/docs/deployment-planning.html">Deployment Planning</a></li>
+</ul>
+</li>
+<li><a href="/comm/index.html">Community</a><ul>
+<li><a href="/comm/index.html#getInvolved">Getting Involved</a></li>
+<li><a href="/comm/index.html#mail-list">Mailing Lists</a></li>
+<li><a href="/comm/index.html#how-do-i-join-the-project">How can I Join</a></li>
+<li><a href="/comm/wiki.html">Wiki</a></li>
+<li><a href="/dev/index.html">Development</a><ul>
+<li><a href="/dev/jira.html">Issue Tracking</a></li>
+<li><a href="/dev/code-documentation.html">Code Documentation</a></li>
+<li><a href="/dev/roadmap.html">Roadmap</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="http://www.apache.org">Apache Software Foundation</a><ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+</ul>
+</li>
+</ul>
+  </div>
+  
+  <div id="content">
+    <h1 class="title">Web Code Installation</h1>
+    <p>{excerpt}This page describes how to install and configure the frontend VCL
+web code components including the web server prerequisites and frontend VCL
+web code. It also describes how to add local web accounts, configure LDAP
+authentication, and set the timezone correctly.{excerpt}</p>
+<p><a name="WebCodeInstallation-*Prerequisites*"></a></p>
+<h2 id="prerequisites"><em>Prerequisites</em></h2>
+<p>Your web server should meet the following criteria before installing the
+frontend VCL code:
+<em> Apache HTTP Server v1.3 or v2.x with SSL enabled - while VCL may run
+under another webserver capable of running PHP code, it has only been
+tested to work with Apache HTTP Server
+</em> PHP 5
+<em> php modules that should be installed (depending on your Linux distro,
+some of these may be compiled in to php instead of being a separate
+module):
+<strong> php-gd
+</strong> php-json (if your PHP version is &lt; 5.2, this is not required)
+<strong> php-mcrypt
+</strong> php-mysql
+<strong> php-openssl
+</strong> php-sysvsem
+<strong> php-xml
+</strong> php-xmlrpc
+</em> useful to have the server set up to be able to send debugging emails
+* php-mcrypt requires libmcrypt and mcrypt libraries as dependencies. 
+These may need to be installed first.</p>
+<p><a name="WebCodeInstallation-*InstallingVCLFrontendWebCode*"></a></p>
+<h2 id="installing-vcl-frontend-web-code"><em>Installing VCL Frontend Web Code</em></h2>
+<ol>
+<li>If you haven't already done so, download and extract a copy of the latest
+release. There is a link to it under the Project Resources section on our
+wiki <a href="apache-vcl.html">home page</a>
+. Look for "Current version".</li>
+<li>
+<p>copy the "web" directory to a location somewhere under the web root of
+your web server:</p>
+<p>cp -r web/ /var/www/html/vcl</p>
+</li>
+<li>
+<p>modify vcl/.ht-inc/secrets.php</p>
+</li>
+<li>
+<ul>
+<li>set $vclhost, $vcldb, $vclusername, and $vclpassword to match your
+database setup</li>
+</ul>
+</li>
+<li>
+<ul>
+<li>create random passwords for $mcryptkey, $mcryptiv, and $pemkey -
+$mcryptiv must be 8 hex characters</li>
+</ul>
+</li>
+<li>run the genkeys.sh script from within vcl/.ht-inc and give it $pemkey
+from secrets.php as the passphrase (3 times, copy/paste is a good idea
+here)</li>
+<li>modify vcl/.ht-inc/conf.php to match your site - COOKIEDOMAIN needs to be
+the domain name your web server is using, or left blank if you are
+accessing it by IP only.
+<em>NOTE:</em> There is a misconfiguration in conf.php in VCL 2.1.  To correct it,
+change affiliationid for "Local Account" in the $authMechs array from 4 to
+1.</li>
+<li>*<em>NOTICE</em>* JpGraph 2.x is no longer available.  JpGraph 3.x is released
+under a dual license. QPL 1.0 (Qt Free Licensee).  Free for non-commercial,
+open-source or educational use (JpGraph Professional License for commercial
+use).  If you are planning to use this for commercial use and don't want to
+pay for JpGraph, you can safely skip this step with the only side effect of
+not being able to display a few graphs on the statistics page.
+Download JpGraph from <a href="http://www.aditus.nu/jpgraph/jpdownload.php">http://www.aditus.nu/jpgraph/jpdownload.php</a></li>
+<li>
+<ul>
+<li>For PHP5, download the 3.x series, extract it, and copy the src
+directory from it to vcl/.ht-inc/jpgraph</li>
+</ul>
+</li>
+<li>download version 0.4.0 of Dojo Toolkit: <a href="http://download.dojotoolkit.org/release-0.4.0/dojo-0.4.0-ajax.tar.gz">http://download.dojotoolkit.org/release-0.4.0/dojo-0.4.0-ajax.tar.gz</a></li>
+<li>
+<ul>
+<li>extract it under the vcl directory and rename "dojo-0.4.0-ajax" to
+"dojoAjax"</li>
+</ul>
+</li>
+<li>download version 1.1.0 of Dojo Toolkit: <a href="http://download.dojotoolkit.org/release-1.1.0/dojo-release-1.1.0.tar.gz">http://download.dojotoolkit.org/release-1.1.0/dojo-release-1.1.0.tar.gz</a></li>
+<li>
+<ul>
+<li>extract it under the vcl directory and rename "dojo-release-1.1.0" to
+"dojo"</li>
+</ul>
+</li>
+<li>go into the themes directory (vcl/themes) and run "./copydojocss.sh
+default" to copy parts of dojo's css into the "default" theme</li>
+<li>if you want to be able to edit any of the documentation that comes
+bundled with the vcl web code, download fckeditor from <a href="http://www.fckeditor.net/download">http://www.fckeditor.net/download</a>
+ (most people can skip this step)</li>
+<li>
+<ul>
+<li>extract it under the vcl directory</li>
+</ul>
+</li>
+<li>open a browser and open the testsetup.php page</li>
+<li>
+<ul>
+<li>i.e. if you set up your site to be <a href="https://my.server.org/vcl/">https://my.server.org/vcl/</a>
+ open [https://my.server.org/vcl/testsetup.php]</li>
+</ul>
+</li>
+<li>debug any issues reported by testsetup.php</li>
+<li>now, open the index.php page in your browser</li>
+<li>select Local Account and use 'admin' as the user and 'adminVc1passw0rd'
+as the password</li>
+<li>click the "Management Nodes" link</li>
+<li>enter the hostname and IP of your management node</li>
+<li>click Add</li>
+<li>fill in "Install Path" - this is parent directory under which image files
+will be stored</li>
+<li>enter "/etc/vcl/vcl.key" for "End Node SSH Identity Key Files"</li>
+<li>click "Confirm Management Node"</li>
+<li>click Submit</li>
+<li>click the "Management Nodes" link</li>
+<li>select "Edit Management Node Grouping"</li>
+<li>click Submit</li>
+<li>select the checkbox for your management node</li>
+<li>click Submit</li>
+<li>click "Manage Computers"</li>
+<li>select the "Add Single Computer" radio button</li>
+<li>click the Submit</li>
+<li>fill in Hostname, IP Address, owner (admin@Local), RAM, Proc Speed,
+Network Speed, select "blade" for Type, select "xCAT 1.x Provisioning" for
+"Provisioning Engine", and click the checkbox under "allcomputers", and
+"newimages"
+&nbsp;&nbsp; &nbsp;Note: if using using vmware, select "virtualmachine" for
+Type and "VMWare Server Provisioning" for "Provisioning Engine"</li>
+<li>click Confirm Computer</li>
+<li>click Submit (don't worry about the fact that the computer you just added
+isn't listed after clicking Submit)</li>
+<li>after you've configured your image library and your management node has
+started checking in, you should be able to make a reservation</li>
+</ol>
+<p><a name="WebCodeInstallation-*Addingextralocalaccounts*"></a></p>
+<h2 id="adding-extra-local-accounts"><em>Adding extra local accounts</em></h2>
+<p>There's not currently a tool for this.  You will need to add entries
+directly to the database.
+1. add entry to user table</p>
+<div class="codehilite"><pre><span class="n">INSERT</span> <span class="n">INTO</span> <span class="n">user</span> <span class="p">(</span><span class="n">unityid</span><span class="p">,</span> <span class="n">firstname</span><span class="p">,</span> <span class="n">lastname</span><span class="p">,</span> <span class="n">email</span><span class="p">,</span> <span class="n">lastupdated</span><span class="p">)</span> <span class="n">VALUES</span>
+</pre></div>
+
+
+<p>('myusername', 'myfirstname', 'mylastname', 'myemailaddr', NOW());</p>
+<ol>
+<li>
+<p>find out the id generated for that user</p>
+<p>SELECT id, unityid FROM user WHERE unityid = 'myusername';</p>
+</li>
+<li>
+<p>add entry to the localauth table</p>
+<p>INSERT INTO localauth (userid, salt, passhash, lastupdated) VALUES
+('place1', 'place2', 'place3', NOW())</p>
+</li>
+</ol>
+<p>with place1 = id from step 2
+place2 = an 8 char random string
+place3 = sha1sum( desired password with place2 stuck on the end )
+this can be generated under linux like this (using 'thedog' as the password
+and 11111111 as place2):
+echo -n 'thedog11111111' \| sha1sum
+Once a user has been added, the user can go to User Preferences to change
+his/her password</p>
+<p><a name="WebCodeInstallation-*AddingLDAPauthentication*"></a></p>
+<h2 id="adding-ldap-authentication"><em>Adding LDAP authentication</em></h2>
+<ol>
+<li>fill in the necessary information in vcl/.ht-inc/conf.php</li>
+<li>add an entry to the affiliation table and use the id for that entry as
+'affiliationid' for your new entry in vcl/.ht-inc/conf.php</li>
+<li>uncomment the 'require_once(".ht-inc/authmethods/ldapauth.php");' line in
+in vcl/.ht-inc/conf.php</li>
+</ol>
+<p><a name="WebCodeInstallation-*SettingTimeZone*"></a></p>
+<h2 id="setting-time-zone"><em>Setting Time Zone</em></h2>
+<ol>
+<li>Edit /var/www/html/vcl/.ht-inc/php5extras.php to indicate the correct
+time zone:
+date_default_timezone_set('America/Los_Angeles');</li>
+<li>Edit /var/www/html/vcl/.ht-inc/requests.php (line 3301 currently) to
+indicate the correct time zone (purely cosmetic):
+print "<small>(Pacific Time Zone)</small>";</li>
+</ol>
+  </div>
+  
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2012 The Apache Software Foundation, Licensed under 
+        the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+        <br />
+        Apache and the Apache feather logo are trademarks of The Apache Software Foundation.
+      </p>
+    </div>
+  </div>
+  
+</body>
+</html>

Added: websites/staging/vcl/trunk/content/confluence_export/web-code-overview.html
==============================================================================
--- websites/staging/vcl/trunk/content/confluence_export/web-code-overview.html (added)
+++ websites/staging/vcl/trunk/content/confluence_export/web-code-overview.html Tue Jan  8 16:38:15 2013
@@ -0,0 +1,498 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+<!--
+
+    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.
+-->
+
+  <link href="/css/vcl.css" rel="stylesheet" type="text/css">
+  <link href="/css/code.css" rel="stylesheet" type="text/css">
+  <title>Apache VCL - Web Code Overview</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+
+<body>
+  <div id="sitetitle">
+    <table width="100%" border="0" cellspacing="0" cellpadding="5">
+      <tr>
+         <td><a href="/index.html"><img src="/img/vcl-logo.png" height="100" align="left" alt="Apache VCL logo"></a></td>
+         <td><a href="http://www.apache.org"><img src="/img/asf-logo.png" align="right" alt="Apache Software Foundation logo"></a></td>
+      </tr>
+    </table>
+  </div>
+
+  <div id="navigation"> 
+  <ul>
+<li>Information<ul>
+<li><a href="/info/about.html">What is VCL?</a></li>
+<li><a href="/info/features.html">Features</a></li>
+<li><a href="/info/architecture.html">Architecture</a></li>
+<li><a href="/info/use-cases.html">Use Cases</a></li>
+<li><a href="/downloads/download.cgi">Download</a></li>
+<li><a href="http://www.apache.org/licenses/LICENSE-2.0.html">License</a></li>
+<li><a href="/info/faq.html">FAQ</a></li>
+</ul>
+</li>
+<li><a href="/docs/index.html">Documentation</a><ul>
+<li><a href="/docs/using-vcl.html">Using VCL</a></li>
+<li><a href="/docs/image-creation.html">Image Creation</a></li>
+<li><a href="/docs/administration.html">Administration</a></li>
+<li><a href="/docs/installation.html">Installation</a></li>
+<li><a href="/docs/deployment-planning.html">Deployment Planning</a></li>
+</ul>
+</li>
+<li><a href="/comm/index.html">Community</a><ul>
+<li><a href="/comm/index.html#getInvolved">Getting Involved</a></li>
+<li><a href="/comm/index.html#mail-list">Mailing Lists</a></li>
+<li><a href="/comm/index.html#how-do-i-join-the-project">How can I Join</a></li>
+<li><a href="/comm/wiki.html">Wiki</a></li>
+<li><a href="/dev/index.html">Development</a><ul>
+<li><a href="/dev/jira.html">Issue Tracking</a></li>
+<li><a href="/dev/code-documentation.html">Code Documentation</a></li>
+<li><a href="/dev/roadmap.html">Roadmap</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a href="http://www.apache.org">Apache Software Foundation</a><ul>
+<li><a href="http://www.apache.org/foundation/thanks.html">Thanks</a></li>
+<li><a href="http://www.apache.org/foundation/sponsorship.html">Become a Sponsor</a></li>
+</ul>
+</li>
+</ul>
+  </div>
+  
+  <div id="content">
+    <h1 class="title">Web Code Overview</h1>
+    <p><a name="WebCodeOverview-*GeneralOverview*"></a></p>
+<h2 id="general-overview"><em>General Overview</em></h2>
+<p>The code is broken up into multiple files, based on sections of the site
+(as divided up by the navigation area). There are also several general
+purpose files:
+<em> index.php -  This is the only file used in any URLs. It includes other
+files based on the passed in "mode".
+</em> states.php - builds an array of modes, which function should be called
+for each mode, and the part of the site each mode belongs to
+<em> utils.php - contains many functions that are common to several sections
+</em> errors.php - contains an array of all errors that can be reported by the
+site. I'm not sure how useful it was do set it up this way, but it's where
+things currently are. errors.php also contains the debug function that is
+used if the current user has an adminlevel of ADMIN_DEVELOPER in the user
+table.
+<em> secrets.php - contains all passwords/passphrases and secret and shared
+keys
+</em> conf.php - contains all configuration variables that might need to be
+modified for each install base
+* php5extras.php - anything that needs to be done differently when using
+php5 vs php4</p>
+<p><a name="WebCodeOverview-*SiteSecurity*"></a></p>
+<h2 id="site-security"><em>Site Security</em></h2>
+<p>The initial handling of form data within the code was quite insecure, and
+several areas of the site are still this way. After learning more about web
+security, I developed a security model based on "continuations". All of the
+pages have been converted to using continuations.</p>
+<p>Deep linking into the site is only allowed for modes in the $actions['entry']('entry'.html)
+ array in states.php. Anything else requires the submission of a
+continuation. For the most part, access to different parts of the site is
+controlled by what privileges you have in the Privileges section of the
+site. However, there are a few things controlled by a user's adminlevel
+field in the user table. The very earliest form of authorization was
+handled by the user's adminlevel field, and it has continued to be useful
+in a few situations.</p>
+<p>All form data passed in to the site should be verified very strictly.
+Unfortunately, that is not currently the case. All of the main pages
+available to the average user should have been updated to have strict
+validation, though other parts of the site have not made it yet. Most
+sections of the site have a single function (or a very small number of
+similar functions) that handle the processing of form data. This will make
+it easier to add better checks throughout the site as the number of
+locations needing to be modified is fairly small.</p>
+<p><a name="WebCodeOverview-*GeneralProcessingFlow*"></a></p>
+<h2 id="general-processing-flow"><em>General Processing Flow</em></h2>
+<p>Every time someone views the site, it is through index.php. This file
+defines several global variables and includes conf.php, states.php,
+errors.php, and utils.php. It then creates a database connection and calls
+initGlobals(), which among other things, determines $mode. Based on $mode,
+index.php determines which function needs to be called and assigns it to
+$actionFunction. Next, checkAccess() is called, followed by sendHeaders()
+and printHTMLHeader() (which doesn't actually print the header if $mode is
+in $noHTMLwrappers). set_error_handler is called if the current user has an
+adminlevel of ADMIN_DEVELOPER. Next, $actionFunction is finally called,
+followed by disconnecting from the database, a call to printHTMLFooter(),
+and a call to semUnlock() to make sure the semaphore was unlocked if it was
+locked somewhere in the process.</p>
+<p>One thing worth noting that initGlobals() does is to include other files
+based on which mode is being processed. This helps to prevent the php
+script engine from having to process unnecessary files. It also adds a
+small layer of security because a section of code cannot be attacked if it
+has not been included.</p>
+<p><a name="WebCodeOverview-*Continuations*"></a></p>
+<h2 id="continuations"><em>Continuations</em></h2>
+<p>Continuations are how the site handles sequences of pages. It also helps
+keep people from getting to parts of the site they aren't allowed to access
+or shouldn't jump in to the middle of (i.e. by using the browser's back
+button). Continuations are created by calling addContinuationsEntry, which
+accepts up to 6 arguments:
+<em> $nextmode - the mode that should be used when the continuation is
+submitted
+</em> $data - an array of any data that you would like to have available when
+the continuation is submitted
+<em> $duration - how long from "now" that the continuation should be valid (in
+seconds)
+</em> $deleteFromSelf - boolean - 1 if this is the start of a new sequence of
+pages, 0 if it will be a continuation of a sequence. If it is set to 0,
+then the "parent" continuation for this one is the continuation that the
+site is currently processing.
+<em> $multicall - boolean - whether or not the continuation may be submitted
+more than once
+</em> $repeatProtect - boolean - used in cases where a "sequence loop" can
+occur</p>
+<p>addContinuationsEntry returns a long encrypted string to be used as an
+identifier to be submitted (either as a hidden form field or in the URL for
+a GET link). What gets encrypted is a salt value, the id of the
+continuation that was created (or updated), the user's numeric id, and a
+timestamp. If the string gets tampered with, it will not decrypt properly.
+If someone tries to submit a continuation given to another user, their user
+ids won't match; so, it will be considered invalid.</p>
+<p>When a continuation is submitted, some checks are run and, if everything
+passes, whatever was submitted as $nextmode is the mode for which the site
+functions. One of those checks is that $duration has not expired; if it
+has, the user is given a notice that he has submitted expired data. Any
+data submitted as $data can be accessed by calling getContinuationsData()
+with a single argument being the index of the array that was passed to
+addContinuationsEntry. Additionally, getContinuationsData can be called
+with no arguments to get all of $data as a single array. If $multicall was
+set to 0, then the continuation is deleted. If $deleteFromSelf was also set
+to 0, then this continuation's parent will also be deleted. If
+$deleteFromSelf was set to 0 for the parent, it's parent will be deleted,
+and so on until a continuation is reached that had $deleteFromSelf set to
+1.</p>
+<p><a name="WebCodeOverview-*JavascriptandAJAX*"></a></p>
+<h2 id="javascript-and-ajax"><em>Javascript and AJAX</em></h2>
+<p>Efforts have been made to ensure the pages required for making and
+connecting to a reservation work without requiring any javascript. However,
+enhancements have been made to enrich those parts of the site if javascript
+is enabled. For some of the administrative parts of the site, javascript
+and AJAX have been used heavily, particularly the Privileges page. The <a href="http://dojotoolkit.org">Dojo Toolkit</a>
+ is what is being used for javascript widgets and to handle some of the
+AJAX.</p>
+<p><a name="WebCodeOverview-*AFewExamples*"></a></p>
+<h2 id="a-few-examples"><em>A Few Examples</em></h2>
+<p><a name="WebCodeOverview-*Addingalinktothenavigationarea*"></a></p>
+<h3 id="adding-a-link-to-the-navigation-area"><em>Adding a link to the navigation area</em></h3>
+<p>Here are the steps that would need to be done to add a new section of the
+site.</p>
+<p>First, modify states.php to add a new mode.
+1. create a new $actions['mode']('mode'.html)
+ with the name of your mode set to the name of the function that should be
+called
+1. create a new $actions['pages']('pages'.html)
+ with the name of your mode set to the name of the section this mode
+belongs to. This is only an internal identifier used to associate modes
+together.</p>
+<p>So, if your mode is named "examplemode", you could end up with these two
+lines being added:</p>
+<div class="codehilite"><pre><span class="nv">$actions</span><span class="p">[</span><span class="s">&#39;mode&#39;</span><span class="p">]</span>
+</pre></div>
+
+
+<p>['examplemode'] = "exampleFunc1";
+    $actions['pages']
+['examplemode'] = "exampleSection";</p>
+<p>While we're editing states.php, lets jump to the top and add our new mode to $actions['entry']('entry'.html)
+ so that it can be called directly without having to already be on the
+site. Just add 'examplemode' as a new item at the end of the array.</p>
+<p>The next thing to do is to actually add the functions. Lets place them in a
+new file called 'examples.php' in the .ht-inc directory. Our first function
+can be really simple and just print out some text. So, create examples.php
+with this in it:</p>
+<div class="codehilite"><pre><span class="cp">&lt;?php</span>
+<span class="k">function</span> <span class="nf">exampleFunc1</span><span class="p">()</span> <span class="p">{</span>
+   <span class="k">print</span> <span class="s2">&quot;exampleFunc1 successfully called.&lt;br&gt;</span><span class="se">\n</span><span class="s2">&quot;</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="cp">?&gt;</span><span class="x"></span>
+</pre></div>
+
+
+<p>There's one last thing we need to do before linking this in on the site. As
+described in the "General Processing Flow" section, initGlobals includes
+the required files based on the current mode's section. So, edit utils.php
+and scroll toward the end of it where files are included (using
+require_once) within a switch statement. In the switch statement, before
+the "default" case, add</p>
+<div class="codehilite"><pre><span class="k">case</span> <span class="s">&#39;exampleSection&#39;</span><span class="p">:</span>
+   <span class="n">require_once</span><span class="p">(</span><span class="s">&#39;.ht-inc/examples.php&#39;</span><span class="p">);</span>
+   <span class="n">break</span><span class="p">;</span>
+</pre></div>
+
+
+<p>Now, we're ready to actually add a link for this example function to the
+navigation area (of course, not all modes are linked to from the navigation
+area, but it is an easy example). To do this, edit utils.php and find the
+getNavMenu function close to the bottom of the file. We'll add our new mode
+to the end; so, find the "logout" part which should look something like
+this:</p>
+<div class="codehilite"><pre>if(<span class="p">$</span><span class="nv">inclogout</span>) <span class="err">{</span>
+   <span class="p">$</span><span class="nv">rt</span> .= menulistLI(&#39;authentication&#39;);
+   <span class="p">$</span><span class="nv">rt</span> .= &quot;<span class="nt">&lt;a</span> <span class="na">href=</span><span class="s">\&quot;&quot;</span> <span class="err">.</span> <span class="err">BASEURL</span> <span class="err">.</span> <span class="err">SCRIPT</span> <span class="err">.</span> <span class="err">&quot;?</span><span class="na">mode=</span><span class="s">logout\&quot;</span><span class="nt">&gt;</span>&quot;;
+   <span class="p">$</span><span class="nv">rt</span> .= &quot;Logout<span class="nt">&lt;/a&gt;&lt;/li&gt;</span>\n&quot;;
+}
+</pre></div>
+
+
+<p>We'll basically duplicate that (without the if conditional), changing a few
+things so that we add this right below it:</p>
+<div class="codehilite"><pre><span class="p">$</span><span class="nv">rt</span> .= menulistLI(&#39;exampleSection&#39;);
+<span class="p">$</span><span class="nv">rt</span> .= &quot;<span class="nt">&lt;a</span> <span class="na">href=</span><span class="s">\&quot;&quot;</span> <span class="err">.</span> <span class="err">BASEURL</span> <span class="err">.</span> <span class="err">SCRIPT</span> <span class="err">.</span> <span class="err">&quot;?</span><span class="na">mode=</span><span class="s">examplemode\&quot;</span><span class="nt">&gt;</span>&quot;;
+<span class="p">$</span><span class="nv">rt</span> .= &quot;Example Section<span class="nt">&lt;/a&gt;&lt;/li&gt;</span>\n&quot;;
+</pre></div>
+
+
+<p>Viewing the site should now show "Example Section" right under "Logout" in
+the navigation area. Clicking "Example Section" should cause "exampleFunc1
+successfully called." to be displayed in the main content area of the site.</p>
+<p><a name="WebCodeOverview-*Usingcontinuationswhensubmittingformdata*"></a></p>
+<h3 id="using-continuations-when-submitting-form-data"><em>Using continuations when submitting form data</em></h3>
+<p>Let's modify examplefunc1 so that it prints some form data that gets
+submitted with a continuation.</p>
+<p>So, change the contents of examplefunc1 to be:</p>
+<div class="codehilite"><pre><span class="p">$</span><span class="nv">options</span> = array(0 =&gt; &quot;option1&quot;,
+         1 =&gt; &quot;option2&quot;);
+print &quot;<span class="nt">&lt;FORM</span> <span class="na">action=</span><span class="s">\&quot;&quot;</span> <span class="err">.</span> <span class="err">BASEURL</span> <span class="err">.</span> <span class="err">SCRIPT</span> <span class="err">.</span> <span class="err">&quot;\&quot;</span> <span class="na">method=</span><span class="s">post</span><span class="nt">&gt;</span>\n&quot;;
+print &quot;Select one of these options:&quot;;
+printSelectInput(&quot;theoption&quot;, <span class="p">$</span><span class="nv">options</span>);
+<span class="p">$</span><span class="nv">cont</span> = addContinuationsEntry(&quot;submitFunc1Form&quot;, <span class="p">$</span><span class="nv">options</span>);
+print &quot;<span class="nt">&lt;INPUT</span> <span class="na">type=</span><span class="s">hidden</span> <span class="na">name=</span><span class="s">continuation</span> <span class="na">value=</span><span class="s">\&quot;</span><span class="p">$</span><span class="nv">cont</span><span class="s">\&quot;</span><span class="nt">&gt;</span>\n&quot;;
+print &quot;<span class="nt">&lt;INPUT</span> <span class="na">type=</span><span class="s">submit</span> <span class="na">value=</span><span class="s">Submit</span><span class="nt">&gt;</span>\n&quot;;
+print &quot;<span class="nt">&lt;/FORM&gt;</span>\n&quot;;
+</pre></div>
+
+
+<p>Now, we have a form that gets displayed when "Example Section" is clicked. 
+Now, we need to add a function to process that form.  Add this function to
+examples.php:</p>
+<div class="codehilite"><pre><span class="n">function</span> <span class="n">submitFunc1Form</span><span class="p">()</span> <span class="p">{</span>
+   <span class="nv">$data</span> <span class="o">=</span> <span class="n">getContinuationVar</span><span class="p">();</span>
+   <span class="nv">$theoption</span> <span class="o">=</span> <span class="n">processInputVar</span><span class="p">(</span><span class="s">&quot;theoption&quot;</span><span class="p">,</span> <span class="n">ARG_NUMERIC</span><span class="p">);</span>
+   <span class="k">if</span><span class="p">(</span><span class="o">!</span> <span class="n">array_key_exists</span><span class="p">(</span><span class="nv">$theoption</span><span class="p">,</span> <span class="nv">$data</span><span class="p">))</span> <span class="p">{</span>
+      <span class="k">print</span> <span class="s">&quot;invalid option submitted\n&quot;</span><span class="p">;</span>
+      <span class="k">return</span><span class="p">;</span>
+   <span class="p">}</span>
+   <span class="k">print</span> <span class="s">&quot;The option you selected was: &quot;</span><span class="p">;</span>
+   <span class="k">print</span> <span class="err">&quot;</span><span class="p">{</span><span class="nv">$data</span><span class="o">\</span><span class="p">[</span><span class="nv">$theoption</span><span class="o">\</span><span class="p">]</span>
+</pre></div>
+
+
+<p>}<br>\n";
+    }</p>
+<p>Next, we add this function to states.php:</p>
+<div class="codehilite"><pre><span class="nv">$actions</span><span class="p">[</span><span class="s">&#39;mode&#39;</span><span class="p">]</span>
+</pre></div>
+
+
+<p>['submitFunc1Form'] = "submitFunc1Form";
+    $actions['pages']
+['submitFunc1Form'] = "exampleSection";</p>
+<p>Now, click the "Example Section" link, select one of the options, and click
+Submit to see if it works.</p>
+<p><a name="WebCodeOverview-*UsingAJAXtodynamicallyupdateapage*"></a></p>
+<h3 id="using-ajax-to-dynamically-update-a-page"><em>Using AJAX to dynamically update a page</em></h3>
+<p>AJAX is very useful for dynamically updating page content.  Let's add
+something to examplefunc1 that can be updated with an AJAX call.</p>
+<p>Add this to the end of examplefunc1:</p>
+<div class="codehilite"><pre>print &quot;<span class="nt">&lt;br&gt;&lt;br&gt;</span>\n&quot;;
+print &quot;<span class="nt">&lt;div</span> <span class="na">id=</span><span class="s">examplediv</span><span class="nt">&gt;</span>\n&quot;;
+print &quot;This will get dynamically changed.<span class="nt">&lt;br&gt;</span>\n&quot;;
+print &quot;<span class="nt">&lt;/div&gt;</span>\n&quot;;
+<span class="p">$</span><span class="nv">cont</span> = addContinuationsEntry(&quot;AJexample&quot;);
+print &quot;<span class="nt">&lt;a</span> <span class="na">onclick=</span><span class="s">\&quot;JS_AJexample(&#39;</span><span class="p">$</span><span class="nv">cont</span><span class="s">&#39;);\&quot;</span><span class="nt">&gt;</span>Click to &quot;;
+print &quot;update<span class="nt">&lt;/a&gt;&lt;br&gt;</span>\n&quot;;
+</pre></div>
+
+
+<p>Next, we need to add the javascript function we just referenced to code.js
+(in .ht-inc's parent directory) as well as a callback function that will be
+called when the results of the AJAX call are returned:</p>
+<div class="codehilite"><pre><span class="n">function</span> <span class="n">JS_AJexample</span><span class="p">(</span><span class="n">contid</span><span class="p">)</span> <span class="p">{</span>
+   <span class="n">dojo</span><span class="o">.</span><span class="n">xhrPost</span><span class="p">({</span>
+      <span class="n">url:</span><span class="s">&#39;index.php&#39;</span><span class="p">,</span>
+      <span class="n">load:</span> <span class="n">JS_AJexampleCB</span><span class="p">,</span>
+      <span class="n">error:</span> <span class="n">errorHandler</span><span class="p">,</span>
+      <span class="n">content:</span> <span class="p">{</span><span class="n">continuation:</span> <span class="n">contid</span><span class="p">},</span>
+      <span class="n">timeout:</span> <span class="mi">15000</span>
+   <span class="p">});</span>
+<span class="p">}</span>
+
+<span class="n">function</span> <span class="n">JS_AJexampleCB</span><span class="p">(</span><span class="n">data</span><span class="p">,</span> <span class="n">ioArgs</span><span class="p">)</span> <span class="p">{</span>
+   <span class="nb">eval</span><span class="p">(</span><span class="n">data</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Then, we need to add a few things to states.php:</p>
+<p>to the $actions array:</p>
+<div class="codehilite"><pre><span class="nv">$actions</span><span class="p">[</span><span class="s">&#39;mode&#39;</span><span class="p">]</span>
+</pre></div>
+
+
+<p>['AJexample'] = "exampleFunc2";
+    $actions['pages']
+['AJexample'] = "exampleSection";</p>
+<p>to the $noHTMLwrappers array:</p>
+<div class="codehilite"><pre><span class="s">&#39;AJexample&#39;</span>
+</pre></div>
+
+
+<p>Now, we need to create exampleFunc2 (in examples.php):</p>
+<div class="codehilite"><pre><span class="n">function</span> <span class="n">exampleFunc2</span><span class="p">()</span> <span class="p">{</span>
+   <span class="k">print</span> <span class="err">&quot;</span><span class="n">document</span><span class="o">.</span><span class="n">getElementById</span><span class="p">(</span><span class="s">&#39;examplediv&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">innerHTML</span> <span class="o">=</span> <span class="err">&#39;</span><span class="n">Dynamic</span>
+</pre></div>
+
+
+<p>update';";
+    }</p>
+<p>Then, we do something we haven't seen before.  getDojoHTML (in utils.php)
+must be modified so that the correct dojo requires get set when we are in
+mode examplefunc1.  For a simple AJAX update, we only need the dojo.parser
+module to be loaded.  Since this is already loaded for some of the Group
+modes, just add another case statement under submitDeleteGroup so we have:</p>
+<div class="codehilite"><pre><span class="k">case</span> <span class="s">&#39;viewGroups&#39;</span><span class="p">:</span>
+<span class="k">case</span> <span class="s">&#39;submitEditGroup&#39;</span><span class="p">:</span>
+<span class="k">case</span> <span class="s">&#39;submitAddGroup&#39;</span><span class="p">:</span>
+<span class="k">case</span> <span class="s">&#39;submitDeleteGroup&#39;</span><span class="p">:</span>
+<span class="k">case</span> <span class="s">&#39;examplemode&#39;</span><span class="p">:</span>
+   <span class="nv">$dojoRequires</span> <span class="o">=</span> <span class="n">array</span><span class="p">(</span><span class="s">&#39;dojo.parser&#39;</span><span class="p">);</span>
+   <span class="n">break</span><span class="p">;</span>
+</pre></div>
+
+
+<p>We also have to add a case statement a little further down where the HTML
+is actually generated. Find "case 'submitDeleteGroup':" in the switch
+statement following the one we just modified, and add another case
+statement for examplemode so we have:</p>
+<div class="codehilite"><pre><span class="k">case</span> <span class="s">&#39;viewGroups&#39;</span><span class="p">:</span>
+<span class="k">case</span> <span class="s">&#39;submitEditGroup&#39;</span><span class="p">:</span>
+<span class="k">case</span> <span class="s">&#39;submitAddGroup&#39;</span><span class="p">:</span>
+<span class="k">case</span> <span class="s">&#39;submitDeleteGroup&#39;</span><span class="p">:</span>
+<span class="k">case</span> <span class="s">&#39;examplemode&#39;</span><span class="p">:</span>
+   <span class="nv">$rt</span> <span class="o">.=</span> <span class="s">&quot;&lt;style type=\&quot;text/css\&quot;&gt;\n&quot;</span><span class="p">;</span>
+</pre></div>
+
+
+<p>Since we modified code.js, to test this, you will need to hold Shift and
+click the reload button in your browser to force your browser to reload
+code.js.  "Click to update" will not show up as a normal link, but it
+should still be clickable.  You can use CSS to make it look like a normal
+link or give it an href="#"  if you want.</p>
+<p><a name="WebCodeOverview-*Awordaboutusingtabsforcodeindentation*"></a></p>
+<h2 id="a-word-about-using-tabs-for-code-indentation"><em>A word about using tabs for code indentation</em></h2>
+<p>All of the code has been indented using tabs (rather than spaces) except
+where code wraps to more than one line, in which case a combination of tabs
+and spaces are used.  This allows someone editing the code to set his tab
+width to whatever he prefers, but still allows code that wraps to multiple
+lines to line up correctly.  To do this, when you want to wrap code to
+another line, put a newline at the end of the one you are on just as you
+normally would.  Next, tab over from the beginning of the line until you
+are even with where the initial line of code started, then use spaces to
+line up this line with something in the line above it that makes sense. 
+I'll give an example.  Almost all of the queries are written on multiple
+lines like this:</p>
+<div class="codehilite"><pre><span class="o">=====------------------------------</span>
+     <span class="nv">$query</span> <span class="o">=</span> <span class="s">&quot;SELECT id, &quot;</span>
+        <span class="o">.</span>        <span class="s">&quot;name, &quot;</span>
+        <span class="o">.</span>        <span class="s">&quot;prettyname &quot;</span>
+        <span class="o">.</span> <span class="s">&quot;FROM image &quot;</span>
+        <span class="o">.</span> <span class="s">&quot;WHERE id &lt; 400 AND &quot;</span>
+        <span class="o">.</span>       <span class="s">&quot;OSid = 3&quot;</span><span class="p">;</span>
+<span class="o">=====------------------------------</span>
+</pre></div>
+
+
+<p>In this example, whitespace indicated by the = marks should be made of
+tabs, whitespace indicated by the - marks should be made of spaces.</p>
+<p><a name="WebCodeOverview-*InlineCodeDocumentation*"></a></p>
+<h2 id="inline-code-documentation"><em>Inline Code Documentation</em></h2>
+<p>Online documentation of the code is generated using Doxygen.  Each file
+that should be parsed to generate docs needs to have the following toward
+the top of it:</p>
+<div class="codehilite"><pre><span class="o">/**</span>
+ <span class="o">*</span> <span class="o">\</span><span class="n">file</span>
+ <span class="o">*/</span>
+</pre></div>
+
+
+<p>All functions should have a header above them that documents what it does. 
+The header should include the name of the function, a description of any
+parameters passed in, a description of anything returned, and a brief
+description of what the function does.  The format of the header is:</p>
+<div class="codehilite"><pre><span class="sr">////////////////////////////////////////////////////////////////////</span><span class="o">/</span>
+<span class="sr">//</span><span class="o">/</span>
+<span class="sr">//</span><span class="o">/</span> <span class="o">\</span><span class="n">fn</span> <span class="n">nameOfFunction</span><span class="p">(</span><span class="nv">$param1</span><span class="p">,</span> <span class="nv">$param2</span><span class="p">)</span>
+<span class="sr">//</span><span class="o">/</span>
+<span class="sr">//</span><span class="o">/</span> <span class="o">\</span><span class="n">param</span> <span class="nv">$param1</span> <span class="o">-</span> <span class="n">description</span> <span class="n">of</span> <span class="n">param1</span>
+<span class="sr">//</span><span class="o">/</span> <span class="o">\</span><span class="n">param</span> <span class="nv">$param2</span> <span class="o">-</span> <span class="n">description</span> <span class="n">of</span> <span class="n">param2</span>
+<span class="sr">//</span><span class="o">/</span>
+<span class="sr">//</span><span class="o">/</span> <span class="o">\</span><span class="k">return</span> <span class="n">description</span> <span class="n">of</span> <span class="n">datastructure</span> <span class="n">returned</span>
+<span class="sr">//</span><span class="o">/</span>
+<span class="sr">//</span><span class="o">/</span> <span class="o">\</span><span class="n">brief</span> <span class="n">short</span> <span class="n">description</span> <span class="n">of</span> <span class="n">what</span> <span class="n">the</span> <span class="n">function</span> <span class="n">does</span>
+<span class="sr">//</span><span class="o">/</span>
+<span class="sr">////////////////////////////////////////////////////////////////////</span><span class="o">/</span>
+</pre></div>
+
+
+<p>If the function doesn't receive any parameters or doesn't return anything,
+those sections can be omitted.</p>
+<p><a name="WebCodeOverview-*Authentication*"></a></p>
+<h2 id="authentication"><em>Authentication</em></h2>
+<p>Authentication has been somewhat modularized.  When a user loads the site,
+the initGlobals function checks to see if the user is logged in.  If not,
+the mode in which the site should function gets set to "selectauth".  Here,
+the user is prompted to select an authentication method to use to log in. 
+Authentication methods are configured in $authMethods which is in conf.php.
+ There are currently three authentication types that can be handled:
+redirect, ldap, and local.  Redirect types send the user to another site to
+handle their authentication, with the expectation that a cookie will be set
+and that knowledge of how to interpret that cookie is handled in
+initGlobals.  If an ldap or local method is chosen, the user is directed to
+a page displayed by printLoginPageWithSkin() (in authentication.php as are
+most of the following functions).  This function sets up the skin for the
+page to match the affiliation defined in $authMethods, and then calls
+printLoginPage().  printLoginPage() displays a form for the user to enter a
+userid and password.  The form is submitted and then processed by
+submitLogin().  If the authentication method is ldap based, ldapLogin() is
+called; if it is the local system, localLogin() is called.  Each of these
+functions tries to validate the user.  If it succeeds, a cookie named
+VCLAUTH is set, and the user is redirected to the main page of the site. 
+If it fails, the user is redirected back to the login page. <em>If you enter
+valid credentials, but still get redirected back to the login page, the
+first thing to check is whether or not the setcookie() call was reached,
+and if so, was the cookie actually set in your browser.</em></p>
+  </div>
+  
+  <div id="footer">
+    <div class="copyright">
+      <p>
+        Copyright &copy; 2012 The Apache Software Foundation, Licensed under 
+        the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.
+        <br />
+        Apache and the Apache feather logo are trademarks of The Apache Software Foundation.
+      </p>
+    </div>
+  </div>
+  
+</body>
+</html>



Mime
View raw message