LINPHONE 'S USER MANUAL

1. Introduction
2. Running linphone
3. How to make a call ?
4. Call parameters
5. Address book
6. Registering on a sip server
7. Behind a firewall
8. Limitations
9. Problems
10. Bugs, sugestions
11. Authors
12. Thanks

1- Introduction

Linphone is a simple web-phone. It allows you to make two party-calls using an IP network like the internet. What you need to run Linphone is :

• Linux (maybe it works also on BSD or other UNIX, but nobody test it under other envirronnements than linux.)
• Gnome 1.2 or more, installed but not necessary running.
• a sound card correctly configured
• headphones or speakers
• a microphone
• a connection to a network (the Internet for example), using a modem, an ethernet card or anything.

Linphone is free, it is released under GNU Public License.

WARNING: This software is provided with NO WARRANTY see file COPYING for details. This means you MUST NOT use linphone for confidential conversations: there is NO encryption, so it is easy for any bad-intentionned person to catch audio streams.
Note also that it is not recommended to run Linphone as root.

2- Running linphone

Linphone can be run as three different ways:

• as normal application: in the gnome menu, linphone should appear in network sub-menu. If you are not running gnome, you can execute linphone by typing linphone in a terminal, for example. When linphone is not running, you cannot receive calls.
• as a gnome applet: by clicking on the gnome panel with the right button, add the applet. Linphone appears in the network menu. By running silently in the panel, linphone is able to receive calls even if its window is not shown. If you want the main window to appear, click on the applet. When a call arrives, the main window is shown and you will hear the ring normally.
• as a silent daemon: this is for non-gnome users. For example in kde, you have a /home/user/.kde2/AutoStart/ directory where you can add links to the application you want to be started when logging. So go to the above directory with the file manager, and do 'add link' by right clicking. The command to run is "linphone --daemon". You will not show linphone's interface, but to make it appear, just runs linphone normally, for example in a terminal.

3- How to make a call ?

a) Basic principles.

Linphone uses the Session Initiation Protocol to establish the connection with a remote host. To call somebody, you must provide to linphone a SIP URL:
user_name@host_name(or IP address).

Note that Sip is a new telecommunication protocol designed to be simple, and it is not compatible with H323 at all.

The user_name is a login name in a linux machine. host_name is the name of a machine, if known by name servers. If not use IP address directly. If you are using a temporary connection to the internet, for example if you are using a modem, it is important that you run linphone after being connected, since linphone needs to find your IP address. If you are connected to multiple networks, linphone will warn you, and you will be recommended to check in the property box if it is using the good network. The person you want to phone must have linphone running in order to receive the call. As SIP is an open protocol, Linphone should work with other sip-compatible web phones.

b) application: two users connected to the internet via a modem.

Here is a "simple" way to proceed: Requirements:

• a 28k or more modem.
• Check in the property box that you are using LPC10-1.5 vocoder. It does not work with GSM, since you need 32kbit/s upstream (an ADSL or cable modem is enough).

• Bob has to call Tom at 21:00. At 21:00 Tom connects to the internet using kppp, or gppp, or wvdial, (or other).
• Once it is connected to the internet, he can run linphone.
• By opening the statistics box of kppp or gppp, he can see its IP address (if not type /sbin/ifconfig to see it). The name of the modem interface should be ppp0.
• Then he sends an e-mail to Bob where it tells "My IP address is xxx.xxx.xxx.xxx.".
• Bob receives the e-mail, and then types in linphone window the name and ip address of the person he wants to contact: Tom @ xxx.xxx.xxx.xxx(Tom's IP address), and finaly press the call button. Then linphone rings at Tom's house.
• Then Tom has just to answer the call by clicking on the answer button, and then should talk each other.
• If you encounter problems, see section 4-problems.

c) test: you have nobody to call to, but you would like to check if linphone can run on your system

Since version 0.3.0, linphone comes with a test program called 'sipomatic'. Sipomatic can answer automatically to calls from linphone. To do this:

• run sipomatic from a terminal. Dont't be surprised, sipomatic does not have a graphical interface, but you don't have to interact with it.
• From linphone, go to the property box, section network, and choose "lo" as the default interface. Apply changes by clicking OK.
• Then type the following sip ur in the main windowl:
  sip:robot@127.0.0.1:5064 . 127.0.0.1 is a local address for your computer, and robot is the name to use for calling sipomatic. 5064 is the port where sipomatic can be joined. Normally you should always use 5060 to call somebody, but sipomatic is the exception: it runs on port 5064. The reason for this is that linphone already runs on 5060, and you cannot have two applications running on the same port, in the same time and on the same machine.
• Then press the call button. After one second, sipomatic should answer to your call and you should here a short annoncement.

4- Call parameters

Linphone has several parameters and options you can change, in order to change or improve its performance:

• Network parameters
• RTP parameters
• SIP parameters
• Codec parameters
• Audio parameters

5- Address book

You can store and recall sip address using the address book (in the connection menu).
A sip address is in the form: user@domain_name. You can also add a display name, that is used only for your information.
To recall a sip address, select it in the address list, and click on the "select" button. Then you will see the address you have selected in the main window. Just press the call button to call the person.

6- Registering on a sip server

When you connects to the internet via a dialup connection, there is a serious problem for your friends to know your IP address in order to phone you.

For this reason you can register a fixed sip address on a SIP server called registrar or redirect server.

Your sip address will become sip:my_name@myregistrar. Your friends will be able to phone you using this address. The principle is very simple: when linphone startups, it tells to the registrar the correspondance between your sip address sip:my_name@myregistrar and your IP address. Then when your friends call you at the above sip address, the registrar gives them your exact Ip address, and the call is redirected to your exact location.

To accomplish this, go to the property box, section SIP and toggle the button in front of « use registrar ». Type the url of the registrar, and choose a user name that is not too frequent to avoid name conflicts. For example it is sure that sip:jack@my_registrar is very usefull. Prefer something like

sip:jack.nicholson@my_registrar.

You may choose a password for your registration: it depends on the registrar server. Follow the instructions given on the registrar web site.

Finnaly click the OK button of the property box. Linphone will close it and immediately talk to the registrar server to inform it of your exact location. When linphone shutdowns, it will take a few seconds to unregister your location from the registrar.

A list of public registrar servers can be found at http://www.cs.columbia.edu/~hgs/sip/servers.html.

Unfortunately, many of these servers don't work anymore, maybe caused by the recent crisis in telecommunications. Some requires authentification methods that are currntly not supported by linphone.

In order for you not to lost your time, a list of working public sip servers usable with linphone is availlable on linphone web site at http://simon.morlat.free.fr/english/servers.html .

Some requires you to fill a registration form, but don't worry all servers on this list are totally free of charge.

7- Behind a firewall

Complete firewall support is planned for near future in linphone.
For the moment linphone can work behind a firewall in the following situation:

• Machines behind the firewall have public internet address, and the firewall just filters incoming and outgoing packets:
  What you have to do is to allow traffic in both directions for the sip port (defaut: 5060) and the audio rtp port (default is 7077 for linphone). These two port are changeable in linphone 's property box, but you are recommended to keep 5060 for SIP, that is the official port for this protocol.

8- Limitations

Since version 0.4.0, linphone uses the osip stack to implement the SIP protocol. Some responses or requests are still unsupported, but others should work fine (INVITE, REGISTER, BYE, ACK, CANCEL, 200, 486, 606, 404).

You may notice that some menus or boxes do nothing. That is normal, it will be done in furure versions.

Linphone-0.4.0 breaks compatibility with older versions. This means that you can't use a 0.4.0 version to call a 0.3.0 one and vice-versa.

9- Problems

a) audio problems

Here is a list of things you can check before saying "That 's shit.":

• Most people get problems because they don't choose the correct network interface in the property box, section network. For a dialup connection, it should be "ppp0". Note also that the "lo" interface SHOULD ONLY be used for testing with sipomatic. In other cases, it will fail.
• Use a mixer to adjust level, and set recording source to the microphone.
• If the voice is sometines cutted, you can modify parameter RTP->jitter compensation in the property box to greater values to avoid this. But it increases the delay transmission.
• If linphone cannot open the audio device, check if it has the permission to open /dev/dsp, close all programs able to use audio device (xmms, kaiman...).

b) Connection problems

• Check name, ip address or host name.
• If you are trying to call someone using another sip phone, don't be surprised if it does not work. To help me in debugging, you can send me the standart output of linphone (what it writes on the terminal you use to execute it).
• The default rtp port (7000) may be used by another application: change it in the property box.

See file BUGS in the sources for other noticed strange things.

NOTE: Linphone cannot work in local loopback: don't try to call yourself or run several linphones on the same host: it does not work. Only the call to sipomatic works in local loopback.

10- Bugs, suggestions

First go to linphone's home page at http://simon.morlat.free.fr/english/linphone.html to check if you have the latest version if linphone.

If linphone crashes, send me directly a report at
linphonebugs@free.fr
If linphone does not work, but does not crash, please ensure you have read all this manual before sending me a bug report at the above address.
If you want to request something, don't hesitate to send me an email at the same above address. Note that video support, proxy support and conferencing are planned features.

If someone is interested in doing translations for linphone, send me a xx.po file based on the po/linphone.pot file of the distribution. You can also translate this user manual in other languages. In any case, please contact me if you want more details.

11- Authors

Simon MORLAT (simon.morlat@free.fr) wrotes:

• main program (src)
• RTP library (lprtplib)
• osipua : the user agent api built on top of osip stack.
• audio interface for oss and alsa drivers. (audio)
• wrappers for lpc10-1.5, gsm and g711 codecs

Aymeric Moizard (jack@atosc.org) wrotes the osip stack that is used by linphone.

The GSM library was written by :
Jutta Degener and Carsten Bormann,Technische Universitaet Berlin.

The LPC10-1.5 library was written by:
Andy Fingerhut
Applied Research Laboratory <-- this line is optional if
Washington University, Campus Box 1045/Bryan 509 you have limited space
One Brookings Drive
Saint Louis, MO 63130-4899
jaf@arl.wustl.edu
http://www.arl.wustl.edu/~jaf/
See text files in gsmlib and lpc10-1.5 directories for further information.

Icons by Pablo Marcelo Moia.

Translations in english by Delphine PERREAU.

12- Thanks

Thanks to Daemon Chaplin, for having done Glade, the gtk interface builder.

Thanks to the authors of LPC10-1.5 and GSM code.

Thanks to Joel Barrios ( jbarrios@linuxparatodos.com ) for his RPMS.

Thanks to Pablo Marcelo Moia for the great icons he has made for linphone.

Thanks to BlueFish developpement team, for having made bluefish, the wonderful html editor that I used to make this page.