<!-- $FreeBSD$ -->

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Console Server</title>
    <link rel="stylesheet" href="./itgastyle.css">
  </head>

  <body>
    <h1>Console Server</h1>

    <h2>The Problem</h2>

    <p>You have a computer room with lots of Unix server machines and
      lots of comms hardware.  Each of these machines needs a serial
      console.  But serial terminals are hard to find and quite
      expensive (especially compared to a much more capable PC).  And
      they take up a lot of precious space in the computer room.</p>

    <p>You need access to the console because when things break, that
      is where error messages go.  And some tasks have to be done on
      the console (e.g. boot problems or OS installs/upgrades).  Some
      Unix systems allow the console to break out to the ROM monitor
      which can sometimes be the only way to unstick a hung machine.
      This is often done with a LINE BREAK sent on the console serial
      port.</p>

    <p>If we are going to play about with consoles, then there are a
      couple of other things that would be great:</p>

    <ul>
      <li>
      <p>Remote access.  Even in the same office, it would be
        convenient to access all the consoles from your desk without
        walking into the computer room.  But often the machines are
        off-site, perhaps even in another country.</p></li>

      <li>
      <p>Logging.  If something has gone wrong, you would like to be
        able to have a look at the previous console output to see
        what is up.  Ordinary console screens give you the last 25
        lines.  More would be better.</p>

      <li>
      <p>Network Independence.  The solution needs to work even if the
        network is down.  After all, a failed network is when you need
        consoles the most! Even better is network independence with
        remote access.</p></li>

      <li>
      <p>No single-point failure.  A console system that crashes every
        machine when it fails is no use.  This is particularly tricky
        with Sun Unix hosts as they will interpret a powered-off
        terminal as a BREAK, and drop back to the ROM monitor.</p></li>

      <li>
      <p>Interface with a pager or some similar alerter
        device.</p></li>

      <li>
      <p>Ability to power-cycle machines remotely.</p></li>

      <li>
      <p>Not be <em>too</em> expensive.  Free is even better!</p></li>
    </ul>

    <h2>Possible Solutions</h2>

    <p>If you use PC hardware for your servers, then a so-called
      "<em>KVM switch</em>" is one possible solution.  This allows the
      use of a single <em>K</em>eyboard, <em>V</em>ideo screen and
      <em>M</em>ouse for multiple boxes.  This cuts down on the space
      problem, but only works for PC hardware (not any comms gear you
      might have), and is not accessible from outside the computer
      room.  Nor does it have much scroll-back or logging, and you
      have to handle alerting some other way.  The big downside is
      that it will not work for serial-only devices, such as
      communications hardware.  This means that even with a room full
      of PC-based servers, you are probably still going to need some
      sort of serial console solution. [Actually, Doug Schache has
      pointed out that you <em>can</em> get KVM switches that also do
      serial consoles or Sun-compatible KVM switching as well as PCs,
      but they are expensive.  See <a
      href="http://www.avocent.com/">Avocent</a> for example.]</p>

    <p>You might be tempted to do without a console terminal, but when
      things go pear-shaped you <em>really</em> need to see what is on
      the console.  And you have to use the console to boot the
      machine and do things like OS upgrades or installs.</p>

    <p>You might try having a single console terminal and switching
      from server to server as needed, either with a serial switch or
      just by patching it into the required machine.  Serial switches
      are also hard to come by and not cheap, and may cause problems
      with sending BREAK when they switch.  And (if your computer room
      is anything like ours) you never seem to have the right
      combination of patch leads to connect to the machine you need
      to, and even if the leads are there you can never work out
      exactly which combination of DTE/DCE headshells goes with which
      lead goes with which hardware.  So you spend the first 10
      minutes fooling around with breakout boxes and a box of leads,
      all while the server is down and the users are screaming.  Of
      course this does not deal with the logging or remote access
      requirements.  And inevitably the console is not switched to the
      machine you need so you lose all the console messages that might
      tell you what is going on.</p>

    <p>One popular solution is to use terminal server hardware.
      Typically, the serial ports are connected to the various machine
      consoles, and set up for "reverse telnet" access.  This means a
      user can telnet to a given IP/port and be connected to the
      appropriate console.  This can be very cost-effective, as
      suitable old terminal servers can be picked up fairly cheaply
      (assuming you do not have a couple lying around).  And it is of
      course network-accessible so suitable for remote access.  But it
      suffers from one major drawback: if the network is down, then
      you have <em>no</em> access to any console, even if you are
      standing right next to the machine.  (This may be partially
      alleviated by having a suitable terminal connected to one of the
      terminal server ports and connecting from there, but the
      terminal server software may not support that.)  Also there is
      no logging or replay of console messages.  But with a bit of
      work, and the addition of some software such as <a
      href="http://www.conserver.com/">conserver</a> (described below),
      this can be made to work pretty well.</p>

    <p>A possibility suggested by Bron Gondwana is similar to the
      above solution.  If you use servers with multiple serial ports,
      you can connect each spare serial port to the console port of
      the "next" server, creating a ring of console connections (in
      some sort of order).  This can be made to work reasonably well
      with the aid of the <a
      href="http://www.conserver.com/">conserver</a> software, but can
      be a bit confusing otherwise (i.e. remembering which port is
      connected to which console).  And you are stuck if you need to
      use serial ports for other things (such as modems) or you have
      machines without spare ports.</p>

    <p>Or, if your budget exceeds your willingness to hack, you can
      buy an off-the-shelf solution.  These vary in price and
      capability.  See, for example, <a
      href="http://www.lightwavecom.com/">Lightwave</a>, <a
      href="http://www.perle.com/">Perle</a>, <a
      href="http://www.avocent.com/">Avocent</a> or <a
      href="http://www.blackbox.com/faxbacks/23000/23362.PDF">Black
      Box</a>.  These solutions can be quite expensive - typically
      $USD100 - $USD400 per port.</p>

    <h2>Our Solution</h2>

    <p>In light of the above requirements, we chose a solution based
      on a dedicated PC running Unix with a multiport serial card, and
      some software designed to handle serial consoles.</p>

    <p>It includes the following elements:</p>

    <ul>
      <li><p>A surplus PC.  We used a Pentium 166, with a PCI bus,
        2Gbyte hard disk and 64Mb of RAM.  This is a massive overkill
        for this task, and P-100, 500Mb, 32Mb would be more than
        enough.</p></li>

      <li><p>A PC Unix system.  We used <a
        href="../../../../index.html">FreeBSD 4.3</a> as that is used
        for other tasks within our office.</p></li>

      <li><p>A multi-port serial card.  We chose the <a
        href="http://www.stallion.com/html/products/easyio.html">EasyIO-PCI</a>
        8-port card from <a href="http://www.stallion.com/">Stallion
        Technologies</a>.  This cost us about $AUD740, or under
        $100/port, from <a href="http://www.ht.com.au/">Harris
        Technologies</a> (which has lots of stuff but is by no means
        the cheapest place in town - shop around and you might get it
        a lot cheaper.)  This card has a big DB80 connector on the
        back, and a cable plugs into that which has a block with 8
        RJ-45 sockets on it.  (We chose the RJ-45 version as our
        entire cable plant is RJ-45.  This allows us to patch
        connections from the required box to the console server
        without any special cables.)  This is the only thing we needed
        to buy to make this all happen.</p></li>

      <li><p>We build two servers, one for each computer room, with 8
        ports in one and 16 ports (via two EasyIO-PCI cards) in the
        other.  If we needed more than 16 ports, then another of the
        Stallion cards would be more cost-effective.  We could
        conceivably support 128 ports in each server (with 2
        EasyConnect 8/64 host cards and 8 16 port RJ-45 modules) for
        about $AUD12,000.</p></li>

      <li><p>A modem for remote access to the console server host when
        the network is down.  We have not done this yet as the computer
        room is next door, but when we put a server in Sydney we will
        add the modem.  The idea is that when the network is down, you
        can dial up and log into the server machine and run the
        console program locally.  For security, we will probably leave
        the modem powered off and ask the gopher in Sydney to turn on
        the well-labelled button when we need it.</p></li>

      <li><p>A program called <a
        href="http://www.conserver.com/">conserver</a>.  This program
        does all the magic required to enable remote access to
        consoles, and do the replaying and logging etc.  It comes in
        two parts: a server called <code>conserver</code> that runs as
        a daemon and connects to the serial ports, handles logging
        etc, and a client program called <code>console</code> that can
        connect to the server, display console messages, send
        keystrokes (and BREAKs) etc.</p></li>
    </ul>

    <p>This design covers all the major requirements except remote
      power cycling:</p>

    <ul>

      <li><p>Remote access comes because the <code>console</code>
        client program works across the network.</p></li>

      <li><p>Logging is handled by the <code>conserver</code>
        program.</p></li>

      <li><p>If the network is down, then we can use the console on
        the PC to run the <code>console</code> client locally.  For
        remote sites, we can add a modem for dial-in access to the the
        server command line to run the client.</p></li>

      <li><p>By patching the Solaris servers (see <a
        href="#solaris">below</a>), we can avoid pranging the whole
        computer room when the console server PC crashes (or the power
        supply fails, or whatever).</p></li>

      <li><p>We already have pager alerts from another system we have
        installed, but the console server has all the required log
        info so that could easily be implemented if we needed.  And it
        even has a modem for calling the pager company!</p></li>

      <li><p>We do not currently support remote power cycling.  Some
        versions of the conserver program support this, but it does
        require specialised serial-controlled power boards.  We have
        no immediate need for remote power cycling (we have a gopher
        in each remote office who can do it by remote control) so this
        is not a major problem, and we could add it easily should we
        ever see the need and get the appropriate hardware.</p></li>

      <li><p>This solution was very cheap.  Total cost for the 9-port
        server was $AUD750 for the IO card, as we re-used a surplus PC
        and already owned the hardware for the special cables.  If we
        had to buy everything, then it would still only cost around
        $AUD1500 for the 8-port server.</p></li>
    </ul>

    <h2>Setting Up The Server</h2>

    <h4>Patching the Stallion driver</h4>

    <p>The only hitch with setting up the server PC is getting the
      device drivers for the Stallion card.  FreeBSD has supported
      Stallion ISA cards for many years, but unfortunately the driver
      has not been actively maintained for some years, and does not
      support the newer Stallion cards (such as the EasyIO-PCI card or
      some of the other ISA cards with newer UART chips).  I have put
      together a <a href="stal-jumbo-patch">patch file</a> for FreeBSD
      4.3 (based on the work of many other people) that will update
      the system to support these newer cards.  Hopefully, this patch
      will be committed to the FreeBSD tree in time for the 4.4
      release.  If you are running FreeBSD 4 from prior to this time,
      you will need to download and apply this patch (instructions are
      included at the top of the patch file).  If you are running
      FreeBSD 3, then you had probably best upgrade.</p>

    <h4>Configuring a new kernel</h4>

    <p>The Stallion driver is not included in the default
      <samp>GENERIC</samp> kernel, so you will need to create a kernel
      config file with the appropriate entries.  See the
      <samp>stl(4)</samp> man page and the appropriate section of the
      <a
      href="../../../../doc/en_US.ISO8859-1/books/handbook/kernelconfig.html">FreeBSD
      Handbook</a>.</p>

    <h4>Building World</h4>

    <p>After applying the patch you will certainly need to update the
      whole system, including all the user programs and the kernel.
      See the documentation in <samp>/usr/src/UPDATING</samp> and the
      <a href="http://www.FreeBSD.org/handbook/makeworld.html">FreeBSD
      Handbook</a>.</p>

    <h4>Making The Devices</h4>

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

    <p>Run a command like</p>
<pre>
	cd /dev/ && sh MAKEDEV cuaE0
</pre>

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

    <h4>Compiling conserver</h4>

    <p>(See the section on Conserver versions <a
      href="#conserver-versions">below</a>; the version I use is not
      the one available in the FreeBSD ports collection.)</p>

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

    <h5>Using the port framework</h5>

    <p>Using the ports framework is a bit cleaner, as the package
      system can then keep track of installed software and cleanly
      delete them when not being used.  Download the port framework
      from <a href="conserver-port.tar.gz">here</a>, unpack it to
      create a directory called <code>conserver-port</code>.  CD to
      that directory and (as <code>root</code>) type</p>

<pre>
	make DEFAULTHOST=<em>consolehost</em> install
</pre>

    <p>where <em>consolehost</em> 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
      <code>conserver.cf</code> file on every host.  This command will
      fetch, patch, configure, compile and install the conserver
      application.</p>

    <p>You can then run <samp>make package</samp> to create a binary
      package that can be installed on all the other FreeBSD hosts
      with the <samp>pkg_add</samp> command.  For extra style points,
      you can make a two versions of the package: one for the console
      server machine without a <samp>DEFAULTHOST</samp> argument, and
      one for all the other hosts with a <samp>DEFAULTHOST</samp>
      argument.  This will mean the console client program on the
      console server machine will default to <samp>localhost</samp>,
      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 <samp>DEFAULTHOST</samp> argument means users can just
      use the <samp>console</samp> client without specifying a
      hostname every time, and without needing to configure the
      <samp>conserver.cf</samp> file on every machine.</p>

    <h5>From the source tarball</h5>

    <p>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.</p>

    <p>Download the file from the <a
      href="ftp://ftp.conserver.com/conserver/conserver-7.0.2.tar.gz">conserver.com
      FTP site</a>.  Extract it into a handy directory then configure
      it by running</p>

<pre>
	./configure --with-master=<em>consoleserver</em> --with-port=782
</pre>

    <p>The <code>--with-master</code> 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
      <code>--with-port</code> argument avoids having to update
      <code>/etc/services</code> on every machine.</p>

    <p>Then type <code>make</code> and, as root, <code>make
      install</code>.</p>

    <h4>Configuring conserver</h4>

    <p>The conserver program is configured via a file called
      <code>conserver.cf</code>.  This file usually lives in
      <code>/usr/local/etc</code> and is documented in the <a
      href="conserver.cf.html"><code>conserver.cf(5)</code></a> man
      page.</p>

    <p>Our config file looks like this:</p>
<pre>
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
</pre>
    <p>The first line means all the console log files by default go
      into the directory <code>/var/log/consoles/</code>.  The
      <samp>&</samp> in each line says the log file for that machine
      will be <samp>/var/log/consoles/</samp><em>machine</em>.

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

    <p>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 <code>conserver.passwd</code> file (see next
      section).</p>

    <h4>Setting conserver passwords</h4>

    <p>The <code>conserver.passwd</code> file contains the encrypted
      version of the password that each user.  The file is documented
      in the <a
      href="conserver.cf.html"><code>conserver.cf(5)</code></a> man
      page.</p>

    <p>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:</p>

<pre><![ CDATA [/*
@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";
]]></pre>

    <p>(Note that 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.)</p>

    <p>Kris Kennaway has since pointed out you can get the same effect
      using the <samp>openssl passwd</samp> command:</p>

<pre>
$ openssl passwd -1 
Password: &lt;password&gt;
$1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/
$ 
</pre>

    <h4>Starting conserver at system boot time</h4>

    <p>There are two ways this can be done.  Firstly, you could start
      up conserver from init by including an entry in /etc/ttys that
      looks a bit like this:</p>

<pre>
cuaE0	"/usr/local/sbin/conserver"	unknown	on	insecure
</pre>

    <p>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 STDOUT 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 would continually restart
      it).  This means conserver will not write a PID file, which makes
      it hard to rotate the log files.</p>

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

    <p>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:</p>

<pre>
#!/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
</pre>

    <p>(Note the use of cuaE0 device and the need to set TTY modes for
      proper NL->CR handling).</p>

    <h4>Keeping the log files trimmed</h4>

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

<pre>
#
# 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
</pre>

    <p>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
      the newsysylog(8) man page for details.</p>

    <h2>Cabling</h2>

    <p>This is always the hardest part of this kind of problem!!  We
      had only a dozen or so cables/headshells to build, and we
      already had a collection of the appropriate crimping tools and
      hardware, so we did it ourselves.  But if you are not set up for
      this, or you have a large number of cables to make, then you
      might consider getting some cables custom made.  Look in the
      yellow pages, there are a surprising number of places that do
      this!  Getting custom-made cabling is good, and you can get much
      more professional results, but can be expensive.  For example,
      the RJ-45 to DB-25 adapter kits described below are about $10
      each; custom-made headshells are about twice that (and take a
      couple of weeks to arrive).  Similarly, crimping custom RJ-45 to
      RJ-45 leads is quite cheap (say, $5 each) but it takes a fair
      amount of time.  Custom made RJ-45 socket to RJ-45 plug
      converters cost about $25 each.</p>

    <p>We have settled on RJ-45 Cat-V cabling for all our office and
      computer room cabling needs. This included patching between
      racks in the computer room.  For serial connections, we use
      patchable headshells that have RJ-45 sockets on the back.  This
      allows us to patch whatever RJ-45 - DB-25 connections we need.</p>

    <p>Which is just as well, because there are many incompatible ways
      to represent serial connections on the RJ-45 plug.  So the
      cabling has to be very careful to use the right mapping.</p>

    <h4>RJ-45 colors</h4>

    <p>RJ-45 cables and plugs have 8 pins/conductors.  These are used
      as 4 matched pairs.  There are a couple of conventions about how
      the pairs are mapped onto pins, but 100baseT uses the most
      common (known as EIA 586B).  There are three common color-coding
      conventions for the individual conductors in RJ-45 cables.  They
      are:</p>

    <table>
      <tr class="alt">
        <th>Pin</th>
        <th>Scheme 1</th>
        <th>Scheme 2 (EIA 568B)</th>
        <th>Scheme 3 (EIA 568A)</th>
        <th>Pair</th>
      </tr>
      <tr>
        <td>1</td>
        <td>Blue</td>
        <td>White+Green</td>
        <td>White+Orange</td>
        <td>2+</td>
      </tr>
      <tr class="alt">
        <td>2</td>
        <td>Orange</td>
        <td>Green</td>
        <td>Orange</td>
        <td>2-</td>
      </tr>
      <tr>
        <td>3</td>
        <td>Black</td>
        <td>White+Orange</td>
        <td>White+Green</td>
        <td>3+</td>
      </tr>
      <tr class="alt">
        <td>4</td>
        <td>Red</td>
        <td>Blue</td>
        <td>Blue</td>
        <td>1+</td>
      </tr>
      <tr>
        <td>5</td>
        <td>Green</td>
        <td>White+Blue</td>
        <td>White+Blue</td>
        <td>1-</td>
      </tr>
      <tr class="alt">
        <td>6</td>
        <td>Yellow</td>
        <td>Orange</td>
        <td>Green</td>
        <td>3-</td>
      </tr>
      <tr>
        <td>7</td>
        <td>Brown</td>
        <td>White+Brown</td>
        <td>White+Brown</td>
        <td>4+</td>
      </tr>
      <tr class="alt">
        <td>8</td>
        <td>White<br>or Grey</td>
	<td>Brown</td>
	<td>Brown</td>
	<td>4-</td>
      </tr>
    </table>

    <p>Note EIA 468A and EIA 568B are very similar, simply swapping
      the colors assigned to pair 2 and pair 3.</p>

    <p>See for example the <a
      href="http://www.cabletron.com/support/techtips/tk0231-9.html">Cabletron
      Tech Support Site</a> for more details.</p>

    <p>The pins in the RJ-45 plug are numbered from 1 to 8.  Holding a
      patch lead with the cable pointing down and the clip away from
      you, pin 1 is at the left.  Or, looking into an RJ-45 socket
      with the clip to the top, pin 1 is on the right.  The following
      illustration (shamelessly lifted from the Cabletron web site
      above) shows it pretty well:</p>

    <img alt="RJ45" src="tk0231-9-1.png">

    <p>We have four classes of equipment to deal with in our setup:</p>

<dl>

<dt>Sun Servers
<dd>

    <p>Sun servers operate as DTE (i.e. send data on TxD and read RxD,
      and assert DTR) with a female DB-25 socket on board.  So we need
      to create a headshell for the Stallion that operates as DCE and
      has a male DB-25 plug (i.e. acts as a <em>null modem</em> cable
      as well as converts from RJ-45 to DB-25).  We use headshells
      that have an RJ-45 socket in them and 8 short flyleads with
      DB-25 pins on the end.  These pins can be inserted into the
      DB-25 plug as required.  This allows us to create a custom
      RJ-45-DB-25 mapping.  We used a couple of different sorts,
      including the <a href="http://www.molexpn.com.au/">MOD-TAP</a>
      part no. <a
      href="http://www.molexpn.com.au/products/index.nsx/1/7/0/0/id=340">06-9888-999-00</a>
      and the <a
      href="http://www.blackbox.com/faxbacks/12000/12654.PDF">FA730
      series</a> from <a href="http://www.blackboxoz.com.au/">Black
      Box</a>.</p>

    <p>On our version of the headshells, these flyleads had the
      following colours (from Pin 1-8): Blue, Orange, Black, Red,
      Green, Yellow, Brown, White.  (Looking into an RJ-45 socket,
      with the clip towards the top, pin 1 is on the right.)  This is
      how they are connected to the DB-25 socket:</p>

    <table>
      <tr class="alt">
        <th>Stallion RJ-45 Pin</th>
        <th>Colour</th>
        <th>Signal</th>
        <th>Sun DB-25 Male Pin</th>
        <th>RS232 Signal</th>
      </tr>
      <tr align=center>
        <td>1</td>
        <td>Blue</td>
        <td>DCD</td>
        <td>20</td>
        <td>DTR</td>
      </tr>
      <tr align=center class="alt">
        <td>2</td>
        <td>Orange</td>
        <td>RTS</td>
        <td>5</td>
        <td>CTS</td>
      </tr>
      <tr align=center>
        <td>3</td>
        <td>Black</td>
        <td>Chassis Gnd</td>
        <td>1</td>
        <td>Chassis Gnd</td>
      </tr>
      <tr align=center class="alt">
        <td>4</td>
        <td>Red</td>
        <td>TxD</td>
        <td>3</td>
        <td>RxD</td>
      </tr>
      <tr align=center>
        <td>5</td>
        <td>Green</td>
        <td>RxD</td>
        <td>2</td>
        <td>TxD</td>
      </tr>
      <tr align=center class="alt">
        <td>6</td>
        <td>Yellow</td>
        <td>Signal Gnd</td>
        <td>7</td>
        <td>Signal Gnd</td>
      </tr>
      <tr align=center>
        <td>7</td>
        <td>Brown</td>
        <td>CTS</td>
        <td>4</td>
        <td>RTS</td>
      </tr>
      <tr align=center class="alt">
        <td>8</td>
        <td>White</td>
        <td>RTS</td>
        <td>8</td>
        <td>DCD</td>
      </tr>
    </table>

    <p>Note that colours may be different for your cables/headshells.
      In particular, pin 8 may be grey instead of white.</p>

    <p>Remember to label the headshell <em>clearly</em>, in a way that
      will not fade/fall off/rub off with time!</p>

<dt>Cisco 16xx/26xx/36xx Routers
<dd>

    <p>I think that all Cisco gear that has RJ-45 console ports and
      runs IOS will have the same cable requirements.  But best to
      check first.  We have tried this on 1600s and 2600s only.</p>

    <p>Both the Stallion card and the 2600 have RJ-45 connections, but
      of course they are not compatible.  So you need to crimp up a
      special RJ-45-RJ-45 cable.  And this cable must be plugged in
      the right way round!  We use normal RJ-45 flyleads from the
      router to the patch panel, then the special flylead from the
      patch panel to the Stallion card.</p>

    <p>We built two special Stallion-Cisco leads by cutting in half a
      2m flylead and crimping an RJ-45 with the appropriate pinouts to
      each free end.  The original connector will be the Cisco end of
      the cable, the new crimped connector will be the Stallion end.
      Holding the RJ-45 connector on the flylead with the cable
      pointing down and the clip pointing away, this is the order of
      the colours of the cables in our flylead (pins 1-8, from L to
      R): white/green, green, white/orange, blue, white/blue, orange,
      white/brown, brown.  For the Stallion end, trim and discard the
      brown/white+brown and green/white+green pairs.  Then holding the
      RJ-45 plug in the same manner (cable down, clip away), the
      connections should be (from L to R): None, None, Blue, Orange,
      White/Orange, White/Blue, None, None, as shown:</p>

<table>
<tr class="alt"><th>Cisco RJ-45 Pin<th>Colour<th>Cisco Signal<th>Stallion RJ-45
Pin<th>Stallion Signal</tr>
<tr align=center><td>1<td>White/Green<td>RTS<td>N/C<td>&nbsp;</tr>
<tr align=center class="alt"><td>2<td>Green<td>DTR<td>N/C<td>&nbsp;</tr>
<tr align=center><td>3<td>White/Orange<td>TxD<td>5<td>RxD</tr>
<tr align=center class="alt"><td>4<td>Blue<td>Gnd<td>3<td>Gnd</tr>
<tr align=center><td>5<td>White/Blue<td>Gnd<td>6<td>Gnd</tr>
<tr align=center class="alt"><td>6<td>Orange<td>RxD<td>4<td>TxD</tr>
<tr align=center><td>7<td>White/Brown<td>DSR<td>N/C<td>&nbsp;</tr>
<tr align=center class="alt"><td>8<td>Brown<td>CTS<td>N/C<td>&nbsp;</tr>
</table>

    <p>Note again that colours may be different for your cables/headshells.</p>

    <p>Carefully label the cable, and each end of the cable, and test
      it.  If it does not work, testing is <em>really</em> hard as they
      do not make RJ-45 serial line testers!</p>

    <p>Let me state this more stongly: Be <em>very</em> <b>VERY</b>
      sure that you label this cable in a way that is easily,
      instantly and permanently recognisable as a special cable and
      not easily confused with normal drop cables.  Some suggestions
      (from Hugh Irvine):</p>
<ul>
<li> Make them out of different coloured cable

<li> For marking the ends, clear heat-shrink tubing slipped over
printed labels *before* putting on the connectors is the best way I have
seen for marking what they are.

<li>You can also use Panduit or similar tags that 
you put on with nylon tie straps, but I find the ink wears off the 
tags.
</ul>

<p>

<dt>Cisco Catalyst switches 
<dd> 

Astoundingly, the pinout on the console ports of the Catalysts is
actually <em>different</em> to the pinout used on the 26xx-series
Cisco hardware.  I think the way to tell which is which is by
considering the operating software.  If it uses IOS, then the previous 
pinout is required.  If it uses the switch software, then this pinout
is required.

    <p>Fortunately, while the pinouts are different, the Catalyst
      pinout is simply a mirror image of the pinout for the 2600.
      Even more fortunately, the Ciscos (both Catalysts and 2600s)
      seem to ship with a special "rollover" cable, which is exactly
      what is required in this case.  We use the rollover cable from
      the Catalysts to the patch panel, then the same cable as above
      for the 2600s from the patch panel to the Stallion card, and it
      all works just fine.</p>

    <p>This rollover cable is an RJ-45-RJ-45 cable and is intended to
      be used with the shipped (hardwired) RJ-45 - DB-25 and RJ-45 -
      DB-9 headshells for console connections.  Ours are 2m long,
      either light blue or black, and are quite flat.  Attempts to use
      them for 100baseT ethernet will fail miserably!  You can tell it
      is a rollover cable by holding both ends with the cable pointing
      down and the clip pointing away from you.  Check the colour of
      the leads in each pin in the two connectors, they should be
      mirror images. (In our case, one goes
      grey-orange-black-red-green-yellow-blue-brown, the other
      brown-blue-yellow-green-red-black-orange-grey).  This is a
      rollover cable.</p>

    <p>If you do not have a rollover cable present, then you can use
      the same cable as for the 26xx except plug it in the other way
      around (i.e. original 8-pin plug goes into the Stallion, the new
      crimped plug with only 4 active wires goes into the Catalyst).</p>

<p>

<dt>FreeBSD Servers (or any other i386 PC systems using a serial console)
<dd>

    <p>We run FreeBSD 4 on a couple of i386 PCs for various peripheral
      uses.  FreeBSD usually uses a screen and keyboard for the
      console, but can be configured to use a serial port (usually the
      first serial port known as COM1 in DOS/Windows or ttyd0 in
      Unix).</p>

    <p>The cabling for these servers depends on the PC harware.  If
      the PC has DB-25 female socket on board (as most older PCs do),
      then the same headshell as works for the Sun server above will
      work fine.  If the PC has DB-9 male plug on board (as more
      recent PCs tend to do), then there are two choices.  Either use
      a DB-9 to DB-25 converter (this is not recommended as it can
      lead to unreliable connections over the long term as the adapter
      is bumped/works loose), or build an RJ-45 to DB-9 cable as
      follows:</p>

<table>
<tr class="alt"><th>Stallion RJ-45 Pin<th>Colour<th>Signal<th>PC DB-9 Female
Pin<th>RS232 Signal</tr>
<tr align=center><td>1<td>Blue<td>DCD<td>4<td>DTR</tr>
<tr align=center class="alt"><td>2<td>Orange<td>RTS<td>8<td>CTS</tr>
<tr align=center><td>3<td>Black<td>Chassis Gnd<td>N/C<td>&nbsp;</tr>
<tr align=center class="alt"><td>4<td>Red<td>TxD<td>2<td>RxD</tr>
<tr align=center><td>5<td>Green<td>RxD<td>3<td>TxD</tr>
<tr align=center class="alt"><td>6<td>Yellow<td>Signal
Gnd<td>5<td>Signal Gnd</tr>
<tr align=center><td>7<td>Brown<td>CTS<td>7<td>RTS</tr>
<tr align=center class="alt"><td>8<td>White<td>RTS<td>1<td>DCD</tr>
</table>
See <a href="#freebsd">below</a> for tips on configuring FreeBSD to
use a serial console.
</dl>



    <h2><a name="solaris">On Sun Systems And Break</a></h2>

    <p>Anyone who has turned off a terminal used as a console for a
      Sun system will know what happens and why this is a problem.
      Sun hardware recognises a serial BREAK as a command to halt the
      OS and return to the ROM monitor prompt.  A serial BREAK is an
      out-of-band signal on an RS-232 serial port that involves making
      the TX DATA line active (i.e. pulled down to less than -5v) for
      more than two whole character times (or about 2ms on a 9600bps
      line).  Alas, this BREAK signal is all to easily generated by
      serial hardware during power-on or power-off.  And the Stallion
      card does, in fact, generate breaks when the power to the PC
      fails.  Unless fixed, this problem would mean that every Sun box
      connected to the console server would be halted whenever the
      power failed (due to dead power supplies, or fat-fingered
      operators unplugging it, or whatever).  This is clearly not an
      acceptable situation.</p>

    <p>Fortunately, Sun have come up with a set of fixes for this.
      For Solaris 2.6 and later (and perhaps earlier, but who was
      crazy enough to run 2.5??), the <code>kbd(1)</code> command can
      be used to disable the ROM-on-BREAK behaviour. This is a good
      start, but leaves you out of luck in the situation where a break
      is needed to get into a broken machine.</p>

    <p>Starting with Solaris 8, the <code>kbd</code> command can also
      be used to enable an alternate break sequence using the
      <samp>kbd -a alternate</samp> command.  When this is set, the
      key sequence &lt;Return&gt;&lt;Tilda&gt;&lt;control-B&gt;
      (within 5 seconds) will drop to the ROM.  You can enable this
      permanently by editing the <code>/etc/default/kbd</code> file;
      see the <code>kbd(1)</code> man page.  Note that this alternate
      break sequence is only active once the kernel has started
      running multiuser and processed the default file.  While the ROM
      is active (during power-on and during the boot process) and
      while running single-user, you still need to use a BREAK to get
      to the ROM prompt.  The console client can cause the server to
      send a BREAK using the escape sequence "^Ecl1" (i.e. escape, c,
      ell, one).</p>

    <p>If you have a Sun software support contract, there are patches
      available for Solaris 2.6 and 2.7 that add the"alternate break"
      capability integrated into Solaris 2.8.  Solaris 2.6 requires
      patch 105924-10 or higher. Solaris 2.7 requires patch 107589-02
      or higher.</p>

    <p>We have added this patch to all our Solaris 2.6 servers, and
      added it (and the entry in the /etc/default/kbd file) to our
      jumpstart configuration so it will automatically be added to
      every new install.</p>

    <p>We have confirmed by direct testing that neither the Cisco
      16xx, 26xx, or Catalyst hardware suffers from the BREAK sent
      when the Stallion card loses power.</p>

    <h2><a name="freebsd">Using a Serial Console on FreeBSD</a></h2>

    <p>The procedure for doing this is described in detail in the <a
      href="../../../../doc/en_US.ISO8859-1/books/handbook/serialconsole-setup.html">FreeBSD
      Handbook</a>.  This is a quick summary.</p>

    <h4>Check the kernel configuration</h4>

    <p>Check that the kernel configuration file has <samp>flags
      0x10</samp> in the config line for the <samp>sio0</samp> device.
      This signals this device (known as <samp>COM1</samp> in
      DOS/Windows or <samp>/dev/ttyd0</samp> in FreeBSD) can be used
      as a console.  This flag is set on the <samp>GENERIC</samp> and
      <samp>LINT</samp> sample configs, so is likely to be set in your
      kernel.</p>

    <h4>Create the <samp>/boot.conf</samp> file</h4>

    <p>This file should be created containing a single line containing
      just "-h".  This tells the FreeBSD boot blocks to use the serial
      console.</p>

    <h4>Edit <samp>/etc/ttys</samp></h4>

    <p>Edit this file and make the following changes.</p>

    <p>If you are not going to have any keyboard/video screen on this
      server at all, you should find all the lines for
      <samp>ttyv0</samp> through <samp>ttyv8</samp>:</p>

<pre>
ttyv1   "/usr/libexec/getty Pc"         cons25  on  secure
</pre>

    <p>Change the <samp>on</samp> to <samp>off</samp>.  This will stop
      login screens being run on the useless video consoles.</p>

    <p>Find the line containing <samp>ttyd0</samp>.  Change it
      from</p>

<pre>
ttyd0   "/usr/libexec/getty std.9600"   dialup  off secure
</pre>

    <p>to</p>

<pre>
ttyd0   "/usr/libexec/getty std.9600"   vt100   on secure
</pre>

    <p>(replacing <samp>vt100</samp> with the term type of your
      console.  <samp>xterms</samp> might be a good choice).  This
      allows you to log in to the console port once the system is
      running multi-user.</p>

    <p>Reboot and away you go!</p>

    <h2>Security Implications</h2>

    <p>The client-server protocol for <code>conserver</code> requires
      the user of the <code>console</code> client to enter a password.
      This password is passed across the net in <em>cleartext!!!</em>
      This means <code>conserver</code> is not really suitable for use
      across untrusted networks (such as the Internet).  Use of
      conserver-only passwords (in the <code>conserver.passwd</code>
      file) slightly mitigate this problem, but anyone sniffing a
      conserver connection can easily get console access, and from
      there prang your machine using the console break sequence.  For
      operating across the Internet, use something secure like
      <em>SSH</em> to log into to the server machine, and run the
      console client there.</p>

    <h2><a name="conserver-versions">On Conserver Versions</a></h2> 

    <p>The <code>conserver</code> program has fractured into a number
      of versions.  The home page referenced above seems to be the
      latest and most featureful version around, and carries a version
      number of "7.0.2".  This is maintained by Bryan Stansell (<a
      href="mailto:bryan@conserver.com">bryan@conserver.com</a>), who
      has brought together the work of many people (listed on his
      webpage).</p>

    <p>The FreeBSD ports collection contains a port for version 8.5 of
      conserver.  This seems to be older and less featureful than the
      7.0.2 version (in particular, it does not support consoles
      connected to terminal server ports and does not support a
      <code>conserver.passwd</code> file), and is written in a fairly
      idiosyncratic manner (using a preprocessor to generate C code).
      Version 8.5 is maintained by Kevin S Braunsdorf (<a
      href="mailto:ksb+conserver@sa.fedex.com">ksb+conserver@sa.fedex.com</a>)
      who did most of the original work on conserver, and whose work
      Bryan Stansell is building on.  The 8.5 version does support one
      feature not in the 7.0.2 version (controlling power to remote
      machines via a specific serial-interfaced power controller
      hardware).</p>

    <p>As shipped with FreeBSD, the 8.5 version does not authenticate
      against FreeBSD servers using MD5 passwords.  There is a patch
      in the FreeBSD GNATS system (<a
      href="http://www.FreeBSD.org/cgi/query-pr.cgi?pr=28432">ports/28432</a>)
      that fixes this problem.  Kevin has indicated this patch will be
      included in future versions of conserver from him.  There are a
      couple of other problems with the 8.5 version as well.</p>

    <ul>
      <li><p>It is hard to rotate log files, as <code>conserver</code>
        does not create a PID file and killing the parent conserver
        process does not kill the children (which have the logfiles
        open).</p></li>

      <li><p>Compiling it (on anything other than FreeBSD) is a pain
        because it depends on a couple of other large programs to
        compile.  This is because it is not written in C but in a
        macro language that produces C code, and so depends on these
        macro processors.  The intent of this macro language is to
        hide system dependencies.  The 7.0.2 version uses GNU
        configure for the same task, and compiling this version on
        Solaris is a breeze.  (Compiling 8.5 is easier on FreeBSD as
        the ports framework takes care of all this for you).</p></li>

      <li><p>After compiling on Solaris, the <code>console</code>
        program would not authenticate against the
        <code>conserver</code> program on FreeBSD, because it used
        <code>getpass()</code> on Solaris that silently truncates
        passwords to 8 characters.  FreeBSD uses MD5 passwords that
        can be (and in our case, are) longer than 8 characters.</p>

      <li><p>There was some confusion about the role of "groups" in
        <code>conserver</code>.  When replaying log messages in 8.5,
        it seemed to replay messages from all consoles in the group,
        whereas 7.0.2 seems to do the obvious thing and keep output
        from individual consoles separate.  (This may well have just
        been boneheaded setup mistakes on my part however.)  The
        upshot was that the 8.5 version needed a new group (and
        process) per console, whereas the 7.0.2 version will happily
        support multiple ports per process.</p></li>
    </ul>


    <H2>Links</h2>

    <p><a href="http://www.conserver.com/">Homepage</a> for the latest
      version of conserver.</p>

    <p><a
      href="ftp://ftp.conserver.com/conserver/conserver-7.0.2.tar.gz">FTP</a>
      the conserver 7.0.2 source tarball.</p>

    <p><a href="http://www.stallion.com/">Stallion Technologies</a> homepage.</p>

    <p>David Harris' <a
      href="http://www.conserver.com/consoles/msock.html">Minor Scroll
      Of Console Knowledge</a> contains heaps of good information on
      serial consoles and serial comms in general.</p>

    <p>His <a href="http://www.conserver.com/consoles/">Greater Scroll
      of Console Knowledge</a> contains evern more specific info on
      connecting various devices to various other devices.  Oh the
      joys of standards!</p>

    <p>Doug Hughes has <a
      href="http://www.eng.auburn.edu/users/doug/console.html">a
      similar console server</a> based on the <samp>screen</samp>
      program and an old SunOs host.</p>

    <p>The <a href="http://www.realweasel.com/">Real Weasel</a> company
      makes a ISA or PCI video card that looks like a PC video card
      but actually talks to a serial port.  This can be used to
      implement serial consoles on PC hardware for operating systems
      that can not be forced to use serial console ports early
      enough.</p>

    <h2>Files</h2>

    <a href="stal-jumbo-patch">Stallion Jumbo Patch for FreeBSD 4
      (unzipped, 400k)</a><br> The same <a
      href="stal-jumbo-patch.gz">Stallion Jumbo Patch for FreeBSD 4
      (gzipped, 140k)</a><br>

    A FreeBSD <a href="conserver-port.tar.gz">port framework</a> for
      conserver 7.0.2.<br> The <a href="conserver-port.shar">Port
      framework as a SHAR file</a><br>

    <h2>Man Pages</h2>

    <a href="console.html">console(8)</a><br>
    <a href="conserver.html">conserver(8)</a><br>
    <a href="conserver.cf.html">conserver.cf(5)</a><br>

    <h2>Change Log</h2>

<dl>
<dt>10 July, 2001
<dd>Initial version announced on FreeBSD and Sage-AU mailing lists.

<dt>12 July, 2001
<dd>
<ul>
<li>Notes on some commercial console servers from Doug Schache.
<li>Grrr.  Fixed the pinout for the Cisco - Stallion RJ-45 cable.
The cable would have worked but was backwards.  The new table now
reflects the description.
<li>Noted that Catalyst cable is a 26xx cable plugged in the othyer
way around.
<li>Added notes about RJ-45 pin numberring and color coding
conventions
<li>Added notes about serial console on FreeBSD/i386 platforms.
<li>Now in RCS.
</ul>

<dt>13 July, 2001
<dd>
<ul>
<li>Notes on cable marking from Hugh Irvine
<li>Notes on custom-made cables, source for headshells
</ul>

<dt>18 July, 2001
<dd>
<ul>
<li>Links to Black Box adapters
<li>Fix dates.  It's July, already!
<li>Pointers to commercial solutions and serial-port-on-other-server setup
<li>Pointer to "openssl passwd" command
</ul>

</dl>

    <hr>
    <address><a href="mailto:gnb@itga.com.au">Gregory Bond</a></address>
<!-- Created: Wed Jul  4 12:35:02 EST 2001 -->
<!-- hhmts start -->
Last modified: Thu Jul 19 10:19:28 EST 2001
<!-- hhmts end -->
<br>
$Id: article.sgml,v 1.5 2001-10-31 23:10:30 chern Exp $

  </body>
</html>
