| Title |
OEM Procedures for delivering run-time solutions to customers |
| Ref. No. |
QNX.000009531 |
| Category(ies) |
Utilities, Installation, Development, Configuration |
| Issue |
OEM Procedures May 25, 95
With QNX's modular architecture, many possibilities exist when creating run-time environments for your customers. With these many variations come many questions. The intention of this document is to describe some of the possibilities available with a QNX OEM contract.
Note:
Throughout this document, the title 'you' refers to the company making the OEM agreement with QNX Software Systems, the title 'we' refers to QNX Software Systems, and the title 'customer' refers to the OEM's customer (your customer). |
| Solution |
A typical OEM arrangement goes something like this:
A. You decide which software pieces you need for your target system. This
typically involves discussions with your QNX sales representative and your
QNX support engineer.
These pieces are then documented and described in your OEM contract.
B. Then, you decide how you wish to distribute your target systems. There are
many, many ways of doing this.
For example: - you provide a 'black box' to your customer. You will
install the software on the systems for the customer and
provide them with a complete pre-installed environment.
- you contract out to a third party to make your target
systems for you.
- you provide your customers with diskettes with which they
will install the OS and your software.
- you provide your customers with non-diskette media
(tapes, CD-ROMs etc.) with your software on it.
etc..
C. You setup a master target system that has all the software that your
system needs. This master system will become the template that you will
use to make your media for distribution.
D. Once C is done, then you can begin the duplication process.
There are several questions that arise:
How will your customer install the software?
How will they boot?
How do you make a boot diskette?
How do you and the customer ensure that licensing is correct?
It is assumed that you have already finished steps A, B and C. This document
will describe the issues related to licensing, booting, duplicating floppies,
making bootable floppies etc.
Making an Archive of the Software
-----------------------------------------------------------
The first thing you will likely want to do now is to make an archive of all
the software that will be part of your target system.
This the way that we (at QNX Software Systems) make our systems.
This implies that the amount of software you need to archive is not too
big ( under 50M for example .. so that you can store it on a harddisk ).
To do this:
A. Make a list (1 file per line) of all of the files that you need to archive
for your system.
e.g. a file called 'Master.file.list' could contain:
/boot/sys/Proc32
/boot/sys/Slib32
/config/sysinit /bin/sin
/bin/Fsys
/bin/Fsys.ata
etc..
To make this list you could use the 'find' utility.
e.g. find / >Master.file.list
** make sure that you do not include the /.boot and /.altboot files in
this list. They cannot be archived using pax.
** make sure that you only include in this list the files that you are
allowed to copy based on your OEM agreement.
** make sure that you don't have any block-special files in this list
(e.g. don't include files like /dev/hd0, /dev/shmem etc.)
B. Once you have this list, then you can make an archive file.
Give the archive a unique name based on your version and date of software.
e.g.
pax -wv <Master.file.list >archive.May15-95.pax
C. You may wish to freeze the archive in order to conserve space. You can
either freeze the archive made by pax after it's generated
e.g. freeze archive.May15-95.pax
OR a better way would be to freeze the archive as you make it.
e.g. instead of the command in B above, use:
pax -wv <Master.file.list | freeze >archive.May15-95.pax.F
D. Now you have a complete frozen version of your software. The only other
pieces you need are the licensing files (/etc/licenses) and the boot
files (/.boot, /.altboot)
Now you can use this archive to distribute your software. There are many
ways you can distribute. We'll look at several ways in detail:
- 'Black Box' approach .. you install software for your customers
- floppy approach .. you provide floppies to your customers and they
install the software.
The 'Black Box' approach
------------------------
In this arrangement, you will be providing your customers with fully
installed systems. The customer will not be required to install the software.
A typical duplication procedure can be as follows:
A. Network
Master system New system (target)
(Node 1) (Node 2)
^ ^
|_____________________________________|
network link (or serial)
If your master system and the target are both on the network then you
can copy files using the network link.
1. Boot node 2 from node 1 (using a BOOT ROM)
2. Start a filesystem on node 2 and mount a disk driver
3. Dinit the disk on node 2 (with all bad blocks marked etc.)
4. Then, install the archive (e.g. archive.May15-95.pax.F) over to node 2's
filesystem.
There are several ways of doing this. The easiest is by using the -s
option on pax.
For example:
- Your archive is made up of files that all reference the root /
e.g. /boot/sys/Proc32
/bin/sin
etc.
- Your node 2 filesystem is mounted as /hd (your root filesystem
/ is still being referenced off of your boot node 1)
- To transfer the files over to /hd do:
fcat archive.May15-95.pax.F | pax -rv -s ",/,/hd/,"
All files will be put on the /hd drive
5. Once the files are brought over then you need to transfer the licensing
that you need over to /hd/etc/licenses
Make a directory /etc/licenses on the /hd filesystem (node 2)
Use the 'license' command to transfer only the license files that you
require over to /hd
e.g. license /etc/licenses/qnx0000001n001 /hd/etc/licenses
Do this for all the licenses that you require on your target system.
See the section on 'How OEM Licensing Works' for more details.
6. If you have any specific boot files that you need on the target (node 2)
then copy them to /hd/.boot
e.g. cp /.boot /hd/.boot
cp /.altboot /hd/.altboot
7. At this point you should be able to disconnect node 2 from the net and
boot it standalone.
B. A second disk drive
Master system
(Node 1)
hard drive 1 (/) is the master
hard drive 2 (/hd2) is the second hard drive that you are setting up
1. Mount the second hard drive as /hd2
2. Dinit the second hard drive (with all bad blocks marked etc.)
3. Then, install the archive (e.g. archive.May15-95.pax.F) over to /hd2
There are several ways of doing this. The easiest is by using the -s
option on pax.
For example:
- Your archive is made up of files that all reference the root /
e.g. /boot/sys/Proc32
/bin/sin
etc.
- Your second drive is mounted as /hd2 (your root filesystem
/ is still being referenced off of your first hard drive)
- To transfer the files over to /hd2 do:
fcat archive.May15-95.pax.F | pax -rv -s ",/,/hd2/,"
All files will be put on the /hd2 drive
4. Once the files are brought over then you need to transfer the licensing
that you need over to /hd/etc/licenses
Make a directory /etc/licenses on the /hd2 filesystem
Use the 'license' command to transfer only the license files that you
require over to /hd2
e.g. license /etc/licenses/qnx0000001n001 /hd2/etc/licenses
Do this for all the licenses that you require on your target system.
See the section on 'How OEM Licensing Works' for more details.
5. If you have any specific boot files that you need on the target
then copy them to /hd2/.boot
e.g. cp /.boot /hd2/.boot
cp /.altboot /hd2/.altboot
6. At this point you should be able to remove the second drive, put it in
a separate machine and boot.
The Floppy approach
-------------------
A slightly more complex example involves the use of floppies.
What you want to do is to use vol to put your archive onto a set of floppy
disks that will become your 'archive set'.
Here are the steps:
1. Check to see how many floppies you'll need
du -ps <archive.May15-95.pax.F
This will display the total archive size in bytes. From this you can
estimate how many floppies you require.
2. Format as many diskettes as you need for the archive.
3. To put the archive on floppies, use the vol command
vol -ws2 /dev/fd0 <archive.May15-95.pax.F
4. You now have an archive set with all your required software, including
OS modules, OS utilities and application software.
5. What do you do now about licensing and booting?
If you are using floppies then you will need a special boot floppy
that the customer can insert in their machine and then boot.
See the section on 'Making a Boot Floppy' for details.
As well, the customer must install licenses. See the section on
'Licensing Options for Floppies'
Also see the section on 'How OEM Licensing Works' for more details.
-----------------------------------------------------------------------------
How OEM Licensing Works
-----------------------------------------------------------------------------
Before we discuss how you provide QNX licensing to your customers, it would
be useful to describe the rules of licensing.
Licensing Rules
---------------
There are several important rules to know about using licenses:
1. ALL QNX products are licensed.
Licenses take two different forms:
A. as a text entry in the ASCII file /.licenses
B. as a special file in /etc/licenses
The text entry type licensing are easier to work with.. they can be
copied from machine to machine, you can edit the file and manually type
in a valid license etc.
The 'special file' licenses stored in the /etc/licenses area are trickier.
You can only use the 'license' program to move/copy them around.
Check out the section on Transferring Licenses for more info.
For QNX, and any QNX products to work correctly, valid licensing
information MUST be present.
e.g. in order to run Socket (TCP/IP) you need a /etc/licenses/tcprt____ file
or an entry in the text file /.licenses that corresponds to
tcprt-some-big-number
If you were to do a 'ls' of /etc/licenses on your QNX development machine
you would see files similar to the following:
qnx0000001n004 tcprt0000002n016 etc..
This filename tells you three things about the license:
'qnx' is the product name (ie. the O.S)
'0000001' is the serial number for this license
'n004' is the number of licenses
So in our example 'qnx0000001n004' is a 4 node QNX Operating System license
with the serial number 0000001.
For 'special file' type licensing contained in /etc/licenses:
2. You MUST use the 'license' program to transfer licenses. You cannot use cp,
mv, pax etc. to transfer, or archive license information. The 'license'
program must be used in all cases with /etc/license style licenses.
The only exception to this rule is if you copy the entire disk volume that
contains license files.
e.g. cp /dev/fd0 /disk.image
(insert new formatted floppy)
cp /disk.image /dev/fd0
See the chapter on 'Transferring Licenses' for more
information.
3. The serial number portion of license files MUST be unique in order for them
to be recognized. For example, assume the following license files for the
OS were in /etc/licenses:
qnx0000001n001 qnx0000002n002 qnx0000002n004
The files qnx0000002n004 and qnx0000002n002 have the same serial number, and
are thus considered the same. When QNX boots, we would see a network size
of: 1 + 2 = 3 or 1 + 4 = 5 (depending how they are read, the point is it
wouldn't be 7 as you might expect.)
4. The difference between 'M' (modular) licensing and regular licensing.
A modular license (e.g. qnxm0000001n001) is slightly different than a
regular license (e.g. qnx0000001n001). The modular license is less
expensive but it is restrictive in the systems you can use them in.
A. If you try to mix modular and regular licensing on the same network
(e.g. you have a mixture of qnxm_______ and qnx_______ licenses on
your system) then when the machine boots a warning will be displayed
and the system will pause for a certain number of seconds (30 seconds).
B. If you try to use a compiler (WCC) on a machine with qnxm licensing
then a warning will be printed and the machine will pause for a certain
number of seconds (15 seconds).
Avoid situations where A and B can occur.
Please note that QNX Software Systems is deprecating our use of these
modular licenses. They can be cumbersome to deal with. Any new OEM should
not be using them as a rule unless explicitly told to do so by QNX.
5. An old-style license can be stored in 'file form' or in 'data form' on a
floppy diskette. On other media (such as hard drives or solid state disk
systems) the license MUST be stored in 'file form'.
What do these terms mean?
File form: The license is stored on the floppy/harddrive as a file.
For example, you can 'cd' to /etc/licenses and do an 'ls' on
the directory and see the license files there.
Data form: The licenses are stored on special blocks on the floppy.
Data form can only be used on floppy disks.
You cannot see the license data stored there as the floppy does not have a filesystem on it ... it is a block special device
only.
QNX had shipped our license diskettes using the 'data form'. Both types of
storage can store multiple licenses.
(note that with current products, QNX ships the 'new style' licenses that
are contained in /.licenses)
For example you can store many hundreds of license files on one diskette.
To read the license information you use the 'license' program (you must be
root to do this).
The syntax on the 'license' program will vary depending on what form you
have used to store the license files.
(these examples assume that your root filesystem is the harddrive you are
putting the license on e.g. /=harddrive)
Restoring file form: Start floppy driver
Fsys.floppy
Mount the floppy as a file system
mount /dev/fd0 /fd0
Run the license command
license /fd0/etc/licenses
Restoring data form: Start floppy driver
Fsys.floppy
Run the license command
license /dev/fd0
** please note that the new style licenses contained in the file
/.licenses do not have any of the restrictions listed above. It is
recommended to use new style licensing whenever possible.
-------------------------------------------------------------------------------
Transferring Old Style Licenses
-------------------------------------------------------------------------------
License files (e.g./etc/licenses/qnx0000001n004) are 'almost' like normal files
in the system. The important thing to remember is that you MUST ALWAYS use the
'license' program when you copy licenses between any two filesystems.
Apart from that, all other file operations are fine on them: rm, ls etc.
In an OEM arrangement where you will be providing your customers with licensed
software we typically provide you with the following:
- a series of 'modular license diskettes'
Currently you'll receive X licenses on each diskette, where X could
be 1, 4 or some larger number.
What do you do when you get these diskettes?
Depends on what you will be providing your customers.
A. You can use these diskettes just like a regular license disk. So when the
customer installs your software and runs the 'license' command, they put in
1 or more modular license disks and make an X node system (adding up all
the licenses they install).
You would ship the license disk(s) 'as is' direct to your customer.
B. If you want to customize the licensing for the customer (and either put
licensing right on your boot floppy, or make a special license disk that
has multiple licenses on it), then you could do the following:
B-1. First thing to do is to put the licenses on your master system.
B-2. Make a directory on your master system called /oem
B-3. Insert the 'modular license diskette' into your machine. Make sure that
Fsys.floppy is running.
B-4. Then, use the 'license' program to transfer the license files to your
master system.
license /dev/fd0 /oem (you must be a 'root' user to do this)
B-5. Save away the 'modular license diskette' ... you don't need it anymore.
B-6. Do step 3 to 5 for each modular license diskette that you have.
What is happening?
You are accumulating all of the licenses into one place on your master
system.
Now, you can transfer these license files to your customer software.
You can transfer license files to floppies or to harddisks/SSD's.
In the following examples we'll look at using floppies ... if you are
using harddisks or SSD's then the concepts are exactly the same except for
the fact that your destination given to the 'license' program will be a
/etc/licenses directory on your target harddisk or SSD system.
There are two main ways of transferring license files:
1. Transferring individual license files
Use the 'license' program and specify a unique license file to transfer.
For example:
- you have a license file called /oem/qnx0000001n001 on your
master system
- you want to transfer this license to a floppy ... the floppy has
a /etc/licenses directory on it and is mounted as /fd0 - to do the transfer, type (as root)
license /oem/qnx0000001n001 /fd0/etc/licenses
- the license will be transferred to the floppy.
** - a license file is NOT automatically deleted once it is transferred.
Therefore, as part of your OEM agreement you MUST do the following:
- record the license number in your OEM register.
- place an OEM sticker either on the floppy disk being made
or in your OEM register
** - remove the license file that you just transferred from your
master system.
e.g. rm /oem/qnx0000001n001
2. Transferring multiple license files
In the case where the floppy being made will have multiple license files
on it, it can be easier to transfer more than 1 license file at a time.
Here's an example of how to do this:
- the 'license' program can transfer entire directories of license
files at once (if you specify a directory as the source)
Let's look at an example:
- in /oem you have the following files
qnx0000001n001 qnx0000002n001 tcprt0000001n004 tcprt0000002n001
qnx0000003n001 qnx0000004n001 tcprt0000003n004 tcprt0000004n001
xrun0000001n004
- you want to transfer enough licensing to make the following:
- a 2 node QNX runtime
- with a 5 node tcpip runtime license
- and a 4 node X runtime
- make a new subdirectory somewhere as a working area. In this example
I'll make a directory called /oem/working
- use the 'license' program to transfer the license files that you
need down to the working directory
e.g.
cd /oem
license qnx0000001n001 /oem/working
license qnx0000002n001 /oem/working
license tcprt0000001n004 /oem/working
license tcprt0000002n001 /oem/working
license xrun0000001n004 /oem/working
- then, once they are in the subdirectory, you can transfer the
licenses to a floppy ... the floppy has a /etc/licenses directory
on it and is mounted as /fd0
- to do the transfer, type (as root)
license /oem/working /fd0/etc/licenses
- the licenses will be transferred to the floppy.
** - a license file is NOT automatically deleted once it is transferred.
Therefore, as part of your OEM agreement you MUST do the following:
- record the license numbers in your OEM register.
- place an OEM sticker either on the floppy disk being made
or in your OEM register
** - remove the licenses file that you just transferred from your
master system.
e.g. rm /oem/qnx0000001n001
rm /oem/qnx0000002n001
rm /oem/tcprt0000001n004
rm /oem/tcprt0000002n001
rm /oem/xrun0000001n004
rm /oem/working/*
- this whole procedure sounds like it is more work than just
transferring the licenses one at a time as in the example #1 above.
However, it could be a useful way to do it if you want to use
shell scripts etc. to streamline your oem procedures.
=============================================================================
Making a Boot Diskette
=============================================================================
This section describes how to make a QNX boot diskette.
A. First, examine the file '/boot/build/floppy' on your development system.
This is a sample floppy boot file.
It starts a ramdisk of a certain size (see the -r option on Fsys).
You may wish to change the size of the ramdisk to 100k or 200k depending
on how you will use the ramdisk in your installation.
Note also that use of a ramdisk is optional (but it can make things
easier).
In my example, I've changed the ramdisk size to 200K and made a floppy
image called '/boot/build/floppyt'
Cut out the piece below and copy it to '/boot/build/floppyt'
--------------------------cut----------------------------
sys/Proc32
$ Proc32 -p 30 -f 8 16 240 -n 10 -s 10 -t 6 -D
sys/Slib32
$ Slib32
sys/Slib16
$ Slib16
/bin/Fsys
$ Fsys -f 10 -i 20 -l 0 -c 40 -r 200k
/bin/Fsys.floppy
$ Fsys.floppy -m 18
/bin/mount
$ mount /dev/fd0 / -r
/bin/sinit
$ sinit TERM=qnx
sys/Debugger
$ 1 Debugger
--------------------------cut----------------------------
Note the following about the above build file:
- It is based on the file /boot/build/floppy that is provided on your
system.
- The options to Proc32 and Fsys make them use less memory than default. This
can be advantageous if you do not know how much memory your customers will
have. These limits can be removed (i.e. use the defaults) if you can
guarantee that the customer has a certain minimum amount of memory (like
4M for example)
- Also take a look at the technical note /etc/readme/technotes/qnx_install for
information on how QNX Software Systems does its install procedure. This can
provide some useful tips.
B. Make the boot image.
cd /boot
make b=floppyt
C. Format and dinit a floppy (I'll assume a 1.44M floppy in drive A)
fdformat -s1.44 -z2 /dev/fd0
dinit /dev/fd0
make sure the floppy is mounted as a filesystem.
e.g. mount /dev/fd0 /fd0
D. Copy the boot image created in step B to the floppy.
cp /boot/images/floppyt /fd0/.boot
E. Now you must copy ALL necessary files to the boot floppy so that it can
boot and prepare your storage media for your archive set.
In this example, I'll assume an IDE hard drive (I include Fsys.ata)
Here are the files you would need ... optional programs that aren't
necessary but could be useful for diagnosis have an 'O' beside them.
** ensure that you only place on the floppy the files that you are
allowed to distribute based on your OEM contract.
/fd0:
.altboot
.bitmap
.boot
.inodes
bin/
etc/
home/
usr/
/fd0/bin:
Dev*
Dev.con*
Fsys.ata*
cp*
dinit*
fdisk*
license*
login*
ls* O
mkdir*
mount*
pax*
prefix*
sh*
sin* O
tinit*
vol*
/fd0/etc:
config/
licenses/
passwd
/fd0/etc/config:
sysinit
/fd0/etc/licenses:
Make the directory /etc/licenses on the floppy but leave the directory blank.
/fd0/home:
qnx/
/fd0/home/qnx:
Make the directory /home/qnx on the floppy but leave the directory blank.
/fd0/usr:
lib/
/fd0/usr/lib:
terminfo/
/fd0/usr/lib/terminfo:
q/
/fd0/usr/lib/terminfo/q:
qnx
Notes on the above list:
- You need the /usr/lib/terminfo/q/qnx file if you want to run any program
that requires terminal emulation.
The 'fdisk' program requires this.
- There is a /home/qnx directory. In this example I want the user to login
as 'qnx' ... here is the '/etc/passwd' file:
qnx::0:0::/home/qnx:/bin/sh
- The sysinit file can launch whatever software you wish to. It can be
expanded to include whatever opening logo or programs that you want to run.
Here's a sample /etc/config/sysinit file:
echo Starting ...
Dev -n 16 &
Dev.con -n 4 &
tinit -t /dev/con1 -T /dev/con[2-3]
This sysinit file starts up some consoles and then brings up 'login' on
them.
- Make sure that a directory called '/etc/licenses' exists on the floppy. This
is where the licensing information will be stored.
See the Chapter on 'Licensing Options' for more details.
=============================================================================
Customer Installation of Software
=============================================================================
How does your customer install your software?
This will likely be different for each OEM. Media could be floppy disks,
tape, CD-ROM etc..
As an example, we'll assume that you have the following to install:
- a floppy archive of your software
- a QNX boot floppy (that you made)
the boot floppy has all required licensing on it in a directory
called /etc/licenses
The following procedures are the manual procedures ... this can all be
put into a user-friendly script file.
You may wish to look at how QNX installs with the software that we ship ..
see the file /etc/readme/technotes/qnx_install (it's a shell script) for some
more details.
A. Boot with the QNX boot floppy.
B. Login as 'qnx' (this can vary as you wish)
C. Start a disk driver.
e.g. Fsys.ide &
D. Create a QNX 4 partition on the drive.
e.g. fdisk /dev/hd0 (create a bootable QNX 4 (type 77) partition)
E. Mount the partitions
e.g. mount -p /dev/hd0
F. Dinit the hard disk, dcheck for bad blocks and the mount the QNX partition
as a file system.
e.g.
dinit /dev/hd0t77
dcheck -mV /dev/hd0t77
mount /dev/hd0t77 /hd
G. Setup the ram disk for use .. the ramdisk is created with the -r option
on Fsys in the floppy boot image. Using a ramdisk is very convenient.. it
provides a holding area for program files (like pax, vol etc.) so you can
swap floppies and still have access to them.
e.g.
dinit /dev/ram
mount /dev/ram /ram
H. Copy any files you need to restore your archive to the ramdisk.
e.g.
cp /bin/vol /ram
cp /bin/pax /ram
cp /bin/freeze /ram
cp /bin/prefix /ram
cp /bin/license /ram
I. Copy the boot files that you want the customer to boot with from the
boot floppy to the harddisk.
e.g.
cp /bootfiles/.boot /hd/.boot
cp /bootfiles/.altboot /hd/.altboot
Remember that you can't use 'pax/vol' to restore the boot files .. you
must copy them separately.
In the case where the customer may need to customize (if you don't know
what type of harddrive they have for example) then you will need to
make a new /.boot file when the install is complete (see step Q).
J. Change the PATH environment variable to search the ramdisk first.
e.g.
export PATH=/ram:$PATH
K. Make a /tmp directory on the harddisk for use by pipes. Then set the
TMPDIR environment variable to point to this directory.
e.g.
mkdir /hd/tmp
export TMPDIR=/hd/tmp
L. Make a spot on the hard disk for licensing.
e.g.
mkdir /hd/etc
mkdir /hd/etc/licenses
M. Transfer the licenses from the boot floppy to the hard disk.
e.g.
license /etc/licenses /hd/etc/licensesx |
|
