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.
If the browser negotiated a ServerNameIdentification 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.
--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.
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 --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.
The following resources are available for customization:
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.
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.
-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
necessarily 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.
shellinaboxd can distinguish between SSL/TLS requests and unencrypted requests. It also knows how to
negotiate ServerNameIdentification, 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 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:
${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
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 sshlocalhost. 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.
-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.
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 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.
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
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.
-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.
Install Now
PNG Icons
