Oberon/ETH Oberon/QEMUinstall

Installing ETH Oberon using the QEMU Hypervisor

This method has proven successful in installing ETH Oberon to a variety of laptop and desktop machines including a Micron Trek 2, AGP laptop. The instructions can be adapted to other virtual machines.

After installation and configuration on a storage medium, the system can be used routinely on a native machine. Alternatively, use can continue on the virtual machine. In the native case, a network connection will be over Ethernet or a serial crossover cable. In the virtual machine case, a network connection uses a TAP or bridge interface connected to the host system.

Terminology

Installation host is the machine where installation is performed using the hypervisor.
Target machine is the machine where ETH Oberon is to be used after installation is completed. This can be the bare x86 PC or a hypervisor presenting an x86 PC environment.
Target storage device or Target device is the device where Oberon is to be installed and used. When ETH Oberon works on the hypervisor, any device it supports can be used. When ETH Oberon works directly on the bare machine, devices are limited to available device drivers. Consequently, for ETH Oberon on the bare machine, a disk drive or Compact Flash card connected by PATA or a USB flash store connected by OHCI will work. With ETH Oberon lacking drivers for SATA, UHCI, EHCI and xHCI, devices with these interfaces will not work on the bare machine. QEMU supports most devices.
Target volume is a volume of a partitioned target device.

Generalities

To illustrate, the following example refers to QEMU running on Linux with installer /home/me/OberonCF0.Dsk. Device names are illustrative. Do not attempt to use an example verbatim. Adapt to your requirement.

In the installation host, the target device has a name such as /dev/sdX where X is "b" or "c" or some other letter. Alternatively, it might have a SYMLINK name assigned with a udev rule. A name such as /dev/KingstonCF for example.

KERNEL=="sd?", ATTR{size}=="1018080", SYMLINK+="KingstonCF"

Where systemd is used, the name can be assigned by a systemd .link file.

The Oberon0 installer uses PATA device names. A target device may be IDE0 with target volume IDE0#05. Again, these are examples only. In another case, the device can be IDE1 with volume IDE1#02.
CAUTION: a typographical error in the device identifier can allow catastrophic damage to the file system of the installation host. Identify devices carefully. Type carefully.

Hardware

Specific hardware is addressed in the Hardware Compatibility List.

If the target machine is not the installation host, move the target device to the installation host. In most cases the target device will connect via a 40 or 44 conductor ribbon cable. A 44 pin laptop drive can be connected to a desktop machine using an adapter. ETH Oberon has limited support for USB and the installation may not succeed for a USB target device. That includes a USB flash drive and a disk drive or memory card connected by a USB adapter.

Storage

In this installation method, ETH Oberon requires a dedicated target volume of the target device. In Linux, a volume can be created with fdisk, parted or gparted. In other systems, other disk manipulators are available. For the complete stock ETH Oberon system on a PC, at least 50 MiB should be allocated; 100 MiB will simplify operations during installation and maintenance. Typically, user specific working files will be in a separate volume mounted with a name such as FAT, HOME, usr or WORK.

Installation Package	Zip archive kB	Unzipped kB
Oberon0	1475	2667
Apps1	800	2304
Apps2	1015	2849
Docu	2770	6118
Gadgets	1086	2914
Pr3fonts	205	655
Pr6fonts	375	1877
Source1	1012	4000
Source2	779	3245
Source3	841	3559
Build	920	2364
SourceB	189	727
System	633	1735
Totals	12100	35014

Display

By direct inspection or by using software, determine the display capabilities of the target machine. In Linux, lspci identifies most video hardware. In addition to the video chipset, knowledge of the VESA BIOS Extensions can be helpful.

Hypervisor

Install QEMU on the host where the installation process is to be performed. Complete system emulation is used. In Debian jessie install the qemu-system-x86 package.

Installer Image

Retrieve an Oberon0 installer image file from Sourceforge. OberonCF0.Dsk includes support for Compact Flash and is recommended. Oberon0.Dsk, also there, is the last image published at ETH. It lacks support for CF; otherwise the two images are identical.

Installer Execution

Start the installer. Access to drives requires root authority. Log in as root or use sudo.
CAUTION: "sdc" and "KingstonCF" are illustrative. Adjust according to your specific requirement. This command is for root executing the installer image in file OberonCF0.Dsk.

qemu-system-i386 \
 -drive file=/home/me/OberonCF0.Dsk,if=floppy,format=raw \
 -drive file=/dev/KingstonCF,if=ide,format=raw \
 -boot order=a

This for a real diskette, write-protected.

qemu-system-i386 \
 -drive file=/dev/fd0,if=floppy,format=raw,readonly \
 -drive file=/dev/KingstonCF,if=ide,format=raw \
 -boot order=a

Risk of damage to a file system in the installation host is mitigated by QEMU restricting access to devices specified in the qemu command. Refer to the QEMU manual page in the installation host or online or to the QEMU manual. Access to a host drive is also discussed in a Linux Suse page. If "format=raw" is omitted, QEMU will produce an error message.

Trial and error may be necessary to establish correct parameters. A shell function can be helpful.

etho () { qemu-system-i386 \
 -drive file=/home/me/OberonCF0.Dsk,if=floppy,format=raw \
 -drive file=/dev/KingstonCF,if=ide,format=raw \
 -boot order=a ; }

Oberon0 Installer Usage

The Oberon0 installer after executing Partitions.Show detail ~. Oberon0 is running on a virtual x86 PC provided by QEMU in Debian Wheezy.

Oberon0 will present a sequence of commands, each of which can be executed with a click of the middle mouse button. Text is selected by dragging with the right mouse button. Consult the original installation instructions for details.

1. Select a disk driver ...

MM on Config.Disk for chosen driver.

2. Select and prepare the partition:

Open InstallFiles.Tool with MM on Edit.Open. Type the option "detail" and execute Partitions.Show detail ~. The intended target volume should be visible in the partition table displayed. In the present example the target volume is IDE0#05; not IDE0#00. Sensible type codes should appear in the fifth column. The type code for the whole target device and for each unallocated area will be "---". Any other volume should have a numerical type code. If "---" appears in the fifth column, the installer failed to read the partition table of the target device properly and successful installation will be impossible. In this case, exit QEMU, correct the problem and try again.

3. Finish Configuration:

Open Configure.Tool with MM on Edit.Open. Choose a display mode according to the previously established information. If no chipset-specific driver is suitable, set a VESA mode. In case the chosen mode fails, another mode is easily tested.

Record the configuration by following instructions in Part 2.

To leave the installer, type and execute System.Quit or use <Ctrl>+<Alt>+<G> to release the mouse pointer and then use QEMU > Machine > Quit.

Testing and Troubleshooting

If the hypervisor (QEMU) supports the configured video, the newly installed system can be tested directly.

qemu-system-i386 \
  -drive file=/dev/KingstonCF,index=1,media=disk,format=raw \
  -vga std -boot order=c

Otherwise test in the target machine. If installation was successful and configuration was correct, ETH Oberon will appear momentarily. Otherwise, refer to troubleshooting instructions. The discussion under Partition management with Oberon, subheading "Troubleshooting a boot problem with this command" is also relevant. To revise the video configuration, run QEMU again and mount the target volume. In this example MM on

FileSystem.Mount DST AosFS IDE0#05 ~

MM on

Edit.Open Configure.Tool

try another

Config.Display ...

and MM on

Config.BootPartition menu ~

again. If using VESA video, test again under the hypervisor. The BIOS might allow booting from a device other than the primary master. Where the drive is installed in the machine as IDE1 and is recognized in the installer as IDE0 the value for the BootVol config string can be edited when the machine boots. To troubleshoot a more difficult problem, record a trace in a file.

qemu-system-i386 \
 -hda file=/dev/KingstonCF,index=1,media=disk,format=raw \
 -serial file:QemuOberonTrace \
 -vga std -boot order=c,menu=on

Boot option "menu=on" allows interaction. After grabbing the QEMU screen, set <Scroll Lock> and set these Trace config strings.

TracePort=1
TraceBPS=115200

For additional details, refer to Tracing. The most powerful troubleshooting method is with a terminal connected by a serial crossover cable. The terminal emulator in a second Oberon system is a possibility.

If the installation host is not the target machine, replace the target device in the target machine and test again. ETH Oberon is a very robust software. With a little persistence it can run on almost any i386 or later PC.

Additional Software

Software beyond Oberon0 is distributed in Zip archive files Apps1.zip, Apps2.zip, Docu.zip, Gadgets.zip, Pr3Fonts.zip, Pr6Fonts.zip, Source1.zip, Source2.zip and Source3.zip. Also, for the specific task of rebuilding the system, files Build.zip, SourceB.zip and System.zip. For the Alpha release, all of these are in archive NativeOberon_2.3.7.tar.gz, available in Sourceforge. In a Unix-like system, the following procedure will obtain these zip files. Commands are executed in a console.

mkdir <somewhere>/Oberon2.3.7

Using any Web browser, retrieve NativeOberon_2.3.7.tar.gz, approximately 12 MiB, from Sourceforge into the Oberon2.3.7 directory.

cd <somewhere>/Oberon2.3.7
# Confirm existence of the gz archive.
ls
# Unzip and untar. 
gunzip NativeOberon_2.3.7.tar.gz
tar -xvf NativeOberon_2.3.7.tar
# Read the ETH license.
more readme.txt

Copy all the zip files to the SYS volume of the Oberon system. A FAT file system on a CompactFlash card, a USB flash drive or a diskette can transfer the data. A more sophisticated method is to establish a network connection and transfer the files by FTP.

In Oberon, MM on these commands to unpack the archives into the SYS volume.

FileSystem.SetDefault SYS
ZipTool.ExtractAll
  Apps1.zip Apps2.zip
  Docu.zip Gadgets.zip
  Pr3Fonts.zip Pr6Fonts.zip
  Source1.zip Source2.zip Source3.zip ~

The Build directory contains files required for rebuilding the system.

ls <somewhere>/Oberon2.3.7/Build/*
Build.zip  SourceB.zip  System.zip

If required these can also be copied to the SYS volume and extracted.

ZipTool.ExtractAll Build.zip SourceB.zip System.zip ~

Then revert to the working volume.

FileSystem.SetDefault YourWorkingVolume ~

Boot Manager

If the target machine, real or virtual, has more than one operating system, a boot manager will be needed.

System Configuration

Fundamental configurations are represented by configuration strings allowing specification of the display driver for example. The boot loader allows access to these strings.

At a higher level, system configuration is in the file Oberon.Text. In the freshly installed base system this file is specifically SYS:Oberon.Text. Two subtleties can confuse the novice.
  * Syntax in Oberon.Text is critical. If a closing bracket "}" is inadvertently removed, some information following the error will be ineffective. Take care in editing Oberon.Text.
  * A storage volume additional to SYS can contain an Oberon.Text. Only the first-prioritized copy of the file has effect. For example, consider a system installed and configured with HOME prioritized before SYS. The first execution of ET.Open Oberon.Text will open SYS:Oberon.Text. After editing, ET.Store will store HOME:Oberon.Text. After reboot, SYS:Oberon.Text will remain but HOME:Oberon.Text will have effect; HOME:Oberon.Text will mask SYS:Oberon.Text. Ambiguity can be avoided by specifying a volume.

ET.Open SYS:Oberon.Text
ET.Open HOME:Oberon.Text

Communications Environment

Oberon on a native machine can connect to the Internet through a wired router. A more flexible connection can be provided by a Linux router. In any case the LAN should have a firewall. With a Linux router, Shorewall is recommended. ETH Oberon supports these communications.

Modality	Protocol	Notes
Email sending	SMTP	Oberon can send to a MTA such as Exim on a LAN machine or directly to a smarthost. Exim can provide secure communication.
Email receiving	POP	POP can be tunneled through Stunnel.
terminal emulator	Telnet	For security, telnet connections should be limited to the LAN.
secure shell	SSH	Secure compared to telnet
file transfer	FTP	For security, FTP should be limited to the LAN.
file transfer	SCP	Secure compared to FTP
World Wide Web	HTTP	In absence of an SSL library, HTTPS is not possible.

Network Connection on a Real Machine

With the base system working, configure a network connection. ETH Oberon supports wired Ethernet with a static IP address. Wireless and DHCP are not supported. In absence of an Ethernet connection, PPP over an RS-232 crossover cable (null modem) is also possible. Refer to the Oberon.Text and NIC pages.

PPP

The original PPP for XOberon was written by Martin Aeschlimann and Claude Knaus. Edgar Schwarz ported to ETH Oberon / PC Native.

The syntax of Oberon.Text allows multiple Devices, Device0 ... Device9. In ETH Oberon 05.01.2003 the maximal number of Devices, MaxDevices, is set in NetBase.Mod to 2. This limit can be increased to 10 at most, with subsequent recompilation of NetBase.Mod. Multiple Devices allow the use of various network hardware and protocol options without changing Oberon.Text. For example Oberon.Text might define these three Devices.

Device0 = { "PPPMain.InstPPP", "COM1"}
Device1 = { "PPPMain.InstPPP", "COM2 \silent"}
Device2 = { "Net3Com509.InstallDevice", "" }

This allows noisy invocation of PPP,

Dialer.Dial DIAL Device0 ~

and "silent" invocation.

Dialer.Dial DIAL Device1 ~

Device2 allows for an Ethernet connection. Note that two different PPPs can not be installed on the same COM port and that NetBase.Mod must be recompiled with MaxDevices* = 3 or more for this example to work.

PPP Troubleshooting

Begin at the lowest level, the crossover cable or modem, and work to the highest level, the browser, mail handler and etc.

A modem has two speeds: interface and modulation. The interface speed is between the computer and the modem. The modulation speed is between the modem and the telephone network. Unless referring specifically to the interface, specifications usually refer to the modulation speed.

The interface speed of an internal modem or computer serial port is set in Oberon.Text in a DIAL script as in this example.

Init = { COM1 57600 }	{* modem port and speed *}

As can be seen in V24.Start, allowed values of this speed are whole divisors of 115200 b/s. Hence, Oberon allows these speeds for the interface.

115200
 57600
 38400
 19200
 14400

The maximal interface speed of a modem is usually higher than the modulation speed.

An external modem connects to a serial port and buffering is an issue. An internal modem connects directly to the system bus. Buffering between computer and internal modem is not an issue or is less critical than with an external modem. Perhaps someone who knows about buses and modem circuitry can elaborate.

The interface speed should be set in the dial script to min(p, m) where p is the highest speed at which the the serial port of the computer can operate and m is the highest speed at which the serial port of the modem can operate. Some of the old IDE I/O cards used in desktop PCs were not reliable above 9600 b/s! Serial ports in laptop PCs are buffered better. My old Toshiba Satellite T2100 operates reliably at 38400 b/s; never tested 57600 b/s.

In absence of specifications, the interface speed can be set empirically. Try one of these settings. If communication fails, adjust to a slower speed.

 Modulation      Interface
   14400           19200
   28800           38400
   57600           57600

Before attempting to make a DIAL script, try the V24.Panel. Execute.

Desktops.OpenDoc  V24.Panel

Set the interface speed in the window. Parameters are COM port, interface speed, bits/byte, number of stop bits, parity. Click the Open button. Key in the modem initialization. For the majority of cases, ATZ will work. More information about initialization is available in the Kermit documentation and elsewhere on the Web.

After the modem acknowledges initialization, in most cases with OK, key a dial command. Eg.

ATD T5392157

The T invokes tone rather than pulse dialing. After a few to several seconds you should see a response from the remote system. If it allows a "terminal" or "dialup" connection you should get a prompt such as "login: ". In any case, you will at least have established that your modem can communicate with the remote modem.

The next objective is to obtain a working DIAL script. It can be built up step by step. Rather than assume the characters which will be returned by the remote system, begin with something such as this, adapted to your environment. Replace "GulfNet" with any name you fancy, set the COM port and speed in Init and replace 5392157 with the number for your server.

{* This is for the Motorola MODMSURFR *}
GulfNet = {
Init = { COM1 38400 }	{* modem port and speed *}
Dial = {
  "ATZ" 
  10 "OK" 
  "ATD T5392101" 
  60 "ZZ"
  }

"ZZ" is unlikely to be returned by the local modem, the remote modem or the remote system. Consequently the script just waits for all characters returned within 60 seconds. The System.Log will show the complete reply. Move it to the user track for easier reading. Choose a string of characters from the reply which indicates unambiguously, completion of the modem-modem connection. For example. {|ATD T5392101||CONNECT 38400|~ ...

The strange characters beginning with ~ are the the PPP negotiations. The modem-modem connection is identified by "CONNECT 38400". Hence, "ZZ" in the script can be replaced with "400". This is a dial script.

{* This for a Motorola MODMSURFR *}
GulfNet3 = {
  Init = { COM1 38400 }	{* modem port and speed *}
  Dial = {
  "ATZ" 
  10 "OK" 
  "ATD T5392101" 
  60 "400"
  CALL "PPPMain.StartInst GulfNet3 peter"
  }
}

If the server does not prompt for a userid and password it should expect PAP (Password Authentication Protocol) authentication.

Network Connection on a Virtual Machine Using a Bridge

A configured bridge interface is required in the host. In Debian Linux, install the cron and bridge-utils packages.

apt install cron bridge-utils

This line in /etc/crontab should create interface br0.

@reboot root ip link add br0 type bridge

Check that the bridge exists.

ip link show br0
4: br0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
    link/ether 92:e0:54:07:2a:e2 brd ff:ff:ff:ff:ff:ff

Without the bridge, this method will fail. The name "br0" is arbitrary, provided consistency with the br option in the qemu command, with the name in /etc/network/interfaces and with the name in the /etc/qemu-ifup script. If there is difficulty creating the interface, assistance might be obtained from an enquiry in the Oberon mailing list or in the qemu-discuss list.

In most Linux systems, a stanza similar to this in /etc/network/interfaces will configure the extant bridge.

# Bridge to qemu guest.
auto br0
iface br0 inet static
        address 10.0.2.1
        broadcast 10.0.2.255
        netmask 255.255.255.0

"10.0.2.1" is a IPv4 private IP address chosen by the designer of the particular LAN. Successful configuration can be verified interactively as in this example.

user@qemuhost:/home/user$ ip addr show br0
 6: br0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default qlen 1000
    link/ether 00:00:00:00:00:00 brd ff:ff:ff:ff:ff:ff
    inet 10.0.2.1/24 brd 10.0.2.255 scope global br0
       valid_lft forever preferred_lft forever

During system startup, if the network happens to be configured before the bridge is created, the bridge won't work for the Oberon guest. The bridge can be raised interactively.

ifup br0

or

ip link set br0 up

When qemu is executed it attempts to create tap0 and to configure it, connected to the existing bridge. The qemu command requires the tap option which requires root priviledge.

sudo qemu-system-i386 \
  -drive file=/dev/KingstonCF,index=1,media=disk,format=raw \
  -vga std -boot order=c \
  -nic tap,script=/etc/qemu-ifup.variant,model=ne2k_pci,br=br0

/etc/qemu-ifup.variant is a script which QEMU invokes to create and configure the tap interface. The user can change the name and content of the script according to requirements. Default routing in the QEMU host is reported by ip.

user@qemuhost:/home/user$ ip route show | grep default
default via 10.0.2.1 dev wlxe894f6248326

The /etc/qemu-ifup provided in Debian 11 assumes the bridge should connect to the default route. Script qemu-ifup.variant was suggested in the qemu-discuss list at 2021-03-17 by Berto Furth to identify the bridge explicitly.

#! /bin/sh
# qemu-ifup.variant script which will be invoked by qemu to produce a tap interface. 

# Specify the preexisting bridge interface which the tap will connect to.
bridge=br0

ip=$(which ip)
echo $0 connecting $1 to $bridge
ip link set "$1" up
ip link set "$1" master "$bridge"
exit

For a bridge name other than br0, "br=br0" should be adjusted. The script must be executable; use chmod if required.

chmod a+x /etc/qemu-ifup.variant

The installed /etc/qemu-ifup should be preserved for reference and to avoid disruption by a package update. The null /etc/qemu-ifdown provided by Debian can remain as installed.

Oberon has software drivers for 3COM and Ne2000 NICs; not for the QEMU default e1000 NIC. QEMU lacks support for 3COM. Therefore the qemu command includes "model=ne2k_pci".

The tap option will require superuser authentication when QEMU is executed.

In the Oberon guest, configuration is in Oberon.Text.

NetSystem = {
  Hosts = {
  ...
      Device0 = { "NetNe2000.InstallDevice", "" }
  ...
  Route0 = {
    Device = "Device0"
    Mode = "arp"
    Host = { "OberonSystem", "10.0.2.2" }
    Gateway = { "QemuHostSystem", "10.0.2.1" }
    Netmask = { "netmask", "255.255.255.0" }
  }
}

Observe that in the subnetwork 10.0.2.0/24 the bridge in the QEMU host has address 10.0.2.1 and the Oberon guest has address 10.0.2.2. Again, these private addresses can be adjusted according to design of the particular LAN. In any case the host bridge and guest will be on one subnetwork, in this example 10.0.2.0/24.

Installation Complete

Further assistance is available via the mailing list.