Configuring your own IDS instance
1. Directory Structure
2. Environment File
3. Communication File
4. Configuration File
- - Copy Configuration Template File
  - Adjust Parameters in Configuration File
5. Initializing IDS
- - Successful Initialization
  - Failed Initialization
Closure
- Change Profile
- Further Information

Configuring your own IDS instance

The installation page described the installation of the IDS Developer Edition on a SUSE Linux system. The installation wizard did also ask you if a demo instance should be automatically created for you.

Now you will see which steps are necessary to setup your own IDS instance. The name of our instance is penguin. Walking thru the individual configuration steps make you more familiar with IDS.

Please login as user informix to create your own IDS instance.

1. Directory Structure

Probably we will create additional IDS instances on the same machine in the future. So it makes sense to establish a useful directory structure that allows us to quickly switch between instances and lookup relevant data:

export PENGUIN=/home/informix/instances/penguin

```
mkdir -p $PENGUIN/logs
```
```
chmod 775 $PENGUIN/logs
```
```
mkdir $PENGUIN/data
```
```
chmod 770 $PENGUIN/data
```
```
mkdir $PENGUIN/backups
```
```
chmod 770 $PENGUIN/backups
```

2. Environment File

The IDS instance needs a certain set of environment variables. Before creating the instance we will create an environment file that contains all necessary settings:

vi /home/informix/instances/penguin/env.sh

#!/bin/bash
export INFORMIXDIR=/opt/ibm/ids/ids.dev
export INFORMIXSERVER=penguin
export ONCONFIG=onconfig.$INFORMIXSERVER
export INFORMIXSQLHOSTS=$INFORMIXDIR/etc/sqlhosts.$INFORMIXSERVER
export LD_LIBRARY_PATH=$LD_IBRARY_PATH:$INFORMIXDIR/lib:$INFORMIXDIR/lib/esql
export PATH=$PATH:$INFORMIXDIR/bin
export PENGUIN=/home/informix/instances/$INFORMIXSERVER

The individual variables and their meaning:

INFORMIXDIR
- full pathname of the IDS installation directory
- example: /opt/ibm/ids/ids.dev
INFORMIXSERVER
- name of the IDS instance
- example: penguin
ONCONFIG
- name (no leading path) of the IDS instance configuration file
- example: onconfig.penguin
- the instance configuration file is always located under the $INFORMIXDIR/etc/ directory
INFORMIXSQLHOSTS
- full pathname of the IDS instance communication file
- example: $INFORMIXDIR/etc/sqlhosts.penguin
LD_LIBRARY_PATH
- full pathname of the shared libraries for development purposes
- example: $INFORMIXDIR/lib:$INFORMIXDIR/lib/esql
PATH
- Unix search path for executable programs and scripts
- is extended by $INFORMIXDIR/bin in order to find the IDS utilities and programs
PENGUIN
- for our own comfort to avoid typing lengthy path names

After creating the file we should execute it in the current shell in order to set the necessary environment for our IDS instance:

```
. $PENGUIN/env.sh
```

Remember to use the leading dot, so that the environment variables are set in the current shell.

You might check if everything has been set correctly using the env comand:

env | egrep "^INFORMIX|^ONCONFIG|^LD_LIBRARY_PATH|^PATH|^PENGUIN"

3. Communication File

The IDS instance communication file is commonly referred to as sqlhosts file. It contains the necessary information to connect to local and remote IDS instances. Local IDS instances will also start listener threads according to the specified protocol and port number for the respective connection names. You can create the sqlhosts file using a normal text editor:

```
vi $INFORMIXSQLHOSTS
```

#=================================================
#DBSERVER      PROTOCOL      HOSTNAME      SERVICE
#=================================================
penguin        onsoctcp      apollo        40000
penguin_drda   drsoctcp      apollo        40001
penguin_shm    onipcshm      apollo        dummy

Please do not copy/paste the sqlhosts file above. This might lead to problems due to hidden control characters. Just write it off from the above example.

The individual columns and their meaning:

DBSERVER
- logical connection name, corresponds to the DBSERVERNAME/DBSERVERALIASES entry in the IDS instance configuration file
- one of these connection names matches the INFORMIXSERVER environment variable
PROTOCOL
- protocol that the listener threads starts for this connection name
- supported protocol entries can be found in the machine notes. For Linux based operating systems they are:
  - onsoctcp: TCP/IP sockets communication using the SQLI protocol for local and remote clients
  - drsoctcp: TCP/IP sockets communication using the DRDA protocol for local and remote clients
  - onipcshm: Shared Memory communication using the SQLI protocol for local clients
  - onipcstr: Stream pipe communication using the SQLI protocol for local clients
HOSTNAME
- hostname of the machine that powers the IDS instance
SERVICE
- portnumber or logical portname (matching an entry in /etc/services). IDS will start a listener thread on this port. For shared memory connections (onipcshm), a dummy entry is sufficient here.

4. Configuration File

The IDS instance configuration file is commonly referred to as onconfig. It contains the instance configuration parameters and must be located under the $INFORMIXDIR/etc directory. There is a template file named onconfig.std that you might use as a foundation for creating your own configuration file:

Copy Configuration Template File

```
cd $INFORMIXDIR/etc
```
```
cp -p onconfig.std $ONCONFIG
```

Adjust Parameters in Configuration File

```
vi $INFORMIXDIR/etc/$ONCONFIG
```

ROOTPATH

full pathname to your root dbspace chunk, i.e. the initial device/file of your IDS instance

create the rootdbs file:

```
touch $PENGUIN/data/rootdbs.chk1
```
```
chmod 660 $PENGUIN/data/rootdbs.chk1
```

ROOTPATH  /home/informix/instances/penguin/data/rootdbs.chk1

MSGPATH

full pathname of the IDS instance message log file

MSGPATH  /home/informix/instances/penguin/logs/online.log

SERVERNUM
- unique IDS instance number on this machine. You have to make sure that every IDS instance on this machine has a unique SERVERNUM assigned. If you decided to create the demo instance during installation, SERVERNUM 0 is probably already used. So we will take SERVERNUM 1 for this IDS instance:
- ```
SERVERNUM  1
```
DBSERVERNAME
- primary IDS connection name which normally corresponds to the INFORMIXSERVER variable
- only a single entry is allowed
- must match an entry in the sqlhosts communication file
- ```
DBSERVERNAME     penguin
```
DBSERVERALIASES
- secondary IDS connection names
- multiple entries separated by commas are allowed
- they must match the corresponding entries in the sqlhosts communication file
- ```
DBSERVERALIASES  penguin_drda,penguin_shm
```
LTAPEDEV
- specifies the tape device for backing up the IDS transaction logs (logical logs)
- setting LTAPEDEV to /dev/null discards the logical logs. The section Backup Logs shows how to backup your logical logs if desired.
- ```
LTAPEDEV  /dev/null
```
DUMPDIR
- pathname where the IDS instance writes it's dump files when a problem or failure occurs
- ```
DUMPDIR  /home/informix/instances/penguin/logs
```
ALARMPROGRAM
- pathname where the IDS instance writes it's dump files when a problem or failure occurs
- ```
ALARMPROGRAM  /opt/ibm/ids/ids.dev/etc/alarmprogram.sh
```
SYSALARMPROGRAM
- pathname where the IDS instance writes it's dump files when a problem or failure occurs
- ```
SYSALARMPROGRAM  /opt/ibm/ids/ids.dev/etc/evidence.sh 
```

5. Initializing IDS

After all preparations have been done, we can initialize our IDS instance:

make sure that the environment settings are active
- ```
. /home/informix/instances/penguin/env.sh
```
initialize the IDS instance for the first time using the oninit -iv command
- ```
oninit -ivy
```
- i: initialize IDS instance
- v: verbose mode
if you are absolutely sure, you might also add the -y option to the oninit command (i.e. oninit -ivy)
- y: automatically answer any questions with yes

It is important to notice that you should only use the -i option for the first initialization. After the IDS instance has been successfully initialized, you should never use the -i option again. Otherwise you will loose your instance and data because the disk space is initialized again !!

Successful Initialization

You can check for a succesful initialization using the onstat - command:

IBM Informix Dynamic Server Version 11.10.FC1DE   -- On-Line -- Up 00:02:03 -- 40124 Kbytes

This status line tells you that the IDS instance is up and running (On-Line) for about 2 minutes now (00:02:03) and that it has about 40 Megabytes (40124 Kbytes) of shared memory allocated currently.

Failed Initialization

If the initialization failed, our onstat - command will return:

shared memory not initialized for INFORMIXSERVER 'penguin'

In this case you have to inspect the IDS instance message log file for further advice about what probably went wrong:

show last 20 lines from message log file:
- ```
onstat --m
```
view message log file in editor:
- if you already know the filename:
```
vi  /home/informix/instances/logs/online.penguin.log
```
- or dynamically determine the filename from onconfig:
```
vi $(awk '/^MSGPATH/ {print $2}' $INFORMIXDIR/etc/$ONCONFIG)
```

Closure

Congratulations - You've successfully configured your own IDS Developer Edition.

Change Profile

You might add the following line to the .profile of user informix in order to automatically set the necessary environment for the demo instance as soon as you login as user informix:

. /home/informix/instances/penguin/env.sh