Anyterm

Installation

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.

Anyterm uses some of the Boost C++ libraries. Primarily it uses header-only libraries, but it does need to link with libboost_system. You may already have Boost on your system; if not, precompiled packages for most systems are available from the usual places. For example, on Debian you should install libbost-dev and libboost-system-dev.

I'm currently using Boost version 1.61. Most versions should work; 1.58 is reported to work. Feedback about other version compatibility is welcome.

I normally buuld using g++, the GNU C++ compiler; clang++ should also work but is tested less frequently (define CXX to select which to use). I'm currently using g++ version 6.2 and clang++ version 3.8. Older versions should be OK as long as they support C++14, which probably means any g++ version newer than 5.0.

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 the Anyterm source code.

3. Compile the Daemon

Compile:

Please don't compile as root.

Use make -j on a multi-core machine.

You should not see any errors or warnings while compiling. If you do see them it may mean that something has gone wrong; don't ignore them.

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

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 and mod_proxy_html (which are part of the core Apache distribution). On Debian this is done using "a2enmod proxy; a2enmod proxy_http". You must then add a section to the server configuration to enable proxying, and to suitably protect the proxied address. The following code is an example; refer to the Apache documentation for details.

Note: this example has not been reviewed recently. Feedback is welcome.

6. 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 as it will just report the hostname of the proxy. 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 %.

7. Starting Anyterm automatically

You'll probably want to have anytermd start when your server boots, or at least when Apache starts. How to do this will depend on what init system you use; you may also be able to arange for it to be restarted if it terminates unexpectedly. Take care to ensure that anytermd is run as a suitably unprivilidged user.

Here's an example of a possible configuration for systemd for an anytermd instance to run behind an Apache proxy:

Note the need for %% in the command; systemd does its own %-expansion.

On Debian, you would put that file in /usr/local/systemd/system/anytermd.service, and then run "systemctl enable anytermd.service". This creates necessary symlinks in /etc/systemd, and anytermd should be started on boot. Presumably other distributions will be similar if not identical.

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 the normal configuration, these files are compiled in to the Anyterm executable. You must therefore re-compile and restart the daemon after changing them. An alternative which avoids the need to do 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 them from the Apache server that is proxying to Anyterm.

To do this, assuming that your web server location /anyterm corresponds to the directory /var/www/anyterm, update the Apache proxy configuration so that only a subdirectory is proxied:

Now copy (or symlink) the files from the browser directory into /var/www/anyterm, and finally change the definition of url_prefix at the start of anyterm.js from "" to "proxy/".

11. Copy and Paste

(This section is probably out of date.)

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.

12. Persistent Sessions

Often it's desirable to make your Anyterm shell sessions persistent, so that, for example, if you lose your network connection while editting something your changes are not lost.

Anyterm doesn't implement persistent sessions, because I've decided that it's better to use other tools for that job. Specifically, the programs "screen" and "dtach" can be used to run persistent shell sessions that you can connect to and disconnect from.