README for MyShell (c)2001 Alejandro Vasquez http://www.digitart.net Licensed under the GNU GPL. See the file LICENSE for details. based on phpShell by Martin Geisler What is MyShell? ------------------ MyShell is a shell wrapped in a PHP script. It's a tool you can use to execute arbiritary shell-commands or browse the filesystem on your remote webserver. This replaces, to a degree, a normal telnet-connection. You can use it for transferring your site as a compressed file, and then unpack it on the webserver, administration and maintenance of your website using commands like ps, free, du, df etc... It includes a built-in password protection system that restrict access to the application and a built-in file editor to allow you to edit and create files directly from MyShell. Limitations ----------- There are some limitations on what kind of programs you can run. It won't do no good if you start something like Netscape or even vi. All programs have to be strictly command-line programs, and they will have no chance of getting user input after they have been lunched. They properly also have to terminate or give some text response within 30 seconds, as this is the default time-limit imposed unto all PHP-scripts, to prevent them from running in an infinite loop. Your ISP may have set this time-limit to something else. Features -------- You can rely on all the normal shell-functionality, like pipes, output and input redirection, etc ... (There is no -completion, though :-) You can use cd command to change directories, but at the moment you have to execute it without pipes and any other commands on the same line. i.e.: "cd /home | ls -l" won't work but "cd /home" and then "ls -l" will kork fine. You also can read online manuals using the "man" command and get meaningfull text without unredeable control chars. Protect yourself from MyShell ----------------------------- Being able to reveal contents of directories and files, and run commands directly on the server, this is a potentialy hazardous application that could challenge your data security. In order to get some sort of protection against this, MyShell has a simple but effective built in password protection that even sends you a warning email if someone is trying to log in with a wrong password/username. If you prefer, you can use .htaccess to restrict access to MyShell and turn off the built in password protection. The point here is that you should never install MyShell in your server without some kind of access restriction. Being a monolithic application -an application integrated in only one file-, you can rename the `shell.php' file to any name you want, and MyShell will remain fully operative despite it's file name. This way you'll prevent some malicious search for the explicit `shell.php' file on your system. You can also prevent MyShell to change to directories above some directory level i.e.: /home/userdirectory/. This is intended to be a System Admin friendly option. Let's face it. If you are a Sys Admin and host users on your server, you'll not allow them to install MyShell and be able to snoop arround your system without a bash_log trace. With this feature, you can let them use MyShell on their own websites as long as they keep this option restricted to their own directory. Maybe this can even replace the need of grant them sell access using telnet or ssh. In the other hand, if you are being hosted by someone else, it would be nice and polite to restrict access to your own directory. After all, you don't want your own security being challenged because someone else fails to prevent a lamer to snoop on your files using an unprotected MyShell, so start by yourself. After all, if you don't have access to system files it's because you don't need them in your day to day website administration. In any of the above circumstances, you are the only responsable of the use or missuse you do of MyShell. We do not accept any direct or implied responsability of any kind on how MyShell is used or installed on your system, so in this matter I'm affraid you are left alone by your own. For more details on the subject please read the LICENSE file included in this distribution. Who am I? --------- You may not be the same user, as when you upload your files with ftp. On some systems you will be nobody, on other systems you will become httpd. This is a rather dangerous "feature" of MyShell! So use it at your own risk - We wont be responsible if your account gets locked or something like that happens. To find out who you are just type whoami How to use it ------------- When you point your browser to MyShell and type in your password (see the file INSTALL for more information on how to password-protect MyShell), you'll be presented with a rather simple page emulating a terminal for telnet (at some extent). It has the following elements: The current working directory: This is the directory where all commands are being executed. You can use the dropdown-box down the page near the command input to choose a new working directory or use cd command to change the current working directory i.e.: "cd /home/mydir/www" in the Command Input box. To quickly jump towards the root of the filesystem, just click on one of the links on the top to jump to that directory. The Output Here goes the output from your commands. You will be able to scroll through the box if the output is to large to fit inside. In normal conditions, only output to stdout goes into the Output box. This can be rather confusing, because then sometimes you just don't get any output. If you select left enabled "auto stderr trap" when configuring shell.php file, you will get output even if your command repororts an error to stderr so you'll get output most of the time. Anyway, to achive this MyShell has to execute the faulty command twice in case of error, the first time, the usual way, to detect the error and the second one to get the error message using the workarround designed by Martin Geisler: 1> /tmp/output.txt 2>&1; cat /tmp/output.txt; rm /tmp/output.txt It is done by simply appending the arguments to your command. It redirects all output from your command to a file, both stdout and stderr. It then shows the file, and cleans things up when finished. It's quick and dirty, and will only work if you haven't already redirected the output. Most of the time this double execution of faulty commands should not be a problem, anyway you can turn "auto stderr trap" off and select to use it or not at your own will using a checkbox near the "Go!" button that appears when you turn it off. The Command Input box: Here you can type a command, and when you press ENTER or the "Go!" button the command will be executed in the current working directory. You'll discover that most of the time you can work as fast as in any console application because every time the page reloads this input box is autmaticly selected and ready to recive your typing. The Echo Checkbox Sometimes it's usefull to know what command you've just typed in, specially if you've just recived an error from your last command. By default this checkbox is off, but once tou select to turn it on, it will keep on for the rest of the session -until you close your browser screen- or until you check it off again. Cols and Rows Some commands produce wider results, i.e.: `ls -l' on directories with files with long file names. You can change on the fly the width and height of the Output Box to suit your needs just typing the number of columns or rows required. This change will keep on for the rest of the session -until you close your browser screen- or untill you change them again. If you want to recover the defaults cols and rows defined on the shell.php file just let the fields blank and for the next command they'll recover the default sizes. Built-in File Editor You can invoke the MyShell's built-in File Editor using the command you defined when installing MyShell. It defaults to "edit", so in order to invoke File Editor to edit a file called myfile.htm you should type: edit myfile.htm This will open the file's content into the Output box where you can start editing. On the top of the page, you'll find the file's path and info like owner and permissions. Use this information to prevent what will happen when you'll try to save the edited file. You can also invoke editor with a nonexisting file or even without defining a file's name, i.e.: edit nonexistingfile.php In such case, instead of the file's info you'll get a NEW FILE report. Just below the Output Box where you edit the file's contents, there are four buttons: Save: This will save the file with the name defined in the "Save file as: " box below, and will resume the File Editor ready to continue editing. CAUTION: There's not any warning if a file is going to be overwrited and certanly there's no messages like 'are you shure you want to...?'. I asume you know what you are doing. Save and Exit: This will save the file much in the same way of Save but will exit the File Editor to get back to the standar MyShell. Restore Original: This let you recover the original file using a mere type='restore' button function. Cancel/Exit: You can exit the File Editor using this button. Bear in mind that this will make you loose any changes you haven't saved at the moment, and that there's no warning about this. MyShell is a model of obedience. When you say exit, it just do it. Wouldn't be great your girl or boyfriend behaves like this? :-) The Command Input box: You'll find that even though you are running the editor, you are able to see and use the Command Input Box. Actually you can use it as the fastest way to get back to MyShell and exit from the file editor. Just type any command, hit Enter, and MyShell will execute it exiting inmediatly from the File Editor (unless you type the file editor's invoking command in which case File Editor will restart). To keep using over and over again the File Editor, keep this box blank, otherwise File Editor will exit without saving no matter if you clicked any of the Save buttons or simply hited the Enter key. The File Name Box: Below the Comand Input Box, there's a box with the name of the file being edited. This is the file name the File Editor will use the next time you'll try to save your edited file. If you want to save the file over its previous version, then leave it as it is. In case you want to save it with a different name, or give it a brand new name -in case of new files-, you should change it before clicking over any of the Save buttons. Errors while Saving: If you try to save the file over a file or directory in wich you don't have permissions, or into a filesystem with no file space left, etc. you'll recive an error report in the Output Box. To recover your recent changes, step back using the back button in your browser and try to save the file with another name or in another directory/filesystem using the File Name Box. Download -------- You can download PHP Shell from http://www.digitart.net/php/myshell. The MyShell-x.x.x.tar.gz distribution file contains these files: shell.php This is the script you run when you use MyShell. You can rename it for your final installation. ChangeLog This file describe the changes We've made to MyShell. By reading it you'll always know when We've added a new feature or made a bugfix, and the nature of the feature/bugfix. README (This file:-) INSTALL Tells you how to install MyShell. It explains how you can password-protect MyShell - this is very important, or else everybody will be able so snoop into your files and perhaps also be able to delete them! Please take the time to read it carefully. sample.htaccess MyShell has a built in password-protect access that doesn't need any extra file in order to ask you for your username and password. Anyhow, if you prefer to use .htaccess to password-protect MyShell, we've include this template for a .htaccess-file. If you set this up correctly Apache will prompt you for a username and password when you try to access the directory containing MyShell. These file are not required if you use the built in password protection. LICENSE Standard GNU disclamer.