Installation guide

This document describes the installation of OSB on a Debian Linux server.


The guide assumes that OSB is installed by the user osbadmin. Is is intended for experienced Unix users, it does not provide explanations for the OS configuration or UNIX commands.

With a few exceptions OSB should not be operated by osbadmin, but by users that are member of the group osbuser.
This provides a minimum tracking who has run which application.

Unix command line is marked with a $ at the beginning, where provided the output is marked with a starting >.

$ echo "OSB installation"

> OSB installation

File systems

We recommend that you use at least 2 partitions to store your data.

Following the above principle will make it easier to define a backup strategy for the system: backups of data partition must be taken more often than backups of static data.

I hear you: "OK, I understand this. But Debian expects the home directories in /home. How do I do this?"
The answer is simple: Create a symbolic link in the root directory / that points to data/home.

$ mount /data

$ cd /

$ ln -s data/home home

$ ls -l home

> lrwxrwxrwx  1 root root 10 Jun 10  2004 home -> data/home

Hint: avoid symbolic links with an absolute path; if you mirror the disk or data partition and later mount it to a different mount point the link points to the correct directory/file and not to the actual root partition.

Of course you are free to use more partitions, e.g., /app for 3rd party software.

Needed software

OSB requires the following software packages:

Unpacking the shipment

OSB is provided in two tarred and gzipped archives, together with a check sum file.

Create the following directories if they do not exist:


The installation directory should belong to the group osbuser and have the group sticky bit set:

$ cd ~

$ chgrp -R osbuser install

$ chmod g+s,g-w install

1. Copy or move the archived OSB shipment into the directory ~osbadmin\shipment, check the content of the shipment:

$ cat OSB_040606.linux.cksum; cksum OSB_040606.linux.tgz

> 1960140082 12082799 OSB_040606.linux.tgz

> 1960140082 12082799 OSB_040606.linux.tgz

The two generated lines must be exactly the same. Similarly you should test the ACE+TAO archive.

2. Change to installation directory ~osbadmin/install and unpack the archives:

$ cd ~/install

$ gunzip -c ../shipment/OSB_040606.linux.tgz | tar xvf -

> OSB_040606/
> OSB_040606/bin/
> OSB_040606/bin/billing
> OSB_040606/bin/rating
> OSB_040606/bin/
> ... [snipped]

and similar for the ACE+TAO archive, if a new version was used to build the OSB shipment.

3. Change the ownership of the unpacked files and set permissions:

$chmod -R o-rwx,g-w osbuser OSB_040606 ACE-5.4+TAO-1.4

4. Create symbolic links to the OSB and ACE+TAO installation directories.

$ cd ~

$ ln -fs install/OSB_041026 osb

$ ln -fs install/ACE-5.4+TAO-1.4 ace+tao

When we install the next OSB shipment, we only need to adjust the symbolic links to point to the new installation directory.

Data directory structure

The default configuration of OSB uses the following directories to store data:

directory comment
/osbdata/ This is either a mount point of its own or a symbolic link to a directory in the data partition.
  admin/ OSB configuration files.

This directory contains all CDR files:
Except for ./collection/backup and ./rating/ok all files modified and removed by the processing application.

  collection/ CDR files as collected from the switches (network elements).
  backup/ Back-up of the CDR files from switches that don't provide for it.
Preferably this is a symbolic link that points outside the CDR directory, e.g., to /osbdata/cdrbackup.
tmp/ Working directory of the CDR file collectors.
conversion/ CDR files after the conversion process.
rating/ CDR files after the rating process.
  ok/ This directory contains the successfully rated, billable CDR records.
Preferably this is a symbolic link that points outside the CDR directory, e.g., /osbdata/ratedcdr.
log/ Log files of all OSB applications.
invoice/ Generated XML invoices.
  draft/ Test bill run.
final/ Committed bill run.
reconcile/ Generated XML reconciliation statements.
  draft/ Test bill run.
final/ Committed bill run.
report/ Configuration of reporting server (currently not supported).
  xls/ XSL stylesheets to format the reports.

Most of these directories can be configured in the tables CONFIGURATION and RECORD_SOURCE as described later in this document.

Unix environment

OSB needs a few environment variables set in order to work properly. Copy the file ~osbadmin/osb/tools/other/osb.env to /osbdata/admin/osbenv and check the following settings:
# paths for OSB
export OSBBASE=/home/osbadmin
export PATH=$PATH:$OSBBASE/bin
export CDPATH=.:/osbdata:/osbdata/cdr

# Oracle environment
unset TWO_TASK
. /usr/local/bin/oraenv
export TNS_ADMIN=/app/oracle/network/admin

# paths for ACE+TAO
export ACE_ROOT=$OSBBASE/ace+tao
export PATH=$PATH:$ACE_ROOT/bin

# Java and Tomcat
export JAVA_HOME=/usr/lib/j2se/1.4 # assumes Blackdown Java Linux
export CATALINA_HOME=/usr/share/tomcat4

Configuration file (osb.cfg)

All OSB applications, including batch applications and CORBA servers need to access the database. For each application the OSB database schema defines a role and provides the necessary access rights.
The configuration file osb.cfg defines the user, password and database for each module. By default it is located in the directory /osbdata/admin. You can specify another configuration file with environment variable $OSBCFG, this is useful if the OSB GUI user is defined in the configuration file (see below).

$ export OSBCFG=${HOME}/myosbcfg.txt

To create and configure this file, run the command osbcfg as user osbadmin:

$ osbcfg {module}

The following table contains a list of modules, together with the default database username, password (change on install!) and database that are required.

Module Username Password 1) Database
billing bill bill OSBDB
conversion mediate mediate OSBDB
rating rate rate OSBDB
storage rate rate OSBDB
osbadmin osbadmin osbadmin OSBDB
tariffadmin tariff tariff OSBDB
productadmin product product OSBDB
contractadmin contract contract OSBDB
networkadmin network network OSBDB

1) OSB uses encrypted passwords, use osbcrypt to encrypt the passwords if you manually edit the configuration file.

For the GUI applications (OSB and tariff administration) you can create an optional entry.
Note: if you opt for this each user should maintain its own configuration file by setting the environment variable $OSBCFG.

Module Username Password Database
guiuser <name> <password> - 2)

2) The database is not relevant, just set it to a '-'.

OSB database instance

Database instance and users

Create the database OSBDB as UNIX user oracle. A few remarks:

Once the database is up and running, run the script to generate OSB roles and users:

If you also install the AR (Accounts Receivable) add-on module, you need to perform similar steps to create the AR roles and users:

Creation of the OSB database schema

This setup task can be performed as user osbadmin. It requires access to the database as user OSB.

Go to ~osbadmin/osb/database and run the script with the OSB user and password as parameter.
In the last step this script creates the primary keys, indexes and foreign keys.
It may fail if any foreign keys are enabled, you can run ~osbadmin/osb/tools/sql/Cr_dropfk.sql to create a script that drops all foreign keys.

$ cd ~osbadmin/osb/database

$ ./ –u osb/{password}

If you install the reporting server load the needed stored procedures. These are owned by the database user REPORT.

$ cd ~osbadmin/osb/reports/database/plsql

$ –v –dOSBDB –u report/{password} -a

$ grep ORA- *.l*

If you also install the AR (Accounts Receivable) add-on module, you need to perform similar steps to create AR tables and triggers and load AR baseline data. Note that these database objects are owned by the database user AR, i.e., the scripts must be loaded as this user.

$ cd ~osbadmin/osb/ar/database

$ ./ –u ar/{password}

Baseline set-up

This section explains the baseline configuration scripts that may differ from one installation to another.

There are different categories of data that need to be configured here:

The very first step is to verify the validity of the data to be loaded with the customer.

Login as user osb and change to the directory ~/osb/database/config. Read the README file in this directory.
It contains all the information on what input is required and how to load the configuration scripts into the database.

Secondly, change into directories ~/osb/database/config/tc_system and ~/osb/database/config/network.

Run make all in both directories. Upon the completion of the process, one set of network related control scripts and one set of TCS related control scripts will be generated. Verify all scripts as valid for this installation before using them.
NOTE: If you are not familiar with OS we recommend that you create and configure networks and tariff objects manually.

Thirdly, change to the directory ~/osb/database/config. Run the following command:

$ ./ –u osb/{password}

Check all the log files for errors.

Starting the OSB web application

The OSB web application consists of 3 components:

  1. the CORBA naming service
  2. the OSB CORBA servers
  3. Tomcat to process the JSP pages.

Naming service

Login as user osbamin to start the Naming_Service:

$ namsvc -s

The default IP address and port number used for the naming service is
Use the namsvc options -i{host} and -p{port} of to change these values. If you opt for this, don't forget to change the settings in the file (see below) and the database table CONFIGURATION, else the OSB web application and CORBA servers will not find the naming service.

CORBA servers

Login as user osbadmin and run the following command:

$ osbsvr -s

Similarly, the OSB CORBA servers can be stopped (killed) with osbsvr -k and re-started with osbsvr -r.
It is also possible to control each server individually, run osbsvr -h to get a list of all possible options.


The following steps describe the installation and configuration of the OSB web application. Tomcat must be installed prior to this.

Preliminary remark

Tomcat should be started and stopped as user osbadmin.
All files and directories (including the symbolic links) below $CATALINA_HOME (the Tomcat installation directory) should belong to the group adm and osbadmin should be a member of this group. However in several attempts I have failed to change the permissions and group ownership at the beginning so that everythink works the first time Tomcat is run. Instead I was changing the settings whenever an error occurred. Use the following commands as root:

$ chgrp [-R] adm {file | directory} Change the group of a file or directory.
$ chmod g+s {directory} Set the group sticky bit for a directory. All files that are created in this directory will have the its group.
$ find . -type d | xargs chmod g+x Provide group execute permission for the current directory and all its subdirectories.

Unpack the OSB web application archive


$ ./bin/

$ tar cvf - osbweb | gzip -c osbweb.old.tgz

$ rm -rf osbweb

$ cd webapps

$ ln -s ~/osb/www/osbweb.war osbweb.war


$ ./bin/

$ cd $CATALINA_HOME/webapps

$ rm -f osbweb.war

$ chgrp -hR adm osbweb


In the directory $CATALINA_HOME/webapps/osbweb/WEB-INF the following configuration files need to be checked and initialised with specific settings or preferences.

Create OSB web users

Start the Tomcat server again and connect to the OSB web application in your browser: http://localhost:8180/osbweb/.

The only online user that exists in new installation is the administrator: admin, password admin. Change this password, create users as needed and define their access to OSB web applications.