abalone
A simple Sinatra & hterm based web terminal.
Table of Contents
- Overview
- Configuration
- SSH
- Custom Login Command
- jQuery plugin
- Limitations
Overview
Simply exposes a login shell to a web browser. This is currently nowhere near to production quality, so don't actually use it.
It supports three methods for providing a shell:
- Simply running the
login
binary and logging in as a system user. (default) - Using SSH to connect to localhost or a remote machine. This can be configured with credentials to automatically connect, or it can request a username and password from the end user.
- Running custom command, which can be configured with arbitrary parameters.
Configuration
Abalone defaults to loading configuration from /etc/abalone/config.yaml
. You
can pass the path to another config file at the command line. In that file, you
can set several options:
-
:autoconnect
- Set this to true if you'd like the session to start on page load and false
if you'd like the user to click a Start Session button instead. Defaults
to
true
.
- Set this to true if you'd like the session to start on page load and false
if you'd like the user to click a Start Session button instead. Defaults
to
-
:port
- Which port to run the server on.
- Default value:
9000
-
:bind
- The hostname or IP address of the interface to listen on.
- Default value:
0.0.0.0
(listen to all interfaces.)
-
:bannerfile
- File to display before login. This does not interpret special characters the way
getty
does. -
true
,false
, or filename to display. - Default value:
false
, or/etc/issue.net
if set totrue
.
- File to display before login. This does not interpret special characters the way
-
:welcome
- A message to display prior to starting a session. This is on the overlay with the Start Session button. Pass a string of text, or a filename. HTML will be interpreted.
- Default value: unset
-
:logfile
- The path of a file to log to.
- Default value: Log only to
STDERR
. If you pass-l
at the command line with no filename, it will log to/var/log/abalone
.
-
:timeout
- Maximum number of seconds a session can last. The shell will be killed at the end of that time. For example, set it to 300 for shells that last for up to five minutes.
- Default value: unset.
-
:ttl
- The number of seconds a session should last after disconnecting. If you reconnect
within this grace period, you'll be reconnected to your session without interruption.
This cannot yet restore the secondary terminal buffer, so if you're running something
like Vim, you may have to run
clear
orreset
after exiting to get your console sane again. - Note that
:timeout
takes precedence, so if your session times out, even during the:ttl
grace period, it will be killed. - Default value: unset.
- The number of seconds a session should last after disconnecting. If you reconnect
within this grace period, you'll be reconnected to your session without interruption.
This cannot yet restore the secondary terminal buffer, so if you're running something
like Vim, you may have to run
- One of
:command
or:ssh
, exclusive.- The login method to use. Abalone can use
login
, SSH, or a custom command to start a shell. See configuration instructions below. - Default value: uses the
login
binary, with no configuration possible.
- The login method to use. Abalone can use
Configuring SSH
The following parameters may be used to configure SSH login. The :host
setting
is required. :user
and :cert
are optional. If :user
is not set, then the
user will be prompted for a login name, and if :cert
is not set then
the user will be prompted to log in with a password. If the SSH server is running
on a non-standard port, you may specify that with the :port
setting.
---
:ssh:
:host: shellserver.example.com
:user: centos
:cert: /etc/abalone/centos.pem
Configuring a custom command
A custom command can be configured in several ways. If you just want to run a command without providing any options, the config file would look like:
---
:command: /usr/local/bin/run-container
Simple options
You can also allow the user to pass in a arbitrary options. These must be whitelisted. You can simply list allowed options in an Array:
---
:command: /usr/local/bin/run-container
:params: [ 'username', 'image' ]
The options will be passed to the command in this way, ignoring the option that was not whitelisted:
- http://localhost:9000/?username=bob&image=testing&invalid=value
/usr/local/bin/run-container --username bob --image testing
Customized options
Finally, you can fully customize the options which may be passed in, including
remapping them to command line arguments and filtering accepted values. In this
case, :params
must be a Hash.
---
:command: /usr/local/bin/run-container
:params:
username:
type:
:values: ['demo', 'testing']
image:
:map: '--create-image'
:values: [ 'ubuntu', 'rhel', /centos[5,6,7]/ ]
Notice that username
has nothing on the right side. It will be treated exactly
the same as username
in the Simple options array above.
The image
parameter is more complex though. It has two keys specified. Both are
optional. If :map
is set, then its value will be used when running the command.
The :values
key can be used to specify a list of valid values. Note that these
can be specified as Strings or regular expressions.
The options in this case will be passed to the command like:
- An option is mapped to a different command line argument:
- http://localhost:9000/?username=bob&image=centos6
/usr/local/bin/run-container --username bob --create-image centos6
- An option without a
:map
is passed directly through to the command:- http://localhost:9000/?username=bob&type=demo
/usr/local/bin/run-container --username bob --type demo
- Image name that doesn't pass validation is ignored:
- http://localhost:9000/?username=bob&image=testing
/usr/local/bin/run-container --username bob
- Invalid options and values are ignored:
- http://localhost:9000/?username=bob&image=testing&invalid=value
/usr/local/bin/run-container --username bob
jQuery Plugin
Abalone comes with a build in jQuery plugin that makes it very easy to use. You
can attach the launcher to any element. If it's a block
element, then a launcher
button will be injected inside, and if it's inline
then it will directly trigger
the terminal.
See a demo of the launcher in action after installation by starting the server and browsing to http://localhost:9000/demo.html. Adjust the URL and port as needed.
The minimum external dependencies are jQuery and jQuery UI:
<link rel="stylesheet" href="https://code.jquery.com/ui/1.12.1/themes/base/jquery-ui.css">
<script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
<script src="https://code.jquery.com/ui/1.12.1/jquery-ui.js"></script>
To load and initialize the launcher, you'll need to load the CSS and Javascript from a running Abalone instance like below. Notice the full URL, including the port number. Alternatively, you can pull those from the repository and host them along with the rest of your HTML.
<link rel="stylesheet" href="http://localhost:9000/css/launcher.css">
<script src="http://localhost:9000/js/launcher.js"></script>
Then you'll simply declare one or more launchers on any element you choose. Note that you must pass in the server parameter. This should be the location of your Abalone server, including the port it's running on.
<script>
$(document).ready(function() {
$('pre.popup').AbaloneLauncher({
label: "Try out a popup!",
title: "Isn't this neat?",
server: "http://localhost:9000",
});
$('pre.inline').AbaloneLauncher({
label: "Try it out inline!",
target: "inline",
server: "http://localhost:9000",
});
$('pre.targeted').AbaloneLauncher({
label: "Try it out!",
target: "#abalone-shell",
location: "se",
server: "http://localhost:9000",
});
$('a#launcher').AbaloneLauncher({
server: "http://localhost:9000",
params: { "type": "demo", "uuid": generateUUID() },
});
});
</script>
Configuration Options
Option | Valid values | Default |
---|---|---|
location |
ne , se , sw , nw
|
ne |
label |
String | Launch |
title |
String | Abalone Web Shell |
target |
popup , inline , tab , CSS selector of a container |
popup |
params |
parameters to be passed to the server | {} |
server |
URL to the Abalone server, including port |
null (required) |
height |
Integer | 480 |
width |
Integer | 640 |
Limitations
This is super early in development and has not yet been battle tested.
Disclaimer
I take no liability for the use of this tool.