Fautore Installer

This page explains how to configure the Fautore Installer for specific operating systems, or to create and manage generally personalized installations. Actual installation instructions can be found on the Fautore Installation page.

Components

The Fautore installer is located in the "install" directory located in the base directory of the pre-installation file structure. The actual installation function is made up of the main program file, "install.pl," the configuration file "install.cfg," initialization template files and post install script to be run, all of which are located in the install directory. The main program file is also supported by the "Install.pm" module file located in the "Fautore" directory, also residing in the base directory of the pre-installation file structure. There is a dependency on the "CfgMgr.pm" PERL module that is freely available for use, but not available on CPAN. This module is also located in the "Fautore" subdirectory.

Concepts

The Fautore installer relies heavily on the associated configuration file designed to provide good flexibility in sourcing and placing files without having to change installation code. The configuration file provides instruction to the main program that are broken out by operating system type. Values defining what files should be copied where, what account should own the file, the group the file should belong to and what permissions should be assigned to the destination copy of the file.

Run Sequence

Installation functions happen in this order:

1. Config is read
2. Command line options and environment variables are checked
3. Operating system type is evaluated
4. User running the installation program is checked
5. Installation environment is verified
6. Destination locations are derived
7. The Fautore configuration file is created using OS specific values defined in "install.cfg"
8. Destination directorie are created if they don't exist
9. Files are copied one at a time
   1. Open file
   2. Read contents
   3. Parse contents for tokens
   4. Write contents
   5. Set permissions
   6. Set owner and group
10. Run operating system specific post install programs

Tokenization

Every copied file is parsed for the replacement of defined tokens for literal values. This allow for startup and application files to be written with place-holding tokens that are replaced with values correct for a specific installation. This minimizes the need to keep operating specific versions of program files. Any string beginning with "!#" and ending with "#!" will be replaced with the value assigned the string between these delimiters in the install.cfg file. In the case of a value being defined in a subsection the full colon ":" character is used to separate section names. The special variable reference "$os" is used to indicate that the definition of the specified token falls within the configuration file section specific to the OS on which the installation is being run.

Examples:

This token will be replaced with the default value defined for the "run_as" paremeter outside of any OS sections in the install.cfg

This token will be replaced with the value of the "initName" parameter in the section of the install.cfg file that is specific to the current OS.

This token will be replaced with the value assigned to the "log" parameter defined in the "dirs" subsection of the section of the install.cfg that is specific to the current OS.
In all case of section and subsection references the section reference tree will be walked upwards from the bottom until a value is found if the token is not defined at the point referenced. The default value defined outside the OS sections will be used if none other is found. If no definition is found at all, including the default, then the token is replaced with a value of "!#<Token>:undefined#!" where <token> is the original token value. This allowes for the for the easy searching for the value of ":undefined#!" in files to find all tokens that were not substituted correctly, while at the same retaining the original reference to aid in reasearching what went wrong.

Configuration File

The configuration file is organized into sections holding data specific to a particular operating system. Interpretation of the configuration file is hierarchical. If a value being sought by the program is not defined at the lowest level of the config file being requested the subsections are traversed backwards until it is found, if it is found. Values defined at the top level of the configuration file are process-wide defaults for all operating systems.
Sections are defined with a single word label, an open curly brace, whatever definitions are necessary, one per line, and then closed with another curly brace. Subsections are defined the same way within a section and are indented as a matter of style for readability.

Example

some_parameter = some default value

linux
{
   some_parameter = some os specific value
   dirs
   {
      dir_ref1 = some/path
      dir_ref2 = some/other/path
   }

   run
   {
      1 = a command
      2 = another command
      3 = yet another command
   }
}

OS Section

The Operating System (OS) sections of the config file segment paraemter definitions so that an installation can be tailored to match the operating system on which it is being run. Any available value can be defined directly in the OS section, with the exception of target directories and post-install programs to be run. Those values are defined in their corresponding subsections.

General Values

There are a number of values defined in the configuration file for directing the correct installation of the application. It is a matter of good style to set these values at the top level of the configuration file, outside any OS specific sections, in order to define a default value or gracefully handle the lack of definition for an OS. In this way OS specific definitions only need be made for cases that the common value just won't do.

debug = 0

strict = 0

id = id_by_id

group = mob

owner = marvin

(,)[*.pl:0755,*.cfg:0644]

source = ./

run_as = root

initName = fautore

Dirs Section

The "dirs" section of the configuration file contains the data necessary to create the requisite directory structure and populate it with the appropriate files. Directory references in this section are first check for existence. Any part of the referenced path that does not exist is created. Once the referenced path is assured to exist referenced files are copied into place.
The data of the "dirs" section has a standard format of:

parameter = value

where:

parameter

is either a defined keyword directory or any other single word.

value

is either any path statement string syntactically correct for the associated operating system, or an array statement similar to the "perms" array.

parameters

Parameters in the "dirs" section can be any single word string, but there are also some special keywords that can be used as well. The freeform parameters are used to ensure a directory path exists and to populate it with file. The special keyword parameters influence the operation of the install process in addition to the functions of the freeform parameters. All parameters of this section are written, with their asociated paths, out to the application configuration file generated as part of the install process.

cfg = (,)[install/fautore.cfg,/home/steve/test/etc/fautore]

start = /home/steve/test/etc/init.d

values

The values provided to the "dirs" subsection parameters take one of two forms depending on whether files are being copied to the referenced directory.

Simple String
A simple, syntactically correct string is used as the parameter value when no files are being copied to the directory. In this case the referenced directory and associated path are only checked for existance and the parameter value pair are writen to the final application configuration file.

Array Value
The array value is used in the "dirs" subsection when files need to be copied to the referenced directory path. When an array format is used it is formatted as described in the General Syntax section of the Fautore Install Setting - Perms page of this document. In this case however the destination directory is the last delimited value of the array and all preceding array elements are considered specifications of files to be copied to the destination directory.
Only the last element of the array value, the destination reference, is written to the final aplication configuration file as the value portion of the parameter value pair.

Examples

logs = /var/logs/fautore

• fautore.cfg entry: logs = /var/logs/fautore
• This "dirs" subsection entry will create the "/vars/logs/fautore" directory if it doesn't already exist
• No files will be copied

lib = (,)[*.pm,/usr/local/fautore/lib]

• fautore.cfg entry: lib = /usr/local/fautore/lib
• Create the "/usr/local/fautore/lib" directory if it doesn't already exist
• All files suffixed in ".pm" will be copied to /usr/local/fautore/lib from the top level source directory

bin = (,)[*.pl,*.sh,/usr/local/fautore/bin]

• fautore.cfg entry: lib = /usr/local/fautore/bin
• Create the "/usr/local/fautore/bin" directory if it doesn't already exist
• All files suffixed in ".pl" or ".sh" will be copied to /usr/local/fautore/bin from the top level source directory

Run Section

The "run" subsection to an operating system section contains a list of commands to be executed as a "post-installation" activity. This section is where database creation commands would go. Any scripts written to massage the operating environment, such as ensuring environment variables are written to appropriate enivironment setup files would be executed from here as well.

The data of the "run" section has a standard format of:

order = command

where:

order

is a numeric value starting at "1" and with an OS specific limit well beyond what would be reasonably expected to ever be used. While having gaps in the number is probably harmless, this is not recommended as the outcome is undefined.

command

is a command that is syntactically correct for the command line of the environment in which it is being run.

Supporting Files

The "install.cfg" file could be considered a "supporting file," but it is central to the correct functioning of the Fautore install (no install.cfg, no worky). The files listed here are either optional, or will only handicap an otherwise operational install process.

Initialization File

It is common for an operating system to support application initialization at start up time. This is often accomplished using an initialization file, that contains application startup command, that is placeed in a startup directory or registered with some governing OS utility. The Fautore installation utility accommodates this by maintaining an initialization template file for each OS. The template file is a complete initialization sequence with tokens where actuall specifics for file location or other instaltion specific values would be used.
During the installation process the template file for the current OS goes through the token substituion process while being copied to the file name given in the "initName" configuration file paramter.
The initialization template file must be located in the standard "install" directory and named according to convention:
<app name>.<file type>-<os>

Todo and areas of suspicion

File Copy

There is a bug where only the "fautore.cfg" file created by the installation process itself copies over at a zero size. All other files copy over without problems.

$os Tokenization

The tokenization function does not translate the $os reference in tokens. Looks like I flat out forgot to implement this. <oopsies>

ID Check

Current use of the "id" or "whoami" commands is likely inadequate to obtain user id information for all OS's. Using "getlogin" or "getpwuid" or "$<" or some combination of the three is likely a better bet. See the Additional Considerations section of the Fautore Install Setting - Id section for more on this.

Unsetting Defaults

It is possible that the default parameter value set for all operating systems in the installation configuration file could cause a problem in an operating system specific install if it is set at all. There should be a mechanism, perhaps a keyword of "unset", that would change a defined default value to not being set at all from within an operating system section. It could be that defining the parameter, but not setting it to a value will work now, but I haven't played with it.

OS Mapping

The "os_map" function code must currently be edited every time a new map is defined. These definitions need to be moved to the configuration file and interpreted by the function, rather than the function itself containing the mappings. (Bad Steve - bad - go to your room)

Tree Copy?

It could be worth endeavoring to add the functionality of pointing to an existing directory and just copying everything in it. Doing this would then beg the question of if we go through the trouble of decending into the entire tree copying and processing files individually, or do we just essentially copy the top level over and everything in it using a "copy" command. Likely this would be implemented as the latter with the former being worked towards later.

Greedy Notation?

It could be worth endeavoring to add the functionality of creating a "greedy copy" notation so that the entire source directory structure is search for a specified file spec instead of just the referenced directory.

Required Modules

The modules listed here are external modules required by Fautore itself, not for the correct functioning of the installer.