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