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:
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
USER := <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:
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.
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.
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.
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.
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.