
==================
BONE BETA 7 README
==================

HOW TO INSTALL BONE:

If you are reading this, you presumably have unzipped the bone_install.zip
file and you now have a 'bone_install' directory somewhere on your disk.
To install BONE, follow these steps:

1) Launch the Terminal application.

2) In Terminal, change directory to the 'bone_install' directory that you
   created when you unzipped bone_install.zip.  If you unzipped
   bone_install.zip onto your Desktop, this command would be
   something like 'cd /boot/home/Desktop/bone_install' followed by the
   Enter key. 

3) Type 'sh ./do_bone_install' in the Terminal and then press the Enter key.
   This will run the BONE installer script.

4) The installer script will run, installing the BONE components,
   copying your existing network settings, and backing up components
   of the pre-BONE networking system (which is called the net_server).
   After the script runs it will prompt you to press a key to reboot
   the system.

   If you're one of those people who wants more details on what exactly
   the do_bone_install script actually does, here's a relatively complete
   list:

   * Converts your current net settings into configuration files usable
     by BONE, BIND, etc.

   * Replaces /system/boot/Netscript with a shell script that configures
     BONE.

   * Installs BONE binaries, modules, scripts, and libraries.

   * Replaces libnet.so with BONE compatibility libnet.so. 

   * Replaces kernel and selected applications.

   * Reboots machine

5) Upon reboot, your system should be up and running with BONE with
   your previous network settings.  The Network preferences panel is
   still on your system, but will not be functional.  You must use the
   Boneyard preferences program to configure BONE.


HOW TO UNINSTALL BONE:

If you run into problems after installing BONE, or just want to go back to
the previous networking system, we have provided an uninstaller.   The uninstaller
has not been extensively tested, but we believe it will work for most people.
To uninstall BONE, follow these steps:

1) Launch the Terminal application

2) Type 'cd /boot/home/net_switch' into the Terminal and then press the Enter key.

3) Type './setnetserver' and then press the Enter key.  This program will restore
   the older programs and configuration files that were on your
   system before you installed BONE. 

4) Reboot the machine by selecting "Restart" from the Deskbar menu.

5) Upon reboot your system should be running the old net_server networking
   system again using the settings that were in place before you installed
   BONE.


BETA FEATURES/DISCLAIMERS:

WARNING! Installing this beta will break printing support!  The BeOS 5
printing system used some features of the net_server to provide Appletalk
support that are not available with BONE.  If you need to print, don't
install BONE.  The Printers preference panel will not run after BONE is
installed.  We realize that this is unfortunate, but our preferred solution
entails quite a bit of additional engineering work that we cannot undertake
right now.

The following protocols are supported in the BONE beta:

TCP, UDP, IPv4, ICMP, PPP/PPPoE, and their associated helpers (ARP, LCP, etc.).

A raw sockets interface is also provided.

IPv6 is planned to be added (eventually).

Multiple network cards are supported.  Routing between them is currently enabled, and
support for IP aliasing (NAT) is included.

ISC BIND 8.2 is provided.

ISC DHCPd 2.0 is provided.

CIFS support is only available via the 'cifsmount' command-line utility. The 'World O Networking' network browser is currently broken.

Applications which have been added or modified by this beta include:

Boneyard - Bone GUI configuration tool.
dhclient -Dynamic Host Configuration Protocol Client (use dhconfig when possible)
dhconfig - BONE kernel dhcp client configuration tool
dhcpd - Dynamic Host Configuration Protocol Server
dhcrelay - Dynamic Host Configuration Protocol Relay Agent
dig - send domain name query packets to name servers
dnskeygen - generate public, private, and shared secret keys for DNS security
dnsquery - query domain name servers using resolver
ezmount - 'cifsmount' wrapper script
finger - user information lookup program
ftp - ARPANET file transfer program
ftpd - DARPA Internet File Transfer Protocol server
host - look up host names using domain server
ifconfig - network interface configuration tool
inetd - internet super-server
ipalias - BONE kernel IP Aliasing (NAT) configuration tool
named - Internet domain name server (DNS)
named-bootconf - convert name server configuration files
named-xfer - ancillary agent for inbound zone transfers
ndc - name daemon control program
netperf - network performance measurement tool
nslookup - query Internet name servers interactively
nsupdate - update Internet name servers interactively
ping - send ICMP ECHO_REQUEST packets to network hosts
pppconfig - BONE kernel PPP configuration tool
rhdaemon - RobinHood webserver
RHConsole - RobinHood GUI tool.
route - show / manipulate the IP routing table
tcpdump - dump traffic on a network
tcptrace - tcpdump analysis tool
telnet - user interface to the TELNET protocol
telnetd - DARPA telnet protocol server
traceroute - print the route packets take to network host

netstat is still pending.

drivers, kernel components, and libs which have changed or have been added

- TTY Module, tty/pty/zz drivers: select() support
- Kernel: select() bug fixes
- cifs filesystem
- lucent modem driver: updated to use new tty module
- TLan ethernet driver: bug fixes and performance modifications.
- DEC (tulip) ethernet driver: bug fixes, performance modifications, Cardbus support.
- Netmate USB ethernet driver: new experimental USB ethernet driver.
- tcm589 and tcm509 ethernet driver: PCMCIA and ISA 3Com cards.
- dp83815 ethernet driver: National Semiconductor Ethernet chip; used in Netgear FA311
- rtl8139 ethernet driver: RealTek Ethernet chip.
- ne2k ethernet driver: New NE2000 Ethernet driver.
- prism 802.11 ethernet driver: experimental driver.
- vt86c100 ethernet driver: experimental driver.
- Wavelan 802.11 ethernet driver: experimental driver.
- libroot.so: modified to include select(), getpw*(), etc.
- libpcap.a: packet capture lib.
- libnet.so: lib to provide binary compatibility with existing network apps.
- libbind.so: BIND 8.2 shared lib
- libsocket.so: new socket library


CONFIGURATION

The new preference applet "Boneyard" replaces the "Network" and "Dial-Up-Networking"
preference panels, and allows you to configure all parts of BONE.


The various parts of BONE get their parameters from various files (all can be configured
with Boneyard):
- the machine's hostname is stored in '/etc/hostname'
- DNS server addresses and important domain names are stored in '/etc/resolv.conf'
- '/etc/hosts' contains host addresses/aliases - note that, by default, this file is checked only
	AFTER a DNS lookup fails (with the net_server, it was checked before the DNS lookup)
- '/etc/network.conf' contains interface settings (IP address, etc.) entered into Boneyard, and
	read by the Netscript
- '/etc/inetd.conf' specifies which network services your machine will provide (telnet, ftp, etc.)


In addition to using Boneyard, network settings can be configured manually from a command line:
- 'ifconfig' configures interfaces (sets IP address, netmask, flags)
- 'route' configures routes
- 'dhconfig' sends commands to the dhcp client
- 'pppconfig' configures PPP/PPPoE interfaces (see example profiles in /etc/dialer)
- 'ipalias' configures BONE's NAT engine

Note that any changes made using these tools are NOT persistant (i.e., they will be reverted
when you reboot or next use Boneyard).


DEVELOPMENT

BONE's headers are installed in /boot/develop/headers/be/bone.

NOTE: Installing BONE will delete outdated network header files. You will need to manually reinstall these files and delete the BONE headers to develop net_server compatible apps. BONE is not "source-compatible" with the net_server.  Certain APIs supported
by/through the net_server no longer exist in BONE:
- the net_settings API (find_net_setting(), etc.) is not part of BONE, and should not be
	used in new development
- the net_server's add-on API is not part of BONE, and cannot be used in new development

New network code must be linked against libsocket.so and libbind.so, NOT libnet.so.
Binaries compiled with BONE's headers, but linked against libnet.so will not function!

Several socket options and ioctls in the headers are not implemented.  The following
definitely are implemented:

Socket ioctls:

FIONBIO
FIONREAD
SIOCADDIFACE
SIOCADDRT
SIOCDELRT
SIOCGRTSIZE
SIOCGRTTABLE
SIOCSIFADDR
SIOCGIFFLAGS
SIOCGIFCOUNT
SIOCGIFCONF
SIOCGIFINDEX
SIOCGIFNAME
SIOCSIFNETMASK
SIOCSIFMTU
SIOCSIFMEDIA
SIOCGIFMEDIA
SIOCSIFRECVPORTID
SIOCSIFTRANSPORTID
SIOCSPACKETCAP
SIOCCPACKETCAP


General socket options:

SO_SNDTIMEO
SO_RCVTIMEO
SO_NONBLOCK 
SO_LINGER
SO_BROADCAST
SO_REUSEADDR
SO_OOBINLINE

TCP options:

SIOCATMARK
SO_SNDBUF
SO_SNDLOWAT
SO_RCVLOWAT
TCP_NODELAY
TCP_MAXSEG
TCP_NOPUSH
SO_RCVBUF



UDP options:

UDP_CHECKSUM


IPv4 options:

IP_HDRINCL


Note that certain non-standard behaviors in the net_server which are bad and evil
but may nevertheless be exploited by some apps (for example, unblocking a receiving
thread by calling socket functions on the same socket in another thread) will
no longer work.  Call it the price of stepping up to a real networking
implementation.  It is now perfectly fine to use one thread to reveive data
and one thread to send data simultaneously on the same socket.  And there was
much rejoicing.

To develop in-kernel network services such as net filesystems,
use the socket module interface in socket_module.h.  It is accessible
by doing a get_module on network/bone_socket.

If you need information for developing BONE protocol modules, please contact
bone-devel-help@be.com for help.

Please file bugs in the bug database under bone/misc for now.


LEGAL STUFF:

Portions of this distribution are Copyright (c) 1993-1999 by
Internet Software Consortium.

This product includes software developed by the University of California,
Berkeley and its contributors.

This product contains software developed by Carnegie Mellon University.

