Overview at ETHZ
Documentation at ETHZ

Installing and Running UnixAOSEdit

A2 has been installed and used on bare PCs. More commonly it is installed as a subsystem on a Unix-like system or on MS Windows. The original instructions[1] for installing UnixAOS are in http://www.informatik.uni-bremen.de/~fld/UnixAos/Readme.txt. Installation files are available from http://www.informatik.uni-bremen.de/~fld/UnixAos/.

The display of freshly installed LinuxAos Generic 32-bit, rev.9527.

The shell script installer assumes existence of a sys group in the host. For systems lacking this group, the script is easily adapted. For example, sys can be changed to bin.

chgrp -R sys ${aosdir}


chgrp -R bin ${aosdir}

In UnixAOS the ext2 filesystem can be used on a removable flash store.

The aos start script, installed by install.UnixAos, by default to /usr/bin/aos, adjusts the operating system environment before starting aos.{solaris,linux,darwin}. As noted in Readme.txt, UnixAos can be started with these two commands.[2]

cd <myWorkingDirectory>

<myWorkingDirectory> must be replaced with a specific destination of course.

User and Machine Specific Configuration of UnixAOSEdit

UnixAos is configured by Configuration.XML. The Oberon subsystem is configured by Oberon.Text; refer to the ETH Oberon page and the original betadocu page.

Firefox and A2 with Weston and XWayland on a Debian 10 system with twin screens.

If the working directory is on a removable store, the myaos script allows the storage device to be used in multiple machines with differing configurations. When the store is not already mounted, e2fsck is applied as a precaution.[3] In case the filesystem has been corrupted, e2fsck will usually complete repairs. A reasonable location for the myaos script is the home directory of the user. For each host, create in the working directory, files Configuration.<host>.XML. To use the Oberon subsystem, create Oberon.<host>.Text. This can be done by copying the installed files and editing the copies. For example, a host named blunder requires Configuration.blunder.XML for A2 and Oberon.blunder.Text for the Oberon subsystem. The XML file contains ASCII text and can be edited with Geany, gedit or mousepad in Linux or with Edit > Text in A2. The installed Oberon.Text contains some binary information.[4] In ETH Oberon it would usually be edited with Edit or ET. Nevertheless plain text will also work. After storing Oberon.Text with ET.StoreChar, it can be edited with Mousepad or Gedit in Linux, with Notepad in MS Windows and with Atom in MacOS. This can resolve the difficulty of a file name, Oberon.<Host>.Text, exceeding the 32 character limit of the Oberon system. myaos copies Configuration.blunder.XML to Configuration.XML and Oberon.blunder.Text to Oberon.Text before starting UnixAos.

The A2 RepositoryEdit

The contemporary source texts of A2 are maintained in Apache Subversion (often abbreviated SVN) along with executables for several platforms. While older methods to install A2 are available, this method, based on the SVN repository, provides the latest version and allows ongoing updates. In summary, the method is to establish a local working copy of the repository and then to update when convenient. The repository is checked out from the ETHZ archive and A2 can be built for various platforms including a bare PC. As of 2022 January it contains completely working executables in subdirectories for Windows, Linux (Intel 32 and 64 bit) and ARM. The working copy of the repository will occupy approximately 1 GB.

Target Systems and File Name ExtensionsEdit

Terminology pertinent to compilation, loading and linking is explained in http://www.inf.ethz.ch/personal/felixf/pdfs/2011_UnifiedStaticDynamicLoading.pdf.

Target System Generic[5] Object File Name Extension Symbol File Name Extension
Unix, x86, 32 bit .GofU .SymU
Unix, AMD64, 64 bit .GofUu .SymUu
Windows, x86, 32 bit .GofW .SymW
Windows, AMD64, 64 bit .GofWw .SymWw
ARM, 32 bit[6] .GofA .SymA
ARM, 64 bit .GofAa .SymAa

In a Unix-like SystemEdit

Install Subversion. In Redhat, for example,

sudo yum install subversion

and in Debian.

sudo apt install subversion

Before attempting to create the local repository, check that UTF-8 character encoding is present in the system. An encoding failure will interrupt checkout with a report similar to this.

svn: E155009: Failed to run the WC DB work queue associated with '/home/me/a2', work item 15168 (file-install 44 UnixAos/DarwinA2 Installer/A2 64.app/Icon{U+ F00D} 1 0 1 1)
svn: E000022: Can't convert string from 'UTF-8' to native encoding:
svn: E000022: /home/me/a2/UnixAos/DarwinA2 Installer/A2 64.app/Icon{U+F00D}

If a locales package is available, it should be installed and configured according to instructions such as for Debian. Encoding "en_US.UTF-8 UTF-8" and several others will be effective.

At an arbitrary location, <somewhere>, in the user directory make a directory for the working copy of the repository. Eg.

mkdir <somewhere>/a2[7]

Clone the repository into the directory. In a graphical environment, a dialogue prompting for the password may appear. In that case, the password option should be omitted from the command.

cd <somewhere>/a2
svn checkout \
        --username infsvn.anonymous \
        --password anonymous \
    https://svn-dept.inf.ethz.ch/svn/lecturers/a2/trunk .

If checkout is interrupted, by an encoding error or communication failure, this should recover.

cd <somewhere>/a2
svn cleanup .
svn update .

Check that the local repository is complete.

svn status <somewhere>/a2

Subsequently, the local repository can be updated.

cd <somewhere>/a2
svn update \
        --username infsvn.anonymous \
        --password anonymous .

See what has changed (including every changed file) since this subversion repository was created. This will produce a very large output.

svn -v log <somewhere>/a2

For additional details refer to the svn manual.

Older instructions, at http://www.ocp.inf.ethz.ch/wiki/Documentation/Installation until November of 2019, remain available from the Wayback Machine. Those pages are not relevant to the SVN archive but contain extensive information about A2 itself.

In WindowsEdit

While SVN is not distributed with Windows, third party softwares are available. TortoiseSVN is one possibility. Install an SVN client and proceed as for Unix-like system as described above. SVN commands are executed in Powershell or in the cmd console (instead of "mkdir" use "md"; don't include the Backslash indicating continuity of the svn command), both available in Windows 10. The executable script for Windows is named a2.bat rather than a2.sh. If using PowerShell change "oberon" in a2.bat to "./oberon" or ".\oberon".

Running A2Edit

With an A2 repository in place, according to the preceding section, A2 can be executed.

Identify supported architectures.

<prefix> cd <somewhere>/a2/
<prefix> ls -d *   (dir /ad  in MS Windows cmd)
AosVM  LanguageReport  Linux32  source  UnixAos  Win64
ARM    license.txt     Linux64  tools   Win32    WinAos

Execute the appropriate start script. This for a 32 bit machine running MS Windows.


For a 64 bit machine running Linux.


User Level ApplicationsEdit

Various documents and applications are available via the menu at the lower left of the A2 display. Note Docu > Program Demos and Demos.

Secure Shell ConsoleEdit

In the target system, localhost or an external system, install a SSH server. This is one possibility.

sudo apt-get install openssh-server

In the A2 menu invoke Tools > Secure Shell. For Host specify "localhost" or "" (without the quote marks) or the name or address of the external machine. Specify your user id. Click on Connect. Provide your password when prompted.


A mail client using IMAP is at Apps > MailClient. The Oberon subsystem described in the following section has Mail.Panel supporting POP3 and SMTP.

The Oberon Subsystem in A2Edit

The Oberon subsystem in UnixAos on an XO-1.5.

Opening the Oberon Sub-systemEdit

An Oberon subsystem can be opened with a command in the Autostart section of Configuration.XML as in this example.

<Section name="Autostart"> 
	<Setting name="Start an Oberon" value="Oberon.Start Oberon 1100x704 0 74  ~"/> 

The dimensions, 1100x704, can be adjusted for satisfactory proportioning of text in a viewer. If the Oberon window is stretched, by grabbing the lower right corner with the mouse, the proportionality of text to viewer is preserved.

Usage Tips, Keyboard and MouseEdit

Mouse usage is unusual but efficient. Definitely worth the small effort to learn. A mouse with three buttons or two buttons and a wheel is essential. If a mouse button is pressed unintentionally, press all mouse buttons before releasing any. All mouse buttons together have no effect. The <Esc> key is used to interrupt a task. For example it can interrupt a long running FTP.GetFiles in the Oberon subsystem. <F1> sets the * marker. <F2> clears all marks. Additional details are in the keyboard page.

Telnet ConsoleEdit

Telnet is an insecure protocol but can allow a host console within the Oberon sub-system.

If the computer has only one user, the following is workable. If the computer has more than one user, allowing all users to access one account is probably unacceptable.

The host system should be firewalled. If not install Shorewall.

Install the telnet daemon the host.

apt-get install openbsd-inetd inetutils-telnetd

Configure with this line in /etc/inetd.conf.

telnet stream tcp nowait <user> /usr/sbin/tcpd /usr/sbin/telnetd -E bin/bash

<user> must be replaced with the id of the Oberon user. Restart the inet daemon.

service openbsd-inetd restart

Then try telnet from within a console in the host.

telnet localhost

Then in the Oberon sub-system.

Desktops.OpenDoc telnet://localhost

To be automatically located in the home directory, append this line to ~/.bashrc.

cd ~


The Mail.Panel in the Oberon subsystem in A2.

The Oberon subsystem in A2 supports POP and POP3 for retrieving e-mail and SMTP for sending it. In UnixA2 (=UnixAos) the subsystem can receive e-mail from a smarthost via Stunnel and send a message via Exim with TLS.[8] TLS is now routine practice; essential to preserve security.

In Oberon.Text (Oberon.<host>.Text if using myaos) make these settings.

NetSystem = {
  SMTP = "localhost"  {* outgoing exim4 mail server *}
  POP = "localhost"  {* stunnel to incoming mail server *}
  POPMode = "POP3"  {* POP3 or APOP *} 
  EMail = "me@my.domain.name"  {* your return address *}

Ports 25 for SMTP and 110 for POP are visible in Oberon.Mail.Mod.

Install stunnel on the host and configure as in this example. The server name and port, exemplified by my.email.server:995, should be adapted to context.

# localhost:/etc/stunnel/stunnel.conf
# Example SSL client mode services 
client = yes 
accept = localhost:110 
connect = my.email.server:995

Set the POP authentication using NetSystem.SetUser as in this example.

NetSystem.SetUser pop:myEmailID:myEmailPassword@my.email.server ~

The original SetUser command assumed the @ character did not occur in myEmailID or in myEmailPassword. This command, for example, would fail.

NetSystem.SetUser pop:me@my.domain.name:password@my.email.server ~

The difficulty is resolved by more thorough parsing in the SetUser command. Retrieve the revised Unix.Oberon.NetSystem.Mod. Compile the module with the compile button in the Notepad editor (hamburger menu > Edit > Text) or by a MM click on this command in an A2 window.

Compiler.Compile Unix.Oberon.NetSystem.Mod ~

The compilation must be performed in A2; not in the Oberon subsystem.

Install Exim in the host according to system specific documentation for Debian, Fedora/CentOS and etc. [9] Exim authenticates to a smarthost according to a password file.[10] Details of configuration for a specific mail server can be obscure. For example, STARTTLS or TLS on connect might not be specified. Before attempting to configure Exim, ambiguities are best resolved using Swaks. Replace parameters -au, -ap, -f and -t with appropriate values for user, password and email address.[11]

 swaks -tls \
       -ao -apt -au me@my.authentication.domain -ap r2d2\$8Ch \
       -s my.smarthost.com --port 587 \
       -f me@my.email.address -t me@my.email.address

The example password has eight characters; the \ prevents misinterpretation of the $ character. Swaks creates a trivial test message automatically. Parameters of the command can be adjusted until transmission succeeds. Transmission can be confirmed by receipt in Oberon as discussed above. Refer to the excellent manual for all details.

Sources, Tools and Configuration Texts in A2Edit

A tiny sample of the approximately 2000 sources in A2. Access the ETHZ Repository with userid infsvn.anonymous and password anonymous.

A contemporary Firefox browser attempts to infer "Content type" from the name extension. By default Firefox infers wrongly that source file *.Mod contains "Amiga SoundTracker audio" and fails to open it. This difficulty is resolved by adjusting the "Action" Firefox associates with "Content Type". Open hamburger menu > Preferences > General > Applications. For "Amiga SoundTracker audio" choose an editor such as /usr/bin/mousepad or /usr/bin/gedit. Most sources in A2 have been converted to plain ASCII text; some remain as Oberon Text. Gedit will open all of these. Mousepad and several other editors will not open Oberon Text. Content type "plain text document" should also be set to the chosen editor. With these adjustments Firefox should open most of the files in the repository.

In some contexts the user may fail to find a configuration of a browser to open files in the repository. In any case a browser should open the Wikibook copy.

ETHZ Repository Wikibook copy[12] Notes
BIOS.V24.Mod BIOS.V24.Mod  
BootManager.Asm BootManager.Asm BootManager source written in Network Assembler by André Fischer.
BootManager.Mod BootManager.Mod Module containing one command Split.[13]
BootManager.Text BootManager Instructional document written by André Fischer. In the repository and in MediaWiki representation.
BootManager.Tool BootManager.Tool Tool file summarizing the instructional document.
Configuration.XML Configuration.XML  
Oberon.Documents.Mod Oberon.Documents.Mod  
Oberon.HTML.Mod Oberon.HTML.Mod Revisions for conformance to HTML5.
  HTML.Tool No "preview" in the ETH Repository.
Oberon.HTMLDocs.Mod Oberon.HTMLDocs.Mod InitEntities() expanded to support more characters.
Oberon.MIME.Mod Oberon.MIME.Mod  
Oberon.Mail.Mod Oberon.Mail.Mod Deviation from SMTP corrected. Wrap() added. Names of types revised. Show() revised. Calculation of cont.len corrected.
  Oberon.MediaWiki.Mod Not in A2 repository.
Oberon.Out.Mod Oberon.Out.Mod Allow delay of execution of Append, using a flag variable.
Oberon.Out1.Mod Allow delay of execution of Append, using a procedure variable.
  Oberon.OutStub.Mod Not in A2 repository.
Oberon.QuotedPrintable.Mod Oberon.QuotedPrintable.Mod Variant from LinuxA2 Gen. 32-bit, rev.9527.
  Oberon.RFC3986.Mod Percent encoding and decoding of URL. Not in A2 repository.
Oberon.Sort.Mod Oberon.Sort.Mod Better presentation of output. Revisions incomplete.
Oberon.TFTPTool.Mod Oberon.TFTPTool.Mod
Oberon.TextFrames.Mod Oberon.TextFrames.Mod LOOPs removed.
Oberon.V24.Mod Oberon.V24.Mod  
Release.Oberon.Text Oberon.Text Usually Oberon.Text is customized to a user.
Unix.Oberon.NetSystem.Mod Unix.Oberon.NetSystem.Mod The "@" character in user or password is handled directly by parsing, without relying upon percent encoding.
  myaos Start script allowing use of a removable working store on multiple machines. Adaptable to requirements of user. Not in A2 repository.


  1. The SVN repository, described subsequently, is a more recent method of installation and release tracking.
  2. The command line prefix in a Unix-like system is user configurable and can be configured to the empty string. For simplicity, the prefix is omitted in most of the commands shown here.
  3. A filesystem can become corrupted if not unmounted before the system is shut down. The directory can also be damaged by natural degradation of the storage media. If the filesystem is intact, the execution time for e2fsck is negligible.
  4. See Oberon Text.
  5. "Generic" refers to applicability of the loader and linker to all target systems, independent of change in language and runtime system.
  6. Allowing A2 on the Raspberry Pi.
  7. In a Unix like system, many variations are available. cd ~ ; mkdir a2 for example.
  8. The same functionality of the Mail.Panel is available in ETH Oberon when another local host provides Exim and Stunnel.
  9. The primary Exim documentation is also available.
  10. In Debian, /etc/exim4/passwd.client associates a password with each (host, user) pair. Multiple host:user:password specifications are acceptable. The file does not determine the destination chosen by exim for sending a message. Refer to the exim4-config_files manual.
  11. me@my.authentication.domain is a userid pattern commonly used by ISPs.
  12. In some cases the Wikibook copy differs from the latest file in the ETHZ repository. For an exact comparison, use a file comparator; Diff.Do in Oberon, comm in Linux. Some sources have a discussion page. Oberon.Mail.Mod discussion for example.
  13. BootManager.Split BootManager.Bin is executed to divide BootManager.Bin into BootManagerMBR.Bin and BootManagerTail.Bin. For additional details, refer to the instructional document of André Fischer.