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