SHELLINABOXD(1)

okay bestie, welcome to the shellinaboxd(1) manual page — it's in the General Commands Manual section, and it's literally all about publishing a command line shell through an AJAX interface 💅✨

✨ NAME ✨

shellinaboxd — publish command line shell through AJAX interface 🦋

---

🌸 SYNOPSIS 🌸

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 💖

so the shellinaboxd daemon is literally a webserver that listens on the port you tell it to. it publishes one or more services that show up in a VT100 emulator that's implemented as an AJAX web application. by default, the port is 4200 and the default service URL is http://localhost:4200/. 💅

if you didn't ask for any particular service, the server launches /bin/login and asks for username and password, then starts the user's default login shell. 🌸

any modern browser with JavaScript and CSS enabled can access the published service, no extra plugins needed. periodt. ✨

---

👑 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 it was built with SSL/TLS support enabled, the daemon looks in certdir for any certificates. if you don't specify it, it defaults to the current working directory. 💖
  • if the browser negotiated a Server Name Identification, the daemon looks for a matching certificate-SERVERNAME.pem file. this lets you virtually host multiple server names on the same IP address and port. slay.
  • if no SNI handshake happened, it falls back to using the certificate in the certificate.pem file.
  • the administrator should make sure there are matching certificates for each virtual host on this server, and that there's a generic certificate.pem file. 👑
  • if no suitable certificate is installed, shellinaboxd will try to invoke /usr/bin/openssl and create a new self-signed certificate. this only works if, after dropping privileges, shellinaboxd has write permissions for certdir. no cap.
  • most browsers throw a warning when they see a self-signed certificate and then let the user accept it. because of that usability problem and the perceived security implications, auto-generated self-signed certificates are only meant for testing or intranet deployments. ⚠️
• --cert-fd=fd — instead of giving a --cert directory, you can pass a filedescriptor fd where the certificate and key can be retrieved. this option disables SNI support, but it's a secure alternative for handing the private key data to the daemon. 🔐
• --css=filename — sometimes you don't need to replace the whole style sheet with --static-file — you just want a tiny incremental change to how the terminal looks. --css lets you append extra style rules to the end of the default styles.css sheet. you can give more than one --css option on the same command line. 💅
• --cgi[=portrange] — instead of running shellinaboxd as a permanent process, you can demand-load it as a CGI web server extension. when you do that, it spawns a server that lives for the duration of the user's session. if you provide an optional portrange of the form MINPORT-MAXPORT, the server limits itself to those port numbers. they should be configured to pass through the firewall. 🔥

--cgi is mutually exclusive with --background, --pidfile and --port. don't mix them, bestie.

in order to be useful as a CGI script, the shellinaboxd binary probably has to be made setuid-root. this is currently a discouraged configuration. use with care. 💀

• -d, --debug — enables debugging mode, which means lots of log messages on stderr. this option is mutually exclusive with --quiet and --verbose. pick one, not all three. 😭
• -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 let you override these with your own external files. the url can be absolute or relative. absolute overrides exactly one built-in resource for one specific service; relative overrides resources for each defined service. 🌈

these are the resources you can customize:

• beep.wav — audio sample that gets played whenever the terminal BEL is sounded.
• favicon.ico — favicon image file that shows up 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, you can provide the name of a directory. this turns shellinaboxd into a simple web server that publishes all the files in that directory. this can help when publishing a more complex root HTML page. ✨

• -g, --group=gid — when started as root, the server drops most privileges at start up. unless you override it with --group, 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 — shows a brief usage message with all the valid command line parameters. you love to see it. 💖
• --linkify=[none|normal|aggressive] — the daemon tries to recognize URLs in the terminal output and make them clickable. this is not fool-proof — you can get false negatives and false positives. by default, only URLs starting with a well-known protocol like http://, https://, ftp://, or mailto: are recognized. in aggressive mode, anything that looks like a hostname, URL or e-mail address is recognized, even without a protocol. 😈
• --localhost-only — normally shellinaboxd listens on all available network interfaces. when you're behind a reverse-proxy, that's not always what you want. this option tells the daemon to only listen on the loopback interface. 🏠
• --no-beep — audible signals are not it in some work environments, and browser media playback support is often buggy anyway. setting this 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, it resolves peer host names before logging them. DNS look-ups can be expensive, so you can request numeric IP addresses instead. 🧮
• --pidfile=pidfile — you can configure the shellinaboxd daemon to store its process identifier in pidfile. 📝
• -p, --port=port — unless you override it with this option, the web server listens on port 4200 for incoming HTTP and HTTPS requests. 🌐 shellinaboxd can tell the difference between SSL/TLS requests and unencrypted requests. it also knows how to negotiate Server Name Identification, so you can use a single port for all types of requests even with virtual hosting. slay. ✨
• -s, --service=service — you can register one or more services on different URL paths:

SERVICE := <url-path> ':' APPLICATION

there's a pre-defined application 'LOGIN' that makes the daemon invoke /bin/login, ask for username and password, and start the user's login shell. this is the default for the root user if no --service was defined. starting /bin/login requires root privileges. 👑

there's another pre-defined application 'SSH'. instead of invoking /bin/login, it calls ssh. this is the default for unprivileged users if no --service was defined. it works for both privileged and regular users. if the optional host parameter is omitted, shellinaboxd connects to localhost. 🖥️

alternatively, you can specify an application by giving a user description, a working directory, and a command line:

APPLICATION := 'LOGIN' | 'SSH' [ ':' <host> ] |  USER ':' CWD ':' CMD

the keyword 'AUTH' means the user information should be requested interactively instead of being part of the service description:

USER := 'AUTH' | <username> ':' <groupname>

the working directory can be an absolute path or the user's home directory:

CWD := 'HOME' : <dir>

the command that shellinaboxd executes can be the 'SHELL' keyword (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.

---

quick lil heads-up bestie: this is still the --service tea from before, we're just picking up right where we left off 💖

Okay so beyond the built-in env vars — $TERM, $COLUMNS, $LINES, $SHELLINABOX_PEERNAME, $SHELLINABOX_REALIP and $SHELLINABOX_URL — you can hand services any extra environment variables you want. How? Just stick space-separated variable assignments of the form KEY=VALUE in front of the <cmdline>. That's it, that's the whole trick. ✨

And <cmdline> is polite about quoting: it understands single quotes and double quotes, plus backslashes for escaping characters, all in the familiar classic way. 🫶

tiny caution tho: when you're invoking shellinaboxd from a command line shell, you might need extra quoting so your shell doesn't gobble up and expand the variables before they ever reach the daemon. Your shell is nosy like that, ngl. 🙈

If you don't explicitly ask for a --service at all, shellinaboxd defaults to attaching the default service to the root directory of the web server. For root, that's /bin/login, and for unprivileged users, it's ssh localhost. Which is literally the same as saying --service=/:LOGIN, or --service=/:SSH, respectively. 💅

important: for the SSH service to work properly, you need a running ssh server on the local system with enabled password authentication. And if you're using the <host> parameter, those exact same conditions have to be true on that remote system too. No password auth, no vibes, no session. 😭

---

✨ OPTIONS ✨ (the rest of the lineup, bestie 💖)

• -t, --disable-ssl — By default, shellinaboxd redirects all incoming HTTP requests to their equivalent HTTPS URLs. But if promoting connections up to encrypted SSL/TLS sessions isn't the vibe you want, you can turn that behavior off. 🚫🔒 This option is also lowkey perfect for testing, or for deploying on trusted intranets where SSL certificates just... aren't available. 🤷‍♀️
• --disable-ssl-menu — If the user shouldn't be able to switch back and forth between HTTP and HTTPS modes, you can yeet that choice right out of the context menu. (They can still make that choice by going directly to the appropriate URL, though — so it's more "out of sight" than "locked down", iykyk.)
• -q, --quiet — Suppresses all messages to stderr. Mutual exclusivity alert: this one is mutually exclusive with --debug and --verbose. Pick your fighter. ⚔️
• -u, --user=uid — If started as root, the server drops privileges by changing to nobody — unless you've overridden the uid with this option. 👑➡️👤 For more details, go read 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 show up as options in the right-click context menu of the terminal emulator. 🎀

Style sheets 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 — that's what powers 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'll 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>

heads up: the user's selection of options gets persisted in a cookie. Which means the default settings of options as passed on the command line only take effect the very first time the user visits the terminal emulator in their browser. On all subsequent visits, the user's preferences win. The cookie is the main character now. 🍪👑

• -v, --verbose — Enables logging of an Apache-style log file to stderr. Mutual exclusivity again, bestie: this one is mutually exclusive with --debug and --quiet. 💅
• --version — Prints the version number of the binary and exits. Short, sweet, iconic. ⭐

---

🛠️ CONFIGURATION 🛠️

There are no configuration files and no permanent settings for shellinaboxd. Nothing hiding in /etc, nothing to hunt down. Freeing, honestly. 🦋

A small number of run-time configuration options are available from a context menu that becomes available when you click 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're using a different web server, go read that server's documentation on how to configure reverse proxy operations. Do your research, bestie, it's giving diligence. 📚✨

When using a reverse proxy, the --localhost-only option would normally be enabled as well. In addition, --disable-ssl might also be considered, depending on the exact configuration details of the reverse proxy.

---

🌸 EXAMPLES 🌸 (the fun part, fr fr)

• 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. And if the command was invoked by a non-root user, the daemon uses ssh instead of /bin/login for the session. Auto-magic, no cap. ✨
• shellinaboxd -t — Attaches a web-enabled login shell to http://localhost:4200/ with SSL/TLS support disabled. Simple. Clean. Unencrypted but intentional. 💅
• shellinaboxd -t -f beep.wav:/dev/null — Runs all services with the audible-bell permanently disabled. Silence is golden, bestie. 🔇
• shellinaboxd -s /:SSH:example.org — The terminal connects to a ssh session on example.org. Off you go. 🌍
• 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™ 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. Aesthetic. 🖤
• 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. And no, bestie, that doesn't typically mean there's a bug in the program — it's just its normal way of reporting errors. That's just how it talks. 😭

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).

---

🔒 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. Responsible king behavior. 👑

Despite these safety features, a bug could conceivably lead to a determined attacker gaining elevated privileges.

STRONGLY discouraged, bestie: it is therefore strongly discouraged to set the setuid flag on the binary. Like, don't. Seriously. 🚫💀

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. Extra layers, extra safe, that's the vibe. 🫶

💖 AUTHOR 💖

Copyright (C) 2008-2010 by Markus Gutschke <markus@shellinabox.com>.

okay so bestie, legal time but make it cute 💅

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. Slay.

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. (yes the caps are screaming, it's legally required, not me being dramatic for once 😭)

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 🎀

---

✨ the extra rights (yes there's more, stay with me) ✨

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. (be polite, they're a real person 💜)

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 🐛

ngl bestie, this is the "it's not me, it's the browsers" section 💀

Due to browser limitations, some features might not be available to users of all browers. (and yes, that's how it's spelled in the original, iconic typo, I'm keeping it fr fr 😌)

• 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. (they're being so nice about it 😭)
• 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. 🧚

---

and that's the whole page bestie!! you read all three parts, main character energy fr fr 👑

This was SHELLINABOXD(1), dated Sep 11, 2010 — so vintage, so iconic, we love a classic ⭐ no cap, go forth and shellinaboxd responsibly 🫶💖