4. Setting Up The Server

4.1. Checking the Stallion driver

FreeBSD has adequate support for modern Stallion cards since 4.4 release. If you are running an older version of FreeBSD, you will need to upgrade to a more modern version of FreeBSD (which you should do anyway, to make sure your system is not vulnerable to known security issues). See the FreeBSD Handbook for information about updating your system.

4.2. Configuring a new kernel

The Stallion driver is not included in the default GENERIC kernel, so you will need to create a kernel config file with the appropriate entries. See stl(4) and the appropriate section of the FreeBSD Handbook.

4.3. Making The Devices

You will need to make the device notes for the Stallion card (which are not made by default). A new version of /dev/MAKEDEV with Stallion support will have been created by the mergemaster run during the above procedure. If you have a Stallion card with more than 8 ports, then you will need to edit /dev/MAKEDEV and change the definition of maxport at about line 250. By default, MAKEDEV only makes device nodes for 8 ports to keep the size of the /dev directory down.

Run a command like:

# cd /dev/ && sh MAKEDEV cuaE0

to create dial-out devices for the first Stallion card. See the comments in MAKEDEV and the stl(4) man page for more details.

4.4. Compiling conserver

Note:

See the section on conserver versions Section 9, “On Conserver Versions”; the version I use is available in the FreeBSD ports collection; however, it is not the only one.)

There are two ways to install conserver. You can either compile from the source or use the FreeBSD ports framework.

4.4.1. Using the ports framework

Using the ports is a bit cleaner, as the package system can then keep track of installed software and cleanly delete them when not being used. I recommend using the comms/conserver-com port. Change into the port directory and (as root) type:

# make DEFAULTHOST=consolehost install

where consolehost is the name of the machine running the console server. Specifying this when the binary is compiled will avoid having to either specify it each time the program is run on remote hosts or having to maintain a conserver.cf file on every host. This command will fetch, patch, configure, compile and install the conserver application.

You can then run make package to create a binary package that can be installed on all the other FreeBSD hosts with pkg_add(1). For extra style points, you can make a two versions of the package: one for the console server machine without a DEFAULTHOST argument, and one for all the other hosts with a DEFAULTHOST argument. This will mean the console client program on the console server machine will default to localhost, which will work in the absence of name servers when the network is busted, and also allow trusted (i.e. no password required) connections via the localhost IP address for users logged into the console server machine (either via the console screen or the emergency backup modem). The version for the other machines with a DEFAULTHOST argument means users can just use the console client without specifying a hostname every time, and without needing to configure the conserver.cf file on every machine.

4.4.2. From the source tarball

If you prefer, you can download conserver and compile it yourself. You might need to do this if you want to install the console client on non-FreeBSD systems. We run the client on our Solaris™ hosts and it inter-operates with the FreeBSD-hosted server with no problems. This allows anyone in the whole company (many of whom have PCs and no FreeBSD host access on their desk) to access the console server.

Download the file from the conserver.com FTP site. Extract it into a handy directory then configure it by running

% ./configure --with-master=consoleserver --with-port=782

The --with-master argument avoids having to specify the master server every time the client is run remotely (or keeping up-to-date config files on all remote hosts). The --with-port argument avoids having to update /etc/services on every machine.

Then type make and, as root, make install.

4.5. Configuring conserver

The conserver program is configured via a file called conserver.cf. This file usually lives in /usr/local/etc and is documented in the conserver.cf(5) manual page.

Our config file looks like this:

LOGDIR=/var/log/consoles
gallows:/dev/cuaE0:9600p:&:
roo:/dev/cuaE1:9600p:&:
kanga:/dev/cuaE2:9600p:&:
%%
allow:  itga.com.au
trusted:        127.0.0.1 buzz

The first line means all the console log files by default go into the /var/log/consoles directory. The & in each line says the log file for that machine will be /var/log/consoles/machine.

The next three lines show three machines to which we need to connect. We use the cuaEx devices rather than the ttyEx devices because console ports typically do not show carrier. This means that opening ttyEx would hang and conserver would never connect. Using the cuaEx device avoids this problem. Another solution would be to use the ttyEx devices and enable soft carrier on these ports, perhaps by setting this using the ttyiEx device in the /etc/rc.serial file. See the comments in this file for more details. Also see sio(4) for information on the initial-state and locked-state devices. (The Stallion driver also supports these conventions). And see the stty(1) for details on setting device modes.

The last section shows that any user logged into the server machine has passwordless access to all consoles. We do this because there are no user accounts on this machine and it is safely isolated from the wide world behind our firewall. The allow line allows anyone on a machine inside our organisation to access the console server if they provide their password, which is recorded in the conserver.passwd file (see next section).

4.6. Setting conserver passwords

The conserver.passwd file contains the encrypted version of the password that each user. The file is documented in the conserver.cf(5) manual page.

The only tricky bit is loading the file with encoded passwords. It appeared in FreeBSD that was is no obvious way to generate an encrypted password for inclusion in another file (but see below). So I put together a quick hack perl script to do this:

@rands = ();
foreach (0..4) {
        push(@rands, rand 64);
}

$salt = join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[@rands];

$salt = '$1$' . $salt . '$';

print 'Enter password: ';
`stty -echo`;
$cleartext = <>;
`stty echo`;
chop($cleartext);
print crypt($cleartext, $salt), "\n";

Note:

This uses the FreeBSD MD5-style encrypted passwords. Running this on other UNIX® variants, or on FreeBSD with DES passwords, will likely need a different style of salt.

Kris Kennaway has since pointed out you can get the same effect using the openssl passwd command:

% openssl passwd -1
Password: password
$1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/

4.7. Starting conserver at system boot time

There are two ways this can be done. Firstly, you could start up conserver from init by including an entry in /etc/ttys that is similar to this:

cuaE0	"/usr/local/sbin/conserver"	unknown	on	insecure

This has two advantages: init will restart the master console server if it ever crashes for any reason (but we have not noticed any crashes so far), and it arranges for standard output of the conserver process to be directed to the named tty (in this case cuaE0). This is useful because you can plug a terminal into this port, and the conserver program will show all console output not otherwise captured by a client console connection. This is useful as a general monitoring tool to see if anything is going on. We set this terminal up in the computer room but visible from the main office. It is a very handy feature. The downside of running conserver from the ttys file is that it cannot run in daemon mode (else init(8) would continually restart it). This means conserver will not write a PID file, which makes it hard to rotate the log files.

So we start conserver from an rc.d script. If you installed conserver via the port, there will be a conserver.sh.sample file installed in /usr/local/etc/rc.d. Copy and/or rename this to conserver.sh to enable conserver to start at boot time.

In fact we use a modified version of this script which also connects conserver to a terminal via a tty device so we can monitor unwatched console output. Our conserver.sh script looks like this:

#!/bin/sh
#
# Startup for conserver
#

PATH=/usr/bin:/usr/local/bin

case "$1" in
        'start')
                TTY=/dev/cuaE7
                conserver -d > $TTY
                # get NL->CR+NL mapping so msgs look right
                stty < /dev/cuaE7 opost onlcr
		echo -n ' conserver'
                ;;

        'stop')
		kill `cat /var/run/conserver.pid` && echo -n ' conserver'
                ;;

        *)
                echo "Usage: $0 { start | stop }"
                ;;

esac
exit 0

Note:

Note the use of cuaE0 device and the need to set tty modes for proper NL-<CR handling).

4.8. Keeping the log files trimmed

FreeBSD has a program called newsyslog that will automatically handle log file trimming. Just add some lines to the configuration file /etc/newsyslog.conf for the console logs:

#
# The log files from conserver
/var/log/consoles/gallows	644  10    1000 *     Z /var/run/conserver.pid
/var/log/consoles/kanga		644  10    1000 *     Z /var/run/conserver.pid
/var/log/consoles/roo		644  10    1000 *     Z /var/run/conserver.pid

This tells newsyslog (which is run from cron every hour on the hour) that the console log files should be archived and compressed once they reach 1Mb, that we should keep 10 of them, and that to signal the server program you send a SIGHUP to the process whose PID is in the conserver.pid file. This is the master server, and it will arrange to signal all the child processes. Yes, this will send a HUP to all clients whenever a single log file needs rotating, but that is quite cheap. See newsyslog(8) for details.

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.