The LSP Application Manager

The Lua Server Pages (LSP) Application Manager is designed as a boot loader for loading, starting, and stopping Lua Server Pages Applications in a running system.

The purpose of the application manager is:

• to make it easy to load and run our LSP example programs. The LSP example programs are provided online and can be downloaded separately. The LSP applications can be loaded after you have started and configured the LSP application manager.
• to make it easy for you to create your own LSP applications.
• to make it possible to dynamically start and stop LSP applications in a running system. Starting and stopping LSP applications in a running system is very useful during development.
• to make it possible to have multiple LSP applications running in the same executable/device. Running multiple applications is not necessary if you have only one application. The LSP application manager can be replaced with your own application, preferably after you have completed the development of your application.

Video tutorials

We recommend new users to view the WFS and the LSP Application Manager Videos. The LSP Application Manager requires the WFS when running in an embedded device without a file system.

Block Diagram

The LSP Application Manager includes the Barracuda Embedded Web Server which we will also refer to as the Barracuda Application Server, the Barracuda plugins, C startup code, and the LSP Application Manager. The LSP Application Manager is a Lua application embedded into the executable and is best visualized as LSP firmware. The LSP firmware is a compressed 250Kbyte ZIP file stored inside the executable and made available to the Lua Virtual Machine via the ZipIo -- i.e. the Barracuda ZIP File System.

The LSP Application Manager's Component Diagram:

The LSP Application Manager is shown in red in the top left corner in the above diagram. The LSP Application Manager is loaded, by the Lua VM, at startup from the embedded ZIP file.

The "C startup Code", which can be found in the subdirectory src/lsp.c in the Barracuda Embedded Web Server SDK, is responsible for assembling an application server. The C code is similar to the code described in the getting started guide. As an example, the C code initializes the Lua Virtual machine and loads the .config Lua script. The .config Lua script, loaded from the embedded ZIP file, initializes the Barracuda Virtual File System for the LSP Application Manager.

Getting Started

The LSP Application Manager is designed to run in anything from embedded systems without a file system to host operating systems such as Windows and Linux. Your Barracuda Embedded Web Server SDK comes with a pre-compiled LSP Application Manager for your host application. We suggest that you initially use the precompiled version before compiling your own version. We also deliver pre-compiled versions for some embedded systems. See our web site for more information.

The LSP Application Manager saves information about which applications you have loaded and the status of the applications in a configuration file. The location of the configuration file must be configured by you. The configuration file is saved as a cookie in the browser and is automatically loaded the next time you start the Application Manager and navigate to the Application Manager using your browser.

Creating the Configuration File

1. Start bin/lspappmgr.
2. Make note of the port number used by the server. The server attempts to open port 80, and if this fails, the server attempts to open port 9357.
3. Start your browser and navigate to http://localhost:9357, where 9357 is the port number used by the server.
4. Since you do not have any root applications, the LSP Application Manager's 404 (not found) page redirects you to the help page.
5. Read the help page.
6. Click the "Configure" tab and navigate to the configuration page.
7. Select the "disk" file system. If you are running the LSP Application Manager on an embedded system without a native file system, select the net file system.

   The NetIo is similar to a network file system and makes it possible for the server to access resources on another Barracuda server.

   The NetIo is a web file manager client specifically designed to operate a remote HttpResMgr aka the Web File Manager. In other words, the remote HttpResMgr's file system appears as a local file system to the code using an instance of the NetIo.

   You will get a severe performance degradation when using the NetIo since the NetIo generates multiple requests for each resource fetched. The following diagram illustrates a page request using the NetIo:

   Browser        Embedded System         Web File Manager
     |                   |                       |
     |    get page       |                       |
     | --------------->  |                       |
     |                   |  stat (file exists?)  |
     |                   | --------------------> |
     |                   |         yes           |
     |                   | <-------------------  |
     |                   |                       |
     |                   |   get fragment 1      |
     |                   | --------------------> |
     |                   |    fragment 1         |
     |     response      | <-------------------  |
     | <---------------  |                       |
     |                   |                       |
     |                   |   get fragment 2      |
     |                   | --------------------> |
     |                   |    fragment 2         |
     |     response      | <-------------------  |
     | <---------------  |                       |
     |                   |                       |
     |                   |                       |
   

   
   Opening a ZIP file over a NetIo

   It is possible to open a deployed LSP application over a NetIo, though opening the ZIP file takes time since the Barracuda ZIP File System does multiple disk seeks and read operations for each file inside the ZIP file, when initializing the ZIP File System. The larger the ZIP file, the longer it takes to initializing the ZIP File System. You should not resubmit the request when opening a ZIP file. Simply wait for the operation to complete.

   The NetIo speed is directly proportional to the speed of the TCP/IP stack being used in the embedded system. The faster the TCP/IP stack, the faster the NetIo will respond.

   Configure the net file system as follows:

   1. The bin directory contains a pre-compiled Web File Server. Start bin/wfs.
   2. Make note of to the port number used by the server.
   3. In the LSP Application Manager, select the net file system and click browse.
   4. Enter the path http://hostip:port/fs/, where hostip is your host computer's IP address and port is the port number the wfs executable is listening on.
   5. Press the "Submit" button.
   6. Continue with step 9 below.
8. Click the browse button after you have selected the file system.
9. Navigate to a location where you have read and write access.
10. Click the radio button to select the directory.
11. Click the "Submit" button to save the configuration file.

Loading, starting, and stopping LSP applications

You can navigate to the "New Application" folder as soon as you have created a LSP application manager configuration file. The "New Application" folder makes it possible to load deployed LSP applications and non deployed LSP applications.

• A deployed LSP application is a LSP application packaged into a ZIP file. Loading a deployed LSP application makes the LSP application manager create a ZIP file system that mounts the selected ZIP file. The ZIP file system works similar to a native file system, except that files can only be opened in read mode.
• A non-deployed LSP application is a directory somewhere on your native file system. A non-deployed LSP application is typically used during development of the LSP application. Changes to LSP pages in a non-deployed application are instantaneously visualized when clicking the refresh button in the browser. The LSP engine automatically recompiles the page if the date stamp has changed -- i.e. if you have modified the page using an editor.

1. Download one of our example LSP applications and save the ZIP file, without uncompressing the content, in a directory which can be accessed via a disk file system or a net file system.
2. In the Application Manager, click the "New Application" folder.
3. Click the "Browse" button and navigate to the directory where you saved the ZIP file.
4. Select the ZIP file.
5. Click the "Submit" button.
6. Select an application name. The name selected will be the base URL for accessing the application, unless you select root application. In other words, the URL to the application is http://server-name/application-name/.
7. Select root application if you want the application to be accessible as http://server-name/.
8. Click the Submit button.
9. The application manager automatically navigates to the "Application-List" folder.
10. Click the start radio button to start the application.
11. The started application shows up as a link in the "Active LSP Applications" list.
12. Click the application link to navigate to your new application.

Loading your own non-deployed LSP application is similar to loading a deployed ZIP application. Follow the steps above, but select a directory (4) instead of selecting a ZIP file. The directory selected should, at a minimum, have an index.html or index.lsp page. The index page is executed when you navigate to http://server-name/your-application-name/.

The .config and .preload scripts

The .config script is run when the C code initializes the Lua Virtual Machine. The .config script is run only one time at system startup. You do not have access to the .config script in the Application Manager, unless you replace the Application Manager's LSP application or modify the code. The Application Manager's LSP files can be found in the lsp subdirectory. A new Application Manager executable must be built if you modify this code.

The .preload script is the LSP application's version of the .config script. The .preload script is executed by the LSP Application Manager when the LSP application is started. The optional .preload application script can, for example, be used to configure a database for the application or configure the Virtual File System for the application when the application starts. Many of the LSP applications we provide contain a .preload script for initializing the application.

The Lua environment where the .preload script executes is made available as the "app" table in LSP pages. This means that a global variable such as myConfigData created by the .preload script can later be accessed in a LSP page as app.myConfigData.

The .preload script is useful if you design a device with an application similar to the LSP application manager -- i.e. if you design an application for loading multiple LSP applications. The .preload script is not managed by the Barracuda Application Server, but by the LSP Application Manager.

The following code fragment from lsp/.config shows how the LSP application manager loads and executes the .preload script. You must have a good understanding of Lua environments in order to understand this code.

-- Create a resource reader by using the provided
-- application name and I/O
local resrdr=ba.create.resrdr(
   not rootapp and app.name or nil,app.prio,io)
if resrdr then
   -- Directory must be inserted before ".preload" to make
   -- dir:baseuri work properly when .preload is run.
   if rootapp then
      resrdr:insert()
   else
      lspappmgr.dirs.rootDir:insert(resrdr)
   end
   local ok=true
   local appenv
   if io:stat".preload" then
      local f
      -- The application's "app" environment table
      appenv=setmetatable({io=io,dir=resrdr},{__index=_G})
      appenv.app = appenv
      -- Load the application's preload script
      f,err = io:loadfile(".preload",appenv)
      if f then
         -- Execute the application's preload script
         ok, err = xpcall(f,errh)
         if ok then err=nil end
      end
   else
      print(fmt("Info: %s/.preload not found",path))
   end
   if not err then
      -- Enable LSP in the resource reader
      resrdr:lspfilter(appenv)
      lspappmgr.apps[app.name]=resrdr
      app.running=true
      return true
   end
   resrdr:unlink()
   if not err then
      err= ".preload failed"
   end
else
   err="Cannot create resrdr"
end