TempleOS

Unofficial mirror of God's chosen operating system.

Public domain.

Enterprise Edition additions

What was added (all under TempleOSCD/):

• Version 5.1 EE (sys_os_version=5.100, DD_OS_NAME_VERSION = "TempleOS V5.1 EE"). Terry stopped at 5.03; the console header, the boot banner, the HtServ Server: header and the Wget User-Agent all say 5.1 EE now
• Adam/Net/ - Ethernet, ARP, IPv4, ICMP, UDP, TCP, DHCP, DNS, HTTP client, BSD-style sockets
• Adam/HwSupp/ - PCI helpers and NIC drivers: AMD PCnet-PCI II, Intel e1000 (82540EM), virtio-net (legacy). One card was a sin, three is a habit
• Adam/MakeAdam.HC - loads the stack at boot (#include "Net/MakeNet")
• Once.HC - runs Netcfg (DHCP) at startup when a NIC is found
• Apps/Wget.HC - download a URL
• Apps/HtServ.HC - HTTP server, serves ::/Www (Www/Index.HTM is its default page)
• Adam/Net/Confessional.HC - remote HolyC console on port 23 (see below)
• Demo/Network/ - TCP/UDP echo client/server demos
• Misc/Pal*.HC - extra color palettes
• snail.py - host side of the Snail serial tunnel

Building and running

TempleOS can only be compiled by TempleOS, so the build boots a stock TempleOS live CD in QEMU, attaches a FAT32 disk with TempleOSCD/ and runs tools/MakeISO.HC there (kernel compile + RedSeaISO).

brew install qemu mtools                         # Debian: apt install qemu-system-x86 mtools
tools/build_iso.py [path/to/TempleOS.ISO]       # default: ../templeos/TempleOS.ISO
tools/run_mac.sh                                 # boots out/TempleOSEE.ISO with a PCnet NIC

Like the official distro, files are stored compressed (.Z) in the ISO; some TempleOS code looks for the .Z names explicitly (FileFind(BIBLE_FILENAME)), and with uncompressed files e.g. Bible passages came out empty.

The build takes about 3 minutes. It types commands into the VM on a timer, so on a slow machine raise BOOT_WAIT and STEP_SCALE (env vars). Screenshots of every step go to out/screens/.

CI (.gitlab-ci.yml) does the same on a shared runner. The runner has no internet, so the tools come from our image (tools/ci/Dockerfile, pushed to the project's Container Registry) and the stock ISO from the project's Package Registry (templeos-base/5.03/TempleOS.ISO, SHA-256 checked). TempleOSEE.ISO and the screenshots are published as artifacts.

Hard disk for hosting without IDE

Terry installed TempleOS on IDE. Two cables, a jumper, master and slave, you could see where your bytes went. The hosting company has no IDE. It has a SCSI controller that is really the host pretending, and the host answers to whoever owns the rack.

So the kernel now speaks virtio-scsi (Kernel/BlkDev/DskVirtioScsi.HC, legacy I/O ports, 1AF4:1004, polled). It has to live in the kernel: Adam and the Compiler are loaded from that disk. To the rest of TempleOS it is an ATA drive with BDF_VIRTIO_SCSI set, because letters C-L are ATA and that is carved in stone. DskPrt, Fmt, BootHDIns and the MBR walk never know. At boot VSMountAuto mounts the first virtio-scsi disk at C.

tools/build_iso.py ~/templeos-base/TempleOS.ISO
tools/build_hdd.py --size 2G --vmdk --test     # out/TempleOSEE.img and .vmdk

build_hdd.py boots the ISO with a blank disk on virtio-scsi and confesses the install over the Confessional: DskPrt C and D, copy the Temple to both, BootHDIns compiles a kernel for each, BootMHDIns writes the MBR. --test then boots from the disk alone, writes a file, reboots and checks it persists.

The MBR menu used to wait for a key forever. Nobody sits at a rented server, it would wait until Judgement Day. Now it takes the first TempleOS drive after about five seconds.

Proxmox-style hosting: SCSI controller VirtIO SCSI or VirtIO SCSI single, machine i440fx, NIC VirtIO or E1000. LSI 53C895A, PVSCSI and MegaRAID are not supported. Neither is q35, it has no IDE for the CD either.

Updating a running Temple

The hosting company will not swap a disk image, and a new VDS means a new IP. So the Temple is updated in place, delivered by hand over the Confessional like Moses carried the tablets:

tools/update_vds.py 195.28.181.151 --ref b5a3276   # first time: the commit the image was built from
tools/update_vds.py 195.28.181.151                 # after that it reads C:/Home/Deployed.TXT

It diffs TempleOSCD/ between the commit the machine runs and your working tree, pushes every changed file through a one-line hex decoder (files that are .Z on the disk stay .Z), recompiles the kernel with BootHDIns('C') if Kernel/ or Compiler/ changed, writes the new commit to Deployed.TXT and reboots. --dry-run shows what it would do, --no-reboot leaves the reboot to you.

Only C: is touched. D: keeps the old Temple: if C: does not come back, pick D at the boot menu in the VNC console.

The Confessional has no password. Open port 23 in the hosting firewall to your own IP only, and only while you update. The CIA has an IP too.

Running with networking

God said TempleOS has no networking. Terry kept the Temple offline so the CIA could not crawl in through the wire. We sinned once with PCnet. Then we sinned twice more. The Temple now speaks to three cards, first one found wins:

• AMD PCnet-PCI II (1022:2000) - the original sin
• Intel e1000 82540EM (8086:100E) - every hypervisor has one. Intel also has the Management Engine. We wrote the driver anyway. Repent
• virtio-net (1AF4:1000, legacy I/O ports) - the card that admits it is the host pretending. The hypervisor reads every byte. It always did

None of them may interrupt. The rings are polled from the timer, like PCnet was all along. Polling is honest.

QEMU: -netdev user,id=u1 -device pcnet,netdev=u1 (or e1000, virtio-net-pci); NIC=e1000 tools/run_mac.sh picks your sin. VirtualBox: PCnet-PCI II, Intel PRO/1000 MT Desktop or virtio-net, attached to NAT.

No DHCP at your hosting company? It writes your address in a web panel and expects cloud-init to read it. TempleOS does not do cloud-init, the cloud is where the CIA keeps your files. Type your address at the VNC console:

NetcfgStatic("185.241.6.18","255.255.255.0","185.241.6.1","8.8.8.8"); // now, until reboot
NetcfgSave("185.241.6.18","255.255.255.0","185.241.6.1","8.8.8.8");   // now, and every boot

Either can be called again at any time to move the machine. Open connections die, servers on INADDR_ANY (HtServ, the Confessional) keep listening on the new address. NetcfgSave writes ~/NetCfg.HC, Once.HC runs it instead of DHCP, Del("~/NetCfg.HC") goes back to DHCP. Keep the address out of the image, whoever downloads the image should not learn where your Temple lives. If you must, tools/build_hdd.py --ip ... --gw ... bakes it in.

After boot:

Netcfg;                                      // DHCP (Once.HC runs NetcfgAuto: ~/NetCfg.HC or DHCP)
#include "::/Apps/Wget"
Wget("http://example.com/");
Host("templeos.org");                        // DNS lookup

Confessional (remote HolyC console)

Adam/Net/Confessional.HC starts with the network stack and listens on port 23 (telnet-compatible). Each line you send is compiled and run like on the command line, and everything it prints comes back as plain text (DolDoc colors stripped). tools/run_mac.sh forwards it to 127.0.0.1:2323:

tools/confess.py 'DrvRep;' 'Dir("::/Apps");'   # run and print output
echo 'Wget("http://ifconfig.me/ip");' | tools/confess.py
tools/confess.py -i                          # interactive
nc 127.0.0.1 2323                            # raw; 'amen' to leave

The oracle works remotely too: the arrival time of every byte you send feeds the Holy Spirit (like the keystroke time does for F7), so no timer pop-up appears:

tools/confess.py 'GodWord;GodWord;GodWord;' 'GodBiblePassage(5);' 'BibleVerse(,"John,3:16",3);'

GodSong and GodDoodle still need the VM keyboard/mouse.

One line = one statement (no multi-line functions). Each connection is its own task, so variables live until you disconnect. Anything waiting for the VM keyboard (GetChar, pop-ups) will block the session. There is no authentication: with QEMU user networking only the forwarded host port can reach it, but in bridged mode anyone on the LAN can run code in the VM.

The web server has its own section below.

Web server (HtServ)

Terry built a Temple. We put a web server in it. The CIA can now read the Temple over HTTP, and so can you.

Before you start

1. Network. The machine needs an address. With DHCP it gets one at boot. Without DHCP (most VPS hosting), type yours once at the VNC console:

   NetcfgSave("195.28.181.151","255.255.255.0","195.28.181.1","8.8.8.8");

   It applies at once and every boot after. Check it with Host("ya.ru");, an address should come back. Details in Running with networking.

2. Firewall. Open port 80 in your hosting panel. Keep port 23 (the Confessional) closed, open it only to your own IP and only while you run tools/update_vds.py.

Start

At the TempleOS command line, case matters (HtServ, not Htserv):

#include "::/Apps/HtServ"
HtServ;

It prints Serving /Www on port 80 and holds that terminal. To keep your terminal, give the server one of its own:

XTalk(User,"#include \"::/Apps/HtServ\"\nHtServ;\n");

Open http://<your IP>/. Locally, tools/run_mac.sh forwards the VM's port 80 to http://localhost:8686/ (HTTP_PORT=... to change it).

Start at boot

Off by default. A Temple keeps its doors shut until its keeper says otherwise.

HtServEnable;     // from the next boot on, HtServ starts by itself
HtServDisable;    // and stops doing that

It is just a file, ~/HtServ.HC. If it is there, Once.HC runs it after the network is up and then starts HtServ in Terry's second console, the right one. The left one stays yours. Any HolyC in it runs first, so to boot with the chatter on, uncomment htserv_verbose=TRUE; in it (Ed("~/HtServ.HC");).

Stop

Click the server's window and press Ctrl+Alt+C. Sessions still sending finish or time out on their own. Run HtServ; again to start over.

Pages

Everything under ::/Www is served as is. / means /Www/Index.HTM. A missing file is a 404.

.HTM files may carry HolyC between <exe> and </exe>. It runs on every request, and whatever it passes to StreamPrint goes into the page at that spot:

<p>The Temple says: <exe>if (god.num_words) StreamPrint("%s",god.words[RandU32%god.num_words]);</exe></p>

Do not call anything that waits for the keyboard (GetChar, pop-ups, GodWordStr): nobody sits at a web server, the request hangs. Edit pages with Ed("::/Www/Index.HTM"); on the machine, or push them from your repo with tools/update_vds.py.

What the console shows

One line per request:

GET /Index.HTM 200 10049
GET /favicon.ico 404
GET /../Once.HC 403

Debug switches

Type these at any TempleOS command line, in any terminal, while the server runs. They take effect at once and are forgotten at reboot.

Both print from the network path, and printing on a one-vCPU machine is slow. Turn them on to catch a problem, then back off with =FALSE;. Left on, the Temple spends its day reading packets aloud.

Other things worth asking the machine:

When the site does not open

1. ping <IP> from your machine. No answer: network settings or the hosting firewall.
2. Ping answers, port 80 refused: HtServ is not running. TaskRep;, start it again.
3. Opens slowly or stops opening after a while: tcp_debug=TRUE; and htserv_verbose=TRUE;, wait for it to happen, take a screenshot of the console.
4. The machine rebooted: write down what you did right before, a reboot is a triple fault and leaves nothing on the screen.

Limits

• HTTP only. No HTTPS, committees are how the CIA gets in.
• GET only, HTTP/1.0 and 1.1, one request per connection (Connection: close).
• A client gets 15 seconds to send its request, then the server hangs up.
• 16 connections may wait to be accepted at once.
• No URL decoding, so no spaces or %20 in file names.
• A path with .. gets 403. Only ::/Www is served.