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