Manual

From Ekiga
Jump to: navigation, search

This is the Ekiga manual. It is updated continuously. If some information is not enough clear for you, or if you think you have found an error or an obsolete information, feel free to contact us.

Contents

Introduction

Ekiga is a free Voice over Internet Protocol (or VoIP) IP telephony and video conferencing application for Linux, Unix-like (e.g. BSD or OpenSolaris), and Windows operating systems. You can place audio and video calls from PC-to-PC or PC-to-phone. SMS-style messaging is also supported.

It supports all major VoIP features like audio and video calling, call hold, call transfer, call forwarding, and instant messaging. It supports the best free video and audio codecs (with limited echo cancellation) for superior call quality. See features for a detailed list of features. Currently, Ekiga does not support:

  • IPv6
  • several communications in the same time
  • communication encryption
  • high definition video (the video is limited to 704x576).

See ToDo List for more information.

Ekiga has also been used in more exotic cases, such as sending fax over IP (in French).

Feel free to contact us to report a bug or make a suggestion regarding the application or this manual.


Ekiga is able to use modern Voice over IP protocols like SIP and H.323.

The Session Initiation Protocol (SIP) is a protocol developed by the IETF MMUSIC Working Group and proposed standard for initiating, modifying, and terminating an interactive user session that involves multimedia elements such as video, voice, instant messaging, online games, and virtual reality. In November 2000, SIP was accepted as a 3GPP signaling protocol and permanent element of the IMS architecture. It is one of the leading signalling protocols for Voice over IP.

H.323 was originally created to provide a mechanism for transporting multimedia applications over LANs, but it has rapidly evolved to address the growing needs of VoIP networks. One strength of H.323 was the relatively early availability of a set of standards, not only defining the basic call model, but also the supplementary services needed to address business communication expectations. H.323 was the first VoIP standard to adopt the IETF standard RTP to transport audio and video over IP networks. H.323 is based on the ISDN Q.931 protocol and is suited for interworking scenarios between IP and ISDN, respectively between IP and QSIG. A call model, similar to the ISDN call model, eases the introduction of IP Telephony into existing networks of ISDN based PBX systems.

Software compatibility

Ekiga is compatible with any software, device or router supporting SIP or H.323. It includes SwissVoice, CISCO, SNOM, Polycom, ... IP Phones, but also software like Windows Messenger, Netmeeting, SJPhone, Eyebeam, X-Lite, ... or also the Asterisk popular IPBX, as well as any other commercial or Open Source IPBX.

Ekiga is not compatible with Skype and will never be as long as their protocol stays proprietary. We do not think using closed protocols for communications is a good thing.

For more information about software compatibility see Ekiga Interoperability.

Minimum requirements

You need a microphone audio input into your computer. A headset is recommended to better prevent echo; however, a webcam with an internal microphone, or a separate microphone will also give good results.

A webcam is not mandatory. If you do not have it, you will still be able to see the other party.

If you are behind a very restrictive network access, be sure to have correctly configured the firewall and the NAT router/gateway (as shown at routers and firewalls section in this manual).

Complexity of the software

A VoIP program such as Ekiga (together with ptlib/opal libraries) is very complex because it uses many technologies and relies on the network. For example:

  • it uses SIP, H.323 (two highly complex protocols), various audio/video codecs, GTK, avahi, LDAP, jabber, X11/DirectX, audio and video devices, libnotify
  • it integrates with Evolution addressbook
  • it is multi-platform (Linux/Unix, Windows)
  • it relies on services on network (ekiga.net, STUN)
  • it is developed in tandem with two libraries: ptlib and opal.

External problems which might arise when using ekiga are bugs in libraries ekiga relies on, network itself (for ex. ekiga packets are changed by firewalls, or STUN issues), video device issues, interoperability (some SIP servers implement features partially or even contrary to the norm) etc.

Here is the number of source code lines for ekiga 4.0.0, as given by cloc:

  • ptlib: 168k lines of code, 45k comment lines, 47k blank lines
  • opal: 454k lines of code, 95k comment lines, 108k blank lines
  • ekiga (with directx directory removed): 56k lines of code, 20k comment lines, 19k blank lines

ptlib library contains audio/video devices and low-level functions, such as STUN.

opal library contains audio/video codecs, SIP, H.323 and related technologies (presence, H.239 etc.)

ekiga itself contains the graphical interface and related components (roster, neighbours, dialpad, LDAP integration, configuration etc.)

License

Ekiga is copyrighted by Damien Sandras (<dsandras@seconix.com>).

Ekiga is free software (as in both free speech and free beer) and is licensed under the GNU General Public License (GPL) (either version 2 of the License, or (at your option) any later version) with the special exception that you have permission to link or otherwise combine this program with the programs OPAL, OpenH323 and PTLIB, and distribute the combination, without applying the requirements of the GNU GPL to the OPAL and PTLIB programs, as long as you do follow the requirements of the GNU GPL for all the rest of the software thus combined.

You can find more information about GNU philosophy at http://www.gnu.org/philosophy.

Authors

Ekiga has been written by various people. You will find below the domain where they contribute:

Main author:

  • Damien Sandras: general coding, ekiga.net site

Current contributors (alphabetical order):

  • Eugen Dedu: testing, bug fixing, user support, release manager, documentation (wiki site)
  • Yannick Defais: testing, ekiga.net site, documentation (wiki site)
  • Julien Puydt: general coding, gstreamer backend, KDE and loudmouth support

Past important contributors (alphabetical order):

  • Matthias Schneider: video part (in ekiga and opal)
  • Jan Schampera: ekiga.net site
  • and many others.

The above contributors have also been involved in ptlib and opal librarires, which are however managed by:

  • Robert Jongbloed: full time ptlib/opal developer and author
  • Craig Southeren: general coding
  • and others.

The creator of the project, Damien Sandras, initiated the project on December 25, 2000, as a master thesis at the Université Catholique de Louvain in Belgium.

The logo/icon and the graphic art were drew by Andreas Kwiatkowski, see his website at http://www.kwiat.org.

The mascot was drawn by Carlos Pardo. The mascot is named Lumi. You can visit Carlos' website at http://www.m4de.com.

The code and the design of ekiga.org website was written by Fabian Deutsch. The old websites were done by Cédric Valcke.

Getting started (first time Assistant)

When starting Ekiga for the first time, the Configuration Assistant will launch automatically. The Configuration Assistant is a step-by-step wizard that will guide you through all the steps involved in creating the basic configuration you will need to use Ekiga. You should go through all of these steps properly, otherwise the assistant will re-appear (when it has not been completed) or Ekiga will not function correctly (if some of your answers have been inaccurate). You may run the Configuration Assistant at any time from the Edit menu.

Tip: All settings can be changed via the preferences window at anytime.

Configuration Assistant introduction

Capture-Ekiga Configuration Assistant (1 of 7).png

Throughout the entire configuration process, navigation is available at the bottom of the window. You will be able to navigate through the questions using the Back, Forward and Cancel buttons. If you hit Cancel during the setup, Ekiga will not be affected by your changes, and all entered information will be discarded.

This page welcomes you to the Configuration Assistant. There is nothing to change or edit here. Press the Forward button at the bottom of the window to start the configuration.

Define your identity

Capture-Ekiga Configuration Assistant (2 of 7).png

The Personal Information window is where you enter your personal details needed to use Ekiga. You should provide both your first name and last name. This information will be displayed on your partner screen when you call him. (Note that when people searches on ekiga.net directory, it is the name you put during account creation on ekiga.net which gets used.)

Register to a VoIP service

Capture-Ekiga Configuration Assistant (3 of 7).png

Ekiga.net is a free VoIP services platform provided to Ekiga users allowing PC-to-PC calling. If you want to call other users and to be callable yourself, you need a SIP address. You can get one from http://www.ekiga.net. Ekiga.net also offers additional services, like conference rooms and online white pages.

Follow the link given in the dialog to register for an account (if you do not already have one), and fill in your username and password. Then press Forward to continue.

Ekiga Call Out account (PC to phone)

Ekiga call out.png

Ekiga can be used with several Internet Telephony Service Providers. These providers will allow calls to real phones from your computer using Ekiga at competitive rates. There is no obligation for you to use a commercial provider, but if you need such service, we recommend using the default Ekiga provider.

If you do not want to use a commercial provider, check the box in front of "I do not want to sign up for the ekiga.net free service", then press Forward to continue.

Default provider

If you want to create an account and use it to call your friends and family using regular phones at competitive rates, click the "Get an Ekiga Call Out account" link.

Once the account has been created, you will receive a login and a password by e-mail. Enter these credentials in the dialog, and you'll be ready to call regular phones using Ekiga. Then press Forward to continue.

See diamondcard section for more information.

Select your connection type

Emblem-important.png The connection type page of the assistant is a bit confusing and error-prone. As such, it is not available anymore starting with Ekiga 4.2.0.

Capture-Ekiga Configuration Assistant (4 of 7).png

Ekiga supports several audio and video codecs. It includes codecs with excellent quality as well as codecs with medium to good quality. The higher the quality of a codec, the more bandwidth it requires. Moreover, video codecs can adapt their quality to the available bandwidth. This option is necessary in the initial configuration of Ekiga so that it chooses the optimal codec suited to your network connection and so that it adjusts the video quality settings.

If your connection type is not mentioned in the list you should select the one closest to your network connection and adjust Ekiga manually with the preferences window (codecs section) later on. This setting will help Ekiga select the optimal codecs to suit your available bandwidth.

Select your audio devices

Emblem-important.png The audio devices page of the assistant is not really useful, since by default Ekiga selects the right device. As such, it is not available anymore starting with Ekiga 4.2.0.

Capture-Ekiga Configuration Assistant (5 of 7).png

Audio device configuration is dependent on the operating system on which Ekiga is running, and different operating systems will configure audio devices in different ways.

Ekiga will attempt to automatically detect audio hardware (e.g. a USB headset, or a webcam with a built-in mic) plugged into your computer. These audio devices will then be listed here, allowing you to select them for your calls.

The audio ringing device (allowing you to hear a ringtone for incoming calls) is usually set to the internal sound card, under the name Default.

The audio output device outputs the incoming sound stream during a call. You would typically select the device that your headphones or speakers are connected to. Default is a good choice for your internal sound card.

The audio input device is where your microphone is connected to. Default is also a good choice for your internal sound card. These settings might be the same as the settings for the audio output device if you have only one soundcard, but it's also possible for the audio input to be set to another device, for example, the internal microphone on your webcam.

Select your video input device

Emblem-important.png The video device page of the assistant is not really useful, since by default Ekiga selects the right device. As such, it is not available anymore starting with Ekiga 4.2.0.

Capture-Ekiga Configuration Assistant (6 of 7).png

Select a video plugin and video input device from the list. It can be Video4Linux2 to manage webcams, or any other choice depending on the operating system on which Ekiga is running.

This step is optional and is relevant for users with video devices (e.g. webcams) only. If you do not have any video devices you may skip this page: Ekiga works fine for audio calls only.

Confirm your setup

Capture-Ekiga Configuration Assistant (7 of 7).png

Configuration of Ekiga is now complete. The last window displays a summary of the settings you have chosen. Verify that your settings are correct; if something is incorrect, you may use the Back button in the lower right hand corner of the window to go to any page of the assistant to correct the mistake.

If all is well, press the Apply button to save the configuration. The assistant will close, and the main window of Ekiga will now appear.

Capture-Ekiga.png

Remember, all settings can be changed via the preferences window at anytime.

Test your setup

It is generally recommended that you test your setup after having completed the Configuration Assistant.

Test your camera (video input device)

Click on the video camera icon (on upper left of Ekiga window). A new window will appear: if you see your face then the camera works well with Ekiga. Otherwise make sure that your camera is working by testing it with another program which uses camera, and check Troubleshooting page. If it still does not work, contact us.

Test your audio device

TODO: input and output

Test audio and video call with ekiga.net

Capture-Ekiga-1.png

If you registered a SIP address with http://www.ekiga.net, you can call a dedicated echo test service by using the address sip:500@ekiga.net.

You should hear a recorded message saying "You're about to enter an echo test. In this mode everything you say will be repeated back to you just as soon as is it received. The purpose of this test is to give you an audible sense of the latency between you and the machine that is running the echo test application. You may end the test by hanging up or pressing the pound key".

By speaking into your mic, you should hear your voice repeated back to you after a short delay. If the test was successful, you can continue to the next page of this manual. If the test was unsuccessful (e.g. you cannot hear your voice repeated back), then you should restart the Configuration Assistant and test your configuration again until you have a setup that works for you.

Note that the echo test accepts only some video and audio codecs, cf. fun numbers page, so you have to ensure that they are checked on in your Ekiga preferences.

You might also be interested by free fun numbers.

Test audio and video call with someone else

TODO: ...

Managing accounts

General information about accounts

An account to a VoIP service provider is not mandatory for using Ekiga (you can use the IP address to call, or to use network neighbours, as shown later in the manual), but having at least one account will greatly enhance the Ekiga softphone experience.

VoIP services can extend Ekiga's feature set in many useful ways:

  • SIP addressing: If you want to call other users and to be callable yourself, you're best off with a SIP address, which is a human-readable address similar in appearance to an email address (e.g. sip:me@provider.net). Your personal SIP address is used by other users to call you. Similarly, you can use the SIP address of your friends and family members to call them. For example, sip:dsandras@ekiga.net is the protocol & address used to call the author of Ekiga.
  • Searchable addressbook: most providers maintain a database registering their users, and may also allow searching through it. Ekiga is able search remote addressbooks if they use the LDAP technology.
  • Conference calls: this service is in charge of collecting all audio (and possibly video) flux and mixing them before sending them back to the participants. The free PBX Asterisk can provide this feature too.
  • Peering: this is an agreement between VoIP service providers which enables the users of one service to call users of another. This is usually implemented by dialing a special prefix number, followed by the number of the recipient (on the 'other' service).
  • PC-to-Phone and Phone-to-PC calls: commercial providers may provide a bridge to PSTN/cellphone networks. The service routes the call to those networks, typically charging you for the operation.
  • Voice mail: if you're not available, a caller may leave you a voice message. Ekiga tells you how many messages you have waiting. The free PBX Asterisk can provide this feature too.
  • etc.

You can register with as many VoIP service providers as you want using Ekiga.

You'll notice that the Configuration Assistant recommends two VoIP services to you during setup:

  • Ekiga.net is a free VoIP service for PC-to-PC communication. Ekiga.net gives you your own SIP address, a searchable addressbook, conference calls, and the ability to contact friends using other service providers with peering or ENUM.
  • Ekiga Call Out is a commercial VoIP service for PC-to-Phone and Phone-to-PC communication. It also allows you to send SMS messages from PC-to-Phone.

Information about addresses

SIP addresses

SIP addresses are formatted as such: sip:user@[host[:port]]

This permits you to call the given user or extension on the specified SIP service provider: sip:jonita@ekiga.net

H.323 addresses

H.323 addresses are formatted as such: h323:[user@][host[:port]]

This permits you to:

  • Call a given host on a port different from the default port 1720: h323:seconix.com:1740
  • Call a given user using their respective alias if registered to a gatekeeper: h323:jonita
  • Call a given phone number if you are registered to a gatekeeper for a PC-To-Phone provider, or if that user has an ENUM record associated to an H.323 URL: h323:003210111222
  • Call a given user using their alias through a specific gateway or proxy: h323:jonita@gateway.seconix.com
  • Call an MCU and join a specific conference room: h323:myfriendsroom@mcu.seconix.com

CALLTO addresses

Callto addresses are formatted as such: callto:[user@][host[:port]]

Callto addresses and H.323 addresses are formatted exactly the same except callto addresses also support ILS addressbook server lookups through callto addresses of the type: callto:ils_server/user_mail.

For example, calling callto:ils.seconix.com/joe.user@somedomain.com will look for the user with the joe.user@somedomain.com email address on the ILS server ils.seconix.com and proceed to initiate a call.

Account window

Capture-Accounts.png

You can open the accounts window by selecting Edit -> Accounts. This window allows you to add and register with SIP, H.323 and other types of accounts or VoIP services.

An account contains the user login and password details to register with to the account or VoIP service. These services can be an Internet Telephony service provider (like Ekiga.net), or an IPBX (like CISCO, Nortel, or Asterisk).

Automated registration

Ekiga features automated registration with your service providers. If you choose to use the Ekiga.net or Ekiga Call Out service while in the Configuration Assistant, Ekiga will try to automatically register with them at startup. If later you want to add another VoIP service account, you'll have the option for Ekiga to automatically register with it while creating the account (tick the Enable Account box).

Manual registration

At any time you can manually register and unregister with a VoIP service: in the Accounts Window (Edit -> Accounts), you can tick and untick the box in front of the account name to register and unregister the service respectively.

Add an Ekiga.net account

Capture-Edit account-2.png

Add an Ekiga Call Out account

Capture-Edit account-3.png

Add a SIP account

Capture-Edit account.png

To add a SIP account, simply click on Account -> Add a SIP Account. A dialog will appear and allows you to enter several parameters:

  • Name: the account name goes here. This should be descriptive name, especially if you have accounts with several service providers.
  • Registrar: the registrar with which you want to register. This is usually an IP address or a host name that will be given to you by your Internet Telephony Service Provider, or by your administrator if you are trying to register to a SIP IPBX.
  • User: this is your account username.
  • Authentication User: if the authentication user is different from the username you used above, enter it here. In this scenario, the User field will be used to control the outgoing identity for the account you are adding, while the Authentication User will be used during the authentication phase.
  • Password: this is your account password.
  • Timeout: The timeout after which the registration should be updated. 3600 is the default setting.

Tip:

Ekiga will do a best guess in determining the identity that will be used when calling out. Sometimes, you will need to force that identity. You can do this by specifying the identity in the User field. For example: dsandras@ekiga.net to force dsandras@ekiga.net to be used as outgoing identity for that account.

Add an H.323 account

Capture-Edit account-4.png

To add a H.323 account, simply click on Account -> Add a H.323 Account. A dialog will appear and allow you to enter several parameters. The meaning of the parameters are similar to SIP account, see previous section.

Add an XMPP account

To add an XMPP account, simply click on Account -> Add a Jabber/XMPP Account. A dialog will appear and allow you to enter the connection parameters.

For this to work, Ekiga should have been built with XMPP support (--enable-loudmouth, which by default it is disabled).

Default account

Emblem-important.png This section could be wrong, it needs review

Usually, when calling someone, you type the SIP address which contains the registrar of one of your VoIP account, e.g. sip:dsandras@ekiga.net may refer to your account Ekiga.net as you can see at the end of this particular address. Ekiga will choose which account to use depending on the end of the SIP address if it is the same as one of the registrar you have in your account list to place the call.

The default account is the one used when you type or dial a SIP address without the end of the SIP address (what is on the right of @), or the account used if you call a sip address which do not refer to any of your registrar in your account list. It is your own address at this default account which will appear on the SIP client of your friend as the source of the call.

In the Accounts Window (Edit → Accounts), the bold font represents the Default Account. You can change the default account simply by highlighting the account you want, then clicking the "Default" button on the right side.

Gnome-status.png If your default account is Ekiga.net, for example, you do not need to add "@ekiga.net" to the sip address or number you are calling.

Managing contacts

The contact list allows you to contact your friends easy.

EkigaContactsRoster.png

Note that the lines of the contacts added to the main contact list are automatically monitored.

Monitoring lines.png

Add a contact to your contact list (roster)

EkigaAddContact.png

To add a contact to your Ekiga roster, click on Chat -> Add Contact. The Add to local roster window will appear, with fields to supply information for the contact's name and address. Contacts can also be added from a contextual menu by right-clicking in the roster, and selecting New contact.

If you do not precise the host part, e.g. you add jim, not jim@ekiga.net, then in the roster right-clicking on the contact allows you to choose which account to use for that call or message sending. This is sometimes useful, as shown in the following.

"In the special case of phone numbers, the phone number can be used with any of many VOIP providers, including ekiga dialout (diamondcard.us). Like a long distance company, your VoIP provider can change often, and you can have more than one. For instance, I currently use one company for US calls, and ekiga dialout for all other countries. Furthermore, there may be other future global addressing schemes that could be used with multiple providers. For instance, at some point Skype will have to give in and at least allow gateways to SIP. Then the Skype address would be useful without a specific domain, in order to allow to chose among gateway providers." [1]

Remove a contact from your contact list (roster)

To remove a contact from your Ekiga roster, first select the contact as visible in the roster. Then click on Chat -> Contact -> Remove. The contact is removed from your roster immediately. Contacts can also be removed from a contextual menu by right-clicking on the relevant contact in the roster.

Group contacts in your contact list (roster)

You can sort your contacts visible in the local roster into pre-defined groups, such as Friends or Work; this allows for example to make visible only one of the groups (e.g. Work when you are at work). You can also create custom group names to sort your contacts into, for example First Level Tech Support.

To change the group a contact belongs to, first right-click on the contact as visible in the local roster, then click on Edit from the contextual menu that appears and tick the group you wish the contact to be sorted into. If you wish to add a custom group, enter your custom group name here, and click Add. Click OK to finish.

Network neighbours

Avahi

Network neighbours is a special group in the roster, called Neighbours, which automatically discovers and shows all ekiga users from your LAN. It is updated each time a users connects or disconnets from your LAN. Neighbours group is visible, at the bottom of the roster, only if there is at least one ekiga user in your LAN. It is available only if ekiga has been built with support for it.

This feature uses the zeroconf technology (called sometimes Bonjour or avahi or rendezvous). This feature assumes you have a local mDNSResponder daemon running on your computer, which is the case for current GNU/Linux machines.

Gnome-status.png Windows version of ekiga does not support currently this technology, see bug #557040 (so your neighbour tab will not be shown).


Managing my contacts with the Address Book

Ekiga Address Book

The Address Book is a feature which allows you to find users to call and/or to save locally your list of persons that you call on a regular basis. It respectively loads the list of users from the LDAP directory and will store locally their addresses.

Basics of the Address Book

Addressbook-24.png To open the Address Book window, select Chat → Address Book.

To your left there will be a list dialog showing the Servers you have added to the list as well as a list of local Address Books. The defaults are the Ekiga.net white pages, the personal address book from Novell Evolution (http://www.novell.com/products/evolution) and the call history.

  • Ekiga is able to use several types of address books, allowing to search for remote contacts, and bookmark local contacts. The most common address book type is the LDAP directory where you can find information about registered users. Ekiga is able to browse any LDAP directory and use a specific attribute as calling URL.
Gnome-status.png For example, you could have an LDAP directory in your company, with a specific attribute containing the local extensions of all your colleagues. Ekiga is able to use such an LDAP directory. Simply select in Address Book → Add an LDAP Address Book, and fill the form.

Search a contact in the Local Address Book

EkigaAddressBook1.png

To view address books, select Chat -> Address Book and the Address Book window should appear. In the left-hand pane there will be a list of local address books, as well as any online (LDAP) address books. The default address books are the Ekiga.net online directory, and the Personal address book shared from Novell Evolution if you use the GNOME desktop, or, the Personal address book shared from KAddressBook if you use the KDE desktop.

To search for a user in the local address book, simply click to highlight it in the left hand pane, then enter the user's name in the Search Filter field and click the Find button.

You can place a call to a user by double-clicking on their name in the search results window.

You can also place a cell phone call to users in the local address book, if the user information was originally entered using Novell Evolution.

Add a new contact to your local address book

To add a contact to the Ekiga local address book, simply select the address book, then select Action -> New Contact. The New contact window will appear and you may now enter the user's name and VoIP address, as well as any other settings. Click OK to finish. If you are running Novell Evolution or KAddressBook, you'll notice the contact has been updated in each respective application's Personal address book as well.

Note that you can only add contacts to local address books in Ekiga: adding contacts to LDAP address books from within Ekiga is not supported.

Remove a contact from your local address book

To remove a contact from a local address book, highlight the contact, then select Action -> Remove. The contact can also be removed by right-clicking on the contact, then selecting Remove from the contextual menu that appears.

Additionally, if you remove the contact from either the Novell Evolution or KDEAddressBook applications, then this will also remove the contact from Ekiga's local address book.

Note that you can only remove contacts from local address books in Ekiga: removing contacts from LDAP address books from within Ekiga is not supported.

Search in a remote Address Book (LDAP)

EkigaLDAPAddressBook1.png

Ekiga is able to connect to online address books, allowing you to search for contacts in a remote directory. The most common online address book type is the LDAP directory. Ekiga is able to search an LDAP directory and use a specific attribute as a calling address (i.e. VoIP URI). For example, you could connect to a an LDAP directory provided from within your own company, and use a specific attribute containing the local extensions of all your colleagues.

You can use the Search Filter field to search for contact names and call addresses in an LDAP directory. A limited number of results corresponding to your search are returned.

Add a remote address Book (LDAP)

Create LDAP directory.png

To connect to an LDAP directory, open the address book window, and click on Address Book -> Add an LDAP Address Book.

Enter the book name and the various parameters and select ’OK’ and the new address book should now appear in the address books list.

  • for the filter template, a "$" is replaced by the search string, whatever was entered in the search dialog box. No other substitutions are performed.
  • for custom attributes, the value must be either a URL or a simple value. If it's a simple value, a "sip:" URL prefix will be tacked on before displaying it.
Gnome-status.png If you do not know what parameters to use for a remote LDAP address book, please ask them to your administrator.


Remove a remote address Book (LDAP)

You can remove an LDAP address books by first highlighting the address book in the left-hand pane of the address book window, then clicking Action -> Remove addressbook. You can also right-click on the address book you wish to remove, and select Remove addressbook from the contextual menu that appears.

Search in the Ekiga.net Directory

The Ekiga.net address book is an LDAP directory pre-configured in Ekiga, allowing convenient searches for other Ekiga.net users. You can use the Search Filter field to search for contact names and call addresses, and a limited number of results corresponding to your search are returned.

Add a contact to your contact list from the Ekiga.net Directory

You can easily add a contact to your local roster from the Ekiga.net directory, or any other LDAP address book. Simply highlight the user, and click on Action -> Add to local roster. You can also right-click on the contact, and select Add to local roster from the contextual menu that appears.

Setting your status

EkigaStatusSetting.png

You can set a status message in Ekiga that advertises your presence to your contacts. Ekiga features three preset status messages, and within each one of these presets, custom status messages can be created.

The three preset status messages are:

  • Available
  • Away
  • Busy

Simply click on the drop-down status message list to select a preset status. Note that you may be called in any of these statuses; they are used simply to inform the other users about your wish.

Custom messages

To define a custom message, click on the drop-down status message list in the main Ekiga window, and select "Custom message..." under the preset status message category you wish to use. In the pop-up window that appears, enter your custom message, and click OK to apply.

To delete a custom message, click on the drop-down status message list in the main Ekiga window, select Clear, and select the custom message you wish to delete. Click Delete to apply.

Calling (audio/video)

Answer calls

When a call arrives, Ekiga rings and displays a notification window in the systray allowing you to accept or reject the call. If notifications are not available in your system (which is the case for Windows systems), then the call window is shown instead allowing you to accept or reject the call.

Some systems have broken notifications, for example they do not show the whole text in case of long text, or they inform that they support notifications but they do not. In this case, when a call arrives, you have to manually open the call window and accept or reject the call from there.

FIXME Furthermore Ekiga offers REPLACE_two_REPLACE modes that override this behaviour: Do Not Disturb, and Forward. They can be activated from the the REPLACE._Main Window_REPLACE

Call a contact

Ekiga supports several actions which can be performed when in a call. These actions enable you to control active sessions.

Select an account for a call

Call on internet (PC to PC)

If you want to call other users and to be callable, you usually need a SIP address. You can get a SIP address from http://www.ekiga.net as described above.

The SIP address can be used by other users to call you. Similarly, you can use the SIP address of your friends and family to call them. You can for example use sip:dsandras@ekiga.net to call the author of Ekiga.

You can use the online address book of Ekiga to find the SIP addresses of other Ekiga users. It is of course possible to call users who are using another provider than ekiga.net (see also Peering and Enum). You can actually call any user using SIP software or hardware, and registered to any public SIP provider.

If you know the URI address of the party that you wish to call, you may enter that URI into the sip: input box at the top of the screen and press the Connect button; eg: sip:foo@ekiga.net and pressing the Connect button would call the user at that address. With the default setup, you can simply type sip:foo to call user foo@ekiga.net.

Tip | Ekiga also supports H.323 and as such can call any H.323 software or hardware. Please refer to the section REPLACE_"Understanding VoIP addresses"_REPLACE to learn more about the various types of URIs that can be used to call remote H.323 and SIP users.

Calling IP to IP directly

Ekiga does not necessarily require a SIP account or STUN (network detection) in order to work. You can call using the IP address of your partner like this:

sip:dummy_name@85.17.189.168

or, if the other user does not use the default SIP port (5060):

sip:dummy_name@85.17.189.168:30000

This is useful for debugging purposes when your partner is in the same network as you.

Call out (PC to phone)

Ekiga allows you to call real phones. You simply have to register an account to a Internet Telephony Service Provider. You do not need any specific hardware to be able to do PC-to-Phone calls: a simple soundcard is enough. Using a headset to avoid echo problems is however highly recommended.

Ekiga can be used with several Internet Telephony Service Providers. Those providers will allow calling real phones from your computer using Ekiga at interesting rates. We are recommending you to use the default Ekiga provider.

Default provider

The default provider is Diamondcard Worldwide Communication Service, which offers these rates. When signing up for a DiamondCard account, a small amount of the subscription is given back to the Ekiga project.

If you want to create such an account and use it to call your friends and family using regular phones at interesting rates, go in the Edit menu, and select Configuration Assistant menu item. Afterwards, press Continue until the Ekiga Call Out Account:

Capture-PC-To-Phone Settings.png

Once the account has been created, you will receive a login and a password by e-mail. Simply enter them in the dialog, resume the Configuration Assistant until the last step, press Apply, and you are ready to call regular phones using Ekiga.

Dial a number

To dial a number, simply add "00" followed by the country code, and by your number. For example, sip:003210111111 to call number 10111111 in Belgium.

If Ekiga.NET or the PC-To-Phone account are not your default account, you will have to enter the full URL to be able to dial, without the leading "00": sip:3210111111@eugw.ast.diamondcard.us.

Send SMS
Other providers

See List of PC to phone providers for a list of alternative providers.

You can use several providers at the same time.

Call in (phone to PC)

Ekiga can be used to receive incoming calls from regular phones.

Default provider

To allow this, you can simply login to your PC-To-Phone account using the Tools menu as described above, and buy a phone number in the country of your choice. Ekiga will ring when people will call that phone number.

Other providers

You can actually use any H.323 or SIP ITSP provider, including your own PBX at work. However we recommend using the integrated provider.

End a call

An active call can be ended by selecting Chat -> Hang Up

Hold a call

You can hold an active call by selecting Chat -> Hold Call. This effectively pauses video and audio transmission. To resume the call select Chat -> Retrieve Call. Video and audio transmission will then resume.

Mute audio during a call

To mute audio during an active call, select Chat -> Suspend Audio. Audio will cease to be sent, but video transmission will continue. To unmute audio, select Chat -> Resume Audio.

Mute video during a call

To mute video during an active call, select Chat -> Suspend Video. Video will cease to be sent, but audio transmission will continue. To unmute video, select Chat -> Resume Video.

Call auto-answering

Starting with version 4.0.0, ekiga can auto-answer calls. When the "Automatically answer incoming calls" ckeck box in Preferences->General->CallOptions is enabled, incoming calls are immediately automatically answered. Note that for security reasons Ekiga does not (yet) support call auto-answering when a specific SIP tag appears in the incoming packet.

Forward calls

Ekiga has the ability to forward incoming calls to another host. Ekiga allows:

  • to forward all incoming calls to a specified URI
  • to automatically forward calls when you do not answer after a configurable amount of time, or when you are busy.

Call Forwarding can be configured through the preferences window. Notice that you need to specify an URI where to forward calls in the preferences to be able to activate that option. Open the preferences window by choosing Edit -> Preferences in the main window and select Call Options on the left. You will now see the appropriate section. It contains three checkboxes for the three cases described above. The IP address/hostname of the host the calls shall be forwarded to can be configured separate in SIP Settings for SIP and accordingly in H323 Settings for H323.

Transfer a call

During a call, you can transfer the remote user to another SIP/H.323/CALLTO URI by using the appropriate menu entry in the Call menu or by double-clicking on an user in your contact list, or in the call history. This is similar to a secretary who receives a call, and after some discussion transfers the call to the right person in the organisation. Note that Ekiga does not support to ask permission of the target address to accept the call transfer.

Message Waiting Indications

Call history

The Call history window stores information (date, duration, URI, Remote user) about all outgoing and incoming calls. They are divided into three groups "Received calls", "Placed calls" and "Unanswered calls".

Received calls contains all incoming calls which were accepted by Ekiga. NEW_It is preceded by this icon SCREENSHOT GREEN ARROW RIGHT_NEW

Placed calls keeps track of all attempts - successful or not - to call another user.NEW_It is preceded by this icon SCREENSHOT GREEN ARROW LEFT_NEW


Unanswered calls shows incoming calls which timed out or were rejected (if Do Not Disturb is enabled, for instance) by Ekiga.NEW_It is preceded by this icon SCREENSHOT GREY ARROW RIGHT_NEW


Tip | REPLACE_Right click_REPLACE on a row in the Calls History will NEW_allow to_NEW call back the selected user, or transfer any active call to that userNEW_, or add the selected contact to the roster_NEW.

CANDIDATEFORSUPPRESSION_Notice that you can also drag and drop entries from the Calls History into the Address Book to store contact information.

This information can be accessed by opening REPLACE_View_REPLACE->Calls History and by switching between the three tabs.

Double-clicking on a row in the Calls History will call back the selected user or transfer any active call to that user.

Missed calls

Dialpad

TODO: Speak about DTMF.

Monitor a call

EkigaCallStats1.png

The status bar (visible at the bottom of the main Ekiga window) shows information about audio and video bandwidth, and the video FPS (frames per second) achieved during an active call.

The status bar uses the format: A:a/b V:c/d FPS:e/f

  • a/b displays transmitted/received audio bandwidth in kB/s
  • c/d displays transmitted/received video bandwidth in kB/s
  • e/f displays transmitted/received video frames per second

To view network traffic statistics during an active call, you can hover the mouse pointer over the status bar to display a pop-up window:

EkigaCallStats2.png


Here is a description of each parameter:

  • Lost packets: The percentage of lost packets, i.e. packets from the remote user that you did not receive. Too high packet loss during reception can result in voice and/or video distortion, and is usually caused by a bad network provider or by settings requiring excessive bandwidth.
  • Late packets: The percentage of late packets, i.e. packets from the remote user that you received but too late to be processed.
  • Out of order packets: An out of order packet is a packet that it is sent before another packet, but it arrives after the other packet. The percentage shown is the number of out of order audio and video packets divided by the total number of audio and video packets.
  • Jitter buffer: The Jitter buffer is the buffer where received sound packets are accumulated. When the buffer is full, then the sound is played. If your network is of insufficient quality, then you need a big jitter buffer - which results in a larger delay before sound is played back.
  • Resolution: The resolution is the video window size in pixels (X by Y) of the transmitted video (TX), and the received video (RX).

Sending instant messages (chatting)

EkigaChatWindow.png

Ekiga allows you to send instant messages to your SIP contacts. Chat messages are not stored on any server, so in order for chat to work your partner must be connected when chatting.

To compose a text message to a user, first highlight the user as visible in your contacts roster, then on the Ekiga menu bar goto Chat -> Contact -> Message. The chat window will appear and allow you to perform a text conversation with the selected remote user.

To send the message simply type Return. To insert a new line inside the message, type Shift-Return.

You can also open the chat window from a contextual menu by right-clicking on the user in your roster, and selecting Message.

Not working anymore (???): You can also exchange text messages with H.323 Ekiga users, but only while being in a call. To do this, simply click on the new tab icon, and a new tab will automatically be created allowing a conversation with the user you are on a call with. To be checked: H.323 text chat however only works from Ekiga to Ekiga.

Ekiga allows to do some simple formatting of the text (italic, bold, underline) and use some emoticons, accessible from within an active chat window itself.

Configuration

Ekiga supports several audio and video codecs. It includes codecs with excellent quality, as well as codecs with medium to good quality. Generally, the higher the quality of a codec, the more bandwidth or CPU power it requires. The first time the Configuration Assistant is run during the initial setup of Ekiga, an optimal selection of the video parameters (size and maximum video transmitted bitrate) is automatically made based on your network connection.

Adjust audio

Choosing the right audio device

EkigaAudioDevices-1.png

If you wish to change the audio input or output device set by the Configuration Assistant, open the Ekiga preferences window with Edit -> Preferences -> Audio -> Devices. Ekiga will attempt to automatically detect audio hardware (e.g. a USB headset, or a webcam with a built-in mic) plugged into your computer. These audio devices will then be listed here, allowing you to select them for your calls.

The audio Ringing Device (allowing you to hear a ringtone for incoming calls) is usually set to the internal sound card, under the name Default.

The audio Output device outputs the incoming sound stream during a call. You would typically select the device that your headphones or speakers are connected to. Default is a good choice for your internal sound card.

The reason to have different output and ringing devices is that you might be interested to have headphones for output and external speakers for ringing, so that you hear incoming calls even when you are far from the computer.

The audio Input device is where your microphone is connected to. Default is also a good choice for your internal sound card. These settings might be the same as the settings for the audio output device if you have only one soundcard, but it's also possible for the audio input to be set to another device, for example, the internal microphone on your webcam.

See OSS4 appendix for using OSS4 as audio device.

Adjust audio input and output volume

EkigaAudioIO-1.png

Audio input (microphone) and output (speaker or headphone) levels may be set when a call is in progress. To adjust audio levels, first click on the speaker icon: in the window that appears, you may adjust levels for your microphone and speakers/headphones independently:

EkigaAudioIO-2.png

For the best audio quality, we recommend the use of a microphone/headphone combination.

Select the best quality/bandwidth ratio for audio

Capture-Ekiga Preferences.png

The audio codecs table in the Ekiga preferences window allows you to enable, disable, and reorder audio codecs. Each codec has strong and weak points. For example, the G.711 codec (also known as PCMU/PCMA) will give you very good voice quality, but it will also use the most bandwidth; the Speex codec on the other hand will give you average voice quality, but with very low bandwidth usage. Note that there are two versions of Speex, one with 16kHz and another one with 8kHz, the former is more accurate but consumes more network bandwidth.

When you reorder codecs, you are reordering the local capabilities table. During a communication, only one audio codec is used, for both directions. The audio codec used is the first active codec on receiver which is active on sender.

You can force the use of a specific codec by selecting it and disabling all other codecs, but this will result in failed calls if the remote user has not enabled that specific codec. The best approach is to put your preferred codecs at the top of the list, and to disable the codecs that you do not want to use for sending and receiving audio.

Other parameters

You can the maximum delay to wait before playing the sound buffers that you have received using the jitter buffer adjustment. If there is too much packets loss, the delay required to have received all packets could be so important that it will exceed the jitter buffer. In such a case, the sound you are receiving will be of bad quality. A solution to that problem would be to increase the maximum limit of the jitter buffer to say one second, resulting in a big delay but an improved voice quality.

Gnome-status.png The jitter buffer will adapt itself to the lowest delay allowing for optimum transmission. A bad voice quality in reception is not due to a too high jitter buffer value, but to bad internet connection quality.

Echo cancellation will only work if you use the same sound device for in and out audio, e.g. echo cancellation won't work if you use the microphone on your webcam and the output sound from your soundcard (PCI). The reason is that the echo cancellation mechanism needs to sync the in and out sounds and this cannot be done properly using two different drivers.

Adjust video

Remember that a camera is not mandatory to use Ekiga.

Every camera supported by the Linux kernel and compatible with the Video4Linux/Video4Linux2 APIs (Philips webcams, Creative webcams, and many others...) can be used with Ekiga.

The supported video settings are found in appendix.

Choosing the right video device

EkigaVideoDevices-1.png

If you wish to change the video input device set by the Configuration Assistant, open the Ekiga preferences window with Edit -> Preferences -> Video -> Devices. Ekiga will attempt to automatically detect video hardware plugged into your computer. These video devices will then be listed here, allowing you to select them for your calls.

You can also adjust other settings for the selected video input device, such as the size of the transmitted video display, the regional video format, and the video source channel to use.

Tip: The regional format does not apply to most USB cameras.

Tip: If there is a problem with the selected video input device, a test picture will instead be sent.

Adjust brightness, whiteness, colour and contrast of your video input device

EkigaVideoSettings-1.png

To adjust the brightness and colour properties of your video input, first make sure you have the Ekiga Call Panel enabled (View -> Show Call Panel). Then, click on the camera icon to display a real-time local feed from your video device. Finally, click on the contrast icon to the left of the camera icon, and use the sliders to adjust the brightness, whiteness, colour, and contrast settings for your video feed:

EkigaVideoSettings-2.png

Select the best quality/bandwidth ratio for video

Capture-Ekiga Preferences-1.png

The video codecs table in the Ekiga preferences window allows you to enable, disable, and reorder video codecs. Each codec has strong and weak points. For example, h261 is an older codec available on the widest variety of video conferencing systems, but has average quality. h264 has very good video quality, but is not necessarily available on every platform.

When you reorder codecs, you are reordering the local capabilities table. During a communication, only one video codec is used. The video codec used is the first active codec on receiver which is active on sender.

You can force the use of a specific codec by selecting it and disabling all other codecs, but this will result in failed calls if the remote user hasn't enabled that specific codec. The best approach is to put your preferred codecs at the top of the list, and to disable the codecs that you don't want to use for sending and receiving video.

Tip: Video codecs can adapt their quality to the available bandwidth. This setting is made when the Configuration Assistant is run during initial setup of Ekiga, so that an optimal quality codec is selected based on your network connection.

Test your webcam

You can test your webcam by clicking on the video camera icon (on upper left of Ekiga window) and check that it shows anything. See test your camera section in this manual for more information.

Controlling the video bandwidth

Ekiga uses a best-effort algorithm to maintain low bandwidth usage when transmitting video. You may if you like adjust video quality settings favouring a good frame rate, or, a good picture quality. Ekiga will dynamically adjust the video bandwidth and the number of transmitted images per second during a call, while trying to respect the requested video bandwidth.

A best-effort algorithm means that it may be impossible for Ekiga to respect a bandwidth setting if it is set too low. However, if the video bandwidth allows transmission with a higher picture quality or a faster framerate than the set value, then Ekiga will dynamically adjust this so that the quality and the framerate are always the best possible.

Choosing a higher framerate and a lower picture quality will have the same result in terms of video bandwidth as choosing higher picture quality with a lower framerate. It depends if you prefer using your bandwidth to transmit more lower quality images, or fewer better quality images.

Send a picture instead of video to your contact

In the event that your video input device is unavailable or if you prefer not to send video, you can instead send a moving logo animation. This can be selected from the Ekiga preferences as follows:

EkigaMovingLogo1.png


The Ekiga logo will then be sent as your video signal in an active call:

EkigaMovingLogo2.png

SIP settings

Outbound proxy

The outbound proxy is the SIP proxy that will relay your calls. The behavior of a SIP proxy is similar to the behavior of an HTTP proxy, ie some entity that issues the requests on your behalve and proxies the streams.

Emblem-important.png The proxy is currently used by all accounts. See feature request 340251: outbound SIP proxy setting should be attached to accounts.

Forward URL

The URI to which SIP incoming calls should be forwarded if configured in the preferences.

H323 settings

Forward URI

The URI to which H.323 incoming calls should be forwarded if configured in the preferences.

Advanced settings

Ekiga permits a fine control of the H.323 settings in the Advanced H.323 Settings section of the preferences.

H.245 tunneling

H.245 tunneling is the encapsulation of H.245 messages within H.225/Q.931 messages (H.245 tunneling). If you have a firewall and enable H.245 tunneling, there is one less TCP port that you need to allow for incoming connections.

Early H.245

This enables H.245 early in the setup and permits to achieve faster call initiation.

Fast connect

Fast Connect is a new method of call setup that bypasses some usual steps in order to make it faster. In addition to the speed improvement, Fast Connect allows the media channels to be operational before the CONNECT message is sent, which is a requirement for certain billing procedures. It was introduced in H.323 version 2.

Handle multiple video streams (H.239)

Ekiga 3.9.90 has initial support for H.239 (handling multiple video streams, such as video and presentation slides). This initial support is the following: Before the call, ekiga user can choose in Preferences->H.323 if he wants to see from the other party the main video stream or another video stream (presentation slides).

In ekiga 4.0.0 except for Windows, the video stream to be shown can also be chosen during the communication, through the View menu. Ekiga 4.0.1 adds support for this on Windows too.

In ekiga 4.1.0 the support is complete as receiver. This means that you can see both video streams simultaneously, in two windows. The extended stream window appears when a frame of the extended video is processed, and it is hidden when the communication ends. There is no support as sender for a second video stream.

Using Ekiga with audio servers

Windows: Direct Sound

GNU/Linux: ALSA, Pulse Audio, OSS

FreeBSD: OSS

Solaris: OSS

Using Ekiga with routers and firewalls

If you are behind a router, Ekiga has advanced NAT support thanks to STUN. In 95% of the cases, you do not have any configuration to do, and you can even be reachable from the outside without any port forwarding.

In the other 5% Ekiga normally shows an error specifying that it did not manage to configure your network settings automatically. You need first to find out the precise error, i.e. your NAT type, which is reported when executing Ekiga like this: ekiga -d 4 2>&1 | grep STUN. For example, if it reports a message like this:

2013/07/10 10:46:45.008   0:02.777      StunDetector:0x41b1d950	OPAL STUN server "stun.ekiga.net" replies Symmetric NAT, external IP X.Y.Z.T

then your NAT type is symmetric NAT.

Several cases appear for your NAT type:

  • Blocked: you probably have a firewall, usually on your own machine, which blocks Ekiga packets. You have to tell it to allow Ekiga to access Internet.
  • Cone NAT or Port Restricted NAT: you probably use H323 and you need to forward a few other TCP ports, see below.
  • Symmetric NAT: it is not possible de guess what ports will be used, and you need to reconfigure your router. You will have either to forward ports manually to your internal machine, or to dynamically navigate the router, as written in the next section (if it allows it, and a must do if you use Ekiga on several machines). An alternative solution is to use exterior help, i.e. an external proxy; however, there is no free such proxy, because they use a VERY high bandwidth (Skype for example avoids this problem by using users with public IP addresses themselves as proxies).

(For H323: you will have to manually forward ports 5000 to 5100 to your internal machine. If you want to be reachable from the outside, you will need to forward TCP port 1720 from your router to the internal machine running Ekiga. If you want to be able to do calls with Netmeeting users, you will need to forward TCP ports 30000 to 30010 from the NAT router to the machine running Ekiga. This last step is only necessary when calling H.323 software that does not support H.245 Tunnelling (the H.323 part of Ekiga supports H.245 Tunnelling, forwarding that TCP port range is thus not required when calling them using H.323).)

Some notes about routers:

  • Many VoIP forums report massive problems with some embedded SOHO routers blocking VoIP protocols restrictively and need the built in Firewall turned off (not that bad, you are still behind NAT and mostly protected). For example, Netgear is known to have "very good hardened" firewalls. Ask Manufacturer Support and update Firmware first.
  • For good sound quality a router with built-in QoS is a must have, "V" type products should have it, older stuff rarer. The best routers to buy are Linux based and have GPL'ed firmware.

Configuration of the ports used by Ekiga

The default ports are defined by the standards SIP, H.323 and STUN. You should not change those ports except for complex configurations or rare cases. The default ports used by Ekiga are the following:

The ports used by default by Ekiga
Protocols Ports Types Descriptions
SIP 5000 to 5100 UDP SIP signalling, listen port: 5060
STUN 3478 to 3479 UDP Outgoing traffic to the STUN server
RTP Random/Various UDP Incoming traffic from the other end. Often 5004, 7070, 16382
H323 1720 TCP Listen port
H323 5000 to 5100 UDP H.323 gatekeepers
H323 30000 to 30010 TCP H.245 channel for old H.323 implementations (Netmeeting)

Ekiga allows to configure the following variables:

  • listen_port is the port Ekiga listens for incoming connections on: 5060 in UDP for SIP, and 1720 in TCP for H.323.
  • udp_port_range is the range of UDP ports that Ekiga uses for SIP signalling or when registering to H.323 gatekeepers. It is also used for RTP (audio and video communication channels). Ekiga needs to be restarted for the new values to take effect (??)
  • tcp_port_range is the range of TCP ports beside the listen_port that Ekiga uses for the H.245 channel with the H.323 protocol. That port range is not used by SIP. It is not used either when H.245 Tunneling is enabled, which is in general always the case, except when calling old H.323 implementations like Netmeeting.

To change those ports, open gconf-editor, select apps from the left hand side menu and then select Ekiga. Then select "sip" or "h323", it should give you a list in the corresponding window to your right. Select listen_port and change it to your desired value. You can also change the UDP/RTP port ranges.

A last port used by Ekiga is the one used by ZeroConf (the Bonjour / Rendez-Vous technology from Apple), allowing for automatic Ekiga client discovery on the LAN. However, this port cannot be changed.

Avahi port
Protocol Port Type Description
ZeroConf 5353 UDP Zeroconf / Rendezvous / Bonjour port

Note: Ahavi/MDNS/STUN and friends might give you several drawbacks, like SSH clients taking a while to open, or requests to your apache from clients without reverse lookup getting 5 seconds penalty. Thus, if you are in a cooperate environment, and just want to talk to your local SIP-Gateway instead of doing this through your internet link, you should probably disable STUN (network detection) from Ekiga preferences dialog box. Removing mdns from your /etc/nsswitch.conf will resolve your ssh troubles.

Symmetric NAT: Dynamic navigation of NAT routers

  • Overview

To understand the problems with symmetric NAT, read Understanding NAT/firewall issues with SIP clients (eg ekiga).

This type of NAT cannot be served by a VoIP program without a "trick". Skype for example works in this case too because it uses the other users of skype as proxies, otherwise said the other users give (are forced to give) ressources (CPU and network bandwidth) for Symmetric NAT skipe users.

Another solution is to have a public proxy for all the symmetric NAT users. This can work for audio traffic, but for (the much higher bandwidth consuming) video traffic this is overkill. And it seems iptel.org provides such a service, but for audio only.

Finally, the simplest solution, if it works, is to change the NAT from Symmetric to another type. For that, if the Assistant Configuration reports a "symmetric NAT" (in ekiga v2) or you receive when ekiga starts a dialog box about that (in ekiga v3) and you have access to your router configuration, you may try the following.

  • The issue

Typical SOHO routers incorporate a Network Address Translator (NAT): local network addresses are hidden behind (translated into) a single address presented to the WAN, which in the domestic case is normally that provided by an ISP.

Normally incoming packets (those from the WAN) are silently dropped unless they match a previous outgoing packet. Apart from reasons of security, the router has no means of determining the destination address on the LAN if there is no match with a previous outward bound packet. This creates a problem in establishing a voip connection between machines which are both behind separate NATs: neither can reach the other to initiate communication even when a sip server has provided each with the other's address.

  • Port Forwarding

Such routers normally have facilities for port forwarding: incoming packets for distinguished ports can be directed to a particular machine on the LAN behind the NAT. The limitation is that only the choosen machine can engage in voip calls.

  • STUN

The STUN protocol (rfc 3489) is designed to solve this problem, but it does not work with symmetric NATs: those that are strict about incoming packets matching precisely a previous outgoing packet.

  • Application Rules: dynamic gateways

Many NAT routers allow Application Rules to be defined which allow specified ports to be opened dynamically to incoming packets when triggered by an outgoing packet. If this trigger is fired when ekiga sends a packet to a STUN server, ports can be opened so that the STUN protocol sees essentially an open NAT: a full CONE. Actually, the trigger rules below just open a restricted range, so this is more accurately a "Port restricted NAT" which is how ekiga may describe the situation once the rules are in place.

That then allows the voip traffic to pass unimpeded.

Example:

  • Trigger ports: 3478-3479
  • Public ports: 3478-3479,5000-5100
  • Protocol: UDP

This rule is shown below on a DLink router: Stun voip rule.jpg

Another example (Linksys router):

  • Trigger port: 3478
  • Ports opened (forwarded) : 5000-5100

It is only necessary to trigger on 3478, despite the previous example. For some unexplained reason, this firmware (1.52.15) does not offer a choice of protocols for Port Triggering.

Sip trigger BEFSX41.jpg

Other solutions

If the above simpler methods do not work, you can use an outbound proxy (to be set in Preferences): siproxd for SIP, and GNU Gatekeeper for H.323.

When connected to a very restricted network such as a university or a corporate network where for example only 80, 443 and 8080 ports are accessible, you have to use an HTTP proxy, which allows to tunnel SIP signaling & RTP communication. A free service which is known to work comes from realTunnel (BEAWARE: proprietary solution, binary-only program, Ekiga developers makes no guarantee on this): http://www.paradial.com/download/realtunnel-nat-sip-traversal.html.

Troubleshooting

Troubleshooting is covered in more detail in the Troubleshooting Section in the wiki.

Error messages in Ekiga

These are the error message Ekiga presents. OPAL sends a numeric code to Ekiga and Ekiga presents these phrases to the user. The two messages with opal codes of n/a are produced internally by Ekiga.

It has been noted that Ekiga cannot offer more details than it gets from OPAL.

   Ekiga			OPAL	   Internal
   Message  			Code  	   Parameter
Address incomplete 		484 	Failure_AddressIncomplete
Alternative service 		380 	Redirection_AlternativeService
Ambiguous 			485 	Failure_Ambiguous
Bad event 			489 	Failure_BadEvent
Bad gateway 			502 	Failure_BadGateway
Bad request 			400 	Failure_BadRequest
Busy everywhere 		600 	GlobalFailure_BusyEverywhere
Busy Here 			486 	Failure_BusyHere
Conflict 			409 	Failure_Conflict
Decline 			603 	GlobalFailure_Decline
Does not exist anymore 	604 	GlobalFailure_DoesNotExistAnywhere
Extension required 		421 	Failure_ExtensionRequired
Forbidden 			403 	Failure_Forbidden
Globally not acceptable 	606 	GlobalFailure_NotAcceptable
Illegal status code 		n/a 	IllegalStatusCode
Internal server error 		500 	Failure_InternalServerError
Interval too brief 		423 	Failure_IntervalTooBrief
Length required 		411 	Failure_LengthRequired
Loop detected 			482 	Failure_LoopDetected
Message too large 		513 	Failure_MessageTooLarge
Method not allowed 		405 	Failure_MethodNotAllowed
Moved permanently 		301 	Redirection_MovedPermanently
Moved temporarily 		302 	Redirection_MovedTemporarily
Multiple choices 		300 	Redirection_MultipleChoices
Not acceptable 		406 	Failure_NotAcceptable
Not acceptable here 		488 	Failure_NotAcceptableHere
Not found 			404 	Failure_NotFound
Not implemented 		501 	Failure_NotImplemented
Payment required 		402 	Failure_PaymentRequired
Proxy authentication required 	407 	Failure_ProxyAuthenticationRequired
Request entity too big 	413 	Failure_RequestEntityTooLarge
Request pending 		491 	Failure_RequestPending
Request terminated 		487 	Failure_RequestTerminated
Request URI too long 		414 	Failure_RequestURITooLong
Server timeout 		504 	Failure_ServerTimeout
Service unavailable 		503 	Failure_ServiceUnavailable
SIP version not supported 	505 	Failure_SIPVersionNotSupported
Temporarily unavailable 	480 	Failure_TemporarilyUnavailable
Timeout 			408 	Failure_RequestTimeout
Too many hops 			483 	Failure_TooManyHops
Transport error 		n/a 	Local_BadTransportAddress
Unauthorized 			401 	Failure_UnAuthorised
Undecipherable 		493 	Failure_Undecipherable
Unsupported media type 	415 	Failure_UnsupportedMediaType
Unsupported URI scheme 	416 	Failure_UnsupportedURIScheme
Use proxy 			305 	Redirection_UseProxy

Glossary

   Defines specific terms in the book. You do not need to define terms that are in the http://www.bartleby.com/61/.

VoIP

NAT

SIP

H.323

Appendices

   Contain additional notes about related topics that are not directly explained in the document body.

Related Softwares

IPBX

   * Asterisk PBX: http://asterisk.org

SIP

   * SIP Express Router: http://www.iptel.org/ser

H.323

   * OpenH323 Gatekeeper: http://www.openh323.org
   * GNU Gatekeeper: http://www.gnugk.org
   * OpenH323 Proxy: http://openh323.sourceforge.net
   * H323 - ISDN Gateway: http://www.telos.de/linux/H323/

Conferencing/VoIP Software

   * OpenMCU: http://www.openh323.org

Similar Clients

   * XTen: http://www.xten.com
   * SJPhone: http://www.sjlabs.com/
   * OpenPhone: http://www.openh323.org
   * Netmeeting: http://www.microsoft.com

Understanding VoIP addresses

SIP addresses

SIP URIs are formatted as such "sip:user@[host[:port]]"

This permits you to call the given user or extension on the specified SIP proxy: sip:jonita@ekiga.net

H.323 addresses

H.323 URIs are formatted as such "h323:[user@][host[:port]]"

This permits you to:

   * Call a given host on a port different from the default port which is 1720: h323:seconix.com:1740
   * Call a given user using their respective alias if registered to a gatekeeper: h323:jonita
   * Call a given phone number if you are registered to a gatekeeper for a PC-To-Phone provider, or if that user has an ENUM record associated to an H.323 URI: h323:003210111222
   * Call a given user using their alias through a specific gateway or proxy: h323:jonita@gateway.seconix.com
   * Call an MCU and join a specific room: h323:myfriendsroom@mcu.seconix.com

CALLTO addresses

Callto URIs are formatted as such "callto:[user@][host[:port]]"

Callto URIs and H.323 URIs are formatted exactly the same except however callto URIs also support ILS lookups directly: callto:ils_server/user_mail.

CANDIDATEFORSUPPRESSION_For example, calling callto:ils.seconix.com/joe.user@somedomain.com will look for the user with the joe.user@somedomain.com email address on the ILS server ils.seconix.com and proceed to initate a call.

Technical Specifications

SIP

List the RFCs

Network transversal: STUN

Free codecs Plugins Vidéo: H263, H264 Plugins Audio: G729, iLBC

H323

List the RFCs

Free codecs Audio: G729, iLBC

IM: SIP/SIMPLE

Plug n'play using a local network: ZeroConf/Bonjour

codecs

audio
Video

LDAP support

ENUM support

Ekiga has enum support, which allows you to associate your real phone number to a SIP or H.323 address and to be callable by other users using that phone number.

API for devices support

Audio: ALSA, OSS, Direct audio
Video: V4l2, DirectX

Using OSS 4.x

Some technical people might prefer OSS4 audio device over ALSA or Pulse. This appendix presents how to configure Ekiga to use it.

To install OSS4, check your distro forums/documentation. Some distros such as Arch Linux provide packages in the main repository to install OSS 4.x. If your distro does not provide an OSS4 package, you may build OSS4 from source.

You should most likely uninstall ALSA and Pulse Audio before installing OSS 4.

Gnome-status.png As of Ekiga 3.2.4 (PTLIB 2.6.2), OSS 4.x devices do not show up in the Ekiga Audio Device preferences.

To get Ekiga to work with OSS 4.x:

  • 1. Make sure that your installation of Ekiga includes OSS support.
Emblem-important.png OSS support may not be enabled on your system by default. On Ubuntu 9.04, for example, you will need to install the libpt-plugins-oss package.
  • 2. Close Ekiga and make sure no instances of Ekiga are running.
  • 3. Manually set all audio devices in the Ekiga gconf options to "/dev/dsp (PTLIB/OSS)" where /dev/dsp is the OSS device you wish to use.

You may use the following terminal commands to change the options:

 $ gconftool-2 --set /apps/ekiga/devices/audio/input_device --type string "/dev/dsp (PTLIB/OSS)"
 $ gconftool-2 --set /apps/ekiga/devices/audio/output_device --type string "/dev/dsp (PTLIB/OSS)"
 $ gconftool-2 --set /apps/ekiga/general/sound_events/output_device --type string "/dev/dsp (PTLIB/OSS)"

Alternatively, you may edit the options with gconf-editor.

  • 4. Start Ekiga and double-click "Echo Test" to make sure everything works. You will hear a woman voice and after, you should hear yourself talking with a small delay (echo).

Supported video settings

An old document about supported video settings:

Stream Properties in the Sending Direction
Software name Codec Transport Resolution Frames/s bit/s Configuration Options
Ekiga 2.0.x H.261 RFC 2032 QCIF 25 80k-240k Target Bitrate = 128k, Quality = (is ignored)
QCIF 25 80k-280k Target Bitrate = 256k, Quality = (is ignored)
QCIF 25 80k-320k Target Bitrate = 512k, Quality = (is ignored)
QCIF 25 80k-360k Target Bitrate = 1024k, Quality = (is ignored)
H.263 (1995) RFC 2190 QCIF 25 80k-400k Target Bitrate = (is ignored), Quality = (is ignored)
CIF 25 400k-600k Target Bitrate = (is ignored), Quality = (is ignored)
MPEG 4 Part 2 Visual RFC 3016 QCIF 25 120k-400k Target Bitrate = (is ignored), Quality = (is ignored)
CIF 25 512k-1600k Target Bitrate = (is ignored), Quality = (is ignored)
Ekiga 3.0 TBD
Windows Messenger H.261 RFC 2032 QCIF 3-5 24k-40k none
H.263 (1995) RFC 2190 CIF 3-5 24k-40k none
X-Lite 3.0/eyeBeam H.263 (1995) RFC 2190 QCIF 5-10 ~48k Preset "Cable"
CIF 5-15 ~256k Preset "Fast Cable"
CIF 15-25 ~512k Preset "LAN"
Linphone MPEG 4 Part 2 Visual RFC 3016 QCIF 6 48k-80k Target Bitrate = 128k
CIF 10 80k-200k Target Bitrate = 256k
CIF 10 320k-560k Target Bitrate = 512k
CIF 18 800k-1600k Target Bitrate = 1024k
Kapanga H.263 (1995) RFC 2190 QCIF 5-10 ~240k Resolution = QCIF, bitrate = ??, framerate = (is ignored)
CIF 5-10 480k Resolution = CIF, bitrate = ??, framerate = (is ignored)

GNOME integration

Evolution address book

SIP URI in GNOME

Configuration storing (GConf daemon)

KDE integration

KAdressBook

SIP URI in KDE

Configuration storing

Windows integration

SIP URI in Windows

Configuration storing

Index

   Provides keyword links to specific concepts in the book. Follow the guidelines in this guide to create an effective index.
Personal tools