Example of Custom Script

Applies to platform: UTM 3.0, Edge 3.0, UTM 5.0, Edge 5.0
Updated on: 09th November 2017

The ability to upload custom python scripts to Endian Appliances is a recently introduced feature. Scripts must adhere to a few guidelines that are illustrated in this lesson, with the help of an example.

Guidelines for the Python Scripts

Guidelines make sure that the upload procedure correctly recognises the script as runnable on the Appliance and stores it on the Appliance. The list of guidelines is the following:

1. The script must be importable. In other words, the script can use other Python modules installed on the system, but can not rely on Python modules which are not present on the system.
2. The script must implement a class called ScriptEvent.
3. A method called exactly __init__(self) must be implemented in the ScriptEvent class. This method, which can be empty or contain some variables or code, initialises the script.
4. A method called process must be implemented in the ScriptEvent Class. This method is the one that will be invoked when the event to which it is associated takes place.
5. The process method must accept the **kwargs parameter. In other words, it must accept a dictionary of key : value parameters.

An Example Script

As a sample scenario, consider an Endian Appliance connected to a remote VPN concentrator. You would like to ensure that when an uplink goes offline, the OpenVPN client does not try to reconnect.

To achieve this goal, you need to write a few lines of python code. Let's first see a detailed list of the requirements and see what parts of the API it is necessary to access.

1. The script must be triggered right after the uplink goes offline.
2. Settings and information about the uplink must be retrieved and slightly modified. The system configuration, of which the uplink is part, is handled by the DataSource package.
3. Next, as the script must interact with the OpenVPN client, access to the OpenVPN client's restartscripts is mandatory.
4. To make sure the OpenVPN client does not try to connect with the uplink not working, temporary modify one of its settings to disable the automatic reconnection.
5. Finally, restart the client. Since the connection is set to disable, no connection attempt will take place.

To carry out point 1. above, please follow the procedure described in this lesson. This should however be done after the script has beel written and uploaded to the Endian Appliance.

First of all, open your favourite text editor, which can be nano on the Endian Appliance's command line; notepad, notepad++, or wordpad on Windows systems; gedit, mousepad, or kate on Linux boxes. Of course, any IDE with python support can be used as well.

And now, let's start writing some code.

Define the interpreter to use to execute the script, which is python.

1       #!/usr/bin/python

Import into working space every module from the Endian DataSource package to get access to the system configuration - point 2. above.

2       from endian.data.ds import *

Import from the restartscripts package only those for the OpenVPN client - point 3. above.

3       import endian.restartscripts.openvpnclients as openvpn

Create the ScriptEvent class, as required by the guidelines - Guideline 2.

4       class ScriptEvent(object):

Add an __init__ method right after the ScriptEvent class definition. The method can be empty, but if you want to add some code therein, replace the pass keyword with the code you deem necessary, like e.g., a variable definition - Guideline 3.

5           def __init__(self):
6           pass

Create the method process with the **kwargs argument as required by the guidelines - Guidelines 4. and 5.

7           def process(self, **kwargs):

Now, retrieve the name of the uplink.

8               uplink_name = kwargs.get("UPLINK")

Read the configuration for the OpenVPN client connection. In the following line, CONNECTION_NAME must be replaced with your connection's name, while SETTINGS is the part of the data that you need to retrieve, which are the settings of the OpenVPN client connection.

9               configuration = DataSource('openvpnclients')['OPENVPN_CLIENT_TO_WORK_WITH']['SETTINGS']

fullConfiguration = DataSource()

Disable the OpenVPN connection - point 4. above.

10              configuration['ENABLED'] = 'off'

Write the configuration and apply the settings: The OpenVPN tunnel is turned off.

11              configuration.write()
12              clients = openvpn.OpenVPNClientsJob()

Finally, force the client's restart. While this action might seem counterintuitive, it will apply the configuration and make sure it is correct, but not start the OpenVPN tunnel and neither start the other services, as the ENABLED value is set to off.

13              clients.restart_client('OPENVPN_CLIENT_TO_WORK_WITH')

In this simple example, no value has to be returned, so make sure that the process method always succeds.

14              return True

The resulting script thus becomes:

#!/usr/bin/python

from endian.data.ds import *
import endian.restartscripts.openvpnclients as openvpn

class ScriptEvent(object):

   def __init__(self):
   pass

   def process(self, **kwargs):
      uplink_name = kwargs.get("UPLINK")
      configuration = DataSource('openvpnclients')['OPENVPN_CLIENT_TO_WORK_WITH']['SETTINGS']
      configuration['ENABLED'] = 'off'
      configuration.write()
      clients = openvpn.OpenVPNClientsJob()
      clients.restart_client('OPENVPN_CLIENT_TO_WORK_WITH')
      return True

Finally, to associate the script to the event, refer to this lesson.