ccp.1

.\" Manpage for Common Configuration Parser
.\" Copyright (C) Eskild Hustvedt 2006
.\"
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
.TH CCP 1 "January 2006" "Common Configuration Parser 0.4.1" "User Manuals"
.SH NAME
ccp - A program that parses and upgrades configuration files

.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH SYNOPSIS
.B ccp
[\fIOPTIONS\fR] --oldfile \fI/path/\fR --newfile \fI/path/\fR
.SH DESCRIPTION
\fBCCP\fR is a program that reads configuration files and upgrades them.

It takes a --oldfile (typically the configuration file you're currently
using) and a --newfile (typically the default version of the new configuration
file). CCP first reads all the configuration options and values in
the new file, then in the old file, then it generates the template (or uses
the template supplied by the user, if any), finally it merges the files into one
- creating a new configuration file that has the changes that was made to the
old file but also the new options that is included in the new file.

CCP is completely independent of the program that created the configuration file,
and can be used for many different purposes. For instance it can be used to merge
changes between an old user-edited configuration file and a .rpmnew file generated
by rpm when a rpm package was upgraded.

CCP is an acronym for "Common Configuration Parser".

.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH OPTIONS
.TP
\fB\-o\fR, \fB\-\-oldfile\fR \fI/path\fR
Define the old configuration file. Typically this will be a configuration file for
an earlier version of a program that has been changed by the user.
This is also the file that the changes made by ccp will be written back to if
--outputfile isn't supplied.
.TP
\fB\-n\fR, \fB\-\-newfile\fR \fI/path\fR
Define the new configuration file. Typically this will be the default configuration
file for the new version of the software.
.TP
\fB\-b\fR, \fB\-\-backup\fR \fI(/path)\fR
Make a backup of the file we're writing to before making changes to it. It will be backed
up to \fIfilename.ccpbackup\fR or optionally to the file path supplied.
.TP
\fB\-d\fR, \fB\-\-delete\fR
Delete the --newfile if it is writeable by the user running ccp and the configuration file
is upgraded successfully.
.TP
\fB\-i\fR, \fB\-\-ifexists\fR
If --newfile doesn't exist then exit silently instead of displaying an error message.
Useful when running in for instance rpm %postin
.TP
\fB\-i\fR, \fB\-\-ifnewer\fR
If --newfile's mtime is older than --oldfile's, ccp will do nothing.
.TP
\fB\-g\fR, \fB\-\-ignoreopt\fR \fIname\fR
Ignore the options supplied when generating templates. That means that the value for
that option will be kept as it is in the --newfile (ie. not replaced by the value set in
the --oldfile). Typically this will be if the config file defines its own version number
in the config file - ofcourse you want that version number to be that of the new file,
not the old file.

It can also be used to ignore some orphaned options when used with --set NoOrphans.
Or, it can be used to make CCP *not* uncomment some options, but
uncomment others.

This option can be supplied more than once.
.TP
\fB-s\fR, \fB--set\fR \fIname\fR
Set the option supplied. See the section SETTINGS below for a list of settings
that can be set.

--set can take either a single setting like
.nf
	--set NoOrphans
.fi
or a space seperated list of settings like
.nf
	--set "NoOrphans NoTemplateUncommenting ParanoidMode"
.fi
.TP
\fB\-f\fR, \fB\-\-outputfile\fR \fI/path\fR
Write the new (merged) configuration file to this file instead of --oldfile.
.TP
\fB\-\-writetemplate\fR \fI/path\fR
Write the auto-generated template to the file supplied. This is the \fBonly\fR option that
doesn't require --oldfile. It will not upgrade any configuration file but it will create
a template from --newfile and write it to the file supplied.
.TP
\fB\-p\fR, \fB\-\-template\fR \fI/path\fR
Don't generate the template on-the-fly but use the pre-generated one supplied as a
parameter to this option.
.TP
\fB\-h\fR, \fB\-\-help\fR
Display the help screen
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Be verbose. Displays more information about what it's doing, and also shows warnings.
Unless ccp is told to be verbose most warnings will just be suppressed.
.TP
\fB-V\fR, \fB\-\-veryverbose\fR
Be very verbose, implies --verbose. Displays alot information about what it's doing,
generally useful to find out why something isn't working right.
.TP
\fB\-\-version\fR
Display the version number of CCP.

.\" Options not in --help
.TP
\fB\-\-fullversion\fR
Display the version number of CCP aswell as it's CVS revision information.

.TP
\fB-D\fR, \fB\-\-debug\fR
Run in debugging mode, outputs alot of information. Only useful for debugging.
Implies -V and --set ParanoidMode.
.TP
\fB\-\-bug\fR
Output a ./ccpdebug file that contains information about your CCP version and
the files you are trying to use. It requires you to at least supply --newfile
and --oldfile aswell.

.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH SETTINGS
These options can be set by issuing --set \fI[OPTION]\fR or
--set \fI"Option1 Option2"\fR (with the quotes).
.TP
\fBNoOrphans\fR
Exit if orphaned options are detected. See the section "About orphaned options" below for
more information on orphaned options.

.TP
\fBAllowOrphans\fR
\fBDon't\fR exit if orphaned options are detected. When both AllowOrphans and
NoOprhans are set, NoOrphans takes precedence.  See the section "About orphaned
options" below for more information on orphaned options.

.TP
\fBNoTemplateUncommenting\fR
Don't uncomment options in autogenerated templates automatically.

Normally CCP will uncomment options that the user has uncommented
automatically, this disables that.

.TP
\fBParanoidMode\fR
Make ccp paranoid, runs additional tests on the files to check for two different
settings named the same (which the program can handle fine, but CCP doesn't).
CCP may also output even more information than in very verbose mode when running
in paranoid mode. This implies -v.

If you're uncertain about if a file will work or not in CCP then you should test it
with --set ParanoidMode and check for warnings.
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH CONFIGURATION FILETYPES
These are the different forms of --type(s) you can supply.
Examples:

.nf
--type keyvalue
--type ini
.fi
.TP
\fBkeyvalue\fR (default)
This filetype is for files in the format

.nf
key = value
.fi

and all similar derivatives such as

.nf
$key = "value";
.fi

Comments (# ; /** * */) and unrecognized lines are skipped, so it will also work with
php-source files such as those used in squirrelmail.
.TP
\fBini\fR
This filetype is for files in the format

.nf
[Section]
key = value
.fi

and all similar derivatives such as

.nf
[Section]
$key = 'value';
.fi

Comments (# ; /** * */) and unrecognized lines are skipped
.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH ABOUT ORPHANED OPTIONS
Orphaned options are options that is found in the oldfile or newfile but can't
be found in the template file (meaning CCP couldn't find a commented option
to uncomment either). These will be discarded by default, which can in some
cases lead to configuration loss.  Therefore it is recommended that you either
use \fB--backup\fR
or \fB--set NoOrphans\fR when working on files that can have additional configuration
options added that is not defined by default if ccp is run on it automatically.
If ccp is not run automatically then using -vb will do the trick, -v makes sure
ccp tells you about it and you can restore or check the backup (-b) afterwards.

On configuration files that doesn't have the ability to add/uncomment options
orphans will not occur (unless there is a bug in ccp).

.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH USAGE EXAMPLES
.TP
\fBSquirrelMail\fR .rpmnew
\fB$\fR ccp --delete --ifexists --ignoreopt config_version --set NoOrphans --oldfile /etc/squirrelmail/config.php --newfile /etc/squirrelmail/config.php.rpmnew


--delete makes sure the .rpmnew is deleted, --ifexists makes it exit (silently) if the .rpmnew
does not exist (for use in %post scripts in RPMs), --set NoOrphans makes sure that ccp doesn't
touch the file if the user has uncommented options, --ignoreopt config_version makes sure
we use the config_version from the .rpmnew and not the old one.

.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH ENVIRONMENT VARIABLES
CCP reacts to a few different environment variables. All of these override
commandline options if set. Useful if you want ccp to use a different verbosity
level when ccp is called from an external piece of software, such as from a
RPM %post script.
.TP
\fBCCP_VERBOSE\fR
Set this environment variable to the value "1" to force CCP to be verbose.
You can only increase the verbosity level using this variable, you can't
decrease it.
.TP
\fBCCP_VERYVERBOSE\fR
Set this environment variable to the value "1" to force CCP to be very verbose.
You can only increase the verbosity level using this variable, you can't
decrease it.
.TP
\fBCCP_PARANOID\fR
Set this environment variable to the value "1" to force CCP to be very verbose.
You can only make CCP paranoid using this variable, you can't make it not-paranoid.
.TP
\fBCCP_DISABLE\fR
Set this envornment variable to the value "1" to force CCP to be disabled.
CCP will immedietly exit. Useful
if you have CCP run automatically but want to skip using it.

.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH AUTHOR
.B CCP
is written by Eskild Hustvedt \fI<eskild at mandriva dot org>\fR

.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH BUGS
There are currently no known bugs with ccp. If you find any bugs, please report them
to the bug tracker at \fI<http://random.zerodogg.org/ccp/bugs>\fR

.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

.SH COPYRIGHT
Copyright (C) 2005, 2006 Eskild Hustvedt.
.br
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.