Documentation

• In the tar-balls, there is a file called README with basic information, installation and bootstrap procedures.
  
• Quick start guide for the impatient one that just want to get Yxa up and running with two phones.
• Simple site configuration howto to get you started.
• More in-depth Architecture document, trying to describe how the pieces are connected and how to write Yxa SIP applications.
  
• Text about how (non-)RFC-compliant Yxa is.
  
• CPL sub-system design analysis.
  

Basic information

Why the name Yxa?

'Yxa' is Swedish for 'axe'. AXE is a large (traditional) telephony switching system made by Ericsson (Erlang is a programming language developed by Ericsson).

Why write it in Erlang?

Although it might seem odd to choose a language that is not as widely used as C, C++ or Java, we believe that Erlang is a language very suitable for writing a reliable SIP server in.

Erlang is the result of two decades of work at Ericsson to create a programming language (together with a set of function librarys) for writing large, fail-safe, soft real-time telecom applications. Erlangs three main advantages for this kind of programming are :

• Strong process isolation properties, together with extremely light-weight processes. This, together with the fail-recovery mechanisms of Erlang OTP, makes it easy to prevent for example malformed SIP-messages from crashing the whole system.
• Erlang comes with a multi-master distributed database called Mnesia. This is extremely good to make the location database available to all servers and allows for multiple registrar servers, without having a single database server backend resulting in a single point of failure.
• According to programmer productivity measurements, a single programmer is able to write the same ammount of lines of code per work-day, regardless of if it is Erlang or C. Erlang programs is typically five to ten times shorter than their equivalence in C. This means less development costs and shorter time-to-market. Also, Erlang isn't as hard to learn for someone who knows other programming languages as you might think.

Applications

incomingproxy

This is what most people would think of as the main program. Functions :

• Handle REGISTER requests
• Proxy requests from UACs (clients, phones) to other parts of the Yxa system
• Relay requests to remote servers/domains
• Sequential destination searching
• Routing features:
  • Location database querys
  • Do ENUM lookups of things that looks like E.164 phone numbers
  • Lookup telephone numbers/SIP addresses in LDAP (can also look for users with e-mail addresses matching the SIP address being called).
  • Do regexp-rewriting of Request-URI's
  • Default routing
  • ...

outgoingproxy

Helps SIP requests traverse NATs between your clients and your proxys. It's better to not use NAT, but not everyone has that option. Also, some clients are broken to the point that they need an application like this even when they are not behind NAT, since they don't accept SIP requests from other proxys than the one they registered with.

pstnproxy

Written to make it possible to control access to a (Cisco) VoIP gateway that has no SIP destination access control of its own. Functions :
• Let different users call PSTN numbers they have access to based on number classification done using regular expressions.
• Let anyone call PSTN numbers in configured classes without authentication. For example, you might have a gateway to your PBX and you want your employees to be able to call any PSTN number, but anonymous users on the Internet should only be allowed to call numbers that are free to you (internal, and perhaps toll-free numbers).
• Supports looking up SIP users phone numbers in LDAP and identifying them via Remote-Party-Id to the VoIP gateway for working caller-id.
• Can do ENUM lookups for calls from the PSTN. This way you could do least-cost-routing from your PBX by setting it up to try SIP+ENUM first, and fall back to PSTN if no ENUM-data was found.

appserver

Handles more complicated requests to users of an Yxa system, like forking and CPL script interpretation. You will need to an incomingproxy too. The incomingproxy then forwards incoming requests to your users to the appserver if they have more than one location registered in the location database, or if they have a CPL script. Functions :
• Parallell forking of requests.
• CPL interpretation. CPL is Call Processing Language - a way to specify how the server should act when people call you - much like e-mail filters for incoming e-mail sorting. You can use it to direct calls differently depending on who is calling, what time of day it is etc.

testserver

This program is used together with the testclient.pl perl-script to verify certain functionality of the Yxa system when making code changes. We have automatic code tests which are executed using "make test", but some tests are still easier to perform using real SIP requests, sent over a real network connection.

Web interface

There is a web interface available. It is based on Yaws. See the documentation in the README file to learn how to set it up. Things you can do with the web interface :
• See which server nodes are running.
• Inspect the location database.
• Manage user accounts, if you are using the Mnesia user database backend (default).
• Get information about running nodes, like their uptime, configuration, ongoing transactions etc.

$Id: documentation.html,v 1.9 2006/08/01 06:45:13 ft Exp $