Quattor Documentation Release 0.0.1
Total Page:16
File Type:pdf, Size:1020Kb
Quattor Documentation Release 0.0.1 Quattor Community Oct 30, 2018 Contents 1 Content 3 i ii Quattor Documentation, Release 0.0.1 This is the official documentation for Quattor: • configuration-modules-core • configuration-modules-grid • CAF • CCM • Unit Testing Also see the Quattor homepage for more information. Contents 1 Quattor Documentation, Release 0.0.1 2 Contents CHAPTER 1 Content 1.1 CAF 1.1.1 Common Application Framework This is the Perl Common Application Framework (CAF) for Quattor. It is a library encapsulating most annoying details like reporting, file handling or command executions. It gives a unified way of doing potentially dangerous things in the right way. 1.1.2 Applicability Quattor developers must use modules here for: • Executing commands (see CAF::Process). • Manipulating files (see CAF::FileWriter and CAF::FileEditor). • Reporting. Most likely, your code receives a $self object that provided CAF’s interfaces. 1.1.3 Content Application NAME CAF::Application - Common Application Framework core class 3 Quattor Documentation, Release 0.0.1 SYNOPSIS package example; use strict; use warnings; use LC::Exception qw (SUCCESS throw_error); use parent qw(CAF::Application); <extend/overwrite default methods here...> # Main loop package main; use strict; use warnings; use LC::Exception qw (SUCCESS throw_error); use vars ($this_app%SIG); unless ($this_app= example->new($0,@ARGV)) { throw_error (...); } $this_app->report("Hello"); ... DESCRIPTION CAF::Application is the core class which provides command line and configuration file parsing, and general applica- tion methods. Applications can extend or overwrite the default methods. Public methods name(): string Return the application name (basename) version(): string Returns the version number as defined in $self->{‘VERSION’}, or <unknown> if not defined. hostname(): string Returns the machine’s hostname. username(): string Returns the name of the user. option_exists($opt): boolean Returns true if the option exists, false otherwhise. Option can be defined either in the application config- uration file or on the command line (based on AppConfig module). option($opt): scalar|undef 4 Chapter 1. Content Quattor Documentation, Release 0.0.1 Returns the option value coming from the command line and/or configuration file. Scalar can be a string, or a reference to a hash or an array containing the option’s value. option() is a wrapper on top of AppConfig->get($opt). If the option doesn’t exist, returns undef, except if the defaultargument has been specified: in this case this value is returned but the option remains undefined. set_option($opt, $val): SUCCESS Defines an option and sets its value. If the option was previously defined, its value is overwritten. This is a wrapper over AppConfigmethods to hide the internal implementation of a CAF::Application. This method always returns SUCCESS. show_usage(): boolean Prints the usage message of the command based on options and help text. show_version(): boolean prints the version number of the Application. app_options(): ref(array) to be overloaded by the application with application specific options. This function has to return a reference to an array. Every element in the array must be a reference to a hash with the following structure: NAME=> option name specification in the Getopt::Long(3pm) format "name|altname1|altname2|..[argument_type]" DEFAULT=> [optional] default value (string). If not specified: undef HELP=> help text (string) example: push(@array, {NAME=>'M|myoption=s', DEFAULT=>'defaultvalue', HELP=>'do somewhat on something'}); return \@array; see also _app_default_options() Private methods _initialize Initialize the Application. Arguments $command Name of the script/command/. (typically $0). Remaining arguments @argv Typically this is the perl builtin variable @ARGV, but can be any array of options/arguments, or a single arrayref (in which case all elements of the arrayref are handled as options/arguments). Any arguments that are not handled by the options, can be retrieved either via @ARGV or by passing an arrayref holding the options/arguments. In these 2 cases, the contents is modified, 1.1. CAF 5 Quattor Documentation, Release 0.0.1 removing all handled options, leaving the non-option arguments in place. (In particular, using a regular array will leave the original array unmodified). _app_default_options This method specifies a number of default options, with the same format as app_options. The options are: debug <debuglevel> : sets debug level (1 to5) help : prints out help message quiet : no output verbose : verbose output version : print out version number& exit The ‘noaction’, ‘cfgfile’ and ‘logfile’ options are not enabled by default but recognized (they have to be added to the application specific code - see the ‘example’ file): noaction : execute no operations cfgfile <string>: use configuration file <string> logfile <string>: use log file <string> _add_options add options coming from _app_default_options() and app_options() Download :: LWP NAME CAF::Download::LWP class to use LWP (and Net::HTTPS). DESCRIPTION CAF::Download::LWP prepares LWP (and Net::HTTPS) and provides interface to LWP::UserAgent. Remarks wrt SSL/TLS: If LWP is recent enough (v8.333, e.g. on EL6+), the choice of SSL module will be the system default (typically IO::Socket::SSL when available, Net::SSL otherwise). The usual environment variable will not be honoured (this module will typically be executed in a minimal environment anyway). When LWP is too old, Net::SSL will be forced (e.g. on EL5). If LWP is recent enough and IO::Socket::SSL is the default, hostname verification is forced. METHODS _initialize Initialize the object. Optional arguments: log A CAF::Reporter object to log to. 6 Chapter 1. Content Quattor Documentation, Release 0.0.1 _get_ua Prepare the environment and initialise LWP::UserAgent. Best-effort to handle ssl setup, Net::SSL vs IO::Socket::SSLand verify_hostname. Example usage . my $ua = $self->_get_ua(%opts); local%ENV=%ENV; $self->update_env(\%ENV); ... Returns the LWP::UserAgent instance or undef. Options cacert: the CA file cadir: the CA path cert: the client certificate filename key: the client certificate private key filename ccache: the kerberos crednetial cache timeout: set timeout _do_ua Initialise LWP::UserAgent using _get_ua method and run method with arrayref args. All named options are passed to _get_ua. Exception NAME CAF::Exception - provides basic methods for failure and exception handling Private methods _get_noaction Return NoAction setting: Return 0 is keeps_state is true Any other value of keeps_state is ignored. (In particular, you cannot use keeps_state to enable NoAction). Return value of noAction method (when defined) CAF::Object::NoAction otherwise Supports an optional msg that is prefixed to reporter. _reset_exception_fail Reset previous fail attribute and/or exception. msg is a suffix when reporting the old fail attribute and/or exception error (with debug level 1). 1.1. CAF 7 Quattor Documentation, Release 0.0.1 EC is a LC::Exception::Context instance that is checked for an existing error, which is set to ignore if it exists. Always returns SUCCESS. _function_catch Execute function reference funcref with arrayref $args and hashref $opts. Method resets any existing fail attribute and error from LC::Exception::Context instance EC. When an exception thrown is thrown, it is catched and reset. No error is reported and undef is returned in this case and the fail attribute is set with the exception error text. _safe_eval Run function reference funcref with arrayref argsref and hashref optsref. Return and set fail attribute with failmsg ($@ is added when set) on die or in case of an error (undef returned by funcref). In case of success, report msg (stringified result is added unless sensitive attribute is set) at verbose level. Note that _safe_eval doesn’t work with functions that don’t return a defined value when they succeed. Resets previous fail attribute and or exceptions (via the LC::Exception::Context instance EC). FileEditor NAME CAF::FileEditor - Class for securely making minor changes in CAF applications. DESCRIPTION This class should be used whenever a file is to be opened for modifying its existing contents. For instance, if you want to add a single line at the beginning or the end of the file. As usual, all operations may be logged by passing a log argument to the class constructor. Public methods new Returns a new object it accepts the same arguments as the constructor for CAF::FileWriter with one additional option: source This option, when present, must be a file name whose contents will be used as the initial contents for the edited file if the source modification time is more recent than the edited file modification time. This allows to rebuild the file contents based on a new version of the reference file. The source can be a pipe: in this case, it is always considered more recent than the edited file. open Synonym for new() 8 Chapter 1. Content Quattor Documentation, Release 0.0.1 set_contents Sets the contents of the file to the given argument. Usually, it doesn’t make sense to use this method directly. Just use a CAF::FileWriter object instead. head_print Appends a line to the very beginning of the file. seek_begin Seek to the beginning of the file. seek_end Seek to the end of the file. replace_lines(re, goodre, newvalue) Replace any lines matching re but *not* goodre with newvalue. If there is no match, nothing will be done. For instance, $fh->replace(qr(hello.*), qr(hello.*world), 'hello and good bye, world!') Will replace all lines containing ‘hello’ but not world by the string ‘hello and good bye, world!’. But if the file contents are There was Eru, who in Arda is called Iluvatar it will be kept as is. This is useful when we want to change a given configuration directive only if it exists and it’s wrong. The regular expressions can be expressed with the qr operator, thus allowing for modification flags such as i. add_or_replace_sysconfig_lines(key, value, whence) Replace the value in lines matching the key.