CCP

Section: User Manuals (1)
Updated: January 2006
Page Index

NAME

ccp - A program that parses and upgrades configuration files

SYNOPSIS

ccp [OPTIONS] --oldfile /path/ --newfile /path/

DESCRIPTION

CCP 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".

OPTIONS

-o, --oldfile /path

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.

-n, --newfile /path

Define the new configuration file. Typically this will be the default configuration file for the new version of the software.

-b, --backup (/path)

Make a backup of the file we're writing to before making changes to it. It will be backed up to filename.ccpbackup or optionally to the file path supplied.

-d, --delete

Delete the --newfile if it is writeable by the user running ccp and the configuration file is upgraded successfully.

-i, --ifexists

If --newfile doesn't exist then exit silently instead of displaying an error message. Useful when running in for instance rpm %postin

-g, --ignoreopt name

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.

-s, --set name

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

        --set NoOrphans

or a space seperated list of settings like

        --set "NoOrphans NoTemplateUncommenting ParanoidMode"

-f, --outputfile /path

Write the new (merged) configuration file to this file instead of --oldfile.

--writetemplate /path

Write the auto-generated template to the file supplied. This is the only 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.

-p, --template /path

Don't generate the template on-the-fly but use the pre-generated one supplied as a parameter to this option.

-h, --help

Display the help screen

-v, --verbose

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.

-V, --veryverbose

Be very verbose, implies --verbose. Displays alot information about what it's doing, generally useful to find out why something isn't working right.

--version

Display the version number of CCP.

--fullversion

Display the version number of CCP aswell as it's CVS revision information.

-D, --debug

Run in debugging mode, outputs alot of information. Only useful for debugging. Implies -V and --set ParanoidMode.

--bug

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.

SETTINGS

These options can be set by issuing --set [OPTION] or --set "Option1 Option2" (with the quotes).

NoOrphans

Exit if orphaned options are detected. See the section "About orphaned options" below for more information on orphaned options.

AllowOrphans

Don't exit if orphaned options are detected. From ccp 0.5 (the next version) NoOrphans will be default, so you should use this to allow orphans. When both AllowOrphans and NoOprhans are set, NoOrphans takes precedence. See the section "About orphaned options" below for more information on orphaned options.

NoTemplateUncommenting

Don't uncomment options in autogenerated templates automatically.

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

ParanoidMode

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.

CONFIGURATION FILETYPES

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

--type keyvalue
--type ini

keyvalue (default)

This filetype is for files in the format

key = value

and all similar derivatives such as

$key = "value";

Comments (# ; /** * */) and unrecognized lines are skipped, so it will also work with php-source files such as those used in squirrelmail.

ini

This filetype is for files in the format

[Section]
key = value

and all similar derivatives such as

[Section]
$key = 'value';

Comments (# ; /** * */) and unrecognized lines are skipped

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 (THIS DEFAULT WILL CHANGE IN 0.5), which can in some cases lead to configuration loss. Therefore it is recommended that you either use --backup or --set NoOrphans 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).

USAGE EXAMPLES

SquirrelMail .rpmnew

$ 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.

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.

CCP_VERBOSE

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.

CCP_VERYVERBOSE

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.

CCP_PARANOID

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.

CCP_DISABLE

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.

AUTHOR

CCP is written by Eskild Hustvedt <eskild at mandriva dot org>

BUGS

There are currently no known bugs with ccp. If you find any bugs, please report them to the bug tracker at <http://savannah.nongnu.org/bugs/?group=ccp>

COPYRIGHT

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