Dial Plan

Starting with a Basic Dialplan

Dialplans define the exact parameters of how a call is processed. When someone calls you, do you want the call to go to your extension first and then your voice mail? Or, do you want the caller to receive a recording asking him to enter an extension first? You can also establish an order in which calls reach you. You can build a dialplan that attempts to reach you on your office line, your cellphone, and the VoIP softphone on your computer, and then send the call to your voice mail . . . now that's being connected!

You build the dialplans in the extensions.conf file that is usually located in the following directory:

/etc/asterisk

The extensions.conf file is one long string of dialplans, separated only by the individual contexts within brackets. All configurations beneath one context and above another apply to the upper context.

This is an example of a simple dialplan:

[incoming]

exten => 2565551212,1,Answer()

 Remember   This simple dialplan doesn't look like much now, but from these humble beginnings, great things are made.

Figure 5-1 identifies the four elements of a basic dialplan. Each element of the dialplan acts as shorthand for a set of rules, processes, or locations that are applied to all calls that fall within the dialplan parameters. The dialplan in Figure 5-1 is for an incoming call that is being directed to phone number 9495551212. This scheme doesn't play a greeting to the caller, nor does it offer voice mail or a list of extensions; it simply sends the caller to the extension for phone number 949-555-1212, where the caller remains until someone picks up the line or he hangs up the phone.

 

 Understanding the context

[incoming]

exten =>9495551212,1,Answer()

The context is the first line of code and it correlates to the context you defined when configuring the individual VoIP, analog, digital, and/or IAX devices. (If you're wondering how to program the context to these devices, check out Chapter 4.)

 

 

When a call comes in to the server, Asterisk looks for the device sending the call (SIP/0001, for instance) for registration. If Asterisk can't find the registration, it looks for a default context for the channel type (VoIP, analog, or IAX connection, for example).

You should group devices with the same functions and that belong to the same financial entity into contexts for ease of programming. The contexts we cover in this chapter are as follows:

§                    [incoming]: Use this context to configure Asterisk for inbound calls.

§                    [internal]: Use this context to configure Asterisk for calls that are transferred between two endpoints within the Asterisk network.

§                    [outgoing]: This context is for outbound calls through analog, digital,VoIP, or wireless connections.

§                    [globals]: This is a special context in which you build dialplan universals that you apply to all contexts. Your home area code would be listed here, for example, and used as a telecom point of reference for all local calls.

 

 

These contexts are actually configuration contexts assigned to devices connecting to the Asterisk system. The device parameters and abilities are linked to the dialplan, which allows you to process the incoming and outgoing calls from the device. The [globals] context is the only special context because the relationships established in this context are used in every other context in your dialplan. These relationships are generally coding expedients whereby a common name is used to replace a complex device ID, such as

TRUNK=SIP/111.222.333.444/

This programming shorthand, called a variable, allows you to write the word TRUNK instead of typing the VoIP port and IP address of SIP/111.222.333.444.

 

 

 

 Remember   You don't have to use all these specific context names. Only the [globals] context is preset in Asterisk. You can use any naming convention you want for the other contexts. Context names can include letters, numbers, and hyphens. You can make your life easier if you do name your dialplans something descriptive. Context names such as [inbound], [outbound], [longdistance], [local], [international], and [extensiononly] are easier to work with, and you can more easily remember their purpose.

 

 

 

 Warning   Okay, you can also use underscores in context names, but they can be problematic. Underscores are also used in other aspects of Asterisk, and mistyping a context with an underscore can complicate your dialplan. We recommend not using them for contexts; stick with hyphens instead.

 Tip   If you're using Asterisk for internal company use as well as for external customers, create context names that reflect the different entities. For instance, you can split the [incoming] context into the following:

[incoming-mine]

[incoming-customer]

Splitting contexts reduces confusion and allows you to handle internal calls differently. If you dial 0 in your office, you probably want to speak to your receptionist. If your customer has the option of dialing 0, you can have him sent to your customer service queue instead.

Asterisk does have one context that isn't really a context as we understand them in the dialplan. The [general] context is located in the extensions.conf file, but is actually a general holding place for information in the extensions.conf file and not a traditional context like [incoming] or [outgoing]. It holds information that pertains to all contexts, like the autofallthrough option that acts like a security net to handle calls that may have inadvertently have no real destination due to a gap in your dialplan programming

 

Identifying extensions

[incoming]

exten =>9495551212,1,Answer()

In the most traditional sense, extensions refer to the number you dial to call someone within your company. Asterisk takes extensions to a whole new level. It views not only the physical phone on a desk or channel driver (SIP/ZAP, IAX) as an extension, but it also provides intelligence to the extension allowing it to play a message while sending the call to various places, in this order:

1.          The phone on your desk.

2.          Your cellphone, if you don't answer your desk phone in a preset number of seconds.

3.          Your voice mail, if you don't answer your cellphone.

 

Remember   The new era of VoIP also expands how you identify extensions. You are no longer restricted to simply using numbers to identify Asterisk extensions. You can use e-mail addresses as valid extension names if you build them into the system, as well as employee names (for use in dial-by-name directories).

The extensions you build can be as complex and dynamic as you need. The automated systems that prompt you for your essential and nonessential information when you call customer service are one example of the intelligence you can build into an extension, or a set of extensions. Every response the caller keys into the system either sends her to another extension within the system in a different context, or simply further along in the dialplan. As long as you remember that an extension can be a virtual destination within a device used to qualify responses of the caller, and not just a phone on a desk, you are ready to unlock the potential of Asterisk extensions.

 

Technical Stuff   Devices are physical hardware and can contain and facilitate extensions, but aren't extensions themselves. The only way you can reach a device is through an extension, which must be dialed to route a call to a specific device. The rub is the fact that extensions are not defined on a one-for-one basis with devices.

Extensions can have a multitude of possible destinations, of which only some are devices. Samples of nondevices into which an extension can terminate are as follows:

 

§                    Applications

§                    Direct voice mail servers

§                    Calling card applications

§                    Conference rooms

§                    Fax servers

 

If you want to call the physical analog phone in your customer service department from the VoIP softphone on your desk, you simply dial the Asterisk internal extension that directs your call to a device connected to the Zaptel card, and the remote phone rings. If you want to call Papua, New Guinea, over your outbound VoIP carrier, your Asterisk actually connects your call to an extension that terminates in an outbound device, such as SIP/1.

Extensions are identified in the extensions.conf file with the following line of code:

exten => 133,1,Answer()

The exten => part identifies the extension, and the number or letters after the => indicate the specific extension you're defining. In this example, 133 is the extension.

Just like the context names, you can design most of your own extension names. The default extensions with Asterisk are as follows:

§                    exten => s: This extension is the start extension. It receives calls and plays an automated greeting prompt as long as it is configured in your device configuration.

 

§                    exten => i: This is the invalid extension. If you prompt a caller to input a 3-digit extension number and he presses three digits that aren't listed as a legitimate extension, he's sent to exten=> i.

 

 

§                    exten => t: This is the timeout extension. You set time limits on some extensions in your dialplan, and if the caller doesn't choose a prompt within your time limit, the call is sent to the exten => t extension.

 

§                    exten => T: This is an absolute timeout identifying the maximum duration Asterisk allows for an active phone call before it's sent to the T extension or hung up. Carriers use a feature like this to prevent calls that have failed to completely hang up (called a hung call) from remaining active in their switch.

 

 

§                    exten => #: This functions like a command more than an extension.It's normally used to hang up a call in a dialplan with many layers of recordings prompting you to "press 1" for this and "press 2" for that. These Interactive Voice Response (IVR) systems use the extension as an expedient to disconnect a call, in spite of it not being a traditional "pre-defined" extension destination.

 Remember   These extensions are case-sensitive. Confusing a t extension with a T extension could result in calls being disconnected that simply can't find their extension. Pay attention when using them in your dialplan to avoid headaches later.

These extensions allow you to build a solid dialplan. Asterisk does have a safety net to prevent calls from being sent to limbo and left hanging. The autofallthrough option in the [general] section of the extension configuration prevents forgotten calls from lingering in the system.

The default extensions in the previous bulleted list are predefined destinations in Asterisk. You must still define them in your context so that Asterisk knows what you want it to do when someone must be routed to the extension. Do you want to hang up on people that exceed your timeout limit, or send them back to the main recorded greeting for a second chance? Failing to program for these little eventualities can cause the call to congest the system and automatically be hung up.

Warning   It is very important to identify and process calls that time out. Someone could call you on Friday at 5:00 p.m. on your toll-free number, connect to your phone system, and fail to hang up correctly (honest, it happens). In this case, you would have a billable phone call that lasts until Monday morning, when the person calling you realizes his phone line has no dial tone because it is still connected to your system.

 

Utilizing priorities

[incoming]

exten =>9495551212,1,Answer()

The second parameter of the extension code is the priority; it controls the sequence of events in the dialplan. Each priority contains a call to a single application in Asterisk. It can also forward information to that application, if necessary, to provide additional features to the call. The priorities increase in value as each step in the dialplan is executed. A dialplan with several steps would look like this:

exten => 133,1,EatPizza()

exten => 133,2,DrinkSoda()

exten => 133,3,WathchTV()

exten => 133,4,TakeNap()

This is, of course, a bogus Asterisk extension with non-existent applications, but it does demonstrate how the priority increases sequentially as progressive actions are taken in sequence.

Tip   If you don't want to remember the last priority you used in an extension, you can replace the priority number with n (which is referred to as an unnumbered priority). The n represents the previous priority plus 1. You write an unnumbered priority in a dialplan like the following:

exten => 133,1,EatPizza()

exten => 133,n,DrinkSoda()

exten => 133,n,WathchTV()

exten => 133,n,TakeNap()

Engaging an application

[Incoming]

exten =>9495551212,1,Answer()

The application is the last element of code in the extension line. Even though it is only one element, it is actually constructed of two distinct sections: the application and the argument:

 

§                    Application: The application represents the action being taken at this step (priority) of the extension. In Figure 5-2, the application being used is dial. The first channel on the Zap card from extension 9495551212 is being dialed.

 

Figure 5-2: An application schematic.

Many different applications are available with Asterisk; answer, hangup, background, dial, and Goto are the most important to know, so we discuss those in the following sections.

§                    Argument: The argument includes three unique parameters, separated by commas. In Figure 5-2 the arguments are as follows:

 

o                           Parameter 1: The syntax of the first parameter of the code specifies the channel technology/resource. Our example identifies the channel technology as ZAP, indicating the Zapata time-division multiplexing (TDM) (analog) card. The resource, listed after the backslash is 1, indicating port 1 as the channel device using this application. It could have just as easily been a device with a VoIP port, a digital card, or a Wi-Fi port.

o                           Parameter 2: The 20 identifies that you're requiring Asterisk to maintain this application for 20 seconds. If the dialed device answers the call before the 20 seconds are up, the call is bridged through it. If the dialed device doesn't answer in 20 seconds, the extension proceeds to the next priority. You can configure it to send the call to voice mail, return to the main operator for the system, or disconnect the call. Each of these available fallback destinations is an additional priority and is located in the current context, or in another context.

o                           Parameter 3: The r parameter allows the person originating the call to hear the phone ringing.

 

 

 

 

 

 Remember   You can omit any of the parameters within the argument if you don't want to restrict the call or enable the ringing. An extension without a specified duration looks like this:

exten=> 9495551212,1,Dial(Zap/1,,r)

If you want to keep the 20-second time limit on the application, but don't want to the person making the call to hear a ringing tone, the code is as follows:

exten=> 9495551212,1,Dial(Zap/1,20)

Answering calls

The answer() application doesn't use arguments; because the parentheses are always blank, you can omit them if you want. The answer() application receives a call from the outside world and sends a connect signal back through the device that originated the call.

 Technical Stuff   The parentheses in applications aren't essential if they don't hold any information. You can even replace the parentheses with a single comma between the application and the arguments. For example, you can write the application Dial(Zap/1,,r) as Dial,Zap/1,,r.

The Asterisk environment is very dynamic, so don't be linked to the idea that whenever we mention a call that it is coming from someplace beyond your network. A wealth of calls is flying through Asterisk networks from SIP phones to voice mail, or analog phones linking up on a teleconference. A whole world of traffic is rolling through your Asterisk phone; this traffic is referred to as calls.

 Remember   The connect signal sent back to an incoming carrier happens regardless of the device that delivers the incoming call. The answer() application also receives inbound VoIP calls or internal calls into your Asterisk phone. The answer() application is only necessary when immediately connecting you to a system that plays a message, such as "Please enter the extension of the person you wish to dial," before connecting you to a second device.

The application doesn't play a recorded message or anything else, aside from establishing a connection on the call. The code for a call sent to a default start extension (s) and answered appears like this in a dialplan:

exten=> s,1,Answer()

exten=> s,2,Background(enter-ext-of-person)

 Remember   Only use the answer() application when it is inside your IVR system (you know, the thing asking you for the extension you wish to dial). You don't have to use this application if you are using the dial application directly because it automatically answers the call when the destination channel picks up the call.

Hanging up calls

The hangup is the logical conclusion to every call. As such, this command doesn't appear with a priority of 1. Common courtesy dictates that you at least answer the phone before hanging up on someone. The code for a call to be answered and then hung up is as follows:

exten=> s,1,Answer()

exten=> s,2,Hangup()

Responding to touch tones

We have all called a large company and received the voice-mail prompt of "Please enter your party's 3-digit extension." You also notice that if you dial the 3-digit extension while the recording is playing, it stops the recording and immediately sends you to the extension you dialed. Asterisk has the same feature, and because it is waiting in the background for you to dial the extension, the application is called background(). It looks like this in the dialplan:

exten=> s,1,Answer()

exten=> s,2,Background(enter-ext-of-person)

Dialing the new-fashioned way

Every inbound call includes at least two segments. The [incoming] context receives the call into the Asterisk, but after it has arrived there, the call must still be sent to a desired channel device, voice mailbox, or external carrier. The dial() application allows you to forward the call to its next destination. The following example demonstrates a simple dialplan using dial():

[internal]

  exten => 0,1,Dial(Zap/1,20,r)

This code allows internal customers to dial 0 and receive the operator that is connected to the Zap/1 card.

Moving with a Goto

The Goto application allows you to do wonderful things because it allows you to send a call from one context to another. A simple dialplan that allows an incoming customer call to reach your internal operator looks like the following:

[internal]

  exten => 0,1,Dial(Zap/1,20,r)

[incoming-customers]

  exten => 7,1,Goto(internal,0,1)

 Tip   If you want a complete list of the applications available on your Asterisk, you can type the show applications command in the Asterisk command-line interface (CLI). When you find an application you are interested in, you can read a detailed document on the application by querying Asterisk for it with the following command:

Show application name

Simply replace name with the name of the application you are interested in, and a document appears with all the application's pertinent information. You can also find the documentation by scanning the /docs/ directory of the Asterisk source code.

For a general list of applications available on Asterisk, check out the following Web site:

www.voip-info.org/wiki-Asterisk+-+documentation+of+application+commands

This simple bit of code shows how the call in the [incoming-customers] context, when pressing extension 7, is routed to the new [internal] context, extension 0 and priority 1. The [internal] context identifies where extension 0 is sent.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

How to create a Callback option

Overview

This tutorial will show you how to create a queue, where your incoming calls to arrive. Noting so special, but we are also going to show you how to give a choice to the callers - they will be able to leave the queue at any time and in our example they will have the choice to leave a number at which you could callback them later. The best part is that the number will be nicely emailed to your email box with details not only about the left number, but also the CallerID, the queue at which the caller was initially placed and the date and time at which he has left his number.

Prerequisites

Before we start we will assume that you have a working Asterisk PBX with registered users in iax.conf, sip.conf or mgcp.conf(It depends on which protocol you would like to use)

We will show you how to create your extensions in extensions.conf.

For the sending of the emails you will need to install the mime-construct package. apt-get install mime-construct (in Debian) should do the trick. Of course you will need a SMTP server too.

Asterisk PBX configurations

We need to create one user in the iax.conf file. This is because we are going to use Idefisk and its IAX2 support. Idefisk supports the SIP protocol too. So if you want to use it, you have to do the configurations below respectively in sip.conf.

Here is the configuration.

[general]
trunkmtu = 4000
bandwidth=low
disallow=lpc10
jitterbuffer=no
forcejitterbuffer=no
tos=lowdelay
autokill=yes

[caller1]
secret=caller1
type=friend
host=dynamic
context=incoming_calls

So, we now we have the user caller1

Type=friend means that this user can make and receive calls. Host=dynamic means that the IP is not statically assigned but dynamically through a DHCP server. Allow=allmeans that the line which this user will use, support all available audio codecs, supported by Asterisk. Context=test - this shows that the user is allowed to work with the extensions in the context with this name in the configuration file extensions.conf.

Our extensions.conf looks like:

The configuration is below:

[incoming_calls]

exten => 100100,1,Set(CALLERID(name)=queue1)
exten => 100100,n,Queue(queue1)
exten => 100100,n,Hangup()

exten => 200200,1,Set(CALLERID(name)=queue2)
exten => 200200,n,Queue(queue2)
exten => 200200,n,Hangup()

exten => 300300,1,Set(CALLERID(name)=queue3)
exten => 300300,n,Queue(queue3)
exten => 300300,n,Hangup()

[queue1out]

exten => 1,1,Set(FLAG=1)
exten => 1,n,Playback(CallBack)
exten => 1,n,Read(NUMBER|beep|10|||5)
exten => 1,n,Wait(1)
exten => 1,n,Set(FLAG=2)
exten => 1,n,GoToIf($[${NUMBER} = ""]?empty:full)
exten => 1,n(empty),System(/usr/bin/call/mailnonumber.sh callback@test.org ${CALLERID(num)} Queue1)
exten => 1,n,Hangup()
exten => 1,n(full),System(/usr/bin/call/mailnumber.sh ${NUMBER} callback@test.org ${CALLERID(num)} Queue1)
exten => 1,n,Hangup()

exten => h,1,NoOp(${FLAG})
exten => h,2,GoToIf($[${FLAG} = 1]?h|3:h|4)
exten => h,3,System(/usr/bin/call/mailnonumber.sh callback@test.org ${CALLERID(num)} Queue1)
exten => h,4,Hangup()

[queue2out]

exten => 1,1,Set(FLAG=1)
exten => 1,n,Playback(CallBack)
exten => 1,n,Read(NUMBER|beep|10|||5)
exten => 1,n,Wait(1)
exten => 1,n,Set(FLAG=2)
exten => 1,n,GoToIf($[${NUMBER} = ""]?empty:full)
exten => 1,n(empty),System(/usr/bin/call/mailnonumber.sh callback@test.org ${CALLERID(num)} Queue2)
exten => 1,n,Hangup()
exten => 1,n(full),System(/usr/bin/call/mailnumber.sh ${NUMBER} callback@test.org ${CALLERID(num)} Queue2)
exten => 1,n,Hangup()

exten => h,1,NoOp(${FLAG})
exten => h,2,GoToIf($[${FLAG} = 1]?h|3:h|4)
exten => h,3,System(/usr/bin/call/mailnonumber.sh callback@test.org ${CALLERID(num)} Queue2)
exten => h,4,Hangup()

[queue3out]

exten => 1,1,Set(FLAG=1)
exten => 1,n,Playback(CallBack)
exten => 1,n,Read(NUMBER|beep|10|||5)
exten => 1,n,Wait(1)
exten => 1,n,Set(FLAG=2)
exten => 1,n,GoToIf($[${NUMBER} = ""]?empty:full)
exten => 1,n(empty),System(/usr/bin/call/mailnonumber.sh callback@test.org ${CALLERID(num)} Queue3)
exten => 1,n,Hangup()
exten => 1,n(full),System(/usr/bin/call/mailnumber.sh ${NUMBER} callback@test.org ${CALLERID(num)} Queue3)
exten => 1,n,Hangup()

exten => h,1,NoOp(${FLAG})
exten => h,2,GoToIf($[${FLAG} = 1]?h|3:h|4)
exten => h,3,System(/usr/bin/call/mailnonumber.sh callback@test.org ${CALLERID(num)} Queue3)
exten => h,4,Hangup()

As we are talking about queues, we are going to create three different queues in thequeues.conf configuration file

The configuration:

[general]

[default]

[queue1]

music = default
strategy = ringall
timeout=15
retry = 5
context = queue1out
periodic-announce-frequency = 60
periodic-announce = Call_Back_1

member => IAX2/user1
member => IAX2/user2
member => IAX2/user3
member => IAX2/user4
member => IAX2/user5
member => IAX2/user6
member => IAX2/user7
member => IAX2/user8
member => IAX2/user9

[queue2]

music = default
strategy = ringall
timeout=15
retry = 5
context = queue2out
periodic-announce-frequency = 60
periodic-announce = Call_Back_1

member => IAX2/user1
member => IAX2/user2
member => IAX2/user3
member => IAX2/user4
member => IAX2/user5
member => IAX2/user6
member => IAX2/user7
member => IAX2/user8
member => IAX2/user9

[queue3]

music = default
strategy = ringall
timeout=15
retry = 5
context = queue3out
periodic-announce-frequency = 60
periodic-announce = Call_Back_1

member => IAX2/user1
member => IAX2/user2
member => IAX2/user3
member => IAX2/user4

Now let’s take a look at the shell script you will need if you want to send emails with the left number. The script will use the mime-construct program to create the email message and send it to the desired recipient. The second script has the same purpose and the only change is in the body of the email message.

Here are the configurations:

Script 1:

#!/bin/sh

NUMBER=$1
RECIPIENT=$2
CALLERID=$3
QUEUE=$4

mime-construct --to $RECIPIENT --subject "You have just missed a call" --string "The number that have been left by the caller: $NUMBER. The CallerID we have received: $CALLERID. The call is coming from the $QUEUE queue. Call was received at `date`"


Script 2: 

#!/bin/sh

RECIPIENT=$1
CALLERID=$2
QUEUE=$3

mime-construct --to $RECIPIENT --subject "You have just missed a call" --string "The caller did not left a telephone number. The CallerID we have received: $CALLERID. The call is coming from the $QUEUE queue. Call was received at `date`"

 

4. Explanation

Now, we are going to explain you what the configurations about actually means and how it works.

However, keep in mind that we are going to explain you only the configurations concerning the Callback possibility. If you want to learn more about the used configuration files and their options - take a look at one of our tutorials:

iax.conf
extensions.conf
queues.conf

Let's start with queues.conf.

In the example above you could see three different queues each one with different number of agents.

Each queue has its own configuration. Most of the settings are common, unless one option - the context.

This option is giving you the possibility to define a context, where eventually, by pressing a single digit, the caller will be "transferred". The digit could be pressed at any time while the caller is waiting in the queue. The context we are talking about has to be created in the extensions.conf configuration file. There is one more requirement and it is that you have to create an extension of one digit, in this context - the digit that the caller will press in order to exit the queue.

Despite of the fact, that for all the queues, the setup for leaving a number and then emailing it to our email address will be pretty much the same, we recommend you to create different contexts for every different queue. That is because we are going to email not only the left number but also some other information such as the queue from which the caller has quitted. Of course you could do it with one common and more complicated context for all the queues, but we think that it will be much easier to manage and change the settings for each queue independently of the other ones.

So here are all the options in our queue and what they are doing"

music = default - the music class defined in musiconhold.conf, where Asterisk will be looking for mp3 files, which will be played to the caller instead of ringing tone, while he is waiting in the queue. 
strategy = ringall - one of six ringing strategies that you could choose. This one means the phone of each agent, assigned to the queue, will start ringing in case of incoming call. For details about the other strategies take a look at our tutorial about queues.conf 
timeout=15 - a timeout in seconds. It defines after how many seconds with no answer the agent phone to stop ringing. For more information about refer to our tutorial about queues.conf .
retry = 5 - after how many seconds to try to ring all the agents again. For more information about refer to our tutorial about queues.conf.
context = queue3out - we have already explained this above.
periodic-announce-frequency = 60 - define in seconds an interval of time after which the caller, waiting in the queue, will hear a prerecorded message. It could be a message with instructions or something else. It is up to you. For more information about refer to our tutorial about queues.conf.
periodic-announce = Call_Back_1 - that is the name of the prerecorded message that should be played after the periodic announce timeout expires. For more information about refer to our tutorial about queues.conf.

member => IAX2/user1 - there are two different ways to assign agents to a specific queue. We have picked up the easies one. Whenever a phone with username user1 is registered successfully to the Asterisk system, the incoming calls in the queue will be send to this phone. You could have as many as you want agents assigned to the queue in this way and the incoming call will be send to all of them according to the chosen strategy. For more information about refer to our tutorial about queues.conf.

Now let's take a look at the configurations in extensions.conf.

First of all we have three extensions for the incoming calls. They are all put in the[incoming_calls] context. Their purpose is to put the incoming calls in the corresponding queue.

When we have an incoming call, the first thing we are doing is to change the Callerid name to the name of the queue where the caller will be put. Thus the agent who is answering the call will know from which queue exactly the call is coming. It is not absolutely necessary, but the idea is that one agent could be assigned to many different queues. In order to do the change we are using the Set application - More information about it in our tutorial

The next step is to actually send the call in the queue - pretty easy one. There is an application called Queue to which you just have to pass the name of the desired queue as an argument. We are not going to use any extra options. You could find more information about how to use the QUEUE application in our tutorial

You could notice and the usage of the Hangup application. It is always a good idea to use it as last application for all of your extensions. Thus, you will always be sure that the used channel will be released when the conversation is over. Refer to our tutorial for more information on this application

Next step is to create the contexts, where the callers should be "transferred" in case they have decided to exit the queue. As we have mentioned above we have different context for each of the queue. 

Before we continue - a few words about the idea behind. We are running queues with a callback option. In other words, when we have a caller waiting in the queue, we will play him a message every 60 seconds. The message will saying: "All of our lines are busy. You could leave your number by pressing one and we will call you back as soon as possible or you could stay in the queue and wait to be served.".

If the caller decides to exit the queue, he will be asked to leave his number after the "beep" signal. At this stage, you have to keep in mind that the caller might not leave his number for some reason. So what we will have a check and if the number is not left we will send an email message that the caller has decided not to leave his number.

So what do we need as extensions? The first thing we are doing is to set a flag. Why? In case the caller hangs up at some point before leaving his number, we need to send a message that we did not received the number. For the purpose we are using the so called predefined extension - h, which allows you to execute something in case of hang up. Refer to our tutorial for more information

However, there is a slight chance that the caller might wait for the timeout to expires without leaving his number or to have a problem with the sending of DTMF tone, that we will have an email saying that the caller has left his number but the number field will be empty and because we have a hang up event even if the caller has left his number, we need the flag to determine whether the hang up is before the application that will store the number or after it and on that basis we will know whether we need to send an email message on hang up or not. In this way we omit the sending of one message twice.

On the next step we have the Playback application. Its simple purpose is to play a sound files. We have a sound message, which instructs the caller to type his number after the beep tone and to press the pound key (#) when he is ready. For more information refer to our tutorial about the Playback application

Next, comes the Read application. It’s the one used to store the number typed by the caller. It has many options. 

There is a small limitation in the application we are going to use to save the number typed by the caller. We need to know, when he has finished with the typing. So there are two ways. 

The first one is to ask him to press the pound key (#) once he is ready and the second one is to limit the length of the number the caller could type plus a timeout.
In our example we are going to limit the length of the number to 10 digits and we are going to put a timeout of 5 seconds. We are going to store the number typed by the caller in the NUMBER variable. The Read application gives you the possibility to play a sound file before the typing of the number. In our case we will are going to play abeep tone

Refer to our tutorial for more information and details about the Read application

Next steps - we have the Wait application, which is not absolutely necessary and then we set the flag variable to 2. This, as we have already described above will be used to omit the sending of one and the same email message twice. For more information about the Wait application, refer to our tutorial.

We now have to check whether the caller has actually left his number or not. For the purpose we can use the GoToIf application. It has a very specific syntax, but its idea is simple to verify whether one condition is true or false. So, in our case we are just checking whether the NUMBER variable is empty or not. If it is empty then the execution of the dialplan will continue with the next step, marked as n(empty). nmakes your life easier as you do not have to write and follow the steps (priorities) - nmeans that you take the previous priority and increase it with 1. (empty) is a label showing to you and the system to which n you will be send.

If the NUMBER variable contains even one digit then we assume that we have the number of the caller so the execution of the dialplan will be send to the step with label (full). Refer to our Tutorial for more information, details and option about the GoToIf application.

Both steps (empty) and (full) have one and the same task - to execute the shell script, which will form the email message and send it. The only difference would be in the body of the email message. The application, which we have to use is calledSystem. It just executes system commands as you will do it in your Linux CLI. Refer to our Tutorial for more information about the System application.

In our case we are executing our own scripts called mailnumber andmailnonumber. They are written in such way that we have to pass them a few parameters. You could see them above as screenshots and in pure text

If we do not have the caller's number, we will execute the script calledmailnonumber. We need to add, as first parameter, the email address of the recipient. The second parameter is the CallerId number as we have received it in our system. The last parameter is the name of the queue from which the caller has exited.

If we have the caller's number we will have executed another shell script calledmailnumber which has a different body, but the same parameters plus one more, which of course is the number left by the caller.

The sending of the email is the last step we need to do and that is why after it we have to hang up the channel. For the purpose we will use once again the Hangup application.

In the predefined extensions starting with h we have a simple check of the FLAGvariable to help use determine whether we have to send an email with saying that we do not have the caller's number. (this step is only needed in case the caller hangs up before the prompt to leave his number)

A few words about the shell scripts.

They are not very complicated. All you need is a basic knowledge of shell scripts and the mime-construct package. apt-get install mime-construct (in Debian) and you will have it. Then its just up to the mime-construct's syntax

Now all you have to do is to register your IAX2 base softphone Idefisk to your Asterisk system with the settings, shown above, in iax.conf and dial one of the extensions created in the [incoming_calls] context.

What will happen (if you have followed our setup) is that you will be put in a queue and on every 60 seconds you will hear a message saying that you could exit the queue and leave your number by pressing 1. If you press one you will hear a prompt to leave you number after the signal. Then you will hear beep and if you leave your number followed by the pound key (#), the number will be emailed to the desired email address and you will probably receive a callback.

 

4. Uploaded files

extensions.conf
iax.conf
queues.conf
mailnumber.sh
mailnonumber.sh

 

Clocking - Fundamentals

General Importance of Timing

Clocking (or timing) is essential because digital signals are evaluated or read by the voltage on the line.

Each piece of equipment needs to know exactly when to read the voltage. Figure 1 depicts an ideal digital signal. (The 0 reading equates to binary 0, while a V value equates to binary one.) If your clock told you to read the signal when the signal was at time t1, you would record that signal as a 0. While reading the signal at time t2 means you record the signal as a 1. If all devices are synchronized, they will transmit and receive the signal correctly. If two clocks are out of synchronization, you can end up with one person reading the signal at what it thinks is the correct time (t1), but is actually time t2, giving an incorrect value.

You would like every device in your network timed by the same clock source. Either timed directly or timing derived from the same device that provides clocking for the entire network. Since you derive timing from a "Master" clock, all the devices in the network will be synchronized.

Traditionally the wide area carrier provides a Stratum 1 clock source. 

Asterisk CLI Commands

Most Frequently General CLI Commands :

! - Execute a shell command
abort halt - Cancel a running halt
cdr status - Display the CDR status
feature show - Lists configured features
feature show channels - List status of feature channels
file convert - Convert audio file
group show channels - Display active channels with group(s)
help - Display help list, or specific help on a command
indication add - Add the given indication to the country
indication remove - Remove the given indication from the country
indication show - Display a list of all countries/indications
keys init - Initialize RSA key passcodes
keys show - Displays RSA key information
local show channels - List status of local channels
logger mute - Toggle logging output to a console
logger reload - Reopens the log files
logger rotate - Rotates and reopens the log files
logger show channels - List configured log channels
meetme - Execute a command on a conference or conferee
mixmonitor - Execute a MixMonitor command.
moh reload - Music On Hold
moh show classes - List MOH classes
moh show files - List MOH file-based classes
no debug channel (null)
originate - Originate a call
realtime load - Used to print out RealTime variables.
realtime update - Used to update RealTime variables.
restart gracefully - Restart Asterisk gracefully
restart now - Restart Asterisk immediately
restart when convenient - Restart Asterisk at empty call volume
sla show - Show status of Shared Line Appearances
soft hangup - Request a hangup on a given channel
stop gracefully - Gracefully shut down Asterisk
stop now - Shut down Asterisk immediately
stop when convenient - Shut down Asterisk at empty call volume
stun debug - Enable STUN debugging
stun debug off - Disable STUN debugging
udptl debug - Enable UDPTL debugging
udptl debug ip - Enable UDPTL debugging on IP
udptl debug off - Disable UDPTL debugging

AEL commands

ael debug contexts - Enable AEL contexts debug (does nothing)
ael debug macros - Enable AEL macros debug (does nothing)
ael debug read - Enable AEL read debug (does nothing)
ael debug tokens - Enable AEL tokens debug (does nothing)
ael nodebug - Disable AEL debug messages
ael reload - Reload AEL configuration


Agents commands

agent logoff - Sets an agent offline
agent show - Show status of agents
agent show online - Show all online agents

AGI commands

agi debug - Enable AGI debugging
agi debug off - Disable AGI debugging
agi dumphtml - Dumps a list of agi commands in html format
agi show- List AGI commands or specific help
dnsmgr reload - Reloads the DNS manager configuration
dnsmgr status - Display the DNS manager status
http show status - Display HTTP server status

Console commands

console active - Sets/displays active console
console answer - Answer an incoming console call
console autoanswer - Sets/displays autoanswer
console boost - Sets/displays mic boost in dB
console dial - Dial an extension on the console
console flash - Flash a call on the console
console hangup - Hangup a call on the console
console mute - Disable mic input
console send text - Send text to the remote device
console transfer - Transfer a call to a different extension
console unmute - Enable mic input

Core related commands

core clear profile - Clear profiling info
core set debug channel - Enable/disable debugging on a channel
core set debug - Set level of debug chattiness
core set debug off - Turns off debug chattiness
core set global - Set global dialplan variable
core set verbose - Set level of verboseness
core show applications - Shows registered dialplan applications
core show application - Describe a specific dialplan application
core show audio codecs - Displays a list of audio codecs
core show channels - Display information on channels
core show channel - Display information on a specific channel
core show channeltypes - List available channel types
core show channeltype - Give more details on that channel type
core show codecs - Displays a list of codecs
core show codec - Shows a specific codec
core show config mappings - Display config mappings (file names to config engines)
core show file formats - Displays file formats
core show file version - List versions of files used to build Asterisk
core show functions - Shows registered dialplan functions
core show function - Describe a specific dialplan function
core show globals - Show global dialplan variables
core show hints - Show dialplan hints
core show image codecs - Displays a list of image codecs
core show image formats - Displays image formats
core show license - Show the license(s) for this copy of Asterisk
core show profile - Display profiling info
core show switches - Show alternative switches
core show threads - Show running threads
core show translation - Display translation matrix
core show uptime - Show uptime information
core show version - Display version info
core show video codecs - Displays a list of video codecs
core show warranty - Show the warranty (if any) for this copy of Asterisk

Database commands

database del - Removes database key/value
database deltree - Removes database keytree/values
database get - Gets database value
database put - Adds/updates database value
database show - Shows database contents
database showkey - Shows database contents

Dialplan commands

dialplan add extension - Add new extension into context
dialplan add ignorepat - Add new ignore pattern
dialplan add include - Include context in other context
dialplan reload - Reload extensions and *only* extensions
dialplan remove extension - Remove a specified extension
dialplan remove ignorepat - Remove ignore pattern from context
dialplan remove include - Remove a specified include from context
dialplan save - Save dialplan
dialplan show - Show dialplan

DUNDI commands

dundi debug - Enable DUNDi debugging
dundi flush - Flush DUNDi cache
dundi lookup - Lookup a number in DUNDi
dundi no debug - Disable DUNDi debugging
dundi no store history - Disable DUNDi historic records
dundi precache - Precache a number in DUNDi
dundi query - Query a DUNDi EID
dundi show entityid - Display Global Entity ID
dundi show mappings - Show DUNDi mappings
dundi show peers - Show defined DUNDi peers
dundi show peer - Show info on a specific DUNDi peer
dundi show precache - Show DUNDi precache
dundi show requests - Show DUNDi requests
dundi show trans - Show active DUNDi transactions
dundi store history - Enable DUNDi historic records

GTalk & Jabber commands

gtalk reload - Enable Jabber debugging
gtalk show channels - Show GoogleTalk Channels
jabber debug - Enable Jabber debugging
jabber debug off - Disable Jabber debug
jabber reload - Enable Jabber debugging
jabber show connected - Show state of clients and components
jabber test - Shows roster, but is generally used for mog's debugging.

IAX2 commands

iax2 provision - Provision an IAX device
iax2 prune realtime - Prune a cached realtime lookup
iax2 reload - Reload IAX configuration
iax2 set debug - Enable IAX debugging
iax2 set debug jb - Enable IAX jitterbuffer debugging
iax2 set debug jb off - Disable IAX jitterbuffer debugging
iax2 set debug off - Disable IAX debugging
iax2 set debug trunk - Enable IAX trunk debugging
iax2 set debug trunk off - Disable IAX trunk debugging
iax2 show cache - Display IAX cached dialplan
iax2 show channels - List active IAX channels
iax2 show firmware - List available IAX firmwares
iax2 show netstats - List active IAX channel netstats
iax2 show peers - List defined IAX peers
iax2 show peer - Show details on specific IAX peer
iax2 show provisioning - Display iax provisioning
iax2 show registry - Display IAX registration status
iax2 show stats - Display IAX statistics
iax2 show threads - Display IAX helper thread info
iax2 show users - List defined IAX users
iax2 test losspct - Set IAX2 incoming frame loss percentage

Manager commands

manager show command - Show a manager interface command
manager show commands - List manager interface commands
manager show connected - List connected manager interface users
manager show eventq - List manager interface queued events
manager show users - List configured manager users
manager show user - Display information on a specific manager user

MGCP commands

mgcp audit endpoint - Audit specified MGCP endpoint
mgcp reload - Reload MGCP configuration
mgcp set debug - Enable MGCP debugging
mgcp set debug off - Disable MGCP debugging
mgcp show endpoints - List defined MGCP endpoints

Module management

module load - Load a module by name
module reload - Reload configuration
module show - List modules and info
module show like - List modules and info
module unload - Unload a module by name

PRI commands

pri debug span - Enables PRI debugging on a span
pri intense debug span - Enables REALLY INTENSE PRI debugging
pri no debug span - Disables PRI debugging on a span
pri set debug file - Sends PRI debug output to the specified file
pri show debug - Displays current PRI debug settings
pri show spans - Displays PRI Information
pri show span - Displays PRI Information
pri unset debug file - Ends PRI debug output to file

Queue commands

queue add member - Add a channel to a specified queue
queue remove member - Removes a channel from a specified queue
queue show - Show status of a specified queue
rtcp debug ip - Enable RTCP debugging on IP
rtcp debug - Enable RTCP debugging
rtcp debug off - Disable RTCP debugging
rtcp stats - Enable RTCP stats
rtcp stats off - Disable RTCP stats
rtp debug ip - Enable RTP debugging on IP
rtp debug - Enable RTP debugging
rtp debug off - Disable RTP debugging
say load - Set/show the say mode
show parkedcalls - Lists parked calls
show queue - Show information for target queue
show queues - Show the queues

SIP commands

sip history - Enable SIP history
sip history off - Disable SIP history
sip notify - Send a notify packet to a SIP peer
sip prune realtime - Prune cached Realtime object(s)
sip prune realtime peer - Prune cached Realtime peer(s)
sip prune realtime user - Prune cached Realtime user(s)
sip reload - Reload SIP configuration
sip set debug - Enable SIP debugging
sip set debug ip - Enable SIP debugging on IP
sip set debug off - Disable SIP debugging
sip set debug peer - Enable SIP debugging on Peername
sip show channels - List active SIP channels
sip show channel - Show detailed SIP channel info
sip show domains - List our local SIP domains.
sip show history - Show SIP dialog history
sip show inuse - List all inuse/limits
sip show objects - List all SIP object allocations
sip show peers - List defined SIP peers
sip show peer - Show details on specific SIP peer
sip show registry - List SIP registration status
sip show settings - Show SIP global settings
sip show subscriptions - List active SIP subscriptions
sip show users - List defined SIP users
sip show user - Show details on specific SIP user

Skinny commands

skinny reset - Reset Skinny device(s)
skinny set debug - Enable Skinny debugging
skinny set debug off - Disable Skinny debugging
skinny show devices - List defined Skinny devices
skinny show lines - List defined Skinny lines per device

Voicemail commands

voicemail show users - List defined voicemail boxes
voicemail show users for - List defined voicemail boxes for target context
voicemail show zones - List zone message formats

Zaptel commands

zap destroy channel - Destroys a channel
zap restart - Fully restart zaptel channels
zap show cadences - List cadences
zap show channels - Show active zapata channels
zap show channel - Show information on a channel
zap show status - Show all Zaptel cards status

Installation of Asterisk GUI

Asterisk GUI provides the functionality of web based system to manage the asterisk box.

Prerequisite :


CVS should be installed . Below is the download link for the same .

http://www.nongnu.org/cvs/

asterisk 1.4 - and all modules needed to compile and install asterisk 1.4

Preparations :

Go to /usr/src directory and download the latest asterisk-gui using the following link

svn checkout http://svn.digium.com/svn/asterisk-gui/trunk asterisk-gui

For installing Asterisk - GUI on Fedora and Redhat

directly do

yum install svn checkout http://svn.digium.com/svn/asterisk-gui/trunk asterisk-gui

For installing Asterisk - GUI on Ubuntu and Debian family

apt-get svn checkout http://svn.digium.com/svn/asterisk-gui/trunk asterisk-gui

This will provide you this kind of ouput

[root@lintel 1.4]# svn checkout http://svn.digium.com/svn/a
asterisk-gui/trunk asterisk-gui
A asterisk-gui/tools
A asterisk-gui/tools/zapscan
A asterisk-gui/tools/zapscan.c
A asterisk-gui/tools/Makefile
A asterisk-gui/LICENSE
A asterisk-gui/config
A asterisk-gui/config/meetme.html
A asterisk-gui/config/cfgappliance.html
A asterisk-gui/config/record.html
A asterisk-gui/config/zapata.html
A asterisk-gui/config/iax.html
A asterisk-gui/config/moh.html
A asterisk-gui/config/status.html
A asterisk-gui/config/scripts
A asterisk-gui/config/scripts/prototype.js
A asterisk-gui/config/scripts/tooltip.js
A asterisk-gui/config/scripts/rico.js
A asterisk-gui/config/scripts/astman.js
A asterisk-gui/config/jabber.html
A asterisk-gui/config/cfgadvanced.html
A asterisk-gui/config/trunks.html
A asterisk-gui/config/networking.html
A asterisk-gui/config/menus.html
A asterisk-gui/config/home.html
A asterisk-gui/config/homeapp.html
A asterisk-gui/config/sysinfo.html
A asterisk-gui/config/options.html
A asterisk-gui/config/sip.html
A asterisk-gui/config/setup.html
A asterisk-gui/config/cfgbasic.html
A asterisk-gui/config/users.html
A asterisk-gui/config/images
A asterisk-gui/config/images/split-v.png
A asterisk-gui/config/images/refresh.png
A asterisk-gui/config/images/loading.gif
A asterisk-gui/config/images/slice.png
A asterisk-gui/config/images/panel.png
A asterisk-gui/config/images/slice-v.png
A asterisk-gui/config/images/accordion-icon.gif
A asterisk-gui/config/images/adv.png
A asterisk-gui/config/images/favicon.ico
A asterisk-gui/config/images/tick.gif
A asterisk-gui/config/images/adv-v.png
A asterisk-gui/config/images/home-icon.png
A asterisk-gui/config/images/digiumlogo.gif
A asterisk-gui/config/images/iaxtel.jpg
A asterisk-gui/config/images/home.png
A asterisk-gui/config/images/dots.gif
A asterisk-gui/config/images/split.png
A asterisk-gui/config/numberplan.html
A asterisk-gui/config/backup.html
A asterisk-gui/config/queues.html
A asterisk-gui/config/jingle.html
A asterisk-gui/config/voicemail.html
A asterisk-gui/config/stylesheets
A asterisk-gui/config/stylesheets/rico.css
A asterisk-gui/config/stylesheets/schwing.css
A asterisk-gui/security.txt
A asterisk-gui/COPYING
A asterisk-gui/configs
A asterisk-gui/configs/providers.conf.sample
A asterisk-gui/gui_configs
A asterisk-gui/gui_configs/gui_bkpfiles.conf
A asterisk-gui/gui_configs/gui_custommenus.conf
A asterisk-gui/gui_configs/gui_sysinfo
A asterisk-gui/CREDITS
A asterisk-gui/Makefile
A asterisk-gui/README
Checked out revision 134.

Compiling and Installing

Enter this directory where you installed the Asterisk GUI

cd Asterisk-GUI (In the location of /usr/src )
# ./configure
# make

# make install

# make checkconfig

Configuration

Take the backup of the complete system before proceeding by going to the directroy and copy /etc/asterisk and execute the following command

cp -r /etc/asterisk /etc/asterisk.backup

There are two files which you should modify:

1) `manager.conf`

enabled = yes
webenabled = yes

We will have to add a new user to `manager.conf`:

[administrator]
secret = wrxiur (this is your password)
read = system,call,log,verbose,command,agent,user,config
write = system,call,log,verbose,command,agent,user,config

Bindaddress : 0.0.0.0

Uncomment the following two things mentioned above .

modify using the vim mode : vim /etc/asterisk/manager.conf

press i to insert or modify the things

Save it using shift + : + q

2) `http.conf`

enabled=yes
enablestatic=yes
bindaddr=0.0.0.0

Running the Asterisk - GUI

In order to load the asterisk-gui, asterisk must restart/reload. You can reload your Asterisk server from your CLI console by executing the command `reload`. You can use asterisk-gui from these addresses (192.168.0.202 is our Asterisk server IP address):

http://192.168.0.202:8088/asterisk/static/config/cfgbasic.html
http://192.168.0.202:8088/asterisk/static/config/cfgadvanced.html

Asterisk - Heartbeat High Availability Linux Solutions

This document provides the information about the high availability cluster solutions which we deployed for one of our South African customer .
Customer (ISP) wanted to setup the Voip network using asterisk . It was expecting a traffice of 2000 simulatneous calls . So it would require a cluster of asterisk servers .
Also it has to get incorporate the servers with the combination of OpenSer + A2billing + high availibility .
We evaluated Heartbeat for High Availability and installed it on the server .
What is Heartbeat ?
Your "cluster" is established via a "heartbeat" between two or more computers (nodes) generated by the software package of the same name.
The basic goal of the High Availability Linux project is to:
Provide a high-availability (clustering) solution for Linux which promotes reliability, availability, and serviceability (RAS) through a community development effort.

Heartbeat now ships as part of SUSE Linux, Mandriva Linux, Debian GNU/Linux, Ubuntu Linux, Red Flag Linux, and Gentoo Linux. Ultra Monkey, and several company's embedded systems are also based on it. Although this is called the Linux-HA project, the software is highly portable and runs on FreeBSD, Solaris, and OpenBSD, even on !MacOS/X from time to time.
There have been many articles and several chapters in books written on this project and software. See the PressRoom for more details.
We are now competitive with commercial systems similar to those described in D. H. Brown's 1998 or March 2000 analysis of RAS cluster features and functions. This release 2 series brings technologies and basic capabilities which match or exceed the capabilities of many commercial HA systems. We think you'll be surprised. An R2 getting started guide is available.
We include advanced integration with the DRBD real-time disk replication software, and also work well with the LVS (Linux Virtual Server) project. We expect to continue to collaborate with them in the future, since our goals are complementary.
We have a page of reference sites to provide a few real-life examples of how organizations both small and large use Heartbeat in production. Submissions for this page are actively encouraged.
Heartbeat is a leading implementor of the Open Cluster Framework (OCF) standard

Definitions
Node: An Instance that runs an OS
Resource: A service or facility you want to be highly-available
RA: Resource Agent
CRM:
More to come....
Getting Started
What you need:
At least two computers. You don't need to have identical hardware in both machines (or amount of memory, kernel, etc.).
One or more media to send the heartbeat packages (serial, USB or Ethernet cable(s)).
A Linux OS and the media between the 2 nodes configured and working.
High Availibility as good as it gets:
Avoiding a single point of failure is the whole idea of the setup. This also means it is advised to use more than one communications method between the nodes. It is also advised not to use only Ethernet cables or one single type of media, because in that case the mediastack would be a single point of failure.
The Setup
This quickstart will describe a full installation and configuration of Heartbeat 2 and some resources on Debian Unstable. It is a quickstart so we will configure a simple and common configuration. We will make an Apache 2 service highly available on a shared IP (Active/Passive). The configuration will contain monitors and starting the resources will be done using a group. Completing this document should give you a basic understanding of Heartbeat 2.
For simplicity, we use only one media, an Ethernet cable between the hosts:
The primary node: hostname = mars, ipaddr = 10.0.0.10
The slave node: hostname = venus, ipaddr = 10.0.0.20
The IP Apache listens to: 10.0.0.30
Installing Heartbeat
Heartbeat is available at:
Download Software
You can build it from source: tar -xvzf /path_to_downloaded_tarball/heartbeat-x.x.x
./ConfigureMe configure
make && make install
or use the RPM or .deb binaries available. If you use Gentoo, you can simply emerge it.
I used the .deb binaries for Debian so I added the following line to /etc/apt/sources.list
deb http://ftp.belnet.be/debian/ unstable main contrib non-free
and then
apt-get update
apt-get install heartbeat-2
Configuring Heartbeat
General Configuration Info
Configuring Heartbeat v2 is a little more tricky than Heartbeat v1, but Heartbeat v2 can also be used with a Heartbeat v1 configuration. If you would like to try out the v1 configuration first, read this.
There are 3 files you need to configure - you have to create these files:
HA v1
HA v2
Purpose
Notes
/etc/ha.d/authkeys
/etc/ha.d/authkeys
authenticate the nodes
the same in both versions
/etc/ha.d/ha.cf
/etc/ha.d/ha.cf
general Heartbeat configuration
HA v2: you have to define you want to use the CRM
/etc/ha.d/haresources
/var/lib/heartbeat/crm/cib.xml
configure the resources
another world
Configuring Authkeys
The authkeys file is used to authenticate the members of the clusters. There are three types of authentication methods available:
crc: Has as good as none security, and doesn't use much resources. Don't use this on real networks.
md5: Has security and doesn't use a lot of CPU resources
sha1: Best security currently available
In this example we are going to use md5. If you want to know more about authkeys, look at this document.
A sample of the /etc/ha.d/authkeys file could be: auth 1
1 md5 key-for-md5-any-text-you-want
Whatever index you put after the keyword auth must be found below in the keys listed in the file. If you put "auth 4", then there must be a "4 signaturetype" line in the list below.
The file permissions MUST be safe so do: chmod 600 /etc/ha.d/authkeys
Configuring ha.cf
#logfacility local7
#logfile /var/log/ha-log
#debugfile /var/log/ha-debug
use_logd on
udpport 694
keepalive 1 # 1 second
deadtime 10
initdead 80
bcast eth0
#serial /dev/ttyS0 #if you use serial
#baud 19200 #if you use serial
node linuxha1 linuxha2
crm yes
auto_failback yes
Log and debug explained:
If the logging daemon is used, logfile/debugfile/logfacility in this file are not meaningful any longer. You should check the config file for logging daemon (the default is /etc/logd.cf). Example in /usr/share/doc/heartbeat-2/ha_logd.cf.
If use_logd is not used, all log messages will be written to log files directly. The logging daemon is started/stopped in heartbeat script.
use_logd
Use the ha-logd, setting to "yes" recommended.
logfacility
Defines which syslog logging facility it should use for logging its messages. Ignored if use_logd is enabled.
logfile
All non-debug messages from Heartbeat will go into this file. Ignored if use_logd is enabled.
debugfile
Specifies the file Heartbeat will write debug messages to. Ignored if use_logd is enabled.
Time & Network:
udpport
Specifies which port Heartbeat will use for communication between nodes, default 694.
keepalive
Specifies the time between keepalive packets.
deadtime
Specifies how quickly Heartbeat should decide that a node in a cluster is dead.
initdead
Specifies how long to wait before a node is considered dead after things first come up (e.g. after reboot), to take into account bootup time and network initialization.
bcast
Specifies which interface(s) should be used to send keepalives on (if you want to use broadcasts).
Note that mcast and ucast can be used in place of bcast if desired.
Other:
node
Tells what machines are part of the cluster.
crm
Specifies whether Heartbeat should run v2-style. We set it to on
Note: When you want to use a Heartbeat 1 setup set crm to off.
I want to know more about the ha.cf file
Configuring Resources
/var/lib/heartbeat/crm/cib.xml: Basically this file specifies the services for the cluster and who the default owner is.
A simple example setup that explains a basic resource configuration can be found here: v2/Examples/Simple.
An example that explains some more advanced configuration is here: v2/Examples/Advanced.
And more advanced things are here: ClusterInformationBase/UserGuide.
Other configuration
Apache
You need to configure 2 things for our setup, these you can simply configure in the Apache config.
In Debian: /etc/apache2/apache2.conf
Define the IP that Apache has to listen to:
Listen 10.7.200.30:80
For the monitoring:
# Allow server status reports, with the URL of http://servername/server-status
# Change the ".your_domain.com" to match your domain to enable.
#

SetHandler server-status
Order allow,deny
Allow from all

DRBD
If you want to use DRBD instead of shared storage, then you need to configure it
OCF Scripts
We recommend that any resources agents you write be OCF resource agents.