$Id: README,v 1.20.2.1 2003/03/28 05:26:01 bko Exp $


/** @name Sip To H323 Call Signaling Gateway README

<pre>
====================================================================
Sip To H.323 Call Signaling Gateway README
====================================================================
siph323csgw server
Release 1.3.0
December 2001


====================================================================
LICENSE AND COPYRIGHT 
====================================================================
For information about licensing, please see the LICENSE file in this
directory, or <a href="http://www.vovida.org/license.html">
http://www.vovida.org/license.html</a> .


====================================================================
INTRODUCTION 
====================================================================
The siph323csgw is a SIP centric H.323 to SIP protocol converter. 
The siph323csgw assumes that directory and location services will
be performed by the SIP network. The siph323csgw acts as a call-routed 
gatekeeper on the h.323 side, and as a SIP user agent on the SIP side.


====================================================================
FEATURES AND FUNCTIONS IN THIS RELEASE 
====================================================================

Release 1.3.0
--------------
This release has number of critical bug fixes for the siph323csgw.

This release also adds gateway trunking capabilities to the siph323csgw.

The following call scenarios have been tested for this release:

  Cisco 7960 (SIP) <----> NetMeeting 3.01
  Cisco 7960 (SIP) <----> Cisco AS5300 12.1(5) (H.323 dial peers)
  Cisco AS5300 (SIP dial peer) <-----> NetMeeting 3.0.1
  NetMeeting 3.01 <----> NetMeeting 3.01
  NetMeeting 3.01 <----> Cisco AS5300 12.1(5) (H.323 dial peers)
  

Release 1.2.0
--------------
The siph323csgw supports basic SIP to H.323 calls.

The following features are supported by the siph323csgw

 - gatekeeper discovery
 - endpoint registration
 - endpoint admission
 - gatekeeper routed calling via the siph323csgw
 
The following endpoints are known to interoperate:

 - NetMeeting to Vocal's SIP UA (Audio only)
 - NetMeeting to Cisco 7960 SIP (Kazoo) (Audio only)
 - NetMeeting to Cisco 5300 SIP (Audio only)
 - NetMeeting to NetMeeting (Audio, Video, T.120 Data)

 - Komodo H.323 to Vocal's SIP UA, Cisco 7960 SIP and Cisco 5300 SIP
 - Komodo H.323 to Komodo H.323
 
 - Cisco 2600 H.323 to Vocal's SIP UA, Cisco 7960 SIP and Cisco 5300 SIP
 - Cisco 2600 H.323 to Cisco 2600 H.323
 
The following features are not yet supported:

 - Faststart
 - H.245 tunneling
 - Re-INVITE (SIP) / dynamically opening and closing channels
 - TCS 0

The following features are not supported:

 - H.450 Supplementary Services 
 

====================================================================
BUG FIXES 
====================================================================
For the most up to date bug information, please see the 
<a href="http://www.vovida.org/bugzilla/index.html">
http://www.vovida.org/bugzilla/index.html</a>.


====================================================================
GETTING STARTED
====================================================================

SOFTWARE DEPENDENCIES
--------------------------------------------------------------------
The siph323csgw uses portions of the OpenH323 H.323 stack beta 1.3.
This is available at <a href="http://www.openh323.org">
http://www.openh323.org</a>. 

Try it, you'll like it.


PLATFORM SUPPORTED
--------------------------------------------------------------------
The siph323csgw currently is supported on Linux systems using
gcc. 

siph323csgw will not build no Solaris using Forte's CC. This is
due to the openh323 not being able to build using Forte. It should
build with gcc, but we have do tested this.

To build the siph323csgw, you will need at least 256 M, it will use
it all during linking.


COMPILE INSTRUCTIONS
--------------------------------------------------------------------
From the directory where vocal was installed type:

[bash]$ make siph323csgw


USING THE SOFTWARE
------------------

The command line options are available via the --help switch,

i.e.

[bash]$ siph323csgw --help

Which reads:

usage: siph323csgw [ options ]
  [ -o ] [ --output ]    directory   Output directory, 
                                       Defaults to "./"
  [ -l ] [ --loglvl ]    level       Log level, 
                                       Defaults to "LOG_ERR"
  [ -g ] [ --gkid ]      id          Use for gatekeeperIdentifier, 
                                       Defaults to hostname
  [ -e ] [ --eptid ]     id          Use for endpointIdentifier, 
                                       Defaults to "endpoint_"
  [ -p ] [ --sipport ]   port        Sip udp port
                                       Defaults to 22400
  [ -a ] [ --sipremote ] ipaddress   IPAddress of sip remote entity
                                       Defaults to 192.168.1.1:5060
  [ -c ] [ --client ]                If set, the remote address represents
                                       a SIP client and H.323 registrations
                                       will not be forwarded.

I usually run the translator as stand alone with the command line:

/usr/local/vocal/bin/siph323csgw \
  -o /usr/local/vocal/log/siph323csgw \
  -l LOG_INFO \
  -p 22400 \
  -a 172.19.175.166:5060

Where 172.19.175.166:5060 is the ip address/port of the sip proxy (marshal) 
it will be talking to. 

I use LOG_INFO, since that provides the h.323 and sip messages being 
sent without too much debug information. You may want to use LOG_ERR 
or LOG_WARN.

You can also do a killall -TERM siph323csgw. This will bring down the 
translator safely, killing all outstanding listening sockets and 
unregistering registered endpoints.

You may also want to run the siph323csgw using a configuration file.
A sample configuration file, "siph323csgw.conf", is provided. The only
way to use pre-provisioned gateways that do not use RAS for registration
is to use the configuration file. To run the translator using a
configuration file use the "-f" or the "--config" switch. For example,
if your vocal installation is in /usr/local/vocal, and you placed the
siph323csgw.conf in /usr/local/vocal/etc the command line to using the
config file is:

[bash] $ /usr/local/vocal/bin/siph323csgw --config=/usr/local/vocal/etc/siph323csgw.conf

or 

[bash] $ /usr/local/vocal/bin/siph323csgw -f/usr/local/vocal/etc/siph323csgw.conf


====================================================================
SOURCE CODE INFORMATION
====================================================================

The main functional modules for the siph323csgw are the H323 Gatekeeper,
the H323 Router, the SIP - H323 Call Translator and the SIP Proxy.
The H323 Gatekeeper and the H323 Router together form a gatekeeper that
performs gatekeeper routed signaling. The SIP - H323 Call Translator
provides the translation function from H.323 to SIP. And the SIP Proxy
serves as the interface to the SIP network.

The H.323 Gatekeeper module was written as an extensible framework.
The intent is that building other gatekeepers on top of this should 
be fairly easy.


Generating SIP Stack Documentation using doc++
----------------------------------------------
You can use doc++ to generate API documentation. 

I have had the best luck with doc++-3.4.5. doc++-3.4.7 is known to
not work properly.

You can download doc++ from http://www.zib.de/Visual/software/doc++/

In the translators/h323 directory type:

[bash]$ make docs

This will create the documentation in the translators/h323/html
directory.


====================================================================
DIRECTORY STRUCTURE 
====================================================================

translators/h323/siph323csgw

    This directory holds the application code for the siph323csgw.
    
translators/h323/doc

    This contains design documentation for the siph323csgw. It's not
    up to date, but it's better than nothing.
    
translators/h323/doc++

    This contains design documentation for the siph323csgw. It's not
    up to date, but it's better than nothing.
    
translators/h323/html

    This contains design documentation for the siph323csgw. It's not
    up to date, but it's better than nothing.
    
translators/h323/gk

    The extensible h.323 gatekeeper module / toolkit. 
    A example standalone gatekeeper exists under translators/h323/gk/unit_test.
    
translators/h323/router

    The h.323 call router. This has the q.931 state machine, the h.245 state 
    machines and the h.245 signaling entities.
    
translators/h323/translator

    The h.323 to sip translation state machines and the h.323 to sip
    capability translator.

translators/h323/proxy

    The basic SIP proxy.
    
translators/util

    Contains specialized message logging classes, useful for message traces.
    
translators/util/mte

    The router / translator state machine framework.
    
translators/h323/events

    The h.323 events passed between the gatekeeper, router, the sip proxy
    and translator.
    
translators/h323/sipevents

    Events that flow between the sip proxy and the translator.
    
translators/h323/tools

    Tools for creating html based message traces.
    
translators/h323/public_html

    Sample web pages for managing an all in one vocal system.
    
    

====================================================================
CONTRIBUTORS 
====================================================================  
This software consists of voluntary contributions made by Vovida
Networks, Inc., Cisco Systems, Inc., and many individuals.

Also visit OpenH323. 
    <a href="http://www.openh323.org">http://www.openh323.org</a>


====================================================================
CONTACT INFORMATION AND WEBSITE
====================================================================
We welcome your feedback, suggestions and contributions. Contact us
via email if you have questions, feedback, code submissions, 
and bug reports.

For general inquiries - info@vovida.org

We have mailing lists for the VOCAL applications and proctocol stacks: 

vocal   - vocal@vovida.org
sip     - sip@vovida.org
mgcp    - mgcp@vovida.org
rtp     - rtp@vovida.org
rtsp    - rtsp@vovida.org
trip    - trip@vovida.org
cops    - cops@vovida.org
radius  - radius@vovida.org

You can subscribe to the mailing lists on 
http://www.vovida.org/mailman/listinfo/index.html

You can submit bug, patches, software contributions, and feature 
requests using Bugzilla.  Access Bugzilla from 
http://www.vovida.org/bugzilla/index.html 

====================================================================
$Id: README,v 1.20.2.1 2003/03/28 05:26:01 bko Exp $
====================================================================

</pre>
*/

//@{
//@Include: ./LICENSE
//@}
======================================================================

Copyright 2000-2003, Cisco Systems, Inc.
THE INFORMATION HEREIN IS PROVIDED ON AN "AS IS" BASIS, WITHOUT ANY
WARRANTIES OR REPRESENTATIONS, EXPRESS, IMPLIED OR STATUTORY, INCLUDING
WITHOUT LIMITATION, WARRANTIES OF NONINFRINGEMENT, MERCHANTABILITY OR
FITNESS FOR A PARTICULAR PURPOSE.

$Id: README,v 1.20.2.1 2003/03/28 05:26:01 bko Exp $
