DCLinabox

Contents

• ShellInABox
• Installation
• Configuration
• Right-click Menu
• Virtual Keyboard
• Long Line Edit
• Comms Insight
• Login Prompt
• Single Sign-On
• Access Port Name
• Customising
• Bookmarklet
• Obfuscation
• Problems
• Releases
• Acknowlegements

DCLinabox provides an in-browser VT102 terminal emulation (plus more) via a WASD WebSocket scripting application 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.

DCLinabox should work with all relatively modern browsers. Developed against Chrome, Firefox, Edge, and Safari, on macOS, Windows and Linux platforms, it uses HTML5 elements including the WebSocket protocol, and will not work with the HTML4 generation of browsers.

Does this browser support WebSocket?   YES   NO! 

DCLinabox is an adaptation of a JavaScript VT102 emulator from the ShellInABox project.

Operation of DCLinabox should be straight-forward, having simple, obvious controls and VT emulation. An extended (editing and numeric) keyboard is mapped into a logical VT220-style keypad. Some DCLinabox session characteristics may be selected via a right-click menu. Others need to be customised on an installation basis.

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

• Obtain the DCLinabox kit from

  http://wasd.vsm.com.au/wasd/

• Suggest deleting contents of any existing DCLinabox before installing a new version (ensuring a backup is available, just-in-case).

  $ SET DEFAULT WASD_ROOT:[000000]
  $ DELETE [SRC.DCLINABOX...]*.*;*
  $ DELETE [RUNTIME.DCLINABOX...]*.*;*
  

• UNZIP the kit

  $ SET DEFAULT WASD_ROOT:[000000]
  $ UNZIP "-V" location:DCLINABOXnnn.ZIP
  

• Note that this performs a link-only build against the supplied object modules. Compilation is also available (just remove the LINK parameter).

  $ SET DEFAULT WASD_ROOT:[SRC.DCLINABOX]
  $ @BUILD_DCLINABOX LINK
  

• Copy the DCLinabox application to the script executable location.

  $ COPY WASD_EXE:DCLINABOX.EXE CGI_EXE:
  

• Modify the default WASD_CONFIG_MAP configuration file to make runtime mapping include a search=none setting.

  pass /*/-/* /wasd_root/runtime/*/* search=none
  

  Reload the server mapping rules.

  $ HTTPD/DO=MAP
  

• Configure the application.

• Now login using the EXAMPLE.HTML page
  or directly via the executable
  or by opening a bookmarklet

• Edit the system startup to make required logical names, and if required installed image, persistent.
  The example DCLINABOX_STARTUP.COM can assist with this.

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

When Updating

Remember that the more recent JavaScript will need to be (re)loaded into browsers, the executable image reINSTALLed, and that as a WebSocket application will require any currently instantiated processes flushed with $ HTTPD/DO=DCL=DELETE (caution! – peremptorily removes all script processes)

Browsers often can be reluctant to refresh cached JavaScript:

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"

While the LNM$SYSTEM table is used in these examples, logical names may be defined in any table searched by LNM$FILE_DEV, including WASD_TABLE.

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"

An idle session is one not having terminal input for a given period. By default idle sessions are disconnected after two hours with a five minute warning. The logical name DCLINABOX_IDLE allows the number of minutes before client disconnection to be specified, the number of minutes warning (delivered in a browser alert), and the warning message (allowing language customisation). Each of these elements is delimited by a comma.

Define to -1 to to disable idle disconnection.

$ DEFINE /SYSTEM DCLINABOX_IDLE -1

To specify a four hour idle period with ten minute warning and local warning message (which may contain just one "%d" to substitute the minutes warning).

$ DEFINE /SYSTEM DCLINABOX_IDLE "240,10,WARNING - disconnection in %d minutes!"

The logical name DCLINABOX_ALERT results in an announcement being displayed in a browser alert dialog. This alert will be delivered at session establishment if it exists at the time, perhaps as a permanent announcement, otherwise will be alerted within a minute of it first being defined. If an ephemeral announcement it should be undefined when no longer relevant. For example

$ DEFINE /SYSTEM DCLINABOX_ALERT -
"*** DCLinabox restart shortly - PLEASE LOG OFF ***"

By default the terminal title bar displays the DCLinabox host name, VMS node name and username. To display the process name in addition (periodically updated if changes) the executable image needs to be installed with WORLD privilege. System startup requires

$ INSTALL ADD CGI-BIN:[000000]DCLINABOX.EXE /AUTH=(WORLD)

and on executable image update

$ INSTALL REPLACE CGI-BIN:[000000]DCLINABOX.EXE

In addition to privileges required for other behaviours, the ACCPORNAM capability requires a small segment of code to be exceuted in kernel mode. The presence of CMKRNL enables the TT_ACCPORNAM code.

$ INSTALL ADD CGI-BIN:[000000]DCLINABOX.EXE /AUTH=(CMKRNL)

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.

Also see Obfuscation.

Right-click Menu

Right-click on the terminal "screen" displays a pop-up menu with the following items. Those with a ✓ symbol beside are active when the symbol is displayed and inactive when not. Other items behave as described.

Virtual Keyboard

The session status bar contains  VKB   which when checked opens a virtual keyboard.

It is reminiscent of the family of LK keyboards. All of the expected and commonly used keys are present and generate characters and sequences based on the VT220 Programmers Guide.

The Shift, Ctrl and Alt keys on the left are one-shot applied to the next keystroke. The …Shift, …Ctrl, …Alt, and also …Caps, remain locked and are applied to all subsequent keystrokes. These keys are toggled on and off.

A keyboard detached from the terminal may be created by pressing the  ↖   key, and that may be raised to the top (found again) by re-pressing.

Note 1: When clicked, the "VKB" label on  VKB   directly performs the same functions as  ↖ .

Note 2: Some browser controls on "popup" windows may need to be relaxed to use the detached virtual keyboard.

Note 3: Request customisation allows for the inline keyboard to be open using VKB=true, and for the detached keyboard using VKB^=true.

The adjacent  ⧉   key allows a single virtual keyboard keypress then returning focus to the terminal session for further physical keyboard input. The parent terminal session may be brought to focus by pressing this key twice.

Long Line Edit

A common gripe with the VMS terminal driver is the inability to line-edit behind the current line. DCLinabox provides a kludge to assist with composing particularly long lines to insert into the terminal session.

The session status bar contains  LLE   which when checked opens an adjacent text edit section. Input may be composed directly in this, text may be copied into it, subsequently edited, and when ready, Send to the terminal session. Content remains if the box is subsequently unchecked and so may be revisited later in the session. The Strip button removes all carriage-control from the LLE content and so may be used to excise pasted output line limits.

While intended for composing longer single lines, the LLE may also be used to compose a series of return/Enter delimited lines, which can then be sent as a batch of commands.

As well as the action buttons, the LLE checkbox also reveals other checkboxes described in the Comms Insight section.

Comms Insight

It can sometimes be useful to observe the data flowing between terminal and system. Each octet is displayed as a two digit hexadecimal number. The client can control this through checkboxes displayed when the Long Line Edit facility is open. These are  TX RX  with the TX displaying terminal input transmitted to the system (each record preceded by a '|' – horizontal bar), and the RX displaying characters received from the system (records preceded by a '!' – bang).

The first TX checkbox displays the hex without transmitting to the system. If the second checkbox is also enabled it is additionally sent to the system. If only the second checkbox, then it is recorded in the browser console log as well as sent to the system.

The first RX checkbox displays the hex without sending to the terminal. If the second checkbox is also enabled the output is additionally sent to the terminal. If only the second checkbox, the data is displayed in the console log as well as sent to the terminal.

With both TX and RX enabled, entering the command SHOW TIME would display

|x53!x53|x48!x48|x4F!x4F|x57!x57|x54!x54|x49!x49|x4D!x4D|x45!x45|x0D!x0Dx0A!x0Dx5Fx57x68x61x74x3Ax20

Login Prompt

The right-click user option Login Prompt enables username and password fields associated with the CONNECT dialogue.

These inputs are commonly recognised by browsers' password management capabilities and may be used to supply login credentials to the VMS system. The username and password are delivered via the same (SSL encrypted) data stream as they would if keyed into the VT emulation and therefore are as fundamentally secure as any other password management by the browser. Once supplied to the VMS system the credentials are not kept further by DCLinabox.

Leave disabled if uncomfortable with browser credential management and the VMS system will prompt for username and password as usual. Enter data into the fields and browser should prompt to save them and then pre-fill the fields when again using DCLinabox against that system's URL. While the various browsers handle this capability in different ways and with varying transparency, use of the Login Prompt can offer a little convenience and save a little time with an accomodating platform.

Single Sign-On

By default, DCLinabox terminal sessions prompt for a username and password. For sites where WASD SYSUAF authentication is available, or where the authenticated remote user string is the equivalent of a VMS username, DCLinabox can use that browser-authenticated VMS username to establish a terminal session without further credential input (i.e. the terminal just displays the DCL prompt, ready to go).

This is obviously very powerful and should only be used with DUE CAUTION!

Note that the browser must support the authentication being used for its WebSocket capability as well as for general web access. For example, at the time of writing (July 2013) only Firefox 22.0 supports the standard HTTP BASIC authentication mechanism (username and password) for WebSocket, and Chrome 28.0, MSIE 10.0, Opera 12.16 and Safari 6.0 do not.

It is possible to selectively apply SSO authentication dependent on the browser in use. This allows suitable browsers to SSO while not disabling others from using DCLinabox via the logon prompt. For example the following applies it only to browsers with firefox or whatever in the agent identification.

["VMS credentials"=WASD_VMS_RW=id]
if (websocket:)
   if (user-agent:*firefox* || user-agent:*whatever*)
      /*dclinabox* r+w,https:
   endif
endif

The SSO functionality is enabled using the DCLINABOX_SSO logical name.

This logical name is multi-valued, allowing considerable granularity in establishing allowed use of the facility. Each value begins with the name of the realm associated with authentication of the VMS username. This is separated by an equate symbol and zero or more comma-separated usernames allowed to single sign-on and/or trailing wildcard. Preceding a username with a '!' (exclamation point) specifically disallows the matching username from SSO. All string matches are case-insensitive.

Account restrictions (e.g. times) are not evaluated. If a specific username matches it is permitted regardless of the account privileges. If a '**' (double asterisk) is specified any username is permitted regardless of the account privileges. If a '*' (single asterisk) is specified any non-privileged account is permitted to SSO. If '!*' (exclamation point then asterisk) is specified DCLinabox cannot be used except if permitted by SSO.

For example, the following authentication rule

["VMS credentials"=WASD_VMS_RW=id]
if (websocket:) /*dclinabox* r+w,https:

would require the logical name defintion

$ DEFINE /SYSTEM DCLINABOX_SSO "WASD_VMS_RW=*"

to allow any such non-privileged authenticated user to create a logged-in terminal session, while the logical name definition

$ DEFINE /SYSTEM DCLINABOX_SSO "WASD_VMS_RW=REN,STIMPY"

would allow only users REN and STIMPY to do so. The logical name definition

$ DEFINE /SYSTEM DCLINABOX_SSO "WASD_VMS_RW=**"

would allow any account (privileged or non-privileged) to SSO, and

$ DEFINE /SYSTEM DCLINABOX_SSO "WASD_VMS_RW=REN,!STIMPY,*"

allows (perhaps privileged) REN but not STIMPY, and then any other non-privileged account.

If a matching authentication realm is not present, or a matching username in a matched realm is not found, or a disabling account status, then single sign-on does not occur and the terminal session just prompts for credentials as usual. Of course, even if the logical name does not allow SSO, the access to DCLinabox is still controlled by the web server authentication and authorisation.

The logical name DCLINABOX_ANNOUNCE allows an SSO session establishment announcement to be displayed in the terminal window. This multi-valued logical name appends carriage-control to each value displaying it as separate line.

$ DEFINE /SYSTEM DCLINABOX_ANNOUNCE "***** WARNING *****"," ","AUTHORISED USE ONLY!"

Single sign-on requires the executable image to be installed with privileges to allow UAI and persona services to be used. System startup requires

$ INSTALL ADD CGI-BIN:[000000]DCLINABOX.EXE /AUTH=(DETACH,SYSPRV,WORLD)

(WORLD only for terminal title management) and on executable image update

$ INSTALL REPLACE CGI-BIN:[000000]DCLINABOX.EXE

Access Port Name

If configured (by the site) the access remote port is available in the terminal session.

$ show terminal
Terminal: _FTA60:     Device_Type: VT102         Owner: _FTA60:
                                              Username: SYSTEM
Remote Port Info: inabox/192.168.1.254:58768
  8< snip 8<
$ write sys$output f$getdvi("tt","tt_accpornam")
inabox/192.168.1.254:58768

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;

• terminal embedded in an HTML page
• standalone terminal window

• embedded:  <iframe src="/dclinabox/-/dclinabox.html"></iframe>
• standalone:  < ... onclick="openDCLinabox()" ... >

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

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

and optional request configuration directives (see below).

< ... onclick="openDCLinabox('the.host.name','WxH=132x24')" ... >

Configuration of some elements of DCLinabox behaviour is possible using the following (JavaScript) variables.

Embedded JavaScript

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;
DCLinaboxSecureAlways = false;
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).

Request Customisation

In addition to customisation using JavaScript variables, the same directives can be supplied with the request, in URI query syntax, interchangeably as a fragment identifier or query string. Using this mechanism the directive name is the same as the JavaScript variable without the leading "DCLinabox", so directive DCLinaboxFontSize becomes FontSizein the request. Case must be maintained.

The following example opens an embedded terminal with a font size of 20 pixels, 48 lines of 132 characters, with immediate login prompt.

<iframe src="/dclinabox/-/dclinabox.html#FontSize=20&WxH=132x48&Immediate=true"></iframe> 

This example uses the executable to initiate the same session supplying the directives as a query string.

<iframe src="/cgiplus-bin/dclinabox?FontSize=20&WxH=132x48&Immediate=true"></iframe> 

And the same again with a detached virtual keyboard.

<iframe src="/cgiplus-bin/dclinabox?FontSize=20&WxH=132x48&Immediate=true&VKB^=true"></iframe> 

Message Customisation

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>

Style Customisation

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. Request configuration can be further tailored using the Other field or by editing the bookmark JavaScript.

Bookmarklet code also can be used directly as a click-event or anchor link.

<tag onclick="javascript:void(window.open('...','_blank','status=0,...'))" tag>
<a href="javascript:void(window.open('...','_blank','status=0,...'))">standalone</a>

Obfuscation

With a public system it may be necessary to reduce nuisance-value access attempts and/or an attack vector with the executable having an alternate name. 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?

• With the DCLinabox kit ... Mark.Daniel@wasd.vsm.com.au
• The info-WASD mailing list

Releases

v1.7.1  03-JUL-2021

• Tweak to script process nomenclature.
• Added DCLinaboxVisualBell
• bugfix; VT100.js space(s) input when display attributes active
• bugfix; dclinabox.js DCLinaboxTheme

v1.7.0  29-MAR-2021

• LK-ish virtual keyboard available via the VKB  checkbox.
• If configured (by the site) the terminal session has the access remote port data set.

v1.6.0  06-OCT-2020

• Allow F1..F12 on PC-style keyboards, and option-F1..F12 with option-F16..F19 on a Mac-style extended keyboad, to be available as VT220-style function keys.
• Terminal driver line-editing annoyances can be somewhat worked around using the Long Line Edit facility.
• Associated DCLinaboxLLE configuration variable.
• Communications data, terminal-to-system and system-to-terminal, may be observed using the Comms Insight facility.

v1.5.0  19-NOV-2016

• An editing and numeric keypad can now be mapped into a VMS- (VT220-) functional layout.
• Browser management of username/password credentials may now be leveraged using the corresponding Login Prompt option.
• Added DCLinaboxVMSkeysMac, DCLinaboxVMSkeysPC and DCLinaboxScreen configuration variables.
• Further VT100.js refinements and fixes.

v1.4.0  18-JUL-2016

• Refine and refactor VT100.js  (DCLinabox is now more of a fork of the ShellInABox JavaScript code.)
• Simplify themes to dark-on-light, light-on-dark, and green-screen.
• Support DECSWL, DECDWL and DECDHL line height/width functions.
• Support DECELR, DECSLE and DECRQLP locator (mouse) functions.
• Support DECLL0 thru DECLL4 LED functions.
• Added DCLinaboxLEDs and DCLinaboxTheme and configuration variables.
• Paste portal has been removed in favour of right-click menu options.
• In an effort to make updates transparent and reliable, JavaScript and Style Sheet resources (.js and .css) now have a query string appended, encouraging browsers to perform an implicit and transparent refresh when the version identifier changes.
  This requires a modification to mapping .

v1.3.0  05-APR-2015

• Allow a terminal to be initiated by the executable.
• Allow for use within the WASD acme environment.
• Allow configuration by query string or fragment identifier.
• Improve flexibility of openinabox.js JavaScript.
• Refine terminal width and character sizing.
• Added DCLinaboxFontSize and DCLinaboxMinimise configuration variables.
• Splash page for identification and improved up-front issue visibility.

v1.2.1  20-DEC-2013

• bugfix; VT100.js for Firefox [-_] keycode

v1.2.0  20-JUL-2013

• Paste portal.
• XON/XOFF flow control.
• Audible bell right-click menu select and MP3 implementation.
• wsLIB refinements.

v1.1.0  01-OCT-2012

• Session alert.
• Dynamic terminal resize.
• Refine idle session management.
• Standlone terminal title includes logon detail.
• Refine process termination detection and signalling.
• Single sign-on (no [additional] password required).
• Added DCLinaboxResizeEmbedded and DCLinaboxResizeOptions configuration variables.

v1.0.2  21-JUL-2012

• wsLIB shut and destroy refinements.
• Added DCLinaboxLogoutClose configuration variable.
• Tested against MSIE 10.0 (Windows 8 Developer Preview) and Safari 6.0 (Developer Preview).

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.

v1.0.0  22-JAN-2012

• initial

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.

Thanks to Thomas E. Dickey (and predecessor, Per Lindberg) for the Vttest VTnnn conformance program. An invaluable aid in further development of the VT100.js component of DCLinabox. http://invisible-island.net/vttest/vttest.html