Log In [secure]
Log In [http]

Anyterm

A Terminal Anywhere

Installation - 1.1 Branch

1. Prerequisites

Anyterm has been known to work with various Linux distributions, FreeBSD, OpenBSD and Mac OS X. 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, but it currently only needs their header files at compile time; it doesn't actually link with any of the libraries at run-time. You may already have these headers on your system; if not, precompiled packages for most systems are available from the usual places. If you choose to use the source from boost.org, note that you don't actually need to compile Boost; just install the headers. I'm currently using version 1.34.1; version 1.33 should work, but older versions won't. Newer versions will probably work; feedback is welcome.

A dependency on zlib, i.e. Debian's zlib1g-dev package, seems to have slipped in recently.

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

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

Compile:

$ make

(If you've compiled anyterm before, note that the directory structure changed slightly in version 1.1.28; you should now make from the top-level directory.)

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.

There's currently no "make install" rule; just copy the anytermd executable to somewhere appropriate.

4. Test a direct connection

To check the basic functionality, start anytermd as follows:

$ anytermd -p 7777 --local-only

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:

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.

<VirtualHost *:443> # HTTPS port ServerName example.com <Location /anyterm> # When someone visits /anyterm they'll be proxied to # Anyterm on port 7676. ProxyPass http://localhost:7676 ttl=60 # There are various parameters that can appear at the end of the # ProxyPass directive to control the maximum number of connections # and so on. See the Apache documentation. ProxyPassReverse http://localhost:7676 # Allow only authorised users AuthType Basic AuthName "example.com" # More Auth directives, depending on where your # usernames & passwords are stored. require valid-user </Location> SSLEngine on SSLCertificateFile /etc/apache2/ssl/example.com.pem </VirtualHost>

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:

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:

$ anytermd -c 'ssh username@localhost'

Various escape sequences can be used within the command string:

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:

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:

<Location /anyterm/proxy> ProxyPass http://localhost:7676 ttl=60 ProxyPassReverse http://localhost:7676 </Location>

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.