%$Header: /home/dashley/cvsrep/e3ft_gpl01/e3ft_gpl01/webprojs/fboprime/docs/manual/manual.tex,v 1.36 2006/04/10 04:28:07 dashley Exp $ %----------------------------------------------------------------------------------- %Notational conventions: % o Software product names are placed in italics (\emph{}), both in % the text and in the index. % o Unix commands are placed in italics (\emph{}). % o Database table names are shown in italics (\emph{}), both in the text and % in the index. % o Database table field names are shown in italics (\emph{}). % o Include file names are shown in Courier-like text (\texttt{}). % o Standalone script names are shown in Courier-like text (\texttt{}). %----------------------------------------------------------------------------------- \documentclass[letterpaper,10pt,titlepage]{article} % %\pagestyle{headings} % \usepackage{amsmath} \usepackage{amsfonts} \usepackage{amssymb} \usepackage[ansinew]{inputenc} \usepackage[OT1]{fontenc} \usepackage{graphicx} \usepackage{makeidx} % % %Define certain conspicuous global constants. \newcommand{\productbasename}{FBO-Prime} \newcommand{\productversion}{0.1} \newcommand{\productname}{\productbasename{}-\productversion} % %New environments %The following environment is for the glossary of terms at the end. \newenvironment{docglossaryenum}{\begin{list} {}{\setlength{\labelwidth}{0mm} \setlength{\leftmargin}{4mm} \setlength{\itemindent}{-4mm} \setlength{\parsep}{0.85mm}}} {\end{list}} %% %The following environment is for the database table and field %documentation at the end. \newenvironment{docdbtblfielddef}{\begin{list} {}{\setlength{\labelwidth}{0mm} \setlength{\leftmargin}{10mm} \setlength{\itemindent}{-5mm} \setlength{\parsep}{0.85mm}}} {\end{list}} %% %Embarrassingly, I've forgotten why "makeindex" is necessary ... \makeindex % \begin{document} %----------------------------------------------------------------------------------- %"See" References %----------------------------------------------------------------------------------- %%%%% M %%%%% \index{Dawn Masternak|see{Masternak, Dawn}} \index{Eric Metzger|see{Metzger, Eric}} \index{Sunhee Metzger|see{Metzger, Sunhee}} %%%%% W %%%%% \index{Theresa Whiting|see{Whiting, Theresa}} \index{Dan Wynja|see{Wynja, Dan}} %----------------------------------------------------------------------------------- \title{\emph{\productname{}} Installation, Maintenance, and User Manual} \author{\vspace{1cm}\\David T. Ashley\\\texttt{dta@e3ft.com}\\\vspace{1cm}} \date{\vspace*{8mm}\small{Version Control $ $Revision: 1.36 $ $ \\ Version Control $ $Date: 2006/04/10 04:28:07 $ $ (UTC) \\ $ $RCSfile: manual.tex,v $ $ \\ \LaTeX{} Compilation Date: \today{}}} \maketitle %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %Abstract confirmed OK, DTA, 20060304. % \begin{abstract} This document describes in detail the \emph{\productbasename{}} web-based FBO support software, version \productversion{}\@. The document provides substantial technical detail and is suitable for server administrators, webmasters, and users. At present, \emph{\productbasename{}} software provides only web-based resource scheduling (for aircaft, simulators, and flight instructors)\@. However, in the future, it may be enhanced to provide additional functionality for FBOs or to provide support for the aviation community that almost always surrounds an FBO (such as by providing support for various types of aviation associations). The software is designed to run satisfactorily in the environment available through most web hosting companies on a shared Linux server. A single instance of the software has the capability to support only one FBO (and it uses only one \emph{MySQL} database)\@. However, an arbitrary number of instances of the software may be installed on a single server, supporting an arbitrary number of FBOs (with each instance using one \emph{MySQL} database). The software is offered under the GPL, and is free both monetarily and in an intellectual property sense. \end{abstract} \clearpage{} \pagenumbering{roman} %No page number on table of contents. \tableofcontents{} \clearpage{} \listoffigures \clearpage{} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %Force the page number to 1. We don't want to number the table of contents %page. % \setcounter{page}{1} \pagenumbering{arabic} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Introduction, Overview, and Miscellany} \label{siov0} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Acknowledgements} \label{siov0:sack0} I am very grateful to all of the following individuals and institutions: \begin{itemize} \item The original authors of \index{ORS@\emph{ORS}}\emph{ORS} \cite{bibref:p:ors}, who answered all questions by e-mail and were very supportive in this endeavor. Additionally, the designs of the \emph{\productbasename{}} web pages are heavily borrowed from \emph{ORS}\@. The authors of \emph{ORS} saved me \emph{much} design time in figuring out how to achieve the desired effects with HTML. \item \index{Masternak, Dawn}Dawn Masternak \cite{bibref:i:masternakdawn} for original ideas about reimplementing the website. \item \index{Whiting, Theresa}Theresa Whiting \cite{bibref:i:whitingtheresa} and \index{Wynja, Daniel}Dan Wynja \cite{bibref:i:wynjadaniel} for numerous technical, functionality, and usability observations and suggestions. \item \index{Metzger, Eric}Eric and \index{Metzger, Sunhee} Sunhee Metzger \cite{bibref:i:metzgereric} for allowing me to use the Marshall FBO as a testbed for this software. \item \index{Rostamian, Rouben}Rouben Rostamian \cite{bibref:i:rostamianrouben} for assistance with the simple expression for scheduling interval overlap (see Eq. \ref{eq:stbg0:sdov0:01}, p. \pageref{eq:stbg0:sdov0:01}). \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{History} \label{siov0:shis0} In 2005, the \index{Marshall Aviation Center}Marshall Aviation Center (hereinafter referred to as \index{MAC}\emph{MAC}) was succeeded by \index{Metzger's Aircraft Services}Metzger's Aircraft Services (hereinafter referred to as \index{MAS}\emph{MAS}) as the FBO at the Marshall, Michigan, USA airport. The web hosting and database development for MAC had been handled by \index{Kalamazoo Software}Kalamazoo Software \cite{bibref:com:kalsoft}\@. \index{Masternak, Dawn}Dawn Masternak \cite{bibref:i:masternakdawn}, the office manager at MAC, had been dissatisfied with Kalamazoo Software for these reasons: \begin{itemize} \item The base price of \$99/month for the web presence with a scheduler seemed high. \item Dawn had the subjective impression that MAS was being overbilled for website changes. Her impression was that changes requiring about 1/2 hour of time were typically billed for 1-2 hours. \end{itemize} MAC spent, on average, approximately \$2,000/year for the web presence with aircraft scheduler. For a small business, this is a significant expenditure. It was natural to investigate whether it could be done less expensively. When MAS assumed the FBO in 2005, the arrangement with Kalamazoo Software was discontinued, and MAS hosted the site with \index{Ashley, David}Dave Ashley \cite{bibref:i:ashleydavidt} using \index{ORS@\emph{ORS}}ORS \cite{bibref:p:ors} on an experimental basis. After a period of experimentation, it was determined that ORS would perform satisfactorily. Experimentally, the MAS website was moved to \index{Hagen Hosting}Hagen Hosting \cite{bibref:hagenhostingweb}. After a few weeks of hosting with Hagen Hosting, all user data was lost (and had to be restored by Dave Ashley) twice in one week. Correspondence with Hagen Hosting revealed that HTTP server issues that could not be quickly resolved were the root cause (these issues had caused difficulties for other customers as well). To prevent further hiccups, the MAS website was moved back to Dave Ashley. The nature of the technical hiccups with Hagen Hosting was probably that an HTTPD process was dying unexpectedly. Because ORS works by fully reading and then fully writing files, HTTPD processes that die unexpectedly could result in truncated or incompletely written data files. The file that was damaged when the site was hosted with Hagen Hosting was truncated to zero length twice in one week. The technical design of ORS is sound, but an implementation using a \index{MySQL@\emph{MySQL}}\emph{MySQL} \cite{bibref:c:mysql} database would be more resilient with respect to dying HTTPD processes (and hence might be more reliable on a heavily-loaded server). In January of 2006, the ORS source code was examined in detail by Dave Ashley with the aim of customizing it to provide more user privacy and meet other goals of MAS\@. It was determined that it wasn't a good investment to modify the source code, and instead it was decided to rewrite the resource scheduler from scratch as a \emph{MySQL} implementation. \emph{\productbasename{}} (the software described in this document) is the rewrite. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Suboptimal Characteristics of ORS} \label{siov0:ssco0} It was determined (in 2005 and 2006) that ORS \cite{bibref:p:ors} has the following characteristics that make it suboptimal for use by MAS: \begin{enumerate} \item The file-based database implementation is vulnerable to dying HTTPD processes, and may make the product unsuitable for hosting on heavily-loaded servers (which would impede the ability to move the MAS site to a professional web hosting company). \item Performance issues include: \begin{enumerate} \item Scheduler page loads were sometimes noticeably slow, taking several seconds (but at other times taking less than a second). \item The file-based implementation requires that \emph{all} data be read on every page load ($O(N)$ or worse). \item The mutual exclusion mechanism (a lockfile to prevent others processes from reading any scheduler file) has performance disadvantages in a heavy usage environment. \item Regular maintenance (backups, database pruning) is integrated with the page loads. This also contributes to slow page loads. \end{enumerate} \item There may be security issues, as some of the files intended to be PHP include files can be directly executed by forming an appropriate URL\@. It is unclear what attacks may be possible. \item The paradigm of user privacy isn't what MAS desires. It is possible for users to get unnecessary and potentially private information about other users. Specific information that shouldn't be obtainable in the MAS environment includes: \begin{itemize} \item A list of the other users (no relevance to a customer scheduling an airplane, simulator, and/or instructor). \item Identity of person reserving aircraft at various times (no relevance to a person scheduling an airplane, simulator, or instructor). \item Comments included with the reservation (for discovery flights, this often involves names and phone numbers---not relevant to other customers). \end{itemize} \item For members of the line crew working at MAS, the authentication timeout period is too short (as an employee works behind the counter during a business day, they need to authenticate \emph{several} times). \item The way in which the hours of a day's schedule are displayed means that the late night and early morning hours can't be easily viewed. It would be helpful to have scheduling views that are more ``free form'' where: \begin{itemize} \item One can freely scroll forward and backwards in time, without respect to time and calendar boundaries. \item One can freely zoom in and out, obtaining finer and coarser views of scheduling. \end{itemize} \item The calendaring system makes it awkward to move around between dates. It seems that a calendar with one or more months displayed and where one can directly click on a day of interest might be easier to use. \item The display of half-hours is awkward (the ``:30'')\@. A simpler method is to textually display only whole hours but have it clear by the geometry (i.e. where rectangles begin) whether a reservation begins on a whole or half hour. \item Aircraft/simulators and flight instructors have to be scheduled separately, even for a simple instructional appointment. \item The ORS notion of ``hiding'' aircraft a user can't schedule is a good one, but there are those occasions where the user wants to see aircraft they can't schedule, so there needs to be an override available to the user. (Example: maybe a user can't fly a multi-engine aircraft, but they want to get a quick ride somewhere in such an aircraft with a flight instructor. In this case it would help to figure out the availability of the aircraft before making a phone call.) \item Users like \emph{Line}, \emph{Crew}, or \emph{Maint} are awkward (they require a separate account under ORS). Instead, users should always log in as themselves (i.e. authentication tied to the individual, always), and some users should by default have things they schedule appear as a ``pseudo-user'' such as \emph{Line}, \emph{Crew}, or \emph{Maint}. It is also important that they be able to schedule as themselves---this covers the case where a line employee is taking flight lessons, and perhaps other cases as well. \item Storing passwords in the clear is ill-advised. The more modern way of thinking is hashed storage with password test and reset ability only. \item ORS isn't the right framework for expansion to meet the other needs of MAS (such as electronic maintenance of student training records, support of other aviation organizations associated with the FBO, etc.). \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Software and Documentation License} \label{siov0:slic0} The \emph{\productbasename{}} software and all associated documentation (including this document) is licensed under the \index{GNU Public License (GPL)}GNU Public License \cite{bibref:gnuorgweb}. The software is free both in a monetary and in an intellectual property sense. Please note that the GPL may impose the requirement that if the source code is modified, the modifications be made available publicly. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Obtaining the Software} \label{siov0:sosw0} The software is viewable via \emph{ViewCVS}, and later the server will be set up to make nightly tarballs of the tip of the CVS archives and perhaps also to allow anonymous CVS access. This will be finalized when the software is more mature. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Requesting Changes to this Document} \label{siov0:scdo0} I'm very sensitive to issues of readability, organization, and indexing. Please forward suggestions for simple changes (typographical mistakes, grammar issues, indexing issues, etc.) to me (Dave Ashley \cite{bibref:i:ashleydavidt}). For more complex changes or enhancements (such as the rewrite or addition of a paragraph or section), you might consider modifying the \LaTeX{} source code directly and e-mailing me the entire document or the rewritten/added section. (There is, of course, a small possibility that I would reject a change---so advance coordination about the proposed changes would be prudent.) This document is maintained under a version control system (note the revision information on the title page), so changes are very easy to accommodate. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Feature Wish List} \label{siov0:sfwl0} The following features will be incorporated in future releases of \emph{\productbasename{}}: \begin{enumerate} \item \textbf{Demonstration mode:} a configuration constant that will allow the software to be run on a demonstration website to demonstrate its capabilities. Demonstration mode would include login without authentication and automatic periodic purge of data. \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Software Recommendations} \label{siov0:ssrc0} TBD\@. (This section is reserved for recommendations concerning software an FBO might use to maintain a website.) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Hosting Company Recommendations} \label{siov0:shrc0} TBD\@. (This section is reserved for recommendations for hosting companies that provide hosting plans and equipment known to work well with \emph{\productbasename{}}.) %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Theory of Operation, Installation, and Maintenance} \label{sins0} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Theory of Operation} \label{sins0:sots0} Logically, the server source code is composed of three components: \begin{itemize} \item A set of PHP scripts that are executed in response to HTTP requests (described in \S{}\ref{swpg0}, p. \pageref{swpg0}). These files all reside in the same directory of an \emph{Apache} \emph{DocumentRoot} or are \emph{Alias}'d or \emph{ScriptAlias}'d into the \emph{Apache} namespace. All of these files have the extension \emph{.php}. \item A set of PHP library files that are included and used by the \emph{.php} files (described in \S{}\ref{sphl0}, p. \pageref{sphl0}). All of these files have the extension \emph{.inc}. \item A set of standalone PHP utility scripts that can be executed to perform various utility functions (described in \S{}\ref{ssas0}, p. \pageref{ssas0}). These scripts are designed to be executed from a shell or a cron job. These utility scripts can be located anywhere except where they can be executed in response to HTTP requests, but the recommended location is with the PHP library files. All of these utility scripts have the extension \emph{.php}. \end{itemize} The \emph{\productbasename{}} software works in the following way: \begin{itemize} \item Some \emph{.php} scripts (\S{}\ref{swpg0}) are executed in response to web visits. These \emph{.php} scripts allow users and administrators to view and modify user and scheduling information using a web browser. \item Some utility \emph{.php} scripts (\S{}\ref{ssas0}) are executed periodically by the *nix system, normally via \emph{cron}. These scripts perform database maintenance and promote standby reservations. \item Some utility \emph{.php} scripts (\S{}\ref{ssas0}) are manually executed in special circumstances (for example, to initialize the database or if an administrator password is lost). \item All \emph{.php} scripts may include \emph{.inc} files (\S{}\ref{sphl0}) in the PHP library. (These include files are shared between all PHP scripts, and provide a way to localize functionality so that changes need to be made in only one place.) \item All \emph{.php} scripts may interact with the \emph{MySQL} server (by executing SQL queries) in order to store, modify, and retrieve user and scheduling information. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Administrator Requirements} \label{sins0:sarq0} The instructions in this document assume that the individual attempting to install \emph{\productbasename{}} has solid Unix administration skills. The individual attempting to install \emph{\productbasename{}} must have these skills: \begin{itemize} \item An understanding of Unix file and directory permissions, including: \begin{itemize} \item \index{UID}UID, \index{GID}GID, and the standard Unix file and directory permission bits. \item \index{chmod@\emph{chmod}}\emph{chmod}, \index{chown@\emph{chown}}\emph{chown}, and other commands used to modify Unix file and directory permission bits. \end{itemize} \item An understanding of standard Unix commands, including \index{cp@\emph{cp}}\emph{cp}, \index{mv@\emph{mv}}\emph{mv}, \index{rm@\emph{rm}}\emph{rm}, and \index{tar@\emph{tar}}\emph{tar}. \item An rudimentary understanding of how dynamic web content is generated and served, including \index{Apache@\emph{Apache}}\emph{Apache}. \item A rudimentary understanding \index{SQL}\emph{SQL} and \emph{MySQL}. \end{itemize} Attaining competence in Unix sufficient to install \emph{\productbasename{}} is not trivial, especially if one has no experience with Unix systems. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Server System Requirements} \label{sins0:ssyr0} In order to run the \emph{\productname{}} software, the \index{server requirements}server must meet the following specifications. \begin{itemize} \item \emph{Linux} (necessary version uncertain). \item \emph{Apache} (necessary version uncertain). \item \emph{MySQL} (necessary version uncertain). \item \emph{PHP} (necessary version uncertain). \item The server must be configured so that \emph{cron} jobs can be run. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Server Software Installation Instructions} \label{sins0:sssi0} This section contains precise instructions for installing the \emph{\productbasename{}} software on a server. The server must meet the requirements in \S{}\ref{sins0:ssyr0}. The steps in installing the \emph{\productbasename{}} software are: \begin{enumerate} \item Choose the path where the \emph{PHP} web files, \emph{PHP} library files, and web graphics will be placed (\S{}\ref{sins0:sssi0:spwg0}, p. \pageref{sins0:sssi0:spwg0}). \item Set up the \emph{MySQL} database software (\S{}\ref{sins0:sssi0:smsq0}, p. \pageref{sins0:sssi0:smsq0}). \item Set up the \emph{Apache} web server software (\S{}\ref{sins0:sssi0:sapc0}, p. \pageref{sins0:sssi0:sapc0}). \item Unpack the \emph{\productbasename{}} software (\S{}\ref{sins0:sssi0:susc0}, p. \pageref{sins0:sssi0:susc0}). \item Generate the \emph{\productbasename{}} hash key (\S{}\ref{sins0:sssi0:sgsh0}, p. \pageref{sins0:sssi0:sgsh0}). \item Customize the PHP library include path (\S{}\ref{sins0:sssi0:sphl0}, p. \pageref{sins0:sssi0:sphl0}). \item Customize the web page script include path (\S{}\ref{sins0:sssi0:scwp0}, p. \pageref{sins0:sssi0:scwp0}). \item Customize the \emph{MySQL} database access constants (\S{}\ref{sins0:sssi0:sdac0}, p. \pageref{sins0:sssi0:sdac0}). \item Initialize the \emph{MySQL} database (\S{}\ref{sins0:sssi0:sdin0}, p. \pageref{sins0:sssi0:sdin0}). \item Perform the functionality tests (\S{}\ref{sins0:sssi0:sftt0}, p. \pageref{sins0:sssi0:sftt0}). \item Customize the default FBO information (\S{}\ref{sins0:sssi0:scdf0}, p. \pageref{sins0:sssi0:scdf0}). \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Choice of PHP Source File, PHP Library, and Graphics Paths} \label{sins0:sssi0:spwg0} Server environments vary considerably. For example: \begin{itemize} \item On a server owned by the FBO, there is generally full freedom in locating files (such as \index{PHP library}PHP library files). \item On a server owned by a web hosting company, there is generally very little freedom in locating files (such as PHP library files). Typically, all locations are specified by the web hosting company. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph{PHP Source File Path} First, choose where to locate the PHP source files (these are the files that are executed in response to HTTP requests---see \S{}\ref{swpg0}, \pageref{swpg0}), and record this choice to use in later installtion steps. All of the files identified in \S{}\ref{swpg0} must be located in the same directory. For an FBO with website \texttt{http://myfbo.com}, a typical choice for a URL to access the flight scheduler would be\\\\ \texttt{http://myfbo.com/flightschedule}.\\\\ This URL has associated with it a path on the server (usually, below the Apache \index{Apache@\emph{Apache}!DocumentRoot directive@\emph{DocumentRoot} directive}% \index{DocumentRoot (Apache directive)@\emph{DocumentRoot} (Apache directive)}\emph{DocumentRoot}). In this case, the server directory to contain the PHP source code should be chosen and created; permissions should be checked to ensure that the Apache server can read the files; and the choice should be recorded for later installation steps. A second common choice is to locate the flight scheduler at a URL of the form \texttt{http://flightschedule.myfbo.com}. The mechanics of setting up DNS and Apache are not discussed here. If you are an inexperienced Unix administrator, I recommend that you make the simpler choice described in the paragraph above. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph{PHP Library Path} The PHP library path is the path where the PHP interpreter searches for files specified in the PHP \emph{include()} and \emph{require()} commands. The likely PHP library path chosen varies depending on whether the server is owned. For an server owned by the FBO, a typical choice is to place the library include files in a subdirectory of the path specified in the \emph{php.ini} file. For a server owned by a hosting company, a typical choice is anywhere not aliased into Apache's URL space.\footnote{In other words, web clients should not be able to choose a URL so as to point to the PHP library files.} This choice should be made, the directory should be created, and permissions should be set so that Apache can read but not modify the files, and the choice should be recorded. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \paragraph{Graphics File Path} \emph{\productbasename{}} has some graphics (logos, arrows, icons, etc.) that must be loadable by a browser. These files must all be together in the same directory. A typical choice for a location for these graphics is\\\\ \texttt{http://myfbo.com/fboprimegraphics}.\\\\ The necessary directory should be created on the server, permissions should be set appropriately, and the base URL of the graphics should be recorded. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{\emph{MySQL} Database Setup} \label{sins0:sssi0:smsq0} Setup of \index{MySQL@\emph{MySQL}!Setup for \productbasename{}@Setup for \emph{\productbasename{}}}% \emph{MySQL} involves obtaining a database name, userid, and password. (This is the only information required to set up \emph{\productbasename{}}---creation of database tables is handled by a script.) The steps to set up \emph{MySQL} depend on how the software is hosted. \begin{itemize} \item If the software is hosted by a hosting company, the \emph{MySQL} database name, userid, and password will probably be assigned by the hosting company. \item If the software is hosted on an owned or dedicated server, the setup must be performed by the individual installing \emph{\productbasename{}}. \end{itemize} If the software is hosted on an owned or dedicated server, the following steps should be used to set up \emph{MySQL}: \begin{enumerate} \item Choose a database name, userid, and password for use with \emph{MySQL}. In subsequent description, these are denoted \emph{dbname}, \emph{userid}, and \emph{password}. \item Log into \emph{MySQL} as the root user.\footnote{Note that the \emph{root} password for \emph{MySQL} is not the same thing as the \emph{root} user password for \emph{Linux}.} The command to do this is: \texttt{mysql --user=root -p} \item Create the database. The \emph{MySQL} command to do this is: \texttt{create database \emph{dbname};} \item Grant the user \emph{userid} all privileges on database \emph{dbname} using password \emph{password} when connecting from \emph{localhost}.\footnote{The normal arrangement is that the \emph{MySQL} daemon runs on the same server as \emph{Apache}, hence the connection from \emph{localhost}.} The command to do this is: \texttt{grant all on \emph{dbname}.* to \emph{userid}@localhost\\identified by '\emph{password}';} \item Log out of \emph{MySQL} (Control-D). \item Test the permissions created by running \texttt{mysql --user=\emph{userid} -p} and entering the \emph{password} chosen. Issue the command: \texttt{use database \emph{dbname};} to verify permission to access \emph{dbname}. \item Log out of \emph{MySQL} (Control-D). \end{enumerate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{\emph{Apache} Setup} \label{sins0:sssi0:sapc0} \index{Apache@\emph{Apache}!Setup for \productbasename{}@Setup for \emph{\productbasename{}}}% As with \emph{MySQL}, the setup of \emph{Apache} is more complex for an owned or dedicated server. Details TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Unpacking of \emph{\productbasename{}} Source Code} \label{sins0:sssi0:susc0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Generation of \emph{\productname{}} Hash Key} \label{sins0:sssi0:sgsh0} The \emph{\productbasename{}} hash key must be defined in a file in the PHP library named \emph{sitehashkey.inc}. The \index{sitehashkeygen.php@\emph{sitehashkeygen.php}}\texttt{sitehashkeygen.php} script (\S{}\ref{ssas0:shkg0}, p. \pageref{ssas0:shkg0}) should be used to generate this file automatically. Simply execute the \texttt{sitehashkeygen.php} script with the path to the PHP library as the only parameter, then review permissions on the \emph{sitehashkey.inc} file for appropriateness. It would also be possible to generate the \emph{sitehashkey.inc} file manually (although there should be no reason to do this). The recommended approach would be to replicate the file contents shown in Figure \ref{fig:ssas0:shkg0:00} (p. \pageref{fig:ssas0:shkg0:00}), but with the key chosen randomly (perhaps by typing random keystrokes in the text editor). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Customization of Include Path in PHP Library Files} \label{sins0:sssi0:sphl0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Customization of Include Path in Web Pages} \label{sins0:sssi0:scwp0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Customization of \emph{MySQL} Database Access Constants} \label{sins0:sssi0:sdac0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Database Initialization} \label{sins0:sssi0:sdin0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Functionality Tests} \label{sins0:sssi0:sftt0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Customization of Default FBO Information} \label{sins0:sssi0:scdf0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Maintenance and Other Procedures} \label{sins0:smpr0} This section contains the precise instructions for installing the \emph{\productname{}} software on a server. The server must meet the requirements in \S{}\ref{sins0:ssyr0}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Backing Up \emph{MySQL} Database Contents} \label{sins0:smpr0:sbak0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Backing Up FBO Web Content} \label{sins0:smpr0:sbak1} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Restoring \emph{MySQL} Database Contents} \label{sins0:smpr0:sres0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Restoring FBO Web Content} \label{sins0:smpr0:sres1} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Upgrading to a Newer Version of \emph{\productbasename{}}} \label{sins0:smpr0:sugd0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Technical Background} \label{stbg0} This section provides technical background that may be useful in understanding the \emph{\productbasename{}} software. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The Site Hash Key} \label{stbg0:sshk0} \index{site hash key}In order to provide security for hashed passwords, session identifiers, and other constructs, the \emph{\productbasename{}} software must have available a string (or equivalently, a number) that is not available to non-administrative users of the software. This string is called the \emph{site hash key}. It is most convenient to generate the site hash key using the \texttt{sitehashkeygen.php} script, described in \S{}\ref{ssas0:shkg0}, p. \pageref{ssas0:shkg0}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{The MD5 Message Digest Algorithm} \label{stbg0:smdf0} \index{MD5 message digest algorithm}The MD5 message digest algorithm \cite{bibref:rfc1321} is a cryptographic hash algorithm. The most important properties of the algorithm are described in the executive summary of \cite{bibref:rfc1321}: \begin{quote} \emph{This document describes the MD5 message-digest algorithm. The algorithm takes as input a message of arbitrary length and produces as output a 128-bit ``fingerprint'' or ``message digest'' of the input. It is conjectured that it is computationally infeasible to produce two messages having the same message digest, or to produce any message having a given prespecified target message digest. The MD5 algorithm is intended for digital signature applications, where a large file must be ``compressed'' in a secure manner before being encrypted with a private (secret) key under a public-key cryptosystem such as RSA.} \end{quote} The statement that ``\emph{it is computationally infeasible to produce two messages having the same message digest, or to produce any message having a given prespecified target message digest}'' means that it is conjectured infeasible to ``work backwards'' from a message digest to a message having that digest except by generating random messages. Even by generating random messages and evaluating their MD5 message digest at the rate of a billion ($10^9$) messages per second (an unattainable rate on a single computing platform), the expected time to find a message with a prespecified message digest is 5 trillion billion years. The MD5 message digest function is ``one-way'' in that it is very inexpensive to find the MD5 message digest given a message, but intractable to find a viable message given its MD5. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{\productbasename{}} Cryptographic Hash Functions} \label{stbg0:sfch0} The \emph{\productbasename{}} software provides a cryptographic hash function used extensively in the software and denoted the \index{site hash function}\emph{site hash function} or \index{SHF}\emph{SHF}\@. The SHF function maps from an arbitrary number of input strings to an MD5 message digest. The SHF is designed so that a potential attacker cannot determine the MD5 message digest that would be generated from a set of input strings. In order to accomplish this behavior, the input strings are ``mixed'' with the \index{site hash key} before the MD5 message digest is calculated. If $s_i$ denotes the $i$th input string, $n$ denotes the number of input strings, $h$ denotes the site hash key, and ``$+$'' denotes string concatenation, the hash function used is \begin{eqnarray} \nonumber & SHF(s_1, s_2, s_3, \ldots{}, s_n)& \\ \label{eq:stbg0:sfch0:00} & = & \\ \nonumber & MD5(h + s_1 + h + s_2 + h + s_3 + \ldots{} + s_n + h) . & \end{eqnarray} Note that given the input strings $s_1 \ldots{} s_n$, an attacker cannot predict $SHF(s_1 \ldots{} s_n)$ without knowledge of the site hash key. Note also that an attacker cannot deduce the site hash key by observing a number of sets of strings and the corresponding $SHF()$ output. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Password Storage} \label{stbg0:spst0} \index{password}Although unsafe computing practice, it is anticipated that some users will use the same passwords for \emph{\productbasename{}} as they use for other systems (such as e-mail and banking). It is unwise to store \emph{\productbasename{}} passwords on the server in the clear, in case the server is compromised or in the case of misconduct by employees of the FBO or the hosting company. Current doctrine with respect to password storage is: \begin{itemize} \item Passwords should not be stored on the server. Instead, only cryptographic hashes of the passwords should be stored. \item \index{salt}``Salt''\footnote{Some element of uncontrollability or randomness.} should be applied to cryptographic hash generation. Without salt, two negative circumstances are possible: \begin{itemize} \item It may be possible to determine if two users have the same password (because the stored cryptographic hashes are identical). \item Dictionary attacks may become easier. (Salt makes dictionaries difficult to build.) \end{itemize} \item It should not be technically possible to view passwords. \item Users and administrators should only be able to verify and reset passwords (never to view them). \end{itemize} The algorithm used for password storage in \emph{\productbasename{}} is: \begin{itemize} \item When a user account is created, an SGUID and other random elements are used to create 128 bits of ``salt''. This salt is stored with the user record. \item The password information stored is the SHF of the user's salt and the password. \end{itemize} In order for an attacker to glean information about a user's password based on information stored on the server: \begin{itemize} \item The site hash key would need to be compromised. \item The user's salt would need to be compromised. \item Even with the two previous conditions met, the only attack possible is a dictionary attack.\footnote{The dictionary database could not be built until the site hash key and user's salt were compromised. Additionally: \begin{itemize} \item Due to the salt, the dictionary would apply to only one user. \item It would not be possible to determine whether two users have the same password. \end{itemize}} \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Unix Time vs. Scheduling Time} \label{stbg0:sutv0} Traditionally, time in Unix systems has been represented as integer seconds since the \index{Unix epoch}\index{epoch}Unix epoch, where the Unix epoch is defined as 00:00:00 \index{UTC}UTC on January 1, 1970. Unix systems overall perform well, but there are occasional glitches---for example, a carelessly-written Unix \emph{cron} job might run twice or not at all as \index{daylight savings time}daylight savings time comes or goes. Note that traditional Unix time does not include the notion of daylight savings time. UTC is never adjusted in this way. Only the offset of local time with respect to UTC changes. It would be possible to have the resource scheduler use the traditional Unix time. There would be two disadvantages to such an approach: \begin{enumerate} \item GET and POST parameters would not be human-friendly (making debugging more difficult). \item There would be complexity in handling reservations near the transitions to and from daylight savings time. \end{enumerate} For these reasons, this software uses two time schemes: \begin{itemize} \item For \index{SGUID}SGUIDs (\S{}\ref{stdd0:sdty0:sgui0}, p. \pageref{stdd0:sdty0:sgui0}) and other special purposes where only time ordering is required, the software uses traditional Unix time. \item For reservation scheduling (see \index{STIME}STIME, \S{}\ref{stdd0:sdty0:stim0}, p. \pageref{stdd0:sdty0:stim0}), an abstract representation of local time is used. This abstract representation does not consider daylight savings time. \end{itemize} In behavior, the scheduler resembles a large piece of paper with many squares. There is no allowance made for the extra hour or missing hour that accompany daylight savings time. This means that reservations spanning the transition may be longer or shorter by one hour than the scheduler calculates. In practice, this is not likely to be a problem, as very few pilots fly a rental plane at 2 a.m. The Unix notion of time and the scheduler's notion of time intersect at these places: \begin{itemize} \item The time and date displayed by the scheduler as the current time and date. \item Time of day and date assumed for deciding which calendar day and which portion of the day to display. \item Time of day used for deciding if a user is trying to schedule or cancel a reservation too close to the time of the reservation. \end{itemize} It is anticipated that this software may be run on a server not in the same \index{locale (time)}locale as the FBO. For this reason, the software can be customized to use as the current time either: \begin{itemize} \item The server local time with an optional offset. \item UTC (GMT) time with an optional offset. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Time Interval Conventions} \label{stbg0:stic0} The \emph{\productbasename{}} software deals extensively with \index{time interval}time intervals. It is useful---and it prevents mistakes---to have a formal definition of what is intended by an interval. For example, if \emph{Student A} reserves an airplane from 2 p.m. to 3 p.m., and \emph{Student B} reserves the same airplane from 3 p.m. to 4 p.m., which student has the airplane at exactly 3 p.m.?\footnote{Answer: \emph{Student B}, and the rationale follows.} The convention used in the \emph{\productbasename{}} software is that reservation intervals are \index{closed interval}\index{interval!closed}closed on the left and \index{open interval}\index{interval!open}open on the right, that is, a scheduling interval from $t_0$ to $t_1$ encompasses all values or time $t$ such that \begin{equation} t \in [ t_0, t_1), \end{equation} \noindent{}or, equivalently but using different notation, \begin{equation} t_0 \leq t < t_1 . \end{equation} At first glance, it may seem frivolous to pay so much attention to this definition. However, in the formation of SQL queries and in definitions such as \emph{adjacency} or \emph{overlap}, uncertain definitions lead to software with uncertain behavior. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Definition of Overlapping Intervals} \label{stbg0:sdov0} \index{overlapping intervals}\index{interval!operlapping}Two time intervals \begin{equation} \label{eq:stbg0:sdov0:000} \overline{c} = [c_0, c_1) \end{equation} \noindent{}and \begin{equation} \label{eq:stbg0:sdov0:0000} \overline{w} = [w_0, w_1) \end{equation} \noindent{}overlap if there can be found some value of time $t$ which is in both intervals, i.e. \begin{equation} \label{eq:stbg0:sdov0:00} \exists t : t \in \overline{c} \wedge t \in \overline{w} . \end{equation} It can be shown that a simple test\footnote{Thanks to Rouben Rostamian \cite{bibref:i:rostamianrouben} for his post to the \texttt{sci.math} newsgroup containing this expression.} for overlap is \begin{equation} \label{eq:stbg0:sdov0:01} (c_0 < y_1) \wedge (y_0 < c_1) . \end{equation} It is also possible and potentially desirable to generalize the notion of a reservation to include \index{reservations!zero-length}zero-length reservations where $t_0 = t_1$. If this is done, we must accept the $t_0=t_1$ case as an idiom for $[t_0, t_1]$\footnote{Rather than for $[t_0, t_1)$, which wouldn't make sense with $t_0=t_1$}. In this case, the notion of overlap presented in (\ref{eq:stbg0:sdov0:00}) can still be applied. It is believed that the simplest expression for overlap of two potentially zero-length reservations is \begin{equation} \label{eq:stbg0:sdov0:02} ((c_0 < y_1) \wedge (y_0 < c_1)) \vee (c_0 = y_0) . \end{equation} No special results have been obtained for evaluating more than two intervals for overlap. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection[\mbox{\protect$O(\log N)$}, \mbox{\protect$O(N)$}, and \mbox{\protect$O(N^2)$}] {\mbox{\protect\boldmath$O(\log N)$}, \mbox{\protect\boldmath$O(N)$}, and \mbox{\protect\boldmath$O(N^2)$}} \label{stbg0:sonn0} \index{O() notation@$O()$ notation}``$O()$'' notation comes from computer science, and denotes an upper bound on the number of steps required to perform a calculation or to execute an algorithm (such as a database search algorithm)\@. In this context, $N$ is used to denote some parameter that can be varied to represent more difficulty, such as more records in a database or more records to sort. In designing the \emph{\productbasename{}} software, it is natural to be concerned with the performance of the software as the number of records (users, resources, reservations) increases. This is especially relevant because ORS had performance problems. The nature of an $O(N)$ algorithm is easiest to comprehend. An $O(N)$ algorithm is normally an algorithm where a fixed amount of processing is performed for each of $N$ items. For example, reading $N$ items from a file tends to be an $O(N)$ operation. If it takes one second for a computer to read 1,000 items, it might be reasonable to expect it to take two seconds to read 2,000 items. An $O(\log N)$ operation is an operation where the time to complete the operation varies roughly as the logarithm of the number of elements. For example, if it takes one second for a computer to perform an operation on 10 elements and two seconds on 100 elements; it might be reasonable to expect it to take three seconds on 1000 elements.\footnote{$\log 10 = 1$, $\log 100 = 2$, and $\log 1000 = 3$.} An $O(N^2)$ is an operation where the time to complete the operation varies roughly as the square of the number of elements. For example, if it takes one second for a computer to perform an operation on 10 elements, it would be reasonable to expect it to take four seconds on 20 elements and nine seconds on 30 elements. Note that $O(N^2)$ operations are frequently created (usually accidentally!) by nested loops over data, such as occur in the classic rock/bubble sorts. $O(N^2)$ algorithms are \emph{extremely} undesirable. It is easy to see that $O(\log N)$ algorithms are more desirable than $O(N)$ algorithms, which are in turn more desirable than $O(N^2)$ algorithms. The goal in designing the database for \emph{\productbasename{}} is to ensure as much as possible that all database queries require $O(\log N)$ time to execute, rather than $O(N)$ or $O(N^2)$ time. $O(\log N)$ behavior is in general achieved by defining the fields used in important queries to be \index{key field}\index{MySQL@\emph{MySQL}!key field}\emph{key} fields. Definition as a key field has two effects on the behavior of database queries: \begin{itemize} \item Queries involving equalities or inequalities of the key field become $O(\log N)$ rather than $O(N)$. \item Database insertions require somewhat more time (because of the overhead of maintaining special indexes or trees that assist in searching). \end{itemize} As an example of a critical query, consider a user who is browsing airplane scheduling information. In order to allow the scheduling information to be quickly displayed, \emph{MySQL} must be able to quickly locate the scheduling records that correspond to the airplane and the time period being viewed. For this reason, database table fields identifying the airplane and the start and end of the reservation are key fields. Comments and explanations involving $O()$ notation are found throughout the \emph{\productbasename{}} source code and throughout this document. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection[\mbox{\protect$1\leftrightarrow{}1$}, \mbox{\protect$1\leftrightarrow{}\infty{}$}, and \mbox{\protect$\infty\leftrightarrow\infty{}$} Table Relationships] {\mbox{\protect\boldmath$1\leftrightarrow{}1$}, \mbox{\protect\boldmath$1\leftrightarrow{}\infty{}$}, and \mbox{\protect\boldmath$\infty\leftrightarrow\infty{}$} Table Relationships} \label{stbg0:sdbx0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Technical Design Decisions} \label{stdd0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Standard Web Page Appearance} \label{stdd0:swpa0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Data Types} \label{stdd0:sdty0} \index{data types}% This section describes the custom data types maintained by the software. PHP is primarily a string-based language. The important data types that are used to implement this software are, for the most part, forced into string form. String forms provide a way to represent data not inherently supported by PHP, such as long integers. The string forms of data described here generally (but not always) have these characteristics. \begin{itemize} \item String forms are typically constant-length. \item String forms typically have as their first two characters a type identifier. This provides a way for the software to trap typing mistakes. \item String forms are typically chosen so that the lexographic ordering of the strings corresponds to the desired ordering of the represented data. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{UTIME (Unix Timestamp)} \label{stdd0:sdty0:sutm0} \index{UTIME}% A Unix timestamp is a decimal representation of the number of seconds since the Unix epoch, and includes a fractional part. \begin{figure} \centering \includegraphics[width=4.6in]{utimeformat01.eps} \caption{Format of UTIME} \label{fig:stdd0:sdty0:sutm0:00} \end{figure} Figure \ref{fig:stdd0:sdty0:sutm0:00} illustrates the format of an UTIME. A UTIME consists of 22 characters, with the following components. \begin{itemize} \item \textbf{``UT'' (2 characters):} This fixed string aids in preventing type accidents with string data types. \item \textbf{Integer seconds since the Unix epoch (11 characters):} These 11 characters are an integer, zero-padded on the left as necessary, that represent the integer seconds since the Unix epoch. \item \textbf{Nanoseconds associated with the integer seconds (9 characters):} These 9 characters are an integer, zero-padded on the left as necessary, that represent the nanoseconds associated with the integer seconds since the Unix epoch. \end{itemize} Note that UTIMEs as described have the property that the lexical string sort order corresponds to the time sort order. Note that the UTIME format can be used only for values that: \begin{itemize} \item Are used as part of generating a unique or random data value (see, for example, \S{}\ref{stdd0:sdty0:sgui0}). \item Are used to determine elapsed time. \end{itemize} UTIMEs cannot be mixed directly with scheduling time, as the FBO may be in a different time zone than the server. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{SGUID (Server Globally-Unique Identifier)} \label{stdd0:sdty0:sgui0} \index{SGUID}% \index{globally-unique identifier}% It is necessary or helpful in some contexts to have a way to create an identifier that is guaranteed to occur no more often than once in the lifetime of the server. \emph{MySQL} can be used to create such identifiers, and there are also methods based on file and IPC semantics that can be used. The method used in the software is a \index{spin lock}spin lock on a precision timestamp; and the timestamp is concatenated with the PID. The method works because: \begin{itemize} \item A single process (by virtue of the spin lock) can't generate the same precision timestamp twice. \item No two processes can have the same PID at the same time. \end{itemize} \begin{figure} \centering \includegraphics[width=4.6in]{sguidformat01.eps} \caption{Format of SGUID} \label{fig:stdd0:sdty0:sgui0:00} \end{figure} Figure \ref{fig:stdd0:sdty0:sgui0:00} illustrates the format of an SGUID. An SGUID consists of 32 characters, with the following components. \begin{itemize} \item \textbf{``SG'' (2 characters):} This fixed string aids in preventing type accidents with string data types. \item \textbf{Integer seconds since the Unix epoch (11 characters):} These 11 characters are an integer, zero-padded on the left as necessary, that represent the integer seconds since the Unix epoch.\footnote{Note that 11 digits comfortably solves the Unix 2037 A.D. issue, as this will guarantee SGUIDs beyond 5000 A.D.} \item \textbf{Nanoseconds associated with the integer seconds (9 characters):} These 9 characters are an integer, zero-padded on the left as necessary, that represent the nanoseconds associated with the integer seconds since the Unix epoch.\footnote{As of this writing, Linux provides time to a resolution of microseconds. It is anticipated that a resolution of nanoseconds will accommodate any hardware speed advances in the foreseeable future.} \item \textbf{PID (10 characters):} These 10 characters are an integer, zero-padded on the left as necessary, that represent Unix PID expressed as a decimal number.\footnote{As of this writing, PIDs are 16 bits only. However, it seems inevitable that PIDs will be expanded to 24 or 32 bits in the future.} \end{itemize} Note that SGUIDs as described have a very important property---the lexical string sort order corresponds to the time sort order, with the PID used as a tie-breaker. This property is used to decide the priority of standby reservations (\S{}\ref{stdd0:ssby0}, p. \pageref{stdd0:ssby0}). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{SID (Session Identifier)} \label{stdd0:sdty0:ssid0} A \index{session identifier}session identifier (\index{SID}SID) is the cookie provided to the browser to authenticate the user after a successful login process is completed. A session identifier is an identifier only. The state associated with the session is maintained on the server side. A session identifier is exactly 66 characters long and consists of these components: \begin{itemize} \item The two characters ``SI'' (2 characters). \item An SGUID as described in \S{}\ref{stdd0:sdty0:sgui0} (32 characters). \item The server cryptographic hash function of the first two fields described above (32 characters). \end{itemize} The process of using an SID for authentication is protected by these mechanisms: \begin{itemize} \item It is impossible for a client to forge an SID, as the client does not have access to the server hash key. (Additionally, it would be extremely for a client to guess an SGUID that is already associated with a session on the server, as this space is quite large.) \item The \emph{\productbasename{}} software also records the IP address of the connecting computer, records that information in the server-side session state, and will not accept the SID from a computer connecting from a different IP address. Thus (NAT schemes aside) an SID cannot be reused by a client other than the one it was issued to. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{STIME (Scheduling Timestamp)} \label{stdd0:sdty0:stim0} \index{STIME}% A scheduling timestamp is a timestamp in an abstract calendar format with a resolution appropriate for: \begin{itemize} \item Representing the start times and end times of reservations. \item Marking database records with a modification time that will be formatted and displayed. \item Representing dates, such as expiration dates. \end{itemize} \begin{figure} \centering \includegraphics[width=4.6in]{stimeformat01.eps} \caption{Format of STIME} \label{fig:stdd0:sdty0:stim0:00} \end{figure} Figure \ref{fig:stdd0:sdty0:stim0:00} illustrates the format of an STIME\@. An STIME consists of 16 characters, with the following components. \begin{itemize} \item \textbf{``ST'' (2 characters):} This fixed string aids in preventing type accidents with string data types. \item \textbf{Calendar year (4 characters).} \item \textbf{Calendar month (2 characters).} \item \textbf{Calendar day (2 characters).} \item \textbf{Hour, 24-hour time (2 characters).} \item \textbf{Minute (2 characters).} \item \textbf{Second (2 characters).} \item \textbf{Microsecond (6 characters).} \end{itemize} Note that STIMEs as described have the property that the lexical string sort order corresponds to the time sort order. An STIME is used only for scheduling time, and is necessarily the time in the client locale. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{DT8 (Short Calendar Date)} \label{stdd0:sdty0:sdat8} \index{DT8}% The DT8 data type is used to specify dates in a shorthand format in GET/POST parameters and in software internals. The format is a string consisting of exactly 8 characters: \begin{itemize} \item Calendar year (4 characters). \item Calendar month (2 characters). \item Calendar day (2 characters). \end{itemize} A DT8 is used only for scheduling time, and is necessarily the time in the client locale. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{T4 (Short Calendar Time)} \label{stdd0:sdty0:sdtt4} \index{T4}% The T4 data type is used to specify times in a shorthand format in GET/POST parameters and in software internals. The format is a string consisting of exactly 4 characters: \begin{itemize} \item Hour (``00''-``23'', 2 characters). \item Minute (``00''-``59'', 2 characters). \end{itemize} Note that the string ``2400'' is not a legal T4\@. Technically, ``2400'' is ``0000'' of the following day. A T4 is used only for scheduling time, and is necessarily the time in the client locale. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{T3 (Shorter Calendar Time)} \label{stdd0:sdty0:sdtt3} \index{T3}% The T3 data type is used to specify times in a shorthand format in GET/POST parameters and in software internals, with a granularity of 10 minutes. Because \emph{\productbasename{}} will only schedule with a granularity of 30 minutes, any start time of a reservation is expressible as a T3. The format of a T3 is a string consisting of exactly 3 characters: \begin{itemize} \item Hour (``00''-``23'', 2 characters). \item Minutes divided by ten (``0''-``5'', 1 character). \end{itemize} Note that the string ``240'' is not a legal T3\@. Technically, ``240'' is ``000'' of the following day. A T3 is used only for scheduling time, and is necessarily the time in the client locale. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{T2 (Shortest Calendar Time)} \label{stdd0:sdty0:sdtt2} \index{T2}% The T2 data type is used to specify times in a shorthand format in GET/POST parameters and in software internals, with a granularity of 1 hour. A T2 is simply the hour of the time, and may range from ``00''-``23''. Note that the string ``24'' is not a legal T2\@. Technically, ``24'' is ``00'' of the following day. A T2 is used only for scheduling time, and is necessarily the time in the client locale. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{User Permissions} \label{stdd0:supm0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Permission Templates and Permission Schema} \label{stdd0:supm0:snap0} There are [at least] two ways of thinking about user permissions: \begin{itemize} \item A user is in a defined role (customer, FBO owner, line employee, flight instructor, etc.) and should have fixed privileges directly tied to to the role. \item The role of the user is only a starting point for the granting of permissions. Users may require more or fewer permissions, in a fine-grained sense, than is traditional for their role. For example, a line employee may be authorized to change fuel prices or have other privileges not granted to other line employees. \end{itemize} The approach taken in the \emph{\productbasename{}} software is the second approach---fine-grained permissions. The specific approach taken is: \begin{itemize} \item At the time a user is created, they are created as a ``permission template'' corresponding to their role or job. The permission template is a starting point. \item Permissions are very specific and fine-grained, and all permissions can be individually added or removed from an individual user after the user account is created. \item The permission templates and the associated permissions are customizable in the configuration file. \item Most user permissions are Boolean in nature, but some may have integer, floating point, or string values. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Mechanism of Storage and Query} \label{stdd0:supm0:sstq0} PHP is an interpreted language. The steps that are interpreted run relatively slowly (because the interpreter must parse the PHP statements), whereas PHP built-in functions (compiled `C' code) run very quickly. One way to enhance efficiency is to be sure that things that happen often come down to built-in functions rather than PHP statements that must be interpreted. SQL queries are also relatively slow, and a mechanism that avoids these is desirable. The mechanism chosen to represent permissions is: \begin{itemize} \item User permissions are represented as a single string (in \emph{MySQL}, a \emph{varchar} field). \item The user permission string is a group of permissions separated by the forward slash character (``/''). \item Each permission takes one of the following forms: \begin{itemize} \item \emph{``/ptag''}: For a boolean permission, presence of the \emph{ptag} indicates that the user has the permission, and absence of the \emph{ptag} indicates that the user does not have the permission. \item \emph{``/ptag=``value''}: The permission (or attribute) \emph{ptag} is assigned the \emph{value}. \end{itemize} \item Permission strings are escaped so that the string \emph{``/ptag''} can occur only at the start of the definition of the permission \emph{ptag}. Specifically: \begin{itemize} \item If the forward slash character occurs in the value of a permission, the forward slash character is escaped by suffixing it with the backslash character. \item The permission values allowed are very restrictive. Specifically: \begin{itemize} \item Backslashes are not allowed within permission values. \item Double-quotes are not allowed within permission values. \end{itemize} \end{itemize} \item Presence of a permission can be rapidly determined by using a string search\footnote{The string search functions are built into PHP, and are very quick because they are compiled `C' code.} by ``\emph{/ptag}''. Because of the escaping used, this string can only occur if permission \emph{ptag} exists. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Administrator Permissions} \label{stdd0:supm0:sadp0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{MySQL} Database Design} \label{stdd0:smdd0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Overall Relational Design} \label{stdd0:srds0} Figure \ref{fig:stdd0:srds0:00} illustrates the overall relational database design. The design consists conceptually of only five tables. However, because the $\infty\leftrightarrow\infty$ relationships require a cross-reference table, seven physical tables are actually required. \begin{figure} \centering \includegraphics[width=4.6in]{rdoveralldesign01.eps} \caption{\emph{\productname{}} Relational Database Overall Design} \label{fig:stdd0:srds0:00} \end{figure} In the actual \emph{MySQL} database, the eight tables shown in Figure \ref{fig:stdd0:srds0:00} are named exactly as indicated: \index{usrs@\emph{usrs}}\emph{usrs}, \index{resv@\emph{resv}}\emph{resv}, \index{slot@\emph{slot}}\emph{slot}, \index{rscs@\emph{rscs}}\emph{rscs}, \index{sper@\emph{sper}}\emph{sper}, \index{sess@\emph{sess}}\emph{sess}, \index{loge@\emph{loge}}\emph{loge}, and \index{dpar@\emph{dpar}}\emph{dpar}. The cross-reference table not shown in the figure is named by concatenating the cross-referenced table names: \index{usrsresv@\emph{usrsresv}}\emph{usrsresv}. The seven tables shown in Figure \ref{fig:stdd0:srds0:00} have the following contents: \begin{itemize} \item \textbf{\emph{usrs} (Users):} User information, including contact information and hashed password. \item \textbf{\emph{resv} (Reservations):} Reservations, including comments. \item \textbf{\emph{slot} (Slots):} Information about the actual time slot occupied by a reservations's linked resource, including start time and end time.\footnote{The \emph{slot} table allows a single reservation to use two or more different resources at different times. This occurs most commonly when a student schedules both ``ground'' and ``air'' time with an instructor, and the ``ground'' time extends either before or after the ``air'' time, or both.} \item \textbf{\emph{rscs} (Resources):} Schedulable resources, including aircraft, simulators, and flight instructors. \item \textbf{\emph{sper} (Scheduling Permissions):} The relationship between users and resources, in terms of the user's ability to schedule the resource with and without an instructor.\footnote{Instructors themselves have no scheduling restrictions---any student may schedule time with any instructor.} \item \textbf{\emph{sess} (Sessions):} State of user logins. \item \textbf{\emph{loge} (Log entries):} Significant and insignificant events for the software. These are stored in a database table rather than a file for easier sorting, viewing, manipulation, and pruning. \item \textbf{\emph{dpar} (Database parameters):} Parameters of the database as a whole, such as the current version of \emph{\productbasename{}} that created the database and an SGUID obtained at the time any table of the database was modified. \end{itemize} Note in Figure \ref{fig:stdd0:srds0:00} that there is a 1:1 link indicated between resources and users. Every flight instructor resource is also a user, and so when a user (usually, a student) creates, modifies, or cancels a reservation, the flight instructor user may be automatically notified by e-mail. In order to determine the e-mail addresses associated with the flight instructor resource, the link from the resource to the user is followed. Without such a link, the flight instructor's e-mail addresses would have to be maintained in two places in the database. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Structure of Reservations} \label{stdd0:sres0} A reservation consists of the following components (please refer to Figure \ref{fig:stdd0:srds0:00}): \begin{itemize} \item One or more entries from the users table (\emph{usrs}). In the case of multiple users attached to a reservation, all have authority to modify the reservation. \item \textbf{Exactly one} record from the reservations table (\emph{resv}). \item One or more entries from the slots table (\emph{slot}). \item One or more entries from the resources table (\emph{rscs}), paired 1:1 with the entries from the slots table. (Note also that a given reservation may include a given resource only once.) \end{itemize} The format of a \emph{reservation} as presented above is deliberately general. It allows these reservation structures: \begin{itemize} \item More than one user may be included on a reservation. This facilitates the case where two users schedule the same resource at the same time (for example, if two users fly together somewhere recreationally). \item If more than one resource is included on a reservation, the resources need not be scheduled at the same time. (For example, this accommodates the case where a student may have some ``ground'' time with a flight instructor before or after flying.) \item Any number of resources may be present on a reservation. (For example, a mechanic could reserve three planes at once for reservations.) \end{itemize} Note that other rules (not related to database structure) may prohibit some of the structures above. For example, a student may be prohibited from scheduling more than one airplane and one instructor. Zero-length reservations (reservations with $t_0 = t_1$) are currently prohibited. Reservations can be of three types: \begin{itemize} \item \index{active reservation}\index{reservation!active}\textbf{Active Reservations:} An active reservation is a reservation that currently blocks a resource (prevents other simultaneous active reservations). \item \index{standby reservation}\index{reservation!standby}\textbf{Standby Reservations:} A standby reservation is a reservation that can be promoted to an active reservation if the conflicting active reservation(s) are canceled. \item \index{banner reservation}\index{reservation!banner}\textbf{Banner Reservations:} A banner reservation is a ``reservation'' that is for information only, and cannot block active reservations or be promoted to an active reservation. A banner reservation is for user information only. Sample uses of banner reservations: \begin{itemize} \item To provide special instructions for scheduling an airplane or flight instructor. (Example: ``\emph{Please contact Jane directly to schedule instruction on Mondays}''.) \item To provide information about an airplane or flight instructor. (Example: ``\emph{Rates have been increased to \$100/hr for this aircraft}''.) \end{itemize} \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Treatment of Standby Reservations} \label{stdd0:ssby0} A \index{standby reservation}\index{reservation!standby}\emph{standby reservation} is a reservation made for resource(s) when the resource is/are already committed to another reservation(s) at the same time. (\emph{At the same time} means any form of overlap.) A standby reservation is represented in exactly the same way as an \index{active reservation}\index{reservation!active}active reservation, except that the Boolean table field \emph{isactive} (see \S{}\ref{sdtf0}) is set FALSE. Active and standby reservations are manipulated using the following rules. \begin{enumerate} \item The maximum number (i.e. depth) of standby reservations is limited by a configuration constant in the \emph{TBD} file. If this configuration constant is 0, standby reservations are not allowed. \item The maximum depth of standby reservations configuration constant is only loosely enforced. There are some situations where depth of standby reservations will be underestimated (due to the computational complexity of evaluating the true depth), but \emph{at least} the number of configured standby reservations will be allowed. \item When a user schedules a reservation, the reservation is created as an active reservation if there are no resource conflicts. However, if there are resource conflicts and if the configuration allows it, the user is given the option of creating a standby reservation. \item When an active reservation is canceled, one or more standby reservations will be automatically promoted, if applicable, to occupy the resources freed up. If permission flags for the canceling user are appropriate, the promotion of standby reservations may be suppressed. \item If a cancelation is made too close to the reservation time, (the notion of ``too close'' is a configuration constant), a standby reservation cannot be promoted (rationale: not enough time for the person whose reservation is promoted to react). \item FBO staff may change active reservations to standby reservations and may promote a given standby reservation to active (thus changing all conflicting active reservations to standby reservations), \textbf{but standby reservations may not have their priority reordered}. The relative priority of multiple standby reservations is determined by the creation SGUID---this is an automatic assignment and cannot be changed manually. \end{enumerate} E-mail notifications are sent whenever: \begin{itemize} \item Standby reservations are automatically or manually promoted to active reservations. \item A standby reservation can't be promoted to an active reservation because an active reservation was modified or deleted too close to the reservation time. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Query Complexity} \label{stdd0:sqcx0} It needs to be verified that all of the intended queries and maintenance operations are approximately $O(\log N)$ (see \S{}\ref{stbg0:sonn0}, p. \pageref{stbg0:sonn0}). In this section, the major queries are examined in detail. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Resource Scheduling Views} \label{stdd0:sqcx0:ssvw0} Scheduling views are perhaps the most important query. Users expect ``snappy'' response (near-instant display of scheduling information). A scheduling view is parameterized by: \begin{itemize} \item The set of resources whose schedules are to be displayed. \item The time window, identified by a lower and an upper bound. \end{itemize} The set of resources whose scheduling information is to be displayed is a linear constant. It tends to be either of size one or every resource schedulable. In any case, it is a small number ($<$100). The time window is parameterized for an SQL query on key fields. $O(\log N)$. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{User Views} \label{stdd0:sqcx0:suvw0} All conceivable user views and edits (alphabetical, uid, whatever) are $O(\log N)$. There may be a few deceptive queries that become $O(N)$, but these can be massaged. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsubsection{Standby Reservations} \label{stdd0:sqcx0:ssby0} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Session Management} \label{stdd0:ssmg0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Mutual Exclusion and Database and Table Locking} \label{stdd0:sdbl0} \index{locking (database}\index{database locking}\emph{MySQL} guarantees that each SQL statement will execute atomically. In many cases, necessary actions can be phrased as a single SQL statement, and no locking is required. However, in other cases, complex database updates must be completed atomically and locking is required. In addition to database design issues, editing collisions due to the nature of HTTP must be handled appropriately.\footnote{Among web developers, these collisions are sometimes called \emph{midair collisions}\@. I don't believe this is suitable nomenclature in an aviation environment, and so the term \emph{HTTP editing collision} is used.} An HTTP editing collision occurs when two [or more] users obtain copies of data in web browser forms, one user commits changed data back, and the second user commits different changes, with no knowledge of the changes made by the first user, and thus may overwrite the first user's changes. The strategy for mutual exclusion and database/table locking should meet these requirements and constraints: \begin{itemize} \item The strategy must allow a database maintenance script to run concurrently with web access to the database. \item The strategy must not block web page views for too long (never longer than 1-4 seconds, and no delay for the vast majority of web page accesses). \item The strategy must be fair: no process should block indefinitely. \item The strategy should be simple. \item The strategy must at least detect and optionally correct HTTP editing collisions. \end{itemize} The strategy employed is: \begin{itemize} \item Any process (either maintenance or web access) that has mutual exclusion needs locks the entire database (rather than locking individual tables). \begin{itemize} \item This strategy is very simple. \item This strategy prevents the possibility of deadlock (due to ordering of table locks). \item This strategy inherently serializes and is fair (because of \emph{MySQL}'s behavior). \item Maintenance scripts can be written to check and correct the database incrementally and to lock the database only for short periods of time, thus not blocking web users for too long. \end{itemize} \item In any scenario where an HTTP editing collision is a potential problem: \begin{itemize} \item An SGUID is stored on a database record commit. \item The SGUID is provided as a hidden form field on editing pages. \item At the time a commit is attempted, if the SGUID held by the browser is different than the one in the database, there has been an editing collision. In this case, at minimum notification is made. \end{itemize} \end{itemize} Finally, database locking has the standard software problem of how to embed a critical section within another critical section. The pseudo-code below should suffice. \begin{verbatim} local_lock_var = global_lock_var; lock_database(); global_lock_var = TRUE; ... Take action, perhaps calling sub-functions with identical pseudo-code. ... if (! local_lock_var) { unlock_database(); global_lock_var = FALSE; } \end{verbatim} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Web Pages} \label{swpg0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{index.php} (Scheduler Entry Page / All Scheduling Views)} \label{swpg0:siph0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{logview.php} (Action / Event / Exception Log View)} \label{swpg0:slvw0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{resourceadd.php} (Resource Addition)} \label{swpg0:srad0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{resourceedit.php} (Resource Edit)} \label{swpg0:sred0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{resourcemanage.php} (Resource List / Select Action)} \label{swpg0:srmg0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{resourceview.php} (Resource View)} \label{swpg0:srvw0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{signupadd.php} (Signup Addition)} \label{swpg0:ssad0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{signupedit.php} (Signup Edit)} \label{swpg0:ssed0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{signupmanage.php} (Signup List / Select Action)} \label{swpg0:ssmg0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{signupview.php} (Signup View)} \label{swpg0:ssvw0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{useradd.php} (User Addition)} \label{swpg0:susd0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{useredit.php} (User Edit)} \label{swpg0:suse0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{useremail.php} (Send Mass E-mail / Announcement to Users)} \label{swpg0:seus0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{usermanage.php} (User List / Select Action)} \label{swpg0:sumg0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{userview.php} (User View)} \label{swpg0:suvw0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Standalone Scripts} \label{ssas0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{adminforce.php} (Emergency Administrator Password Reset)} \label{ssas0:samf0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{dbconncheck.php} (Database Connectivity and Authentication Check)} \label{ssas0:sdbc0} \index{dbconncheck.php@\texttt{dbconncheck.php}}The \texttt{dbconncheck.php} script takes the following actions: \begin{itemize} \item Attempts to connect and authenticate to the \emph{MySQL} daemon using the information in \index{config.inc@\texttt{config.inc}}\texttt{config.inc}. \item Attempts to select the database specified in the \texttt{config.inc}. \item Attempts to close the \emph{MySQL} connection. \item Announces failure or success and provides details. \end{itemize} The \texttt{dbconncheck.php} can be used to verify \emph{MySQL} database connectivity during the \emph{\productbasename{}} setup process. The \texttt{dbconncheck.php} script takes no command-line parameters (it receives the \emph{MySQL} connection it requires by including \emph{PHP} library files). %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{dbinit.php} (Database Initialization and Upgrade)} \label{ssas0:sdbi0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{mainthot.php} (In-Service Daily Database Maintenance)} \label{ssas0:smah0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{phplibset.php} (Source File PHP Library Path Modification)} \label{ssas0:sphl0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{sitehashkeygen.php} (Source Hash Key Generation)} \label{ssas0:shkg0} The \index{sitehashkeygen.php@\emph{sitehashkeygen.php}}\texttt{sitehashkeygen.php} script generates a suitable site hash key as a constant in a PHP include file and places it in a file named \emph{sitehashkey.inc}. By default, the \emph{sitehashkey.inc} is placed in the current working directory. However, the \texttt{sitehashkeygen.php} script accepts an optional parameter, the directory in which to place the file. \begin{figure} \begin{scriptsize} \begin{verbatim} ff" . "vS(s17Wc,f?F*fS70WOz<3dUMfLV9= \end{verbatim} \end{scriptsize} \caption{Format of Automatically-Generated \emph{sitehashkey.inc} File} \label{fig:ssas0:shkg0:00} \end{figure} A typical automatically-generated \emph{sitehashkey.inc} file is shown in Figure \ref{fig:ssas0:shkg0:00}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{sbyrespromote.php} (Promotion of Standby Reservations)} \label{ssas0:spsr0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{PHP Library Files} \label{sphl0} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{config.inc} (Global Configuration Constants)} \label{sphl0:siph0} \index{config.inc@\texttt{config.inc}}The \texttt{config.inc} file contains particulars of the FBO and the installation, including: \begin{itemize} \item FBO location and contact information (mailing address, phone numbers, etc.). \item Database connection information (host, database, userid, and password information). \item Behavioral constants (scheduling and data retention policy). \end{itemize} This file must be customized as part of the \emph{\productbasename{}} installation process. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{confighard.inc} (Global Unmodifyable Configuration Constants)} \label{sphl0:scfh1} \index{confighard.inc@\texttt{confighard.inc}}The \texttt{confighard.inc} file contains global configuration constants that either: \begin{itemize} \item Would not need to be configured by the FBO, or \item Are bound tightly to the code and so can't be changed without also changing the code. \end{itemize} The constants in this file should not be changed by the users of the \emph{\productbasename{}} software. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{crhsh.inc} (Cryptographic Hash Functions)} \label{sphl0:schf0} \index{crhsh.inc@\texttt{crhsh.inc}}The \texttt{crhsh.inc} file contains functions dealing with cryptographic hashes. See \S{}\ref{stbg0:smdf0}, \S{}\ref{stbg0:sfch0}, and \S{}\ref{stbg0:spst0}. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{datefunc.inc} (Date Calculation and Related Functions)} \label{sphl0:sdfc0} \index{datefunc.inc@\texttt{datefunc.inc}}The \texttt{datefunc.inc} file contains functions that perform date calculations (for example, date differences and the day of the week corresponding to an arbitrary date). Many of the calculations are based on modulo arithmetic. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{sitehashkey.inc} (Site Hash Key)} \label{sphl0:sshk0} \index{sitehaskey.inc@\texttt{sitehashkey.inc}}The \texttt{sitehashkey.inc} file contains the site hash key. This file is normally automatically generated by the \index{sitehashkeygen.php@\emph{sitehashkeygen.php}}\texttt{sitehashkeygen.php} script as part of the \emph{\productbasename{}} installation process. Please see: \begin{itemize} \item \S{}\ref{sins0:sssi0:sgsh0} (p. \pageref{sins0:sssi0:sgsh0}) for instructions about how to execute the \texttt{sitehashkeygen.php} script to generate the \texttt{sitehashkey.inc} file. \item \S{}\ref{ssas0:shkg0} (p. \pageref{ssas0:shkg0}) for a description of the \texttt{sitehashkeygen.php} script. \item Fig. \ref{fig:ssas0:shkg0:00} (p. \pageref{fig:ssas0:shkg0:00}) for the typical format of a site hash key. \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{timeraw.inc} (Raw Time Acquisition)} \label{sphl0:strw0} \index{timeraw.inc@\texttt{timeraw.inc}}The \texttt{timeraw.inc} file contains functions that obtain the raw time from the server's clock. Functions that obtain the raw time are localized in one file to ease Unix epoch issue changes if they have to be made. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\texttt{utime.inc} (UTIME Acquisition and Operations)} \label{sphl0:sutm0} \index{utime.inc@\texttt{utime.inc}}The \texttt{utime.inc} file contains functions that: \begin{itemize} \item Obtain the raw time from the server's clock in the UTIME format (described in \S{}\ref{stdd0:sdty0:sutm0}). \item Perform operations on the UTIME data type (described in \S{}\ref{stdd0:sdty0:sutm0}). \end{itemize} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \clearpage{} \section{\emph{MySQL} Database Tables and Fields} \label{sdtf0} This section provides a detailed description of each \emph{MySQL} database table and field. Documentation is maintained in this document rather than in the software source code. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{usrs} (Users) Table} \label{sdtf0:susr0} The \emph{usrs} table contains information about each user, with each user stored in one database row. \begin{docdbtblfielddef} \item \index{uidx@\emph{uidx}}\textbf{\emph{uidx} (int)} An integer index identifying the user, automatically assigned by the \emph{MySQL} database. In many contexts (GET and POST parameters, for example), this index is used to identify a user. It provides a generally shorter way to identify a user than the \emph{userid}. \item \index{userid@\emph{userid}}\textbf{\emph{userid} (varchar[20])} The text string used to log in to the \emph{\productbasename{}} software. In the database table, this string is always stored in lower-case, but the software treats this string as case-insensitive when it is entered by a user. This string must begin with a letter, and may contain letters and digits only. The FBO may assign this text string arbitrarily. Common conventions are to use the first initial and last name (example: \emph{dashley}), first and middle initial and last name (example: \emph{dtashley}), or a nickname (example: \emph{womanizer}). \end{docdbtblfielddef} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{resv} (Reservations) Table} \label{sdtf0:srsv0} \index{resv@\emph{resv}}The \emph{resv} table contains one record for each reservation. \begin{docdbtblfielddef} \item \index{ridx@\emph{ridx}}\textbf{\emph{ridx} (int64)} An integer index identifying the reservation, automatically assigned by the \emph{MySQL} database. \item \index{sstime@\emph{sstime}}\textbf{\emph{sstime} (char[14])} An STIME string identifying the start time of the reservation. This is necessarily the minimum of the start times of any of the \emph{slot}s linked to the reservation, and is used to facilitate more efficient queries. \item \index{estime@\emph{estime}}\textbf{\emph{estime} (char[14])} An STIME string identifying the end time of the reservation. This is necessarily the maximum of the end times of any of the \emph{slot}s linked to the reservation, and is used to facilitate more efficient queries. \item \index{csguid@\emph{csguid}}\textbf{\emph{csguid} (SGUID)} An SGUID assigned at the time the reservation is created. This provides information about when the reservation is created, and also provides a guaranteed unique sort order for standby reservations. \item \index{msguid@\emph{msguid}}\textbf{\emph{msguid} (SGUID)} An SGUID assigned at the time the reservation is created or modified. This is used to prevent editing collisions and double-commits. \item \index{isactive@\emph{isactive}}\textbf{\emph{isactive} (BOOLEAN)} TRUE if the reservation is an \index{active reservation}\index{reservation!active}active reservation, or FALSE if the reservation is a standby reservation. \end{docdbtblfielddef} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{slot} (Slots) Table} \label{sdtf0:sslt0} \index{slot@\emph{slot}} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{rscs} (Resources) Table} \label{sdtf0:srsc0} \index{rscs@\emph{rscs}} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{sper} (Scheduling Permissions) Table} \label{sdtf0:sspr0} \index{sper@\emph{sper}} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{sess} (Sessions) Table} \label{sdtf0:sses0} \index{sess@\emph{sess}} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{loge} (Log Entries) Table} \label{sdtf0:slge0} \index{loge@\emph{loge}} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{\emph{dpar} (Database Parameters) Table} \label{sdtf0:sdpr0} \index{dpar@\emph{dpar}} TBD. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \clearpage{} \section{User Permission Flags and Values} \label{supf0} \begin{docdbtblfielddef} \item \index{slvl@\emph{slvl}}\textbf{\emph{slvl} (Security Level)} The general security level of the user. Security levels are in descending security order. In general, a user at security level $n$ cannot modify the settings of users with security level $