@c CfgTie --> Environment manager
@c Copyright 1998-1999, Randall Maas.  All rights reserved.  This program is
@c free software; you can redistribute it and/or modify it under the same terms
@c as PERL itself.                                                                   
@chapter CfgTie:: A Configuration Interface thru Perl
@heading Introduction

CfgTie is a package of Perl modules and tools.  These make it easier to
configure and maintain Unix computers.

The idea is that just about everything in your machines environment can --
nay should -- be operable thru a single consistent interface.  This is a
set of tools that make many of the various configuration subsystem in your
machine appear to be Perl variables of some sort.  (There are other modules
available from CPAN for the other aspects of your environment).

@subheading Problem Domain
This module makes the configuration text files and subsystems available to
Perl as conventional objects.

These are mapped into Perl, usually as hash arrays, but providing object
nethods where appropriate.

@subheading Installation
After unpacking the tar file, do:
@example
        perl Makefile.PL 
        make 
        make test
        make install
@end example

@subheading Additional, post-install tests
There are some extra tests that can also be done after a successful install.
This are not intended for normal installs, but for developpers working on CfgTie
and various extensions.

@subheading Optional Modules
@itemize
@item Rcs
@item Getopts::Long
@end itemize

@subheading How to find out more
@table @emph
@item online documentation
There is a set of online documentation.
@url{http://www.geocities.com/CapeCanaveral/Lab/1862/script/CfgTie_toc.html}

@item mailling list
There is a mailling list to discuss this package.

@table @asis
@item Send email to @email{cfgtie@@onelist.com}
@item You can subscribe by going to
@url{http://www.onelist.com/subscribe.cgi/cfgtie}
@item You can browse through the archives by going to
 @url{http://www.onelist.com/archives.cgi/cfgtie}

@item You can subscribe by going to OneList's homepage.  @url{http://www.onelist.com/}

@end table

@item Contact the author:
Randall Maas (@email{randym@@acm.org})
@end table

@subheading Copyright

Copyright @copyright{} 1998-1999, Randall Maas. All rights reserved.  This
package is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

@node Overview, SS, Introduction, Top
@chapter A broad overview of CfgTie
@heading Standards in the API
Most of the configuration elements have been developed to work as both Perl
ties (almost always hashes or associative arrays), and as Perl objects.  In
The more complex cases, the associative arrays often refer to other associatve
arrays.  Otherwise the stored values are list references.

To make these work as a normal variable you need only:

@itemize
@item reference the desired module:
@code{require cfgthingy;}

@item determine a variable name, and declare it:
@code{my %Table;}

@item Then, tie it a variable that you want to use:
@code{tie %Table, 'cfgthingy', param1, param2, ...}

@end itemize

@subheading Traps
Traps on changes in the variables are not currently implemented in this
module.   The Perl module @code{Tie::Watch} seems to provide the proper
functionality for this.

@subheading Common object methods
There as some standard methods available to associative arrays:

@code{$Table->HTML();} or @code{$Table->HTML('MyHTMLClass');}  Both return a
string formatted in HTML.  If an HTML class is specified, it will be embedded
in the HTML.  This is useful for style sheets.

@heading Attributes
The flags used in all of the variable control procedures are composed of
three sections, based upon what they control

@table @asis
@item Scope
This controls the scope of the variable setting.  The scope, from the
narrowest to the widest scope: @emph{Session}, @emph{Application},
@emph{User}, @emph{Group}, @emph{Global}.  That is, a variable set in the
@emph{user} scope, say, will only affect applications run by that user.
Currently all of the configuration modules are effectively global.

@item Inheritance
This controls whether or not a child process would inherit the variable.

@item Precedence
This controls whether an operation should affect an already existing variable.
@end table

@subheading Scope attributes
The current scopes are mutually exclusive, and defined as follows, from the
narrowest to the widest scope:

@table @dfn
@item session
This sets the variable for this session only.

@item application
This sets the variable for executions of this application only.

@item user
This sets the variable for use by this user (and any applications that may
run by said user) only.  If a user is not specified or otherwise implied, the
effective user id is used to determine the user name.

@item group
This sets the variable for use by this group (and any applications that may
run by an users in said group) only.  The effective group id is used to
determine the user name.

@item global
This sets the variable for use in general by any user or any applications.

@end table


@c @item noinherit
@c This prohibits the variable setting from being inherited by child processes.
@c If the flag is not set, the child processes will inherit the value (unless it
@c is overridden).

@node SS, Modules, Overview, Top
@chapter Safety & Security
@section Safety
@subheading Undoing changes to the configuration
Since undoing a modification is a critical functionality, this module is
designed to allow this:
@enumerate
@item The destructive changes (delete or modifying and existing value) are not
committed until the END phase of execution.

@item Changes done to the text files are done in a way so that original file
is not replaced until after the text file has been completed.

@item All aspects that employ text files support the use of the @code{Rcs}
module and checking these text files.

@end enumerate

The last item requires an add-on module, and user experience with RCS to
undo changes.  There is some prototyping of an additional method to complete
this, and make it possible in a programmatic fashion.  The plan is to allow
tagging of configuration sets...

@itemize
@item <tag, {<file,version>}>
@item Ability to rollback (undo) changes.
@item go back to $tag versions, or
@item revert all the settings associated with $tag to what the were before
@end itemize

@section Security
Much of the environment manager package is agnostic about security -- it does
not try apply much of its view of security, nor does it try to undermine
standard security models.   Here are the basics:
@enumerate
@item None of the modules in the standard distribution attempt to switch
to another user or group, except to make the real UID and GID the same as the
effective UID and GID.  This is for SUID/SGID programs, and this switch is
done when opening files for reading, writing, appending, or anything else.
These are returned to their previous settings after the file is closed.

The switch is done to cover the following kinds of scenarios.  Lets say there
is a SUID program to let some people do a particular task, but the task is
SUID'd to root.  The effective UID would be root, but all of the files the
create here will be owned by the normal user.  This is to prevent anyone
other than (say) root from creating or changing files (and contents) that
are or will be owned by root --  which would be bad to let happen.
Alternatively, lets say the admin login in as root (the user id really is
root),  but as temporarily switch effective user ids to help a user out.
We don't let any files with critical configuration information
get owned by the user -- not for an instant.

@c EXCEPT in the command line module, where
@c it only attempts to switch to the user and group requested

@item The potential replacement files are initially created with the current
real user & group priviledges, as described above.  These are changed to match
the target configuration file's priviledges; if (and only if) they match, then
the replacement configuration file will be migrated in.  A very nice article
appeared recently in Dr. Dobbs Journal that describes this method,
@url{http://www.ddj.com/articles/1999/9901/9901h/9901h.htm}

@item The environment manager employs @code{system}, and @code{popen}, which
have known issues with SGID, SUID programs and others.
@end enumerate

By logical extension, the security of your system with respect to the things
the environment manager touches are:
@enumerate
@item The effective and actual user and group ids at execution time.  Sticky
bits, SGID, SUID, and executing as root should be carefully considered.  (SUID
is to be avoided even more than SUID). There are alternative ways, some of
which are discussed below.

@item The execution ID and group of the system service programs and daemons
that use the configuration files.  It is strongly advised (from both
experience, and logical security) that none of the service daemons be allowed
to operate as root user ID or root group ID.  One alternative is to assign
daemons their own user ID and a common group ID.

@item The permissions set on the configuration files.  In general, none of the
service processes or daemons should be allowed to modify their configuration
files; at the least, not unless executed specifically, and carefully by an
administrator.  Instead, it is advised that both world and group permissions
to the configuration files not have write (or execute!) access.  The
configuration files group should be the same as the daemon's group, with read
permission enabled for the group.  The owner of the configuration files should
a user (preferably not root) other than the daemon's user id, and may have
write access.  Alternatively, if SGID methods are used (and the configuration
files are allowed group write access), be sure that the daemons execute as a
different group id.   This way, control of who may modify the configuration
files can be carefully maintained, and not by anyone who may subvert the
daemon.
@end enumerate

These suggestions are an operational definition of the @dfn{principle of least
priviledge}.

@c FUTURE TEXT
@c processes it touches or employs ... These have been documented in each
@c mmodule & a full list of the distribution is included in the appendix
@c These, in some cases, should be allowed to modify the configuration files,
@c atleast under controlled circumstances


@heading Requirements

If you wish to use the revision control aspects, you will need the RCS module
for Perl (from CPAN).


@c --- Configuration --------------------------------------------------------
@node Modules, Related work, SS, Top
@chapter Modules
@include CodeMenu.tex

@node Related work, Function Index, lib, Top
@chapter Related Work and things to do

@heading Related Modules
The following is a table of related modules.  They are different from this
module.  Any feedback or work on determining if this difference should be
reduced would be appreciated.  Of course, doing the work too.

@table @asis
@item HTTPD
There is a Perl module, @code{HTTPD-Tools} that help configure the HTTPD
daemon.

@item .newsrc associative array
The Perl module that already does this is @code{News-Newsrc}

@item Process associative arrays
@c open "ps -awxhjch|"; ppid,pid,pgid,sid,tty,tpgid, stat,uid, time, command
@c if tty not equal to '?'
The relevant existing Perl module is @code{Proc-ProcessTable}.
If it used an associative array interface, in part, this would make
signalling named services easier.

@item Quotas
The relevant Perl module is @code{Quota}
The quota subsystem could be nicely worked with the User hash-space.

@item Windows INI files
The relevenat Perl module is @code{Win32_Tie_Ini_Source}

@item Windows Registry Files
The relevant Perl module is @code{Win32_TieRegistry}
@end table

@heading What needs to be or could be written
@table @asis
@item IO descriptor associative array
manipulate sockets and files and such

@item semaphore associative array

@item shared memory associative array

@item arp interface

@item session associative array

@item tty associative array

@item folder associate array
Scan folders and such.  Not neccessarily good idea.

@end table

The future:
@table @asis 
@item Boundaries, routers, gateways and bridges
@itemize
@item ascend
@item cisco
@end itemize

@item Interlink services
@itemize
@item sendmail
@item qmail
@item apache
(see the HTTPD thing above.)
@item INN
@item modifying services table (media protocols, and service protocols)
@end itemize

@item Monitor services
@itemize
@item NOCOL
@item statusd
@end itemize

@item Distribution services
@itemize
@item rsync, rdist
@end itemize

@item User interfaces
@itemize
@item XWindows
 Window managers (FVWM2)
 .Xresources
@item C shell
@item POSIXly shells --  Korn & Bourne & BASH
@end itemize

@item Local system
@itemize 
@item filesystem tables
@item tunefs
@end itemize

@item Ability to receive batch changes
@item CVS
@item Handle symbolic links better.
@item Work with cfengine
@url{http://www.delorie.com/gnu/docs/cfengine/}

@item Possibly work with RFC 2244
@url{ftp://ftp.isi.edu/in-notes/rfc2244.txt}

@item Work with linuxconf
@url{http://www.solucorp.qc.ca/linuxconf/}
@item Work with webmin
@url{http://www.webmin.com/webmin/}
@item Possibly work with opStore
@url{http://24.1.97.22/gmd/opStore/framedIndex.html}
@end table


