Roadshow TCP/IP stack notes (2020-09-05)
1. The demonstration version and the commercial release
Roadshow is a commercial product which can be bought online or on CD-R from
"http://www.apc-tcp.de". Support is available at "http://roadshow.apc-tcp.de".
A free demonstration version as well as the free software development kit
(SDK) are available on the same web site.
The demonstration version is almost identical to the commercial version, but
there is one important difference: the demonstration version will run only for
a short period of time after which it stops. Once stopped, it will remain in
memory, which means that you may have to restart your Amiga in order to give
Roadshow another try.
Because it remains in memory, it also means that you cannot easily shut it
down and start a different TCP/IP stack. Sorry! This is not how it should
work, but a different way to make the demonstration version work has not
yet made itself obvious :-(
For information on how to make the TCP/IP stack work again which you used
before, after you have given Roadshow a try, please see section 7 of these
notes (at the end of this document).
1.1. Upgrading the demonstration version to the commercial release
Once you have installed the demonstration version, configured and tested it,
you might want to buy the commercial release. You can retain your current
Roadshow setup (keeping all the configuration files, etc.) and have those
parts of Roadshow replaced with the versions which are only available as part
of the commercial release.
In order to perform this upgrade to the commercial release, just start the
installation for the commercial Roadshow version. The installation script will
detect if you currently have a demonstration version of Roadshow installed
(all demonstration versions of Roadshow 1.9-1.14 are supported). If the
demonstration version is found, its libraries and network device drivers will
be upgraded to the current commercial release. The script will then exit.
Please note that if you already have the commercial Roadshow version
installed, then the installation script will prompt you to choose between
making a backup copy of your configuration files and of uninstalling the
Roadshow software. In that case, you might want to choose neither option and
abort the installation instead.
2. Preparations for installing Roadshow
Before you begin you might want to dip into the documentation provided in the
"Documents" drawer. Specifically, the file "Documents/Installation.guide"
should be useful when you are setting up your network for the first time.
Printable versions of the documentation are available in the
"Documents/Printable" drawer. The files in this drawer are in PDF format,
suitable for printing through tools such as APDF or any other program which
can process and output this document format. Note that the big Roadshow
documentation is more than 100 pages in size and may be best used for
3. The installation script
Note that if you want to try Roadshow on MorphOS, then the installation
script may not work for you. Sorry, this is how it is at the moment, and I
do not have any good idea on how to fix this. You can, however, install the
single components of Roadshow manually by copying the contents of the
"Workbench" drawer to your system partition. Careful: do not copy the
"Workbench/S/User-Startup" file! You might want to add the contents of the
"Workbench/S/User-Startup" to your "S:User-Startup" file.
To begin the installation, double-click on the "Install_Roadshow" icon.
The installation script gives you a choice to run in "advanced" or "expert"
mode. Picking "expert" allows for a few more choices to be made than the
"advanced" mode. For example, in "expert" mode you will always be asked if you
want to install a special version of the software, optimized for Amigas with
MC68020 CPUs (or better), regardless of whether your current Amiga computer
supports this (note: only the commercial version includes these specially
optimized versions of the software).
Note that if the installation script detects that Roadshow may be already
installed, it will ask you if you want to uninstall Roadshow first.
The installation script can run in "pretend mode", meaning that if you choose
not install for real, then a log of all installation operations will be
generated instead, for you to review.
Lastly, the installation script can be rerun after you have installed the
software and will give you two new choices: 1) you can choose to uninstall the
Roadshow software previously installed, and 2) you can have it make backup
copies of your current Roadshow configuration files.
4. Installing Roadshow under Amiga operating system version 2
The minimum installation requirements for Roadshow are an Amiga with operating
system version 2.04 and 2 MBytes of main memory. But the tools provided for
reading the documentation may actually require operating system version 3.0 to
work out properly.
This means that you may have to use your preferred document reader or text
editor to open and review the documentation before you can install Roadshow on
your system. The installation procedure for Amiga operating system version 2
should be identical to the procedure used for Amiga operating system version 3
and beyond, though.
If need be, you can also install Roadshow manually by copying the necessary
files to your system partition.
5. Uninstalling Roadshow
Both the demonstration and commercial releases of Roadshow can be uninstalled
by restarting the installation script. It will detect if you currently have
Roadshow installed and then prompt you to choose between making a backup of
your current Roadshow configuration files and uninstalling Roadshow.
To uninstall Roadshow, choose the latter. The script will then proceed to
remove all the files which the installation script copied to your system. When
the script is finished, you should reboot your system as soon as convenient.
Please note that if you do not currently have Roadshow installed on your
system, then the installation script will proceed assuming that you want to
6. The software development kit
The software development kit (not included with the demonstration version:
visit the web site to download it) is provided in the "SDK" drawer, which does
not have an icon to double-click on. This drawer contains documentation,
source code, examples and other files helpful and/or required if you want to
create new software for Roadshow.
7. Creating a stripped-down installation floppy disk
You might want to create a stripped-down version of the installation disk, for
use with installing the TCP/IP stack from a single floppy disk. Here is what
you can do:
- You need to retain the contents of the "Workbench" drawer, the "Installer"
program and the "Install_Roadshow" installation script.
- From the "Workbench" drawer, you will need to remove a few files which
are not strictly essential to the operation of the TCP/IP stack and the
- The following shell commands can be removed to save space:
- If you do not need the PPP/PPPoE drivers to be installed, the following
drawers can be removed:
And you can also remove the following shell commands:
- If you know that you are not going to need the special MC68020-optimized
version of bsdsocket.library, then you can remove the following drawer
and its content:
Alternatively, if you know that the special MC68020-optimized version is
what you need, you can replace the plain MC68000/MC68010 version with
the MC68020-optimized version and then delete the plain version:
Copy Workbench/Libs/020/bsdsocket.library Workbench/Libs
Delete Workbench/Libs/020 ALL QUIET
Note that you can, of course, always copy the relevant files manually back
to your system partition later. It's just that the installation script will
adapt to the missing data and proceed safely if you take care in removing the
files and drawers described above.
Removing all of the files and drawers described above should make enough room
for the remaining installation files to fit onto a single 880K floppy disk.
8. Going back to Miami/AmiTCP/etc. after you have tried Roadshow
Should you find that Roadshow does not compare well to the TCP/IP stack you
were using before, and you need to return it, please note that you must
uninstall Roadshow first. Otherwise, the TCP/IP stack you were using before
will probably not run correctly any more.
This is because the Roadshow installation script places the file
"bsdsocket.library" in your LIBS: folder, and this prevents other TCP/IP
stacks such as "Miami" or "AmiTCP" from working correctly.
So, in order to make "Miami" or "AmiTCP" work again, you should either rerun
the Roadshow installation script (which includes an option to remove the
files it installed before), or delete the file "LIBS:bsdsocket.library"
Roadshow 1.14 (23.08.2020)
- The "bsdsocket.library" version text now includes information which
allows you to quickly verify whether you have the version for all Amigas
installed, or the version which requires at least an 68020 CPU. Also
included is the Roadshow release version which the "bsdsocket.library"
is a part of. In this case, it would be "Roadshow 1.14". To inspect
this information you will need to use the following shell command:
Version full file bsdsocket.library
Please note that this version information will not be printed if you use
the "Version bsdsocket.library" command instead.
- The vsyslog() function in bsdsocket.library did not remove the facility
information from the "priority" parameter and ended up truncating the
severity information instead, which it should have left unchanged.
Thanks go to Patrik Axelsson who reported the problem and provided a
- The WaitSelect() function in bsdsocket.library now waits exactly as
long as the provided timeout requires instead of rounding the time
according to what the 1994 4.4BSD-Lite2 kernel required. This
both simplified operations and avoids possible overflow errors which
might result from the seconds/microseconds conversion.
- If the WaitSelect() function in bsdsocket.library is called with a
zero length timeout (polling), it will update any user-supplied
signal conditions and also check if the interrupt signal had been
set. In previous library versions the results of this update operation
did not match what waiting for a timeout would have produced, triggering
side-effects such as programs stopping as if an interrupt signal had
been sent, with no such signal having been sent.
- Whenever the TCP/IP stack needs to learn about the current system
time it will no longer update a global variable and refer to it
later. Instead, the current system time will be queried and stored
in a local variable. This is a more robust approach since it avoids
side-effects from concurrent Processes and the TCP/IP stack itself
updating the time.
- The "DEVS:Internet/name_resolution" configuration file now supports
a new option which can be either "prefer static" or "prefer dynamic".
The default is "prefer dynamic".
This option selects whether or not dynamically-added DNS resolver
addresses will be used first ("dynamic") or if the DNS resolver addresses
in the "DEVS:Internet/name_resolution" configuration file will be used
first. If the DHCP server provided your Amiga with a DNS server which
is unresponsive or unacceptable, you can now override it.
- The "DEVS:Internet/servers" configuration file now supports a new option
"NOREQ/S" which can be used to make any shell command executed avoid
showing AmigaDOS requester windows, such as prompting for a disk to
be inserted. This should aid in making automation a bit smoother.
- Roadshow version 1.14 ships with an "rsh" command which in the absence
of a more robust "ssh" command could be useful to control other computers
from your Amiga. Roadshow version 1.14 also has a built-in remote shell
server itself, which is disabled by default. In order to enable it, you
would need to add the following line to the "DEVS:Internet/servers" file:
shell stream internal
The "shell" service in the line above is the remote shell service on TCP
port 514 which was first introduced way back in 1977 and is now considered
obsolete and outrageously insecure.
It may still be useful on the Amiga, bringing Roadshow closer to functional
parity with the 1992 "Envoy" product which, too, allowed for remote code
execution and multiprocessing.
Because no security features are implied or enforced by the built-in
Roadshow "shell" service, you should only enable it if you can guarantee
that it will not be misused.
The built-in Roadshow "shell" service enables you to combine several
Amiga shell commands into a single line. These commands must be separated
by ";" characters, like you would do with a Unix shell. The "shell" service
will rewrite the command string, replacing each ";" character with a line
feed, suitable for use with the AmigaDOS shell. This rewrite operation
respects the syntax used by the AmigaDOS shell, only replacing ";" characters
which would otherwise be recognized as introducing a comment text. Please
note that use of ";" may require some tricky escaping/quoting on the "rsh"
- Fixed a long-standing bug (since 2009) in the NetShutdown command which
prevented the shutdown timeout & recall procedure from working. Thanks go
to Timm S. Mueller for finding and reporting it!
- The "rsh" client command has been updated to produce better error
error messages, providing more detail as to what went wrong. Errors
caused by timeouts now show the timeout being exceeded as the problem.
- If the "rsh" client receives an error message from the remote server,
it will now exit with an error status set after having printed the
message. Previous versions only printed the message but failed to
exit, as they should have done.
- The "rsh" client command could corrupt memory while reading and
printing the remote server's output.
Thanks go to Patrik Axelsson for finding this problem!
- The "ftp" client needs at least 12000 bytes of stack space to work properly
without crashing. It now uses a minimum default stack size of 20000
bytes, to be on the safe side.
Thanks go to Patrik Axelsson for finding this problem!
- Rebuilt the "ftp" client with the updated clib2 libunix.a which includes a
fix for the __translate_unix_to_amiga_path_name() function to the effect
that '//' are now correctly dealt with.
- Rebuilt the "tcpdump" command with the updated clib2 libunix.a which
includes a fix for the __translate_unix_to_amiga_path_name() function to
the effect that '//' are now correctly dealt with.
- The "NetLogViewer" program has been updated to render its message list more
quickly and to avoid leaving rendering errors in the display. The program
no longer requires Kickstart 3.0 or better to work, finally making it
compatible with Kickstart 2.04. This in turn means that Roadshow is now
fully Kickstart 2.04 compatible in all its parts.
Thanks go to Patrik Axelsson for showing me that the rendering needed work,
as well as the small bugs still present after all those years!
- The "AddNetInterface" command now makes sure that it has more than 4096
bytes of stack space available. It requires a minimum of 8000 bytes to be
on the safe side. This is to address stack and memory corruption which
seems to have been a problem, and a hard to detect one, too, for a very
Thanks go to Patrik Axelsson who reported the problem!
- Set the default DHCP timeout used by the "AddNetInterface" command to 10
seconds. This used to be 30 seconds, which could make your system startup
stall for much too long if your Amiga had not been connected to the
local network or the local DHCP server was not listening. Ten seconds
should still be more than enough, and you can still override the default,
- Set the default DHCP timeout used by the "ConfigureNetInterface" command to
10 seconds so that it is consistent with what the AddNetInterface command
- The "wget" command now supports the "--timeout" options, and in particular
the "--connect-timeout" option, which required a replacement for the
connection operation. Please note that the connection timeout is limited
to a maximum of 75 seconds due to limitations in how far the TCP/IP stack
allows a connection attempt to linger. You can specify longer connection
timeouts, but in practice the TCP/IP stack will not wait longer than
Thanks go to Patrik Axelsson who pointed out the problem!
- The "wget" command's "--read-timeout" option now works as it should for the
first time. Note that the "--timeout" option still has no effect on the
DNS lookup (neither has the "--dns-timeout" option) because it depends upon
the Unix alarm/signal mechanism which does not exist in this form on the
- The "wget" command could fail to print the correct error message if an
error occurred trying to establish a connection.
Thanks go to Patrik Axelsson who pointed out the problem!
- Rebuilt the "wget" command with the updated clib2 libunix.a which includes
a fix for the __translate_unix_to_amiga_path_name() function to the effect
that '//' are now correctly dealt with.
Roadshow 1.13 (24.4.2017)
- Tomasz Potrykus provided Polish localization files for Roadshow,
"bsdsocket.library", "usergroup.library", "ppp-ethernet.device" and
"ppp-serial.device". Thank you very much!
- The "ping" command sports a new switch which controls how many packets
should be sent ("-c"). This parameter now also implies a test to see for how many
packets sent there were matching responses. If fewer responses were received
than there were packet sent, "ping" will now exit with return code 5, which
can be tested for in shell scripts with "if warn .. endif".
Further switches have been added which control how long packets should be
sent before the program exits ("-t" and "-o").
- Fixed several bugs in "bsdsocket.library", the "SampleNetSpeed" and
"ppp_sample" programs all related to the same problem:
combining GetMsg() and WaitIO() is unsound and may lead to memory corruption
and seemingly random crashes. You either should use GetMsg() or WaitIO(),
but not both in the same context. Thanks go to Sebastian Bauer for finding
the problem and convincing my stubborn self to take this issue more
- The "ConfigureNetInterface" command tested the wrong parameter when checking
the DHCPUNICAST/K parameter. Fixed.
- The 68020+ builds of "bsdsocket.library", "ppp-ethernet.device" and
"ppp-serial.device" no longer crash when opened on plain 68000 or 68010
systems. They now just fail to open at all. I added these tests because of
problems with the Roadshow installation script which were caused by the CPU
type test to mistakenly offer the option to install the 68020+ builds on
plain 68000 or 68010 systems.
- Updated the Roadshow installation script in order to make the test for the
CPU type more robust. It turned out that the "(patmatch ..)" function in
versions of the "Installer" tool prior to V43 does not work as documented.
In fact, that function barely works at all. This problem broke the old
installation script. The new installation script now tests if the CPU type
is "68000" or "68010" in a simpler fashion.
- The "bsdsocket.h" and "usergroup.h" inline header files for use with GCC 68k
have been rebuilt using fd2pragma 1.264 because the versions built with
fd2pragma 1.171 were reported not to work correctly. These rebuilt versions
are now part of the SDK. Thanks go to Anders Ali Lindgren for reporting the
- The "TCP:" handler leaked memory whenever it was opened, 144 bytes to be
precise. Thanks go to Patrik Axelsson who detected the problem and provided
a test case!
- Data received by an open connection and which is never read can accumulate a
lot of memory over time. While the TCP/IP stack will eventually signal to
the remote that the data has not been read by the client yet, so much memory
may have been allocated to hold it that your system runs out of free memory
first. Due to performance considerations, and also because it made the data
reception from the network interface simpler, Roadshow always allocates a
"cluster" of 2048 bytes for each inbound packet, and the received data
remains in that "cluster" until it has been processed, even if only 40 bytes
of memory would have been sufficient to keep it, for example. This can be
problematic in the long run when 20 Megabytes of memory have piled up which
contain only some 32 Kilobytes of unread data.
To address this quirk, new options have been added to the "RoadshowControl"
command. "RoadshowControl set if.receive.useclusters = 0" will make Roadshow
store incoming data using as little free memory as possible, at the expense
of slightly higher processing effort. In this mode the TCP/IP stack should
run much more stable in the long term.
Again, Patrik Axelsson found the problem, provided a test case and tested
the updated bsdsocket.library version. Thank you very much!
- Both the "ping" and "traceroute" commands show greater accuracy when
measuring the lengths of time intervals. As Patrik Axelsson demonstrated,
the measurements taken could be very coarse on the Amiga 2000, using
timer.device version 39. The new measurement method is the most accurate
which the Amiga operating system permits. Again, thanks go to Patrik
for finding the problem and for providing a test case!
- The wget command no longer gets itself into trouble when too little shell
stack space is available. Also, the transmission rate calculation finally
works as intended. The problem was with how the length of time intervals
was calculated, which assumed that the number of microseconds in each
time stamp was stored as a signed number. The processing of the short
form command options (e.g. "-q" for "--quiet") never worked correctly
either, with a bug in clib2 causing the problem.
Both the stack space and the short form command option problems were
reported by Patrik Axelsson. Thank you very much!
ping 4.13 (3.5.2017)
- The main ping loop could wind up checking the state of the
timeout request, even though it had never been used. This
had repercussions because it was then followed by a WaitIO()
call on the timerequest, which implies a Remove(), triggering
an Enforcer hit. Thanks go to Patrik Axelsson for spotting
- The average round-trip time printed is no longer rounded to
microsecond precision. The rounding had curious side-effects when
printing the average round-trip time for a single packet,
which did not equal the minimum and maximum round trip
- All trip times are now printed with a fixed number of digits
(three) following the decimal point. Also, the trip time is
always printed as a series of digits and the decimal point,
never in scientific notation (mantissa with exponent).
- An invalid "-t" option value is no longer ignored, but results
in an error message being printed and the ping command exiting
with a failure code set.
Roadshow 1.12 (5.10.2016)
- Added new API functions for use with name resolution in order to make it
easier to port application software. The new functions include the BSD
style gethostbyname_r() and gethostbyaddr_r(), as well as versions of
getaddrinfo(), gai_strerror(), freeaddrinfo() and getnameinfo() which
are currently restricted to IPv4 addresses.
- Processes which share the same library base can now safely perform
overlapping name resolution operations, without danger of corrupting each
other's query results.
Please note that the gethostbyname_r() and gethostbyaddr_r() functions need
to be used to be completely safe from accidental corruption.
If your code still uses gethostbyname() or gethostbyaddr() then the recent
changes will make the name resolution much more robust, but because the
functions share state information which is available only once (as part of
the library base) conflicts are still possible.
- Reworked the ftp client command, improving robustness. This means that
buffer overrun issues have been corrected which had remained unfixed since
- The AddNetInterface and ConfigureNetInterface commands, as well as
bsdsocket.library itself, have been enhanced to allow for the DHCP server
to send address offers using unicast datagrams. Previously, only broadcast
datagrams were supported.
The unicast support brought a small bug to the surface to the effect that
bsdsocket.library never asked the DHCP server to respond with a broadcast
datagram. This bug has been fixed.
- The bsdsocket.library API function QueryInterfaceTags() tag
'IFQ_HardwareAddressSize' would copy more than 16 bytes for the hardware
address. In fact, it would copy as many bytes as there were bits in the
address (usually, that would be 48 bytes). This bug could cause
the ShowNetStatus command to crash and has been fixed in
- By request a new ready-made network interface configuration file has
been added, for use with the "cnet16.device" driver. This file is found
in the "Storage/NetInterfaces" drawer and is called "CNet16".
- The TCP/IP stack's internal timekeeping relies upon the system time
(as counted in microseconds) to increase "monotonously". This means that
as time passes, the system microsecond counter only ever increases and
never decreases, and (hopefully) never stays the same.
However, this was never guaranteed because you could manually change the
clock time, or a tool could automatically switch between daylight saving
time and back. These clock changes could cause Roadshow to drop
name resolution and routing entries prematurely, and it could also
trip up the TCP protocol's time measurements.
bsdsocket.library has been updated so that it is no longer sensitive
to system clock time changes. Changing the system clock time can no
longer result in cache entries getting dropped, or the TCP protocol's
time measurements to slip.
Ingo Schmitz and Harald Meinzer kindly tested the 68000 version of
the updated bsdsocket.library (version 4.321). Thank you very much!
Roadshow 1.11 (9.11.2013)
- Improved the robustness of the ppp-serial.device and ppp-ethernet.device
drivers on Amiga computers with 68000 and 68010 CPUs. Thanks go to
Christian Vogelgsang for raising the issue and testing the changes.
- The version of ppp-serial.device intended for all Amigas no longer allows
Van-Jacobson header compression when running on an Amiga with a 68000 or
68010 CPU. This restriction may be lifted in a future version of the
- The ppp-ethernet.device no longer supports Van-Jacobson header compression,
because that feature is not supported by the PPPoE protocol anyway.
- Replaced the copying routines in the bsdsocket.library version intended
for all Amigas, specifically those with 68000 and 68010 CPUs. This change
was prompted by the investigation which led to the robustness improvements
for the ppp-serial.device and ppp-ethernet.device drivers. The version of
bsdsocket.library for Amigas with 68020 CPUs (or better) is essentially
the same as before, with its version number bumped to match the library
version for all Amigas.
- The documentation no longer recommends tweaking the tcp.do_timestamps
and tcp.do_win_scale settings.
Roadshow 1.10 (19.10.2013)
- Added a ready-made, new network interface configuration file for the
"X-Surf 100" Ethernet card.
- The "ftp" command did not process the "host" parameter correctly, and
the optional "port" parameter was ignored. Thanks go to Alexandre Balaban
for finding the issue.
- The "ppp_connector", "ppp_dialer" and "ppp_sample" commands have been
replaced with the correct versions, suitable for "classic" 68000-based
Amigas. Previously, these commands were built to run only on AmigaOS 4;
I had accidentally copied them from the wrong distribution drawer :-(
- The optimized IP/TCP/UDP checksum calculation and verification code in
the bsdsocket.library version intended for all Amigas (with 68000 and
68010 CPUs, too, such as the A500, A2000 and A600) was not stable and
had to be replaced by the portable version. This change fixes crashes on
these Amiga types. Amigas with 68020/030/040/060 were unaffected by
these problems. Thanks go to Thorham for verifying the fixes.
Roadshow 1.9 (24.2.2013):
- Network interface names cannot be longer than 15 characters. Shame
on me, I did not remember this when I added the new MorphOS
interface files. Network interface file names have been changed
Freescale-MPC52xx -> MPC52xx
Marvell-Discovery-II -> Discovery-II
Poseidon-Asix -> Asix
Poseidon-Davicom -> Davicom
Poseidon-MosChip -> MosChip
Poseidon-Pegasus -> Pegasus
Realtek-RTL8139 -> RTL8139
- USB device driver names have been corrected for the Asix, Davicom and
MosChip network interface configuration files.
- The documentation has been updated to explain in greater detail how
the "DEVS:Internet/servers" configuration file looks like, and how one
may convert "inetd.conf" configuration data so that it matches the
format of "DEVS:Internet/servers".
- Added ready-made configuration lines to the "DEVS:Internet/servers"
files for use with the Samba server suite. These lines have been
commented out and can be easily reactivated after you have installed
Samba on your Amiga (take care, installing Samba is a challenging
Roadshow 1.8 (19.1.2013):
- Added more example network interface files for use with MorphOS:
"Freescale-MPC52xx", "Marvell-Discovery-II" and "Realtek-RTL8139".
Roadshow 1.7 (19.1.2013):
- Updated the example network interface files "SunGEM" and "VIA-Rhine"
to include the line 'state=online', which switches the respective
network device drivers online even if DHCP configuration is not used.
Roadshow 1.6 (10.1.2013):
- Modified AddNetInterface (4.52) to switch an interface online prior to
starting DHCP negotiation. This improves compatibility with the MorphOS
"sungem_eth.device" and "via_rhine_pci.device" drivers.
- AddNetInterface now supports "up", "down", "online" and "offline" as
parameters for the "state" configuration file option.
- Updated AddNetInterface source code is now part of the SDK.
- Added example network interface files "SunGEM" and "VIA-Rhine" for MorphOS.