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
.
: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 to true
.
: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
or reset
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.
- 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.
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:
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:
- An option without a
:map
is passed directly through to the command:
- Image name that doesn't pass validation is ignored:
- Invalid options and values are ignored:
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.
Contact
binford2k@gmail.com