| SHELLINABOXD(1) | General Commands Manual | SHELLINABOXD(1) |
shellinaboxd - publish command line shell through AJAX interface
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.
The following command line parameters control the operation of the daemon:
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.
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.
The following resources are available for customization:
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.
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.
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.
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:
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.
This option is also useful during testing or for deployment in trusted intranets, if SSL certificates are unavailable.
For more details, refer to the description of the --group option.
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.
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.
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.
chmod(1), last(1), login(1), sh(1), shells(5), openssl(1SSL), w(1), wy60(1), xterm(1).
The daemon uses privilege separation techniques to allow it to drop privileges early. It is aware of setuid flags and restricts some operations when launched as a setuid application.
Despite these safety features, a bug could conceivably lead to a determined 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.
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 published 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 MERCHANTABILITY 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 combining it with the OpenSSL project's OpenSSL library (or a modified version 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 compatible 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)
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 reliably 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 simultaneously. 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.
| September 11, 2010 |