NAME
NCustom - Perl extension for customising system configurations.
SYNOPSIS
NCUSTOM_SCRIPT
use NCustom;
# do stuff in your script using NCustom routines
KICKSTART POST SECTION
# install package management tool that is used in NCUSTOM_SCRIPT
rpm -i http://install/install/rpm/apt-0.5.5cnc6-fr1.i386.rpm ;
echo 'rpm http://install/ install/rh90_apt os extras' > /etc/apt/sources.list;
apt-get update ;
# install and use NCustom
apt-get -q -y install perl-NCustom ;
ncustom -i ;
ncustom -c src_fqdn=install.example.com ;
ncustom -n NCUSTOM_SCRIPT
ncustom -n smb_ldap_pdc-0.4-rh90.ncus ;
ABSTRACT
NCustom provides some file editting routines and some package management hooks to assit in system configuration.
File editting: The file editing routines include features such as transactions, and undo by transaction. The original files are archived within a directory tree structure.
Package management: You may specify packages (and minumum/maximum/exact versions) that you require to be installed, and a routine to be called if they are not installed. Your routine may use simple "rpm" commands (or whatever you want), or you may use the provided routine that uses "apt". In-built support for other package management tools is on the todo list.
System configuration: A commandline interface provides for initialisation, configuration, and invocation (including invocation across the network). This enables NCustom to be used from the post section of Kickstart script. It may also be used stand alone on an already built system.
If system configuration tweaking is minor, then scripts (even in the post section of a kickstart configuration) may be more useful. If the system configuration tweaking is related to only one rpm, then re-rolling the rpm with a new post section may be more useful. If there are several packages that need inter-related configuration (eg building a Samba, PDC, LDAP server), then NCustom may improve the speed of development of automated system configuration.
DESCRIPTION
File editting: Files are saved into a directory structure within the users home directory. This location may be configured. A file will be saved within a directory structure named after the current transaction name, and also under the "all" directory. Because of this "all" changes, or only changes relating to a "transaciton" may be reversed.
Package management: When a package requirement is not met, a routine that you may provide shall be called.
System configuration:
EXPORT
None by default.
API
transaction
trasaction("tx1");
Set the current trasaction. If not set it defaults to basename($0). Using the default is normally good enough.
save_files
save_files("~/dir2/file1");
save_files(<<' EOF');
~/dir2/file2
~/dir3/*
EOF
There is not much point to this - the customise works or not. But it helps while developing the customisation. Note: changes effected by using NCustom functions are saved automatically.
initialise
initialise();
Initialise the archive of saved files. As this deletes files this is not done automatically.
overwrite_file
overwrite_file(file => "~/dir6/file1", text => ' some content');
overwrite_file(file => "~/dir6/file2",
strip => '^\s{4}',
text => <<' EOF');
This will be line 1 of the new content of the file.
This will be line 2 of the new content of the file.
This, line3, will still be indented. As will line 4.
I bet there will be a dollar sign and two single quotes on the next line.
'I told you so ! Now you owe me $20', I would then say.
This will be the last line.
EOF
Overwrite file overwrites $file with $text.
So that you can have pretty indentation when using here documents, the pattern $strip is stripped out prior to processing.
More clearly, overwrite file is equivalent to:
open(FILE,">$file");
$text =~ s/$strip//;
print FILE $text;
append_file
append_file(file => "~/dir7/file1", text => 'an extra line');
append_file(file => "~/dir7/file2",
strip => '^\s{4}',
text => <<' EOF');
An extra line to add on to the file.
This line, will be indented.
The last last line with some special chars *!@$%.'"
EOF
Append file is the same as overwrite file, except it behaves as ">>" instead of ">".
prepend_file
prepend_file(file => "~/dir8/file1", text => 'an extra line');
prepend_file(file => "~/dir8/file2",
strip => '^\s{4}',
text => <<' EOF');
An extra line at the start of the file.
This line, will be indented.
Some special chars *!@$%.'"
The last extra line added to the start of the file.
EOF
Prepend behaves the same as append, except the text is added to the start instead of the end.
edit_file
edit_file(file => "~/dir9/file1", code => 's/file/FILE/g;');
edit_file(file => "~/dir9/file2",
strip => '^\s{4}',
code => <<' EOF');
s/my\.example\.com/whatever\.com/g;
s/^$/replace all blank lines with these three lines
two of three, with 4 leading spaces
and three of three/ ;
s/might/WILL/g;
EOF
edit_file(file => <<' EOF', strip => '^\s{6}', code => <<' EOF');
~/dir9/file3
~/dir10/*
EOF
s/file/FILE/g;
s/least/LEASTWAYS/g;
EOF
Edit file is similar to:
perl -i -e "$code" $file
With edit file, $file must exist. As with the other routines, $code has the pattern $strip stripped out.
You can also provide multiple filenames to be editted. This holds true for the other routines too.
undo_files
undo_files("tx1");
undo_files("~/.ncustom/save/tx2");
undo_files("tx3 tx4");
undo_files(<<' EOF');
tx5
~/.ncustom/save/tx6
EOF
Undo transaction will restore the files from a given transaction archive directory. That includes removing any new files that were created. For any directories that it cannot find, it will try looking in $Config{'save_dir'}. Undo does not: restore files that were edited by non-NCustom function if they were not first saved using NCuston::save_files; delete new directories that were created (yet). Again: this is only a development aid.
required_packages
sub handler{
my ($reqref, $url, $file) = @_;
print "As $$reqref{'match'} version $$reqref{'version'} of ";
print "$$reqref{'pkg'} was $$reqref{'result'} - ";
print "we are going to fetch $file from $url and execute it.\n";
print "This should set things right.\n";
return 1;
}
required_packages(<<' EOF');
EXACTLY; 9.9.9; acme; handler($req, "URL", "FILE")
NOTWANT; 0.0.0; perl; print "Dont be stupid\n"
#MAXIMUM; 9.9.9; perl; carp("Warning: untested with this perl")
#MINIMUM; 9.9.9; perl; apt_fix()
NOTWANT; 0.0.0; perl; for($i = 0; $i < 10; $i++){$s="Hello"; print "${s}${i}\n"}
EOF
Required packages take a multi-line argument list, where each line is of the format: requirement, version, package, handler code.
Required packages will invoke the handler if the package is (or isnt) installed as per the requirement and version.
Valid requirements are: MINUMUM, MAXUMUM, EXACTLY, and NOTWANT.
Input lines will be ignored if the first non-whitespace character is the '#' character.
The handler code is eval'd, and it may make use of the hashref "req". The hash has the keys: match, version, and package; which correspond to the original arguments. The hash also contains result, which is the answer as to whether the requirements was met or not. Possible values of result (each referring to the package or it's version in relation to the requuirements) are: MISSING, ABOVE, BELOW, or UNWELCOME.
A handler "apt_fix" is provided that will simply attempt to remove UNWELCOME packages, and do an install for all other scenarios - so you might get the verion you want or not, depending upon your apt repository.
blat_myconfig
blat_myconfig();
Blat_myconfig overwrites the personal configuration profile with the global configuration profile. The personal configuration profile is "~/.ncustom/NCustom/MyConfig.pm".
config_edit
config_edit((src_fqdn => '"install.baneharbinger.com"',
test_url1 => '"install.baneharbinger.com/index.html"'));
Config_edit is followed by name vaule pairs. If there is a corresponding name in the personal configuration file, then its vaule shall be updated. If there is no corresponding name then the name value shall be added to the end of the file. If there is no file it shall be created. The personal configuration file is "~/.ncustom/NCustom/MyConfig.pm".
If some configuration vlaues are defined in terms of other configuration values, then the order may be important.
ncustom
ncustom(<<' EOF');
~/test1.ncus
test2.ncus
EOF
Ncustom is passed one or more filenames, either local filenames or URLs. The filenames are assumed to be NCustom scripts, are fetched, and executed. If the filename is not an NCustom script, then transactions will not be journalled, and will not be able to be undone. An unqualified NCustom script name will be searched for in pwd and the location(s) specified in NCustom::Config. URLs will be fetched using the get_url subrouting in NCustom::Config.
SEE ALSO
NCustom NCustom::Config ncustom
http://baneharbinger.com/NCustom
AUTHOR
Bane Harbinger, <bane@baneharbinger.com>
COPYRIGHT AND LICENSE
Copyright 2003 by Bane Harbinger
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 93:
You can't have =items (as at line 223) unless the first thing after the =over is an =item