Shell In A Box Gives Your Browser Terminal Status

Shell In A Box is project that includes a web server, Javascript files and CSS templates to setup web-based terminal access to your system. You might remember that Shell In A Box was part of last week’s TurnKey Linux project. It is a fascinating project of its own and it deserves some focused attention.

Give yourself the freedom of a web-based terminal session with Shell In A Box. It’s a small, easy to install and use application that makes downloading an SSH client obsolete. And, if your system has SSL/TLS enabled, your communications are secure.

The Basics

Point your browser to ShellInABox.com, which redirects you to its hosted location on Google Code. Download the source code or Debian package from the project’s download page. The source code works well on Debian-based and on Red Hat-based distributions.

For a quick install, unzip and untar the code, cd into the source directory and issue the standard, ./configure ; make ; make install command. After a few minutes, your Shell In A Box compiles and installs. The shellinaboxd executable installs to /usr/local/bin, which should be in your path ($PATH). If it isn’t, add it with the following command:

$ PATH=$PATH:/usr/local/bin 

To make the change permanent, add that line into the .bash_profile file in your home directory.

Once you have Shell In A Box installed, it’s time to move on to setup and usage.

User-Level Shell In A Box

Note: Any user can invoke and use Shell In A Box (SIAB), which can be both a blessing and a curse for System Administrators. If you prefer to have a single SIAB running that you manage and support, change the permissions so that only the root user can execute SIAB.

Provided that your System Administrator doesn’t shut down your personal access to SIAB, let’s look at how you can enjoy it for yourself–at least until the System Nazis figure it out and ruin it for everyone.

The default SIAB port is 4200 but it would be wise, as a regular user, to change this port to one that doesn’t conflict with any other system service. Try the easy-to-remember port, 5678. A quick netstat -at |grep LISTEN will give you a list of used ports.

Note: If you start your own instance of SIAB, any user can connect to that port and login. Just so you know that it isn’t a private port for your use only.

To start using SIAB right away, issue this simple command.

$ shellinaboxd --port=5678

Open a web browser on a remote system and enter the SIAB system’s name or IP address and port number. For example, http://zaphod:5678. Your browser will respond with something similar to:

zaphod login: khess
khess@zaphod's password: *********
khess@zaphod:~$

Enter your username and password and you’re in. Issue any system command that you want at this point (X programs don’t seem to work). You have full shell access and you can manage your system with this interface.

When you login to your SIAB interface, you probably noticed that it white with black text. You can change this default behavior by specifying the CSS file that presents you with the more UNIX standard of white text on a black background. You’ll find the CSS files in the source tree under the shellinabox directory. Your choices for styles are: black-on-white (default), white-on-black, color and monochrome. Copy the CSS files to your home directory so that you can use them at will.

To use something other than the default, use the CSS switch, –css=[filename.css] in your command.

$ shellinaboxd --port=5678 --css=white-on-black.css

You also noticed that your shell in which you invoked SIAB “hung” after you entered the command shellinaboxd –port=5678. This is due to the way you started SIAB–as a foreground process. You can issue the command with the standard UNIX-style ‘&’ to place the program in background or you can use the background switch (-b) to do the same thing in a more elegant way.

$ shellinaboxd -b --port=5678 --css=white-on-black.css

This command allows you to continue to use your regualar shell and provide a web-based shell. Now, let’s look at how to provide a controlled SIAB to all users on a system and create it as a standard system service.

A System-wide Shell In A Box

As a System Administrator, you might want to keep control of system ports and various services used on systems that you administer. You want to provide SIAB to your users as you would any other system service such as SSH or HTTP and you want to do it in a way that protects your system. SIAB gives you this ability.

You’d handle SIAB in the same way that you’ve seen previously but with a couple of extra twists. As stated earlier, you should lock-down SIAB with a simple permissions change.

# chmod 700 /usr/local/bin/shellinaboxd

Now, only you can start SIAB. Next, if you’re providing this as a system service, you’ll want to create startup and shutdown scripts so that the service starts on any reboot and so that you can start and stop SIAB at will without a search for the command line options every time you need to start or stop it.

Create an executable file in /etc/init.d and name it something clever like shellinabox. Edit the /etc/init.d/shellinabox file and enter the following into it.

#!/bin/sh
# Shell In A Box (Web-based Terminal Emulator) that runs on port 4200

case "$1" in
'start')
        /usr/local/bin/shellinaboxd --css /usr/local/bin/white-on-black.css --background=/var/run/SIAB.pid
        ;;
'stop')
        SIABPID=`cat /var/run/SIAB.pid`
        kill $SIABPID
        ;;
*)
        echo "Usage: $0 { start | stop }"
        ;;
esac
exit 0

Notice that you have to use the explicit switch, –background to specify a PID file. The PID file allows you to kill the process by using the process ID and your handy /etc/init.d script.

Shell In A Box is one of those somewhat obscure projects that often catches my eye for this column. Innovative and useful projects like SIAB provide stepping stones and enhancements for other projects such as the TurnKey Linux project. Please the the SIAB manual for more information and options not covered here.

If you find cool projects like Shell In A Box, let us know. Chances are that if you find it fun and useful, others will as well.