asterisk/README.html

<html><head><title>Readme for asterisk-20.22.0-rc2</title></head><body>

<h1 dir="auto">The Asterisk(R) Open Source PBX</h1>
<pre class="notranslate"><code class="notranslate">By Mark Spencer &lt;markster@digium.com&gt; and the Asterisk.org developer community.
Copyright (C) 2001-2025 Sangoma Technologies Corporation and other copyright holders.
</code></pre>
<h2 dir="auto">SECURITY</h2>
<p dir="auto">It is imperative that you read and fully understand the contents of<br>
the security information document before you attempt to configure and run<br>
an Asterisk server.</p>
<p dir="auto">See <a href="https://docs.asterisk.org/Deployment/Important-Security-Considerations" rel="nofollow">Important Security Considerations</a> for more information.</p>
<h2 dir="auto">WHAT IS ASTERISK ?</h2>
<p dir="auto">Asterisk is an Open Source PBX and telephony toolkit.  It is, in a<br>
sense, middleware between Internet and telephony channels on the bottom,<br>
and Internet and telephony applications at the top.  However, Asterisk supports<br>
more telephony interfaces than just Internet telephony.  Asterisk also has a<br>
vast amount of support for traditional PSTN telephony, as well.</p>
<p dir="auto">For more information on the project itself, please visit the <a href="https://www.asterisk.org" rel="nofollow">Asterisk<br>
Home Page</a> and the official<br>
<a href="https://docs.asterisk.org" rel="nofollow">Asterisk Documentation</a>.</p>
<h2 dir="auto">SUPPORTED OPERATING SYSTEMS</h2>
<h3 dir="auto">Linux</h3>
<p dir="auto">The Asterisk Open Source PBX is developed and tested primarily on the<br>
GNU/Linux operating system, and is supported on every major GNU/Linux<br>
distribution.</p>
<h3 dir="auto">Others</h3>
<p dir="auto">Asterisk has also been 'ported' and reportedly runs properly on other<br>
operating systems as well, Apple's Mac OS X, and the BSD variants.</p>
<h2 dir="auto">GETTING STARTED</h2>
<p dir="auto">Most users are using VoIP/SIP exclusively these days but if you need to<br>
interface to TDM or analog services or devices, be sure you've got supported<br>
hardware.</p>
<p dir="auto">Supported telephony hardware includes:</p>
<ul dir="auto">
<li>All Analog and Digital Interface cards from Sangoma</li>
<li>Any full duplex sound card supported by PortAudio</li>
<li>The Xorcom Astribank channel bank</li>
</ul>
<h3 dir="auto">UPGRADING FROM AN EARLIER VERSION</h3>
<p dir="auto">If you are updating from a previous version of Asterisk, make sure you<br>
read the Change Logs.</p>

<p dir="auto"><a href="ChangeLogs/ChangeLog-20.22.0-rc2.html">Change Logs</a></p>

<h3 dir="auto">NEW INSTALLATIONS</h3>
<p dir="auto">Ensure that your system contains a compatible compiler and development<br>
libraries.  Asterisk requires either the GNU Compiler Collection (GCC) version<br>
4.1 or higher, or a compiler that supports the C99 specification and some of<br>
the gcc language extensions.  In addition, your system needs to have the C<br>
library headers available, and the headers and libraries for ncurses.</p>
<p dir="auto">There are many modules that have additional dependencies.  To see what<br>
libraries are being looked for, see <code class="notranslate">./configure --help</code>, or run<br>
<code class="notranslate">make menuselect</code> to view the dependencies for specific modules.</p>
<p dir="auto">On many distributions, these dependencies are installed by packages with names<br>
like 'glibc-devel', 'ncurses-devel', 'openssl-devel' and 'zlib-devel'<br>
or similar.  The <code class="notranslate">contrib/scripts/install_prereq</code> script can be used to install<br>
the dependencies for most Debian and Redhat based Linux distributions.<br>
The script also handles SUSE, Arch, Gentoo, FreeBSD, NetBSD and OpenBSD but<br>
those distributions mightnoit have complete support or they might be out of date.</p>
<p dir="auto">So, let's proceed:</p>
<ol dir="auto">
<li>
<p dir="auto">Read the documentation.<br><br>
The <a href="https://docs.asterisk.org" rel="nofollow">Asterisk Documentation</a> website has full<br>
information for building, installing, configuring and running Asterisk.</p>
</li>
<li>
<p dir="auto">Run <code class="notranslate">./configure</code><br><br>
Execute the configure script to guess values for system-dependent<br>
variables used during compilation. If the script indicates that some required<br>
components are missing, you can run <code class="notranslate">./contrib/scripts/install_prereq install</code><br>
to install the necessary components. Note that this will install all dependencies<br>
for every functionality of Asterisk. After running the script, you will need<br>
to rerun <code class="notranslate">./configure</code>.</p>
</li>
<li>
<p dir="auto">Run <code class="notranslate">make menuselect</code><br><br>
This is needed if you want to select the modules that will be compiled and to<br>
check dependencies for various optional modules.</p>
</li>
<li>
<p dir="auto">Run <code class="notranslate">make</code><br><br>
Assuming the build completes successfully:</p>
</li>
<li>
<p dir="auto">Run <code class="notranslate">make install</code><br><br>
If this is your first time working with Asterisk, you may wish to install<br>
the sample PBX, with demonstration extensions, etc.  If so, run:</p>
</li>
<li>
<p dir="auto">Run <code class="notranslate">make samples</code><br><br>
Doing so will overwrite any existing configuration files you have installed.</p>
</li>
<li>
<p dir="auto">Finally, you can launch Asterisk in the foreground mode (not a daemon) with<br>
<code class="notranslate">asterisk -vvvc</code><br><br>
You'll see a bunch of verbose messages fly by your screen as Asterisk<br>
initializes (that's the "very very verbose" mode).  When it's ready, if<br>
you specified the "c" then you'll get a command line console, that looks<br>
like this:<br><br>
<code class="notranslate">*CLI&gt;</code><br><br>
You can type <code class="notranslate">core show help</code> at any time to get help with the system.  For help<br>
with a specific command, type <code class="notranslate">core show help &lt;command&gt;</code>.</p>
</li>
</ol>
<p dir="auto"><code class="notranslate">man asterisk</code> at the Unix/Linux command prompt will give you detailed<br>
information on how to start and stop Asterisk, as well as all the command<br>
line options for starting Asterisk.</p>
<h3 dir="auto">ABOUT CONFIGURATION FILES</h3>
<p dir="auto">All Asterisk configuration files share a common format.  Comments are<br>
delimited by <code class="notranslate">;</code> (since <code class="notranslate">#</code> of course, being a DTMF digit, may occur in<br>
many places).  A configuration file is divided into sections whose names<br>
appear in <code class="notranslate">[]</code>'s.  Each section typically contains statements in the form<br>
<code class="notranslate">variable = value</code> although you may see <code class="notranslate">variable =&gt; value</code> in older samples.</p>
<h3 dir="auto">SPECIAL NOTE ON TIME</h3>
<p dir="auto">Those using SIP phones should be aware that Asterisk is sensitive to<br>
large jumps in time.  Manually changing the system time using date(1)<br>
(or other similar commands) may cause SIP registrations and other<br>
internal processes to fail.  For this reason, you should always use<br>
a time synchronization package to keep your system time accurate.<br>
All OS/distributions make one or more of the following packages<br>
available:</p>
<ul dir="auto">
<li>ntpd/ntpsec</li>
<li>chronyd</li>
<li>systemd-timesyncd</li>
</ul>
<p dir="auto">Be sure to install and configure one (and only one) of them.</p>
<h3 dir="auto">FILE DESCRIPTORS</h3>
<p dir="auto">Depending on the size of your system and your configuration,<br>
Asterisk can consume a large number of file descriptors.  In UNIX,<br>
file descriptors are used for more than just files on disk.  File<br>
descriptors are also used for handling network communication<br>
(e.g. SIP, IAX2, or H.323 calls) and hardware access (e.g. analog and<br>
digital trunk hardware).  Asterisk accesses many on-disk files for<br>
everything from configuration information to voicemail storage.</p>
<p dir="auto">Most systems limit the number of file descriptors that Asterisk can<br>
have open at one time.  This can limit the number of simultaneous<br>
calls that your system can handle.  For example, if the limit is set<br>
at 1024 (a common default value) Asterisk can handle approximately 150<br>
SIP calls simultaneously.  To change the number of file descriptors<br>
follow the instructions for your system below:</p>
<h4 dir="auto">PAM-BASED LINUX SYSTEM</h4>
<p dir="auto">If your system uses PAM (Pluggable Authentication Modules) edit<br>
<code class="notranslate">/etc/security/limits.conf</code>.  Add these lines to the bottom of the file:</p>
<pre lang="text" class="notranslate"><code class="notranslate">root            soft    nofile          4096
root            hard    nofile          8196
asterisk        soft    nofile          4096
asterisk        hard    nofile          8196
</code></pre>
<p dir="auto">(adjust the numbers to taste).  You may need to reboot the system for<br>
these changes to take effect.</p>
<h4 dir="auto">GENERIC UNIX SYSTEM</h4>
<p dir="auto">If there are no instructions specifically adapted to your system<br>
above you can try adding the command <code class="notranslate">ulimit -n 8192</code> to the script<br>
that starts Asterisk.</p>
<h2 dir="auto">MORE INFORMATION</h2>
<p dir="auto">Visit the <a href="https://docs.asterisk.org" rel="nofollow">Asterisk Documentation</a> website<br>
for more documentation on various features and please read all the<br>
configuration samples that include documentation on the configuration options.</p>
<p dir="auto">Finally, you may wish to join the<br>
<a href="https://community.asterisk.org" rel="nofollow">Asterisk Community Forums</a></p>
<p dir="auto">Welcome to the growing worldwide community of Asterisk users!</p>
<pre class="notranslate"><code class="notranslate">        Mark Spencer, and the Asterisk.org development community
</code></pre>
<hr>
<p dir="auto">Asterisk is a trademark of Sangoma Technologies Corporation</p>
<p dir="auto">[<a href="https://www.sangoma.com/" rel="nofollow">Sangoma</a>]<br>
[<a href="https://www.asterisk.org" rel="nofollow">Home Page</a>]<br>
[<a href="https://www.asterisk.org/support" rel="nofollow">Support</a>]<br>
[<a href="https://docs.asterisk.org" rel="nofollow">Documentation</a>]<br>
[<a href="https://community.asterisk.org" rel="nofollow">Community Forums</a>]<br>
[<a href="https://github.com/asterisk/asterisk/releases">Release Notes</a>]<br>
[<a href="https://docs.asterisk.org/Deployment/Important-Security-Considerations/" rel="nofollow">Security</a>]<br>
[<a href="https://lists.digium.com" rel="nofollow">Mailing List Archive</a>]</p>
</body></html>