OpenClovis Product Documentation

Revision as of 20:32, 25 October 2012

Preface

SAFplus Platform Installation Guide guide provides the system requirements, installation procedure for SAFplus Platform software development kit (SDK) and the Evaluation System.

Audience

SAFplus Platform Installation Guide is designed for system integrators, designers, and system architects. To use the product, you must be aware of the fundamentals of design, development, operation, management and configuration of telecommunication and networking systems. You must also be familiar with C programming, UML notations, and have the basic knowledge of Linux.

Documentation Conventions

This guide uses different fonts and symbols to differentiate between document elements and types of information. These conventions are summarized in the following table.

Code

This indicates the presence of notes or annotations, related to the context of the document.
This indicates that certain precautionary measures must be taken before performing a particular task.
This indicates that additional information is provided to you.

Related Documents

For additional information about OpenClovis products, refer to the following guides:

• SAFplus Platform Release Notes provides information about the software and the hardware required to install OpenClovis Application Service Platform (SAFplus Platform) and Integrated Development Environment (IDE). It summarizes the additional features and enhancements of the product since the previous release. It also summarizes the issues and limitations of the product and provides workarounds wherever applicable.
• SAFplus Platform SA-Forum Compliance describes the level of compliance of OpenClovis SAFplus Platform and its Application Programming Interface (API) with the relevant Service Availability Forum Specifications.
• SAFplus Platform Installation Guide provides the system requirements, installation procedure for OpenClovis SAFplus Platform, IDE, and the Evaluation System.
• SAFplus Platform Sample Application Tutorial explains the steps to create and build a sample model using OpenClovis IDE and OpenClovis SAFplus Platform. It also provides troubleshooting information for this process. This provides the logical first step in understanding the SAFplus Platform offering.
• SAFplus Platform Evaluation System User Guide provides all the required information to configure and run the sample models packaged within the Evaluation System. This document also provides good understanding of OpenClovis SAFplus Platform's functionality. This is the natural follow on to the OpenClovis Sample Application Tutorial as it builds on the example created in that document.
• SAFplus Platform SDK User Guide provides information about SAFplus Availability/Scalability Platform architecture, various SAFplus Platform components, and their interactions. This guide helps you to configure the OpenClovis SAFplus Platform components, compile, and execute the SAFplus Platform code to build your custom application.
• SAFplus Platform IDE User Guide describes the usage of Integrated Development Environment (IDE), a graphical development environment that complements the SAFplus Platform. This guide helps you to understand how to use the various features of the IDE to build the application.
• SAFplus Platform Log Tool User Guide provides information about the usage of OpenClovis Log Tool. OpenClovis Log Tool is an interactive utility that allows you to view binary log files in a readable format and hence monitor system errors, warnings, and other log information. Log Tool allows you to format the .log files and filter them to view the required entries.
• SAFplus Platform API Reference Guide [1] is provided for each component. It describes the Application Programming Interface (API), Service Model, and Management Information Model of the various OpenClovis Application Service Platform (SAFplus Platform) services. It helps the developer to understand the capabilities of the SAFplus Platform services and the APIs provided by these services.
• SAFplus Platform Console Reference Guide provides details about managing applications built on SAFplus Platform using the SAFplus Platform runtime debug console commands. SAFplus Platform Console commands can be used to manage, monitor, and test your application.

OpenClovis Online Technical Support

OpenClovis customers and partners can register on our Web site and receive personalized services and information. If you need any support or assistance while working on OpenClovis products, you can access the following: URL: http://www.openclovis.com. Send your queries to: support@openclovis.com. Open source community support is available at: http://www.openclovis.org/forum.

Documentation Feedback

We are interested in hearing from our customers on the documentation provided with the product. Let us know your comments and suggestions on improving the documentation at OpenClovis Inc. Send your comments to: support@openclovis.com. Or even better, edit (or comment in) the page on our documentation wiki located at http://help.openclovis.com.

Prerequisites to Install

This chapter provides an overview of the OpenClovis SDK solution comprising OpenClovis SAFplus Platform and IDE. It also provides the hardware and software requirements for running OpenClovis SDK and the Evaluation System.

Overview

OpenClovis provides a modular and cost-effective software platform for creating next-generation communication systems. OpenClovis SDK is designed for solution integrators, network equipment manufacturers (NEPs), and telecommunication equipment manufacturers (TEMs) to facilitate the creation of a broad range of telecommunication devices, including routers, switches, media gateways and wireless infrastructure nodes.

OpenClovis fits seamlessly with various distributions of Linux and hardware platforms such as AdvancedTCA, BladeCenter T, and other off-the-shelf proprietary hardware.

The OpenClovis solution comprises OpenClovis SAFplus Platform and OpenClovis IDE.

OpenClovis Application Service Platform (SAFplus Platform) is middleware that offers a comprehensive set of modular, portable, reusable software components designed to provide system management and high availability functionality. OpenClovis SAFplus Platform is the run-time part of the OpenClovis offering. It provides run-time services for your value add applications, offering a layered, hardware-platform independent application environment.

OpenClovis Integrated Development Environment (IDE) is designed to simplify and accelerate the development of application service platforms for the telecommunication marketplace. Coupled with the OpenClovis SAFplus Platform, this intuitive software solution streamlines the process of specifying the information model, high availability (HA) aspects, and the communication infrastructure of a system. OpenClovis IDE stores all information describing a project in well defined XML files that can be modified by the user. Modeling of system resources and relationships are specified using a graphical UML editor.

OpenClovis Evaluation System is a evaluation sample system based on SAFplus Platform that provides the user with a better understanding of the scope of the product, usage patterns, its quality and usability.

Development Host Requirements

This section provides the hardware and software requirements for installing OpenClovis SAFplus Platform and IDE. It is not necessary to install OpenClovis IDE on the target host, as all the modeling activities are performed on the development host. The system requirements for the development host is summarized in Table System Requirements for a Development Host.

The OpenClovis SDK installation process verifies the Third Party Packages, and installs any missing packages automatically, as a part of the SDK Installation.

Target Host Requirements

This section provides the hardware and software requirements for installing OpenClovis SAFplus Platform on the target host. These requirements are summarized in Table System Requirements for the Target Platform.

These are the Linux distributions on which SAFplus Platform is tested and certified.

SAFplus Platform SDK Packages

The SAFplus Platform SDK Installation packages listed in Table Required Installation Packages.

OpenClovis SDK is supplemented with a set of crossbuild packages for different CPU and Operating System combinations. The md5 and crossbuild packages are optional and maybe downloaded depending on your requirements.

OpenClovis SDK Installation

This chapter provides a step-by-step approach for installing OpenClovis SDK. Before proceeding with installation, ensure that all the required hardware and software are available on your system. You need not install the third-party packages, as the installation package installs the third-party packages along with OpenClovis SDK.

Installation Procedure - Get Started

To install Openclovis SDK on your local machine, go to the directory where you have downloaded the required installation files.

Before you install,

• Ensure you have write permissions for the current directory (directory where the installation files are downloaded) and the target directory (directory where you will install the application.)
• At least 500MB of free disk space.
• You can install the SDK either as a root user or a non root user. Installing as root user is not required for a single user host. When using the SDK for larger projects it is advisable to install as root, since multiple users can share the same SDK. Irrespective of the mode of installation, the SDK can be used to model and build code using non-root privileges.

To extract the SDK package, execute the following command:

# tar -xzmf openclovis-sdk-3.0.tar.gz

The m option to tar ensures that the timestamps on the files within the SDK package are consistent with the host system. This is important, since discrepancies can adversely affect the build procedure.

To ensure that your system has all the prerequisite software packages required by the installation process, the SDK package contains preinstallation scripts for a variety of Linux distributions. Prerequisite packages are packages that are supplied by your distribution but may not have been installed on your system. Essentially this is the GNU compiler toolchain and programming utilities such as pkg-config, flex, and bison. These scripts enable the user to acquire and install the prerequisite software packages automatically. Some distributions provide these packages on your installation CDROMs, so you may be asked to insert them. Other distributions provide these packages via internet-based software repositories (notably Ubuntu). If your system does not have internet access, please see Appendix A: Installing the Prerequisites without Internet Access. The following table covers the distributions supported by the preinstall scripts:

The preinstall scripts need to be run as root.

The preinstall script installs SQLite as database engine by default. If you would like to select GNU Database Manager or Berkeley Database, please visit section Database Abstraction Layer (DBAL) in OpenClovis SDK User Guide for more information.

Please run the preinstall script corresponding with your Linux distribution by executing the following commands:

# cd openclovis-sdk-3.0
# ./preinstall-<os>.sh

An installation of Red Hat EL4 with the default package set contains all the packages required for installing OpenClovis SDK. In particular, the 'Development Tools' package subset must be installed to cover these requirements.

Once the preinstall script completes, start the SDK installation by executing the following command:

# ./install.sh

After you execute the install command, the Welcome screen is displayed as illustrated in Figure OpenClovis Installer Welcome Screen. When prompted by the installer, the user can enter the name of the directory where the SDK should be installed or accept the default provided:

OpenClovis Installer Welcome Screen

The default directory for installation is /opt/clovis for root installation and $HOME/clovis for non root users as illustrated in Figure OpenClovis Installer Welcome Screen. The installation progress is illustrated in Figure Installation Directory and Progress.

Installation Directory and Progress

Third Party Packages

The required third party packages are installed in the following steps:

• Scans the system for existing third party packages.
• Displays the list of packages that are available, along with their version numbers.
• Displays the list of packages that are not available or that have a version mismatch.

This display may vary at the time of your installation, depending on the packages that are available on your system. Figure Third Party Packages - Availability Status demonstrates a typical display.

Third Party Packages - Availability Status

To proceed with the installation, enter y for the message, Proceed with the installation <y/n> [y]:

Figure Third Party Packages Installation Progress illustrates the approximate installation time and the installation status for each package.

Third Party Packages Installation Progress

After installation of third party packages, the installer displays the message, All SDK dependencies are now in place. as illustrated in Figure OpenClovis Packages Installation - Status.

OpenClovis Packages Installation - Status

After completion of the third party packages, the installer prompts the user for the installation of the crossbuild toolchains.

Crossbuild Toolchains

Crossbuild toolchains are required to install SAFplus Platform on a platform that is different from the development host platform. For instance if the development host is x86 Intel based and the target platform is PowerPC based the user will need a crossbuild toolchain for that particular PowerPC based architecture.

For crossbuild toolchains, you will require the following:

• A cross compiler and related binary tools for the target CPU architecture.
• All the SAFplus Platform prerequisites that are pre-compiled for the target platform, so that all library files are available.

OpenClovis SDK comes with a standard set of pre-built crossbuild toolchain packages. The names of these packages help you to identify the CPU and OS combinations for which they have been built.

The SDK installer (install.sh) assists you in installing one or more of these toolchains as illustrated in Figure Crossbuild Toolchains. Enter the crossbuild toolchain that you require to be installed from the available list. After the toolchains are installed, you can select any of these cross-tools for your project build.

Crossbuild Toolchains

If you would like to install more crossbuild toolchains at a later time, please download them and re-run install.sh. You may skip the remaining portions of the install process past the installation of crossbuild toolchains when you are prompted to do so.

SAFplus Platform, IDE and Utilities

After installation of the toolchain, the system proceeds with the installation of SAFplus Platform, IDE and Utilities as illustrated in Figure Installing SAFplus Platform, IDE and Utilities.

Installing SAFplus Platform, IDE and Utilities

The installer creates the required binaries and prompts you to create optional symbolic links, so that the SDK commands can be accessed on your system in a well known location, as illustrated in Figure Creating Symbolic Links. The main SDK commands of interest to the user are:

• cl-create-project-area: Command to create a new OpenClovis SDK project area. A project area is the workspace for the OpenClovis SDK. It contains the IDE models and the generated source code. The user makes modifications to the generated source within this workspace and builds runtime images here as well. A typical project area has the following directory structure:

  <project_area>
     |ide_workspace
     |+<model>
     |   |+build
     |   |   |+local
     |   |   |   |-Makefile
     |   |   |+<crossbuild>
     |   |   |   |-Makefile
     |   |+src
     |   |   |+app
     |   |   |+config
     |   |   |+doc
     |   |   |-target.conf
     |   |+target 
     |   |-Makefile
     |-Makefile
  

• cl-ide: Command to start the OpenClovis IDE. Please note that you should have already created a project area using cl-create-project-area before using cl-ide to work within this project area.

Creating Symbolic Links

Enter Y to create the symbolic links. The installer then prompts the user for a location to place the links with a default option /usr/local/bin if you are installing as root, or $HOME/bin for non root user installation.

If you choose not to create symbolic links and enter N, then you can either:

• Add the installation directory to the shell path. For example with a bash shell:

  export PATH=$PATH:<install_dir>/sdk-3.0/bin
  

• or access the SDK commands from the <install_dir>/sdk-3.0/bin/ directory. For example to create a new project area at <project-area_dir>:

  <install_dir>/sdk-3.0/bin/cl-create-project-area <project-area_dir>
  

After creating symbolic links, the installation of OpenClovis SDK is complete. All the required packages and crossbuild toolchains are installed and the directory where you have downloaded the installation packages can be discarded.

If your installation is not successful, or if you encounter any problems during the installation, refer to the Chapter Troubleshooting.

Next Steps

After completing the Installation, the OpenClovis SDK Documentation set listed in the Related Documents section is available in the doc folder located at <install_dir>/sdk-3.0 directory.

We recommend the following steps to get familiar with our product:

• Read and follow the OpenClovis Sample Application Tutorial - The Sample Application Tutorial will step you through the process of creating a high available system. It takes you from model conception all the way through deployment and running of the sytem. After going through this guide you will understand the basics of the OpenClovis offering.

• Read and follow the OpenClovis Evaluation System User Guide - Evaluation System User Guide will introduce you to more advanced modelling topics. These topics are introduced incrementally through a series of targeted tutorials. After completing this guide you will be ready to start building your own system.

Troubleshooting

This chapter describes some of the probable errors that you may encounter during the installation. This chapter also provides the solution to these errors.The errors that you may encounter are:

• Error: Installation Failure, during third party installation.
  Solution: You can manually fix this error by getting more information from the corresponding log file under the log directory. You can also send the log.tar.gz to support@openclovis.com for more help. The installation can be resumed after the errors are fixed. The installer will detect any new updates and proceed with the missing prerequisites.
  
• Error: gcc (pkg-config, perl, md5sum) not found in your PATH.
  Solution: Ensure that the directory where the gcc resides is in the PATH variable.
  
• Error: Not enough space on the target installation directory.
  Solution : Change the target installation directory to the directory with at least 500MB free disk space.
  
• Error: <WORKING_DIRECTORY> is read-only.
  Solution: You need to have write permission for the current working directory to extract the contents of the archive, configure, and build. Ensure that you turn ON write permission using chmod +w ... command.
  
• Error: md5 checksums are used to check if the packages are correctly downloaded. If they are not downloaded correctly, the system displays the message: It is not safe to install these packages, please download them again.
  Solution:The installer checks the integrity of the downloaded packages. If the download is either incomplete or corrupt, download the packages again.
  
• Error: SAFplus Platform fails to start, reporting the underlying SQLite database version used is not-supported.
  Solution: Use SQLite version 3.3.13 or newer. The source code can be downloaded from http://www.sqlite.org/download.html. The user can install the latest version of SQLite if the specified version is not present in this repository.

Appendix A: Installing the Prerequisites without Internet Access

Some customers do not want their evaluation system to have internet access for security purposes. If this is your situation, please consider temporarily enabling internet access while running the "preinstall-<os>" script. At this point the evaluation system should only have the base OS installed, so there is no proprietary data on the system. Also note that the "preinstall" scripts are only about a page long so you can easily review them for security purposes.

However, if you still do not want to enable internet access one strategy that can be used is to go to a system with internet access (it must use the same Linux distribution and the same version), download them there, use a USB flash drive to move them to the unconnected system, and then install them on that system. If this approach is unacceptable (it does still use the internet), then perhaps the Linux distribution you chose is not appropriate -- instead use one that contains all packages on the installation CDROMs.

Example Using Ubuntu 7.04

Packages can be downloaded but not installed on Ubuntu by using the "-d" flag to the "apt-get" package manager. The files are downloaded to "/var/cache/apt/archives". It is recommended to remove (or move) all files in this directory first (it is just a cache, and so it will contain any packages that you have previously installed), so that the directory contains just the packages needed for the OpenClovis SDK:

rm /var/cache/apt/archives/*

Next edit the preinstall-ubuntu.sh script, search for all instances of "apt-get" and add the flags "-d --reinstall" just after the "apt-get" program. For example:

apt-get -d --reinstall -y --force-yes install build-essential

Next run this modified script on your internet-connected machine. This script will download 6MB of files (this list will vary by Linux distribution or version):

bison_1%3a2.3.dfsg-4build1_i386.deb                           
libgdbm-dev_1.8.3-3_i386.deb
build-essential_11.3_i386.deb                                 
libltdl3-dev_1.5.22-4_i386.deb
e2fslibs-dev_1.39+1.40- WIP-2006.11.14+dfsg-2ubuntu1_i386.deb  
libperl-dev_5.8.8-7build1_i386.deb
e2fsprogs_1.39+1.40-WIP-2006.11.14+dfsg-2ubuntu1_i386.deb     
linux-headers-2.6.20-16-generic_2.6.20-16.32_i386.deb
flex_2.5.33-10build1_i386.deb                                 
gawk_1%3a3.1.5.dfsg-4build1_i386.deb                          
gettext_0.16.1-1ubuntu2_i386.deb                              
pkg-config_0.21-1build1_i386.deb
libdb4.5-dev_4.5.20-1ubuntu1_i386.deb                         
uuid-dev_1.2- 1.39+1.40-WIP-2006.11.14+dfsg-2ubuntu1_i386.deb

Now copy these files to a new directory in your unconnected machine:

On the connected machine:

root@desktop:/# cp /var/cache/apt/archives/*.deb <your flash media>

On the unconnected machine:

root@desktop:/# mkdir /root/pkgs
root@desktop:/# cp <your flash media> /root/pkgs/

Finally, install them using the standard "dpkg" package installer:

root@desktop :/# cd /root/pkgs
root@desktop:~/pkgs# dpkg -i *.deb
(Reading database ... 113653 files and directories currently installed.)
...
root@desktop:~/pkgs#

At this point, you should be done installing the prerequisites! You should now continue the installation procedure at the step after installing prequisites.