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:
ng_cfdepend
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.
ng_cforder
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.
ng_debug
Set the _DEBUG variable.
ng_extralogs
A list of extensions for any additional logfiles to be rotated.
ng_logperms
The permission mode for the logfile. If this resource is null, the logfile pemissions will not be changed.
ng_logrotate
A list of tags representing additional lines to be inserted in the logrotate file.
ng_logrotate_tag
The logrotate line corresponding to tag.
ng_monitor
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).
ng_prod
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.
ng_prodmethod
The component method to call to "prod" the component.
ng_reconfig
This resource is interpreted by the LCFG client to determine the method to call when the component resources have changed.
ng_statusdisplay
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".
ng_syslog
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.
ng_verbose
Set the _VERBOSE variable.
ng_ports
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.
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 7ngeneric 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.
Hey! The above document had some coding errors, which are explained below:
You can't have =items (as at line 144) unless the first thing after the =over is an =item