Chapter 11. Miscellaneous Tools

11.1.1. Automating Documentation

This book has assumed that you are familiar with tools like telnet, rlogin, and X Windows. To use these tools effectively, you'll want to be able to record or log your activities from time to time. Arguably, one reason documentation is so often flawed is that it is usually written after the fact. This is often done from memory or an incomplete set of notes several days after changes have been made. While the best time to write documentation is as you go, often this simply isn't possible. When your network is down and management is calling every five minutes asking if it's fixed yet, you probably won't be pausing to write much down.

There are a few things you can do to help simplify writing documentation after the fact. First, get copious printouts at every stage, preferably with some kind of time and date stamp. When a production system is down, it is not the time to worry about the cost of paper. Several commands you are probably already familiar with may be easy to overlook with the stress of dealing with a dead system.

If you are using X Windows, you can use the xwd command to capture windows. To use this command, in an xterm window, type:

bsd1# xwd -out xwdfile

You can then click on the window you want to capture. In this example, the file xwdfile will be created in the current directory. The file can be examined later or printed using tools such as xv or gimp. Be sure to give these files meaningful names so that you can sort things out later.

If you are using a text-based interface and are interested in capturing the output of a single command, you may be able to use the tee command. This command allows you to send output from a command to both the screen and a file. For example, the following command will display the output of the command arp -a on the screen and write it to the file outfile:

bsd1# arp -a | tee outfile

The tee command may require special measures to work. For example, you must use the option -l with tcpdump if you want to use tee. An example was given in Chapter 5, "Packet Capture". As with xwd, you should be careful to use meaningful filenames, particularly if you are capturing windows on the fly.

An alternative to tee is script. It can be used to capture the output of a single command or a series of commands. To capture a series of commands, you start script and then issue the commands of interest. For example, the following command will create the file scriptfile and return to the system prompt:

bsd1# script scriptfile
Script started, output file is scriptfile

Everything that is displayed on your terminal will be logged to the file scriptfile. One advantage of logging a series of commands is that you can embed documentation into the file as you go. Simply type the comment character for your shell, and everything else you type on the line will be ignored. For example, with the Bourne shell, you might type something like:

bsd1# #Well, the foo program didn't work.  \
>Let's try the bar program.

The "\" character was used to continue the comment on a new line.

When you are done logging a session, type exit or press Ctrl+D as in:

bsd1# exit

Script done, output file is scriptfile

You can now print or edit the file as desired.

One option that is often overlooked is to include a command with the script command. For example:

bsd1# script scriptfile ifconfig -a

will run the program ifconfig -a, writing the output to the file scriptfile and displaying the output on the screen as well. This file will include two time and date stamps, one at the beginning and one at the end of the file.

You should be aware of a few problems with using script. First, the file can get very big very quickly. This shouldn't be much of a problem unless you are pressed for disk space, but it can be painful to read after the fact. Second, it is all too easy to lose the file. For example, if a system crashes or is halted, the file may be lost in the process. Third, commands that directly control the screen such as vi tend to fill the output file with garbage. Finally, since a new shell is started by script, environmental changes made while script is running may be lost.

If you are connecting to a remote system using a variant of telnet, you may be able to log the session or print the screen. This is particularly true for PC implementations of telnet. See the documentation for the version you are using.

11.1.2. vnc

vnc, short for virtual network computing, was developed by what is now the AT&T Laboratories at Cambridge. vnc is actually a pair of programs. One is a server, which generates and sends the local display's contents to another computer. The other is a viewer, which reconstructs the server's display. You use the computer running the viewer program to control the remote computer running the server program. An application, for example, would actually be running on the server's CPU but controlled by the station running the viewer.

The program's implementation is based on the concept of a remote frame buffer (i.e., remote video display memory). The server maintains the frame buffer, a picture of the server's display, and sends it to the viewer. The viewer recreates the display on the local host. The updates to the remote frame buffer may be the complete contents of the frame buffer or, to minimize the impact on bandwidth, just what has changed since the last update.

In a Unix environment, vnc provides a way to deliver an X Windows session to a host that may not support a native X Windows connection. On the surface, a vnc connection probably seems a lot like an X Windows connection. There are, however, some fundamental differences. vnc is designed so the viewer is a very thin client. Unlike an X Windows, almost no work is done at the viewer, and the client software is stateless. And vnc is freely available on some non-Unix systems where X Window isn't.

vnc can run in one of two modes. In view only mode, the screen is displayed, but the viewer is not given control of the server's mouse or keyboard. If view only mode is not selected, the viewer will share control of the mouse and keyboard. Please note, the mouse and keyboard will not necessarily be disabled at the server.

To use vnc in a Unix environment, telnet to the remote computer and start the vnc server with the vncserver command. The first time you run it, it will create a .vnc directory under your home directory and will query you for a connection password that will be used for all future sessions. (You can change this with the vncpasswd command.)

lnx1$ vncserver

You will require a password to access your desktops.

Password:
Verify:

New 'X' desktop is lnx1.lander.edu:1

Creating default startup script /home/jsloan/.vnc/xstartup
Starting applications specified in /home/jsloan/.vnc/xstartup
Log file is /home/jsloan/.vnc/lnx1.lander.edu:1.log

The command returns an address or hostname and a display number for the newly created display, in this instance lnx1.lander.edu:1. (Alternately, you could start the vnc server while seated at the machine and then go to the client. This will be necessary if you want to run the server on a Microsoft Windows platform.)

Next, connect a viewer to the display. To start the viewer on a Unix system, start an X Window session and then use the vncviewer command with the host and display number returned by the viewer program as an argument to the command. By default, vncserver uses the twm X Window manager, but this can be reconfigured.[39] If you are used to all the clutter that usually comes with gnome or something similar, the display may seem a little austere at first but will perform better. The basic functionality you need will be there, and you will be able to run whichever X programs you need.

[39]To change the window manager, edit the file xstartup in the .vnc directory. For example, if you use gnome, you would change twm to exec gnome-session.

vnc starts a number of processes; you'll want to be sure that they are all stopped when you are done. You can stop vnc with the -kill option as shown here:

lnx1$ vncserver -kill :1
Killing Xvnc process ID 6171

Note that you need to specify only the display number, in this case :1. You should also be aware that this sometimes misses a process on some systems. You may need to do a little extra housekeeping now and then.

Once running, vnc supports sending special keystroke combinations such as Ctrl-Alt-Del. If both systems support it, you can cut and paste ASCII data between windows.

vnc also provides a reasonable level of security. Once the password has been set, it is not transmitted over the network. Rather, a challenge response system is used. In addition to the password, the Microsoft Windows version of vncserver can be configured to accept connections from only a specific list of hosts. It can also be configured to use a secure shell (SSH) session. The default port can be reassigned to simplify configuration with firewalls.

The viewer and server can be on the same or different machines or can even be used on different architectures. vnc will run on most platforms. In particular, the viewer will run on just about any Microsoft Windows machine including Windows CE. It will run under an X Window session, on Macintoshes, and as plug-ins for web browsers. vnc is available in Java, and the server contains a small web server that can be accessed by some Java-aware browsers. To do this, you simply add 5800 to the window number for the HTTP port number. In the previous example, the window was :1, so the HTTP port number would be :5801, and the URL would be http://lnx1.lander.edu:5801.

There is substantial documentation available at the AT&T Laboratories web site, http://www.uk.research.att.com/vnc.

11.1.3. ssh

One of the problems with telnet, rlogin, rsh, and the like is a lack of security. Passwords are sent in clear text and can be easily captured by any computer they happen to pass. And with the r-services, it can be very easy to mimic a trusted system. Attach a laptop to the network, set the IP address appropriately, and there is a good chance you can mimic a trusted host.

One alternative is ssh, written by Tatu Ylönen, a replacement for the r-services that uses encryption. While the original version is free, with Version 2 ssh has evolved into a commercial product, marketed by SSH Communications Security, Inc. However, Version 2 is freely available for academic and noncommercial use. Recently, the OpenSSH project, a spin-off of the OpenBSD project, released a free port that is compatible with both versions of ssh and is covered by the standard BSD license.

ssh is actually a set of programs that uses encryption to both authenticate users and provide encrypted sessions. It provides four levels of authentication, ranging from trusted users and systems, like rsh and rlogin, to RSA-based authentication. By doing host authentication as well as user authentication, DNS, IP, and route spoofing attacks can be circumvented.

On the downside, ssh provides minimal protection once your systems have been compromised. Version 1 of the SSH protocol has also been compromised by man-in-the-middle attacks when incorrectly configured. Also, some of its authentication methods can be relatively insecure. ssh is not trivial to configure correctly, but fortunately, there is a fair amount of documentation available for ssh, including two books devoted exclusively to ssh. If you need particularly robust security, pay close attention to how you configure it or consider Version 2.

The legality of ssh is yet another question. Since encryption is sometimes the subject of peculiar laws in some countries, using or exporting ssh may not be legal. The OpenBSD and OpenSSH projects avoid some of these problems by developing code outside of the United States. Consequently, the distribution of their code is not subject to the United States' peculiar munitions export laws since it can be obtained outside the United States.

Despite these concerns, ssh is something you should definitely consider if security is an issue.