Contiki BBS 0.3.x quick startup guide

Preamble:

Contiki BBS is a tiny, little and text based bulletin board system (BBS) for the Commodore 64 homecomputer and a compatible ethernet cartridge (e.g. RRnet, 64NIC+ etc.). It can be accessed through a standard telnet connection and currently provides basic BBS functionality (select from multiple boards, post/read messages, page sysop).

This guide is intended to be used as a quick startup guide. It will cover the compilation and installation of Contiki BBS from source on a Linux system. This guide (c) 2019 by Niels Haedecke.

If you just want to run the software without compiling it (e.g. you have downloaded the .d64 disk image), skip to section 10.) of this document.

Changes:

0.3.1:
- As of version 0.3.1 it is no longer required to add any users beforehand (during setup of Contiki BBS). Instead, a new "online-registration" feature allows you to create a user once you are connected to the BBS. To do so, simply enter 'new' (without the quotes) at the Contiki BBS 'login:' prompt.

• In addition to the new online-registration feature, the user editor in the bbs-setup program now includes an option to delete a user or edit a user (change the password or ACL).

• Starting with version 0.3.1, Contiki BBS will be compiled and linked against the 6502 port of Contiki OS provided by Oliver Schmidt. This port includes changes to Contiki OS that are platform specific and which are not included in the "upstream" (vanilla) Contiki OS sources. For example, there is now specific support for the RRnet Mk3 LAN adapter. Also, support for TFE adapters was dropped from the 6502 port (this is important, see below). See http://retrohackers.com/viewtopic.php?f=5&t=678 and https://github.com/oliverschmidt/contiki for more information about Oliver's 6502 port of Contiki OS.

• Due to the change of the upstream Contiki OS code repositiory (see above), there is no more support for TFE adapters in Contiki BBS.
  Just to make sure you really understand: Contiki BBS DOES NO LONGER SUPPORT TFE ADAPTERS !!

• A bugfix was provided for the 'list' command in the 'bbs-read.c' module. The bug caused a memory leak when trying to list messages of an empty (0 messages) board.

0.3.0:
- As of version 0.3.0, Contiki BBS can also be installed on and run from SD2IEC devices (e.g. in its own directory on the sdcard).
The software now also supports multiple disk drive setups and thus allows you to store board/message data and user data on different drives (e.g. "9" for board data and "10" for user data).

Prerequisites:

The following tools are required for a successful compile and installation of Contiki BBS:

• GNU Make

• The cc65 (6502) C compiler

• Git revision control tool

• VICE Emulator installed (needed due to the included c1541 commandline program)

• A second machine (physical or VM) on the same network running a VICE Emulator with ethernet emulation enabled through libnet & libpcap (UNIX/Linux) or WinPCAP (Windows).

NOTE: On Linux you may have to use libnet0-1.0.2a from its original source code archives in order to get ethernet emulation working with VICE, since the libnet packages provided by recent Linux distros (e.g. libnet1) won't work (VICE will not be able to use the 'write_link_layer' function).

Alternatively, a Commodore 64 with a Commodore 1541/1570/1571/1581 disk drive and any compatible ethernet cartridge (e.g. RRnet, 64NIC+ etc.) will work as well. You just have to transfer the D64 image to a 5.25" / 3.5" disk. Search the web for 'opencbm' for information on how to accomplish this.

The Contiki BBS sourcecode repository contains a folder named "d64" where the latest version of Contiki BBS can be found on a D64 disk image to run the program in an emulator or write it back to a real 5.25" floppy disk. This folder now also contains a zipfile with all files and binaries required to run Contki BBS on a SD2IEC device (e.g. from within a folder on the sdcard). Just unzip the contents of the zipfile into a folder of your choice on your SD2IDE sdcard.

How to build Contiki BBS from scratch

This guide assumes your are using Linux as your development platform. Shell commands needed to be entered will be displayed with the well known UNIX commandline prompt at the beginning. E.g. the following example will show the 'ls' command being issued:

$ ls

1.) Create a folder where you are going to keep your Contiki and Contiki BBS sources.

$ mkdir src

2.) Go to your new source folder

$ cd src

3.) Get sources of the 6502 port of Contiki OS:

$ git clone https://github.com/oliverschmidt/contiki.git

4.) Get Contiki BBS sources:

$ git clone git://git.code.sf.net/p/contiki-bbs/code contiki-bbs-code

5.) Go to the directory containing the Contiki BBS sources

$ cd contiki-bbs-code/platform/c64/

6.) Build the binaries

$ make

7.) Seperately build the Contiki BBS setup program

$ make -f Makefile.bbs-setup

Voila! You have now built your own Contiki BBS binaries. Now, how do we get these on a D64 disk image?

8.) Still in the source directory, create a D64 disk image (make sure you have set your PATH to point to the c1541 commandline program)

$ c1541 -format "contikibbs,30" ctkbbs.d64

9.) Write the neccessary files to your new D64 disk image. Depending on what ethernet hardware you are using, you may skip writing *.eth drivers to the image that you don't need in order to save disk space. RRnet dnd 64NIC+ devices require the cs8900a.eth driver to be present.

$ c1541 ctkbbs.d64 -write contiki-bbs.c64
$ c1541 ctkbbs.d64 -write bbs-setup.c64
$ c1541 ctkbbs.d64 -write default.cfg contiki.cfg,s
$ c1541 ctkbbs.d64 -write cs8900a.c64 cs8900a.eth
$ c1541 ctkbbs.d64 -write lan91c96.c64 lan91c96.eth
$ c1541 ctkbbs.d64 -write login.txt login.txt,s
$ c1541 ctkbbs.d64 -write logout.txt logout.txt,s
$ c1541 ctkbbs.d64 -write menu.txt menu.txt,s

Congratulations, you're done! Now you have a working D64 disk image containing Contiki BBS, ready to run in an emulator or to be written back to a real 1541 Disk in order to run it on a real Commodore 64.

Okay, so this is how to build and prepare Contiki BBS for use on a Commodore 64. Now let's go through the setup process of Contiki BBS itself. So startup your VICE emulator and attach your ctkbbs.d64 disk image to drive 8. You are now at the Commodore 64 BASIC prompt.

10.) Load the Contiki BBS setup program

 LOAD "BBS-SETUP.C64",8,1

11.) Start it ...

 RUN

Contiki BBS configuration

The main menu will appear

 *** Contiki BBS 0.3.1 setup ***

 1...BBS base setup
 2...BBS board setup
 3...TCP/IP setup
 4...User editor
 q...Quit

1...BBS base setup

The output below shows an example configuration for the BBS base setup. Here you set up your disk drives, BBS prompt and timeout values. If you have more than one disk drive you can now store all board/message data files and user data files on seperate disk drives. The only requirement is that drive 8 is used as the boot disk drive. In the example below we use a second disk drive (device number 9) for storing the board/message data files and a third disk drive (device number 10) to store the user data files. Of course, if you only have one floppy disk drive, the board and userdb drive number will be the same as the boot drive number: 8. Login and session timeouts are set to 120 and 360 seconds and online-registration of new users is also allowed.

 * BBS base setup

 Enter boot drive #  : 8
 Enter board drive # : 9
 Enter userdb drive #: 10

 Login timeout (seconds)  : 120
 Session timeout (seconds): 360
 Enable online registration (y/n): y

Once you have answered the above questions, you will be asked to confirm your input:

 Base data correct (y/n)?

Enter 'y' if everything is okay or 'n' to re-enter the BBS base configuration values.

2...BBS board setup

Boards are an early predecessor of today's internet forums. It's the place people write their postings. Below you will see an example output showing the creation of one board. Please be patient, as the creation of the data files may take some time (especially when you run Contiki BBS on real hardware). You may add as many boards as you like as long as you have the disk space available.

* BBS board editor

(a)add, (l)ist or (q)uit :a

 Board #1
 Board name : lounge
 Access lvl.: 10

 Board data correct (y/n)? y

You may use the (l)ist option to print a list of all boards available. Following the example above, you will see the "lounge" board being listed.

* BBS board editor

(a)add, (l)ist or (q)uit :l

ID#|Acc|Boardname 
---+---+----------------------------  
001|010|lounge

Press key

3...TCP/IP setup

This configuration step will configure your Commodore 64 ethernet hardware, including IP addresses, driver and memory location of the cartridge. The example below shows a typical LAN setup using a RRnet or 64NIC+ cartridge at memory address $de08. Both cartridges use the cs8900a.eth driver. ETH64 network devices may use the lan91c96.eth driver along with its appropriate memory address.

NOTE: do not prefix your memory address with the '$' sign. E.g. if your ethernet cartridge resides at $de08 just enter 'de08' when being prompted for the memory address.

* BBS network setup

Host IP             : 192.168.200.64
Netmask             : 255.255.255.0
Gateway IP          : 192.168.200.1
DNS IP              : 192.168.200.1
Mem addr. ($de08)   : de08
Driver (cs8900a.eth): cs8900a.eth
Write to drive # (8): 8

Network data correct (y/n)? y

4...User editor

NOTE: as of Contiki BBS 0.3.1 it is no longer required to add any users during setup of Contiki BBS. Instead, a new "online-registration" feature allows you to create a user once you are connected to the BBS. To do so, simply enter 'new' (without the quotes) at the Contiki BBS 'login:' prompt.

IMPORTANT: The very first user that is registered to the system will become the SysOp user with the ACL automatically set to 255. It does not matter wether you create that first user in the user editor during setup of the bbs or via the online-registration feature at first connect. All other users (user_id > 1) using the online-registration method will automatically have the new user's ACL set to 10. You can then use the new user editor in the bbs-setup program to change the ACL or password of a specific user.

The user editor now allows you to add, list, show, edit and delete the users of your BBS. Each of these options is easy to use and pretty self-explanatory. The difference between "list" and "show" is that "list" will print a list of all user accounts, not showing the user's passwords whereas "show" will ask for a specific user ID (user number) and then show all information of that particular user, inclunding the password.

In the example below we use the "(a)dd" functionality to create a 'guest' user with the password 'guest' after the inital (sysop) user was created using online-registration.

* BBS user editor

(a)add, (s)how, (l)ist (e)dit (d)elete (q)uit :a

User #  : 2
Username: guest
Password: guest
Access lvl.: 10

User data correct (y/n)? y

You have now set up your Contiki BBS system and are ready to run. Quit the BBS setup program from the main menu by entering 'q'.

Running Contiki BBS

Once you have set up your Contiki BBS, reset your machine or emulator and load the Contiki BBS server from the Commodore 64 BASIC prompt.

1.) Load and run Contiki BBS
LOAD "CONTIKI-BBS.C64",8,1

2.) Start it...
RUN

3.) Now use a second machine to connect to the IP address of your Commodore 64 (the Host IP address you entered in Step 3 of the BBS setup program) via telnet.

      W e l c o m e   t o :

       -=-=-=-=-=-=-=-=-=-

      >> Contiki BBS Demo <<

Contiki BBS  V0.3.1 (C) 2009-2019   
               by                   
           N. Haedecke

Type "new" to create a new account,
or log-in using your credentials.

Contiki BBS 0.3.1

login:

You are now connected to your Contiki BBS system and can now create your first user (which will be the 'sysop' / 'administrator' user). Well done!
To add your first user (which is automatically the 'sysop' user), enter 'new' (without the quotes) at the 'login:' prompt and follow the instructions. All other new users registering to the bbs (all users registered after the very first user) will get a default ACL of 10. Use the new user editor function in the bbs-setup program to change a user's password or ACL.

Have fun !!