Nidbtool Wrapper Reference Guide

Current Document Information
Author/Maintainer : Daravong Luangphakdy daravongl@zer0knowledge.com 2000-12-05 Project: NI 2.01
Audience:  Private Status:  Reviewed Version:  1.0
Reviewer(s) :  Dan Kha Pham danp@zeroknowledge.com January 24th, 2001
Revision History
Revised by: <Name> <email address> <Date>
Revision Notes: <mods made>

Table of content

1- Introduction
2- Installation
3- Configuration
4- Usage


1- Introduction

The purpose of this document to describe how to install, configure and use the Nidbtool Wrapper utility.

The Nidbtool Wrapper utility is a perl script which enables the broadcasting of Nidbtool commands (through SSH connections) to multiple NIDBs residing on different physical hosts. This ensures the synchronization of multiple NIDBs.

For more details about the Nidbtool Wrapper, please refer to the perl documentation of this utlity:
perldoc nidbtoolWrapper.pl
 
 


2- Installation

2.1 Software Requirements

The following is needed by the Nidbtool Wrapper: Since the Nidbtool Wrapper uses SSH connections and because the user may not want to be prompted continously for entering a password, you need to install the SSH2 Agent. The next section covers the installation of the SSH2 agent.

2.2 SSH Agent Installation Procedures

  1. If the SSH2 public/private keys of the Nidbtool Wrapper user do not yet exist, you will have to generate them. It is strongly recommeded to protect your keys with a passphrase:

  2. [root@niqs ~/.ssh2]$ ssh-keygen2
    Generating 1024-bit dsa key pair
       2 Oo.oOoo.oOo.
    Key generated.
    1024-bit dsa, root@niqs.t1.dev.zks.net Thu Jan 25 2001 10:45:39 -0500
    Passphrase :
    Again      :
    Private key saved to /root/.ssh2/id_dsa_1024
    Public key saved to /root/.ssh2/id_dsa_1024.pub
     
     
  3. Copy the generated PUBLIC key (id_dsa_1024.pub) onto every machine hosting an NIDB under ~<username>/.ssh2/. Make sure these hosts are specified within the Nidbtool Wrapper configuration file (more details on this at the configuration section).

  4.  
  5. On each host, append "Key   id_dsa_1024.pub" into ~<username>/.ssh2/authorization. The Nidbtool Wrapper user public key is now installed on all NIDB hosts.

  6.  
  7. Run and configure the ssh-agent:
    a) You first need to run ssh-agent and some environment variables are required. To do so in a CSH, type: ssh-agent -c >  ~<username>/.ssh-agent
    b) Source this file: source  ~<username>/.ssh-agent

  8. c) Add the private key: ssh-add  ~<username>/.ssh2/id_dsa_1024
    d) You will be prompted to enter the passphrase.
     
     

3- Configuration

The Nidbtool Configuration file should be outlined as shown by the following example:

          ;;
          ;; Nidbtool Wrapper configuration:
          ;;

           [general]
            ssh     = /usr/local/bin/ssh

           [nidb0]
             host     = t0.niqs.dev.zks.net
             prog     = /freedom/bin/nidbtool
             conf     = /freedom/etc/freedom-nidb.conf

           [nidb1]
             host     = t1.niqs.dev.zks.net
             prog     = /freedom/bin/nidbtool
             conf     = /freedom/etc/freedom-nidb.conf

           [nidb2]
             host     = t2.niqs.dev.zks.net
             prog     = /freedom/bin/nidbtool
             conf     = /freedom/etc/freedom-nidb.conf
 

host: host name of where the NIDB resides.
prog: Absolute path to the nidbtool application.
conf: Absolute path to the nidbtool configuration file.

Note: If the nidbtool file and/or the configuration file is not found, the Nidbtool Wrapper will exit to ensure the synchronization of the NIDBs.
 



 
 

4- Usage

4.1 Introduction

IMPORTANT:

Since the Nidbtoool Wrapper uses SSH connections which can potentially hang, it is STRONGLY recommended that the Nidbtool Wrapper is not left pending for a long period of time. Ideally, all commands should be executed through a seed file.

Nidbtool should not be directly used.

The Nidbtool Wrapper can run either in an interactive mode (as the nidbtool), or using a seed file.
 

Usage: nidbtoolWrapper.pl [--version] [--help] [--config <file>] [--seedfile <file>] [--debug]

 --version       : version information
 --help          : this help
 --config        : Input configuration file to read.Using this option
                   overrides the default value
                   (/usr/freedom/etc/freedom-nidbtooolWrapper.conf)
 --seedfile      : Input the seed file will seed from that file
 --debug         : Debug mode.

You may access the nidbtool help screen by doing:
[root@niqs bin]# ./nidbtoolWrapper.pl --config nidbtoolw.conf

[===]
[===] Loading configuration files: nidbtoolw.conf
[===]
adding nidb0 host: niqs.t1.dev.zks.net....OK

Opening ssh connection to:
 nidb0 niqs.t1.dev.zks.net
root's password:
NidbTool-Master> help
You enter: help
cache            cache [get] | [set value]
report           report ent-type ent-name
entity           entity ( list | show | add | delete | update | state | desc ) ...
context          Display the current application context
unset            unset name
set              set [ name value ]
source           source filename
echo             echo [ parm1 ... parmN ]
prompt           prompt string
?                ? [ command ]
help             help [ command ]
quit             quit

hostname         <nidbtool command> Broadcast a nidbtool to a particular host.
broadcast        <nidbtool command> Broadcast a nidbtool to all the hosts.

 Broadcast Flag is Off
NidbTool-Master>
 
 

4.2 Broadcast to all hosts vs. targeting a single host

By default, all READ commands (help, cache get, ...) are only executed on the first host specified in the configuration file (the target is the first host only), as opposed to the WRITE commands (cache set, entity update aip ...) which are by default broadcasted to all hosts in the configuration file.

To broadbast a command, you may type "Broadcast" in front of the given command. For example:
NidbTool-Master> broadcast entity show aip host1

To execute a command on a specific host, you may type the host name in front of the given command. If the host is not found, an error will occur.
NidbTool-Master> niqs.t1.dev.zks.net cache get
 Broadcasting to nidb0 [niqs.t1.dev.zks.net]: cache get
Cache data version: [2000112833]
 Broadcast Flag is Off
NidbTool-Master> foo.dev.zks.net cache get
You enter: foo.dev.zks.net cache get
Error:  unrecognized command: foo.dev.zks.net
 Broadcast Flag is Off
 
 

4.3 Examples

Examples of nidbtool commands:

NidbTool-Master> cache get
You enter: cache get
Cache data version: [2000112854]
 Broadcast Flag is Off

NidbTool-Master> report aip host1
You enter: report aip host1
<AipService>
<EntityInfo>
<hostname> danielf.dev.zks.net </hostname>
<ip> 10.16.128.148 </ip>
<company> Zero-Knowledge Systems [100] </company>
<city> --- </city>
<state> CA103934N07845W </state>
<country> --- </country>
</EntityInfo>
<NoTag>
<errorMsg> can't find stat info </errorMsg>
</NoTag>
<NoTag>
<errorMsg> can't find freedom info </errorMsg>
</NoTag>
<NoTag>
<errorMsg> can't find aip info </errorMsg>
</NoTag>
</AipService>
 Broadcast Flag is Off

NidbTool-Master> entity list
You enter: entity list
NIDB matches: 15
 [ 4] host4/18
 [ 8] host3/1
 [12] host1/1
 [ 3] host3/18
 [ 7] NymServer/7
 [11] NISS/20
 [15] host5/1
 [ 2] host2/18
 [ 6] host2/1
 [10] NIQS/19
 [14] TokenServer/9
 [ 1] host1/18
 [ 5] host5/18
 [ 9] host4/1
 [13] KeyQryServer/10
 Broadcast Flag is Off

NidbTool-Master> entity show aip host1
You enter: entity show aip host1
Data retrieved for [host1].
entity aip host1 12 1 51101 51102 30 3600 1
 Broadcast Flag is Off
 
 

toc