DCL in a box

Version 1.0.1, 28th April 2012

Copyright © 2011,2012 Mark G. Daniel
This program, comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under the
conditions of the GNU GENERAL PUBLIC LICENSE, version 3, or any later version.
http://www.gnu.org/licenses/gpl.txt

Contents




DCL in a box  provides an in-browser VT102 terminal emulation via a WASD WebSocket scripting application connected to LOGINOUT using the pseudo-terminal API. WebSocket makes the terminal input/output stream interface particularly straight-forward and allows a session logged-in via the Web to be maintained fairly simply.

Although at the time of first DCLinabox release (January 2012) the WebSocket Protocol had just been published (http://www.rfc-editor.org/rfc/rfc6455.txt) and mainstream browser support was fairly limited, the asynchronous, bidirectional data stream available using WebSocket will quickly make it an invaluable Web service building block with broad mainstream support. This version of DCLinabox has been developed using mainstream releases, Chrome 18.0 and Firefox 12.0.

Does this browser support WebSockets?   NO! 

DCLinabox is based on a JavaScript VT102 emulator from the ShellInABox project.

For all things VT ... vt100.net

Shell In A Box

Is a Free and Open Source project by Markus Gutschke <markus@shellinabox.com>.

http://code.google.com/p/shellinabox/
"Shell In A Box implements a web server that can export arbitrary command line tools to a web based terminal emulator. This emulator is accessible to any JavaScript and CSS enabled web browser and does not require any additional browser plugins. Most typically, login shells would be exported this way."

DCLinabox exports the DCL command-line in a similar way.

Installation

By default all the required JavaScript, CSS and graphics are located in the WASD runtime directory WASD_ROOT:[RUNTIME.DCLINABOX] 

Configuration

DCLinabox allows remote login from a Web browser to the server system. This could be a security issue and so the script disables itself by default. Logical name value DCLINABOX_ENABLE controls whether the application can be used. Define this system-wide using a value of "*" to simply allow experimentation. Alternatively provide one or more comma-separated, dotted-decimal IP address to specify one or more hosts allowed to use the script, and/or one or more comma-separated IP addresses and CIDR subnet mask to specify a range of hosts. IPv4 only! For example

$ DEFINE /SYSTEM DCLINABOX_ENABLE "*"
$ DEFINE /SYSTEM DCLINABOX_ENABLE "192.168.1.2"
$ DEFINE /SYSTEM DCLINABOX_ENABLE "192.168.1.2,192.168.1.3"
$ DEFINE /SYSTEM DCLINABOX_ENABLE "192.168.1.0/24"
$ DEFINE /SYSTEM DCLINABOX_ENABLE "192.168.1.0/24,192.168.2.2"

By default the WebSocket, and hence all traffic to and from the DCLinabox login and session, is only allowed over Secure Sockets Layer (wss:). This is the case even when the terminal page is accessed via standard (unencrypted) HTTP and implies the system must have a working SSL service. To allow access via unencrypted connections (CAUTION) add ws: somewhere in the logical name value and if the terminal page is accessed using standard HTTP the WebSocket will be established using the same service.

$ DEFINE /SYSTEM DCLINABOX_ENABLE "ws:,*"
$ DEFINE /SYSTEM DCLINABOX_ENABLE "192.168.1.0/24,ws:,192.168.2.2"

The logical name DCLINABOX_IDLE allows the number of minutes before client disconnection to be specified. Define to -1 to to disable idle diconnection.

$ DEFINE /SYSTEM DCLINABOX_IDLE 1440
$ DEFINE /SYSTEM DCLINABOX_IDLE -1

Also see Obfuscation.

Customising

A DCLinabox session has user-selectable characteristics available via a right-click menu.

The DCLinabox terminal emulator infrastructure is designed to allow straight-forward application and site localisation.

DCLinabox operates in one of two modes;

Both the embedded terminal and the terminal launcher are simple to incorporate in a site-local page. The EXAMPLE.HTML page demonstrates both.

The standalone terminal openDCLinabox() function will accept an optional host name (with optional scheme and/or port).

< ... onclick="openDCLinabox('the.host.name')" ... >

Configuration of some elements of DCLinabox behaviour is possible using JavaScript variables.

VariablePurposeValue
DCLinaboxAnother the  ^  button displayed on a standalone terminal can also be made available on an embedded terminal true or false(D)
DCLinaboxConfig specifies a JavaScript file name containing these variables (string) name.JS
DCLinaboxHeight terminal height (number of lines) (integer) 12 to 96 (24(D))
DCLinaboxHost specifies the host to which the terminal connects (string) host name or address
DCLinaboxImmediate a standlone terminal connects immediately but an embedded terminal must CONNECT with this setting overriding this true or false(D)
DCLinaboxMessage allows message text (and hence language) customisation see below
DCLinaboxScriptName allows the DCLinabox script to have a different name see below
DCLinaboxScroll terminal scrollback buffer (integer) zero(D) to disable or number of lines
DCLinaboxSecureAlways always connect to the terminal system via SSL true(D) or false
DCLinaboxStyle specifies a CSS file name containing site specifics (string) name.CSS
DCLinaboxTitle by default a standalone terminal is named "DCLinabox: host" with this providing a local alternative (string) description
DCLinaboxWidth terminal width (integer) 80(D) or 132
DCLinaboxWxH terminal dimensions (width x height) (string) e.g. 80x24, 132x24, 132x48

Common settings can be seen and are available for modification in the file CONFIGINABOX.JS for site-wide configuration, or the JavaScript variable can be assigned using a <script>..</script> element appended to the <head>..<head> section of an embedded terminal page or terminal launcher page to provide page-specific customisation. For example:

<script type="text/javascript">
DCLinaboxSecureAlways = true;
DCLinaboxImmediate = true;
DCLinaboxWidth = 132;
DCLinaboxScroll = 200;
</script>

By default DCLinabox connects to the same host and port used to access the HTML page containing the embedded terminal or launcher button/link. It is possible to have the terminal connect to a different host (which of course must have the /cgiplus-bin/dclinabox application available). This host specification can contain an optional, colon-delimited port number and the variable used to specify just an alternate port number. Add the DCLinaboxHost JavaScript variable to the embedded terminal or launcher page.

<script type="text/javascript">DCLinaboxHost="the.host.name"</script>

Alternatively, a host selection dialog can be generated on the embedded terminal or launcher page.

<span id="selectDCLinaboxHost"><script type="text/javascript">
selectDCLinaboxHost("one.host.name,two.host.name,three.host.name")
</script></span>

Optionally, the host specification can include an equate symbol delimitted description.

<span id="selectDCLinaboxHost"><script type="text/javascript">
selectDCLinaboxHost("one.host.name=FIRST,two.host.name,three.host.name=3rd host name")
</script></span>

DCLinabox supports terminal widths of 80 and 132 characters and page lengths from 12 to 96, defaulting to 80x24. Terminal width and height may be independently set using the appropriate configuration variables or jointly set using DCLinaboxWxH variable (which overrides the individual settings). In common with non-emulated terminals, a SET TERMINAL /INQURE is generally used to inform the terminal driver of these characteristics.

Customised and non English language messages are configurable. Carefully reproduce the default message object found in DCLINABOX.JS using desired equivalents and specify as for other configuration elements. One, some or all may be specified, with absent messages defaulted.

<script type="text/javascript">
DCLinaboxMessage = { NOTSUP : 'WebSocket stöds inte!',
                     CONNEC : 'ANSLUTA',
                     DISCON : 'KOPPLA',
                     DISURE : 'KOPPLA: Är du säker?'
                   };
</script>

The file DCLINABOX.CSS is available for style-sheet customisation of terminal elements (colour, border size and style, font size, etc.) A local style file may be specified using the JavaScript variable DCLinaboxStyle.

Bookmarklet

A Bookmarklet is a snippet of useful JavaScript often stored as the URL of a bookmark/favorite. DCLinabox provides for bookmarklet activation allowing standalone terminals to be activated simply by clicking such a bookmark (or link). The following application allows the essentials of a DCLinabox activation to be entered (with appropriate defaults) and the resulting link be added to the current browser's bookmarks.

Terminal Host Script NameSize
SSL  
 (click, or drag into bookmarks)
 (copy-and-paste as required)

Obfuscation

With a public system it may be necessary to reduce nuisance-value access attempts and/or an attack vector. The obvious approach in a Web-based environment might be to make the DCLinabox script subject to authorisation. This is not possible with WebSockets where there is no RFC-defined authorisation scheme, access-control relies on the underlying WebSocket application - which of course DCLinabox has with the LOGINOUT username/password dialog.

In a somewhat security though obscurity approach (or more like don't make youself an easy target), the DCLINABOX.EXE file may be alternately named. It just means the well-known /cgiplus-bin/dclinabox path will not exist and is akin to changing from the well-known SSH port number to reduce that obvious attack vector. Just use a less-than-obvious (or access-controlled) customised terminal page (or bookmarklet), with a different script executable file name, and add that script name to the <head>..</head> section of the HTML terminal file as with other per-terminal configuration variables.

<script type="text/javascript">DCLinaboxScriptName="anexample"</script>

The script accessed will then be /cgiplus-bin/anexample and the script file name CGI_EXE:ANEXAMPLE.EXE.

The logical names reflect the executable name and so in this case would be ANEXAMPLE_ENABLE, etc.

Problems?

Releases

v1.0.0  22-JAN-2012
initial
v1.0.1  28-APR-2012
•  Firefox (at least 11.0 and 12.0) reports (and presumably has) a different line height (via .clientHeight) for the same font (plus three pixels on Windows and plus one on OS-X and Linux). Add a minor kludge to dclinabox.js to adjust the terminal line height for this.
•  Added DCLinaboxWxH and DCLinaboxHeight configuration variables.

Acknowlegements

Many thanks to Markus Gutschke <markus@shellinabox.com> for the original ShellInABox project and for making it Free and Open Source via the GPL. Furthermore, the vt100.js implementation appears to be particularly rigorous, so thanks again.