Chapter 38
Process and Shell Support

[p]This chapter describes the [code][OS_Process][/code] type which allows Lasso to execute local processes or shell commands. [/p]

• Overview describes the methodology of executing local processes and shell commands.
• Installation describes how to install the [code][OS_Process][/code] type module.
• Security describes how to configure Lasso security so users can access the [code][OS_Process][/code] type.
• OS Process Type describes the member tags of the [code][OS_Process][/code] type and provides examples of how to use the tag on Mac OS X and Linux, how to use the tag on Windows, and how to create a custom tag which uses the [code][OS_Process][/code] type to provide specific functionality to users without opening up full use of the type to them.

Overview

[p]Lasso provides the ability to execute local processes through the [OS_Process] type. This type allows local processes to be launched with an array of parameters and shell variables. Some processes will execute and return a result immediately. Other processes can be left open for interactive read/write operations. The [code][OS_Process][/code] type enables Lasso users to do things such as execute AppleScripts, print PDF files, and to filter data through external applications. [/p]

[p]The [code][OS_Process][/code] type works across all three platforms which Lasso supports. The UNIX underpinnings of Mac OS X and Linux mean that those two operating systems can run much the same commands and shell scripts. Windows presents a very different environment including DOS commands and batch files. [/p]

[p]The [code][OS_Process][/code] type is implemented in a separate module which is not installed by default. Allowing access to the [code][OS_Process][/code] type has security implications since it can be used to essentially bypass some of Lasso’s built-in security controls. See the Installation section below for information about installing and allowing access to the type. [/p]

Installation

[p]The [code][OS_Process][/code] type is implemented as an external module. The module is located within the [code]Extensions/OS_Process[/code] folder in the Lasso Professional 8 application folder. If the module is installed into the global [code]LassoModules[/code] folder then it will be accessible to all sites hosted by Lasso. Alternately, the module can be installed into the [code]LassoModules[/code] folder for a specific site in order to make this functionality available only to that site. [/p]

[p]The module will have one of these three names depending on which platform is being used. [/p]

[pre]Mac OS X OS_Process.dylib
Red Hat Linux OS_Process.so
Windows OS_Process.dll [/pre]

To install the OS Process module for all sites on a server:

[p]Open the Lasso Professional 8 application folder. Copy the module from the [code]Extensions/OS_Process[/code] folder into the global [code]LassoModules[/code] folder . Restart Lasso Service and follow the instructions in the Security section below to enable individual users to use the module. [/p]

To install the OS Process module for one site on a server:

[p]Open the Lasso Professional 8 application folder. Copy the module from the [code]Extensions/OS_Process[/code] folder into the site-specific [code]LassoModules[/code] folder. For example, the module can be enabled for use in the default site by copying it into the [code]LassoSites/default-1/LassoModules[/code] folder. Restart the site and follow the instructions in the Security section below to enable individual users to use the module. [/p]

Security

[p]A group [code]OS Process Users[/code] is automatically created when the OS Process module is installed. Only users within this group or the site administrator will be allowed to use the [code][OS_Process][/code] type. Since the ability to execute the [code][OS_Process][/code] type can bypass some of Lasso’s built-in security controls, the users who are added to this group should be carefully controlled. [/p]

[p]The following security considerations should be taken into account when granting users permission to use the [code][OS_Process][/code] type by adding them to the [code]OS Process Users[/code] group: [/p]

• The user will be able to access any files which the OS user executing Lasso Service can access. This may include files in other Web sites, files within the Lasso Professional 8 application folder, and other gloally accessible files throughout the local file system.
• The user will be able to directly access MySQL or other data sources on the machine. The user will need a valid username and password to access these data sources through command line tools, but may be able to bypass particular security settings established within Lasso.
• The user will be able to use many local commands such as telnet, curl, ssh, etc. to access other machines through various Internet protocols. These commands may be used to bypass restrictions on the [code][Net][/code] type built-in to Lasso.
• The example at the end of this chapter shows how the [code][OS_Process][/code] type can be wrapped in a protected tag allowing only a single local process or command to be executed without giving completer permission to access the [code][OS_Process][/code] command directly.

To add a user to the OS Process Users group:

[p]Open Lasso Site Administration and visit the Setup > Security > Users section. Select the user which should be allowed to access the [code][OS_Process][/code] type. Select [code]OS Process Group[/code] from the list of groups and select [code]Update[/code] to add the user to that group. [/p]

[note][b]Note: [/b]If the [code]OS Process Group[/code] does not appear in the list of groups then the OS Process module has not been installed properly. Follow the steps in the Installation section above to install the OS Process module. Make sure the Lasso Service and/or the current site has been restarted. [/note]

To use the [OS_Process] type with a specific user’s permissions:

[p]An [code][Inline] … [/Inline][/code] can be used to execute the [code][OS_Process][/code] type using the permissions of a specific user. the following code executes the [code][OS_Process][/code] type using the permissions of the user [code]JohnDoe[/code] with the specified password. [/p]

<?LassoScript
Inline: -Username='johndoe', -Password='mysecretpassword';
Var: 'os' = (OS_Process: '/bin/echo', (Array: 'Hello World!'));
Encode_HTML: $os->Read;
$os->Close;
/Inline;
?>

[pre] Hello World! [/pre]

[p]Alternately, an [code][Auth][/code] or [code][Auth_Admin][/code] tag can be used to prompt the site visitor for a username and password. This will cause all of the LassoScript code on the page to execute with the permissions of the specified username. One of these techniques should be applied to all of the code in this chapter, although for brevity the authentication code is not included in the individual examples. [/p]

OS Process Type

[p]The [code][OS_Process][/code] type allows a developer to create a new process on the machine and both read from and write data to it. The process is usually closed after the [code][OS_Process][/code] type is destroyed, but can optionally be left running. The [code][OS_Process][/code] type shares many of the same member tags and conventions as the file type. The following members are supported: [/p]

Table 1: OS Process Type

[table][tr][th]Tag[/th][th]Description[/th][th] [/th][/tr]

[tr][td][OS_Process][/td][td]Crates a new [OS_Process] instance. [/td][/tr]

[tr][td][OS_Process->Open][/td][td]Opens a new process. The command string should consist of any path information required to find the process and the process name. An optional arguments array can be given. Any arguments are converted to strings and passed to the new process. An optional array of environment strings may be passed in. Both of these optional arrays will be passed to the new process. The command string should be identical to what would need to be typed on the command line with the Lasso site folder as the current working directory. [/td][/tr]

[tr][td][OS_Process-->Read][/td][td]Reads the specified number of bytes from the process. Returns a bytes object. The number of bytes of data actually returned from this tag may be less than the specified number, depending on the number of bytes that are actually available to read. Calling ->Read without a byte count will read all bytes as they become available until the peer process terminates. [/td][/tr]

[tr][td][OS_Process-->ReadError][/td][td]Reads the specified number of bytes from standard error output for the process. Returns a bytes object. Calling ->ReadError without a byte count will read all bytes as they become available until the peer process terminates. [/td][/tr]

[tr][td][OS_Process-->ReadLine][/td][td]Reads data up until a carriage return or line feed. Returns a string object created by utilizing the current encoding set for the instance. [/td][/tr]

[tr][td][OS_Process-->ReadString][/td][td]Reads the specified number of bytes from the process. Returns a string object created by utilizing the current encoding set for the instance. Calling ->readString without a byte count will read all bytes as they become available until the peer process terminates. [/td][/tr]

[tr][td][OS_Process-->Write][/td][td]Writes the data to the process. If the data is a string, the current encoding is used to convert the data before being written. If the data is a bytes object, the data is sent unaltered. [/td][/tr]

[tr][td][OS_Process-->SetEncoding][/td][td]Sets the encoding for the instance. The encoding controls how string data is written via ->write and how string data is returned via ->readString [/td][/tr]

[tr][td][OS_Process-->IsOpen][/td][td]Returns true as long as the process is running. If the process was terminated, ->isOpen will return false. [/td][/tr]

[tr][td][OS_Process-->Detach][/td][td]Detaches the os_process object from the process. This will prevent the process from terminating when the os_process object is destroyed. [/td][/tr]

[tr][td][OS_Process-->Close][/td][td]Closes the connection to the process. This will cause the process to terminate unless it has previously been detached from the os_process object. [/td][/tr]

[tr][td][OS_Process->CloseWrite][/td][td]Closes the "write" portion of the connection to the process. This results in the process' standard input file being closed. [/td][/tr]

[/table]

Mac OS X and Linux Examples

[p]This section includes several examples of using [code][OS_Process][/code] on Mac OS X. Except for the AppleScript example, all of these examples should also work on Linux machines. See the Installation section above for details about how to install the OS Process module and the Security section for details about how to execute the [code][OS_Process][/code] type using the permissions of a specific user or the site administrator. [/p]

• [def]Echo[/def] – This example uses the [code]/bin/echo[/code] command to simply echo the input back to Lasso.

<?LassoScript
Var: 'os' = (OS_Process: '/bin/echo', (Array: 'Hello World!'));
Encode_HTML: $os->Read;
$os->Close;
?>

[pre] Hello World! [/pre]

• [def]List[/def] – This example uses the [code]/bin/ls[/code] command to list the contents of a directory.

<?LassoScript
Var: 'os' = (OS_Process: '/bin/ls', (Array: '.'));
Encode_Break: $os->Read;
$os->Close;
?>

[pre] JDBCDrivers
JavaLibraries
LassoAdmin
LassoApps
LassoErrors.txt
LassoLibraries
LassoModules
LassoStartup
SQLiteDBs [/pre]

• [def]Create File[/def] – This example uses the [code]/usr/bin/tee[/code] command to create a file [code]test.txt[/code] in the site folder. The LassoScript does not generate any output except for the file.

<?LassoScript
Var: 'os' = (OS_Process: '/usr/bin/tee', (Array: './test.txt'));
$os->(Write: 'This is a testn');
$os->(Write: 'This is a testn');
$os->Close;
?>

• [def]Print[/def] – This example uses the [code]/usr/bin/lpr[/code] command to print some text on the default printer. The result in this case is a page that contains the phrase [code]This is a test[/code] at the top. This style of printing can be used to output text data using the default font for the printer. The [code]lpr[/code] command can also be used with some common file formats such as PDF files.

<?LassoScript
Var: 'os' = (OS_Process: '/usr/bin/lpr');
$os->(Write: 'This is a test');
$os->(Write: Bytes->(Import8Bits: 4) & );
$os->CloseWrite;
$os->Close;
?>

• [def]AppleScript[/def] – This example uses the [code]/[/code]usr/bin/osascript' command to run a simple AppleScript. AppleScript is a full programming language which provides access to the system and running applications in Mac OS X. The script shown simply returns the current date and time.

<?LassoScript
Var: 'os' = (OS_Process: '/usr/bin/osascript', (Array: '-'));
$os->(Write: 'return current date');
$os->CloseWrite;
Encode_HTML: $os->Read;
$os->Close;
?>

[pre] Tuesday, March 21, 2006 11:52:34 AM [/pre]

• [def]Web Request[/def] – This example uses the [code]/usr/bin/curl[/code] command to fetch a Web page and return the results. [code][Include_URL][/code] can be used for the same purpose, but the [def]curl[/def] command provides some options which aren’t available directly from within Lasso. Only the first part of the outpu is shown.

<?LassoScript
Var: 'os' = (OS_Process: '/usr/bin/curl', (Array: 'http://www.apple.com/'));
Encode_HTML: $os->Read;
$os->Close;
?>

[pre] <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Apple</title>
… [/pre]

Windows Examples

[p]This section includes several examples of using [code][OS_Process][/code] on Windows. Each of the examples uses the command-line processor [code]CMD[/code] with the option [code]/C[/code] to interpret an individual command. See the Installation section above for details about how to install the OS Process module and the Security section for details about how to execute the [code][OS_Process][/code] type using the permissions of a specific user or the site administrator. [/p]

• [def]Echo[/def] – This example uses the [code]CMD[/code] processor with an [code]ECHO[/code] command to simply echo the input back to Lasso.

<?LassoScript
Var: 'os' = (OS_Process: 'cmd', (Array: '/c ECHO Hello World!'));
Encode_HTML: $os->Read;
$os->Close;
?>

[pre] Hello World! [/pre]

• [def]List[/def] – This example uses the [code]CMD[/code] processor with a [code]DIR[/code] command to list the contents of a directory. The [code]/B[/code] option instructs Windows to only list the contents of the directory without extraneous header and footer information.

<?LassoScript
Var: 'os' = (OS_Process: 'cmd', (Array: '/C DIR /B .'));
Encode_HTML: $os->Read;
$os->Close;
?>

[pre] JDBCDrivers
JavaLibraries
LassoAdmin
LassoApps
LassoErrors.txt
LassoLibraries
LassoModules
LassoStartup
SQLiteDBs [/pre]

• [def]Help[/def] – This example uses the [code]CMD[/code] processor with a [code]HELP[/code] command to show the help information for a command. The start of the help file for [code]CMD[/code] itself is shown. Running [code]HELP[/code] without a parameter will return a list of all the built-in commands which the command processor supports.

<?LassoScript
Var: 'os' = (OS_Process: 'cmd', (Array: '/C HELP cmd'));
Encode_HTML: $os->Read;
$os->Close;
?>

[pre]S Starts a new instance of the Windows XP command interpreter
CMD [/A | /U] [/Q] [/D] [/E:ON | /E:OFF] [/F:ON | /F:OFF] [/V:ON | /V:OFF] [[/S] [/C | /K] string]
/C Carries out the command specified by string and then terminates
/K Carries out the command specified by string but remains
/Q Turns echo off
/A Causes the output of internal commands to a pipe or file to be ANSI
/U Causes the output of internal commands to a pipe or file to be Unicode
… [/pre]

• [def]Multiple Commands[/def] – This example uses the [code]CMD[/code] processor interactively to run several commands. The processor is started with a parameter of [code]/Q[/code] which suppresses the echoing of commands back to the output. The result is exactly the same as what would be provided if these commands were entered directly into the command line shell. In order to process the results it would be necessary to strip off the header and the directory prefix from each line.

<?LassoScript
Var: 'os' = (OS_Process: 'cmd', (Array: '/Q');
$os->(Write: 'ECHO Line Onern');
$os->(Write: 'ECHO Line Tworn');
Encode_HTML: $os->Read;
$os->Close;
?>

[pre] Microsoft Windows XP [Version 5.1.2600]
(C) Copyright 1985-2001 Microsoft Corp.
C:Program FilesOmniPilot SoftwareLasso Professional 8LassoSitesdefault-1>Line One
C:Program FilesOmniPilot SoftwareLasso Professional 8LassoSitesdefault-1>Line Two [/pre]

• [def]Batch File[/def] – This example uses the [code]CMD[/code] processor to process a batch file. The contents of batch file [code]batch.bat[/code] is shown below. The file is assumed to be located in the folder for the current site in the Lasso Professional 8 application folder.

[pre]@ECHO OFF
CLS
ECHO This file demonstrates how to use a batch file. [/pre]

• The batch file is executed by simply calling its name as a command. The results of the batch file are then output. Using a batch file makes executing a sequence of commands easy since all the code can be perfected using local testing before it is run through Lasso.

<?LassoScript
Var: 'os' = (OS_Process: 'cmd', (Array: '/C batch.bat');
Encode_HTML: $os->Read;
$os->Close;
?>

[pre] This file demonstrates how to use a batch file. [/pre]

Security Example

[p]This example shows how a custom tag can be used to provide access to a specific local process without opening up access to general use of the [code][OS_Process][/code] type. This technique can be used by ISPs or other shared hosting providers in order to allow specific Lasso users to perform platform-specific tasks without opening up security holes on the shared server. [/p]

[p]First, the OS Process module must be installed according to the Installation instructions above. Create a user which will have permission to execute [code][OS_Process][/code] commands according to the instructions in the Security section above. This user will only be used to authenticate the [code][OS_Process][/code] type. Its password should not be given out to any shared hosting users. For example, the user [code]OSProcessUser[/code] could be created with the password [code]mysecretpassword[/code]. [/p]

[p]A privileged custom tag to print some data can now be created as follows. An [code][Inline] … [/Inline][/code] is used to authenticate as the user who has permissions to access [code][OS_Process][/code]. A custom tag is created with the -Privileged keyword so that it hangs onto the permissions of that user. The [code][OS_Process][/code] type is used within to issue an [code]lpr[/code] command. [/p]

<?LassoScript
Inline: -Username='OSProcessUser', -Password='mysecretpassword';
Define_Tag: 'Local_Print', -Required='Data', -Privileged;
Var: 'os' = (OS_Process: '/usr/bin/lpr');
$os->(Write: #data);
$os->(Write: bytes->(import8bits: 4) & );
$os->Closewrite;
$os->Close;
/Define_Tag;
/Inline;
?>

[p]The code above is placed in a file in [code]LassoStartup[/code] so that the defined tag is available to the users of the Lasso site, but the actual code of the tag is not (including the secret password for the [code]OSProcessUser[/code] account). Now, any user of the machine can use the [code][Local_Print][/code] tag to print a file on the local printer even though they do not have explicit access to the [code][OS_Process][/code] tag itself. [/p]

[pre][Local_Print: (Include_Raw: 'mypdf.pdf')] [/pre]

[p]More information about permissions can be found in the Lasso Setup Guide and more information about privileged custom tags can be found in the Custom Tags chapter in this guilde.[/p]