Installation
and
Troubleshooting
Thank you for selecting VMS emulation software from Boston Business Computing, Ltd.
This guide contains the following sections:
1. Introduction
2. Quick Installation
3. Technical Support
4. Detailed Installation Information
4.1 Media Device Paths
4.2 File Placement
4.3 Custom Installation
4.4 Network Installation
4.5 Modifications to system files
4.6 Disk space requirements
4.7 Licensing
4.8 Uninstalling
4.9 The
bbc program
5. Troubleshooting
5.1 Installation
5.2 Licensing
Please also read the
README.* files in the bbc/ distribution
directory before using your software.
To perform a first-time installation of your Boston Business Computing software into the default
locations or to upgrade an existing installation, place your distribution
media into the appropriate drive, login as root, and type
cd /tmp
tar xb 20
bbc/install
rm -rf /tmp/bbc
If you received your Boston Business Computing software distribution on multiple diskettes, you
should perform the `tar xb 20' step once for each diskette before
proceeding to the `bbc/install' step.
If the `
tar xb 20' command fails, you may need to type
tar xbf 20 media-device-path
instead, where media-device-path refers to the drive containing your
distribution media. See section 4.1, Media Device Paths for some examples of
media-device-path values.
If you encounter installation or licensing problems, please refer to section 5, Troubleshooting for possible solutions.
For further assistance, you can contact Boston Business Computing technical support by telephoning
(978) 725-3222, sending a FAX to (978) 725-3229, or sending email to bbc@bosbc.com. Please
include the following information in your problem description:
- your Boston Business Computing reference number, located in the output from `
bbc
info' and on the distribution media;
the name and version number of the affected product(s), located
in the output from `bbc info' and on the distribution media.
The following table lists typical media device paths for use with the `tar xbf 20 media-device-path' command:
This is a table.
The install program categorizes the files it installs into four components:
- auxiliary files;
- product binaries, which are actually symbolic links to certain
auxiliary files;
- manual pages; and
- configuration files.
All Boston Business Computing products share the auxiliary and configuration file components.
If your system already contains one or more Boston Business Computing products, the install
program by default places the new files in the same locations as the
old, replacing obsolete files with their new counterparts.
Otherwise, the install program uses characteristics of your system to choose
default locations, which on most systems are
/usr/lib/bbc/ for
auxiliary files, /usr/bin/ for product binaries, /usr/local/man/
for the manual pages, and /etc/bbc/ for configuration files.
At any time after installation, you can check the locations of Boston Business Computing software
components by running `
bbc info'.
To place files in locations other than those described in section 4.2, File
Placement, perform the following steps:
- Uninstall all Boston Business Computing products on the system.
- Follow the instructions in section 2, Quick Installation, replacing the
`
bbc/install' step with `bbc/install noquick'.
To use Boston Business Computing software on more than one system in the same network, it is
necessary to install the software on every system on which it will be used.
The simplest way to achieve this is by performing the full installation
procedure, as described in section 2, Quick Installation and section 4.3, Custom
Installation, on every system on which the software will be used.
An alternative way is by using NFS to share some or all of the Boston Business Computing software
components described in section 4.2, File Placement. Administrators who choose this
alternative should keep the following points in mind:
/etc/bbc/config should exist on every system.
The values of the "BBC", "BINS", "MANS", and
"CATS" fields in the /etc/bbc/config file should be the paths of
the directories containing the auxiliary files, product binaries, manual
pages, and formatted manual pages, respectively.
Files in /etc/bbc/ whose names are two-digit numbers -- for
example, 05 -- are license key files which should exist only on systems
on which licenses have been installed.
After the configuration and auxiliary files are in place, the following
commands will install product binary links and manual pages in the
appropriate locations:
cd auxiliary-file-directory
bbc setup
It is not necessary to install license keys on every machine on which Boston Business Computing
software will be used. See section 4.7, Licensing for more information.
Under some circumstances, the install program adds an entry to /etc/services and one to /etc/inetd.conf; see section 4.7, Licensing for more
information. The install program does not modify any other system files.
Depending on how many and which products you install and on what kind of
system you have, your software installation requires from one to six megabytes
of disk space. During installation, the file system containing your current
working directory requires an additional one to six megabytes of disk space.
To use Boston Business Computing software, you must install or already have installed one or more
license keys permitting it to run on your system.
You may install license keys either on the system on which you will use the
software or on any other system in the same local network. When installing
Boston Business Computing software on multiple machines in the same network, it is often more
convenient to install all license keys on one or two systems.
In the rest of this section, the term license server refers to any
system on which you have installed one or more license keys.
Obtaining License Keys:
You can obtain license keys by contacting the Boston Business Computing sales department in
whatever way you find convenient (normally telephone, fax, or email) and
providing them with the following information:
- Your BBCREF, which is a short sequence of letters and digits that
Boston Business Computing uses to quickly identify your customer account. You can find your
BBCREF by running `
bbc info'.
The appropriate license server's server code, which is a sequence
of digits that Boston Business Computing uses for generating license keys. You can find the
server code by logging in on the license server and running `bbc info'.
The following limitations apply to server codes:
- Boston Business Computing staff do not know your system's server code until you relay it
to them;
- server codes are not transferable from one system to another.
If you submit your BBCREF and server code outside Boston Business Computing's normal business
hours of Monday through Friday, 9:00am to 5:30pm EST, Boston Business Computing will provide you
with your license keys the following business day.
Installing License Keys:
You can install license keys by logging in as root on the appropriate license
server and running `bbc license'. The `bbc/install' program
automatically invokes `bbc license'.
When `
bbc license' runs, the following events occur:
- You are presented with your BBCREF and the license server's server code.
- You are prompted to enter your license keys. After each prompt, you should
type a license key and then press
ENTER. After you have entered all your
keys, you can proceed to the next step by pressing just ENTER without typing
a license key.
You are asked whether you wish the license server to make its licenses
available to other systems on the local network. If you answer `yes',
the licensing program will modify /etc/services and /etc/inetd.conf to allow other systems to access the license server's license
keys. You can add or remove this capability at a later date by logging in as
root and running `bbc vlm' or `bbc rmvlm', respectively.
Transferring License Keys:
You can transfer license keys to a new system by performing the following
steps:
- For each license key you wish to transfer, complete one copy of the
License Transfer Request Form
at the end of
the printed version of
this document. The form requires the server codes of the old and new systems,
which you can determine by running
`
bbc info' on the old and new systems.
Contact Boston Business Computing for instructions on deleting the license key from the old system,
and follow those instructions.
FAX or mail the completed form to Boston Business Computing, who in turn will provide you with a
license key for the new system. Non-maintenance customers incur a fee for each
license transfer; please contact Boston Business Computing for current pricing.
Install the new license key on the new system by logging in as root and
running `bbc license'.
To uninstall all Boston Business Computing products, login as root and type
bbc uninstall
To uninstall some but not all Boston Business Computing products, type
bbc uninstall product-names
instead, where product-names is a space-separated list of the names of
the products you wish to uninstall.
The bbc program is a catch-all administrative tool for Boston Business Computing
software. It accepts the following parameters:
- `
cfg name value'Associates name with value in the Boston Business Computing configuration file. You should not specify this unless
Boston Business Computing technical support staff instruct you to do so.
`dspcfg'Displays the contents of the Boston Business Computing configuration file.
`help'Displays usage information for the bbc program.
`info'Displays information about software installed and licenses
available on this system. The information is especially useful when
troubleshooting installation or licensing problems.
`license'Installs license keys on this system.
`rmvlm'Restricts this system's license keys to use on this
system only.
`setup'Installs product binary links and manual pages based on
the contents of the auxiliary and configuration file directories; see section 4.2, File Placement and section 4.4, Network Installation for more information.
`startvlm'Starts the license manager daemon, vlmd. On
license servers that have trouble automatically starting vlmd from
inetd, it may be useful to include this command in a system startup
file.
`uninst product ...'Uninstalls the specified Boston Business Computing products. If no products are specified, uninstalls all Boston Business Computing products.
`vlm'Makes this system's license keys available to other systems
on the same network.
This section describes solutions to installation-related problems that you may
encounter.
- Symptom:
- The `tar xb 20' command fails with an error like "tar:
/dev/rmt0: I/O error", "tar: cannot open: /dev/rmt0", or "tar:
rmt0: No such device or address".
- Cause 1:
- The drive that contains your distribution media is offline.
- Solution 1:
- Make sure the drive is online.
- Cause 2:
- You are running tar on an SGI machine and reading from a
byte-swapped device.
- Solution 2:
- Type `tar xbf 20 media-device-path' instead of `tar xb 20', where media-device-path is the path of the non-byte-swapped
device corresponding to the drive containing your distribution media.
Non-byte-swapped device names typically end with ns or nsv.
- Cause 3:
- The default device path does not correspond to the drive that contains your
distribution media.
- Solution 3:
- Type `tar xbf 20 media-device-path' instead of `tar xb 20',
where media-device-path refers to the drive containing your distribution
media. See section 4.1, Media Device Paths for some examples of media-device-path values.
- Symptom:
- `tar xb 20' fails with "No space left on device".
- Cause:
- The file system containing your current working directory lacks
sufficient space to contain your Boston Business Computing product distribution.
- Solution:
- First, type `rm -rf bbc' to delete the files tar extracted.
Then, either delete enough files from the current file system to leave roughly
six megabytes free, or else cd to a different file system -- e.g.,
/usr/tmp/ -- that has at least six megabytes free. Finally, rerun
tar. The df command is useful for displaying space usage
statistics on mounted file systems.
- Symptom:
- `bbc/install' fails with "No space left on device".
- Cause:
- A file system in which you have chosen to install a Boston Business Computing software
component -- most likely the auxiliary files -- lacks sufficient space to
accommodate that component.
- Solution:
- You have two options:
- Remove enough files from the affected file system to leave roughly six
megabytes free, then reinvoke `
bbc/install'.
- Run `
bbc/install noquick' and specify a directory in a file system with
enough free space to contain the relevant software component.
The
df command is useful for displaying space usage statistics on
mounted file systems.
- Symptom:
- SGI tar pauses and displays a prompt similar to "Change tape and press the Enter key:". If you continued to the `bbc/install' step, `bbc/install' tells you that some expected files are
missing from the installation directory.
- Cause:
- The tape device that tar is accessing cannot read 10240-byte
blocks.
- Solution:
- Rerun the tar command as `tar xbf 20 media-device-path', where media-device-path ends in nsv. If
tar pauses again and displays the same prompt, you may need to run
`mt -t media-device-path 10240' and then rerun tar.
5.2 Licensing
This section describes solutions to licensing-related problems that you may
encounter.
An additional troubleshooting resource is the log file that each license
server keeps of its network transactions and corresponding errors. The log
file, named
vlm.log, is located in the Boston Business Computing auxiliary file directory;
see section 4.2, File Placement for information about that directory.
- Symptom:
- The product exits with "%LICENSE-F-NOLICENSE, all licenses
for 'product-name' are currently in use".
- Cause:
- The demand for licenses to run product-name currently exceeds
the number of licenses installed.
- Solution:
- Wait until another user finishes using the product and then try
again, or else arrange to purchase more simultaneous user licenses.
- Symptom:
- The product exits with "%LICENSE-F-NOFEATURE, no licenses for
'product-name' are installed on host 'host-name'".
- Cause:
- No license keys for product product-name are installed on the local
system or on the system named host-name, which has been set up to make
its license keys available to other systems on the network.
- Solution:
- Contact Boston Business Computing to obtain and install license keys for product product-name on either the local system or on system host-name.
- Symptom:
- The product exits with "%LICENSE-F-NOSERVER, no response
from license manager".
- Cause 1:
- No license keys for the product are installed on the local system, and
no remote system on the network has been configured to make its licenses
available to other systems.
- Solution 1:
- If a remote system on the network already has licenses for the
product, follow the instructions in section 4.7, Licensing to configure the remote
system to make its licenses available to other systems. Otherwise, contact
Boston Business Computing to obtain and install license keys for the product.
- Cause 2:
- For one of a variety of reasons, the local system cannot communicate
with the license manager daemon on the remote system that makes its license
keys for the product available to other systems.
- Solution 2:
- Ensure the local system can contact the remote system by running
`ping remote-host', `/sbin/ping remote-host', `/usr/etc/ping remote-host', or `/etc/ping remote-host',
where remote-host is the name of the remote system; if that fails, your
system administrator should take steps to correct the problem. Otherwise,
confirm that the remote system is configured to share its license keys by
running `bbc info' on the remote system. If it is, you may need to
login as root and run `bbc cfg VLMHOST remote-host' on the local
system, where remote-host is the name of the remote system; this tells
the local system to request licenses directly from remote-host rather
than broadcasting a request to the local network.
- Symptom:
- The product exits with "%LICENSE-F-AUTHFAIL, license
authorization failure on host 'host-name'".
- Cause 1:
- The system named host-name has invalid license keys installed,
probably as a result of transferring them from another system.
- Solution 1:
- Contact Boston Business Computing to obtain and install new license keys.
- Cause 2:
- An obsolete license manager on system host-name has responded to
the product's license request.
- Solution 2:
- Upgrade the license manager on system host-name.
- Cause 3:
- A non-Boston Business Computing license manager on system host-name has responded to the
product's license request.
- Solution 3:
- Please contact Boston Business Computing technical support.
- Symptom:
- The product exits with "%LICENSE-F-NOBINLIC, 'product-name' is not licensed to run on this system type".
- Cause:
- No installed license key allows systems of the same type as the local
system to run product-name. System types roughly equate to system
manufacturers; for example, all Hewlett-Packard workstations have the same
system type.
- Solution:
- Contact Boston Business Computing to upgrade your license keys to support systems of
the same type as the local system.
- Symptom:
- The product periodically displays "%LICENSE-F-LOST, license
for 'product-name' has been lost".
- Cause:
- The product has lost contact with the license manager, possibly due to
a network or system crash.
- Solution:
- Exit and restart the product.
- Symptom:
- The product exits with "%LICENSE-F-NOHOST, host 'host-name' is unknown".
- Cause:
- The local system cannot translate host-name, the name of the
system on which the license manager runs, to a numeric address.
- Solution:
- Add host-name and its numeric address to /etc/hosts.
- Symptom:
- The product exits with "%LICENSE-F-NOHOST, host ' ' is
unknown".
- Cause:
- The local system has no name.
- Solution:
- Set the local system's name using the hostname command.
- Symptom:
- The product exits with "%LICENSE-F-SEMGET, unable to
retrieve license key semaphore".
- Cause:
- The system is not configured to support semaphores. If this is the
case, the output from running `ipcs -s' should display a message to that
effect.
- Solution:
- Reconfigure the system to support semaphores.
To reconfigure a SunOS 4.x system, add the lines `
options IPCSEMAPHORE'
and `options IPCSHMEM' to the kernel config file, build and install a
new kernel, and then reboot. Chapter 9 of the System & Network
Administration manual describes in more detail how to generate new kernels.
- Symptom:
- The product exits with "%LICENSE-F-SEMLOCK, unable to lock
license key semaphore" followed by "-RMS-F-FUL, device full
(insufficient space for allocation)".
- Cause:
- Other applications have consumed all of a particular type of semaphore
resource.
- Solution:
- Reconfigure the system to make more semaphore resources available.
To reconfigure a Solaris system, add the line `
set
semsys:seminfo_semmnu=500' to /etc/system and then reboot. If the
system runs many database applications, it may also be beneficial to increase
the values of `semsys:seminfo_semmni', `semsys:seminfo_semmsl',
and `semsys:seminfo_semmns'. The AnswerBook document Security,
Performance, and Accounting Administration, Appendix A describes those
parameters.
To reconfigure a SunOS 4.x system, add the lines `
options SEMMNU=300'
and `options SEMMNS=300' to the kernel config file, build and install a
new kernel, and then reboot. Chapter 9 of the System & Network
Administration manual describes in more detail how to generate new kernels.
- Symptom:
- The product exits with "%LICENSE-F-NOSOCKET, connection
failed, system error 'number'".
- Cause:
- Internal kernel resources have been exhausted. This usually indicates
that too many network connections are in use on the current host.
- Solution:
- Try again later. Chronic problems may be solved by reconfiguring
the kernel.
- Symptom:
- The product exits with "%LICENSE-F-NOTSENT, unable to send
message to license manager, system error 'number'".
- Cause:
- Internal kernel resources have been exhausted. This usually indicates
that too many network connections are in use on the current host.
- Solution:
- Try again later. Chronic problems may be solved by reconfiguring
the kernel.
- Symptom:
- The product exits with "%LICENSE-F-SYSERR, miscellaneous
system error".
- Cause:
- The current system's date is wildly incorrect.
- Solution:
- Login as root and run the date command to correct the
system's date.