Cover image for Practical VoIP Using VOCAL

Book description

While many books describe the theory behind Voice over IP, only Practical VoIP Using VOCAL describes how such a phone system was actually built, and how you too can acquire the source code, install it onto a system, connect phones, and make calls.

VOCAL (the Vovida Open Communication Application Library) is an open source software project that provides call control, routing, media, policy, billing information and provisioning on a system that can range from a single box in a lab with a few test phones to a large, multi-host carrier grade network supporting hundreds of thousands of users. VOCAL is freely available from the Cisco Systems-sponsored Vovida.org community web site (www.vovida.org).

A Silicon Valley start-up called Vovida Networks, Inc (think of VOice, VIdeo, DAta) created VOCAL and invested over one hundred man years into its development. Since Cisco acquired Vovida in 2000, individuals representing every significant telecom company and service provider in the world have downloaded the source code. Today, more and more people are successfully building VOCAL into professional solutions, while contributing fixes and new functionality back to Vovida.org.

Because VOCAL is open source, you can look "under the hood" to the base code and protocol stack levels and discover not only how the system works, but also how common problems are being worked out in the development environment. We're hoping that you will be inspired to take this system to another level by implementing a feature or functionality that no one has thought of before.

Written by a team from Vovida Networks, Practical VoIP Using VOCAL includes the following topics

  • Installing and configuring VOCAL 1.4.0 onto a single host and onto a multi-host network with phones and gateways

  • C++, C and Java architecture found within VOCAL

  • Provisioning a VoIP system

  • SIP (Session Initiation Protocol), SDP (Session Description Protocol) and RTP (Real-time Transport Protocol) for call control and media

  • TRIP (Telephony Routing over IP), DNS SRV and ENUM for routing

  • MGCP (Media Gateway Control Protocol) and H.323 for call control and translation into SIP

  • COPS (Common Open Policy Service), OSP (Open Settlement Protocol) and RSVP (Reservation Protocol) for policy and Quality of Service

  • RADIUS (Remote Authentication Dial In User Service) for interfacing with billing servers

  • SNMP (Simple Network Management Protocol)

If you're interested in VoIP, this is the only book available that focuses on the real issues facing programmers and administrators who need to work with these technologies.

:

Table of Contents

  1. Practical VoIP Using VOCAL
    1. Preface
      1. How to Use This Book
      2. How This Book Is Organized
      3. Conventions Used in This Book
      4. How to Contact Us
      5. Acknowledgments
    2. 1. VOCAL: Say, What?
      1. What’s This All About?
        1. Voice over IP
        2. Open Source
        3. VOCAL
          1. The business model
          2. Gaining acceptance
      2. System Architecture
        1. Data Types
        2. VoIP Protocol Stacks
        3. SIP Architecture Components
          1. SIP user agents
          2. SIP servers
          3. SIP messages
        4. VOCAL Servers
          1. Peripheral equipment: endpoints
        5. Writing the Code
      3. Where’s This Going?
      4. What’s in This for You?
    3. 2. Setting Up a Phone System at Home
      1. Hardware Requirements
        1. Host Machine Requirements
        2. Peripheral Requirements
      2. Software Requirements
        1. Versions
        2. Secure Shell
        3. Linux Red Hat
          1. Options
          2. Partitions
        4. Apache Server
        5. Verifying Networking Requirements
          1. Verifying your INET address and multicast
          2. Verifying DNS
          3. Testing DNS
          4. Verifying your hostname
          5. Verifying your hosts file
        6. Java Runtime Environment
      3. Acquiring VOCAL Software
      4. Installing and Deploying VOCAL
        1. Untarring VOCAL
        2. Compiling VOCAL
          1. Optimizing the code
          2. Source code information
          3. Instructions for compiling VOCAL
        3. Deploying VOCAL
      5. Testing Your Installation
        1. Launching Two User Agents
          1. Registering ua1000
          2. Registering ua1001
        2. Making a Call
          1. Dialing
          2. Ringing
          3. Answering
          4. Hanging up
      6. Accessing Provisioning
      7. Installing and Running a UA from Separate Hosts
        1. Local Area Network
        2. Wide Area Network
      8. Configuring Software UAs
        1. Using the UA
          1. Configuring two UAs
          2. Launching two UAs
          3. Working with the UAs
        2. Setting Up Other IP Phones
        3. Provisioning New Users
      9. Starting, Restarting, and Stopping VOCAL
        1. Syntax for Restarting, Starting, and Stopping
          1. Using vocalstart
          2. Using the command line
    4. 3. Setting Up an Internal Trial System
      1. Interfacing with the PSTN
        1. Gateways
        2. Analog Signaling
        3. Channel Associated Signaling
        4. ISDN Primary Rate Interface
      2. Setting Up a Redundant System
        1. What Is Redundancy?
          1. Primary and backup
          2. Load sharing
          3. Heartbeat
        2. An Illustrated Look at a Redundant System
          1. Redirect server
          2. Provisioning server
          3. Call Detail Record (CDR) server
          4. Policy server
          5. Marshal server
          6. Feature server
        3. Distributed Hosting Guidelines
        4. Stateless and Stateful Servers
      3. Configuring a PSTN Gateway
        1. Setting Up a Cisco 5300 Gateway
          1. Dial plans
          2. Defining dial peers
          3. Changing the configuration of dial-peers
          4. Viewing information about dial-peers
        2. Software Configuration
      4. Installing VOCAL onto a Multihost System
        1. VOCAL Configuration File
        2. Deploying VOCAL onto Multihosts
        3. Reprovisioning Servers
          1. Using the GUI
          2. Steps
        4. Provisioning Users
        5. Making Calls to the PSTN
      5. Working with VOCAL
    5. 4. Provisioning Users
      1. Quick Step for Provisioning Users
        1. Prerequisites
        2. Accessing Provisioning
      2. Logging into the Provisioning System
        1. The Login Screen
        2. Password Maintenance
          1. Adding new IDs
          2. Editing existing IDs
        3. Login Procedure
      3. User Configuration Screen
        1. Buttons
        2. Option Boxes
        3. Right-Click Menu
      4. Adding, Viewing, Editing, and Deleting Users
        1. Adding New Users
          1. Name
          2. Group
          3. Marshal
          4. Static Registration
          5. Make Calls Using JTAPI
          6. Forward All Calls
          7. Block Long Distance or 900/976 Outgoing Calls
          8. Screen Incoming Calls
          9. Block Phone Number Display
          10. Forward Busy or Unanswered Calls
          11. Return Calls
          12. Change Password
        2. Viewing Users: Individually
          1. Viewing user
          2. Viewing a single user
          3. Load all users
        3. Viewing Users: Data Field Descriptions
          1. Default data fields
          2. Admin data field
          3. User data field
        4. Viewing Users: All Users
          1. Finding users
        5. Deleting Users
        6. Editing Users: Administrator Controlled
        7. Editing Users: Show Aliases
        8. Editing Users: User Controlled
          1. Editing user feature: Edit User screen
            1. Aliases
            2. Make Calls Using JTAPI
            3. Block Long Distance or 900/976 Outgoing Calls
            4. Screen Incoming Calls
            5. Block Phone Number Display
            6. Forward Busy or Unanswered Calls
    6. 5. Configuring System Parameters and Dial Plans
      1. Login Procedure
      2. Configuring Servers
      3. The System Folder
        1. System Configuration Data
        2. OSP Server
        3. Dial Plans
          1. Regular expressions
          2. Keys and contacts
          3. Sample dial plans
          4. Procedures
          5. Digit dial plan
          6. IP dial plan
    7. 6. Provisioning Servers
      1. The Servers Folder
        1. Adding New Server Groups
        2. Adding New Servers
        3. Editing Servers
          1. Regenerating users
          2. How to edit servers
        4. Deleting Servers
      2. Call Detail Record Servers
      3. Redirect Server
      4. User Agent Marshal Server
      5. Gateway Marshal Servers
      6. Conference Bridge Marshal Server
      7. Internetwork Marshal Server
      8. Feature Servers
      9. Voice Mail Feature Servers
      10. JTAPI Servers
      11. Heartbeat Server
      12. Policy Servers
    8. 7. Session Initiation Protocol and Related Protocols
      1. What Is SIP?
        1. What SIP Does
          1. Registering a user with a system
          2. Inviting users to join an interactive session
          3. Negotiating the terms and conditions of a session
          4. Establishing a media stream between two or more endpoints
          5. Terminating sessions
        2. SIP Architecture Components
          1. SIP User Agents
          2. SIP servers
      2. Sample Message Flows
        1. SIP Request Messages
        2. SIP Response Messages
        3. Call Components
        4. Basic Call Setup
        5. Proxying
        6. Redirection
        7. Registration
        8. Putting It All Together
      3. Message Headers
        1. The INVITE
        2. Breakdown of the Headers
          1. INVITE
          2. Via
          3. From
          4. To
          5. Call-ID
          6. CSeq, or command sequence
          7. Subject
          8. Contact
          9. Content-Type
          10. Content-Length
        3. Other SIP Message Headers
          1. Proxy-Authorization
          2. Expires
          3. Organization
          4. Priority
          5. Proxy-Require
          6. Record-Route
          7. Retry-After
          8. Route
          9. Server
          10. Timestamp
          11. Unsupported
          12. Warning
          13. Proxy-Authenticate
      4. SDP Messages
        1. The INVITE
        2. Breakdown of the Lines
          1. v: version number
          2. o: session origin and owner’s name
          3. s: session name
          4. c: connect information
          5. t: time the session is active
          6. m: Media name and transport address
          7. a: attribute lines
          8. Alternate attributes
      5. Sample SIP Call Message Flow
      6. Forking
        1. A Forking Example
        2. Forking to a Forwarded Phone
      7. Weird Situations
        1. Two Users Hang Up Simultaneously
        2. BYE and CANCEL: Similar but Not Interchangeable
    9. 8. Vovida SIP Stack
      1. Architecture
        1. Classes
          1. Messages
          2. Headers
          3. Body
          4. Network management
          5. Transport
      2. Constructing and Deconstructing Messages
        1. Sending
        2. Receiving
        3. Examples
          1. Example 1
          2. Example 2
          3. Example 3
          4. Example 4
      3. Parsing
          1. Smart pointers
        1. Parsing Examples
          1. Example 1
          2. Example 2
          3. Example 3
      4. Transporting
        1. State Machines
        2. High-Level Design
        3. High-Level Message Flow
        4. Application Interfaces
          1. Illustrations
          2. FIFOs
          3. FIFOs and VoIP
          4. Threadsafe
          5. Event loops, FIFOs, and timing
        5. Working with TCP
          1. Should you use TCP rather than UDP?
          2. How about firewalls?
          3. When should TCP be used?
          4. When should TCP not be used?
        6. Transaction Databases
        7. Data Structures
          1. Key structures
          2. Threads and interaction
          3. Internet Control Message Protocol (ICMP) messages
        8. Advanced Interactions
          1. Network Address Translation traversal
          2. DNS SRV support
      5. Compiling and Running the Stack
        1. Copying and Untarring the Files
        2. Compiling
        3. Running Tests
      6. Bugs/Limitations
        1. The Difficulty with Reducing the Size of the Stack
        2. Performance Issues
          1. Parsing
          2. Application reliability
          3. Multithreaded applications
    10. 9. Base Code
      1. State Machine
      2. Class Structure
        1. Operator Class
        2. State Class
        3. Feature Class
        4. Builder Class
      3. High-Level Flow
        1. SIP Thread
        2. Worker Thread
      4. Key Data Structures
      5. Dependencies
    11. 10. VOCAL User Agent
      1. Call Processing
        1. States
        2. Operators
        3. Walking Through Two Call Flows
          1. Making a call
          2. Receiving a call
          3. New calling parties and called parties
        4. Error States and Operators
        5. Early Media
        6. Using the INFO Message with MGCP
      2. Multicall Processing
        1. States
        2. Operators
        3. Conferencing
          1. Conference bridges
          2. Scheduled versus ad hoc conference calls
          3. Flash hook
          4. Call Waiting
          5. Conferencing with the VOCAL UA
        4. Walking Through Two Call Flows
          1. Transferring a call: Ua_Xfer_Mode = Transfer
          2. Conferencing call flow: Ua_Xfer_Mode = Conference
      3. Looking Through the Code
        1. Classes
          1. Call info class
          2. Event classes
        2. Threads
      4. Other UA Processes
        1. Load Generation
        2. Registration
      5. B2BUA
    12. 11. SIP Proxy: Marshal Server
      1. High-Level Design
        1. Transaction Statefulness
        2. Ingress and Egress Signaling
        3. Types of Marshals
        4. Class Diagram
        5. Threads
        6. Source Code
        7. Basic Proxy State Machine
          1. Operators
          2. Return values
        8. SIP Request Message Handling
          1. REGISTER
          2. INVITE
          3. ACK
          4. BYE
          5. CANCEL
        9. SIP Status Message Handling
          1. 100 Trying
          2. 181 Call Is Being Forwarded /182 Queued
          3. 180 Ringing /183 Session Progress
          4. 2xx (success status messages)
          5. 302 Moved Temporarily
          6. 4xx (Client Error), 5xx (Server Error), 6xx (Global Failure)
      2. Functionality
        1. Billing
        2. Quality of Service
        3. Heartbeat with Redirect Server
        4. Redundancy
      3. Security
        1. Pretty Good Privacy
        2. IPsec
        3. Firewalls and NAT
          1. Non-NAT firewalls
          2. SIP ALGs for NATs and firewalls
          3. Preconfigured NAT firewalls
      4. Authentication
        1. What Is Authentication?
        2. User-Level Authentication
          1. Basic
          2. Access list
          3. Digest
        3. Gateway-Level Authentication
    13. 12. Redirect Server
      1. High-Level Design
        1. Class Diagram
          1. Key classes
          2. The dial plan container
          3. The server container
          4. Server groups
          5. The subscriber container
        2. Startup
        3. Redundancy
          1. Synchronization (RedundancyWorkerThread.cxx)
          2. Mirroring (RSMirror.cxx)
          3. Heartbeat
        4. Registration
          1. Calling and called features
          2. Static registration
        5. Call Processing
      2. Routing
        1. Initial SIP Requests
        2. SIP Responses
        3. Aliases
        4. Least-Cost Routing
        5. TRIP
          1. Option 1: dial plan in RS
          2. Option 2: dial plan in LS
        6. ENUM
        7. TRIP and ENUM
      3. Ongoing Development
        1. Simplified Routing
        2. Dial Plan
        3. Customer Partitioning
        4. Here’s a Project for You
    14. 13. CPL Feature Server
      1. What Are Features?
        1. Feature Development in the PSTN
        2. Feature Development in VoIP
        3. Accessing Features in VoIP
      2. Core Features
        1. Calling Line Information Features
        2. Call Forwarding
        3. Call Blocking
        4. Call Screening
      3. Set Features
        1. Call Transfer
        2. Call Return
        3. Call Waiting (CW)
        4. Cancel Call Waiting (CCW)
      4. New Features
        1. Call Park, Call Pickup
        2. Ring Again
        3. Multiline Appearance
      5. SIP Messages and Feature Servers
        1. SIP Messages to the Feature Servers
        2. Feature Servers to the PSTN
      6. Scriptable Feature Development
        1. What Is CPL?
        2. CPL Definitions
          1. Standard default actions
        3. CPL Supplements
      7. How CPL Script Converts to a C++ State Machine
        1. Types of States and Operators
        2. Changing States with the State Machine
        3. How the State Machine Works
        4. From DOM Tree to FS State Machine
        5. Attaching States/Operators to the State Machine
        6. How CPLBuildStatus Tracks Where to Add New Operators
          1. Adding a Simple operator
          2. Adding a Compound operator
          3. Using the Compound operators list
          4. Linking subactions to the state machine
      8. Feature Activation
        1. Walkthrough of Feature Activation
        2. State Machine for Call Forward Busy/No Answer
        3. State Machine for Call Forward All Calls
      9. How to Develop a Feature
        1. Desired CPL
        2. Sample CPL Scripts
          1. Example 1: Call Blocking
          2. Example 2: Caller ID Blocking: complete
          3. Example 3: Call Forward All Calls
          4. Example 4: Call Forward Busy/No Answer
          5. Example 5: Call Return
          6. Example 6: Call Screening
          7. Example 7: Voice Mail
      10. Feature Server Files
        1. Base Files
        2. CPL Conversion Files
        3. Classes
        4. Code Changes
          1. cpl.dtd
        5. CallProcessingLanguage Class
        6. CPLOpIM Class
        7. CPLOpAddressBkLookup and More
        8. CPLInterpreter Class
        9. Arguments for CPLBuildStatus
      11. Writing Your Next Killer Feature
    15. 14. Unified Voice Mail Server
      1. High-Level Design
      2. Voice Mail Feature Server
        1. Initialization
          1. Provisioning
          2. Data structures
          3. VmBuilder instantiation
          4. VmBasicProxy instantiation
        2. Heartbeat
          1. FSVM receiving UAVM heartbeat messages
          2. FSVM sending heartbeat messages
        3. Call Processing
        4. FS Code Hooks
      3. Voice Mail User Agent
        1. VMCP Protocol
        2. vmcpDevice
          1. VMCP message handling
          2. SIP message handling
        3. Play/Record
          1. Play
          2. Record
        4. DTMF Digits
        5. VmServer Redundancy
      4. Voice Mail Server
        1. VMCP Messages Received by VMS
        2. VMS Initialization
        3. IMAP Server
        4. Interactive VMS Mode
      5. Setting Up a Voice Mail System
        1. Configuring the Server
        2. Adding a New User
        3. Recording the User Greeting
        4. Running the Server
        5. Running the Client
    16. 15. MGCP Translator
      1. Media Gateway Control Protocol
        1. Comparing MGCP to SIP and H.323
        2. Messages
          1. Two-level implementation
          2. Architecture
        3. Vovida MGCP API
          1. Architecture
          2. Memory management
          3. Error handling
          4. Interoperability
          5. Issues
      2. MGCP Translator
        1. Key Data Structure
        2. High-Level Flow: Startup
          1. Provisioning
          2. Starting the Call Agent
          3. Starting heartbeating
          4. Starting the MGCP stack threads
          5. Starting to receive SIP messages
          6. Starting MGCP state machine
        3. Call Flow Sequence
      3. Test Tools
      4. Future Development
      5. Detailed Message Flows
        1. Registration
        2. Basic Call
          1. Off-hook
          2. Dial tone
          3. Dials digits
          4. Ring-back tone
          5. Established speechpath
          6. On-hook
          7. Speechpath cleared
          8. Rings
          9. Off-hook
          10. Established speechpath
          11. On-hook
          12. Speechpath cleared
      6. State Diagram
        1. Key to the State Diagram
          1. General
          2. State symbols
          3. Event symbols
          4. Process symbols
        2. Walking Through Basic Calls
          1. Making a call
          2. Receiving a call
          3. Tearing down the call
        3. Graphic State Diagram
    17. 16. H.323 Translator
      1. H.323 Background
        1. Messages
          1. Registration, admission, and status (RAS)
          2. H.225/Q.931
          3. H.245
        2. Translator Components
      2. Registration and Admission
        1. Registration
        2. Admission
        3. Placing a Call
        4. Receiving a Call from VOCAL
        5. Tearing the Call Down
      3. Source Code
        1. Project Components
        2. Call-Signaling Gateway
        3. Directory Structure
      4. Getting Started
        1. Platform Supported
        2. Compile Instructions
        3. Using the Software
    18. 17. System Monitoring
      1. SNMP Support
        1. Elements
        2. System Components
        3. Messages
        4. Process Interaction
          1. Creating the executable
          2. Altering the SNMPTRAP daemon
        5. VOCAL’s Network Management System
        6. Flow Diagram
          1. Host 1
          2. Host 2
          3. Host 3
          4. Host 4
          5. Host 5
      2. MIBs
        1. Network Services Monitoring MIB
        2. SIP MIBs
        3. UCD Enterprise MIB
      3. SNMP Daemon
        1. High-Level Flow
        2. Key Data Structures
      4. Network Manager
        1. Threads
        2. Heartbeat Server
        3. SNMP++
      5. Agent API
        1. Implemented MIBs
        2. MRTG-Generated Statistics
        3. Running the SNMP Agent
      6. SNMP GUI
        1. Hosts and Processes
        2. SNMP Process Controller
        3. SNMP Traps
        4. Most Recent Trap
      7. Adding MIBs
        1. SNMPd Side
        2. Agent Side
        3. MIB Group Directory
      8. Creating New Agent Code
        1. Agent Extensibility
        2. example.h: Interface Information
        3. example.c: Implementation Code
        4. MIB to C Script
        5. Using mib2c
      9. Heartbeat Server
        1. Transmit Thread
        2. Receiving Heartbeats
        3. Housekeeping
        4. Using the Heartbeat Software
    19. 18. Quality of Service and Billing
      1. Quality of Service
        1. Policy Server
        2. COPS
          1. Key features
          2. Basic protocol design
          3. Messages
          4. Classes
        3. RSVP
        4. Quality of Service Enabled
          1. Suggesting a bandwidth path
        5. Managed Networks Versus the Internet
      2. Billing
        1. CDR Server
          1. The bill record
          2. Sending records with RADIUS
          3. Class descriptions
        2. Call Detail Records
          1. What defines the start of a call?
          2. Notifying the CDR server for Start record
          3. What defines the end of a call?
        3. RADIUS Stack
          1. Key features
          2. Operation of RADIUS accounting
          3. Authentication
          4. Initialization of service
      3. OSP
        1. Making Internetwork Calls
        2. The INVITE Message Is Received
        3. Tearing Internetwork Calls Down
      4. Billing and Toll Fraud
    20. 19. Provisioning
      1. Old Provisioning System
        1. Key Features
        2. High-Level Flow
        3. Key Data Structures
        4. Redundancy
          1. No redundancy
          2. Redundancy
          3. Synchronization
          4. After synchronization
          5. Resynchronization
        5. Miscellaneous
        6. PSLib
          1. Classes
          2. Caching
      2. Mascarpone Provisioning System
        1. Architectural Overview
          1. Top-level components
          2. Modular Provisioning server
          3. Autogenerating reference GUI
          4. Bulk-provisioning tool and other GUIs
          5. Interface library
          6. Daemon
        2. Protocol
      3. Provisioning Server
        1. Architecture
        2. Redundancy
        3. Provisioning Server Modular Database API
          1. Design
          2. DBConnection class methods
          3. DBResultset class methods
          4. Search filters
      4. Provisioning Interface Libraries
        1. PSLib
          1. PSLib components
          2. Client/PSLib call flows
        2. PSLib API
          1. ProvisioningInterface class functions
          2. PSDBResult class functions
        3. Java Comm Package
          1. Comm package components
      5. Java User Interface
        1. Dynamic GUI from Text Description
          1. Architecture
          2. GuiComponent
          3. ContentData
          4. Getting and setting data
        2. Tabular Display of Data
          1. Tasks
          2. Event handlers
        3. Template Builder
          1. DataProviders
          2. User interface
        4. Dial Plan
        5. Security/Authentication/Encryption
        6. Server Provisioning
        7. Account Provisioning
      6. GUI Screens
      7. DTD for Data Definition
      8. Examples of Protocol Transmissions/Replies
    21. A. VOCAL SIP UA Configuration File
      1. General
      2. SIP Port and Transport
      3. Proxy Server
      4. Transfer and Conferencing
      5. Registration
      6. Ringback
      7. RTP
      8. Call Waiting
      9. Call Progress Timer
      10. Subscribe/Notify
      11. Dialing Timers
      12. Dial Patterns
      13. Speed Dial List
      14. RSVP Configuration
      15. Manual Call ID
      16. Load Generation
    22. B. Testing Tools
      1. genPutUsers.pl
      2. Netcat
    23. Index
    24. Colophon