mirror of
https://github.com/asterisk/asterisk.git
synced 2025-09-04 20:04:50 +00:00
Merge "README: Convert to README.md."
This commit is contained in:
Joshua Colp
Gerrit Code Review
@@ -1,15 +1,9 @@
|
|||||||
===============================================================================
|
# The Asterisk(R) Open Source PBX
|
||||||
=== The Asterisk(R) Open Source PBX
|
```text
|
||||||
===
|
By Mark Spencer <markster@digium.com> and the Asterisk.org developer community.
|
||||||
=== by Mark Spencer <markster@digium.com>
|
Copyright (C) 2001-2016 Digium, Inc. and other copyright holders.
|
||||||
=== and the Asterisk.org developer community
|
```
|
||||||
===
|
## SECURITY
|
||||||
=== Copyright (C) 2001-2016 Digium, Inc.
|
|
||||||
=== and other copyright holders.
|
|
||||||
===============================================================================
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
--- SECURITY ------------------------------------------------------------------
|
|
||||||
|
|
||||||
It is imperative that you read and fully understand the contents of
|
It is imperative that you read and fully understand the contents of
|
||||||
the security information document before you attempt to configure and run
|
the security information document before you attempt to configure and run
|
||||||
@@ -19,80 +13,62 @@ an Asterisk server.
|
|||||||
version of the documentation in doc/tex/asterisk.pdf. Alternatively, pull up
|
version of the documentation in doc/tex/asterisk.pdf. Alternatively, pull up
|
||||||
the HTML version of the documentation in doc/tex/asterisk/index.html. The
|
the HTML version of the documentation in doc/tex/asterisk/index.html. The
|
||||||
source for the security document is available in doc/tex/security.tex.
|
source for the security document is available in doc/tex/security.tex.
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
## WHAT IS ASTERISK ?
|
||||||
--- WHAT IS ASTERISK ? --------------------------------------------------------
|
|
||||||
|
|
||||||
Asterisk is an Open Source PBX and telephony toolkit. It is, in a
|
Asterisk is an Open Source PBX and telephony toolkit. It is, in a
|
||||||
sense, middleware between Internet and telephony channels on the bottom,
|
sense, middleware between Internet and telephony channels on the bottom,
|
||||||
and Internet and telephony applications at the top. However, Asterisk supports
|
and Internet and telephony applications at the top. However, Asterisk supports
|
||||||
more telephony interfaces than just Internet telephony. Asterisk also has a
|
more telephony interfaces than just Internet telephony. Asterisk also has a
|
||||||
vast amount of support for traditional PSTN telephony, as well. For more
|
vast amount of support for traditional PSTN telephony, as well.
|
||||||
information on the project itself, please visit the Asterisk home page at:
|
|
||||||
|
|
||||||
https://www.asterisk.org
|
For more information on the project itself, please visit the Asterisk
|
||||||
|
[home page] and the official [wiki]. In addition you'll find lots
|
||||||
The official Asterisk wiki can be found at:
|
of information compiled by the Asterisk community at [voip-info.org].
|
||||||
|
|
||||||
https://wiki.asterisk.org
|
|
||||||
|
|
||||||
In addition you'll find lots of information compiled by the Asterisk
|
|
||||||
community on this Wiki:
|
|
||||||
|
|
||||||
https://www.voip-info.org/wiki-Asterisk
|
|
||||||
|
|
||||||
There is a book on Asterisk published by O'Reilly under the Creative Commons
|
There is a book on Asterisk published by O'Reilly under the Creative Commons
|
||||||
License. It is available in book stores as well as in a downloadable version on
|
License. It is available in book stores as well as in a downloadable version on
|
||||||
the http://www.asteriskdocs.org web site.
|
the [asteriskdocs.org] web site.
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
## SUPPORTED OPERATING SYSTEMS
|
||||||
--- SUPPORTED OPERATING SYSTEMS -----------------------------------------------
|
|
||||||
|
### Linux
|
||||||
|
|
||||||
--- Linux
|
|
||||||
The Asterisk Open Source PBX is developed and tested primarily on the
|
The Asterisk Open Source PBX is developed and tested primarily on the
|
||||||
GNU/Linux operating system, and is supported on every major GNU/Linux
|
GNU/Linux operating system, and is supported on every major GNU/Linux
|
||||||
distribution.
|
distribution.
|
||||||
|
|
||||||
--- Others
|
### Others
|
||||||
|
|
||||||
Asterisk has also been 'ported' and reportedly runs properly on other
|
Asterisk has also been 'ported' and reportedly runs properly on other
|
||||||
operating systems as well, including Sun Solaris, Apple's Mac OS X, Cygwin,
|
operating systems as well, including Sun Solaris, Apple's Mac OS X, Cygwin,
|
||||||
and the BSD variants.
|
and the BSD variants.
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
## GETTING STARTED
|
||||||
--- GETTING STARTED -----------------------------------------------------------
|
|
||||||
|
|
||||||
First, be sure you've got supported hardware (but note that you don't need
|
First, be sure you've got supported hardware (but note that you don't need
|
||||||
ANY special hardware, not even a sound card) to install and run Asterisk.
|
ANY special hardware, not even a sound card) to install and run Asterisk.
|
||||||
|
|
||||||
Supported telephony hardware includes:
|
Supported telephony hardware includes:
|
||||||
|
* All Analog and Digital Interface cards from [Digium]
|
||||||
|
* QuickNet Internet PhoneJack and LineJack (http://www.quicknet.net)
|
||||||
|
* any full duplex sound card supported by ALSA, OSS, or PortAudio
|
||||||
|
* any ISDN card supported by mISDN on Linux
|
||||||
|
* The Xorcom Astribank channel bank
|
||||||
|
* VoiceTronix OpenLine products
|
||||||
|
|
||||||
* All Analog and Digital Interface cards from Digium (www.digium.com)
|
### UPGRADING FROM AN EARLIER VERSION
|
||||||
* QuickNet Internet PhoneJack and LineJack (http://www.quicknet.net)
|
|
||||||
* any full duplex sound card supported by ALSA, OSS, or PortAudio
|
|
||||||
* any ISDN card supported by mISDN on Linux
|
|
||||||
* The Xorcom Astribank channel bank
|
|
||||||
* VoiceTronix OpenLine products
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
--- UPGRADING FROM AN EARLIER VERSION -----------------------------------------
|
|
||||||
|
|
||||||
If you are updating from a previous version of Asterisk, make sure you
|
If you are updating from a previous version of Asterisk, make sure you
|
||||||
read the UPGRADE.txt file in the source directory. There are some files
|
read the [UPGRADE.txt] file in the source directory. There are some files
|
||||||
and configuration options that you will have to change, even though we
|
and configuration options that you will have to change, even though we
|
||||||
made every effort possible to maintain backwards compatibility.
|
made every effort possible to maintain backwards compatibility.
|
||||||
|
|
||||||
In order to discover new features to use, please check the configuration
|
In order to discover new features to use, please check the configuration
|
||||||
examples in the /configs directory of the source code distribution. For a
|
examples in the [configs] directory of the source code distribution. For a
|
||||||
list of new features in this version of Asterisk, see the CHANGES file.
|
list of new features in this version of Asterisk, see the [CHANGES] file.
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
### NEW INSTALLATIONS
|
||||||
--- NEW INSTALLATIONS ---------------------------------------------------------
|
|
||||||
|
|
||||||
Ensure that your system contains a compatible compiler and development
|
Ensure that your system contains a compatible compiler and development
|
||||||
libraries. Asterisk requires either the GNU Compiler Collection (GCC) version
|
libraries. Asterisk requires either the GNU Compiler Collection (GCC) version
|
||||||
@@ -101,55 +77,54 @@ the gcc language extensions. In addition, your system needs to have the C
|
|||||||
library headers available, and the headers and libraries for ncurses.
|
library headers available, and the headers and libraries for ncurses.
|
||||||
|
|
||||||
There are many modules that have additional dependencies. To see what
|
There are many modules that have additional dependencies. To see what
|
||||||
libraries are being looked for, see ./configure --help, or run
|
libraries are being looked for, see `./configure --help`, or run
|
||||||
"make menuselect" to view the dependencies for specific modules.
|
`make menuselect` to view the dependencies for specific modules.
|
||||||
|
|
||||||
On many distributions, these dependencies are installed by packages with names
|
On many distributions, these dependencies are installed by packages with names
|
||||||
like 'glibc-devel', 'ncurses-devel', 'openssl-devel' and 'zlib-devel'
|
like 'glibc-devel', 'ncurses-devel', 'openssl-devel' and 'zlib-devel'
|
||||||
or similar.
|
or similar.
|
||||||
|
|
||||||
So, let's proceed:
|
So, let's proceed:
|
||||||
|
1. Read this file.
|
||||||
|
|
||||||
1) Read this README file.
|
There are more documents than this one in the [doc] directory. You may also
|
||||||
|
|
||||||
There are more documents than this one in the doc/ directory. You may also
|
|
||||||
want to check the configuration files that contain examples and reference
|
want to check the configuration files that contain examples and reference
|
||||||
guides. They are all in the configs/ directory.
|
guides in the [configs] directory.
|
||||||
|
|
||||||
2) Run "./configure"
|
2. Run `./configure`
|
||||||
|
|
||||||
Execute the configure script to guess values for system-dependent
|
Execute the configure script to guess values for system-dependent
|
||||||
variables used during compilation.
|
variables used during compilation.
|
||||||
|
|
||||||
3) Run "make menuselect" [optional]
|
3. Run `make menuselect` _\[optional]_
|
||||||
|
|
||||||
This is needed if you want to select the modules that will be compiled and to
|
This is needed if you want to select the modules that will be compiled and to
|
||||||
check dependencies for various optional modules.
|
check dependencies for various optional modules.
|
||||||
|
|
||||||
4) Run "make"
|
4. Run `make`
|
||||||
|
|
||||||
Assuming the build completes successfully:
|
Assuming the build completes successfully:
|
||||||
|
|
||||||
5) Run "make install"
|
5. Run `make install`
|
||||||
|
|
||||||
If this is your first time working with Asterisk, you may wish to install
|
If this is your first time working with Asterisk, you may wish to install
|
||||||
the sample PBX, with demonstration extensions, etc. If so, run:
|
the sample PBX, with demonstration extensions, etc. If so, run:
|
||||||
|
|
||||||
6) "make samples"
|
6. Run `make samples`
|
||||||
|
|
||||||
Doing so will overwrite any existing configuration files you have installed.
|
Doing so will overwrite any existing configuration files you have installed.
|
||||||
|
|
||||||
Finally, you can launch Asterisk in the foreground mode (not a daemon) with:
|
7. Finally, you can launch Asterisk in the foreground mode (not a daemon) with:
|
||||||
|
```
|
||||||
# asterisk -vvvc
|
# asterisk -vvvc
|
||||||
|
```
|
||||||
You'll see a bunch of verbose messages fly by your screen as Asterisk
|
You'll see a bunch of verbose messages fly by your screen as Asterisk
|
||||||
initializes (that's the "very very verbose" mode). When it's ready, if
|
initializes (that's the "very very verbose" mode). When it's ready, if
|
||||||
you specified the "c" then you'll get a command line console, that looks
|
you specified the "c" then you'll get a command line console, that looks
|
||||||
like this:
|
like this:
|
||||||
|
```
|
||||||
*CLI>
|
*CLI>
|
||||||
|
```
|
||||||
You can type "core show help" at any time to get help with the system. For help
|
You can type "core show help" at any time to get help with the system. For help
|
||||||
with a specific command, type "core show help <command>". To start the PBX using
|
with a specific command, type "core show help <command>". To start the PBX using
|
||||||
your sound card, you can type "console dial" to dial the PBX. Then you can use
|
your sound card, you can type "console dial" to dial the PBX. Then you can use
|
||||||
@@ -162,12 +137,10 @@ then it won't work right (not yet).
|
|||||||
information on how to start and stop Asterisk, as well as all the command
|
information on how to start and stop Asterisk, as well as all the command
|
||||||
line options for starting Asterisk.
|
line options for starting Asterisk.
|
||||||
|
|
||||||
Feel free to look over the configuration files in /etc/asterisk, where you
|
Feel free to look over the configuration files in `/etc/asterisk`, where you
|
||||||
will find a lot of information about what you can do with Asterisk.
|
will find a lot of information about what you can do with Asterisk.
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
### ABOUT CONFIGURATION FILES
|
||||||
--- ABOUT CONFIGURATION FILES -------------------------------------------------
|
|
||||||
|
|
||||||
All Asterisk configuration files share a common format. Comments are
|
All Asterisk configuration files share a common format. Comments are
|
||||||
delimited by ';' (since '#' of course, being a DTMF digit, may occur in
|
delimited by ';' (since '#' of course, being a DTMF digit, may occur in
|
||||||
@@ -179,20 +152,21 @@ they're used only to help make the configuration file easier to
|
|||||||
understand, and do not affect how it is actually parsed.
|
understand, and do not affect how it is actually parsed.
|
||||||
|
|
||||||
Entries of the form 'variable=value' set the value of some parameter in
|
Entries of the form 'variable=value' set the value of some parameter in
|
||||||
asterisk. For example, in dahdi.conf, one might specify:
|
asterisk. For example, in [chan_dahdi.conf], one might specify:
|
||||||
|
```
|
||||||
switchtype=national
|
switchtype=national
|
||||||
|
```
|
||||||
In order to indicate to Asterisk that the switch they are connecting to is
|
In order to indicate to Asterisk that the switch they are connecting to is
|
||||||
of the type "national". In general, the parameter will apply to
|
of the type "national". In general, the parameter will apply to
|
||||||
instantiations which occur below its specification. For example, if the
|
instantiations which occur below its specification. For example, if the
|
||||||
configuration file read:
|
configuration file read:
|
||||||
|
```
|
||||||
switchtype = national
|
switchtype = national
|
||||||
channel => 1-4
|
channel => 1-4
|
||||||
channel => 10-12
|
channel => 10-12
|
||||||
switchtype = dms100
|
switchtype = dms100
|
||||||
channel => 25-47
|
channel => 25-47
|
||||||
|
```
|
||||||
|
|
||||||
The "national" switchtype would be applied to channels one through
|
The "national" switchtype would be applied to channels one through
|
||||||
four and channels 10 through 12, whereas the "dms100" switchtype would
|
four and channels 10 through 12, whereas the "dms100" switchtype would
|
||||||
@@ -202,16 +176,14 @@ apply to channels 25 through 47.
|
|||||||
parameters. For example, the line "channel => 25-47" creates objects for
|
parameters. For example, the line "channel => 25-47" creates objects for
|
||||||
the channels 25 through 47 of the card, obtaining the settings
|
the channels 25 through 47 of the card, obtaining the settings
|
||||||
from the variables specified above.
|
from the variables specified above.
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
### SPECIAL NOTE ON TIME
|
||||||
--- SPECIAL NOTE ON TIME ------------------------------------------------------
|
|
||||||
|
|
||||||
Those using SIP phones should be aware that Asterisk is sensitive to
|
Those using SIP phones should be aware that Asterisk is sensitive to
|
||||||
large jumps in time. Manually changing the system time using date(1)
|
large jumps in time. Manually changing the system time using date(1)
|
||||||
(or other similar commands) may cause SIP registrations and other
|
(or other similar commands) may cause SIP registrations and other
|
||||||
internal processes to fail. If your system cannot keep accurate time
|
internal processes to fail. If your system cannot keep accurate time
|
||||||
by itself use NTP (http://www.ntp.org/) to keep the system clock
|
by itself use [NTP] to keep the system clock
|
||||||
synchronized to "real time". NTP is designed to keep the system clock
|
synchronized to "real time". NTP is designed to keep the system clock
|
||||||
synchronized by speeding up or slowing down the system clock until it
|
synchronized by speeding up or slowing down the system clock until it
|
||||||
is synchronized to "real time" rather than by jumping the time and
|
is synchronized to "real time" rather than by jumping the time and
|
||||||
@@ -228,10 +200,8 @@ on UTC. UTC does not use daylight savings time.
|
|||||||
|
|
||||||
Also note that this issue is separate from the clocking of TDM
|
Also note that this issue is separate from the clocking of TDM
|
||||||
channels, and is known to at least affect SIP registrations.
|
channels, and is known to at least affect SIP registrations.
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
### FILE DESCRIPTORS
|
||||||
--- FILE DESCRIPTORS ----------------------------------------------------------
|
|
||||||
|
|
||||||
Depending on the size of your system and your configuration,
|
Depending on the size of your system and your configuration,
|
||||||
Asterisk can consume a large number of file descriptors. In UNIX,
|
Asterisk can consume a large number of file descriptors. In UNIX,
|
||||||
@@ -247,50 +217,56 @@ calls that your system can handle. For example, if the limit is set
|
|||||||
at 1024 (a common default value) Asterisk can handle approximately 150
|
at 1024 (a common default value) Asterisk can handle approximately 150
|
||||||
SIP calls simultaneously. To change the number of file descriptors
|
SIP calls simultaneously. To change the number of file descriptors
|
||||||
follow the instructions for your system below:
|
follow the instructions for your system below:
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
#### PAM-BASED LINUX SYSTEM
|
||||||
--- PAM-based Linux System ----------------------------------------------------
|
|
||||||
|
|
||||||
If your system uses PAM (Pluggable Authentication Modules) edit
|
If your system uses PAM (Pluggable Authentication Modules) edit
|
||||||
/etc/security/limits.conf. Add these lines to the bottom of the file:
|
`/etc/security/limits.conf`. Add these lines to the bottom of the file:
|
||||||
|
```text
|
||||||
root soft nofile 4096
|
root soft nofile 4096
|
||||||
root hard nofile 8196
|
root hard nofile 8196
|
||||||
asterisk soft nofile 4096
|
asterisk soft nofile 4096
|
||||||
asterisk hard nofile 8196
|
asterisk hard nofile 8196
|
||||||
|
```
|
||||||
|
|
||||||
(adjust the numbers to taste). You may need to reboot the system for
|
(adjust the numbers to taste). You may need to reboot the system for
|
||||||
these changes to take effect.
|
these changes to take effect.
|
||||||
|
|
||||||
== Generic UNIX System ==
|
#### GENERIC UNIX SYSTEM
|
||||||
|
|
||||||
If there are no instructions specifically adapted to your system
|
If there are no instructions specifically adapted to your system
|
||||||
above you can try adding the command "ulimit -n 8192" to the script
|
above you can try adding the command `ulimit -n 8192` to the script
|
||||||
that starts Asterisk.
|
that starts Asterisk.
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
## MORE INFORMATION
|
||||||
--- MORE INFORMATION ----------------------------------------------------------
|
|
||||||
|
|
||||||
See the doc directory for more documentation on various features. Again,
|
See the [doc] directory for more documentation on various features.
|
||||||
please read all the configuration samples that include documentation on
|
Again, please read all the configuration samples that include documentation
|
||||||
the configuration options.
|
on the configuration options.
|
||||||
|
|
||||||
If this release of Asterisk was downloaded from a tarball, then some
|
Finally, you may wish to visit the [support] site and join the [mailing
|
||||||
additional documentation should have been included.
|
list] if you're interested in getting more information.
|
||||||
* doc/tex/asterisk.pdf --- PDF version of the documentation
|
|
||||||
* doc/tex/asterisk/index.html --- HTML version of the documentation
|
|
||||||
|
|
||||||
Finally, you may wish to visit the web site and join the mailing list if
|
Welcome to the growing worldwide community of Asterisk users!
|
||||||
you're interested in getting more information.
|
```
|
||||||
|
Mark Spencer, and the Asterisk.org development community
|
||||||
|
```
|
||||||
|
|
||||||
https://www.asterisk.org/support
|
---
|
||||||
|
|
||||||
Welcome to the growing worldwide community of Asterisk users!
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
|
|
||||||
--- Mark Spencer, and the Asterisk.org development community
|
|
||||||
|
|
||||||
-------------------------------------------------------------------------------
|
|
||||||
Asterisk is a trademark of Digium, Inc.
|
Asterisk is a trademark of Digium, Inc.
|
||||||
|
|
||||||
|
[home page]: https://www.asterisk.org
|
||||||
|
[support]: https://www.asterisk.org/support
|
||||||
|
[wiki]: https://wiki.asterisk.org/
|
||||||
|
[mailing list]: http://lists.digium.com/mailman/listinfo/asterisk-users
|
||||||
|
[chan_dahdi.conf]: configs/samples/chan_dahdi.conf.sample
|
||||||
|
[voip-info.org]: http://www.voip-info.org/wiki-Asterisk
|
||||||
|
[asteriskdocs.org]: http://www.asteriskdocs.org
|
||||||
|
[NTP]: http://www.ntp.org/
|
||||||
|
[Digium]: https://www.digium.com/
|
||||||
|
[UPGRADE.txt]: UPGRADE.txt
|
||||||
|
[CHANGES]: CHANGES
|
||||||
|
[configs]: configs
|
||||||
|
[doc]: doc
|
||||||
|
|
||||||
Reference in New Issue
Block a user