Re-creating AOL Instant Messenger for vintage clients
Sign a 20-year-old AIM client in and watch the buddy list come alive.
One of the first services I wanted back on FlameNet was AIM. I did not want a clone. I wanted a 20-year-old client to sign in and watch the buddy list come alive, sign-on sound and all.
AIM is an AOL trademark. I use the name here to say which software this is about. Nothing in this post is affiliated with AOL.
How a classic client signs on
Classic clients speak a protocol called OSCAR. A client first talks to a login authorizer, which checks the credentials. Then it talks to a BOS server, short for Basic Oscar Service, which handles the buddy list, messaging and presence.
Two steps, two connections. That detail explains the most common failure, which I cover below.
The server
The community reimplemented OSCAR servers. I run Retro Aim Server, which is on GitHub at mk6i/retro-aim-server. Its README says what it is:
- It is written in Go and licensed under MIT.
- It is independent and not affiliated with AOL or Yahoo.
- It supports classic AIM clients 1.x to 7.x and Pidgin.
- It supports TOC1 and TOC2 clients such as gaim and TiK.
- It supports ICQ 98 to 5.
I run it in a container on FlameNet. The README gives no Docker commands, so I will not invent any here. Follow the project’s own instructions to build and start it.
The settings file
Retro Aim Server reads config/settings.env. These keys matter most:
| Key | What it does | Sample value |
|---|---|---|
OSCAR_LISTENERS |
Where the server listens | LOCAL://0.0.0.0:5190 |
OSCAR_ADVERTISED_LISTENERS_PLAIN |
The address clients are told to reconnect to | LOCAL://127.0.0.1:5190 in the guide |
TOC_LISTENERS |
Listener for TOC clients | 0.0.0.0:9898 |
API_LISTENER |
Management API, local only | 127.0.0.1:8080 |
DB_PATH |
The SQLite database file | oscar.sqlite |
DISABLE_AUTH |
Skips password checks and creates users automatically | true |
Those sample values come from the project. Do not copy them without thinking. The port in your file is the port your clients must use, so do not assume 5190.
Do not leave DISABLE_AUTH on
DISABLE_AUTH=true skips password checks and auto-creates users. It exists for development. On a server that anyone can reach, it lets anyone sign in as any screen name. Turn it off before you open the port to other people.
The advertised address
This one cost me time. The advertised address is what the client reconnects to after the first step. If OSCAR_ADVERTISED_LISTENERS_PLAIN holds a value the client cannot reach, sign-on breaks after a good password. The login looks fine, and then the client cannot connect to the BOS server.
So the value must be an address that the client machine can open. A loopback address works only when client and server share a machine. For a remote client, use the server’s reachable name, for example aim.example.com, with the port from your listener setting.
An earlier version of this post called the login server and the authorizer separate things to configure. The login authorizer is the first step of OSCAR, not another component. One server handles both steps, and the advertised address is the handoff between them.
Pointing the old client at your server
Older AIM builds let you override the login server. That is the whole trick. On the sign-on screen:
- Click Setup.
- Open Sign On/Off, then Connection.
- Enter the host and port that match
OSCAR_ADVERTISED_LISTENERS_PLAINinconfig/settings.env.
Enter a screen name and password, and sign on. If the server is up and the address is reachable, the buddy list loads.
Other clients
Pidgin works with the server, as the supported list above says. TOC clients such as gaim and TiK connect through the TOC listener instead of the OSCAR one, so point them at that port, 9898 in the sample file.
Why I bother
Dead infrastructure breathing again is a small thrill. These protocols were elegant: a client asks one server who it is, gets a cookie and a new address, and carries on with another. Running them is a small act of digital preservation.
Grab a client, point it at FlameNet, say hi.