Data Classification - PUBLIC

Kognitio Configuration and

Maintenance Manual
Version 8.1.0
May 2014

Data Classification - PUBLIC

Notices
This document contains proprietary information that should not be reproduced in whole or in part, nor released to third parties nor
used for purposes other than those for which it has been expressly provided without the prior written agreement of Kognitio.
Kognitio tries to ensure that the information in this document is correct and fairly stated, but does not accept liability for any error or
omission.
Standards Compliance
The Kognitio SQL implementation is fully compliant with the ANSI '89 standard.
Kognitio Configuration and Maintenance Manual, May 2014
Kognitio, 2002-2014
Kognitio Technology Centre
3A Waterside Park, Cookham Road
BRACKNELL, Berks, RG12 1RB
United Kingdom

Kognitio Configuration and Maintenance Manual iii
Data Classification - PUBLIC
About this Manual
This manual is part of a series that describes how Kognitio can enhance the
productivity of your interactive database applications. The manual is intended for
anyone who is responsible for installing, running, maintaining or monitoring a
Kognitio system.
Kognitio can be run on any suitable hardware platform. This manual assumes the
reader is familiar with, and has sufficient additional skills, tools and information
available to control, monitor and maintain the Kognitio platform.
Chapter 1 gives a basic description of Kognitio and the design strategy.
Chapter 2 looks at details associated with the installation and licensing of Kognitio.
It also discusses upgrading to a new version of Kognitio and how software packages
are managed.
Chapter 3 describes the tool that is used for routine Kognitio configuration and
administration tasks.
Chapter 4 shows the standard procedures to be followed to start and stop Kognitio.
Chapter 5 discusses Kognitio configuration files and shows how details of the
system configuration can be listed and modified.
Chapter 6 describes the information that is logged by Kognitio during normal
operation, where these logs are stored and how they can be used and maintained.
Chapter 7 explains how to monitor and control Kognitio disk resources. It gives
details about disk store slabs, procedures for adding or removing disk resources,
software RAID and lists the software steps required to recreate data on a disk
resource.
Chapter 8 discusses the method of targeting commands to particular Kognitio nodes.
Chapter 9 provides some additional information about the Kognitio daemons.
Chapter 10 describes hardware maps and shows how they are used by the system to
report missing hardware during the starting process.
Chapter 11 discusses how the state of the system is automatically monitored and
problems are reported.
Chapter 12 describes how Kognitio can be configured to automatically dump
debugging information and attempt to restart if a crash is detected

iv Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Chapter 13 explains how any Kognitio crashes can be detected and how to extract
information from the system. It also describes certain issues that have arisen in the
past and gives details of how they can be investigated and resolved.
Appendix A describes the Kognitio ODBC drivers produced by Kognitio; in
particular it details the attributes and their associated values that are specific to
Kognitio. The appendix also covers how Secure Shell (SSH) can be used to establish
a secure channel between the client and Kognitio.
Some of the examples of output in this manual have been slightly reformatted so
that they fit neatly on the page. In most cases this has been achieved by inserting
additional carriage returns, however in some cases, some data has been replaced by
ellipses () for the sake of brevity.

Kognitio Configuration and Maintenance Manual v
Data Classification - PUBLIC
Contents
About this Manual ................................................................................ iii
Contents .............................................................................................. v
1 System Description and Specification ........................................................... 1
1.1 Overview ................................................................................................... 1
1.2 Documentation .......................................................................................... 1
1.3 Processing and Memory ............................................................................ 2
1.4 SQL and ODBC ......................................................................................... 3
1.5 Kognitio Nodes and Processes .................................................................. 4
1.6 Kognitio Daemons ..................................................................................... 5
System Manager DaemonSMD ........................................................ 5
1.7 The Kognitio RDBMS System Tables ........................................................ 5
1.8 Kognitio Tools ........................................................................................... 6
1.9 Kognitio System Administration Identities .................................................. 7
1.10 System Requirements ............................................................................... 8
Processor, Memory and Operating System ......................................... 8
Communication Network ...................................................................... 8
Storage Networks and Disk Resources ............................................... 9
1.11 Physical System Description ..................................................................... 10
Hardware Notation ............................................................................... 10
Example .............................................................................................. 11
1.12 Customer Support ..................................................................................... 11
2 Installation, Licensing and Upgrades ............................................................ 15
2.1 Introduction ............................................................................................... 15
2.2 Installation ................................................................................................. 15
Phase 1: The wxinstaller Tool ....................................................... 16
Phase 2: The wxadmin Tool ............................................................... 17
2.3 Kognitio Licensing ..................................................................................... 19
Licence Actions and Types .................................................................. 19
Examples of Licence Manipulation and Use ........................................ 20
2.4 Version Numbers and Naming Conventions .............................................. 25
2.5 Software Upgrades .................................................................................... 26
2.6 Hardware Upgrades .................................................................................. 26

vi Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
3 The wxadmin Tool ............................................................................................27
3.1 Introduction ............................................................................................... 27
3.2 Second Stage Installation .......................................................................... 28
3.3 Information Reports ................................................................................... 28
3.4 Disk Resource Manipulation ...................................................................... 28
3.5 License Key Manipulation .......................................................................... 29
3.6 Configuration Option Manipulation............................................................. 29
3.7 Server Operations and Status Checks ....................................................... 29
3.8 Database Administration ........................................................................... 30
3.9 Troubleshooting ......................................................................................... 30
4 Startup and Shutdown .....................................................................................33
4.1 Starting Kognitio ........................................................................................ 33
Normal Start/Restart ............................................................................ 33
Attempting to Start When Hardware is Missing .................................... 35
4.2 Stopping Kognitio ...................................................................................... 35
Stopping Kognitio ................................................................................ 35
Stopping Kognitio and Daemons ......................................................... 35
Checking for User Sessions ................................................................. 35
5 Configuration Files and Parameters ...............................................................37
5.1 Description ................................................................................................ 37
5.2 Example .................................................................................................... 38
5.3 Describing Hardware ................................................................................. 38
5.4 Single System Image (SSI)........................................................................ 40
5.5 Additional Notes on Configuration File Entries ........................................... 40
5.6 Configuration Details wxserver info config ..................................... 41
5.7 Editing Configuration Details wxviconf ................................................ 41
5.8 Setting Parameters with SQL .................................................................... 41
6 Log Files ...........................................................................................................43
6.1 Logging ..................................................................................................... 43
The system log directory ...................................................................... 43
'Standard' Log subdirectories ............................................................... 44
'Non standard' Log subdirectories ........................................................ 45
Log file attributes ................................................................................. 45
Log Rotation ........................................................................................ 46

Kognitio Configuration and Maintenance Manual vii
Data Classification - PUBLIC
Log Expiry ........................................................................................... 46
Log full behaviour ................................................................................ 47
Logging Levels .................................................................................... 48
Other log files ...................................................................................... 48
7 Disk Resources ................................................................................................ 51
7.1 Disk Store Slabs and File Systems ............................................................ 51
Benefits ............................................................................................... 51
Details ................................................................................................. 51
New Virtual Tables .............................................................................. 54
7.2 Disk Compression ..................................................................................... 56
7.3 Fault Tolerance ......................................................................................... 57
Software RAID ..................................................................................... 58
Data Striping ........................................................................................ 58
Disk Redundancy ................................................................................ 58
Acceptable Limits ................................................................................ 59
Enabling Kognitio Software RAID 5 ..................................................... 59
System Tables Relating to RAID ......................................................... 60
7.4 Disk Resources and the Error Log ............................................................. 61
7.5 SQL Commands Relating to Disk Resources ............................................ 62
RECREATE DISK/CLUSTER .............................................................. 62
Starting/Stopping Disks - SPIN ............................................................ 62
DISK_REPAIR/DISK_CHECK ............................................................. 63
7.6 Virtual Disk-Stores ..................................................................................... 63
7.7 Standby Disks ........................................................................................... 64
7.8 Automatic Recreate of Bad Disks on Startup ............................................. 64
7.9 Disk Resource Reconfiguration and Deskewing ........................................ 65
Reconfigure ......................................................................................... 66
Deskewing ........................................................................................... 66
Reconfigure Down ............................................................................... 68
8 MOP Target Strings ......................................................................................... 71
8.1 Overview ................................................................................................... 71
8.2 MOP target strings .................................................................................... 71
9 Additional SMD Information ............................................................................ 73
9.1 Start Control .............................................................................................. 73

viii Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Primary Start ....................................................................................... 73
Start without loading any images in to RAM ......................................... 73
System Image...................................................................................... 74
9.2 Aborting the Starting Process .................................................................... 74
9.3 SMD Control .............................................................................................. 74
9.4 SMD Prefix for wxserver commands .......................................................... 74
9.5 The syntax command ................................................................................ 75
9.6 Checking Daemon Status .......................................................................... 75
9.7 SMD Fault Tolerance................................................................................. 75
The SMD Angel Process ..................................................................... 75
The SMD uses multiple communication links ....................................... 75
Automatic Kognitio Restart .................................................................. 75
Preventing nodes (especially virtual machines) being master .............. 76
Work Without Broadcasts (e.g. cloud environments)............................ 76
10 Checking Hardware Configuration ...............................................................77
10.1 Hardware Maps ......................................................................................... 77
Overview ............................................................................................. 77
Checking the hardware map ................................................................ 78
10.2 Starting when Hardware Missing ............................................................... 79
10.3 Starting with New Hardware ...................................................................... 79
10.4 System Tables for Monitoring Hardware .................................................... 79
11 System Monitoring and Alerts.......................................................................81
11.1 Introduction ............................................................................................... 81
11.2 Interacting with the monitor ....................................................................... 81
11.3 Monitor control........................................................................................... 82
11.4 Alerts ......................................................................................................... 82
Severity of the event ............................................................................ 82
Event codes ......................................................................................... 83
12 Automatic Crash Recovery ...........................................................................87
12.1 Requirements for Automatic Crash Recovery ............................................ 87
Dump and Restart Information ............................................................. 88
12.2 Automatic Recovery .................................................................................. 88
13 Trouble Shooting ............................................................................................91

Kognitio Configuration and Maintenance Manual ix
Data Classification - PUBLIC
13.1 Detecting Crashes ..................................................................................... 91
13.2 Investigation Options ................................................................................. 92
View history of recent SQL commands ................................................ 92
Display system status information ....................................................... 92
Collect all debugging info for troubleshooting ...................................... 93
Collect core dump files ........................................................................ 93
Collect full Query log ........................................................................... 93
Final Actions ........................................................................................ 93
Important Notes ................................................................................... 93
13.3 Other Problems ......................................................................................... 94
Running Out of Disk Space ................................................................. 94
Check for Busy Processes ................................................................... 94
Dump File Deletion .............................................................................. 95
A ODBC Attributes and SSH Access to Kognitio ............................................. 97
Introduction ....................................................................................................... 97
Kognitio Specific ODBC Attributes .................................................................... 99
SSH Access to Kognitio .................................................................................... 102
Index .................................................................................................................... 103

Kognitio Configuration and Maintenance Manual 1
Data Classification - PUBLIC
1

System Description and Specification
This chapter gives a basic description of the Kognitio architecture. It also describes the key
system requirements and performance considerations. The chapter also lists the associated
documentation that is available from Kognitio.
1.1 Overview
Kognitio is conceived and designed specifically to analyze full-volume detailed data
in very large databases. Kognitio allows tasks as diverse as rapid report generation,
ad-hoc querying, data mining, data exploration and routine analysis to be
performed. Databases are typically many terabytes in size, with larger systems
holding tens or hundreds of terabytes of data. Any organization working with
massive relational database tables can make use of Kognitio's rapid scan rates, and
the ability to join tables in parallel at high speed. Kognitio produces answers at a
speed that allows knowledge workers to investigate data in-depth, asking ad-hoc
questions on the spur of the moment in a Train-of-Thought analysis.
When designing Kognitio, the objective was to create a system that business
managersin the areas of operations, marketing, sales and financecould use to
interact intuitively at Train-of-Thought speed with any data that their organizations
collect, store and manage.
1.2 Documentation
In addition to this manual, the documentation set for Kognitio includes:
Chapter 1 - System Description and Specification
2 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
The SQL Guide (available in PDF only) documents the commands supported by
the Kognitio implementation of SQL.
The Kognitio Guide (available in PDF only) gives background details and in-
depth examples that examine the practicalities of running a Kognitio system.
There are also various Kognitio support forums; these can be accessed via
http://www.kognitio.com/forums.
1.3 Processing and Memory
The size of today's databases can be colossal, being measured in terabytes and
moving toward petabytes for leading edge organizations. This means that a fully
capable system must be able to analyze millions, and more probably billions of rows
per second. Kognitio achieves this by the use of massively parallel computing
techniques.
Kognitio is designed with a massively parallel shared-nothing architecture, where all
operations are performed in parallel by the processing nodes. Installation
configurations are not fixedthere is a great deal of flexibility in how systems are
configured to suit customer requirements.
Kognitio automatically loads the data it needs to execute a query into RAM where it
is scanned interactively without the need for normal indexes. This simple load and
go approach is a key advantage compared with competitors products and is
especially advantageous in data exploration applications.
A Kognitio user has the option to set up a permanent RAM image of a table or
selected columns from a table using the CREATE TABLE IMAGE statement. Any
changes to the table are reflected both in RAM and on the disk resource. Images of
tables are reinstated when Kognitio is restarted. If data from a table that is not in
RAM is required to satisfy a query, then it is streamed in to RAM during query
execution.
In certain situations the rate of loading data into RAM from disk resources can be
improved. If the disk-based data is ordered and/or clustered, then the use of
Kognitio Compressed Data Maps can be particularly beneficial.
The Kognitio Guide contains additional information about the methods used by
Kognitio to store, access and process data.
Chapter 1 - System Description and Specification
Kognitio Configuration and Maintenance Manual 3
Data Classification PUBLIC
1.4 SQL and ODBC
The primary method by which users interact with the Kognitio database is using the
Structured Query Language (SQL). Kognitio supports a subset of the ANSI SQL 92
standard plus some administration extensions. For more details see the Kognitio
SQL Guide.
The Kognitio plugin mechanism allows users to write their own C functions and call
them from within Kognitio SQL SELECT statements. A set of plugin functions
developed by Kognitio form part of the standard Kognitio release and is
documented in the Kognitio SQL Guide. For more information about developing
your own plugins see the Kognitio Guide.
Client applications connect to Kognitio using Open DataBase Connectivity (ODBC),
a standard database access method developed by Microsoft Corporation. The goal of
ODBC is to make it possible to access any data from any application. ODBC
manages this by inserting a middle layer, called a database driver, between an
application and the DBMS. The purpose of this layer is to translate the application's
data queries into commands that the DBMS understands. Kognitio provide ODBC
drivers for Windows and Linux. See the appendix ODBC Attributes for further
information.
Chapter 1 - System Description and Specification
4 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
1.5 Kognitio Nodes and Processes
The following diagram illustrates the high-level Kognitio architecture and shows
how it maps on to a systems processing, networking and storage capabilities.
WX
2
Node
WX
2
Node
WX
2
Node
WX
2
Node
WX
2
Node WX
2
Node
WX
2
Node
WX
2
Communication
Network
WX
2
Storage
Network
WX
2
Storage
Network
Corporate
Network
WX
2
Nodes are configured to be either Server or
Client nodes.
Server: Data processing and client tools
Client: Client tools

A number of Kognitio nodes are connected together via the Kognitio
Communication Network that provides an efficient, point-to-point and broadcast
message passing mechanism. One or more Kognitio Storage Networks provide
access to permanent storage.
Database nodes run various processesgiving the nodes various combinations of
capabilities. The primary capabilities are:
System Management
Daemon (SMD)
All day-to-day Kognitio administration tasks should
be performed through the SMD
RAMStore (RS) The RamStore manipulates data in RAM.
DiskStore (DS) The DiskStore manipulates data on Disk.
Compiler (Comp) The Compiler compiles a SQL query.
Interpreter (Int) The Interpreter runs the compiled SQL query.
Input/Output (IO) The IO process handles communication with the user.
Miscellaneous (Misc) The Misc process performs a variety of other database
tasks.
Chapter 1 - System Description and Specification
Kognitio Configuration and Maintenance Manual 5
Data Classification PUBLIC
1.6 Kognitio Daemons
A daemon is a program that runs continuously and exists for the purpose of
handling periodic service requests that a computer system expects to receive. The
daemon program forwards the requests to other programs (or processes) as
appropriate.
The Kognitio uses a System Manager Daemon (SMD), which can be running on any
number of nodes.
Note: The terms Kognitio services and Kognitio services are sometimes used as collective
terms for the daemons. These terms are normally used when it is necessary to
differentiate between the database and daemon processes.
System Manager DaemonSMD
The SMD is responsible for the following tasks:
Starting/stopping Kognitio.
Monitoring a system for problems.
Installing/uninstalling Kognitio software packages.
Software upgrades.
Synchronizing installed software versions and configuration details.
Expiring old log files and core dumps to prevent disks from filling up.
Alerting the administrator when problems occur.
Performing debug dumps if Kognitio crashes.
The SMD Angel process monitors the SMD; this is responsible for detecting
problems with the SMD and restarting it if necessary.
1.7 The Kognitio RDBMS System Tables
The Kognitio RDBMS uses a series of system tables in the SYS schema to define the
database structure, provide access to the operational and configurational status of
the database and allow access to the database logs. All Kognitio system tables have
the IPE_ prefix; this prefix is reserved for Kognitio use.
The tables fall into one of 6 main categories:
Data Dictionary Tables Define the state of the Kognitio database.
Virtual Tables Give the configuration and operational status of Kognitio.
Chapter 1 - System Description and Specification
6 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Log & Control Tables Referenced and/or modified by Kognitio.
Dictionary Views Views of the Dictionary Tables where data visibility is restricted
by the users current privilege settings.
Import & Export Tables Used during the Import and Export processes
Lookup Tables Contain information that can be used to interpret values in the
other system tables.
1.8 Kognitio Tools
The Kognitio release includes tools that allow the user to:
Administer Kognitio.
Move data to and from Kognitio and analyse it using SQL.
Install, configure and analyse Kognitio.
The following is a list of all the tools that are included with the release. While system
administrators and users will use some of these tools frequently, others are primarily
intended for use by Kognitio support and development personnel.
Administering Kognitio
wxserver A simple command line SMD client program.
wxadmin A logical task-based interface to the underlying Kognitio tools via a series
of hierarchical menus.
wxsvc A program for controlling the SMD and other services.
wxviconf A script for editing the system configuration file and activating the
changes.
Moving data to and from Kognitio and analysing it using SQL.
wxloader A tool to load data on to Kognitio in parallel.
wxunloader A tool to export data from Kognitio in parallel.
wxbackup A tool to backup data on Kognitio in parallel.
wxrestore A tool to restore backup data on to Kognitio in parallel.
wxsubmit A tool to run SQL on Kognitio and display any results.
Installing, configuring and analysing Kognitio
wxdgdump A tool for dumping individual processes.
wxdgtool The tool for creating debug dumps of a system.
wxdumpx A tool for working with debug dumps.
wxgetconfig A tool to determine certain details of the configuration.
wxinstaller The program to carry out the first stage of Kognitio installation.
wxlicence The tool to display and manipulate Kognitio licence key information.
wxpkg The tool for managing Kognitio software packages.
wxprobe A tool to scan the system and report on hardware present and what
Chapter 1 - System Description and Specification
Kognitio Configuration and Maintenance Manual 7
Data Classification PUBLIC
processes are running.
By default wxprobe gives a high-level summary. This checks for and
reports various common problems including:
- missing/crashed/duplicate Kognitio processes
- clock skew between Kognitio nodes
- wxdb or smd dumps
- discrepancies between current versions of software on Kognitio nodes
wxprobe s is used to look at any stopped processes.
wxtool A low-level administration tool.
wxsqlhist A tool to provide a list of the recently run SQL commands and their
associated state.
wxtop A tool to monitor the most active Kognitio processes, updating the
display at regular intervals. It is screen-based program that updates the
display in place.

Most of these tools have a considerable number of command line options and
arguments. Due to their complexity these are not listed here. All the tools have
explanatory help text which is displayed when the tool is run with the h or -?
option, e.g. wxserver -h will display the help text of the wxserver command.
When other sections of this manual refer to the usage of the tools in specific
circumstances, examples of the required command line arguments will also be
supplied.
1.9 Kognitio System Administration Identities
Three system administration identities are used by Kognitio.
$owner the owner of the system.
$master for Kognitio "destructive" operations, (e.g. new system), and for
altering rights and permissions.
$admin for all other day-to-day operation and database administration.
These values should be thought of as environment variables, e.g. for a typical
Kognitio these will be defined as $owner=root, $master=wxroot and
$admin=wxadmin.
These are the administration identities used to control and administer the Kognitio
platform. Different privileges are associated with each identity. Logging in with the
correct identity can help prevent running destructive operations by accident. These
identities should not be confused with the database user identities that will be set up
and maintained by the database administrator, who has the SYS identity.
Chapter 1 - System Description and Specification
8 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
1.10 System Requirements
The basic requirements of any system being commissioned to run Kognitio really
depend on what type of hardware the user has or intends to purchase, the amount of
data they wish to examine and the type of analysis they wish to perform. If required,
Kognitio can assist in the definition of hardware specifications and their
configuration. The key requirements to be considered are outlined below.
Processor, Memory and Operating System
Before Kognitio can be installed on a system each node must have a version of Linux
running on it. The following versions of Linux are currently supported:
Red Hat Enterprise Linux Red Hat Enterprise Linux 3 or later
Novell SUSE LINUX Enterprise Server Novell SUSE Linux Enterprise 9 or later
Each node should have at least 2GB of RAM available. The total amount of RAM
required is a function of the number of concurrent users and the required
performance level. If insufficient RAM is available to allow all the data required to
fulfill a particular query to fit in RAM, Kognitio will make multiple passes across the
data, thereby increasing query execution times. The Kognitio Guide contains a
section on sizing tables, views and view images and describes how to estimate the
RAM requirements of a system.
For best performance, it is important that the performance of all nodes is either
similar or scaled in terms of RAM and CPU power (i.e. if a node has twice the RAM
of another, it should have twice the CPU power.
Communication Network
All Kognitio nodes communicate with one another over the Kognitio
Communication Network. The Communication Network is implemented using fully
switched Ethernet.
The node interconnections must have sufficient bandwidth for the CPU power. For
optimal performance the CPU power and bandwidth need to be balanced. This is
difficult to specify, but two examples of successful configurations are:
A blade system where each blade has a 1200 MHz, Intel Pentium III Mobile
processor and 2 x 100Mbit links.
A blade system where each blade has 2 Hyper threaded 3 GHz Intel Xeon
processors each requiring 2 x 1Gbit links.
Chapter 1 - System Description and Specification
Kognitio Configuration and Maintenance Manual 9
Data Classification PUBLIC
Storage Networks and Disk Resources
One or more storage networks allow a number of nodes to access a number of disk
resources. It is not necessary for all nodes to be connected to a storage network. Disk
resources might physically map on to one or more of the following:
Raw disks.
Disk partitions.
Individual files.
Disk resources must be at least 2GB in size. There is no requirement for all the disk
resources to be implemented in the same way; however it is important that they are
all approximately the same size, as they will be rounded down to the size of the
smallest. This might mean, for example, that on a system with two sizes of disk, the
larger disks will need to be partitioned, with each partition being approximately the
same size as the smaller disks.
Storage networks might be provided by one of the following:
Local disks.
Storage Area Network.
Emerging Internet Protocol storage (IPS) technologies like iSCSI (Internet
SCSI).
There is no requirement for all the storage networks to be implemented by the same
technology; so for example, it would be quite legitimate for some nodes to access
local disks while others access disk resources via a SAN.
Internally Kognitio implements a simple linear file system to store user data. The
method of updating data is to write a new version, and indicate that the previous
record has been superseded. This concept of not updating in place provides the
benefit of consistent read-only database scans, with no interference from concurrent
updates.
Note that data is not physically deleted from the disk resource when a database
record is deleted. The operation of recovering disk space from the Kognitio file
system is known as reclaiming. During a reclaim all user data that is still valid is
concatenated into one contiguous chunk at the start of the user data area of the disk
resource, and all deleted and rolled back records are removed. Running a reclaim
has an impact on system availability and/or performance.
As well as the linear user data area, the disk resource also reserves approximately 50
MB of space to store start-up, workspace and other information.
Chapter 1 - System Description and Specification
10 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
In addition to storing the Kognitio database, disk resources may also be required for
the following:
Linux Swap space; this is used when RAM is full. If the system needs more
memory resources and the physical memory is full, inactive pages in memory
are moved to the swap space. While swap space can help machines with a small
amount of RAM, it should not be considered a replacement for more RAM, as
the disk resource will have a slower access time than RAM. Swap space can be a
dedicated swap partition (recommended), a swap file, or a combination of swap
partitions and swap files. Swap space may be particularly useful for non-
Kognitio processes that run occasionally on a node, for example, the extraction,
transformation and load (ETL) processes that are required if the node is used as a
data staging platform.
To provide a staging area for Kognitio data imports, exports and conversions.
The Kognitio Guide contains sections on sizing tables and import, export and file
conversions.
To hold data that may be generated during the analysis of hardware or software
performance issues. An area of at least 4 GB will ensure that sufficient
information can be gathered. The area can exist on multiple nodes to allow
information to be gathered in parallel or on a single node. Depending on the
usage patterns of Kognitio it may be possible to use the same area for both the
data staging area and analysis area.
The storage networks may be able to provide sufficient fault tolerance to guarantee
data integrity in the event of a component failure. If the storage networks do not
offer such guarantees, then Kognitio can be configured to provide the required fault
tolerance for the database.
It is therefore important when specifying the initial storage network and disk
resource requirements that capacity, performance and fault tolerance are all
considered. The way that data will be loaded, modified and analysed needs to be
understood to ensure that there is sufficient storage capacity to keep the reclaim
frequency at an acceptable level. It is also important to decide before the system is
configured what resources will be required for data loading, swap space and fault
investigation.
1.11 Physical System Description
Hardware Notation
The notation used to physically describe the location of hardware within a blade,
racked or distributed system will vary from vendor to vendor, (e.g. Rack
Enclosure Bay, Rack Slot Position, etc.). Kognitio is aware of the vendor's
terminology. The user can also define alternative terms.
Chapter 1 - System Description and Specification
Kognitio Configuration and Maintenance Manual 11
Data Classification PUBLIC
Example
Many of the details in the preceding sections of this chapter are summarized in the
way Kognitio describes its own particular configuration details. An example of a
section of this description is given below.
Hardware RLXBlade: Status Up.
rack 0: Status Up.
chassis 0: Status Up.
slot 18: ID rlx-0-0-18, sys Linux-2.4.18-27, Status Up
ram 1056288768, swap 268877824,
cpus 1, endian L, links 1.
Caps DES-IO-DS-RS-MI-DBG-KDVR.
Disk: uid WXD:410436CA:00000002,
sysid <NO BOOTINFO>, local Y
ncpus 1, Status Up.
cost 0, local 1, LStatus Up.
Attributes File-Sparse.
resource /home/des_disk.
nsecs 20000000, ssize 512.
slot 20: ID rlx-0-0-20, sys Linux-2.4.18-27, Status Up
ram 1056288768, swap 268877824,
cpus 1, endian L, links 1.
Caps DES-IO-DS-RS-MI-DBG-KDVR.
Disk: uid WXD:410436CA:00000003,
sysid <NO BOOTINFO>, local Y
ncpus 1, Status Up.
cost 0, local 1, LStatus Up.
Attributes File-Sparse.
resource /home/des_disk.
nsecs 20000000, ssize 512.
Notes
1. The hardware is divided into blocks. A block is defined as a group of
physically connected nodes, which in this example is the single block called
chassis 0.
2. At the lowest level of each block, the details of the node are displayed, details
include the nodes name, the version of the operating system it is running, its
operational status, capabilities and details of the RAM, CPU and disk resources.
3. By default the nodes hostname is used to identify it. If this name is not unique,
then a unique name is generated from the details of the nodes position within
the system.
1.12 Customer Support
If you experience any problems with Kognitio or require any further information on
any of Kognitios products or services, please contact
Chapter 1 - System Description and Specification
12 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
The Support Manager
Kognitio Limited
Kognitio Technology Centre
3a Waterside Park, Cookham Road
BRACKNELL, RG12 1RB
United Kingdom
Telephone: (+44) 1344 300 770
Facsimile: (+44) 1344 301 424
Email: wx2-helpdesk@ Kognitio.com


Kognitio Configuration and Maintenance Manual 13
Data Classification - PUBLIC

Kognitio Configuration and Maintenance Manual 15
Data Classification - PUBLIC
2

Installation, Licensing and Upgrades
This chapter looks at the methods of installing, licensing and updating Kognitio. It gives
details of the package version numbers and naming conventions and describes how packages
should be managed.
2.1 Introduction
The initial Kognitio release is distributed as a self-install package that both
configures the Kognitio environment and installs the software. Subsequent upgrade
packages are supplied in a format suitable for installation in an existing Kognitio
environment.
There are two phases of the Kognitio installation, the first has to be run on each node
that is to form part of the Kognitio system. Once this stage is complete all the
Kognitio nodes are running the Kognitio services and are linked together. The
second phase of the installation is then run on this collection of nodes to configure
them as a parallel RDBMS.
Stage 1 of the installation can be automated and/or make use of cloning. This is
particularly beneficial for systems containing a large number of nodes.
2.2 Installation
Kognitio releases are provided as Linux self-install packages, named
install-version.sfx.
Chapter 2 - Installation, Licensing and Upgrades
16 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
When run on a clean system, that is one with no Kognitio environment at all, the
installer will perform an interactive stage 1 install, asking 4 questions (system ID,
networks, $master password and $admin password). It is possible to specify this
information on the command line to make the install non-interactive.
Phase 1: The wxinstaller Tool
The first stage of installing Kognitio on a freshly commissioned Linux system is
performed with the wxinstaller tool. wxinstaller is part of the of the self-
extracting software package.
The Kognitio end user license agreement (EULA) must be accepted before Kognitio
can be installed. During an interactive installation the EULA will be displayed and
the user must confirm they accept the conditions to allow the installation to proceed.
For a non-interactive install it is possible to accept the EULA using the following
wxinstaller command line argument -O accept_eula=yes.
The first stage of installing Kognitio consists of the following steps:
1. Transfer the release file on to the individual nodes that are to run Kognitio.
2. Logon with the $owner identity.
3. Run the self-extracting file, this will ask for several pieces of information,
namely:
a) The system id This is required to identify the cluster of nodes that will
run Kognitio. This id is also used to tag disk resources and may be tied to a
particular license key. Care needs to be taken to ensure that the name is both
unique for each individual Kognitio system being configured on a site and that it is
consistent with any supplied licence keys.
b) The internal network interfaces to be used for clustering by Kognitio The
complete list of interfaces on the system can be displayed by running
ifconfig -a.
c) Whether the $master identity is to be created and if so the password to be
used if this user has already been created on the system, then this
question is omitted.
d) Whether the $admin identity is to be created and if so the password to be
used if this user has already been created on the system, then this
question is omitted.
e) Whether a server install or a client install should be run on the node. A
client install lets you access the database, but the database doesn't run on
that node. A server install will install the full database software on the
node.
4. The set-up continues with the required directories, users, packages, pointers
and files being created and installed as required. The first stage of the
installation on this node is now complete and it is running in single-system
mode with a SMD started.
Chapter 2 - Installation, Licensing and Upgrades
Kognitio Configuration and Maintenance Manual 17
Data Classification - PUBLIC
5. Before wxinstaller exits it displays a command line that performs the
specified installation without any user interaction this can be used directly
(cut and paste) on the other nodes of the system. (On larger systems a
provisioning tool or Unix script might be used). When the phase 1 of the install
is complete, the following will exist on all the Kognitio nodes this can be
confirmed by running a wxprobe -w command:
a) The SMD process.
b) The layout file which records the details of what has been created.
c) The config and local_config files.
d) The $master and $admin users, with home directories in
/opt/kognitio/wx2 containing .bashrc and .profile files.
6. After phase 1 of the installation has been run on all the nodes of the cluster,
(either using wxinstaller, cut/paste or a provisioning tool), the initial
interactive session is complete; before exiting the user is given the option of
running the wxadmin tool to perform the second install phase on this cluster of
nodes and configure them as a parallel RDBMS.
Phase 2: The wxadmin Tool
The wxadmin tool provides a logical task-based interface to the underlying Kognitio
tools via a series of hierarchal menus. The tool allows the majority of administration
function to be performed, including the second install phase. The top-level menu
offers the following options:
Help More information about using the menus.
Setup Perform the entire second stage installation procedure.
Info Display information reports about the system.
Disks Create, configure and examine disk storage resources.
Licenses Add/Remove license keys or examine available licenses.
Config Change or examine the server's configuration options.
Server Perform operations on the server or examine its state.
Database Perform admin operations on the database.
Troubleshooting Assist in troubleshooting problems and collecting system
information.
The Setup option should be used to complete the installation; this guides the user
through the standard Kognitio set-up procedure to produce a working database.
This procedure is summarised below:
1. Check that the hardware summary information reported by the system is
correct by using the Info menu.
Chapter 2 - Installation, Licensing and Upgrades
18 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
2. The Disks menu should then be used to add any required disk resources and
check that the resulting summary information is correct. Kognitio will
automatically detect data storage disk partitions with a partition type of 60 Hex
(0x60). Kognitio recommend that the user use a single large partition of type
0x60 as no additional set-up is required and optimal performance is obtained.
The user should only use files if partitions are not practical. If disk resources are
to be implemented using disk files, their size can be specified when prompted
with:

Enter any other options you would like to specify (e.g. size)

The default is to use 16GB files. If you want to use a different size (e.g. 10GB)
you should respond with something like the following, after ensuring that there
is enough free disk space on all nodes:

size=10G

Note that the minimum file size is 2GB. The disk resource can be specified as
being of one of the following types:

File This is a normal file on the file system and is the
default if no type is specified.
Sparsefile Similar to 'file' but the system will use a sparse file for
unused data locations. Sparse files are created by
seeking beyond the end of a file and then writing
data; only non-null blocks are actually written to disk,
enabling data to be stored much more efficiently.
Partition This is a partition file (e.g. /dev/hda2)
Raw This is a raw disk device (e.g. /dev/raw/raw1)

3. Software licence keys should then added and checked from the Licenses menu.
A run-time licence for Kognitio will be required from Kognitio. The licence to
permit or restrict access to the system can be specified in a variety of ways,
examples include the number of concurrent users and the maximum amount of
disk or RAM in the system. Kognitio will typically email licence keys to users of
the system as required. Additional details about the Kognitio licensing
mechanism can be found in section 2.3, Kognitio Licensing.
4. Provided that at least one disk resource and one licence key was specified, the
Kognitio environment should be working. To complete the installation select the
Newsys option from the Server menu.
5. The Database menu can now be used to connect to Kognitio and run SQL.
Chapter 2 - Installation, Licensing and Upgrades
Kognitio Configuration and Maintenance Manual 19
Data Classification - PUBLIC
2.3 Kognitio Licensing
Licence Actions and Types
Each Kognitio software licence enables a licensed action to be performed on a
Kognitio system. Licensed actions can be either unique, e.g. run the new system
command, or ongoing, e.g. run Kognitio for 1 hour on 5 nodes. For ongoing actions,
multiple licences can be combined.
The Kognitio licensing mechanism is highly flexible. Kognitio provide the following
types of licence:
Full permanent licence: unrestricted Kognitio use.
Resource limit licence: specifies the maximum amount of a Kognitio resource
that can be used, e.g. number of nodes, CPUs, disks, RAM, etc.
Calendar based licence: limits Kognitio use to a specific time window, e.g. 1
st

October 2006 14
th
October 2006).
Runtime limit licence: limits Kognitio use to a specific number of hours of
runtime.
Periodic repeating licence: limit Kognitio use within a specific period, at the end
of the period the limit is reset, e.g. allow 20 hours of runtime per month.
Hardware licence: limit Kognitio use to specific hardware components, e.g.
nodes with specific MAC addresses.
It is possible to combine different licence types in to a single licence. For example,
the resource limit, runtime limit and periodic repeating licences could be combined
to provide a 100 Gigabyte RAM hours a month licence a license to use a
Gigabyte of RAM for 100 hours every month.
Licences fall in to one of two categories: base or extension. A system must have a
single base licence, to which can be added any number of extension licences. It is
possible to use several different licences at the same time. For example, a user might
have a permanent 5-node base licence and the 100 Gigabyte RAM hours a month
extension licence from the above example. They could boot a 10-node system using
the 5-node license for 5 nodes and the Gigabyte RAM hour license for the remainder.
Once the 100 Gigabyte RAM hours had been used the user would have to revert
back to a 5-node system.
The licensing mechanism allows Kognitio to provide on-demand Kognitio licences.
For example a customer could buy 10 individual 1 Gigabyte hour licences; they
could then run a 1GB system for 10 hours, a 10GB system for 1 hour or something
more complex. The on-demand licence makes it easier for a user to specify their
licence requirements as it doesn't stipulate their configuration, allowing them to use
the most appropriate configuration as and when their requirements change.
Chapter 2 - Installation, Licensing and Upgrades
20 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Each licence has a unique identifier that is associated with an individual customer
and Kognitio system. This ensures that Kognitio can:
Ensure that licences issued for one Kognitio system can only be used with other
licences for the same system.
Invalidate existing licenses in new license.
Track down those responsible if a given key was misused.
The process of installing and using licenses is easy and straightforward.
Examples of Licence Manipulation and Use
The following examples show the licences menu of wxadmin being used to list and
manipulate licensing information; in addition there are examples of the error
messages displayed when various licensing restrictions are violated:
Example 1: Licensing Summary Report
This example illustrates the summary report. Two licences are shown, an unlimited
base licence and a gigabyte hour extension licence.
This menu allows you to add WX/DB software license keys to
the system, remove them or examine the licenses you currently
have available.

Options:
1: help -- More information about WX/DB software licensing.
2: summary -- Show licensing summary report.
3: list -- List currently active license keys.
4: add -- Add license keys to the system by typing.
5: addfile -- Add license keys to the system from a key file.
6: remove -- Remove license keys from the system.

Done: Finished in this menu.
Top: go to top level.
Exit: exit this program.

Choice (default Done): 2
-----------------------------------------
1 unlimited usage licenses:
new_system: yes.
ram_node_gb: 16 (Using 16, expired 0).
disk_usable_gb: 160 (Using 160, expired 0).

1 usage limited licenses:
ram_node_gb: 60 mins*count (expired 0 mins*count).
disk_usable_gb: 600 mins*count (expired 0 mins*count).
Chapter 2 - Installation, Licensing and Upgrades
Kognitio Configuration and Maintenance Manual 21
Data Classification - PUBLIC

Next license expiry on Thu Jun 15 18:00:00 2006.
2 good licenses, 0 invalid/expired keys ignored.
Example 2: List Currently Active License Keys
This example illustrates the list report. Two licences are shown, an unlimited base
licence and a gigabyte hour extension licence.
This menu allows you to add WX/DB software license keys to
the system, remove them or examine the licenses you currently
have available.

Options:
1: help -- More information about WX/DB software licensing.
2: summary -- Show licensing summary report.
3: list -- List currently active license keys.
4: add -- Add license keys to the system by typing.
5: addfile -- Add license keys to the system from a key file.
6: remove -- Remove license keys from the system.

Done: Finished in this menu.
Top: go to top level.
Exit: exit this program.

Choice (default Done): 3
-----------------------------------------
License information:
Lic 1193405: Num licenses 1.
generated Thu Jun 8 03:43:01 2006.
Type EXTENSION.
valid for 60 mins.
License allows:
disk_usable_gb 10 (10 * 1)
ram_node_gb 1 (1 * 1)
License valid if:
num_mins 60
license_version 1
valid_to Thu Jun 15 18:00:00 2006
system_id mywx2
base_license no
Lic 1193391: Num licenses 16.
generated Tue May 30 07:38:00 2006.
Type BASE.
License allows:
disk_usable_gb 160 (10 * 16)
ram_node_gb 16 (1 * 16)
new_system yes
License valid if:
license_version 1
valid_from Tue May 30 18:00:00 2006
valid_to Sat Dec 30 18:00:00 2006
Chapter 2 - Installation, Licensing and Upgrades
22 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
system_id mywx2
base_license yes
Example 3: Add License Keys By Typing
This example shows how an obfuscated licence key is added by typing (or pasting)
in the key.
This menu allows you to add WX/DB software license keys to
the system, remove them or examine the licenses you currently
have available.

Options:
1: help -- More information about WX/DB software licensing.
2: summary -- Show licensing summary report.
3: list -- List currently active license keys.
4: add -- Add license keys to the system by typing.
5: addfile -- Add license keys to the system from a key file.
6: remove -- Remove license keys from the system.

Done: Finished in this menu.
Top: go to top level.
Exit: exit this program.

Choice (default Done): 4
-----------------------------------------
Enter the license key to add
(ctrl-c goes back, type ? for help)
? d1TBA.zwQjWIdPjXfrhGVm1UasBVUsrHVfgJTVZWuYv089GeQ
Example 4: Add License Keys From File
This example shows how a licence key is added from a file. Note that the full
pathname of the file has to be specified. The contents of the file will be an obfuscated
string of the form used in the previous example. Kognitio licence key files have a
default extension of wxli.
This menu allows you to add WX/DB software license keys to
the system, remove them or examine the licenses you currently
have available.

Options:
1: help -- More information about WX/DB software licensing.
2: summary -- Show licensing summary report.
3: list -- List currently active license keys.
4: add -- Add license keys to the system by typing.
5: addfile -- Add license keys to the system from a key file.
6: remove -- Remove license keys from the system.

Done: Finished in this menu.
Chapter 2 - Installation, Licensing and Upgrades
Kognitio Configuration and Maintenance Manual 23
Data Classification - PUBLIC
Top: go to top level.
Exit: exit this program.

Choice (default Done): 5
-----------------------------------------
Enter the file to take license keys from
(ctrl-c goes back, type ? for help)
? /opt/Kognitio/wx2/home/wxadmin/1gbhrextension.wxli
Example 5: Remove License Keys
This example shows how a licence key is removed. The licence number is identified
from the list of currently active licence keys (see Example 2: List Currently Active
License Keys).
This menu allows you to add WX/DB software license keys to
the system, remove them or examine the licenses you currently
have available.

Options:
1: help -- More information about WX/DB software licensing.
2: summary -- Show licensing summary report.
3: list -- List currently active license keys.
4: add -- Add license keys to the system by typing.
5: addfile -- Add license keys to the system from a key file.
6: remove -- Remove license keys from the system.

Done: Finished in this menu.
Top: go to top level.
Exit: exit this program.

Choice (default Done): 6
-----------------------------------------
Enter the license number of the license to remove
(ctrl-c goes back, type ? for help)? 1193405
-----------------------------------------
YOU ARE ABOUT TO REMOVE LICENSE NUMBERED 1193405
About to remove license(s).
Enter to continue or ctrl-c to abort.
Example 6: License Usage
This example shows the output of the summary and list reports for an expired
Gigabyte hour licence. The system used for this example was configured as follows:
Disk resources: 50GB in 5 disks.
System RAM 7604MB, 7604MB for data processing.
8 CPUs available for data processing.
As the system has 7GB RAM we have used 7 of our 8 Gigabyte hour licences.
Chapter 2 - Installation, Licensing and Upgrades
24 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
-----------------------------------------
1 usage limited licenses:
new_system: yes.
ram_node_gb: 480 mins*count (expired 420 mins*count).
disk_usable_gb: 4800 mins*count (expired 4200 mins*count).

Next license expiry on Thu Jun 15 18:00:00 2006.
1 good licenses, 0 invalid/expired keys ignored.
-----------------------------------------
License information:
Lic 1193406: Num licenses 8.
Num used up 7.
generated Thu Jun 8 03:48:43 2006.
Type BASE.
valid for 60 mins.
License allows:
disk_usable_gb 10 (10 * 1)
ram_node_gb 1 (1 * 1)
new_system yes
License valid if:
num_mins 60
license_version 1
valid_to Thu Jun 15 18:00:00 2006
system_id mywx2
base_license yes
Example 7: License Limit Exceeded
This example shows a connection attempt to a system where a licence has either
expired or is insufficient for the system resources available.
> wxsubmit -s localhost
Submit - SQL Submission and Report Tool
Unable to connect to server localhost
HY000: [Kognitio][9800 Series Driver]
LC010F: Unlicensed data storage RAM used
Example 8: Connection attempt With No Valid License Keys
This example shows a connection attempt to a system where no valid licences are
available.
> wxsubmit -s localhost
Submit - SQL Submission and Report
Unable to connect to server localhost
HY000: [Kognitio][9800 Series Driver]
LC0142: No valid license codes found
Chapter 2 - Installation, Licensing and Upgrades
Kognitio Configuration and Maintenance Manual 25
Data Classification - PUBLIC
Example 9: No Base License
This example shows a connection attempt to a system where no base licence is
available.
> wxsubmit -s localhost
Submit - SQL Submission and Report Tool
Unable to connect to server localhost
HY000: [Kognitio][9800 Series Driver]
LC0140: No base license found
Example 10: Multiple Base Licences
This example shows a connection attempt to a system where multiple base licences
are available.
> wxsubmit -s localhost
Submit - SQL Submission and Report Tool
Unable to connect to server localhost:6550
HY000: [Kognitio][9800 Series Driver]
LC0141: Multiple base licenses
2.4 Version Numbers and Naming Conventions
The version number format for Kognitio releases is as follows:
The version number is a 5-digit number containing the major, minor and
incremental version number.
Each software version also has a patch string associated with it. For normal
releases, this will be a, b, etc., but for custom releases it might be anything, e.g.
andy1, importfix3, etc.
The version string for a package is made up from the above information and
looks like Major.Minor.Incremental-PatchString. This is the string
printed out by the tools when they are asked for the version number.
Each release has a package root directory. The format of this is:
verVersionNumberPatchString, (e.g. ver50206a). This is the directory in
/opt/kognitio/wx2 that the software will be installed into. This is also
referred to as the package name.
Kognitio is installed below the /opt/kognitio/wx2 directory. Inside this
directory, various software versions are installed in verXXXXX directories.
Chapter 2 - Installation, Licensing and Upgrades
26 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
2.5 Software Upgrades
The upgrade process is controlled by the SMD. The two commands for upgrade,
which can be submitted via either wxadmin or wxserver, are:
upgrade to PackageName This upgrades to a package that is already
installed.
upgrade using Filename This performs an install Filename
followed by upgrade to PackageName.

2.6 Hardware Upgrades
Kognitio is designed to make it very straightforward to incorporated additional
nodes to the system. Once a phase 1 install has been performed on any new nodes
they will automatically be integrated in to the system the next time Kognitio is
restarted.
Note however that any new disk resources will not be incorporated until a RECONFIGURE
command has been run via the wxadmin command line tool.

Kognitio Configuration and Maintenance Manual 27
Data Classification - PUBLIC
3

The wxadmin Tool
The wxadmin tool can be used for routine Kognitio configuration and administration tasks. It
is also used to perform the second phase of Kognitio installation. This chapter describes the
functionality that is available.
3.1 Introduction
The wxadmin tool provides a logical task-based interface to the underlying Kognitio
tools via a series of hierarchal menus. The tool allows the majority of administration
functions to be performed, including the second install phase. The tool has extensive
on-line help text.
The top-level menu offers the following options:
Entry Description
Help More information about using these menus.
Setup Perform the entire second stage installation procedure.
Info Display information reports about the system.
Disks Create, configure and examine disk storage resources.
Licenses Add/Remove license keys or examine available licenses.
Config Change or examine the server's configuration options.
Server Perform operations on the server or examine its state.
Database Perform administration operations on the database.
Troubleshooting Troubleshoot problems / collect system information.
Chapter 3- The wxadmin Tool
28 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Menu options can be chosen either by entering the options name or the associated
number. Some options navigate the menu hierarchy; others perform actual
operations. Menu options can be chained together with a plus sign, for example:
wxadmin server+start. Sometimes, wxadmin will request additional
information to allow it to complete the chosen option. Some menu options activate
scripts that automatically navigate the menu hierarchy and select options, when this
occurs the scripts name is included as part of the prompt. wxadmin will always
request confirmation before performing any task that can potentially alter the state
or configuration of Kognitio. Ctrl+C can be used at any time to revert to the
previous menu. In cases where the generated output would fill more than one
screen, it is displayed a screen full at a time, using the system's more command.
3.2 Second Stage Installation
This option walks the user through the second stage installation procedure
providing extensive help and guidance while automatically selecting various menus
for them. This process is described in detail in chapter 3, Phase 2: The wxadmin
Tool
3.3 Information Reports
Display information reports about the system.
Entry Description
System Summarise the hardware that makes up the system.
Nodes Summary report on nodes in the system.
Disks Summary report on disk resources in the system.
Capabilities Summary report on system capabilities.
List List the system's hardware resources.
Fulllist Detailed list of the system's hardware resources.
3.4 Disk Resource Manipulation
This menu allows a user to add disk resources to the system or examine those that
are present.
Entry Description
Help More information about disk resources.
Summary Display a summary of the disk resources in the system.
Chapter 3- The wxadmin Tool
Kognitio Configuration and Maintenance Manual 29
Data Classification - PUBLIC
List Display a list of the disk resources configuration.
Create Create one or more disk resources.
Change Change settings for one or more disk resources.
Remove Remove one or more disk resources.

Note: If you are using Kognitio disk partitions, you do not need this menu; instead, create the
partitions required, give them partition ID 60 (hex) and Kognitio will detect and
use them automatically.
3.5 License Key Manipulation
This menu allows a user to add or remove Kognitio license keys and examine the
licenses that are currently available.
Entry Description
Help More information about Kognitio licensing.
Summary Show licensing summary report.
List List currently active license keys.
Add Add license keys to the system by typing (or cut/paste).
Addfile Add license keys to the system from a key file.
Remove Remove license keys from the system.
3.6 Configuration Option Manipulation
This menu allows the configuration details of Kognitio to be changed.
Entry Description
Help More information about Kognitio software
configuration.
System Alter system-wide configuration options.
Local Alter per-node configuration options for this node.
Remote Alter per-node configuration options for other nodes.
Apply Restart SMD to make changes take effect.
3.7 Server Operations and Status Checks
This menu allows a user to control or examine the state of Kognitio.
Chapter 3- The wxadmin Tool
30 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Entry Description
Help More information about Kognitio system administration.
State Show the state of the whole Kognitio system.
Start Start (or re-start) the whole Kognitio on all nodes.
Halt Halt Kognitio.
Shutdown Halt the system and stop Kognitio services on all nodes.
Services Show the state of Kognitio services on this node.
Reinit Re-start Kognitio services on this node.
Stop Stop Kognitio services on this node.
Reconfigure Re-configure the database to use new disk resources.
Newsys Wipe all existing data and create a new database.
Smdcli Type commands directly to the system management interface.

The new system command reinitializes all the Kognitiodisk resources and then regenerates
the initial system tables. Obviously any data that existed prior to the new system is lost.
3.8 Database Administration
The database administration menu allows a user to run SQL commands and perform
various other database administrative tasks. The database must be up and running
for these options to work. If the connection fails, check the server state from the
Server Operations and Status Checks menu.
Entry Description
Sql Submit SQL to the system.
Sysimage Drop all RAM table images.
Crimage Run 'create image' to refresh the system.

3.9 Troubleshooting
The troubleshooting menu allows a user to analyse database problems and also
capture additional information to assist Kognitio investigations.
Entry Description
Check Check all nodes for problems.
Showhist View recent SQL command history.
Showinfo Display system status information.
Dump Collect debugging information for analysis by Kognitio.
Chapter 3- The wxadmin Tool
Kognitio Configuration and Maintenance Manual 31
Data Classification - PUBLIC
Cores Collect core files for Kognitio processes.
Gethist Collect the Kognitio SQL history log
Getinfo Collect system status information.


Kognitio Configuration and Maintenance Manual 33
Data Classification - PUBLIC
4
Startup and Shutdown
This chapter shows how to start and stop Kognitio.
4.1 Starting Kognitio
Normal Start/Restart
A normal start is performed by the $admin user, and consists of selecting the
wxadmin server start menu option or alternatively running the
wxserver start command
This starts or restarts Kognitio on all nodes. If Kognitio restarts successfully then the
following message will be displayed:
Startup complete. SERVER IS NOW OPERATIONAL.
If Kognitio is unable to be started successfully then an appropriate error message
will be displayed to indicate the type of problem encountered.
To speed up system restarts, it is possible to reuse the memory Kognitio was using
prior to the restart, rather than have to reload all objects into memory again.
Attempting to reuse memory is enabled by default for wxserver start but not for
wxserver start sysimage.
Table/view image data is stored in Persistent Memory Areas (PMAs). These occupy
a percentage of the RAM available for in-memory processing; the remaining RAM is
used for transient data such as temporary tables created by the query optimiser, sort
buffers, etc.
Chapter 4- Startup and Shutdown
34 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
The percentage of RAM used for PMAs is set with the rs_core_pma_size
parameter in the [boot options] section of the configuration file. This defaults to
70. To disable use of PMAs (and hence prevent fast restarts), set the parameter to 0
and restart. Note that Kognitio CAN use PMA memory for transient objects if
required, but this is transparent to the user.
A new command restore image has been added. This is identical to create
image but it will only work if previous memory can be reused.
To restart with recovery of old images, and error if that fails, use:
wxserver start recover
To attempt to recover old images, and do an old-style create image if that fails,
use:
wxserver start recover or image
To attempt to recover old images, and do an old-style create system image if
that fails, use:
wxserver start recover or sysimage
To restart without attempting recovery of old images:
wxserver start [sysimage] without recovery
There are also configuration file options that control system behaviour when the
original wxserver start [sysimage] commands are used:
[boot options]
auto_recover_on_image=yes/no
auto_recover_on_sysimage=yes/no
require_auto_recover=yes/no

The auto_recover_on_image/sysimage options make the original restart
commands behave as if the recover tag had been used. The former will default to
on and the latter to off.
The require_auto_recover option makes all restarts behave as start
recover unless they explicitly have without recovery appended. This will also
default to off.
The wxpmatool tool is available to manipulate PMAs.
Chapter 4- Startup and Shutdown
Kognitio Configuration and Maintenance Manual 35
Data Classification - PUBLIC
Attempting to Start When Hardware is Missing
The SMD prevents Kognitio starting if any essential hardware that was detected
when the system was previously running is now missing. If the start fails, the SMD
will try starting Kognitio again to see if the failure was caused by a transitory fault
associated with an initialization, configuration or timing issue. If the failure persists
then contact the Kognitio Helpdesk for further advice, (see section 1.12: Customer
Support for the contact details).
4.2 Stopping Kognitio
Stopping Kognitio
To stop Kognitio, select the wxadmin server halt menu option or
alternatively run the wxserver halt command.
Stopping Kognitio and Daemons
To stop Kognitio and the Kognitio services on all nodes, select the wxadmin
server shutdown menu option, or alternatively use wxadmin
server+shutdown from the command line.
Checking for User Sessions
No checks are performed to check if any users are connected to Kognitio when it is
halted or shutdown and users will receive no warning from Kognitio that the halt or
shutdown is imminent. It is therefore important to assess the impact of the operation
on any users of the system.
Whenever possible any queries or operations that are currently running on Kognitio
should either be allowed to complete or aborted before the system is shutdown.
Failure to do this may temporarily affect the performance or availability of Kognitio
when it is restarted, as any incomplete operations may have to be rolled back or
resumed.

Kognitio Configuration and Maintenance Manual 37
Data Classification - PUBLIC
5

Configuration Files and Parameters
This chapter discusses Kognitio configuration files and shows how details of the system
configuration can be listed and modified. It also describes the SQL commands for setting
parameters and the system tables that contain parameter details.
5.1 Description
Kognitio configuration files are held in the /opt/kognitio/wx2/etc directory.
They have a similar form to Microsoft Windows .ini files, in that related parts of
the configuration are grouped together, and each group is introduced by a keyword
in square brackets. The items controlled by the configuration files are:
Client-Kognitio communication.
Path and command line information.
Starting options.
Security information.
Configuration options and parameters.
There are two types of configuration files, global and local. The global configuration
file, called config holds information that is appropriate for replication across all
Kognitio Nodes. Configuration information specific to an individual Kognitio Node
is specified on that node in a configuration file called local_config.
Default values exist for all possible configuration file entries and will be used if
neither configuration file overrides it. If an entry exits in both configuration files,
then the local file entry will be used in preference to the global one.
Chapter 5- Configuration Files
38 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
5.2 Example
The following is an example of a global configuration file. Not all possible entries are
shown, since normally the file installed when Kognitio is commissioned will contain
the minimum number of required entries. Occasionally you may be advised to add
or alter entries if the configuration or use of the system changes (e.g. the number of
users is increased).
The general section contains details about the hardware and daemons and how they
communicate.
[general]
daemon_port=6550
system_id=mywxdes
The boot options describe how the RDBMS system should be configured.
[boot options]
raid_cluster_size=2
num_comp_nodes=8
num_int_nodes=30
The runtime parameters, which can also be change dynamically via SQL, allow
certain aspects of the RDBMS to be altered.
[runtime parameters]
lkti=10
It is possible to define what should occur if the SMD detects certain events or classes
of event.
[wxsmd events]
severity_70=exec /home/mikeb/evh
on_power_up=exec /home/mikeb/puevh
5.3 Describing Hardware
The notation used to describe the physical location of hardware within a blade,
racked or distributed system will vary from vendor to vendor, (e.g. Rack
Enclosure Bay, Rack Slot Position, etc.). Kognitio is aware of the vendor's
terminology. Blade users can also use the mechanism described below to define
alternative terms in the local_config file.
Chapter 5- Configuration Files
Kognitio Configuration and Maintenance Manual 39
Data Classification - PUBLIC
If Kognitio is installed on nodes that cannot report their position (i.e. not blades)
then the location information has to be specified via the configuration files. It is
important that this is done correctly as the location information is used to ensure
that message passing traffic associated with SW RAID stays within a block. The
connectivity within a block is the best available, the connectivity between blocks
might not be so good. So in blade systems a block corresponds to an enclosure,
whereas in a non-blade system it might correspond to a rack.
It is possible to specify location information in the local_config file on each node, but
it is often more convenient to specify the information via another file and reference
that file from the local_config file; this section describes the latter method.
As root on each of the nodes edit the /opt/kognitio/wx2/etc/local_config
file, and specify a file which contains the location information. Add lines similar to
the following:
[includes]
location_info=/opt/kognitio/wx2/etc/wx2-location
Then on each node create the /opt/kognitio/wx2/etc/wx2-location file, this
must be root-owned and non-writable like all other Kognitio configuration files.
Within that file you can specify which attributes should be treated as defining a
block, and which are specific to an individual node. This file could be generated
via a script during system deployment. The following is an example of the contents
of a typical file:
[system]
block_attrs=room,rack
proc_attrs=nodenum

[attributes]
room=server_room
rack=17
nodenum=3
You can also specify the following:
block, which is made up from concatenating the block_attr values with '-' in
between.
proc, which is made up from concatenating the proc_attr values with '-' in
between.
Notes: Any of the above values can be set within back quotes to run a command to get
the value
The [system] section could go into the local or global config file rather than the
location file if it is the same for all nodes.
Chapter 5- Configuration Files
40 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
5.4 Single System Image (SSI)
Single System Image (SSI) allows a Kognitio system to present itself as a single
system with a single system name regardless of how many Kognitio nodes it
contains. Kognitio connections are transparently redirected to balance the
connection load.
The form used to set up the ODBC connections to a Kognitio system allows for
multiple IP addresses to be added. Not all the Kognitio node IP addresses have to be
added to this list. The list is used to identify the node that will handle the initial
connection requests from clients; these connections can either be accepted or
redirected to any of the other nodes in the system.
A connection can be forced through a particular Kognitio node by setting the
ForceConnect parameter when the ODBC connection is set up.
If a system is reconfigured down, care needs to be taken to ensure that the list of
Kognitio node addresses used by ODBC to handle the initial connection request is
still correct.
To make use of SSI, set external_net in the [system] section of the config file to
an interface used by the server software that clients can also talk to, for example:
[system]
external_net=eth0
5.5 Additional Notes on Configuration File Entries
num_comp_nodes. Compilers are typically allocated for a short period of time.
The compiler runs once to produce a piece of s-code (that is, a query plan) for the
query. If you run out of compilers, then you will probably only experience short
delays waiting for one.
num_int_nodes. Interpreters are allocated for the time while a query is actually
running. If a query takes 5 minutes, the interpreter is allocated for 5 minutes. If
there are n interpreters, only n queries can run concurrently. Also, a query can
occasionally use more than one interpreter. You almost certainly want more
interpreters than compilers.
A number of compilers and interpreters can be reserved for the SYS user. This
prevents a rogue application using all compilers/interpreters, requiring a system
restart to recover. By default, 2 compilers and 2 interpreters are reserved for SYS
usage. The number of compilers can be set dynamically with the parameter
reserved_sms, and the number of interpreters with reserved_tms.
For more information on multi-user performance, see the Kognitio Guide.
Chapter 5- Configuration Files
Kognitio Configuration and Maintenance Manual 41
Data Classification - PUBLIC
5.6 Configuration Details wxserver info config
You can obtain details of the current configuration from the global configuration file
by using the wxadmin config menu options or the wxserver info config
command.
Note: There is currently no wxserver command to run on a node to display the local_config
details.
5.7 Editing Configuration Details wxviconf
The global config file is replicated automatically across all Kognitio Nodes by the
SMD. The following rules ensure this process is both safe and reliable:
The config file can only be edited by root.
In order to edit the config file use the wxadmin config menu options or
the wxviconf command. These use an unprivileged shell script which uses
privileged commands to automate the process as follows:
a) Copies the config file.
b) Runs vi on the copy.
c) Checks the edited copy against the original.
d) Writes the new config file out.
e) Restarts the SMD to cause the new config file to be read and replicated.
If the configuration file has been edited to alter the details of the Kognitio
configuration, (e.g. increase the number of compilers), then Kognitio will need to be
restarted before the change comes in to effect.
5.8 Setting Parameters with SQL
It is possible to set system, session and user parameters using SQL. System and user
parameters are persistent, whereas sessions parameters only exist while the session is
active. Parameter values are integers. Parameters are typically used to fine-tune
Kognitio performance for specific configurations and work-loads; they are only
normally set when the system is installed or under the direction of Kognitio.
It is possible to have system, user and session parameters with the same name; in
this case session parameters will be used in preference to user parameters which in
turn will be used in preference to system parameters.
Chapter 5- Configuration Files
42 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
It is possible to verify the value of parameters by inspecting the following system
tables and views: IPE_CURRENT_PARAM, IPE_PARAM, IPE_USER_PARAM and
IPE_ALL_PARAM.
The following command is used to set parameters:
SET [USER | CURENT_SESSION] PARAMETER name TO value


Kognitio Configuration and Maintenance Manual 43
Data Classification - PUBLIC
6
Log Files
6.1 Logging
Kognitio contains a general-purpose logging-module that is used by most of the
software to manage logs. The logging-module provides the following features to the
management tools:
Logs for a given system are stored in a subdirectory specific to the system id,
separating logs for different systems.
Consistent file and directory naming conventions across all tools meaning that
log file names are unique and obvious.
Automatic rotations of log files that have been open for a long time or have
become too big.
Hint files are provided to enable the administrator to easily find a required log
directory.
Automatic expiry of log files when they reach a certain age or occupy too much
space.
A centralised configuration mechanism to enable attributes to be defined
globally or per-log file.
A centralised way of checking for available space on the log volume and
implementing various log full policies as attributes for each log file.
The system log directory
The system management tools put all log files and directories either into the system
log directory or subdirectories of it. No logs should ever be written outside the
system log directory. Prefixing the root log directory name in the config file to a
logs-SystemId subdirectory generates the complete system log directory name.
The root log directory name is defined in the [paths] log_dirs configuration file
setting. If this value is not present, the default value of /var/log/wx2 is used
meaning that by default, all log information for a system goes into the
/var/log/wx2/logs-SystemId directory. The owner/group of the log files is
$master:$admingrp.
Chapter 6- Log Files
44 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Note: It is possible for the layout file to specify an alternative location for /var/log/wx2.
'Standard' Log subdirectories
Inside the system log directory, the system management software creates various
files and directories. The log files created by the logging-module are always put in
subdirectories of the main logging directory. These subdirectories are divided up
into two log classes:
smd - these directories contain logs created by the SMD.
startup - these directories contain logs relevant to a particular start.
The name of each log directory is made up from two parts, the StemName and a
DateString. The parts are separated by a dot. The StemName for each directory
depends on the log class. For SMD the StemName is smd and for startup the
StemName is startup. The DateString is the date and time (with time zone) on
which the log directory was created converted into a string suitable for use in a
filename (i.e. no spaces).
Each time a new log subdirectory is created by the logging-module, a hint file is
written out to point to its location. The hint file is placed in the system logging
directory and is called .log-StemName. The file contains the full path name of the
directory that has just been created. If the hint file existed before the log directory
was created, the old contents are overwritten. Thus, the name of the most recent
SMD log directory can be found by doing cat /var/log/wx2/logs-
SystemId/.log-smd.
The wxlogd command is provided with the software to find the system log
directory and then display the contents of the hint file associated with the given
parameter. These provide a convenient way of getting to the most recent version of
any given log directory type. The parameters are:
smd displays the most recent SMD log directory.
startup displays the most recent startup log directory.
Thus, to go to the SMDs log directory, one could do:
cd `wxlogd smd`
To list the most recent server debug log files, one could do:
ls -lrt `wxlogd smd`/serverdbg.*
Chapter 6- Log Files
Kognitio Configuration and Maintenance Manual 45
Data Classification - PUBLIC
'Non standard' Log subdirectories
Some logging subdirectories are not created using the logging-module. These
directories tend to have a less well-defined name format and do not have hint files to
help find them. These directories are:
config-history This directory contains old configuration files that have
since been replaced with newer ones. The files are called config.timestamp
where timestamp was the last modified time on the configuration file just
before it was replaced.
upgrades This directory contains logs for all software upgrades that have ever
been performed.
newsys.date These directories contain detailed output from the new system
scripts. date is in a different format from the other date strings. Files in here
are named script.out. Each file is the wxsubmit output for script.sql.
reconfigures This directory contains the wxsubmit output for all
reconfigure operations that have been performed.
Log file attributes
The log files created by the logging module have several attributes associated with
them that can be set in the [logs] section of the configuration files. The log
attributes control the way the logs are written out and the data that is placed in
them. The attributes that can be set for a log are:
log_level This controls how much information is put into the log. It is
described later. Default value is 50.
add_time This controls whether or not a date/time string will be put at the
beginning of each line in the log. It is given as a Boolean value. Default value is
yes.
max_time and max_size These control log rotation, which is described later.
Default values are 0 and 0x100000
full_mode This controls the behaviour of the log when the log volume is low
on space and is described later. Default value is Discard.
min_days_history, max_days_history and logs_max_mb These control
log expiry, which is described later. Default values are 7, 30 and 50.
To set an attribute value for all logs in the system, set the [logs] AttributeName
configuration value. The attributes can also be set for all logs in a given class by
setting the [logs] Class_Attribute configuration value (e.g. [logs]
smd_log_level=100 to enable debug output in all SMD logs). Finally, each
attribute can be set for a given log file within a class by setting the [logs]
Class_LogName_Attribute value.
Chapter 6- Log Files
46 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
When multiple settings apply to a particular log, the most specific setting for an
attribute is always used in preference to more general settings. This means that, for
example, [logs] startup_output_log_level would be used for the
startup.date/output log file in preference to any [logs]
startup_log_level setting.
Log Rotation
The logging-module can perform automatic rotation on the various logs it creates.
Automatic rotation is useful to prevent a long-running process from creating a single
huge file that fills up the log volume. Automatic rotation can be performed
according to how long the log file has been open or according to how big the log file
has grown.
When a log file with rotation enabled is created, the log files name has a date string
appended to it. When no rotation is enabled, the logs name does not have a date
string at the end of it. The date indicates when the file was created. When the log is
rotated, the file is closed and a new one opened with a new date string. The old log
file is still there, but it can now be safely expired by the SMD without crashing the
process that created it. When rotating logs, the process writes a string to the end of
the old log containing the name of the new log file, and it also writes a string to the
beginning of the new log file containing the name of the old log file.
Log rotation is controlled by the max_time and max_size attributes for the log.
The max_time attribute specifies the maximum number of minutes the log can be
open for. 0 disables time open based rotation.
Similarly, the max_size attribute specifies the maximum size in bytes of the file.
This size is approximate and the file may get a little bigger than this size. A value of
0 for a log disables size based log rotation.
By default, no rotation at all is performed on the startup logs since these are typically
created all in one go and do not grow over time. Size based rotation is performed on
the SMD logs with a max_size value of 1Mb.
Log Expiry
The logging-module can perform automatic expiry on the various logs it creates.
Automatic expiry is useful to prevent old log files filling up the log volume.
Automatic expiry can be performed according to how old the log file is or according
to how full the logging directories are.
Chapter 6- Log Files
Kognitio Configuration and Maintenance Manual 47
Data Classification - PUBLIC
The expiry algorithm has sufficiently intelligence to prevent it expiring a current or
useful log file, so, for example the log file from the last new system will always be
preserved, regardless of when it was created or how full the logging directories
become.
Log expiry is controlled by the min_days_history, max_days_history and
logs_max_mb attributes for the log.
The min_days_history attribute specifies the age the file must reach before it is
ever considered for expiry.
The max_days_history attribute specifies the number of days after which a file
should be expired.
The logs_max_mb attribute specifies the maximum amount of logging information
that should be maintained. Once this limit is reached, the oldest log files that are
eligible for expiry will be removed until the amount of logging information is once
again under the logs_max_mb threshold.
Whatever the value of logs_max_mb, all eligible files will be expired once their age
exceeds max_days_history and no file that is under the min_days_history
threshold will ever be expired.
Log full behaviour
When writing log files, the logging module checks to see how much space is
available on the logging volume before writing each line. If the number of Mb of
free space is lower than the [logs] min_free_mb configuration value (default 50),
the logging volume is deemed to be full. If the logging volume is full, log writing
behaviour is controlled by the full_mode attribute for each log. The full_mode
attribute can take the following values:
Ignore Ignore the fact that the log is full and try to write anyway. Ignore any write
errors.
Crash Cause whatever process is writing the log to crash. An error message is
written to stdout and a core dump is produced.
Block Block the thread writing to the log until the log volume is no longer full, and
then continue to write normally.
Discard Write a message to the log file saying that log entries are being discarded and
throw away all subsequent writes to the log. When the volume is no longer
full, write another message saying logging is resumed and continue to write
normally.
Chapter 6- Log Files
48 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Logging Levels
Information written to logs through the logging module is written with an
accompanying log level. Each log also has a log_level attribute associated with it
which controls how much information is actually written to the log. Log information
is written if the logging level is <= the log_level attribute, otherwise the
information is discarded. The log levels typically used for writes are:
1 Essential log contents. Without entries at this level the log would be pointless.
5 Error information.
10 Warning information.
50 Normal output. This should not be too big.
100 Debug output. This is used for diagnosing various problems.
>100 Very verbose debug output. Turning these levels on can generate a LOT of
output!

Setting the log level to 0 for a log will turn it off completely because nothing ever
outputs at level 0. The file will not even get created because log files are created on
demand (i.e. when something is written to them).
Note that for many of the startup logs ALL information is written at level 1 so it is
only possible to turn the log on or off. For the SMD logs, occasionally setting the
level to 100 can be very useful for helping Kognitio diagnose a problem.
Other log files
In addition to the above logs, the system management tools also maintain two other
logs in the root of the system-logging directory. These are the smd-angel log and
the action log.
The smd-angel log is a flat file that is maintained by the SMD angel. Entries get
written to this file whenever the SMD is started. Entries also get written when the
SMD crashes/is restarted/etc.
The action log is maintained jointly by all tools and contains a list of all system
management actions performed on Kognitio Node. Because it is maintained jointly,
the action log does not rotate in the normal way. Instead each tool writes to the end
of a file called actions.Date, so the action log is effectively rotated each day.
The action log contains the time, user id and command line for every management
command run on a given Kognitio Node. Thus, if $admin runs wxprobe -w, then a
line like $admin at time: wxprobe -w gets written. Whenever an SMD
command is run, the SMD writes the command text to the action log.
Chapter 6- Log Files
Kognitio Configuration and Maintenance Manual 49
Data Classification - PUBLIC
Not all commands are written to the action log. In particular, command lines with
the -h option typically do not get written, neither do commands with invalid
arguments or SMD commands with invalid syntax.

Kognitio Configuration and Maintenance Manual 51
Data Classification - PUBLIC
7

Disk Resources
This chapter explains how to monitor and control Kognitio disk resources. It gives details
about disk store slabs, procedures for adding or removing disk resources, software RAID and
also lists the software steps required to recreate data on a disk resource.
7.1 Disk Store Slabs and File Systems
Kognitio software incorporates the concept of the Disk Store Slab the logical
division of a disk or disk partition into individually addressable areas, each of which
may be customised to different requirements.
Benefits
The main benefits of Kognitio Disk Store Slabs are:
Data for individual projects can be assigned to specific slabs, thus isolating issues
such as exhausting disk capacity to that project/slab. Reclaim operations can
then be performed on a per-slab basis.
Data is less interleaved on the disk, resulting in lower I/O overheads during
data retrieval. In particular, logging tables can have a dedicated slab rather than
having their data interleaved with user data across the whole disk.
Details
Disk store slabs can each contain up to 16GB of addressable user data.
Chapter 7 Disk Resources
52 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
The slab structure is uniform across all disks; this simplifies slab management and
ensures an even distribution of data across all disks which maximises performance.
The Capacity of a given slab is n x slab-size where n is the number of disks in the
system.
Slabs can be assembled into slab groups, with each slab in the group having identical
characteristics. Slab groups allow a user to specify that more than 16GB of storage
per disk should be allocated to a particular set of tables.
A set of slab groups can be combined into an area. Each disk store is assigned one
area, and this assignment cannot be changed. Each table can only be assigned to one
slab group. Software RAID operations are performed across areas.
Unless a request specifies to the disk store the slab to be used, for example, delete
the record at address x on slab y, the disk store will allocate data to slabs on a round-
robin basis.
Tables are assigned to a slab group. If more than one slab exists within the group,
data will be written to the first available slab until that is almost full, then to the
second, and so on. This ensures that data loaded contiguously remains as contiguous
as possible on disk maximising the efficiency of compressed indices, disk scans
and reclaims.
Slab sizes are currently specified without taking into account the requirements for
RAID if this is in use. So for example if 10GB is allocated to a slab on a disk store
with a total disk size of 50GB, then only approximately 15GB will be available for
other slabs.
These points are illustrated in the following diagram.
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 53
Data Classification - PUBLIC

The system and log slab sizes have a default size of 0.5GB per disk resource. These
values can be overridden at commission time in the [fs] section of the configuration
file by setting the sys_slab_secs and log_slab_secs values. The default value
is 1000000 and the maximum value allowed is 30000000.
Note: Increasing the size of these slabs is likely to be most useful on test/development
systems which have limited disk resources.
In addition, the maximum number of user tables in any user data slab on an
individual disk resource can now be increased from the by setting the ftable_sz
value in the [fs] section of the configuration file at commission time. The default
value is just under 10000.
It is possible to specify the maximum slab size in GB via the [fs] max_slab_gb
setting. This is useful for allowing finer granularity of slab assignment for
schemas/tables.
However, to simplify administration across the set of machines, administrators often
want to ensure that the development, test, and production systems all have the same
number of slabs, regardless of disk resource size. The parameter, [fs]
desired_slabs allows the administrator to specify a value between 3 and 255,
subject to the limits on minimum and maximum slab size. This parameter is
incompatible with disk compression, and with the max_slab_gb parameter.
Chapter 7 Disk Resources
54 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Further information about assigning data to specific slabs and how Kognitio can
automatically move data between slabs to provide automated on-line reclaims are
discussed in the Kognitio Guide.
New Virtual Tables
The Kognitio software allows the details of slabs to be interrogated via SQL using
the following virtual tables:
IPE_DISK_ACCESS
This table shows disk access operations:
Column Name Data Type Description
MPID INTEGER Disk Node ID
PARTITION_ID INTEGER Partition ID
OPERATION CHARACTER Disk Operation
USING_CI INTEGER True if Compressed Index being used
TABLE_ID INTEGER Table Id
FIRST_PAGE INTEGER First Page of table
LAST_PAGE INTEGER Last Page of table
CURRENT_PAGE INTEGER Current position in table
SESSION INTEGER Session ID
TNO INTEGER Transaction Number
ACTIVE INTEGER True if access is active
IPE_FTABLE
This table will expose the file table details for tables:
MPID Message passing id of the disk store in question.
PARTITION_ID The slab id of the slab in question.
TABLE_ID The table id of the table in question.
DROP_TNO The transaction number which dropped this table - 2147483647 indicates
the table has not been dropped.
FIRST_PTR The disk address of the first record on this slab.
LAST_PTR The disk address of the last record on this slab.
NROWS An approximate count of the number of rows for this table in this slab,
including deleted and rolled-back records. Note that this can be an
overestimate with double-counting of records sometimes occurring, but
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 55
Data Classification - PUBLIC
it is usually fairly accurate.
DEL_ROWS The approximate count of the number of deleted rows on the slab
LOW_TNO The lowest tno which added records to this table.
HIGH_TNO The highest tno which added records to this table.
BLOCK_COUNT The number of 8KB disk pages containing records from this table.
OLR_PTR Obsolete
WORDS The approximate size of the active portion of the table on the slab
DEL_WORDS The approximate size of the inactive portion of the table on the slab
TRUNC_WORDS The approximate size of any truncated sections of the table on the slab
IPE_DISKAREA
This table shows which slabs are in which slab groups and areas
Column Name Data Type Description
DISKAREA INTEGER Disk area identifier
SLAB_GROUP INTEGER Slab group identifier
SLAB_ID INTEGER ID of a slab in the slab group
IPE_SLAB
This table lists all the slabs in the system, including their slab group and details of
their geometry:
Column Name Data Type Description
SLAB_ID INTEGER Slab identifier
START_SECTOR INTEGER Disk sector where slab starts
SECTORS INTEGER Number of sectors in the slab
MAX_FILES INTEGER The maximum number of files that can be written to the slab
IPE_DISK_SLAB
This table shows the contents of each slab instance in the system how full each slab
is.
Column Name Data Type Description
MPID INTEGER Disk node ID
SLAB_ID INTEGER Slab ID
DATA_STORED INTEGER Amount of data stored in this slab
FREE_SPACE INTEGER Amount of free space in this slab
TIDEMARK INTEGER The point the data has reached in the slab
Chapter 7 Disk Resources
56 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
LOWMARK INTEGER The point reached by the internal structures growing
down from the top of the slab
IPE_SLAB_TABLE
This table shows which tables are assigned to which slabs
Column Name Data
Type
Description
SLAB_ID INTEGER The Slab ID
SEQ INTEGER Sequence number for this slab, this is to allow more than one
range of tables to be assigned to a slab
START_TABLE INTEGER Lowest Table ID for this slab
END_TABLE INTEGER Highest Table ID for this slab
7.2 Disk Compression
It is possible to compress data on disk. To enable compression, add the following
setting to the systems configuration file before commissioning:
[boot options]
ds_compression=1
By default, this will set a maximum compression ratio of 3:1. If your data is more
compressible than this, you can override this setting by making a setting as follows
before commissioning:
[boot options]
ds_max_comp_pc=40
The setting above would set a maximum compression ratio of 4:1 (the ratio shown is
the ratio times 10, to allow for finer granularity than just specifying the ratio
directly).
Note: Increasing ds_max_comp_pc means that more disk space is required per slab for
storing compression metadata, and more RAM is required for the disk
subsystem.
When compression is enabled, the disk page size, or cache unit (CU) size, is
increased to improve the compression ratio. By default, the system uses an 8KB CU
size with compression off, and a 16KB CU size with compression on. This can be
overridden with the following setting in the config file before commissioning:
[boot options]
ds_cusize=16384
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 57
Data Classification - PUBLIC
There is a limit of 16GB logical disk space per slab within Kognitio, so the maximum
slab size for the system should be altered in line with the compression ratio; so if
ds_max_comp_pc is set to 40, the disk slabs should be physically limited to 4GB with
the following config file setting:
[fs]
max_slab_gb=4
Disk compression can only be used if the system has a disk compression licence. When
disk compression is used, the Kognitio licensing becomes RAM-based rather than
disk-based.
Note that slabs 1 and 2 cannot be compressed, and other slabs using compression
cannot have the RECLAIM operation run on them; space must instead be recovered
by repacking data.
A new virtual table, IPE_DISK_COMPRESSION, shows the compression ratio
achieved per slab in the system. In the example below, we can see that:
Slab 3 has very compressible data, achieving a compression ratio of 16:1
Slabs 4 and 5 are nearer to 4:1
Slabs 1 and 2 are uncompressed
SELECT *
FROM ipe_disk_compression
WHERE data_stored > 0
ORDER BY 1,2;
MPID|SLAB...|DATA...|FREE...|PHYS...|FREE...|COMP_RATIO
14| 1| 25| 28787| 800| 921216| 100
14| 2| 6| 28806| 192| 921824| 100
14| 3| 512514| 219257|1025028|6780285| 1600
14| 4| 513| 731258| 4597|7800716| 357
14| 5| 4941| 726830| 39497|7765816| 400
With very compressible data, it is possible to achieve a performance gain from
compression due to the reduced IO required to retrieve a given amount of logical
data.
7.3 Fault Tolerance
The Kognitio platforms storage networks may be able to provide sufficient fault
tolerance to guarantee data integrity in the event of a component failure. If the
storage networks do not offer such guarantees, then Kognitio can be configured to
provide the required fault tolerance using software RAID techniques.
Chapter 7 Disk Resources
58 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Software RAID
RAID is short for Redundant Array of Independent (or Inexpensive) Disks, and is a
set of techniques that employ two or more drives in combination for fault tolerance
and performance. Kognitio uses RAID 5, which distributes the parity information
between all the disks in a cluster.
RAID 5 operates over clusters of disk resources. Typical cluster sizes are 2 or 4. Note
that
All clusters in the system must be the same size.
The cluster size must be an exact divisor of the total number of disk resources
available.
There must be at least as many nodes as the cluster size because each cluster can
have at most one disk resource on a node. So you cannot use a cluster size of 4
with only 2 nodes, even if you have 10 disk resources per node. This is because
the configuration code is protecting against a node failure making the system
unusable until that node is recovered.
When adding more nodes to a system, you must add at least as many nodes as
the cluster size if you want to use disk resources on those nodes (so with a
clustersize of 4, you must add at least 4 nodes at a time if you want to use the
disk on them).
Two major concepts relating to redundant disk resource arrays are data striping and
redundancy.
Data Striping
With striping, data is distributed transparently between multiple disk resources, to
make them appear as a single fast, large disk resource. Striping improves
input/output (I/O) performance, by allowing multiple reads and writes to be
performed in parallel.
Note that the Kognitio implementation of RAID never splits an individual row of data across
multiple disk resources.
Disk Redundancy
Redundancy is required to tolerate disk resource failures and allow continuous
operation without data loss. It involves writing parity information to one disk
resource whenever data is written to the other disk resources in the cluster. Parity
information can be considered as the sum of all the data written to the other disk
resources. If one disk resource fails, you can subtract all the data on the good disk
resources from the parity data to obtain the missing information.
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 59
Data Classification - PUBLIC
With RAID 5, the parity information is spread over different disk resources,
depending on the area of the disk resource being accessed. This arrangement means
that all disk resources participate in servicing read operations.
Acceptable Limits
Kognitio will continue to operate with one disk resource per cluster marked as bad.
However, if there is more than one bad disk resource per cluster, the system cannot
continue and deliberately halts to prevent the danger of data corruption.
If you encounter a bad disk resource it is important that the situation is resolved in a
timely manner. Systems should be routinely monitored to check for failed disk
resources.
Enabling Kognitio Software RAID 5
WARNING: Enabling Software RAID 5 will erase all the existing contents of the database!
In order to enable RAID 5 on Kognitio, it is necessary to edit the global configuration
file and then re-initialise the database, (the following assumes a cluster size of 4 is
required):
1. Log on as the wxroot Kognitio administrative user
2. Run wxviconf, which will open a copy of the global configuration file. Any
changes made to this file will automatically be replicated to all the nodes when
wxviconf exits
3. Add the following lines to the configuration file:

[boot options]
raid_cluster_size=4
virtual_diskstores=1

[wxsmd]
tolerate_changes=missing_node, missing_link, missing_disk
4. Save and exit the editor in the normal way, which should result in a message
confirming that the edited nodes have been restarted
5. Run wxadmin and choose the server/newsys option
At the end of this process, Kognitio will be available again with RAID 5 enabled. The
available disk capacity with have been reduced by approximately 25%.
Chapter 7 Disk Resources
60 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Notes: The above example assumes a cluster size of 4 is required; if for instance,
raid_cluster_size was set to 2, then the available disk capacity will be reduced by
approximately 50%.
You can enable the resilience functionality at a later date; this will then take
effect when KOGNITIO is restarted it is only the virtual_diskstores and
tolerate_changes entries that can be added at a later date, not the RAID setting.
System Tables Relating to RAID
The System tables IPE_XOR_CLUSTER and IPE_XOR_ELEMENT hold information
relating to RAID clusters.
IPE_XOR_CLUSTER - XOR cluster definition table
This table contains one row per cluster.
Column Name Data Type Description
XOR_CLUSTER_ID INT ID of XOR cluster.
MPID INT Message passing ID of a disk resource in the cluster.
IPE_XOR_ELEMENT - XOR Element Definition Table
IPE_XOR_ELEMENT contains one row per Disk-Store.
Column Name Data Type Description
XOR_CLUSTER_ID INT ID of XOR cluster:-1 => standby disk resource.
MPID INT Message passing ID of Disk-Store process associated
with this disk resource.
STATUS INT Status of disk resource:
0 = bad.
1 = good.
4 = recreating data.
5 = reconfigure needed.
6 = reconfiguring.
7 = recreating parity.
STANDBY_ID INT For future use.
SECTOR_SIZE INT Sector size of the disk resource in bytes.
CAPACITY INT Number of sectors on disk resource.
CU_SIZE INT Cache unit size used on disk resource in bytes.
DATA_STORED INT Database data stored on this disk resourcein cache
units.
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 61
Data Classification - PUBLIC
FREE_SPACE INT Free space on this disk resource in cache units.
CU_TIDEMARK INT Highest numbered cache unit used by data area of
disk resource.
CU_LOWMARK INT Lowest numbered cache unit used by page
management area of disk resource.
PHYS_SECT_STORED INT The number of physical disk resource sectors
occupied by database data.
FREE_PHYS_SECT INT The number of physical disk resource sectors
available to store database data.
The XOR_CLUSTER_ID is fixed when the system is commissioned and does not
change when STATUS changes.
The meaning of disk resource STATUS is as follows.
bad The disk resource is unusable and the data that was on it has not been
recreated elsewhere.
good The disk resource is usable and has valid data on it.
recreating data The disk resource is usable and all data is currently being recreated onto
it (as requested).
reconfigure
needed
The disk resource is a new addition and has not yet been put into
operation using reconfigure.
reconfiguring The disk resource is in the process of being integrated into system
operation using reconfigure.
recreating parity The disk resource is usable and the parity information is being
reconstructed.
7.4 Disk Resources and the Error Log
For historical reasons all disk resource errors are coerced into a SCSI sense data
format. If a read/write error occurs on a file, (rather than an actual SCSI disk), the
information is formatted as follows:
Byte Data
0 Errno.
3(MSB)6(LSB) Sector number for the operation.
8(MSB)11(LSB) Number of sectors involved in the operation (0 for a seek).

The following SQL checks the Kognitio errorlog for any disk resource errors that
have occurred during the past 7 days.
SELECT errtime, seq, mpid, data
FROM ipe_errorlog
Chapter 7 Disk Resources
62 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
WHERE (CURRENT_TIMESTAMP - errtime)DAY < INTERVAL 7' DAY AND
UPPER(data) LIKE '%SCSI%'
ORDER BY 1, 2
7.5 SQL Commands Relating to Disk Resources
RECREATE DISK/CLUSTER
Use the RECREATE DISK command to recreate individual disk resources. Use the
RECREATE CLUSTER command to recreate all parity information for the cluster.
Usage
RECREATE DISK mpid
RECREATE CLUSTER mpid
Notes
Use this command to recreate the contents of a disk resource, or to recreate the
parity for a cluster containing the specified disk resource.
Starting/Stopping Disks - SPIN
Use the SPIN commands to start or stop a physical disk resource or to open/close a
disk resource file. The software will close the file for a disk resource on spin down,
which, for example, would allow the Unix unmount command to be used, without
getting file system in use errors. The disk resource is marked as bad on spin down.
Usage
SPIN {UP | DOWN} mpid
Notes
Spinning a disk resource down causes it to be marked as bad in IPE_XOR_ELEMENT.
The SPIN UP command is normally only used following a SPIN DOWN command.
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 63
Data Classification - PUBLIC
Rather than being file system commands these commands are closely associated
with physical devices because historically raw disks provided the Kognitios disk
resources.
DISK_REPAIR/DISK_CHECK
Use the DISK_REPAIR and DISK_CHECK procedures to repair and check any data
structure inconsistencies on disk resources.
Usage
INVOKE DISK_REPAIR
INVOKE DISK_CHECK
Notes
The INVOKE DISK_REPAIR command invokes a disk resource repair process that
makes a complete scan of all disk resources, and tries to repair any structural
damage encountered in the Kognitio data structure. The Kognitio error log lists all
actions undertaken by DISK REPAIR. At the end of the DISK REPAIR, the disk
resource structure should be consistent (although some data loss may have occurred
and be reported in the error log).
The INVOKE DISK_CHECK command performs the same structural checks, but
makes no changes to the disk resource.
These commands are not required during normal operation. They should only be
run after consultation with Kognitio.
7.6 Virtual Disk-Stores
It is possible to start a system in which not all disk resources come up. The following
entry is required in the [boot options] section of the config file to activate virtual
Disk-Stores:
virtual_diskstores=yes
You also need the following entry in the [wxsmd] section:
tolerate_changes=missing_node, missing_link, missing_disk
Now, if for each missing disk resource:
Chapter 7 Disk Resources
64 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
It is the only disk resource missing from its cluster
All other disk resources in that cluster are in either state 1 (good) or state 7
(recreating parity)
...then a "virtual" Disk-Store will be used for each missing disk resource, enabling the
system to start up and run by making use of the parity information.
7.7 Standby Disks
When a system is commissioned a number of disks can be reserved as standby disks
by adding the following entry to the [wxsmd] section of the configuration file:
num_standby_disks=n

Where n is the number of disks that will be reserved as standby disks; the remaining
number of disks must be a multiple of the cluster size.
Standby disks are not used by Kognitio in the normal course of events, but are
instead reserved as standbys to replace any disks in the system which become
unavailable (e.g. because the node controlling them fails).
After the standby disk has been activated the disk it has replaced can be recovered
and added back to the system, where it will act as a new standby disk to help deal
with any future failures.
Standby disks will be zeroed when the system is commissioned, just like normal
disks. If they are added to the system after commissioning time, they must be zeroed
with the wxtool -Z command as the system will only use zeroed disks as
standbys.
7.8 Automatic Recreate of Bad Disks on Startup
The auto_recreate parameter controls whether and when bad disks are recreated
on system startup. It defaults to 0 if there are no relevant entries in the config file,
and to 2 if the config file contains the following setting:
[wxsmd]
reliability_features=yes

If the auto_recreate parameter is set to 2, Kognitio will recreate bad disks on
startup after the CREATE IMAGE or CREATE SYSTEM IMAGE SQL command has
completed.
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 65
Data Classification - PUBLIC
If the auto_recreate parameter is set to 1, bad disks will be recreated as soon as
the server restarts; this will slow down the CREATE IMAGE or CREATE SYSTEM
IMAGE, but will ensure that the disks are marked as good as soon as possible.
Setting the auto_recreate parameter value to 0 will prevent automatic recreation
of disks. This may be useful if a user imaging script is run at startup; the script can
execute a RECREATE SYSTEM SQL command as its final statement to initiate the
recreate of any bad disks after all required images have been created.
7.9 Disk Resource Reconfiguration and Deskewing
The majority of Kognitio large tables originate in other environments, and are
imported. During import, rows are distributed randomly but evenly between
Kognitios disk resources, using a round-robin algorithm; data continues to be
distributed evenly between disk resources as new tables are created or existing
tables are extended. If the user wishes to add or remove disk resources from a
running system, then all existing data must be redistributed evenly between the disk
resources of the new configuration; this can be accomplished without the need to
unload the data and reload it. The operation of adding or removing disk resources
and automatically redistributing data as required is called reconfiguration.
For some time, Kognitio has been capable of using the RECONFIGURE command to
add disk resources to a system, and redistribute the data. However, with the shift to
commodity hardware and the provision of on-demand functionality, the ability to
remove disk resources is also important. This capability is performed using the
RECONFIGURE DOWN command.
Both RECONFIGURE and RECONFIGURE DOWN are Kognitio specific SQL
extensions.
RECONFIGURE must be run via the wxadmin command line tool, which includes
additional checks before triggering the operation and restarts the system when the
operation is complete a restart is required to recalibrate the data disk information
for the system. There are two ways to perform the reconfigure, although the first
way below (full add) will be deprecated during the 7.2 release series:
1. Full add: the new disk resources are added, and data from the old system is
spread across all the disks to balance the usage of each disk. Until this balancing
operation is complete, no user access is allowed.
2. Quick add: the new disk resources are added as above but no balancing of
existing data will take place at this time. When the server restarts a background
deskew task then deskews the tables one at a time. Deskew ignores tables with a
small amount of skew, or with only a few records in them. Deskew is discussed
in more detail later in this chapter.
Chapter 7 Disk Resources
66 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
RECONFIGURE DOWN cannot be performed via wxadmin. It is important that all of the
steps in the following "Reconfigure Down" section are performed when disk resources are
being removed from a system:
Note: During the Reconfigure the system will be restarted several times with a
CREATE IMAGE; it is therefore recommended that a CREATE SYSTEM
IMAGE be run manually before using wxadmin to perform the Reconfigure.
When the Reconfigure is complete any required RAM images should then be
manually recreated.
Reconfigure
Consider an existing system with n disks each loaded with approximately b bytes of
database data to which we wish to add an additional m disks. The reconfiguration
operation must:
Retain
m n
nb

bytes on each of the existing disks.

Redistribute
m n
b

bytes to each of the new disks.

Any disks that are added should be at least as big as all existing disks.
If Kognitio software RAID is enabled, RAID cluster information for existing disks
will not be altered; new disks will be added to new RAID clusters; this may lead to a
less optimum allocation of disks to RAID clusters than a system commissioned with
all the disks in place. Only complete RAID clusters can be added, so the number of
new disks should be a multiple of the RAID cluster size.
With the full add option (to be deprecated during the 7.2 release series), all
compressed data maps will be deleted along with their statistics. New statistics will
need to be gathered, and the data maps rebuilt once the reconfiguration is complete.
The full add reconfiguration operation will take significantly longer than a
comparable reclaim on the same amount of data, as data has to be distributed to a
number of new disks, rather than simply being concatenated locally on each data
disk.
Deskewing
It is possible to deskew a table using REDISTRIBUTE TABLE table-name. This
ensures that the table is well-balanced across disk resources.
There is also a background deskewer which looks for skew and removes it.
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 67
Data Classification - PUBLIC
The primary use of deskewing is when new disk resources are added to a system, as
normally Kognitio would not have tables skewed across disk resources.
To take advantage of the new background deskewer when adding disk resources,
use the wxadmin tool to select reconfigure, and then choose the quickadd
option rather than fulladd. This will cause the new disk resources to be initialised
and added to the system, but data will not be redistributed.
Note the initialisation of disks can still take some time, but substantially less than a
fulladd reconfigure operation.
When Kognitio is automatically restarted by the quickadd reconfigure operation,
the background deskewer will start to remove skew from tables according to the
setting of two parameters (see below), whilst allowing normal operation of the
server to continue. Note that the redist_threshold parameter needs to be set to an
appropriate non-default value for the deskew to start.
The background deskewer is controlled by two parameters:
redist_count
Tables with less than this many rows will not be considered for
background deskew. The default value is 15,000.
redist_threshold
Tables with less than this percentage of skew will not be
considered for background deskew. Skew is defined as the
percentage less rows of data on the disk resource with the fewest
rows, compared to the disk resource with the most rows. The
default value is 101, which means that by default the background
deskewer will be inactive. To trigger a deskew after adding disks
set this parameter to a lower value, e.g. 20, then back to 101 when
the deskew has completed.
For example, if table T has 100,000 rows on the disk resource in the system
containing the most rows of T, and 90,000 rows on the disk resource containing the
fewest rows of T, then T will be processed by the background deskewer if
redist_threshold is <= 10.
Deskewing works on the total number of rows in a table, including deleted rows, so
it is possible for an initial deskew to not result in a table being perfectly balanced.
Subsequent deskew operations will resolve this issue.
Consider a scenario with 2 disk resources in a system, labelled A and B. A has 100
million rows for table T, and B has 0 rows for table T, however the first 20 million
rows of T on A are all deleted. If a deskew operation is run on T, this will result in
the first 50 million rows being considered for migration to A, but only 30 million will
actually be migrated as the 20 million deleted rows will be ignored. So after the
initial deskew, A will have 50 million rows and B 30 million rows. However, a
subsequent deskew operation will result in A and B both having 40 million rows.
Chapter 7 Disk Resources
68 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Note also that at the end of deskew, the rows migrated from old disks to new disks
are no longer scanned when doing table scans, but they still exist on the old disks. A
reclaim / repack operation must be used to remove the old rows from the old disks,
and balance out disk usage across the system.
Unlike reconfigure, deskew does not invalidate any compressed data maps.
Reconfigure Down
Consider an existing system with n disks each loaded with approximately b bytes of
database data from which we wish to remove m disks. The reconfiguration operation
must:
Redistribute
) ( m n
mb

bytes to each of the remaining disks.

The system must be running and a CREATE [SYSTEM] IMAGE performed, before
the RECONFIGURE DOWN command is submitted.
The disk resources to be removed from the system will run the reclaim algorithm to
decide which data needs to be kept. That data will then be sent, round-robin, to the
disk resources that will remain after the reconfiguration. At the end of the operation,
the disk resources to be removed will be marked as awaiting reconfigure. The
operation is aborted immediately if there is not enough disk space available for the
redistribution.
Follow all of these steps to remove disk resources from a Kognitio system:
1. Identify the MPIDs of the disk stores controlling the disks to be removed. Use
wxprobe -l, and identify the Diskstore processes on the nodes which are
having their disks removed.
2. Set the login mode with set parameter adm_login_mode to 5 this
ensures that only localhost sessions connecting as SYS are allowed.
3. Ensure there are no other connections to the system and submit the following
SQL command: RECONFIGURE DOWN mpid-list; where mpid-list is a
space-separated list of the MPIDs that were identified in step 1.
4. When the RECONFIGURE DOWN finishes, run the wxserver halt command.
5. Stop the SMD on the nodes being removed by running wxsvc stop on those
nodes.
6. Run wxserver start to bring the reconfigured system back up.
7. The nodes no longer being used can now be removed or have their system_id
changed and their SMDs restarted.
Chapter 7 Disk Resources
Kognitio Configuration and Maintenance Manual 69
Data Classification - PUBLIC
8. Reset the login mode with set parameter adm_login_mode to 0 to
remove the access restrictions set in step 2.
If Kognitio software RAID is enabled, all RAID clusters must be either left intact, or
removed entirely. The Kognitio software will check that this is the case.
All compressed data maps will be deleted along with their statistics. New statistics
will need to be gathered, and the data maps rebuilt once the reconfiguration is
complete.
The reconfiguration operation will take a time comparable to running a reclaim on
the same amount of data.
If a system is reconfigured down, care needs to be taken to ensure that the list of
Kognitio node addresses used by ODBC to handle the initial Kognitio connection
request is still correct.


Kognitio Configuration and Maintenance Manual 71
Data Classification - PUBLIC
8

MOP Target Strings
This chapter discusses the method of targeting system management commands to particular
nodes.
8.1 Overview
The system management software uses M-operations for almost all communication.
An M-operation or MOP is a general purpose, multi-target, reliable, streamed
operation over the raw Ethernet protocol, which can send multiple, command
packets to multiple nodes and receive multiple responses back. A MOP can be
thought of as a one-to-many TCP connection originated at a node and terminating at
a group of nodes.
8.2 MOP target strings
Many of the system management tools use the MOP mechanism to perform all of
their tasks. These tools allow the user to define the target for the MOPs they initiate
using a target string which is given using the -a Target command line argument.
Some SMD commands also accept a MOP target string.
For most operations, the default MOP target string is ALL, which selects all nodes.
The MOP target string is used to select a subset of nodes that you are interested in.
There are two parts to every MOP target string, one to specify the begin filter and
one to specify the extended filter. Either of these parts can be left out if you only
want to use one type of filtering. The first part of the MOP target string contains the
begin filter as text. This can take one of the following forms:
Chapter 8 - MOP Target Strings
72 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
A mac address - This sets the target mac address for the MOP and sets the point-
to-point flag.
Positional information for the node in vendor or user specified form.
Node capabilities.
After the begin filter (or at the beginning of the string if there is no begin filter) there
is an extended filter string. This string is enclosed in {}s. The text inside the {}s is
a comma separated list of strings which control filtering. All of these strings are OR-
ed together to make the final filter. It is possible to specify the following:
all - select all nodes
[!]can <capability> select nodes by what it can or cannot do.
mpid <number>[,number,...] - select mpids to respond
Select a group of nodes based on their physical position on the system using
either the vendor or users positional notation.
An ip address - filter by ip address
A mac address - filter by mac address
except - filter the set of things before the except but remove the nodes after the
except.
Note that the {} notation means something special in the csh shell used by default
for $master and $admin. Also, the commands that use -a Target require
Target to be a single argument. Therefore, it is a good idea to put single quotes
around all MOP target strings when running commands, for example:
wxtool -a '{!slot 18 can DES can DS}' R
Note: The above command illustrates how the R argument can be used with wxtool to
resolve MOP target strings, that is, the list of target nodes will be produced, but
no actions will be performed on them. In this case we have asked for all nodes
that have DES and DS capabilities, with the exception of any nodes in slot 18.
This is different to:
wxtool -a '{!slot 18 can DES, can DS}' R
Which is requesting all nodes with DS capabilities as well as all nodes other than those in slot
18 with the DES capability, i.e. the node in slot 18 will be targeted if it has the
DS capability.
Both of the above examples are assuming that there is only one slot 18, i.e. this is a small
system with a single rack containing a single chassis. If the commands were run
on a larger system it would be necessary to identify which slot 18 you werent
interested in, (assuming there is only one).


Kognitio Configuration and Maintenance Manual 73
Data Classification - PUBLIC
9

Additional SMD Information
In certain circumstances, usually under instruction from the Kognitio Helpdesk, you may
need to issue alternative commands to control the SMD or Kognitio. These are briefly
described in this chapter. Also discussed is how particular SMDs can be targeted and how
the syntax of SMD commands can be determined.
9.1 Start Control
This group of commands can either be submitted via the wxadmin server
smdcli interface or directly through the wxserver tool.
Primary Start
To run just the primary start phase, enter the following command:
start primary
Start without loading any images in to RAM
To halt after the secondary start phase, without loading any images into RAM, enter
the following command:
start noimage
Chapter 9 - Additional SMD Information
74 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
System Image
To run a CREATE SYSTEM IMAGE (rather than the normal CREATE IMAGE) after
starting, enter the following command:
start sysimage
9.2 Aborting the Starting Process
The starting process can be aborted as the SMD makes a state change by entering the
following command via the wxadmin server smdcli interface or directly
through the wxserver application:
abort start
9.3 SMD Control
The following commands stop, restart or provide information on a node's SMD:
wxadmin server stop
wxadmin server reinit
wxadmin server services
9.4 SMD Prefix for wxserver commands
Many of the commands can be prefixed with details of the SMD that you wish to
perform the command. Valid entries are:
node-name
master
local
all
Chapter 9 Additional SMD Information
Kognitio Configuration and Maintenance Manual 75
Data Classification - PUBLIC
9.5 The syntax command
The SMD syntax command is a useful way of "remembering" the format of SMD
commands. Starting the command with syntax (or syn) will verify if what you
have typed so far is valid and display a list of tokens that are valid at the next
position. Once the syntax of a complete command has been confirmed it can be
submitted to the SMD.
9.6 Checking Daemon Status
The following command can be used to check the status of the SMD:
wxserver info smds
9.7 SMD Fault Tolerance
The SMD incorporates several features to improve fault tolerance; these are briefly
described here along with any associated configuration file settings.
The SMD Angel Process
If an SMD fails, an associated angel process will dump it off and restart it.
This behaviour is controlled by config file settings. The default settings now enable
dumping of crashed smds and automatic restart of them as follows:
on_crash_dump_smd=1
restart_crash=1
The SMD uses multiple communication links
The SMD can use multiple communication links, making it more tolerant of many
more networking problems.
Automatic Kognitio Restart
The SMD can automatically restart Kognitio if a problem is identified
By setting the following entry in the config file, information will automatically be
collected for a Kognitio crash:
Chapter 9 - Additional SMD Information
76 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
on_crash_dump_wxdb=1
To ensure the Kognitio is automatically restarted in this situation, the following
configuration file entry must be added:
recover_des_crash=1
It is also possible for the SMD to automatically restart Kognitio when is not running,
for example after all the nodes have been rebooted. To do this, add the following
entry to the configuration file:
auto_start_wxdb=1
Preventing nodes (especially virtual machines) being master
It is possible to prevent certain nodes in the system from becoming the master node.
One good reason for doing this is to prevent any virtual machines used as APs from
becoming master, as some virtual machine hosts can put VMs to sleep for a minute
or more, which can cause problems with Kognitios auto-recovery mechanism.
By adding the following lines to the configuration file you can exclude all VMs from
being the master smd (replacing the node names below with the appropriate node
names for your system):
[capabilities]
not_master_nodes=hp-rack1-enc5-5, hp-rack1-enc5-8
Work Without Broadcasts (e.g. cloud environments)
Some cloud environments do not allow broadcast messages. This requires some
changes to allow nodes in a system to find each other.
Providing information on all the Kognitio nodes in a system will allow things to
work in these environments. A line like the following should be placed in the global
Kognitio configuration file for each network interface to be used for Kognitio
management (i.e. for SMD communication):
[net eth0]
peers=10.12.14.74, 10.12.15.77, 10.12.12.201, 10.12.17.193

Kognitio Configuration and Maintenance Manual 77
Data Classification - PUBLIC
10

Checking Hardware Configuration
This chapter shows what hardware maps look like and how they can be used to map
processors out of a configuration. It also shows how they are used by the SMD to report
missing hardware during the starting process.
10.1 Hardware Maps
Overview
While the hardware vendors audit tools have the primary responsibility for
ensuring the reliability and stability of the Kognitio hardware platform, the Kognitio
management software also checks for hardware consistency. Kognitio contains a
hardware-mapping module that is built into the SMD and many of the other
Kognitio system tools. It constructs an internal representation of the hardware
Kognitio is running on, called a hardware map and performs various operations on
it.
A hardware map can be constructed from one of two sources, a hardware map file
or a running Kognitio system. To construct a hardware map from a running
Kognitio system, a MOP is run against the system containing various commands for
detecting hardware. The MOP target and commands used may vary according to
what the controlling process wants to do, so a hardware map may not always
contain a complete description of the system.
The following are some of the types of information that can be contained within a
hardware map:
Chapter 10 - Checking Hardware Configuration
78 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
A list of CPUs in the system. This is the most basic information held. The
hardware map stores various details about each node including the type, speed,
id, position, RAM size and node capabilities.
A list of disk resources used by the system. For each disk resource, we store a
UID, size information and startup information descriptor (system ID, startup
info state).
A list of links in the system. For each link, we store the IP address, MAC
address, and the state of the link.
Process information for each node. This describes the processes running on each
node. It may or may not contain information on each thread the process has. It
contains things like pid, size, state (running, halted, etc.), name, CPU time used,
etc.
Checking the hardware map
Many of the tools that collect hardware maps need to check the data before making
use of it. To do this, the hardware-mapping module provides a function to check the
returned data. When this code is run, the calling code will normally output
something like checking hardware map.
The hardware map check operation actually does two things: it checks to make
sure all information in the hardware map is consistent and valid and it calculates
various bits of summary information which are also stored in the hardware map.
Some of the checks performed by this code will generate errors to the calling
operation. The results will normally be displayed by whatever program is
performing the check. If no results are displayed, everything is OK. The errors
displayed have 3 different severities:
A FATAL ERROR means that checking had to be aborted. This will always
stop whatever operation was about to be done.
An ERROR means that a problem has been found. This will often stop
whatever operation was being performed but may be tolerated.
A WARNING means that a problem has been found which can be worked
around, but the administrator ought to be aware of it.
Once the checks have been performed, summary information is generated and may
be used for displaying brief hardware descriptions.
Because of the nature of the consistency checking, it is not a good idea to check a
hardware map that was generated using certain MOP target strings. For this reason,
many of the tools will skip checking of the hardware map if it was built using a
MOP target string which did not target all nodes. Normally, the code will print a
message saying the check has been skipped.
Chapter 10 - Checking Hardware Configuration
Kognitio Configuration and Maintenance Manual 79
Data Classification - PUBLIC
10.2 Starting when Hardware Missing
Kognitio can be set up to repeatedly retry starting for a number of minutes (20 by
default) to allow everything in the hardware map file to be detected. This allows for
events such as a node running fsck after a power cut. If hardware is still missing at
the end of the retry period then the start will either fail or continue depending upon
whether the failure can be tolerated or not.
10.3 Starting with New Hardware
When new hardware is being installed, it should also be commissioned, (e.g. run the
provisioning tools to get the new nodes started and running SMDs). When Kognitio
is restarted the new hardware will be detected and used. If any disk resources were
added to the system then it will be necessary to run a reconfigure to incorporate
those resources, although it is best practice to run the system for some time first to
ensure the new hardware is reliable - it is more intrusive to remove the new
hardware once the disk resources controlled by it have been incorporated into the
system.
10.4 System Tables for Monitoring Hardware
The virtual system tables IPE_CPUINFO and IPE_NODEINFO contain useful
information about the processors and nodes they sit on. The former shows
information such as processor type, speed, actual clock speed. The latter shows
information such as node and closure name, distribution of Linux, kernel version,
etc.

Kognitio Configuration and Maintenance Manual 81
Data Classification - PUBLIC
11
System Monitoring and Alerts
This chapter discusses how the SMD monitors the state of the system and reports on
problems.
11.1 Introduction
Each SMD contains a system-monitor process. When active, the system-monitor
process monitors the state of the system and reports on problems. The monitor on
each SMD can be controlled manually with SMD commands or automatically. The
monitor uses MOP operations to look at the state of all nodes in the system and
report on errors that come back.
11.2 Interacting with the monitor
Manual monitor control is performed using the monitor SMD command. This has
the following syntax:
monitor {start | stop}
When submitted through wxserver the argument causes the monitor to either start
or stop monitoring. This command will control the monitor on the master SMD.
The state of the monitor can be discovered with the info monitor command. As
with the monitor command, this will report on the masters monitor. The command
will bring back one line describing the current state of the monitor. This will say
whether the monitor is starting, started, stopping or stopped and if the monitor is
running it will give a count of the number of errors detected since the monitor was
started.
Chapter 11 - System Monitoring and Alerts
82 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
The monitor maintains a log in the SMDs logging directory called
monitor.TimeStamp. When a problem is detected, information is written out to
this logfile that describes the problem. Note that the timestamp on the lines in this
logfile is the time the data was written out to the log, not the time the event
occurred. Thus, if two processes crash at roughly the same time, the MOP
mechanism may re-order the packets for those processes and the crashes might get
to the SMD in the wrong order. In this case, the times on each line in the monitor log
could make it look like the processes crashed in the other order. This is unlikely to
happen and times more than a few seconds apart can usually be trusted.
11.3 Monitor control
When automatic monitor control is enabled, the SMD automatically starts and stops
the monitor at the correct time. This feature can be turned on or off with the Boolean
configuration setting [wxsmd] automon. This setting defaults to on, so automatic
monitoring is on by default.
When it has a hardware map, the monitor is then able to monitor the system. This is
controlled by two config settings:
[wxsmd] monperiod This defines the period of the monitor. This is given
in seconds and defaults to 60.
[wxsmd] monusage This tells the monitor whether or not to monitor the
amount of CPU time used by each process on each node.
11.4 Alerts
This section lists all the levels of event severity and the individual events that can
occur. It is possible to specify in the configuration file the actions to be taken by the
SMD when certain of these events or events of a certain severity occur. See Example
of Event Notification on page 85 for additional details:
Severity of the event
The following event severities exist. A system administrator might typically be
interested in security or fatal error events:
Severity Description
0 These events provide verbose debugging information.
These levels should not be required during normal Kognitio
operation.
10
20
Chapter 11 - System Monitoring and Alerts
Kognitio Configuration and Maintenance Manual 83
Data Classification - PUBLIC
25
30 Important information.
40 Security related events.
50 Warnings.
60 Errors.
70 Fatal errors.
80 Automatic recovery failures.
Event codes
SMD events
SMD_missing SMD is missing after master elected
SMD_master_lost master SMD disconnected from us
SMD_slave_lost slave SMD disconnected from us
SMD_start this SMD just started
SMD_master_connect something connected as a master
SMD_slave_connect something connected as a slave
SMD_became_master something became the master
SMD_not_master something stopped being the master
SMD_peer_rejected we rejected a connection with a peer
SMD_crash we crashed an SMD!
SMD_restart_fail this is an angel event
Monitor events
monitor_start monitor started
monitor_stop monitor stopped
server_crash crash of a server process
Start events
start_begun start has begun
start_fail start failure
server_down server is not serving SQL any more
server_up server is serving SQL
in_stable_state server is in a stable state
in_unstable_state server in an unstable state
server_reset server is resetting
power_up server cleared standby
power_down server set standby
new_system server is up and 'new system' finished
init_retry we failed and are retrying
init_fail initialisation failed - not retrying
Chapter 11 - System Monitoring and Alerts
84 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Format events
format_system begin format of all system disks
format_new begin format of new disks
format_complete format was completed
format_fail format failed
Install events
installed_package a new version was installed
uninstalled_package a package was uninstalled
set_current_version the current version changed
upgrade_begun an upgrade was started
upgrade_complete an upgrade finished
Connection/permission events
user_connected a user connected to an SMD
user_disconnected a user disconnected from an SMD
connection_refused a connection was refused by an SMD
permission_ok user has a required permission
permission_denied user does not have a required permission
command user has run a command
hidden_command user ran a hidden command
Debug dump related events
recover_started recovering from a des crash
recover_fail failed recovering from a des crash
recover_too_many too many attempts to recover crashes
auto_restart automatic restart after dumping
dump_begun we started a debug dump
dump_fail we ended a debug dump
dump_complete we ended a debug dump
dump_aborted someone aborted a debug dump
no_auto_restart not auto-restarting due to a problem
Space monitor events
log_space_low running out of space on the log volume
log_vol_full we ran out of space on the log volume
log_vol_ok log vol is no longer full/filling
dump_space_low running out of space on the dump volume
dump_vol_full we ran out of space on the dump volume
dump_vol_ok dump vol is no longer full/filling
Note that the inclusion of an event in the above list is no guarantee that the event can
actually occur in the current Kognitio release. Some events are associated with
previous and/or specific releases and are listed here primarily for completeness.
Chapter 11 - System Monitoring and Alerts
Kognitio Configuration and Maintenance Manual 85
Data Classification - PUBLIC
Example of Event Notification
You specify events you are interested in and their associated event handlers in the
configuration file. It is possible to specify a numeric event severity or a specific event
by prefixing its name with "on_". This example shows an extract from the
configuration file where we indicate that we are interested in all fatal errors and the
specific power on event.
[wxsmd events]
severity_70=exec /home/mikeb/evh
on_power_up=exec /home/mikeb/puevh
Here are the event handlers that capture some information and email the details.
Note that the email generated by the wxdgtool -i command in the first event handler will
often be several thousand lines in length.
evh:
#!/bin/sh
echo "`date` event handler: $EVENT $SEVERITY" \
>>/tmp/mysystemev
wxdgtool -i -o - | mailx -s 'Mysystem event!' \
[email protected]&
puevh:
#!/bin/sh
echo "`date` event handler: $EVENT $SEVERITY" \
>>/tmp/mysystemev
echo "`date` event handler: $EVENT $SEVERITY" | \
mailx -s 'Mysystem Powered On!' [email protected]&
The variables associated with each event can be obtained by looking at previously logged
events in the monitor log in the SMDs logging directory. These variables may
be useful when writing event handlers for specific events.


Kognitio Configuration and Maintenance Manual 87
Data Classification - PUBLIC
12

Automatic Crash Recovery
This chapter describes how Kognitio can be configured to automatically dump and attempt to
restart if a crash is detected.
12.1 Requirements for Automatic Crash Recovery
It is possible to configure Kognitio to automatically detect crashes, dump off the
required crash information and then restart. To achieve this, do the following:
Add these lines to the [wxsmd] section of the configuration file:
recover_des_crash=yes # dump & restart if crash is detected
recover_max_trans=1 # number of times to retry restart
Ensure that sufficient disk resource is available to store the crash dump. See section
1.10: System Requirements for details.
The SMD won't detect any hung processes, as these don't trigger the SMD crash
monitor. These events need manual intervention to ensure that the correct
information is dumped off.
There is a slight risk associated with automatically restarting Kognitio during a
reclaim; normally Kognitio would prefer to check any crash information before
restarting to ensure no disk resource corruption has occurred. Although it isnt
strictly necessary, this risk can be avoided by editing the config file to switch off
automatic crash recovery before commencing the reclaim, and re-enabling the
feature once the reclaim has completed. Likewise automatic crash recovery should
be switched off for disk resource reconfigures or software upgrades.
Chapter 12 - Automatic Crash Recovery
88 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
It is possible to see that a crash is detected and the automatic dump and restart takes
place by checking the contents of the SMD event logs.
It is important to monitor the SMD event logs for automatic recovery if
virtual_diskstores are enabled. Any failure that results in a virtual DiskStore being
used should be investigated and resolved quickly, as in this mode the system's disk
resource performance and ability to withstand another disk resource failure have
been compromised.
Dump and Restart Information
The following SMD commands allow you to verify that the automatic recovery
process is taking place.
info dumper
info dumplist
You can also run the wxserver info state command to check when Kognitio
has restarted.
12.2 Automatic Recovery
Kognitio supports automatic recovery from hardware or software failures.
Please see the notes at the end of section 9.7 if considering this approach in a system
containing virtual machines acting as APs.
To enable automatic recovery, set the following entry in the configuration file:
[wxsmd]
reliability_features=yes
This ensures the system will restart if a node fails or if the software crashes. In the
latter case, information will be automatically collected before restarting to aid with
subsequent analysis of the fault.
If a node is missing, the restart will attempt to bring the system up insisting all
hardware is present 3 times by default, before trying to bring the system up using
virtual disk stores and software RAID. This allows a node which has been restarted
to recover in time to be included in the restart. To ensure the restart is triggered as
quickly as possible, you can prevent the initial restart attempts insisting on all
hardware being present by adding the following line to the [wxsmd] section of the
configuration file:
Chapter 12 - Automatic Crash Recovery
Kognitio Configuration and Maintenance Manual 89
Data Classification - PUBLIC
num_boots_fullsys=0
By default, a CREATE IMAGE will be run at restart time. To run a custom imaging
script instead, add the following entry to the [wxsmd] section of the configuration
file:
auto_start_wxdb_command=start sysimage
And then add an event-handler to the configuration file as follows:
[wxsmd events]
on_server_up=exec imaging-script-pathname
This also allows any manual restart to be performed with wxserver start
sysimage, as the imaging script will run immediately the system image has been
created.
Note: The imaging script and any other dependent files must be present on all nodes in
the system as any node can execute it.
The following is an example imaging script:
#!/bin/sh
echo "`date`: starting imaging script" >> ~wxadmin/res.log
wxsubmit -s $DSN SYS -p * ~wxadmin/img.sql >> ~wxadmin/res.log
echo "`date`: finished imaging script" >> ~wxadmin/res.log


Kognitio Configuration and Maintenance Manual 91
Data Classification - PUBLIC

13

Trouble Shooting
This chapter explains how to detect Kognitio crashes and extract information from a crashed
system. It also describes certain issues that have arisen in the past and gives details of how
they can be investigated and resolved. Additional information about certain data related
problems, (e.g. skewing), can be found in the Kognitio Guide.
13.1 Detecting Crashes
If for some reason you believe the system to have crashed, you can use one of the
following to see if there really is a problem:
wxadmin server state
wxadmin server check
wxadmin troubleshooting check
The following is the type of output displayed when the system has crashed by
wxadmin troubleshooting check:
Kognitio Hardware Discovery Tool
v6.00.00-pre2-markdev1 on test2
(c)Copyright Kognitio Ltd 2001-2006.

Node hp-rack1-enc2-3, ip 172.99.12.3: npr 3.
Process 5553: Name wxdb, nthreads 1, state T, size 712704.
: ppid 5552, pgid 5553, tracerpid 0,
time 0(0,0)+0(0,0).
: status Crashed.
: mpid -1, type WATCHDOG
Chapter 13 - Trouble Shooting
92 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Process 5558: Name WXDB(1): Ramstore, nthreads 52,
state T, size 814100480.
: ppid 5553, pgid 5558, tracerpid 0,
time 400(132,268)+3(1,2).
: status Crashed(CAUSEERROR sigh.c:122).
: mpid -1, type Ramstore
If a Kognitio failure is detected, then depending upon how the system has been
configured, it may be possible to capture system and crash dump information for
analysis by Kognitio. Once this information has been successfully logged, the system
can be restarted as Kognitio can investigate the problem off-line.
13.2 Investigation Options
The following sections indicate the general options available when investigating
Kognitio problems and suspected failures using the wxadmin
troubleshooting menu
1
.
The precise details for a particular system will be dependent upon the way the
Kognitio software was installed and the configuration of the underlying platform. If
you are unsure of how to proceed at any stage then contact Kognitio for advice.
This type of investigation should only be undertaken once it has been established that there are
no on-going problems with, or connecting to, the platform running Kognitio, i.e. the problem is
with Kognitio itself.
View history of recent SQL commands
This option displays the most recent SQL executed by the system. This is particularly
useful in multi-user environments when a heavy workload or malformed query (e.g.
an unintentional theta join) may be causing the system to be less responsive than
normal.
Display system status information
This option produces very detailed information about the system status.

1
The investigations shown here only use the wxadmin utility. Be aware that
additional investigation and debugging options are available using the underlying
tools.
Chapter 13 - Trouble Shooting
Kognitio Configuration and Maintenance Manual 93
Data Classification - PUBLIC
Collect all debugging info for troubleshooting
This option collects a full set of debugging information that will allow Kognitio to
fully investigate any problem. Debug information can sometimes be very large, often
over a gigabyte, so it is important to make sure there is sufficient space available.
The software will cope if there is insufficient space and will never completely fill a
disk with debugging information.
Collect core dump files
This option collects a full set of core dumps that will allow Kognitio to fully
investigate any problem. Core files can sometimes be very large, often over a
gigabyte, so it is important to make sure there is sufficient space available. The
software will cope if there is insufficient space and will never completely fill a disk
with core file information.
Collect full Query log
This option displays the full SQL query log of all SQL executed by the system. This
is particularly useful in multi-user environments when a heavy workload or
malformed query (e.g. an unintentional theta join) may be causing the system to be
less responsive than normal.
Final Actions
Send Kognitio an email containing the results for all of the above steps. Kognitio
may request copies of any files that were generated during the investigation to
analyse the exact nature of the problem.
Important Notes
Only collect debugging information and core files if Kognitio has crashed.
If the failure appears to be a straightforward crash (e.g. just crashed RS nodes, or a compiler or
interpreter node), and Kognitio was running uncomplicated SQL, then it should not cause any
problems if the system is restarted.
If Kognitio crashes during a RECLAIM, RECONFIGURE, UPGRADE, or any other non-typical
operation, DO NOT RESTART - you must first contact Kognitio and ask them to check whether
the operation will resume successfully.
Chapter 13 - Trouble Shooting
94 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
If you restart, and Kognitio fails again very quickly (either in restart, or as soon as users log
back on) please contact Kognitio rather than doing further restarts.
13.3 Other Problems
This section describes how to deal with other situations that may arise with
Kognitio. If your particular issue is not listed in this section then contact Kognitio for
advice.
Running Out of Disk Space
If you run out of disk space do the following:
1. Run wxviconf and put the following entry in the [runtime parameters]
section: rcus=5
2. Restart Kognitio.
3. Connect as SYS, and run the following SQL to run a RECLAIM:
LOCK SYSTEM
RECLAIM TO NOW
4. When the RECLAIM has finished, use wxviconf again to set rcus back to the
default value. A good way to do this is to change the line from (1) to read:
rcus=10
5. Restart Kognitio to make the new rcus value take effect.
Check for Busy Processes
From a suitable location run wxprobe -a '{can DES}' -L 1000 > busy.txt,
then grep "%" busy.txt to see if any nodes are busy - if you see any high %age
values coming back, then Kognitio is busy and that is probably the reason it is not
responding. This may be perfectly valid (i.e. very heavy workload), or it may
indicate a performance issue. If you believe there really is a problem then use the
wxdgdump tool to dump off the busiest WCSDB processes.
Chapter 13 - Trouble Shooting
Kognitio Configuration and Maintenance Manual 95
Data Classification - PUBLIC
Dump File Deletion
The SMD will expire old core files after 7 days by default. At the moment it will
never expire dump files created manually. Because core and dump info can be quite
big, old files may prevent the collection of information on any new problems. It is
therefore important to periodically tidy up old dump files by hand (i.e. delete the
files after Kognitio have diagnosed a problem) to prevent a later failure when trying
to collect all the information needed due to insufficient space.

Kognitio Configuration and Maintenance Manual 97
Data Classification - PUBLIC
A
ODBC Attributes and
SSH Access to Kognitio
This appendix describes the Kognitio ODBC drivers produced by Kognitio; in particular it
details the attributes and their associated values that are specific to Kognitio. The appendix
also covers how Secure Shell (SSH) can be used to establish a secure channel between the
client and Kognitio.
Introduction
Open Database Connectivity (ODBC) is a standard software API specification for
using database management systems (DBMS). ODBC is independent of
programming language, database system and operating system.
The ODBC API is a library of ODBC functions that let ODBC-enabled applications
connect to any database for which an ODBC driver is available, execute SQL
statements and retrieve results.
The goal of ODBC is to make it possible for an application to access data from any
database, regardless of which DBMS is handling the data. ODBC achieves this by
using a driver to translate the applications data queries into native DBMS
commands.
Kognitio produce two ODBC drivers:
1. The DMC ODBC driver this includes driver manager functionality and can be
used by Kognitio tools without needing a driver manager. (DMC stands for
Driver Manager Calls, which are included within the driver).
2. The standard ODBC driver that requires a driver manager to operate.
Appendix A - ODBC Attributes
98 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
An ODBC driver manger is the interface between an ODBC application and the
driver. The driver manager principally provides the ODBC API so ODBC
applications may link with a single shared object and be able to talk to a range of
ODBC drivers. The driver manager also provides additional functionality, such as
controlling repositories of installed ODBC drivers and defined ODBC data sources
and mapping between different versions of ODBC.
There are two open source ODBC driver managers for UNIX, unixODBC and
iODBC. See www.unixodbc.org and www.iodbc.org respecitvely for complete
details including how to install and configure a new ODBC driver.
To illustrate driver manager functionality, we present two typical screenshots of the
unixODBC driver manager; this is a GUI application, similar to Micosoft's ODBC
Administrator. It allows the user to easily configure the User data sources. System
administratiors can also add, remove, and configure System data sources.

Appendix A - ODBC Attributes
Kognitio Configuration and Maintenance Manual 99
Data Classification - PUBLIC

ODBC data sources (DSN) are defined in one of two different files depending on
whether they are a USER DSN or a SYSTEM DSN. SYSTEM data sources are those
accessible by anyone on the machine that defines the data source. USER data sources
are defined in a users home directory and are only readable by that user. The files
contain a section for each defined DSN that lists the attributes that the driver should
use to access the DSN. The files can also contain a general ODBC section that is used
to define a value for all data sources. The DSN values will override the ODBC value,
which would override the default.
Kognitio Specific ODBC Attributes
The following list describes the Kognitio specific ODBC attributes that can be
defined in an odbc.ini file.
Attribute Name Default Description
ForceConnect No Whether a connection
should be forced
through a specified
address/port, or allow
Kognitio to bounce the
connection attempt to
another address/port.
PrivateKey Name of file containing
SSL key
Appendix A - ODBC Attributes
100 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
ServerAddress[n] Address of host to
connect to
ServerPort[n] 6550 Port of host to connect
to
SslAllowFallback 1 To allow fallback to a
non-SSL connection if
an SSL connection
cannot be used
SslEnabled 1 Whether to use SSL by
default
Timeout 3 Timeout period on
attempted connection,
in seconds
WX2AllowUpdateable No Whether to allow FOR
READ ONLY to be
appended to
appropriate SQL
statements
WX2AutoCommit Yes Whether to default to
autocommit or
transaction mode
WX2Debug 0 Generate extra debug
from driver. Can only
be specified at the DSN
level.
WX2DebugLevel 0 Level of extra debug
from driver. Can only
be specified at the DSN
level.
WX2Directory . Directory to look in for
error message
translations. Can only
be specified at the
ODBC or Language
level.
WX2KeepAlive Yes Whether to use the
keepalive option on the
connection
Appendix A - ODBC Attributes
Kognitio Configuration and Maintenance Manual 101
Data Classification - PUBLIC
WX2Locale 4 Information to
determine the name of
the message file to use
for the translating
errors.
WX2MaximumPrefetchRows no limit The maximum size of
the buffer into which
the ODBC driver
fetches data, in rows.
WX2MaximumRowBufferSize 20MB The maximum size of
the buffer, in bytes.
WX2ODBCDbg 0 Determines if driver
generates a trace file
WX2ODBCDbgFilename Linux:
/tmp/wx2odbc.log
Windows:
c:\wx2odbc.log
File used for driver
tracing
WX2PrefetchRows 1000 The initial size of the
buffer, in rows.
WX2RowBufferSize 80000 The initial size of the
buffer, in bytes.
WX2ServerDebug 0 Generate extra debug
from Kognitio. Can
only be specified at the
DSN level.
WX2ServerDebugLevel 0 Level of extra debug
from Kognitio. Can
only be specified at the
DSN level.
WX2SocketLogFile
WX2TrimTrailingSpaces 1 Prevent the ODBC
driver trimming
trailing spaces when
retrieving results. To
prevent the trimming,
set to 0.
Appendix A - ODBC Attributes
102 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
Notes The ServerAddress[n] and ServerPort[n] are used to specify a number of entries
that should be used for connection attempts before giving up. The values of n
must be contiguous.
Boolean values can be specified using all generally accepted forms of true/false,
e.g. 1/Y/T/Yes/True/y/t/yes/true.
SSH Access to Kognitio
Secure Shell or SSH is a set of standards and an associated network protocol that
allows establishing a secure channel between a local and a remote computer. It uses
public-key cryptography to authenticate the remote computer and (optionally) to
allow the remote computer to authenticate the user. SSH provides confidentiality
and integrity of data exchanged between the two computers using encryption and
message authentication codes. SSH is typically used to login to a remote machine
and execute commands.
Kognitio stores a list of public keys and the user IDs that are allowed to authenticate
with them in a table called IPE_AUTHORISED_KEYS. When logging on to Kognitio,
if a blank password is supplied to the ODBC driver and the ODBC driver can
contact an ssh-agent, the Kognitio session will be authenticated using a challenge-
response mechanism. The ODBC driver attempts to connect to a running ssh-agent
using the named socket in the environment variable SSH_AUTH_SOCK. Kognitio
sends a random challenge, which the ssh-agent signs with all the private keys it has,
the resulting signatures are then sent back to Kognitio for verification against the
public keys they claim to be verifiable with, and if one succeeds, authentication is
successful.
If for some reason, an ssh-agent cannot be run, then it is possible to make the ODBC
driver sign the challenge itself, by identifying the location of the key in the odbc.ini
file using an entry of the form: PrivateKey=private-key-pathname. In this
case, authentication using SSH keys is attempted even if the password is non-blank.
If the password is non-blank and the key is encrypted, the password is used as the
passphrase to decrypt the key. If a passphrase is required to decrypt the key and a
password is not given, then an attempt will be made to prompt for the passphrase, if
this is not possible, for example it is a GUI based application, then authentication
will fail This mechanism means the user should never have to type their passphrase
in clear text as both the passphrase and password prompts hide what is typed.
By default key manipulation is performed using the Kognitio SQL extension ALTER
USER ADD DSA KEY key-data.


Kognitio Configuration and Maintenance Manual 103
Data Classification - PUBLIC
Index
A
aborting the starting process, 74
add disk resources to a system, 65
alerts, 82
ALTER USER ADD DSA KEY, 102
ANSI SQL 92, 3
automatic crash recovery, 87
dump and restart information, 88
requirements, 87
Automatic Recreate of Bad Disks on Startup, 64
automatic WX2 restart, 75
B
base licence, 19
C
Calendar based licence, 19
Checking Hardware Configuration, 77
checking the hardware map, 78
ERROR, 78
FATAL ERROR, 78
WARNING, 78
cluster sizes, 58
communication network, 8
Compiler, 4
configuration files, 37
connect/permission events
command, 84
connection_refused, 84
hidden_command, 84
permission_denied, 84
permission_ok, 84
user_connected, 84
user_disconnected, 84
connection/permission events, 84
customer support, 11
D
daemons, 869
status, 75
System Manager Daemon (SMD), 5
debug dump events
auto_restart, 84
dump_aborted, 84
dump_begun, 84
dump_complete, 84
dump_fail, 84
no_auto_restart, 84
recover_fail, 84
recover_started, 84
recover_too_many, 84
debug dump related events, 84
Deskewing, 65, 66
detecting crashes, 91
Disk Compression, 56
Disk Resource Reconfiguration, 65
disk resources, 9, 51
disk partitions, 9
individual files, 9
raw disks, 9
Disk Store Slabs, 51
DISK_CHECK, 63
DISK_REPAIR, 63
disks resources
error log entries, 61
DiskStore, 4
DMC ODBC driver, 97
documentation
Kognitio guide, 2
SQL guide, 2
DS, 4
dump file deletion, 95
E
Enabling WX2 Software RAID 5, 59
end user license agreement, 16
event codes, 83
event handlers, 85
event severity, 82
example
configuration files, 38
Index
104 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
event notification, 85
hardware notation, 11
Examples of Licence Manipulation and Use, 20
extension licences, 19
F
fault tolerance, 57
Fault Tolerance, 57
File Systems, 51
format events, 84
format_complete, 84
format_fail, 84
format_new, 84
format_system, 84
Full permanent licence, 19
H
Hardware licence, 19
hardware maps, 77
hardware notation, 10
hardware upgrades, 26
I
install events, 84
installed_package, 84
set_current_version, 84
uninstalled_package, 84
upgrade_begun, 84
upgrade_complete, 84
installation, licensing and upgrades, 15
Interacting with the monitor, 81
Interpreter, 4
investigating Kognitio problems, 92
iODBC, 98
IPE_ prefix, 5
IPE_DISK_ACCESS, 54
IPE_DISK_SLAB, 55
IPE_DISKAREA, 55
IPE_FTABLE, 54
IPE_SLAB, 55
IPE_SLAB_TABLE, 56
K
Kognitio
configuration files, 37
describing hardware, 38
documentation, 1
overview, 1
Kognitio daemons, 5
Kognitio end user license agreement, 16
Kognitio guide, 2
Kognitio nodes and processes, 4
Kognitio overview, 1
Kognitio services, 5
Kognitio services, 5
Kognitio Tools, 6
L
Licence Actions and Types, 19
Licensing
Add License Keys By Typing, 22
Add License Keys From File, 22
Connection attempt With No Valid License
Keys, 24
License Limit Exceeded, 24
License Usage, 23
Licensing Summary Report, 20
List Currently Active License Keys, 21
Multiple Base Licences, 25
No Base License, 25
Remove License Keys, 23
log files, 43
logging, 43
log expiry, 46
log file attributes, 45
log full behaviour, 47
log rotation, 46
log subdirectories, 44
logging levels, 48
non standard log subdirectories, 45
other log files, 48
system log directory, 43
M
monitor control, 82
monitor events, 83
monitor_start, 83
monitor_stop, 83
server_crash, 83
MOP, 71
Index
Kognitio Configuration and Maintenance Manual 105
Data Classification - PUBLIC
MOP target strings, 71
O
ODBC, 3, 40, 97
ForceConnect, 99
PrivateKey, 99
ServerAddress[n], 100
ServerPort[n], 100
SslAllowFallback, 100
SslEnabled, 100
WX2AllowUpdateable, 100
WX2AutoCommit, 100
WX2Debug, 100
WX2DebugLevel, 100
WX2Directory, 100
WX2KeepAlive, 100
WX2Locale, 101
WX2MaximumPrefetchRows, 101
WX2MaximumRowBufferSize, 101
WX2ODBCDbg, 101
WX2ODBCDbgFilename, 101
WX2PrefetchRows, 101
WX2RowBufferSize, 101
WX2ServerDebug, 101
WX2ServerDebugLevel, 101
WX2SocketLogFile, 101
WX2TrimTrailingSpaces, 101
ODBC attributes, 99
ODBC data sources, 99
ODBC driver manger, 98
on-demand WX2 licences, 19
Open Database Connectivity, 97
Open DataBase Connectivity, 3
operating system, 8
P
package root directory, 25
parity information, 58
Periodic repeating licence, 19
physical system description, 10
plugin functions, 3
plugin mechanism, 3
processing and memory, 2
public-key cryptography, 102
R
RAID, 57
associated system tables, 60
data striping, 58
disk redundancy, 58
IPE_XOR_CLUSTER system table, 60
IPE_XOR_ELEMENT system table, 60
RAMStore, 4
Reclaiming, 9
Reconfigure, 66
Reconfigure Down, 68
RECREATE DISK/CLUSTER, 62
redist_count, 67
redist_threshold, 67
remove disk resources, 65
Resource limit licence, 19
RS, 4
Runtime limit licence, 19
S
Setting Parameters with SQL, 41
Single System Image, 40
single system name, 40
SMD, 4, 5
control, 74
syntax command, 75
SMD Angel, 5
SMD angel process, 75
smd events
smd_became_master, 83
smd_master_connect, 83
smd_master_lost, 83
smd_missing, 83
smd_not_master, 83
smd_peer_rejected, 83
smd_restart_fail, 83
smd_slave_connect, 83
smd_slave_lost, 83
smd_start, 83
SMD events, 83
SMD fault tolerance, 75
smd_crash, 83
Index
106 Kognitio Configuration and Maintenance Manual
Data Classification - PUBLIC
software installation
phase 1, 16
phase 2, 17, 28
software RAID, 58
Software RAID 5, 59
software release packages
naming conventions, 25
version numbers, 25
software upgrades, 26
space monitor events, 84
dump_space_low, 84
dump_vol_full, 84
dump_vol_ok, 84
log_space_low, 84
log_vol_full, 84
log_vol_ok, 84
SPIN, 62
SQL, 3
SQL and ODBC, 3
SQL commands relating to disk resources, 62
SQL guide, 2
SSH Access to WX2, 102
SSI, 40
standard ODBC driver, 97
Standby disks, 64
start events, 83
in_stable_state, 83
in_unstable_state, 83
init_fail, 83
init_retry, 83
new_system, 83
power_down, 83
power_up, 83
server_down, 83
server_reset, 83
server_up, 83
start_begun, 83
start_fail, 83
starting
control, 73
create system image, 74
primary start, 73
without loading images, 73
starting Kognitio, 33
starting when hardware missing, 79
starting with new hardware, 79
starting/stopping disks, 62
stopping Kognitio, 35
checking user sessions, 35
stopping Kognitio and daemons, 35
storage network, 4
fault tolerance, 10
iSCSI, 9
local disks, 9
storage area network, 9
storage networks, 9
Structured Query Language, 3
system administration identities
$admin, 7
$master, 7
$owner, 7
SYSTEM DSN, 99
system image, 74
System Management Daemon, 4
System Manager Daemon, 5
System Monitoring and Alerts, 81
system requirements, 8
system tables, 5
data dictionary tables, 5
dictionary views, 6
import & export tables, 6
log & control tables, 6
lookup tables, 6
virtual tables, 5
System Tables for Monitoring Hardware, 79
system-monitor process, 81
T
the Kognitio RDBMS system tables, 5
tools
wxadmin, 6
wxdgdump, 6
wxdgtool, 6
wxdumpx, 6
Index
Kognitio Configuration and Maintenance Manual 107
Data Classification - PUBLIC
wxgetconfig, 6
wxinstaller, 6
wxlicence, 6
wxloader, 6
wxpkg, 6
wxprobe, 6
wxserver, 6
wxsqlhist, 7
wxsubmit, 6
wxsvc, 6
wxtool, 7
wxtop, 7
wxviconf, 6
trouble shooting
check for busy processes, 94
collect all debugging info for troubleshooting,
93
collect core dump files, 93
collect full query log, 93
display system status information, 92
final actions, 93
investigation options, 92
running out of disk space, 94
view history of recent sql commands, 92
U
unixODBC, 98
upgrade to command, 26
upgrade using command, 26
USER DSN, 99
V
version string, 25
virtual disk-stores, 63
W
Work Without Broadcasts, 76
WX/EULA, 16
WX2 licensing mechanism, 19
WX2 Specific ODBC Attributes, 99
wxadmin
configuration option manipulation, 29
database administration, 30
disk resource manipulation, 28
information reports, 28
license key manipulation, 29
second stage installation, 28
server operations and status checks, 29
wxadmin, 6, 17, 27
wxadmin, 28
wxdgdump, 6
wxdumpx, 6
wxgetconfig, 6
wxinstaller, 6, 16
wxloader, 6
wxserver
info config, 41
SMD prefix, 74
wxserver, 6
wxsubmit, 6
wxsvc, 6
wxtool, 7
wxviconf, 6, 41