ngeneric - LCFG new generic component.
This component is intended for inclusion by other LCFG components. It provides a supporting framework including default methods and utility functions.
The components should include /usr/lib/lcfg/components/ngeneric and call the Dispatch function with the command line arguments. The lcfg component example shows how this is used in practice.
Components can override the following functions:
This routine is called when the configure method, is invoked, as well as start and restart. ngeneric will have placed the values of all resources into the environment with variable names of the form LCFG_
resource.
This routine should (re)create any necessary configuration files, and restart or signal any affected daemons. It is up to the component to determine which (if any) individual resources have changed and to minimize the reconfiguration appropriately (the template processor can help with this).
The component should call Fail() if the reconfiguration fails.
This routine gets called when the start or restart methods are invoked, either manually, or at boot time. Configure will be called before Start leaving the resources available in the environment.
The component should override this routine to start any necessary daemoms.
This routine gets called when a component is stopped, either manually, or at shutdown time (or for a restart). The component should override this routine to stop any necessary daemons. When the routine is called, ngeneric will have placed the configuration (as saved at the last configure) into the environment.
This routine gets called when the run method is invoked. The component should override this routine to perform any necessary operations. When the routine is called, ngeneric will have placed the configuration (as saved at the last configure) into the environment.
This routine gets called when the logrotate method is invoked, normally by the logrotate script when the logfile has been rotated. The component should override this routine to arrange for any running daemons to release the logfile. The environment contains the configuration saved at the last configure/start.
Take any APM suspend action. The environment contains the configuration saved at the last configure/start. This routine is not protected by the normal semaphore.
Take any APM suspend action. The environment contains the configuration saved at the last configure/start. This routine is not protected by the normal semaphore.
Reset the error and warning status files. The existence of these files determines the status of the error and warning icons on the server status page. These files are deleted when the component starts.
Display status information. The environment contains the configuration saved at the last configure/start. The default routine displays the values of the resources at the last configuration.
Display log information. The environment contains the configuration saved at the last configure/start. The default routine displays the current logfile.
Report monitoring information (by calling Notify) for the tag specified by the first argument. The environment contains the configuration saved at the last configure/start. The default routine reports an error.
Takes a single argument which is the sysinfo resource name. It sets an environment variable containing the resource value. e.g.
GetSysInfo "OS_NAME"
Debug "OS name is $LCFG_sysinfo_os_name"
Takes a single argument which is the identifier name of the path and sets an environment variable which holds the path. e.g.
GetSysPath "LCFGBIN"
Debug "lcfgbin path is $LCFGBIN"
Components should avoid writing to STDOUT/STDERR since this may be lost, or may clutter the startup screen. The functions Debug(), Info(), Warn() and Fail() should be used to output short messages. By default, STDERR and STDOUT are redirected to the component logfile. The file descriptors 11 and 12 are opened on the original STDOUT and STDERR respectively for those cases where a method absolutely needs to write to these channels - for example to print a console prompt, or to perform a Log() or Status() method.
Some component resources are interpreted by the ngeneric component or the LCFG client. The names of these resources all begin with ng_ and care should be taken not to use these names for other purposes:
This resource is interpreted by the LCFG client to determine which components should be reconfigured when resources change. The resource should include a list of dependencies of the form >component or <component. In the first case, the specified component will be reconfigured whenever the resources of this component change. In the second case, this component will be reconfigured whenever the resources of the specified component change. The default is <self.
The client default file specifies that the server should use this resource to order the client.components list. (The client.components resource specifies the order in which components should be reconfigured after a configuration change.) ng_cforder specifies a list of constraints on the the order in which the components are reconfigured. A constraint of the form >comp means that this component must be configured after comp. Similarly, <comp means that this component must be configured before comp.
Set the _DEBUG variable.
A list of extensions for any additional logfiles to be rotated.
The permission mode for the logfile. If this resource is null, the logfile pemissions will not be changed.
A list of tags representing additional lines to be inserted in the logrotate file.
The logrotate line corresponding to tag.
If this facility is set to the name of a file, then all errors, warnings and monitoring information will be appended to the named file, if it exists. This is typically set to a named pipe (eg. /var/lcfg/tmp/monitor.fifo
to transmit information to a monitoring system (eg lcfg-pemsensor).
If this resource changes, the client will call the method specified by ng_prodmethod instead of calling ng_reconfig. The value of the resource is specifically unused. This can be used to force one-off execution of a particular method. For example, by setting ng_prod to some new value (typically a timestamp) and ng_prodmethod to restart, the component will restart when the new profile is received.
The component method to call to "prod" the component.
This resource is interpreted by the LCFG client to determine the method to call when the component resources have changed.
If this resource is true then the component will appear in the server status display. (default is true). If it has the value nocomp, then the component is assumed to be a "pseudo component" with no corresponding running code - in this case, no client acknowledgements are expected, and the component shows as "ok", rather than "unknown".
If this variable is set to the name of a syslog facility (eg. local3), then all error and warning messages will be copied to syslog with the specified facility.
Set the _VERBOSE variable.
The name of the service which is being managed by the component (e.g. httpd
or sshd
).
This is a list of TCP/UDP ports that are associated with this component which must be registered with the portreserve daemon. The portreserve daemon is a tool available on Linux which helps prevent the portmap mapping ports to other daemons. Any ports listed here will be reserved until they are released just prior to the ngeneric Start method being called. The ports can be expressed as names or numbers. They can have a /tcp
or /udp
suffix to specify the particular protocol.
This is a list of ngeneric plugins which should be run as part of the environment initialisation process for a method call. The tags must be the short names of modules in the LCFG::Component::Plugin
namespace (e.g. env
for LCFG::Component::Plugin::Env
).
The plugin system only works for Perl components, there is no support for Shell components. By default the following LCFG component methods will run environment initialization plugins: configure
, start
, restart
, stop
, run
, logrotate
, suspend
and resume
. The plugins are loaded and run by the CallPlugins
method in the LCFG::Component class which is in turn called by the InitializeEnvironment
method. If you wish to load plugins for other component-specific methods you should alter your code to call the InitializeEnvironment
method after loading the resources. If you need to do particularly complex environment initialization within a component then you should sub-class the InitializeEnvironment
method.
For each plugin it is possible to specify a set of parameters which will be passed in when the object is created.
This resource is used to specify the short name of the environment initialization module which should be used (e.g. env
). This will be in the LCFG::Component::Plugin namespace, the value is case-insensitive. You only need to specify this when you want a module with a different name from the plugin tag name (e.g. the tag is foo
but you need a module named env
). This can be useful if you want to configure the plugin differently for different component methods. You could, for example, have plugin tags named env_run
and env_conf
which both use the env
module, the first which is only used for the run
method and the second which is only used with the configure
method.
This resource is used to control the methods for which the plugin will be loaded. By default this resource is empty and it will be loaded for all methods. If this resource contains a set of method names then they will be considered as a whitelist and the plugin will only be loaded for those methods, the plugin will not be loaded for any unnamed method. Alternatively you can blacklist specific methods by having a list of method names each prefixed with a minus sign (i.e. -
). For example, if the value of the resource is -configure
then the plugin will be loaded for ALL supported methods EXCEPT configure. Alternatively, for example, if the value of the resource is configure
(note lack of minus prefix) then the plugin will ONLY be loaded for the configure method.
This is a list of parameters which will be passed in when the plugin object is created. Each parameter can have an associated value, if none is specified then the value 1
is used.
A value for the parameter for the particular plugin.
The user which the component will be run as when called using om. The default is root
, this should not normally need to be changed.
The group which the component will be run as when called using om. The default is lcfg
. Sometimes it is necessary to change this to ensure that the default group for any generated files is correct (e.g. it might need to be set to root
).
The umask to set before a component method is called. Must be expressed as an octal number with a leading zero. There is no default value for this resource which means the system-wide default umask will usually apply, this will probably change in the future. Components which care about keeping file contents secure need to set this resource.
This is a list of directories which should be searched for templates which are specified as a relative path when using the LCFG::Template template processor. The items in the list must be separated with whitespace, commas or colons. By default only the /usr/lib/lcfg/conf/comp_name
directory for the particular component is searched.
ngeneric uses lcfglock to create a semaphore on all method calls (with the exception of those noted above). The method unlock can be used to force the removal of the lockfile.
When the configure method is called, ngeneric will look for a logrotate configuration file in /usr/lib/lcfg/conf/component/logrotate
. This is passed through the template proprocessor sxprof to allow per-machine configuration.
If the component does not provide a logrotate file, the ngeneric logrotate file is used. This rotates the component logfile at some default interval and calls the component logrotate method in the postrotate script. The default logrotate file allows extra parameters to be added directly from component resources using the logrotate
resource. Eg:
foo.logrotate a b
foo.logrotate_a daily
foo.logrotate_b rotate 7
ngeneric creates local shell variables beginning with "_". The following variables may be of general use:
The name of the current component.
Enables debugging information. Set by a -D option.
Normally used to perform a dummy execution of the method call for testing. Set by a -d option.
The name of the log file.
Method specific flag, normally used to force a less strict interpretation of method semantics. For example, the start method will exit silently if the component is already running, rather than fail.
The message to be displayed when the method completes sucessfully. Components may append a string of the form {\tt (}{\em message}{\tt )} to this variable, to display additional status information when the method exits.
Disables unnecessary messages, including the "OK" message. This is useful when calling components from cron. Set by a -q option.
The name of the status file.
The lock timeout (in seconds). Set by a -t option.
Enables additional informational messages. Set by -v option.
It is possible to create additional ad-hoc methods. These should be exported with names of the form Method_
methodname, and they will be automatically called by the Dispatch function. Ad-hoc methods should arrange to call the Lock function if appropriate to prevent simultaneous method calls.
An example component.
The template processor.
This is the list of platforms on which we have tested this software. We expect this software to work on any Unix-like platform which is supported by Perl.
ScientificLinux6, EnterpriseLinux7, MacOSX
Please report any bugs or problems (or praise!) to bugs@lcfg.org, feedback and patches are also always very welcome.
Stephen Quinney <squinney@inf.ed.ac.uk>, Paul Anderson <dcspaul@inf.ed.ac.uk>
Copyright (C) 2002-2014 by University of Edinburgh
This library is free software; you can redistribute it and/or modify it under the terms of the GPL, version 2 or later.