Apple II Serial Terminal

One of my on-again, off-again, side-projects has been getting my Apple //e setup as a dumb terminal for OS X. I've been tinkering with this for about 9-years now, but never really had a setup I was happy with. I occasionally re-visit the project, but could never dedicate the time to get it right.

In my ideal setup, I wanted one monitor that handles multiple devices (Atari 7800, G5, Apple //e, etc...). For the most part my Dell 20" LCD has served me well, but one source of dissatisfaction with regards to the Apple //e is how it handled the composite video output in 80-column mode. The video would twitch every few seconds which is very annoying and tough to read. About a week ago, the display started to fail. The screen would go black after several minutes of use. I suspect that the inverter is failing, but don't want to just throw $100 at a hunch. For $150, I decided to replace it with a 22" 1080p HDTV instead of a new monitor, primarily because of the variety of inputs available. One happy coincidence of getting the new display is that 80-column mode now displays perfectly, which gave me the inspiration to revisit perfecting the Apple //e terminal project.

The second source of dissatisfaction came from Mac OS X. In general, I love OS X, but serial terminal support isn't exactly one of it's primary functions. Apple has either disabled or excluded necessary software to achieve this. Typically, to setup a serial login on a *NIX system you would add a line similar to the following to /etc/ttys:

tty.KeySerial1 "/usr/libexec/getty std.9600" vt100 on local secure

However, just doing this in OS X gets you nothing.

As it turns out in OS X, login_tty can only be invoked by the launchd process. There are MANY examples of getting a serial terminal running in OS X, and they all get hung up here and resort to using the "screen" command to get a serial terminal running. This is what I have done in the past, and what I have been searching to resolve. It's clunky, and requires intervention on the Mac before you can connect from the Apple. I just want to boot the //e, and get a login prompt without entering commands into the Mac first.

Eventually, I found a solution to my problem here:

http://www.club.cc.cmu.edu/~mdille3/doc/mac_osx_serial_console.html

In the Unix world, getty is the program that presents a login prompt. In earlier versions of Mac OS, one could add the appropriate line to /etc/ttys and have a prompt appear on a serial port. It appears that as of 10.6, this is no longer possible.

Instead, I found that creating a script to spawn the getty that is run by launchd does the trick. Note that running the getty on the command line appears to fail because the login_tty syscall can only be invoked by the init process (which on Mac OS is launchd). I therefore created a file called serialconsole.plist (name it as you wish) in /Library/LaunchDaemons/ containing the following:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key>Label</key>
        <string>serialconsole</string>
        <key>ProgramArguments</key>
        <array>
                <string>/usr/libexec/getty</string>
                <string>std.115200</string>
                <string>tty.usbserial-FTCCBMZ3</string>
<!--            <string>tty.PL2303-0000201A</string> -->
        </array>
        <key>KeepAlive</key>
        <true/>
</dict>
</plist>

Note that first bit sets the daemon name, the second bit sets the program arguments (one "string" per argument), and the last bit (keepalive) instructs launchd to restart the daemon when it exits (eg, the user logs out of the console). The first program argument is the getty program to execute, the second is the relevant line in /etc/gettytab that defines the desired serial port configuration (in this case the typical 115200 baud, 8 data bits, no parity, 1 stop bit; "8N1"), and the third argument to getty must be the name of the serial port device in /dev, which for the two devices I had were one of the two listed.

I installed the script (which I modified to reflect 9600 baud instead of 115200), rebooted the G5, booted the Apple //e from the Modem.MGR work disk (and set my baud rate, parity, and entered terminal mode), and I received a login prompt from the G5. Success! Or, so I thought... I proceeded to enter my credentials and received an error:

PAM ERROR (Cannot make/remove an entry for the specified session)

Sigh... back to research mode... I did a bit more searching and found my answer here:

http://www.puredarwin.org/users/users 

Thanks to Apple's Damien Sorresso on the launchd-dev mailing list for providing the answer to this. login needs a new security session created for it before it can set it up for the new user. This is what sshd does for in-coming users, and what loginwindow.app does for GUI users under OS X. For the moment, a small PAM module (pam_sessioncreate, available on the Downloads page) can be added to /usr/lib/pam/ and to /etc/pam.d/login just above pam_launchd ("session required pam_sessioncreate.so") to create the necessary session. The file should now include:

[...]

password    required    pam_deny.so

session     required    pam_sessioncreate.so    <- data-blogger-escaped-here="here" data-blogger-escaped-inserted="inserted" data-blogger-escaped-line="line" data-blogger-escaped-new="new" data-blogger-escaped-span="span">

session     required    pam_launchd.so

[...]

So, again I followed directions and downloaded the pam_sessioncreate.so file to /usr/lib/pam on the G5, modified /etc/pam.d/login adding the appropriate line, rebooted everything, tried again and was FINALLY able to login successfully on the Apple //e.

One anticipated side-effect of this project is that the Keyspan serial port is now monopolized. It is always in use by Getty waiting for a connection, which prevents me from using ADT (Apple Disk Transfer) to transfer disk images to the Apple //e and writing them to floppy. As a result, I am adding an additional phase to this project. To resolve the latest problem, I am going to install a second USB-Serial adapter to the G5, and use an A/B serial swich box to switch between them. I plan to start by getting the second adapter working with a direct connection, then add the additional cables and switch box later. I'll post my results in a future update...

Project Notes:

Commands used to start a terminal session after booting the ModemMGR work disk:

• Boot from Modem.MGR work disk
• Esc-M to set Baud Rate: 9600
• Esc-J to set parity: 8-1-None
• Esc-: to set Terminal: VT220
• Press enter and you should get a logon prompt.

Websites I referenced:

• http://pdw.weinstein.org/2007/06/apple-hacking-for-fun-and-profit.html
• http://www.club.cc.cmu.edu/~mdille3/doc/mac_osx_serial_console.html
• http://www.puredarwin.org/users/users
• http://www.puredarwin.org/downloads

Hardware and Software used:

• Apple //e
• SuperSerial card (set to modem, not printer)
• Null Modem cable
• Keyspan USB-Serial adapter
• Modem.MGR
• ADT (Apple Disk Transfer - To copy the Modem.MGR disk image from the G5 to 5.25" floppy via serial transfer)
• PowerMac G5
• Mac OS X 10.5.8