SHELLINABOXD(1)SHELLINABOXD(1)NAMEshellinaboxd - publish command line shell through AJAX interface
SYNOPSISshellinaboxd
[ -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 ] [ --pid‐
file=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 appli‐
cation. 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 dae‐
mon:
-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 cer‐
tificate in the certificate.pem file.
The administrator should make sure that there are matching cer‐
tificates 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 certifi‐
cate. This only succeeds if, after dropping privileges, shellina‐
boxd 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 deploy‐
ments, 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 ses‐
sion. 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 --ver‐
bose.
-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 termi‐
nal 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 appear‐
ance of the terminal.
print-styles.css CSS style file that controls the visual appear‐
ance of printed pages when using the VT100 trans‐
parent printing feature.
It is not recommended to override the root HTML page for a partic‐
ular 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 direc‐
tory. This turns shellinaboxd into a simple web server that pub‐
lishes 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 aggres‐
sive 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 inter‐
faces. When operating behind a reverse-proxy that is not always
desirable. This command line option tells the daemon to only lis‐
ten on the loopback interface.
--no-beep
not only are audible signals undesired in some working environ‐
ments, 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 pos‐
sible 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 unen‐
crypted requests. It also knows how to negotiate Server Name Iden‐
tification, 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 dae‐
mon 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 preced‐
ing the <cmdline> with space separated variable assignments of the
form KEY=VALUE.
The <cmdline> supports single and double quotes, as well as back‐
slashes 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 --ser‐
vice=/:LOGIN, or --service=/:SSH, respectively.
Please note that for SSH service to work properly, we need a run‐
ning ssh server on local system with enabled password authentica‐
tion. 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 dis‐
abled.
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 exclu‐
sive 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 emu‐
lator.
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 com‐
mand 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 shellina‐
boxd.
A small number of run-time configuration options are available from a
context menu that becomes available when clicking the right mouse but‐
ton. These options get persisted in a browser cookie.
Many sites already have a web server running and would like to inte‐
grate 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 docu‐
mentation 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 con‐
sidered depending on the exact configuration details of the reverse
proxy.
EXAMPLESshellinaboxd Attaches a web-enabled login shell to https://local‐
host:4200/. If the user connected without SSL, the ses‐
sion will automatically be promoted. Unless SSL certifi‐
cates can be found in the current directory, the daemon
will automatically generate suitable self-signed certifi‐
cates. 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://local‐
host:4200/ with SSL/TLS support disabled.
shellinaboxd-t -f beep.wav:/dev/null
Runs all services with the audible-bell permanently dis‐
abled.
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 certifi‐
cates will be generated in this directory. This might
require creating an appropriately named user first. Run‐
ning this command as root allows any user on the system to
log in at http://localhost:4200/. Sessions will automati‐
cally 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 ren‐
dered 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.
SEE ALSOchmod(1), last(1), login(1), sh(1), shells(5), openssl(1SSL), w(1),
wy60(1), xterm(1).
SECURITY
The daemon uses privilege separation techniques to allow it to drop
privileges early. It is aware of setuid flags and restricts some opera‐
tions when launched as a setuid application.
Despite these safety features, a bug could conceivably lead to a deter‐
mined attacker gaining elevated privileges. It is therefore strongly
discouraged to set the setuid flag on the binary.
The expected deployment would be from a system rc script launched by
/sbin/init. For extra security, the --group and --user options should
be used to change to a dedicated user.
AUTHOR
Copyright (C) 2008-2010 by Markus Gutschke <markus@shellinabox.com>.
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 as pub‐
lished by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
In addition to these license terms, the author grants the following
additional rights:
If you modify this program, or any covered work, by linking or combin‐
ing it with the OpenSSL project's OpenSSL library (or a modified ver‐
sion of that library), containing parts covered by the terms of the
OpenSSL or SSLeay licenses, the author grants you additional permission
to convey the resulting work. Corresponding Source for a non-source
form of such a combination shall include the source code for the parts
of OpenSSL used as well as that of the covered work.
You may at your option choose to remove this additional permission from
the work, or from any part of it.
If you would like to negotiate different licensing terms that are com‐
patible for integration with other projects, please contact the author.
If the OpenSSL system libraries can be found at run-time, they will be
invoked by shellinaboxd to provide SSL/TLS support. The OpenSSL and
SSLeay licenses require the following notices:
This product includes software developed by the OpenSSL Project for use
in the OpenSSL Toolkit. (http://www.openssl.org/)
This product includes cryptographic software written by Eric Young
(eay@cryptsoft.com)
BUGS
Due to browser limitations, some features might not be available to
users of all browers.
Konqueror does not allow for reliable interception of CTRL keys. If you
press a key together with the CTRL modifier, it continues performing
the browser's predefined behavior for this particular key combination.
In most cases, it also fails to report the correct key to the terminal
emulator. As a work-around, pressing both the CTRL and the WINDOWS key
sometimes works.
Some browsers, most notably IE on Windows, disallow interception of ALT
keys and always interpret these keys as menu accelerators. As a work-
around, many UNIX applications allow pressing ESC, instead of ALT.
When using non-US keyboard layouts, some browser do not allow for reli‐
ably determining shifted ALT keys. Please report these cases if they
turn out to be a problem, as work-arounds might be possible.
Access to the native clipboard is typically not possible. Instead, an
internal clipboard accessible from the right-button context menu is
used for all but IE.
Some browsers restrict the number of concurrent connections to a
server. This restricts how many AJAX terminals can be opened simultane‐
ously. If this becomes a problem, users can typically reconfigure their
browsers to raise the limit.
There have been reports of the VLC plugin on Linux/x86_64 crashing
Firefox when the browser page gets reloaded. Setting the --no-beep
option eliminates all references to VLC and thus appears to work around
this crash.
Sep 11, 2010 SHELLINABOXD(1)
