CONFSTORE README
+-> TABLE OF CONTENTS
|
|-> Introduction
|-> Requirements
|-> Running confstore
|-> Definitions explanation
|-> Restoring configuration
|-> Configuring confstore: cs.conf
|-> Contributing definitions
|-> Confstore modules
|-> The Master Archive
|-> Logging
|-> Archive encryption
+ Introduction
Confstore is a configuration backup utility. Confstore scans your system for all recognised configuration files and then stores them in a archive. Confstore can also restore configuration from a previously created archive. Confstore is solely maintained and written by mastodon and any comments/suggestions should be posted in the Open Discussion forum on the confstore Sourceforge Project page or mailed to fade@xaker.ru.
+ Requirements
Confstore requires the following to run:
- Linux/UNIX based OS (confstore is currently developed and tested on Gentoo Linux) [www.gentoo.org]
- Perl 5.x (tested on 5.8.0, 5.8.2 and 5.8.4 but should run on most versions) [http://www.perl.com]
- tar
Optional requirements:
- bzip2 (for bzip compression)
- gzip (for gzip compression)
- Getopt::Long (should come standard with Perl)
- Net::FTP (if you are planning on using confstores FTP module (should come standard))
- MIME::Lite (if you want to use the Email module)
- Digest::MD5 (if you are using the logging function which creates md5 checksums)
- Crypt::CipherSaber (if you want to encrypt your archives)
(For information regarding the installation of Perl modules, see the FAQ file)
+ Running confstore
To get started, type: './confstore.pl --help' This should print the following:
confstore v0.5.4 -- A configuration backup and restoration utility Usage: confstore.pl [FLAGS]
Flags for creating backup archives of configuration
-s Scan (required)
-v=0/1/2 Verbose level
-d=filename Specify a definitions file
-o=filename Name of the the archive (without the .tar.x)
-c=comptype Type of compression (bz2, gz or none)
-ds=y/n Datestamp the archive
-f Upload archive to a FTP server
-m Mail archive to an Email account
-e Encrypt the archive
Flags for restoring configuration
-r=archive Restore configuration from an archive (required)
-cs=configset Specify a configset to restore (required)
Misc flags
-de=archive Decrypt an encrypted archive
-p=password Password (required if passing -e or -de)
Remember, these flags takes higher precedence than cs.conf options. (e.g. If verbose level in cs.conf is set to 0, but you pass -v=2, then the verbose level will be 2) So for example, if you wanted to create a configuration backup, called mybackup, and you wanted it to be compressed using gzip:
bash-2.05b$ ./confstore.pl -s -o=mybackup -c=gz
Starting confstore v0.5.4 (http://confstore.sourceforge.net) at Thu Aug 12 18:37:29 BST 2004
+ Scanning system...
+ Creating archive of configuration files...
+ Archiving files with: /bin/tar cfP mybackup-2004-08-12.tar <tmpdir>...
+ Adding compression...
+ Done: mybackup-2004-08-12.tar.gz
If you want more detailed output, try passing the -v flag with a value of 1 or 2 (-v=1 or -v=2)
+ Definitions explanation
Confstore knows what to scan for by reading a definition file. The default definition file is locations.def, which can be found (along with other definition files) in defs/. Confstore definition files have a simple layout which makes editing and adding config paths a breeze. Heres a sample:
PHP:/usr/local/lib/php.ini
Apache:/usr/local/apache/conf/httpd.conf:/usr/local/apache/conf/access.conf
The first word at the beginning of each line is the configset, i.e. the application to which the configuration belongs. Each configset can have an infinate number of paths to configuration. The configset is seperated from the paths by a colon, :, and each path is also seperated by a colon. To add more configuration definitions to your existing definitions file, simply add a path to the end of an exiting configset or create a new configset. Confstore also supports wildcards in definition files. E.g. If you are running OpenBSD which has various hostname files in /etc with different extensions, you can add hostname.* to your definition file (this is already included in the defs/openbsd.def file) As of 0.5.4, confstore can also understand environmental variables such as $HOME and $CVSROOT:
fluxbox:$HOME/.fluxbox/menu
Of course you can create your own custom definition files aswell and load them by passing the -d flag at the command line. Confstore is relying greatly on you, the users, to help build the default locations.def to a much greater size, and list paths to most common software. README section, Contributing definitions, explains how you can help out.
+ Restoring configuration
Confstore has the ability to read archives that it has previously created and restore configuration from them.
*Note: this will only work with archives made with v0.4 or higher of confstore
All you need to know is the path to your archive and which configset you want to restore. The restore process is initiated using the -r and -cs flags:
./confstore.pl -r=/home/user/backup.tar.bz2 -cs=Apache
This will bring you to the restore prompts. Here you can either view both the config files, 'v', restore the config file, 'y', or not restore it, 'n'.
+ Configuring confstore: cs.conf
Confstore has various settings you can alter which are stored in cs.conf. Confstore looks for cs.conf in the current directory so make sure its there, or change the $CS_CONFIG_PATH variable in confstore.pl. There are various options in cs.conf, and they are all annotated so the easiest way to learn what you can configure is to look at cs.conf.
As with definition files, cs.conf also supports comments.
+ Contributing definitions
Confstore needs your help with building the main definitions file and submitting custom ones! Please post your definitions files somewhere on the confstore SourceForge forums (preferably Open Discussion) or mail them to fade@xaker.ru. Any custom definition files are also welcome I.E. definition files made for specific OSes/setups
All contributions are greatly appreciated! (include your name/site and youll get a mention in the next release ;)
+ Confstore modules
Confstore has various modules written specifically for it. These modules give added features that some users may want to use. The modules can be found in the modules/ dir. At the moment there are two modules, the FTP and Email modules. To use these modules, simply pass either the -f or -m options.
MODULE FILENAME HOW DO I CHANGE THE SETTINGS? FTP modules/Ftp.pm cs.conf Mailer modules/Mailer.pm cs.conf
** NOTE: Prior to 0.5.4, all module variables were stored in the module scripts themselves. All module settings are now in cs.conf so there is no need to touch the module scripts.
+ The Master Archive
A master archive is an archive of all the configuration you have ever backed up. If you have the master archive feature enabled, after each time you run confstore, the configuration you have just backed-up will be added to the master archive, in a datestamped folder. To enable the master archive, you need to edit the 'masterarchive' option in cs.conf and then set the 'masterloc' option. Enter a full path and an archive name with an extension. Confstore will read the extension and add the compression you want. Make sure 'masterloc' points to an archive thats in a folder that already exists otherwise confstore will fall over, moaning about some directory that doesnt exist. (so if masterloc points to /home/user/backup/MASTER.tar.gz, make sure the directory /home/user/backup exists. Dont worry about the archive, it will be created automatically)
+ Logging
To enable logging, change the log_results and log_locations values in cs.conf. confstore logs the creation of backup archives and the restoration of them. With logging enabled, the following will be added to your log file when you create a backup archive: exact time of the scan, the name of the output archive, an md5 checksum of the archive, the definition file in use for the scan, and finally whether the archive has been mailed or FTPed anywhere.
As previously mentioned, confstore also logs restores and each time you restore some configuration from an archive. The following details are added to the log: archive name, the configset being restored, the names of the files that were answered 'y' to, and the total number of files restored.
+ Archive encryption
As of v0.5.2, confstore can encrypt archives that it has created. To encrypt an archive, simply pass the -e and -p flags when creating the archive. -e tells confstore that the archive should be encrypted and -p is the password you want to encrypt the archive with (-p is required with -e):
./confstore.pl -s -e -p=password
Confstore uses the CipherSaber symmetric-key file encryption system which is implemented through the Crypt::CipherSaber module. If you would like further information on CipherSaber then visit the homepage at: http://ciphersaber.gurus.com/
Once the archive has been encrypted (you'll know an archive is encrypted by the .cpa extension which stands for confstore Protected Archive), the only way to make it readable again is to decrypt it using the -de flag. Again this requires the -p flag so you can submit the password:
./confstore.pl -de=archive.tar.bz2.cpa -p=password
If the password is correct, confstore will decrypt the archive, creating a new readable one; the encrypted archive remains intact and its up to you what you do with it. If you get the password wrong, you will have no sign that you got it wrong. However when you try to decompress the resulting "decrypted" archive, you'll find it isnt decrypted and that there is no way of accessing it. So you'll have to pass the -de and -p flags and try again if you get the password wrong.
Until next release,
mastodon
12/08/2004
fade@xaker.ru
http://confstore.sourceforge.net/