Anyterm

Installation - 1.1 Branch

1. Prerequisites

Anyterm has been known to work with various Linux distributions, FreeBSD, OpenBSD, Mac OS X and maybe Solaris. Development is on Debian GNU/Linux, so if you use a different system you might need to do things a bit differently. If you find any significant differences please let me know and I will add a note to this page. Searching the forum for the name of your operating system or distribution is also recommened.

Anyterm uses some of the Boost C++ libraries. You may already have them on your system; if not, precompiled packages for most systems are available from the usual places. Installing a binary package is advised as Boost takes a long time to compile from source. I'm currently using version 1.34.1; version 1.33 will probably work, but 1.32 or older doesn't. Newer versions will probably work; feedback is welcome.

You need g++, the GNU C++ compiler. Version 3.3 does not work without some hacking; version 3.4 or newer should be OK.

You need GNU Make. Other versions of Make, e.g. the FreeBSD Make, will not work.

2. Download and Unpack

See the download page for instructions on downloading and unpacking the Anyterm source code.

3. Compile the Daemon

In the daemon directory, compile and install:

You should not see any errors or warnings while compiling. If you do see them it may mean that something has gone wrong; please report them in the forums so that they can be investigated, even if everything seems to work.

4. Test a direct connection

To check the basic functionality, start anytermd as follows:

Note that Anyterm will background itself as soon as it starts.

Now visit http://localhost:7777/ with your web browser. With luck you will see a terminal with a shell prompt; you should be able to type commands, use cursor key and control keys, tab completion etc. Applications that use more advanced terminal features may or may not work; "top" and "nano" both work for me. You should see bold and colours where they are used.

Using Anyterm directly like this is not recommended except for local trusted connections because it does not provide any encryption or protection against malicious input. For this reason the --local-only flag was suggested above. For normal use you should configure a proxy to protect Anyterm, as discussed next.

5. Setting up a proxy

We suggest using Apache's mod_proxy between Anyterm and the outside world in order to:

• Provide HTTPS encryption of the communication.
• Provide HTTP AUTH authentication and authorisation of users.
• Perhaps slightly sanitise malicious input before it reaches Anyterm.

The point to remember is that, in contrast to Anyterm, Apache's codebase has been frequently reviwed for security holes. By preventing unauthorised users from having any access to Anyterm by means of HTTP AUTH, you deny them the opportunity to poke at any security holes that Anyterm might have. (Asking for a password within the Anyterm session is not effective since by that time their poisonous HTTP request has already hit the Anyterm daemon.)

Setting up Apache is beyond the scope of this document. In outline, you need to install Apache and install its mod_proxy (which is part of the core Apache distribution). On Debian this is done using "a2enmod proxy_http". You must then add a section to the server configuration to enable proxying, and to sutably protect the proxied address. The following code is an example; refer to the Apache documentation for details.

Note: at the time of writing, this example has not been tested for effectiveness. Feedback is welcome.

6. Using Anyterm with stunnel

Rather than using an http proxy you may prefer to put Anyterm behind an SSL tunnel such as stunnel. This will encrypt the communication, but it will not protect Anyterm from malicious input. Stunnel can be set up as follows:

• Install Stunnel. On Debian, the package is called stunnel4.
• Generate an SSL certificate. The Debian package has a description of how to do this in /usr/share/doc/stunnel4/README.Debian. Something like the following may work, but you should understand the details of what's happening as the security of your system is dependent on it:
$ openssl req -new -x509 -nodes -days 365 -out stunnel.pem -keyout stunnel.pem $ dd if=/dev/urandom of=temp_file count=2 $ openssl dhparam -rand temp_file 512 >> stunnel.pem $ ln -sf stunnel.pem `openssl x509 -noout -hash < stunnel.pem`.0 $ chmod 600 stunnel.pem
• Start the Anyterm daemon, listening for unencrypted HTTP on one port number. Use the --local-only option to prevent unencrypted connections from outside:
$ anytermd -p 8123 --local-only
• Start Stunnel, listening on some other externally-accessible port number and forwarding to Anyterm:
$ stunnel -d 8443 -r 8123 -p stunnel.pem -P ''
• You should now be able to connect to Anyterm at https://example.com:8443/.

7. Specifying the command to run

You can specify the command that Anyterm should run inside its terminal using the -c option. If you want to run a shell interactively, "ssh username@localhost" is a good choice:

Various escape sequences can be used within the command string:

• %h should expand to the hostname of the machine that the user is connecting from, but it's currently broken and isn't much use in the proxied configuration anyway. Get in touch if you need this feature.
• %u expands to the username that the user supplied for HTTP AUTH. One useful application of this is the command 'ssh %u@localhost'. See the section on authentication below for an extra step that's needed to make this work.
• %p expands to a general-purpose parameter supplied from the HTML. If you plan to use this, be aware that it could contain malicious characters that could be interpretted by the shell, such as `.
• %% expands to a single %.

8. Authentication within Anyterm

Anyterm has some very primitive internal support for HTTP AUTH. In general you should not use this but instead place Anyterm behind a proxy that does proper HTTP AUTH. There are two situations where it is useful:

• If you have HTTP AUTH in a proxy and want to use the %u escape inside the command that anyterm runs (see above), the proxy needs to pass the username to Anyterm. This can be achieved by passing the option "--auth=null" to Anyterm: Anyterm will reject requests with no username and password, and the proxy will then forward the credentials to it; it does no further checking.
• If for some reason you aren't using a proxy, despite our encouragement to do so, you can add authentication by hacking the file TrivialAuthenticator to your tastes and then passing "--auth=trivial".

9. Configuring the HTML

If you wish you can make changes to the HTML, Javascript and CSS files in the browser directory to change the appearance of the Anyterm web page.

In particular, you can change the dimensions of the terminal, the number of lines of scrollback and the character set that is used. These settings are all defined near the start of anyterm.html.

These settings are specified here rather than when Anyterm is started because they are per-session rather than global. If you wished you could add some Javascript to let the user choose the size of their terminal for that session before it is opened, for example.

Note that in its basic configuration, the HTML and other files that are sent to the browser are compiled in to the Anyterm executable. You must therefore make any changes to these files before compiling, and re-compile after changing them. An alternative which avoids the need to re-compile is to have the files served by the web server that is acting as proxy; this is described next.

10. Serving the Anyterm static content from your proxy server

If you want to be able to change your HTML and related files without recompiling your Anyterm daemon - and this is a not-unreasonable requirement - the the suggested method is to serve then from the Apache server that is proxying to Anyterm.

Considering the Apache configuration shown above, a request for /anyterm/anyterm.html will be proxied to Anyterm which will return its built-in content. To instead serve that from the proxy server, simply copy (or symlink) the files from the browser/ directory to the directory that corresponds to the URL /anyterm, e.g. /var/www/anyterm, and change the proxy directives as follows:

Now only the subdirectory anyterm/proxy is proxied; you simply need to change the definition of url_prefix at the start of anyterm.js from "" to "proxy/" so that the actual terminal data still goes to Anyterm.

11. Copy and Paste

You may need to adjust your browser's security settings to make the copy and paste buttons at the top of the window fully functional. In IE, just go to Tools -> Internet Options -> Security, select "Custom Level" and enable "Allow paste operations via script". In Mozilla it is more complicated; see this page: http://kb.mozillazine.org/Granting_JavaScript_access_to_the_clipboard. Without changing the security settings a basic two-step paste functionality should still be available, and you can copy using your browser's Edit menu.

One problem with Copy is that the selection will be deselected each time the screen updates. In a similar vein, when pasting you need to be quick when any dialog boxes are presented, as the communication with the server could time out if the dialog box is open for too long.