<!doctype linuxdoc system>
<article>

<title> The MacTerminal MINI-HOWTO
<author> Robert Kiesling
<date>v1.4, 9 November 1997

<abstract>
This mini HOWTO describes the 1,002nd use for a dead Macintosh (grin):
how to configure the Mac for use as a Linux terminal.  Configurations
using getty and the terminal program kermit are described, as well as
using kermit peer-to-peer networking between between Linux and a
Macintosh.  This document may be reproduced freely, in whole or in
part, provided that any usage conforms to the general copyright notice
of the HOWTO series of the Linux Documentation Project.  See the file
COPYRIGHT for details.  Send all complaints, suggestions, errata, and
any miscellany to <htmlurl url="mailto:kiesling@terracom.net" name =
"kiesling@terracom.net">, so I can keep this document as complete and
up to date as possible.
</abstract>
<toc>
<sect>Introduction.
<P>
This mini-HOWTO should give you some Insanely Great ideas for how to
make your Macintosh work with Linux.  Unfortunately, I have been very
busy, and so I haven't been able to include even half of what I wanted
to include, like using MacTCP and Open Transport to connect to your
Linux box via a PPP line.  That will need to wait for future versions.

This mini-HOWTO doesn't cover networking with LocalTalk and AppleTalk,
either.  I might explore these avenues if there's enough interest in,
say, printing to a LaserWriter printer from Linux.  Otherwise, it
seems to me that such applications, being more trouble than they're
worth (not to mention pricey), are beyond the scope of this document.

I don't plan to cover MkLinux in this document, either.  It's more than
adequately documented elsewhere.  

So if you have ideas for this document, drop me a line at the e-mail
above.  Both systems embody a lot of the beginner's mindset as well as
technical prowess, and in my opinion they don't talk to each other
nearly enough.

<sect>Setting up a serial link.
<P>
To set up a serial link between a Mac and a Linux machine, you will
need, on the Linux side, either a DB9 Female-to-DB25 Male serial cable
or a DB25 Female-to-DB25 Male serial cable, depending on your serial
port.  On the Macintosh side, you will need a DIN9-to-DB25 Male
high-speed modem cable.

Make sure that the cable is labeled a "high speed" cable, because some
older Macintosh cables are configured with their handshaking lines
tied high, which makes them useless for high-speed serial connections.

You will also need a null modem adapter, available at Comp USA, Radio
Shack, and similar outlets, and a DB25 Female-to-DB25 Female serial gender
changer to connect the two serial cables.

I have heard that Mac printer cables are really null modem cables in
disguise, but I can't confirm this.  Some of them are DIN9-to-DIN9
anyway, and wiring one into a serial link would be more trouble than
it's worth.

If this sounds like Greek to you, read the Serial-HOWTO for details of
RS-232 cable configurations and data transmission protocols.

Before connecting the Mac and the Linux machines, you should determine
that you have a working serial port on both machines, either by
connecting a modem and dialing out to another computer with <tt>minicom</tt>
(Linux), ZTerm (Mac), <tt>kermit</tt> (either), or the communications
program of your choice.

The latest version of minicom is available from <htmlurl
url="ftp://sunsite.unc.edu/pub/Linux/apps/serialcomm/dialout"
name="sunsite.unc.edu/pub/Linux/apps/serialcomm/dialout"> and mirror
sites. 

ZTerm is a complete, easy to use comm program.  Unfortunately, it's
shareware.  A current version is available from <htmlurl
url="ftp://mac.archive.umich.edu" name="mac.archive.umich.edu"> and
outlets like it.

The <tt>kermit</tt> program has been ported to every computer and
operating system in existence.  The archives are located at <htmlurl
url="ftp://ftp.columbia.edu/kermit" name="ftp.columbia.edu/kermit">.

You should strongly consider using <tt>kermit</tt> on both machines at
this stage at least, because 1) it's free (although it's not covered
by the Free Software Foundation's General Public License); and 2) it's
a lot less confusing to have <tt>kermit</tt> on both machines than two
completely different communications programs.

If you have another way to determine that the serial ports of the two
machines are operational, feel free to use that.  The point is to ensure
that both machines have working serial ports.

Making the actual serial connection should be easy, given the
directions above.  In case it isn't, the connection looks like this:
<verb>

 Linux PC    DB9- or DB25-  Null     Gender   DIN9-to-       MacBox
 ---------   to-DB25 male   Modem    Changer  DB25 Mac      --------
 |       |   serial cable. |     |  |     |   Serial Cable  |      |
 |       |-----------------|     |--|     |-----------------|      |
 |       |                 |     |  |     |                 |      |
 ---------                  Adapter                         --------

</verb>

<sect>Client-server connection with <tt>kermit</tt>.
<P>
This is the most transient of all the configurations described here.
It requires the least amount of system configuration, although in
operation, it is the more difficult to use of the systems described
here.

In brief, you start <tt>kermit</tt> on both the Linux machine and the
Mac, and place one of them in server mode.  It doesn't matter which
machine is the client ant which is the server, because this is a
peer-to-peer connection.  However, the Linux <tt>kermit</tt> can take
advantage of Linux's superior scripting abilities, so it seems logical
(to me at least) to designate the Linux-side <tt>kermit</tt> as the
server, because this is the more readily automated task.

You should ensure that <tt>kermit</tt> is installed correctly on both
the Mac and the Linux PC.  Follow the instructions in the respective
kermit distributions.  On the Linux machine type <tt>kermit</tt> at
the shell prompt to start it.  You may need root permissions in order
to set the port and baud rate.

<tt>kermit</tt>, the recent POSIX versions for Unices, supports baud
rates up to 115 Kbps.  The more recent Macintosh versions support
serial port speeds up to 57.6 Kbps.  This should be more than
sufficient for any dumb tty-type application, but if you need a
higher-speed connection, you're s.o.l, as far as <tt>kermit</tt> and
serial lines are concerned.  However, <tt>kermit</tt> provides
facilities for communication over a TCP/IP link, but I haven't been
able to test it.  See the alternative in the following sections.  Just
remember, especially on the Mac side, to use a different port for
<tt>kermit</tt> serial connections than your TCP/IP connections,
because Mac <tt>kermit</tt> will rudely hose a serial port that is
already in use.

With that in mind, your <tt>.kermrc</tt> file would contain something
like this:
<verb>
echo Executing site initialization file /usr/local/bin/ckermit.local.ini....
set prompt Chanel3 >
set line /dev/ttyS0
set baud 38400
set send packet-length 2000
set receive packet-length 2000
set block 3
set file type binary
</verb>
Then, in your <tt>&tilde;/.kermrc</tt> file, you would have a line like
<verb>
take /usr/local/bin/ckermit.local.ini
</verb>
On the Macintosh side, set the same communication parameters for bps,
stop bits, parity, and word length.  Some older versions of Mac Kermit
do not support 2k packets, so you might need to set a smaller packet
size.  Howerver, <tt>kermit</tt> sets the communication packet length
based on the receive packet-length setting, so you need to set a shorter
packet size on the Linux end, too.

To actually communicate over the link, you need to enter server mode
on either the Mac or Linux side.  It doesn't matter which.  See the
<tt>kermit</tt> docs for details of server mode.

<sect1>Macintosh resources.
<P>
This is one of the very few <tt>kermit</tt> applications where setting
a <tt>text</tt> file type for transfers is useful.  This is because
Macintosh files have two parts: the <bf>data fork</bf> and the
<bf>resource fork</bf>.  The data fork corresponds to what we in the
Linux world think of as a file: it's the actual data.  The resource
fork contains bitmaps for the icons, keymaps, font specifications, and
the like.  If you transfer a file from Linux to the Mac, the file
won't be recognized as a text file by the Mac, if you use binary mode.

When transferring binary files between the two systems, you should use
the Macintosh <tt>.hqx</tt> BinHex format, which is a 7-bit encoding
of an 8-bit data file.  Mac utilities like BinHexer or StuffIt will
covert the file to its binary form.

If you have a text file which inadvertently ends up as a data-only
file on the Mac, it's likely that it won't even appear in an Open
dialog list box.  What you need to do is open the file with ResEdit,
which is available from <tt>mac.archive.umich.edu</tt>.  ResEdit will
tell you that the file you're opening has no resource fork and then
asks if you would like to add one.  You should answer "Yes" to this
question.  You can then edit the file's Type and Creator by selecting
the Open Special option of the File menu.  All Macintosh text files
are type <tt>TEXT</tt>, so replace the question marks in the Text box
with that.  The Creator code depends on your text editor or word
processor.  Each one is unique, incidentally, and is how the Mac
identifies different apps.  The Creator code for GNU Emacs on the Mac
is <tt>EMAC</tt>, for example.  If in doubt what the creator code of
your text editor or word processor is, use <tt>ttxt</tt>, which is the
creator code for TeachText (which is the Mac equivalent of
<tt>EDLIN.EXE</tt>.)  Then your real word processor or text editor can
translate the file from TeachText to its native type.

There are many other neato things which TeachText can do, so it's
worthwhile to keep it permanently on your Mac.  The book <em>Voodoo
Mac,</em> by Kay Yarborough Nelson, is a good source of tried-and-true
Macintosh tricks that use ResEdit, TeachText, the Finder, and other
overlooked programs.

<sect>Logging in via <tt>kermit</tt>.
<p>
Configuring Linux to use the Mac as a <tt>login:</tt> terminal is even
easier.  <tt>kermit</tt> is ideal for this purpose, because it is one
of the few free communication programs which provides credible
VT100/120/220 emulation.

Essentially, what you want to do is start <tt>kermit</tt> on the
Macintosh side as in the previous section, but rather than issue
server commands, you enter <tt>connect</tt> mode.  This is the normal
terminal emulation mode that most people use, anyway.

On the Linux side, the serial line must be configured with a
<tt>getty</tt> on it to start a <tt>login:</tt> shell.  To do this,
you need to tell <tt>init</tt> that the serial line has a terminal on
it.  In your <tt>/etc/inittab</tt> file you will need a line something
like this:
<verb>
T1:23:respawn:/sbin/getty -L ttyS0 9600 vt100
</verb> 
Be sure to substitute the appropriate serial device for
<tt>/dev/ttyS0</tt> and the correct baud rate for <tt>9600</tt> in the
command line above.

This command tells <tt>getty</tt> to start <tt>login</tt> (the
<tt>-L</tt> switch) on the terminal display, and, when the login times
out, to re-start (<tt>respawn</tt>) the login program until someone
logs in.  If no device is connected to the serial line, or if the
connection is defective, you may see a message on the system console
like: <tt>/dev/ttyS0 respawning too fast: disabling for 5
minutes</tt>.  If this happens, you can return things to normal by (as
root) <tt>kill</tt>ing the <tt>getty</tt> process, or using the
<tt>init q</tt> command.  Both of them have the effect of re-spawning
the <tt>getty</tt> processe(s).  If everything is in order, you should
see the Linux banner and login prompt on the Mac's <tt>kermit</tt>
window.  That's all there is to it.

Also, if you use something besides vanilla <tt>getty</tt>, like
<tt>getty_ps</tt>, the command above will look somewhat different.
The important thing to remember is that everything to the right of
<tt>/sbin/getty</tt> is an argument for <tt>getty</tt> itself; not
<tt>init</tt>.  You should look at the manual pages for
<tt>getty</tt>, <tt>init</tt>,and <tt>inittab</tt> if you have
questions concerning the setup of <tt>init</tt> and <tt>getty</tt>.

The Serial HOWTO provides helpful details on how to configure
<tt>/etc/inittab</tt> for <tt>getty_ps</tt>, if that's what your
system uses.  

To transfer files back and forth between the Macintosh and the Linux
machine, you can (via the Mac's Kermit) issue the <tt>kermit -x</tt>
command to start the Linux <tt>kermit</tt> in server mode.  You can
then use the normal file transfer commands to send files across
the serial line.  It's useful to set a prompt in your
<tt>&tilde;/.kermrc</tt> with a line like
<verb>
set prompt Linux-kermit >
</verb>
Otherwise, remembering which machine you're on can quickly become
confusing.

<sect1>Other Mac terminal programs.
<p>
This method should work equally well for any other Mac terminal
program.  If you have ZTerm, you can use <tt>rz</tt> and <tt>sz</tt>
on the Linux machine to transfer files via the ZModem protocol.  If
Microphone Lite came bundled with your fax modem, that works
equally well, albeit without <tt>kermit's</tt> superior scripting and
configuration facilities.

<sect>Conclusion.
<p>
If you have questions about any of this material, or suggestions for
future directions of Mac-Linux serial-line connectivity, don't
hesitate to drop me a line at <tt>kiesling@terracom.net</tt>.
</article>
