2,411
edits
Changes
Jump to navigation
Jump to search
mLine 1:
Line 1: − + − + Line 37:
Line 37: − + Line 48:
Line 48: − + Line 66:
Line 66: − + Line 73:
Line 73: − + Line 86:
Line 86: − + Line 93:
Line 93: − + Line 106:
Line 106: − + Line 117:
Line 117: − + Line 134:
Line 134: − + Line 226:
Line 226: − + Line 241:
Line 241: − + Line 269:
Line 269: − +
SME Server:Documentation:Developers Manual:Chapter7 (view source)
Revision as of 13:28, 25 April 2008
, 13:28, 25 April 2008Adjusting header(s)
<div class="CHAPTER">
<div class="CHAPTER">
=Actions and events=
==Actions and events==
<div class="SECT1">
<div class="SECT1">
==Actions==
===Actions===
An action is a program, frequently written in a scripting language, which performs a single task. It is typically an encapsulation of a task usually done by a system administrator, such as editing a configuration file or reconfiguring a service. Actions are not called directly; they are always called by signalling an event.
An action is a program, frequently written in a scripting language, which performs a single task. It is typically an encapsulation of a task usually done by a system administrator, such as editing a configuration file or reconfiguring a service. Actions are not called directly; they are always called by signalling an event.
----
----
===Action script parameters===
====Action script parameters====
Action scripts are always called with at least one parameter; the name of the current event. Many action scripts, such as <tt class="FILENAME">set-external-ip</tt> , are called with a single additional parameter. This parameter is usually a configuration database key, for example the username being modified or the new IP address.
Action scripts are always called with at least one parameter; the name of the current event. Many action scripts, such as <tt class="FILENAME">set-external-ip</tt> , are called with a single additional parameter. This parameter is usually a configuration database key, for example the username being modified or the new IP address.
----
----
==Events==
===Events===
Events are a mechanism which allows the system to trigger a set of actions in response to actual events that happen on the system. When one of the users interfaces modifies the configuration databases, it must signal an event to regenerate the various server application configuration files according to the new configuration. <span class="emphasis">''The user interface must never modify configuration files directly.''</span>
Events are a mechanism which allows the system to trigger a set of actions in response to actual events that happen on the system. When one of the users interfaces modifies the configuration databases, it must signal an event to regenerate the various server application configuration files according to the new configuration. <span class="emphasis">''The user interface must never modify configuration files directly.''</span>
----
----
===Implicit actions: services2adjust and templates2expand===
====Implicit actions: services2adjust and templates2expand====
Most events contain two common tasks: expanding various templates and adjusting (e.g. restarting) the relevant services. For this reason, two implicit actions are included in all events. These implicit actions mean that additional code does not need to be written to perform these common tasks. The implicit actions are represented by entries in the <tt class="FILENAME">services2adjust/</tt> and <tt class="FILENAME">templates2expand/</tt> subdirectories.
Most events contain two common tasks: expanding various templates and adjusting (e.g. restarting) the relevant services. For this reason, two implicit actions are included in all events. These implicit actions mean that additional code does not need to be written to perform these common tasks. The implicit actions are represented by entries in the <tt class="FILENAME">services2adjust/</tt> and <tt class="FILENAME">templates2expand/</tt> subdirectories.
----
----
====services2adjust====
=====services2adjust=====
The <tt class="FILENAME">services2adjust/</tt> directory contains links mapping a specific service to the action to perform on that service. For example, if signalling the event in question requires that the <var class="LITERAL">ntpd</var> service is restarted, you simply include the link <var class="LITERAL">ntpd -> restart</var> in the <tt class="FILENAME">services2adjust</tt> directory. The implicit action services2adjust would then restart the ntpd service. As an example, the <tt class="FILENAME">services2adjust/</tt> directory for the <var class="LITERAL">ip-change</var> event is shown below:
The <tt class="FILENAME">services2adjust/</tt> directory contains links mapping a specific service to the action to perform on that service. For example, if signalling the event in question requires that the <var class="LITERAL">ntpd</var> service is restarted, you simply include the link <var class="LITERAL">ntpd -> restart</var> in the <tt class="FILENAME">services2adjust</tt> directory. The implicit action services2adjust would then restart the ntpd service. As an example, the <tt class="FILENAME">services2adjust/</tt> directory for the <var class="LITERAL">ip-change</var> event is shown below:
----
----
====templates2expand====
=====templates2expand=====
The <tt class="FILENAME">templates2expand/</tt> directory contains a list of the configuration files which need to be regenerated from their templates. This list consists of a collection of empty files with the same file name as the configuration file to be expanded and in a heirarchy mirroring their location on the system. For example, to expand templates for the <tt class="FILENAME">/etc/samba/smb.conf</tt> configuration file, simply include the empty file <tt class="FILENAME">etc/samba/smb.conf</tt> in the <tt class="FILENAME">templates2expand/</tt> directory of the relevant event(s). For more detail, see [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#TEMPLATES2EXPAND the Section called ''Mapping templates to events: templates2expand'' in Chapter 8].
The <tt class="FILENAME">templates2expand/</tt> directory contains a list of the configuration files which need to be regenerated from their templates. This list consists of a collection of empty files with the same file name as the configuration file to be expanded and in a heirarchy mirroring their location on the system. For example, to expand templates for the <tt class="FILENAME">/etc/samba/smb.conf</tt> configuration file, simply include the empty file <tt class="FILENAME">etc/samba/smb.conf</tt> in the <tt class="FILENAME">templates2expand/</tt> directory of the relevant event(s). For more detail, see [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#TEMPLATES2EXPAND the Section called ''Mapping templates to events: templates2expand'' in Chapter 8].
----
----
====Order of implicit actions====
=====Order of implicit actions=====
The implicit actions are implemented by inserting the action script <tt class="FILENAME">generic_template_expand</tt> early in the list of actions to be run in an event and the <tt class="FILENAME">adjust-services</tt> action near the end of the list.
The implicit actions are implemented by inserting the action script <tt class="FILENAME">generic_template_expand</tt> early in the list of actions to be run in an event and the <tt class="FILENAME">adjust-services</tt> action near the end of the list.
----
----
===Signalling events===
====Signalling events====
The <tt class="FILENAME">signal-event</tt> program takes an event name as an argument, and executes all of the actions in that event, providing the event name as the first parameter and directing all output to the system log. It works by listing the entries in the event directory and executing them in sequence. So for example, the command:
The <tt class="FILENAME">signal-event</tt> program takes an event name as an argument, and executes all of the actions in that event, providing the event name as the first parameter and directing all output to the system log. It works by listing the entries in the event directory and executing them in sequence. So for example, the command:
----
----
===Events with arguments===
====Events with arguments====
So far we have described the following general principle throughout the SME Server; changes are made by altering the configuration files, then signalling events. The actions triggered by each event typically regenerate entire configuration files, taking into account the latest configuration information.
So far we have described the following general principle throughout the SME Server; changes are made by altering the configuration files, then signalling events. The actions triggered by each event typically regenerate entire configuration files, taking into account the latest configuration information.
----
----
===Standard events and their arguments===
====Standard events and their arguments====
The table below summarises the key SME Server events and their argument if required. Remember, each action script is always called with the event name as the first argument. The arguments listed in this table are provided as the second argument.
The table below summarises the key SME Server events and their argument if required. Remember, each action script is always called with the event name as the first argument. The arguments listed in this table are provided as the second argument.
----
----
===Handling deletions===
====Handling deletions====
When adding a user, the user is created in the <tt class="FILENAME">accounts</tt> database, and various actions, such as creating the Linux account, are performed in the <tt class="FILENAME">user-create</tt> event. However, when deleting a user, we want to maintain the <tt class="FILENAME">accounts</tt> database entry for as long as possible, in case there is information which the actions in the <tt class="FILENAME">user-delete</tt> event might need in order to cleanly delete the users.
When adding a user, the user is created in the <tt class="FILENAME">accounts</tt> database, and various actions, such as creating the Linux account, are performed in the <tt class="FILENAME">user-create</tt> event. However, when deleting a user, we want to maintain the <tt class="FILENAME">accounts</tt> database entry for as long as possible, in case there is information which the actions in the <tt class="FILENAME">user-delete</tt> event might need in order to cleanly delete the users.
----
----
===Event logs===
====Event logs====
All events, and all actions run by the event, are logged to the <tt class="FILENAME">messages</tt> system log. Here is an example action log, which has been formatted onto multiple lines to enhance readability:
All events, and all actions run by the event, are logged to the <tt class="FILENAME">messages</tt> system log. Here is an example action log, which has been formatted onto multiple lines to enhance readability:
----
----
===Failed events===
====Failed events====
<span class="emphasis">''If an action script fails, the entire event fails.''</span> The other actions scripts in the event are run, but the whole event is marked as having failed.
<span class="emphasis">''If an action script fails, the entire event fails.''</span> The other actions scripts in the event are run, but the whole event is marked as having failed.