table of contents
SHELLINABOXD(1) | General Commands Manual | SHELLINABOXD(1) |
NAME¶
shellinaboxd - publish command line shell through AJAX interfaceSYNOPSIS¶
- 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.
- --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.
- -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.
- 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.
- -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.
- -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.
- -s | --service=service
- One or more services can be registered on different URL
paths:
SERVICE := <url-path> ':' APPLICATION
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>
CWD := 'HOME' : <dir>
CMD := 'SHELL' : <cmdline>
- ${columns}
- number of columns.
- ${gid}
- numeric group id.
- ${group}
- group name.
- ${home}
- home directory.
- ${lines}
- number of rows.
- ${peer}
- name of remote peer.
- ${uid}
- numeric user id.
- ${url}
- the URL that serves the terminal session.
- ${user}
- user name.
- -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.
- --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
- Surpresses 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.
- --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 := GROUP { ';' GROUP }*
GROUP := OPTION { ',' OPTION }*
OPTION := <label> ':' [ '-' | '+' ] <css-file>
- -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.<Location /shell>
ProxyPass http://localhost:4200/
Order allow,deny
Allow from all
</Location>
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(Tm) 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.SEE ALSO¶
chmod(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 operations when launched as a setuid application.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 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)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 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 |