Update README documentation.
[asterisk/asterisk.git] / README
1 ===============================================================================
2 ===                     The Asterisk(R) Open Source PBX
3 ===
4 ===                   by Mark Spencer <markster@digium.com>
5 ===                  and the Asterisk.org developer community
6 ===
7 ===                    Copyright (C) 2001-2009 Digium, Inc.
8 ===                       and other copyright holders.
9 ===============================================================================
10
11 -------------------------------------------------------------------------------
12 --- SECURITY ------------------------------------------------------------------
13
14   It is imperative that you read and fully understand the contents of
15 the security information document before you attempt to configure and run
16 an Asterisk server.
17
18   If you downloaded Asterisk as a tarball, see the security section in the PDF
19 version of the documentation in doc/tex/asterisk.pdf.  Alternatively, pull up
20 the HTML version of the documentation in doc/tex/asterisk/index.html.  The
21 source for the security document is available in doc/tex/security.tex.
22 -------------------------------------------------------------------------------
23
24 -------------------------------------------------------------------------------
25 --- WHAT IS ASTERISK ? --------------------------------------------------------
26
27   Asterisk is an Open Source PBX and telephony toolkit.  It is, in a
28 sense, middleware between Internet and telephony channels on the bottom,
29 and Internet and telephony applications at the top.  However, Asterisk supports
30 more telephony interfaces than just Internet telephony.  Asterisk also has a
31 vast amount of support for traditional PSTN telephony, as well.  For more
32 information on the project itself, please visit the Asterisk home page at:
33
34            http://www.asterisk.org
35
36   In addition you'll find lots of information compiled by the Asterisk
37 community on this Wiki:
38
39            http://www.voip-info.org/wiki-Asterisk
40
41   There is a book on Asterisk published by O'Reilly under the Creative Commons
42 License. It is available in book stores as well as in a downloadable version on
43 the http://www.asteriskdocs.org web site.
44 -------------------------------------------------------------------------------
45
46 -------------------------------------------------------------------------------
47 --- SUPPORTED OPERATING SYSTEMS -----------------------------------------------
48
49 --- Linux
50   The Asterisk Open Source PBX is developed and tested primarily on the
51 GNU/Linux operating system, and is supported on every major GNU/Linux
52 distribution.
53
54 --- Others
55   Asterisk has also been 'ported' and reportedly runs properly on other
56 operating systems as well, including Sun Solaris, Apple's Mac OS X, Cygwin,
57 and the BSD variants.
58 -------------------------------------------------------------------------------
59
60 -------------------------------------------------------------------------------
61 --- GETTING STARTED -----------------------------------------------------------
62
63   First, be sure you've got supported hardware (but note that you don't need
64 ANY special hardware, not even a sound card) to install and run Asterisk.
65
66   Supported telephony hardware includes:
67
68         * All Analog and Digital Interface cards from Digium (www.digium.com)
69         * QuickNet Internet PhoneJack and LineJack (http://www.quicknet.net)
70         * any full duplex sound card supported by ALSA, OSS, or PortAudio
71         * any ISDN card supported by mISDN on Linux
72         * The Xorcom Astribank channel bank
73         * VoiceTronix OpenLine products
74
75 -------------------------------------------------------------------------------
76
77 -------------------------------------------------------------------------------
78 --- UPGRADING FROM AN EARLIER VERSION -----------------------------------------
79
80   If you are updating from a previous version of Asterisk, make sure you
81 read the UPGRADE.txt file in the source directory. There are some files
82 and configuration options that you will have to change, even though we
83 made every effort possible to maintain backwards compatibility.
84
85   In order to discover new features to use, please check the configuration
86 examples in the /configs directory of the source code distribution.  For a
87 list of new features in this version of Asterisk, see the CHANGES file.
88 -------------------------------------------------------------------------------
89
90 -------------------------------------------------------------------------------
91 --- NEW INSTALLATIONS ---------------------------------------------------------
92
93   Ensure that your system contains a compatible compiler and development
94 libraries.  Asterisk requires either the GNU Compiler Collection (GCC) version
95 3.0 or higher, or a compiler that supports the C99 specification and some of
96 the gcc language extensions.  In addition, your system needs to have the C
97 library headers available, and the headers and libraries for ncurses.
98
99   There are many modules that have additional dependencies.  To see what
100 libraries are being looked for, see ./configure --help, or run
101 "make menuselect" to view the dependencies for specific modules.
102
103   On many distributions, these dependencies are installed by packages with names
104 like 'glibc-devel', 'ncurses-devel', 'openssl-devel' and 'zlib-devel' 
105 or similar.
106
107   So, let's proceed:
108
109 1) Read this README file.
110
111   There are more documents than this one in the doc/ directory.  You may also
112 want to check the configuration files that contain examples and reference
113 guides. They are all in the configs/ directory.
114
115 2) Run "./configure"
116
117   Execute the configure script to guess values for system-dependent
118 variables used during compilation.
119
120 3) Run "make menuselect" [optional]
121
122   This is needed if you want to select the modules that will be compiled and to
123 check dependencies for various optional modules.
124
125 4) Run "make"
126
127   Assuming the build completes successfully:
128
129 5) Run "make install"
130
131   If this is your first time working with Asterisk, you may wish to install
132 the sample PBX, with demonstration extensions, etc.  If so, run:
133
134 6) "make samples"
135
136   Doing so will overwrite any existing configuration files you have installed.
137
138   Finally, you can launch Asterisk in the foreground mode (not a daemon) with:
139
140 # asterisk -vvvc
141
142   You'll see a bunch of verbose messages fly by your screen as Asterisk
143 initializes (that's the "very very verbose" mode).  When it's ready, if
144 you specified the "c" then you'll get a command line console, that looks
145 like this:
146
147 *CLI>
148
149   You can type "core show help" at any time to get help with the system.  For help
150 with a specific command, type "core show help <command>".  To start the PBX using
151 your sound card, you can type "console dial" to dial the PBX.  Then you can use
152 "console answer", "console hangup", and "console dial" to simulate the actions
153 of a telephone.  Remember that if you don't have a full duplex sound card
154 (and Asterisk will tell you somewhere in its verbose messages if you do/don't)
155 then it won't work right (not yet).
156
157   "man asterisk" at the Unix/Linux command prompt will give you detailed
158 information on how to start and stop Asterisk, as well as all the command
159 line options for starting Asterisk.
160
161   Feel free to look over the configuration files in /etc/asterisk, where you
162 will find a lot of information about what you can do with Asterisk.
163 -------------------------------------------------------------------------------
164
165 -------------------------------------------------------------------------------
166 --- ABOUT CONFIGURATION FILES -------------------------------------------------
167
168   All Asterisk configuration files share a common format.  Comments are
169 delimited by ';' (since '#' of course, being a DTMF digit, may occur in
170 many places).  A configuration file is divided into sections whose names
171 appear in []'s.  Each section typically contains two types of statements,
172 those of the form 'variable = value', and those of the form 'object =>
173 parameters'.  Internally the use of '=' and '=>' is exactly the same, so 
174 they're used only to help make the configuration file easier to
175 understand, and do not affect how it is actually parsed.
176
177   Entries of the form 'variable=value' set the value of some parameter in
178 asterisk.  For example, in dahdi.conf, one might specify:
179
180         switchtype=national
181
182   In order to indicate to Asterisk that the switch they are connecting to is
183 of the type "national".  In general, the parameter will apply to
184 instantiations which occur below its specification.  For example, if the
185 configuration file read:
186
187         switchtype = national
188         channel => 1-4
189         channel => 10-12
190         switchtype = dms100
191         channel => 25-47
192
193   The "national" switchtype would be applied to channels one through
194 four and channels 10 through 12, whereas the "dms100" switchtype would
195 apply to channels 25 through 47.
196   
197   The "object => parameters" instantiates an object with the given
198 parameters.  For example, the line "channel => 25-47" creates objects for
199 the channels 25 through 47 of the card, obtaining the settings
200 from the variables specified above.
201 -------------------------------------------------------------------------------
202
203 -------------------------------------------------------------------------------
204 --- SPECIAL NOTE ON TIME ------------------------------------------------------
205   
206   Those using SIP phones should be aware that Asterisk is sensitive to
207 large jumps in time.  Manually changing the system time using date(1)
208 (or other similar commands) may cause SIP registrations and other
209 internal processes to fail.  If your system cannot keep accurate time
210 by itself use NTP (http://www.ntp.org/) to keep the system clock
211 synchronized to "real time".  NTP is designed to keep the system clock
212 synchronized by speeding up or slowing down the system clock until it
213 is synchronized to "real time" rather than by jumping the time and
214 causing discontinuities. Most Linux distributions include precompiled
215 versions of NTP.  Beware of some time synchronization methods that get
216 the correct real time periodically and then manually set the system
217 clock.
218
219   Apparent time changes due to daylight savings time are just that,
220 apparent.  The use of daylight savings time in a Linux system is
221 purely a user interface issue and does not affect the operation of the
222 Linux kernel or Asterisk.  The system clock on Linux kernels operates
223 on UTC.  UTC does not use daylight savings time.
224
225   Also note that this issue is separate from the clocking of TDM
226 channels, and is known to at least affect SIP registrations.
227 -------------------------------------------------------------------------------
228
229 -------------------------------------------------------------------------------
230 --- FILE DESCRIPTORS ----------------------------------------------------------
231
232   Depending on the size of your system and your configuration,
233 Asterisk can consume a large number of file descriptors.  In UNIX,
234 file descriptors are used for more than just files on disk.  File
235 descriptors are also used for handling network communication
236 (e.g. SIP, IAX2, or H.323 calls) and hardware access (e.g. analog and
237 digital trunk hardware).  Asterisk accesses many on-disk files for
238 everything from configuration information to voicemail storage.
239
240   Most systems limit the number of file descriptors that Asterisk can
241 have open at one time.  This can limit the number of simultaneous
242 calls that your system can handle.  For example, if the limit is set
243 at 1024 (a common default value) Asterisk can handle approximately 150
244 SIP calls simultaneously.  To change the number of file descriptors
245 follow the instructions for your system below:
246 -------------------------------------------------------------------------------
247
248 -------------------------------------------------------------------------------
249 --- PAM-based Linux System ----------------------------------------------------
250
251   If your system uses PAM (Pluggable Authentication Modules) edit
252 /etc/security/limits.conf.  Add these lines to the bottom of the file:
253
254 root            soft    nofile          4096
255 root            hard    nofile          8196
256 asterisk        soft    nofile          4096
257 asterisk        hard    nofile          8196
258
259 (adjust the numbers to taste).  You may need to reboot the system for
260 these changes to take effect.
261
262 == Generic UNIX System ==
263
264   If there are no instructions specifically adapted to your system
265 above you can try adding the command "ulimit -n 8192" to the script
266 that starts Asterisk.
267 -------------------------------------------------------------------------------
268
269 -------------------------------------------------------------------------------
270 --- MORE INFORMATION ----------------------------------------------------------
271
272   See the doc directory for more documentation on various features. Again,
273 please read all the configuration samples that include documentation on
274 the configuration options.
275
276   If this release of Asterisk was downloaded from a tarball, then some
277 additional documentation should have been included.
278      * doc/tex/asterisk.pdf --- PDF version of the documentation
279      * doc/tex/asterisk/index.html --- HTML version of the documentation
280
281   Finally, you may wish to visit the web site and join the mailing list if
282 you're interested in getting more information.
283
284    http://www.asterisk.org/support
285
286   Welcome to the growing worldwide community of Asterisk users!
287 -------------------------------------------------------------------------------
288
289 --- Mark Spencer, and the Asterisk.org development community
290
291 -------------------------------------------------------------------------------
292 Asterisk is a trademark of Digium, Inc.