Included in this document are the following areas:

Setting up an Initial QNX4 Network
Adding More Machines
Adding a Second Network
Fault Finding

Setting up an Initial QNX4 Network

QNX is a network distributed operating system that allows users on any node (with appropriate priveleges) to access any file or device on any other node. This powerful feature is built into the heart of every QNX system but like any system it needs to be configured correctly before it can be fully utilised. This technote will take a step by step approach to setting up a QNX network and give some hints on troubleshooting.

The scenario is that we have two machines onto which we have just installed QNX, using the default installation process. We are going to connect these two machines using an Ethernet network. See Figure 1.

Step 1: Changing node numbers

QNX uses a logical node address so that it can differentiate one computer from any other computer on a network. Each machine is given a number, starting at one and incrementing every time a new machine is added to the network. The default QNX installation makes every computer node 1 and this is fine for all standalone systems. We will need to change one of the machines to recognise itself as node 2.

Change directory to where the build files are kept:
```
cd /boot/build
```
Copy the existing build file to the new one:
```
cp hard.1 hard.2
```

Edit the new build file to make the changes necessary. You can use whichever editor you feel most at home with but your build file wants to look like this. Only the changes necessary are highlighted.

sys/Proc32
$ 52000 Proc32 -l 2  
 
sys/Slib16
$ 1 Slib16
 
sys/Slib32
$ 1 Slib32
 
/bin/Fsys
$ 8000 Fsys
 
/bin/Fsys.aha7scsi
$ 1000 Fsys.aha7scsi 
 
/bin/mount
$ 1000 mount -p /dev/hd0 /dev/hd0t77 /
 
/bin/sinit
$ 1000 sinit  TERM=qnx

Save the file and change up one directory:

cd ..

Now we need to build the new boot image. This is the set of instructions that start QNX and tell it how to configure itself:
```
make b=hard.2
```
When this has finished we need to copy the newly created boot file into the correct place and we'll make a backup of the old one just in case things go wrong:
```
cp /.boot /.altboot
cp images/hard.2 /.boot
```
Now we need to copy the system initialisation file to it's new place:
```
cp /etc/config/sysinit.1 /etc/config/sysinit.2
```

Step 2: Installing the licenses

This must be done on both machines

Each set of QNX master disks contains an electronic license which is required for the system to operate. In a networked system each machine must have all available licenses so that it 'knows' how many other machines it can talk to. Licenses can only be transferred onto hard disk using the license command. Any attempt to copy, move, rename or back them up will render them useless.

The licenses are kept on the install disk 1 of the set. Insert the first disk into the drive and, as root, enter:
```
license
```
When prompted change disks and hit enter. When both licenses have been installed press n to finish.
The licenses are now installed on disk but QNX's in memory database needs to be updated as this is where requests are routed to. To do this:
```
license -r
```

Check that the licenses have been installed and recognised. To do this enter:

sin info

and the output will look like this:

Node   CPU    Machine Speed     Memory    Ticksize   Display            Flags
  1  586/587   PCI    16629 18504k/31744k 10.0ms   VGA Color D3P-----------8P
 
Heapp Heapf Heapl Hands Names Sessions Procs Timers Nodes  Boot
29616 27428  5916    32    30       32   150     40     2  Hard at Oct 05 11:28
 
Locators: 1

If the number in the nodes doesn't match the number of disks that you put in then retry, making sure you use install disk 1. If you still have problems contact your supplier.

Once this has been verified reboot the system so that it will now come up as node2. If the system doesn't come up switch it off and on again and when QNX displays the message:
```
Press ESC for alternate OS
```
Quickly hit the ESCAPE key. This will boot the old boot image (the one we copied to /.altboot) and the system will be exactly as it was before so you can go back and carefully review what you did and try to put it right.

Step 3: Configuring the Network

This must be done on both machines

As we have seen QNX supports the idea of a logical network node number. This makes it easier to use than the unwieldy numbers that are used to identify each individual network card. Unfortunately, the network cards are reuired to use these numbers in their communication with each other. We must tell QNX about these numbers and how they correspond with the logical numbers we have given each system.

This is done in the file /etc/config/netmap which looks like this:

one-to-one

What we must do is change this file to relflect our network. We have two machines and two NE-2000 Ethernet cards. Each of these cards has an Ethernet address, written on a sticker somewhere on the card. Ours have the addresses:

02DF1E 012354
02DF1E 013258

So our /etc/config/netmap would look like this:

1	1	02DF1E012354
2	1	02DF1E013258

NOTE:There is a carriage return after the last line.

This tells QNX that we have two nodes, one and two and they are connected via network one (QNX also support more than one network in a machine so we need a way of differentiating those as well.) and how the physical address of the network card corresponds to the logical address we have given each machine.

Step 4: Starting the Network Software

This must be done on both machines

QNX was designed to be a very efficient system and the networking is no exception to this. All of the clever tricks that QNX networking does are performed by the Network Manager, Net. Net doesn't contain any code that accesses hardware, it has a family of device drivers that do that. This keep sthe system as small and efficient as possible by allowing you to only start the network device driver that you need and not have a lot of unused code using valuable system resources.

Start the Network Manager:
```
Net &
```
The ampersand is used to run Net in the background, otherwise it would lock the console up and prevent the user from entering any more commands.
Start the network device driver:
```
Net.ether1000 -i 10 -v &
```
The -i 10 tells the driver that the card is configured for Interrupt 10. This is usualy enough for the driver to work out everything else about the card. If it isn't other options can be specified on the command line. Typing:
```
use Net.ether1000
```
will display the options available.
The -v option tells the driver to print out some information about the card as a check that it is running OK. This can be left out.
Now we have the Network Manager and a device driver running all we need to do is explain to QNX about our network:
```
netmap -f
```
The -f tells netmap to read from the file /etc/config/netmap. There are other options to netmap that allow us to manually describe our network or to read the description from another computer running QNX.
Test the network by entering the following command from node 1:
```
sin -n 2
```
You should see a list of all proceses running on node2. If it returns with
```
sin: unable to connect to node 2 (No route to host).
```
then something is wrong. See the section on fault finding for more details.
Add the commands above to the system initialisation file so that they are started every time the machine is switched on.

Adding More Machines

Here we will discuss adding a third machine to the setup described above. Adding a fourth or fifth or hundredth follows exactly the same procedure described here. There are also some shortcuts you can use when the number of machines becomes too unwieldy to update by hand.

We will assume that you have gone through the default installation and have a standalone QNX system running on the new machine.

Step 1: Changing node numbers

This is pretty much the same as configuring for node 2, except you're using a 3. Here it is again to show you exectly what I mean.

Change directory to where the build files are kept:
```
cd /boot/build
```
Copy the existing build file to the new one:
```
cp hard.1 hard.3
```

Edit the new build file to make the changes necessary. You can use whichever editor you feel most at home with but your build file wants to look like this. Only the changes necessary are highlighted.

sys/Proc32
$ 52000 Proc32 -l 3  
 
sys/Slib16
$ 1 Slib16
 
sys/Slib32
$ 1 Slib32
 
/bin/Fsys
$ 8000 Fsys
 
/bin/Fsys.aha7scsi
$ 1000 Fsys.aha7scsi 
 
/bin/mount
$ 1000 mount -p /dev/hd0 /dev/hd0t77 /
 
/bin/sinit
$ 1000 sinit  TERM=qnx

Save the file and change up one directory:

cd ..

Now we need to build the new boot image. This is the set of instructions that start QNX and tell it how to configure itself:
```
make b=hard.3
```
When this has finished we need to copy the newly created boot file into the correct place and we'll make a backup of the old one just in case things go wrong:
```
cp /.boot /.altboot
cp images/hard.3 /.boot
```
Now we need to copy the system initialisation file to it's new place:
```
cp /etc/config/sysinit.1 /etc/config/sysinit.3
```

Step 2: Installing the licenses

This must be done on all machines

As mentioned before each QNX machine must contain enough licenses for it to be able to communicate with ALL other machines on the network. This means that we must put the new license on nodes 1 and 2 and put all threee licenses on node 3. This is done using the license command. See the earlier notes for exact details.

if you are adding the 20th machine to your network then updating 20 machines and juggling all those disks is a real nightmare. There is a simpler way. Install all 20 licenses on node 20 and put the new license on node 1. From each of the nodes 2 to 19 run the following commands:

license //1/etc/licenses /etc/licenses
license -r

This will allow the other machines to take the licensing information from node 1 and copy it to their own local database. It is possible to automate this process by using a shell script.

Step 3: Configuring the Network

This must be done on all machines

We must tell QNX about our new network and to do this we need to add the new machine's details into every /etc/config/netmap. If the new card has a node address of:

02DF1E 132540

our new file will look like this:

1	1	02DF1E012354
2	1	02DF1E013258
3	1	02DF1E132540

NOTE:There is a carriage return after the last line.

This must be done on each machine in the network. If you have 20 nodes you need only manually alter the first and last and copy the rest from node 1:

cp //1/etc/config/netmap /etc/config/netmap

This process could be included as part of the shell script that updates the licenses.

Step 4: Starting the Network Software

This is the same as step 4 in the previous example, except we are only starting the drivers on the new machine as the rest are already running them.

Adding a Second Network

Taking the three node example above we will expand it to include a second network. This will give us betterf network performance and fault tolerant networking. We are aiming for something that looks like figure 2:

We are installing a second Ethernet but you could use any network type, just as long as you start the correct QNX device driver for it. Out two new Ethernet cards have the address:

0ACF12079685
0ACF12789543

Step 1: Install the Cards

Power off the machines and install the network adapters in nodes 1 and 3, taking note of the settings of the card just in case we need to give more infomration to the QNX device driver later.

Step 2: Starting the Drivers

Net is already runnig so all we need to do is start the drivers for the second network.

Net.ether1000 -l 2 -vv &

Here we are telling QNX that this is the driver for the second network attached to our system using the option -l 2. We've also asked QNX to give us more infomration about the card and driver startup than it normally would using -vv.

Step 3: Configuring Netmap

This MUST be done on nodes 1 and 3

All we have to do is to describe our network setup to QNX and it should be ready to go. This is in the /etc/config/netmap file and we'll need to change it so that it looks like this:

1	1	02DF1E012354
1	2	0ACF12079685 
2	1	02DF1E013258
3	1	02DF1E132540
3	2	0ACF12789543

Once the file has been saved force the changes to take effect by issuing the command:

netmap -f

Step 4: Testing the New Connection

To test the new connection we just unplug the cable on the original network and enter the following command from node 3:

sin -n 1

It should behave just the same as the test we did when we installed the first network.

Fault Finding

This section explains and deals with common problems encountered whilst setting up a QNX network.

Licenses

If there is no conection it may be possible that insufficient licenses have been installed on a machine. Generally, the rule is that every QNX machine on a network must contain a copy of ALL licenses on that network. The way to check this is to type:

sin info

and examine the nodes column. The number here should equal the number of nodes you have on your network. If it doesn't you will need to re-install the licenses from floppy disk or from another node, using the license command.

If you have a machine that has been installed as node 1 and you change it to node 5 and then install 4 extra licenses they won't be recognised. You should install the extra licenses first and then change the node number.

At any time the licinfo command will tell you what each node thinks is going on with the licenses available, how many it knows about, how many it thinks are being used and by which node.

Cabling

Network Cards

Generally, just starting the driver will be enough for QNX to auto-detect the hardware. Sometimes this isn't the case so use the command line options to the device driver to specify as much information about the card as you can. The -v option is especially useful in obtaining more information about what the device driver is doing and what it has found. You can specify up to 4 -v's on a command line

QNX supports a wide range of network adaptors and more are being added. Please contact your dealer for more information.

Network Diagnostics

Most of the information you will ever need to know about network problems can be found by using netinfo. Netinfo displays the contents of Net's in-memory event log. Th eoutput will be in the following format:

Date      Net  (Nid|Status)   Code   Description
16:16:37   0   Logical 10     (35)   NET logical node not in netmap

Explanation of fields

Timestamp of the event. The format of this can be changed with the -f option to netinfo.
Which logical network the error or event occurred on. In this example 0 is an invalid logical network because the error occurred at a higher level, inside the Network Manager.
Information associated with the event, maybe a logical or physical Node ID or a status number. Generally, it is the most appropriate piece of information for the event.
A unique error code. Ranges are reserved currently:
- 1-99 Net
- 100-199 Net.arcnet
- 200-299 Net.ether8003
- 400-499 Net.ether503
- 500-599 Net.ether1000
- 600-699 Net.tr164a
- 700-799 Net.fd
- 800-899 Net.tr164a
- 1000-1099 Net.star
- 1100-1199 Net.ether2100
- 1200-1299 Net.wavelan
- 1300-1399 Net.fddidfe
- 1400-1499 Net.ether9000
- 1500-1499 Net.ether21x40
This is a short textual description of the event. Use netinfo -a to see all posible codes.