Console Server
Prev |  | Next

# 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; 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 `cuaE`x`` devices rather than the `ttyE`x`` devices because console ports typically do not show carrier. This means that opening `ttyE`x`` would hang and conserver would never connect. Using the `cuaE`x`` device avoids this problem. Another solution would be to use the `ttyE`x`` devices and enable “soft carrier” on these ports, perhaps by setting this using the `ttyiE`x`` 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 `<kris@FreeBSD.org>` 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.

Prev | Home | Next
Our Solution |  | Cabling

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.