mk6i-open-oscar-server/docs/BUILD.md

Development: How to Run/Compile Open OSCAR Server

This guide explains how to set up a development environment for Open OSCAR Server and build/run the application. It assumes that you have little to no experience with golang.

Dependencies

Before you can run Open OSCAR Server, set up the following software dependencies.

Golang

Since Open OSCAR Server is written in go, install the latest version of golang.

If you're new to go, try Visual Studio Code with the go plugin as your first IDE.

Mockery (optional)

Mockery is used to generate test mocks. Install this dependency and regenerate the mocks if you change any interfaces.

go install github.com/vektra/mockery/v3@latest

Run the following command in a terminal from the root of the repository in order to regenerate test mocks,

mockery

Building the Server Binary

To build the server binary:

go build -o open_oscar_server ./cmd/server

To run the binary with the settings file:

./open_oscar_server -config config/settings.env

Running the Server

This project provides configuration for running with plain sockets and SSL sockets. Choose the mode that best suits your needs.

Plain Socket Config (most common)

To run AIM v1.0-v6.1, you can use the plain socket config (located in config/settings.env) with no additional dependencies.

make run

SSL Socket Config (for AIM v6.2-v7.0)

To run AIM v6.2-v7.0, you must run the server with SSL enabled. This project provides tooling for generating a self-signed certificate and fronting the server with the SSL proxy stunnel.

Note: The stunnel image is pinned to OpenSSL 1.0.2u on purpose. These AIM clients begin the TLS handshake with an SSLv2-format ("v2 hello") ClientHello for backward compatibility, even when they go on to negotiate TLS 1.0. OpenSSL 1.1.0 removed support for parsing this v2 hello, so modern OpenSSL (1.1.x / 3.x) rejects the handshake outright. 1.0.2u is the last release that still accepts it. This is why Dockerfile.stunnel builds its own OpenSSL instead of using the distro package.

Prerequisites

• Git
• Docker Desktop
• Unix-like terminal with Make installed (use WSL2 for Windows)

1. Clone the Repository

git clone https://github.com/mk6i/open-oscar-server.git
cd open-oscar-server

2. Build Docker Images

This builds Docker images for:

• Certificate generation
• SSL termination

• The Open OSCAR Server runtime

  make docker-images
  

3. Configure SSL Certificate

The following creates a self-signed certificate under certs/server.pem.

make docker-cert OSCAR_HOST=ras.dev

Replace ras.dev with the hostname clients will use to connect.

4. Generate NSS Certificate Database

This creates the NSS certificate database in certs/nss/, which must be installed on each AIM 6.2+ client.

make docker-nss

5. Start Open OSCAR Server

Start the server in a terminal.

make run-ssl

6. Start stunnel

In a separate terminal, start stunnel.

make run-stunnel

7. Client Configuration

Certificate Database

Follow the AIM 6.x client setup instructions to install the certs/nss/ database on each client.

Resolving Hostname

If OSCAR_HOST (e.g., ras.dev) is not a real domain with DNS configured, you'll need to add it to each client's hosts file so clients can resolve it.

• Linux/macOS: /etc/hosts
• Windows: C:\Windows\System32\drivers\etc\hosts

Add a line like this, replacing the IP with your server's IP address:

127.0.0.1 ras.dev

Testing

Open OSCAR Server includes a test suite that must pass before merging new code. To run the unit tests, run the following command from the root of the repository in a terminal:

go test -race ./...

Before opening a PR, run the same lint checks used by CI:

make lint

Install golangci-lint locally if the command is not already available on your PATH.

Config File Generation

The config file config/settings.env is generated programmatically from the Config struct using go generate. If you want to add or remove application configuration options, first edit the Config struct and then generate the configuration files by running make config from the project root. Do not edit the config files by hand.

Setting Up Test Clients (optional)

Windows XP is the most convenient OS for running Windows OSCAR clients, which were released across the 1990s, 2000s, and 2010s. An ISO of the most recent version is available on archive.org.

To run Windows XP on your modern machine, install a hypervisor:

• UTM (macOS)
• QEMU w/ KVM (Linux)
• VirtualBox (Windows)