Changes

<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.

This script sets the <var class="LITERAL">ExternalIP</var> value and the <var class="LITERAL">IPAddress</var> property of the <var class="LITERAL">ExternalInterface</var> record in the configuration database to the value provided as a parameter. The <var class="LITERAL">$event</var> parameter is not used in this particular script.

This script sets the <var class="LITERAL">ExternalIP</var> value and the <var class="LITERAL">IPAddress</var> property of the <var class="LITERAL">ExternalInterface</var> record in the configuration database to the value provided as a parameter. The <var class="LITERAL">$event</var> parameter is not used in this particular script.

 

{{Note box|msg=The two records exist due to an partial migration from simple to complex entries in the configuration database. Setting both values in this script avoids the need to perform database migration in the ip-change event.}}

<div class="NOTE"><blockquote class="NOTE">

<div class="SECT2">

 

'''Note: '''The two records exist due to an partial migration from simple to complex entries in the configuration database. Setting both values in this script avoids the need to perform database migration in the ip-change event.

 

</blockquote></div><div class="SECT2">

----

----

===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.

You should normally link your action scripts in the range <var class="LITERAL">S10</var> to <var class="LITERAL">S80</var> so that they occur after <var class="LITERAL">templates2expand</var> and before <var class="LITERAL">services2adjust</var>.

You should normally link your action scripts in the range <var class="LITERAL">S10</var> to <var class="LITERAL">S80</var> so that they occur after <var class="LITERAL">templates2expand</var> and before <var class="LITERAL">services2adjust</var>.

 

{{Note box|msg=The <tt>generic_template_expand</tt> action is currently run at <var class="LITERAL">S05</var> and <tt class="FILENAME">adjust-services</tt> is run at <var class="LITERAL">S90</var>. The order of action scripts within an event is subject to change between releases.}}

<div class="NOTE"><blockquote class="NOTE">

</div></div><div class="SECT2">

 

'''Note: '''The <tt class="FILENAME">generic_template_expand</tt> action is currently run at <var class="LITERAL">S05</var> and <tt class="FILENAME">adjust-services</tt> is run at <var class="LITERAL">S90</var>. The order of action scripts within an event is subject to change between releases.

 

</blockquote></div></div></div><div class="SECT2">

----

----

===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.

But how is the action code to know which user was just added? The new username is passed as an argument to the user-create event. This way the action programs triggered by the user-create event have a choice. They can either ignore the username argument and regenerate their output based on the updated list of accounts, or they can pay attention to the username argument, retrieve the rest of the information about the new user from the <tt class="FILENAME">accounts</tt> database, and perform the incremental work to add the user.

But how is the action code to know which user was just added? The new username is passed as an argument to the user-create event. This way the action programs triggered by the user-create event have a choice. They can either ignore the username argument and regenerate their output based on the updated list of accounts, or they can pay attention to the username argument, retrieve the rest of the information about the new user from the <tt class="FILENAME">accounts</tt> database, and perform the incremental work to add the user.

Events are not currently serialized. In most cases overlapping events will not cause issues, but caution should be exercised when events are signalled from programs.}}

 

</div><div class="SECT2">

 

Events are not currently serialized. In most cases overlapping events will not cause issues, but caution should be exercised when events are signalled from programs.

 

</blockquote></div></div><div class="SECT2">

----

----

===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.

 

{{Note box|msg=Events which are not listed in this table are subject to change and may not appear in future releases of the SME Server.}}

<div class="NOTE"><blockquote class="NOTE">

<div class="TABLE">

 

'''Note: '''Events which are not listed in this table are subject to change and may not appear in future releases of the SME Server.

 

</blockquote></div><div class="TABLE">

 

{| class="CALSTABLE" border="1"

{| class="CALSTABLE" border="1"

! Event

! Event

! Argument

! Argument

! Description

! Description

| bootstrap-console-save

| bootstrap-console-save

| (none)

| (none)

----

----

===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.