|
shellinaboxd_man
shellinaboxd - publish command line shell through AJAX interface
shellinaboxdSYNOPSIS 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 ] [ -p |
--port=port ] [ -s | --service=service ] [ -t | --disable-ssl ]
[ --disable-ssl-menu ] [ -q | --quiet ] [ -u | --user=uid ]
[ --user-css=styles ] [ -v | --verbose ] [ --version ] DESCRIPTIONThe 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. OPTIONSThe following command line parameters control the operation of the daemon:
Launch shellinaboxd as a background daemon process. Optionally, write the process id to pidfile. 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. 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. 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. 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 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. Enables debugging mode, resulting in lots of log messages on stderr. This option is mutually exclusive with --quiet and --verbose. 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: 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 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. Display a brief usage message showing the valid command line parameters. the daemon attempts to recognize URLs in the terminal output and makes them clickable. This is not neccessarily a fool-proof pro‐ cess 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. 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. 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. 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. One or more services can be registered on different URL paths:SERVICE := <url-path> ':' APPLICATIONThere 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 ':' CMDThe 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 default environment variables of $TERM, $COLUMNS and $LINES, 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. 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. 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. Surpresses all messages to stderr. This option is mutually exclusive with --debug and--verbose. 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. 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. Enables logging of Apache-style log file to stderr. This option is mutually exclusive with --debug and --quiet. Prints the version number of the binary and exits. CONFIGURATIONThere 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. 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
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. Attaches a web-enabled login shell to http://localhost:4200/ with SSL/TLS support disabled. Runs all services with the audible-bell permanently disabled. The terminal connects to a ssh session on example.org. 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. If the certificates directory exists and is writable by the shellinaboxd group, self-signed SSL certificates will be generated in this directory. 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. 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. Instead of the standard ANSI/VT100 terminal, publish a Wyse 60 terminal. Again, this command should be run as root. 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. 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. DIAGNOSTICSThe 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 ALSO"chmod(1), last(1), login(1), sh(1), shells(5), openssl(1SSL), w(1), wy60(1), xterm(1). SECURITYThe 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. AUTHORCopyright (C) 2008-2009 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) BUGSDue to browser limitations, some features might not be available to users of all browers.
|
Sign in to add a comment
It would be nice to see an example for SSHing forward to another host using ShellInABox.
I can' seem to figure out the --service parameter.
Thanks.
Hi,
I am using UTF8 as the default encoding for my files. They show up correctly in the shellinabox, but I can't enter any accentuated character with my keyboard (azerty/french). Is it a bug, or is it that this feature is not implemented ?
In any case, thanks for your work. This is really a good piece of software.
Support for accepting keyboard input is one of the parts of JavaScript? that is very poorly supported by most browsers. It takes a lot of browser-specific code to be able to receive most keyboard input, but some keys or key combinations are still difficult or impossible to receive. International (i.e. non-US) keys and keyboards are often particularly poorly supported by the JavaScript? implementations in many browsers.
Having said all that, I would still like to try and find a solution for the problem that you are reporting. But you could help me a lot if you provided more details. Maybe, you could file a new "Issue" and include information on the browser that you are using (including version number), the operating system that is affected, and the exact keyboard configuration. If I can reproduce the problem locally, then I might be able to find a work-around that detects the particular configuration and figures out the correct keys.
Also, since I probably don't know how the AZERTY keyboard is supposed to behave, please give an exact description of which key(s) you press, what result you expect to see, and what ShellInABox does instead.
This is tracked as Issue 13 which is now resolved.
Firstly thank you very much for creating shellinabox.
I've compiled it to run on my Nokia N800 tablet (which is always switched on, unlike my PC, so better suited to remote access). However, the objcopy commands didn't work until I changed the output target. In Makefile.in, I changed: ' -O elf64-x86-64 -B i386:x86-64' to ' -O elf32-littlearm -B arm' Obviously this is not a proper fix, but it got it working for me. The available targets I have are: elf32-littlearm elf32-bigarm elf32-little elf32-big srec symbolsrec tekhex binary ihex - I started at the first option on the list, which seems to work, so I didn't try any more.
I also reverse-proxied shellinabox through Apache (with SSL + client certs + http auth). I modified the code to make shellinabox listen on the loopback adapter only (I didn't want other machines to be able to connect directly, only via Apache). In libhttp/server.c I changed serverAddr.sin_addr.s_addr = INADDR_ANY; to serverAddr.sin_addr.s_addr = htonl(INADDR_LOOPBACK); May I suggest making this as a command-line option?
Thank you.
Thank you for those suggestions. The SVN version now has both of these changes.
I can confirm the latest version (svn131) successfully compiles for my N800 without making any changes to the Makefile. I've tried the --localhost-only switch and that works fine too.
Thanks very much!
In reply to "devraj"'s query. I added a SSH option to the list of predefined services and included an example in the manual page. This should make this common use case easier to configure.
shellinabox is really a great tool. Would it be possible to run the spawned cgi process on a local socket and tunnel all communication through the cgi script? This will solve problems where people are behind a port-80/443-only proxy.
You can use the --localhost-only option to make the daemon listen on a local socket.
But there currently is no option to run the binary as a CGI that connects to this socket. It would be trivial to write a tiny script that does this, but you are probably better off to configure your web server or your (reverse-)proxy to connect to the local socket.
This is in fact that way that a lot of people are using ShellInABox.
Performance is not quite as good as when using a dedicated external socket, as most reverse proxies appear to not know about keeping connections open. But in practice that doesn't matter much for local connections from the proxy to the ShellInABox daemon.
shellinabox is really a great tools for me but non working with ssh
Could anyone tell me if it's possible to have it auto-login to a bash prompt after passing either PHP/PERL authentication? It might sound insecure but its a risk I'm comfortable taking given the nature of what I'm doing, local intranet.
Alternatively can someone show me how to only allow this to run after passing php authentication? If a user's session isnt authenticated I dont even want them getting to this app.