shellinaboxd - Online in the Cloud

PROGRAM:

NAME

shellinaboxd - publish command line shell through AJAX interface

SYNOPSIS

shellinaboxd
[ -b | --background[=pidfile] ] [ -c | --cert=certdir ] [ --cert-fd=fd ]
[ --css=filename ] [ --cgi[=portrange] ] [ -d | --debug ] [ -f | --static-
file=url:file ] [ -g | --group=gid ] [ -h | --help ]
[ --linkify=[none|normal|aggressive] ] [ --localhost-only ] [ --no-beep ] [ -n |
--numeric ] [ --pidfile=pidfile ] [ -p | --port=port ] [ -s | --service=service ]
[ -t | --disable-ssl ] [ --disable-ssl-menu ] [ -q | --quiet ] [ -u | --user=uid ]
[ --user-css=styles ] [ -v | --verbose ] [ --version ]

DESCRIPTION

The shellinaboxd daemon implements a webserver that listens on the specified port. The
web server publishes one or more services that will be displayed in a VT100 emulator
implemented as an AJAX web application. By default, the port is 4200 and the default
service URL is http://localhost:4200/.

If no particular service was requested, the server launches /bin/login querying the user
for their username and password. It then starts the user's default login shell.

Any modern JavaScript and CSS enabled browser will be able to access the published service
without requiring additional plugins.

OPTIONS

The following command line parameters control the operation of the daemon:

-b | --background[=pidfile]
Launch shellinaboxd as a background daemon process. Optionally, write the process id
to pidfile.

-c | --cert=certdir
If built with SSL/TLS support enabled, the daemon will look in certdir for any
certificates. If unspecified, this defaults to the current working directory.

If the browser negotiated a Server Name Identification the daemon will look for a
matching certificate-SERVERNAME.pem file. This allows for virtual hosting of multiple
server names on the same IP address and port.

If no SNI handshake took place, it falls back on using the certificate in the
certificate.pem file.

The administrator should make sure that there are matching certificates for each of
the virtual hosts on this server, and that there is a generic certificate.pem file.

If no suitable certificate is installed, shellinaboxd will attempt to invoke
/usr/bin/openssl and create a new self-signed certificate. This only succeeds if,
after dropping privileges, shellinaboxd has write permissions for certdir.

Most browsers show a warning message when encountering a self-signed certificate and
then allow the user the option of accepting the certificate. Due to this usability
problem, and due to the perceived security implications, the use of auto-generated
self-signed certificates is intended for testing or in intranet deployments, only.

--cert-fd=fd
Instead of providing a --cert directory, it is also possible to provide a
filedescriptor fd where the certificate and key can be retrieved. While this option
disables SNI support, it does offer an alternative solution for securely providing
the private key data to the daemon.

--css=filename
Sometimes, it is not necessary to replace the entire style sheet using the --static-
file option. But instead a small incremental change should be made to the visual
appearance of the terminal. The --css option provides a means to append additional
style rules to the end of the default styles.css sheet. More than one --css option
can be given on the same command line.

--cgi[=portrange]
Instead of running shellinaboxd as a permanent process, it can be demand-loaded as a
CGI web server extension. When doing so, it will spawn a server that lives for the
duration of the user's session. If an optional portrange of the form MINPORT-MAXPORT
has been provided, the server limits itself to these port numbers. They should be
configured to pass through the firewall.

The --cgi option is mutually exclusive with the --background, --pidfile and --port
options.

In order to be useful as a CGI script, the shellinaboxd binary probably will have to
be made setuid-root. This is currently a discouraged configuration. Use with care.

-d | --debug
Enables debugging mode, resulting in lots of log messages on stderr. This option is
mutually exclusive with --quiet and --verbose.

-f | --static-file=url:file
The daemon serves various built-in resources from URLs underneath the service mount
points. One or more --static-file options allow for overriding these resources with
customized externally provided files. The url can either be an absolute or a
relative path. In the former case, it overrides exactly one built-in resource for one
specific service, whereas in the latter case it overrides resources for each defined
service.

The following resources are available for customization:

beep.wav audio sample that gets played whenever the terminal BEL is sounded.

favicon.ico favicon image file that is displayed in the browser's navigation
bar.

ShellInABox.js JavaScript file implementing the AJAX terminal emulator.

styles.css CSS style file that controls the visual appearance of the terminal.

print-styles.css CSS style file that controls the visual appearance of printed pages
when using the VT100 transparent printing feature.

It is not recommended to override the root HTML page for a particular service.
Instead, move the service to an anonymous URL and serve a static-file that references
the service in an <iframe>.

Instead of a file, it is possible to provide the name of a directory. This turns
shellinaboxd into a simple web server that publishes all of the files in that
particular directory. This option can be helpful when publishing a more complex root
HTML page.

-g | --group=gid
When started as root, the server drops most privileges at start up. Unless overridden
by the --group option, it switches to nogroup.

When already running as an unprivileged user, group changes are not possible.

If running with SSL/TLS support enabled, the certificates must be accessible to the
unprivileged user and/or group that the daemon runs as.

-h | --help
Display a brief usage message showing the valid command line parameters.

--linkify=[none|normal|aggressive]
the daemon attempts to recognize URLs in the terminal output and makes them
clickable. This is not neccessarily a fool-proof process and both false negatives and
false positives are possible. By default, only URLs starting with a well known
protocol of http://, https://, ftp://, or mailto: are recognized. In aggressive mode,
anything that looks like a hostname, URL or e-mail address is recognized, even if not
preceded by a protocol.

--localhost-only
Normally, shellinaboxd listens on all available network interfaces. When operating
behind a reverse-proxy that is not always desirable. This command line option tells
the daemon to only listen on the loopback interface.

--no-beep
not only are audible signals undesired in some working environments, but browser
support for media playback is often buggy, too. Setting this option suppresses all
audio playback and enables the visual bell by default.

-n | --numeric
When running in --verbose mode, the daemon prints an Apache-style log file to stderr.
By default, host names of peers get resolved before logging them. As DNS look-ups can
be expensive, it is possible to request logging of numeric IP addresses, instead.

--pidfile=pidfile
The shellinaboxd daemon can be configured to store its process identifier in pidfile.

-p | --port=port
Unless overridden by this option, the web server listens on port 4200 for incoming
HTTP and HTTPS requests.

shellinaboxd can distinguish between SSL/TLS requests and unencrypted requests. It
also knows how to negotiate Server Name Identification, allowing the use of a single
port for all types of requests even when virtual hosting.

-s | --service=service
One or more services can be registered on different URL paths:
SERVICE := <url-path> ':' APPLICATION

There is a pre-defined application, 'LOGIN', which causes the daemon to invoke
/bin/login requesting the user's name and password, and starting his login shell.
This is the default option for the root user, if no --service was defined. Starting
/bin/login requires root privileges.

There is another pre-defined application, 'SSH'. Instead of invoking /bin/login, it
calls ssh. This is the default option for unprivileged users, if no --service was
defined. This operation is available to both privileged and regular users. If the
optional host parameter is omitted, shellinaboxd connects to localhost.

Alternatively, an application can be specified by providing a user description, a
working directory, and a command line:
APPLICATION := 'LOGIN' | 'SSH' [ ':' <host> ] | USER ':' CWD ':' CMD

The keyword 'AUTH' indicates that the user information should be requested
interactively, instead of being provided as part of the service description:
USER := 'AUTH' | <username> ':' <groupname>

The working directory can either be given as an absolute path, or it can be the
user's home directory:
CWD := 'HOME' : <dir>

The command that shellinaboxd executes can either be specified as the 'SHELL'
keyword, denoting the user's default login shell, or an arbitrary command line:
CMD := 'SHELL' : <cmdline>

The <cmdline> supports expansion of variables of the form ${VAR}. Supported
variables are:

${columns} number of columns.

${gid} numeric group id.

${group} group name.

${home} home directory.

${lines} number of rows.

${peer} name of remote peer.

${realip} value of HTTP header field 'X-Real-IP'.

${uid} numeric user id.

${url} the URL that serves the terminal session.

${user} user name.

Other than the environment variables of $TERM, $COLUMNS, $LINES,
$SHELLINABOX_PEERNAME, $SHELLINABOX_REALIP and $SHELLINABOX_URL, services can have
environment variables passed to them, by preceding the <cmdline> with space separated
variable assignments of the form KEY=VALUE.

The <cmdline> supports single and double quotes, as well as backslashes for escaping
characters in the familiar fashion.

Please note that when invoking shellinaboxd from a command line shell, additional
quoting might be required to prevent the shell from expanding the variables prior to
passing them to the daemon.

If no explicit --service has been requested, shellinaboxd defaults to attaching the
default service to the root directory of the web server. For root, this is
/bin/login, and for unprivileged users, this is ssh localhost. This is equivalent to
saying --service=/:LOGIN, or --service=/:SSH, respectively.

Please note that for SSH service to work properly, we need a running ssh server on
local system with enabled password authentication. If we are using <host> parameter,
same conditions must be true on that remote system.

-t | --disable-ssl
By default, shellinaboxd redirectes all incoming HTTP requests to their equivalent
HTTPS URLs. If promoting of connections to encrypted SSL/TLS sessions is undesired,
this behavior can be disabled.

This option is also useful during testing or for deployment in trusted intranets, if
SSL certificates are unavailable.

--disable-ssl-menu
If the user should not be able to switch between HTTP and HTTPS modes, this choice
can be removed from the context menu. The user can still make this choice by directly
going to the appropriate URL.

-q | --quiet
Suppresses all messages to stderr. This option is mutually exclusive with --debug
and --verbose.

-u | --user=uid
If started as root, the server drops privileges by changing to nobody, unless the uid
has been overridden by this option.

For more details, refer to the description of the --group option.

--user-css=styles
The visual appearance of the terminal emulator can be customized through user-
selectable style sheets. These style sheets will show up as options in the right-
click context menu of the terminal emulator.

Styles sheet make up either independently selectable on/off options, or multiple
style sheets can be grouped together. When forming a group, only one member of the
group can be active at any given time. This is used for multiple-choice options.

Multiple independent groups are separated by semicolons:
STYLES := GROUP { ';' GROUP }*

The members of a group are separated by commas:
GROUP := OPTION { ',' OPTION }*

Groups with exactly one member are used for options that can be independently turned
on and off.

Options include a human readable label that will be shown in the context menu,
followed by the name of the CSS file. They also must include an indicator showing
whether the option should initially be turned on or turned off. Within a group,
exactly one option should be turned on:
OPTION := <label> ':' [ '-' | '+' ] <css-file>

The user's selection of options will be persisted in a cookie. This means, the
default settings of options as passed on the command line only takes effect the very
first time the user visits the terminal emulator in his browser. On all subsequent
visits, the user's preferences take precedence.

-v | --verbose
Enables logging of Apache-style log file to stderr. This option is mutually
exclusive with --debug and --quiet.

--version
Prints the version number of the binary and exits.

CONFIGURATION

There are no configuration files or permanent settings for shellinaboxd.

A small number of run-time configuration options are available from a context menu that
becomes available when clicking the right mouse button. These options get persisted in a
browser cookie.

Many sites already have a web server running and would like to integrate shellinaboxd into
their existing site. This is most commonly done by means of a reverse-proxy entry for the
main web server. For Apache this would require adding an option such as:
<Location /shell>
ProxyPass http://localhost:4200/
Order allow,deny
Allow from all
</Location>

If you are using a different web server, refer to that server's documentation on how to
configure reverse proxy operations.

When using a reverse proxy, the --localhost-only option would normally be enabled as well.
In addition, the --disable-ssl might also be considered depending on the exact
configuration details of the reverse proxy.

EXAMPLES

shellinaboxd Attaches a web-enabled login shell to https://localhost:4200/. If the user
connected without SSL, the session will automatically be promoted. Unless
SSL certificates can be found in the current directory, the daemon will
automatically generate suitable self-signed certificates. If the command was
invoked by a non-root user, the daemon uses ssh instead of /bin/login for the
session.

shellinaboxd -t
Attaches a web-enabled login shell to http://localhost:4200/ with SSL/TLS
support disabled.

shellinaboxd -t -f beep.wav:/dev/null
Runs all services with the audible-bell permanently disabled.

shellinaboxd -s /:SSH:example.org
The terminal connects to a ssh session on example.org.

shellinaboxd -t -s /:AUTH:HOME:/bin/bash
Interactively request the user's name and password prior to launching a
Bourne shell. This command can be run by unprivileged users. But if doing so,
it only allows this particular user to log in.

shellinaboxd -c certificates -u shellinabox -g shellinabox
If the certificates directory exists and is writable by the shellinabox user
and group, self-signed SSL certificates will be generated in this directory.
This might require creating an appropriately named user first. Running this
command as root allows any user on the system to log in at
http://localhost:4200/. Sessions will automatically be promoted to SSL/TLS.

shellinaboxd -t -s /:LOGIN -s /who:nobody:nogroup:/:w
In addition to the login shell at http://localhost:4200, show a list of
currently logged in users when accessing http://localhost:4200/who. This
command must be run as root in order to be able to change to nobody:nogroup
as requested by the service description.

shellinaboxd -t -s '/:root:root:/:wy60 -c /bin/login'
Instead of the standard ANSI/VT100 terminal, publish a Wyse 60™ terminal.
Again, this command should be run as root.

shellinaboxd --css white-on-black.css
Loads the white-on-black.css style sheet from the current directory and
appends it to the built-in styles.css sheet. This causes the terminal to
always render white text on a black background.

shellinaboxd --user-css Normal:+black-on-white.css,Reverse:-white-on-black.css
Allow the user to select whether they want text to be rendered normally or in
reverse video. This command line option adds a new entry to the right-click
context menu.

DIAGNOSTICS

The daemon returns a non-zero exit code in case of failure. With the exception of a small
number of common error cases that are handled explicitly, most errors result in printing a
"Check failed" message. This does not typically indicate a bug in the program but is
instead its normal way of reporting errors.

Common failure conditions are reusing a port that is already in use, lack of sufficient
privileges to run a service, failure to find SSL/TLS certificates, and failure to write
newly generated certificates to the certification directory.

Use shellinaboxd online using onworks.net services