Thomson Gateway Embedded Script Files

Date: Version:

June 2008 v2.0

Abstract:

This application note guide describes the use and functionality of the so called embedded script files. This application note applies to all platform firmware releases from R7.4.2 on and upwards.

Applicability:

Updates:

Thomson continuously develops new solutions, but is also committed to improving its existing products. For more information on Thomson's latest technological innovations, documents and software releases, visit us at http://www.thomson-broadband.com

Chapter 1

Script Files (STS)

Acronym
Most commonly referred to as STS files, script files are text files which contain one or more sequentially ordered Command Line Interface (CLI) commands that can be executed on the Thomson Gateway. There are different ways of executing these scripts on the Thomson Gateway: locally after transferring the file to the Thomson Gateway via File Transfer Protocol (FTP). remotely by means of the Remote Procedure Call "Download" (with FileType equal to "3 Vendor Configuration File") in the TR-069 protocol. The Thomson Gateway will recognize an STS file by means of the STS file extension (as opposed to a INI file). remotely by automatic downloading via BOOTP/TFTP.

Format of STS files

A valid command line script file needs to comply with the following rules: the first line must include the following two space-separated fields: TPVERSION=x: this is the so-called tag-parser version that indicates the command line interface syntax version. The tag-parser version defines the CLI command syntax compatibility. BOARD_NAME=y: this is the hardware platform mnemonic (BANT-8, CANT-A,) Commands are absolute, meaning they include the full path from CLI root menu. All CLI commands are executed in sequence. This is an example of the content of a simple STS-file:
TPVERSION=2.0.0 BOARD_NAME=BANT-X :env set var=CONF_VERSION value=1.1.1 :dsd urlfilter rule add url=www.yahoo.com action=redirect redirect=www.google.net :dsd urlfilter rule add url=www.cisco.com action=block

The order of CLI commands is important. An STS file should always be closed with a carriage return (\CR), otherwise the last line in the STS file will not be executed. On most text editors this is the equivalent of one white line after the set of commands.

Testing and debugging of STS files

STS files can be tested locally as explained below. It is assumed that the user has already prepared a STS file for testing called "test.sts". The steps for local debugging are the following: 1 Connect your computer via the LAN to the Thomson Gateway. Use any FTP client of your choice to upload the "test.sts" file to the file system of the Thomson Gateway. The file needs to be placed in the / dl directory. Start a TELNET session to the Thomson Gateway and execute the following command: :config load echo=enabled filename=test.sts 3 The Thomson Gateway will now execute one by one the commands as specified in the "test.sts" files and print the output of these commands to the TELNET prompt. If any errors pop up they can be spotted and corrected here.

E-DOC-CTC-20071112-0001 v2.0

Chapter 2

Embedded STS Files

Mechanism
Embedded STS files have exactly the same file format and conventions as a normal STS file. An embedded STS file however is executed only once, i.e. after a remote firmware upgrade. The advantage is that it only requires one CPE WAN Management Protocol (CWMP) action to download a new build and update the configuration afterwards, whilst the user configuration is kept and restored. This allows to apply a firmware upgrade that preserves the user configuration but additionally applies either configuration changes or updates (e.g. for new added functionality). "Embedded" refers to the fact that these STS files are not remotely downloaded to the Thomson Gateway, but are embedded in the firmware. The process of embedding these STS files is executed during customization, prior to delivery. The embedded STS file is executed only once in its lifecycle: immediately after the upgrade to the software build it is embedded in. That means that after a remote upgrade, the Thomson Gateway will reboot, load the user.ini file and it will run the commands that are included in the STS file. After an embedded STS file has been executed once, it will not be executed again, not even after a factory reset. Even when the same firmware release is uploaded twice to the same Thomson Gateway, the device will execute the embedded STS only once (the first time, that is).

Implementation
Two prerequisites are needed for activating the embedded STS files after an upgrade process: a platform firmware and the STS file tailored to your needs. During the customisation phase, the STS files is renamed to "upgrade.sts" and added to the archive of the build. This step is done through customization. The remote firmware upgrade process with embedded STS file consists of the following steps: 1 2 3 4 5 The Thomson Gateway receives the RPC:Upgrade command. The Thomson Gateway initiates a download of the firmware. After this download, the Thomson Gateway will reboot to load the new firmware into the flash. At the end of the booting process, the Thomson Gateway will perform a config load of the user configuration (user.ini) or factory defaults (in case no user.ini present). The Thomson Gateway will check if an "upgrade.sts" file is present. If this is the case, and if no sts<_build >.upg flag is present in the directory /dl (this means the STS file has not been run before), then the Thomson Gateway will do the following: Perform the command :config load "upgrade.sts". Write the sts<_build>.upg flag. Perform a :saveall. The sts<_build>.upg flag holds a reference to the firmware version to make the distinction between flags originating from previous firmware upgrades. This allows to execute each STS exactly one time.The flag cannot be removed manually. Immediately after loading the embedded STS file the flag is written to prevent it from being loaded again afterwards. A saveall is performed by default after loading the STS file, so there is no need to include it in the STS file.

E-DOC-CTC-20071112-0001 v2.0

Visit us at:
www.thomson-broadband.com

Coordinates:
Thomson Telecom Prins Boudewijnlaan 47 B-2650 Edegem Belgium

Copyright
2008 Thomson. All rights reserved. The content of this document is furnished for informational use only, may be subject to change without notice, and should not be construed as a commitment by Thomson. Thomson assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The information contained in this document represents the current view of Thomson on the issues discussed as of the date of publication. Because Thomson must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Thomson, and Thomson cannot guarantee the accuracy of any information presented after the date of publication. This document is for informational purposes only. Thomson MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AS TO THE INFORMATION IN THIS DOCUMENT. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.