From 90f9885f73f9ea3f4553c7968419275e49dc334c Mon Sep 17 00:00:00 2001 From: Corey Farrell Date: Fri, 17 Nov 2017 22:33:04 -0500 Subject: README: Convert to README.md. Convert the README file to markdown format, remove the old README. This causes websites like github to display the README in a much nicer format with live links. The raw file is still very readable from plain text editors and terminals. Change-Id: I7d13131764a9a9026e5f8a6ddb245a01bbd788e7 --- README.md | 272 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 000000000..4ed9b3eec --- /dev/null +++ b/README.md @@ -0,0 +1,272 @@ +# The Asterisk(R) Open Source PBX +```text + By Mark Spencer and the Asterisk.org developer community. + Copyright (C) 2001-2016 Digium, Inc. and other copyright holders. +``` +## SECURITY + + It is imperative that you read and fully understand the contents of +the security information document before you attempt to configure and run +an Asterisk server. + + If you downloaded Asterisk as a tarball, see the security section in the PDF +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 +source for the security document is available in doc/tex/security.tex. + +## WHAT IS ASTERISK ? + + Asterisk is an Open Source PBX and telephony toolkit. It is, in a +sense, middleware between Internet and telephony channels on the bottom, +and Internet and telephony applications at the top. However, Asterisk supports +more telephony interfaces than just Internet telephony. Asterisk also has a +vast amount of support for traditional PSTN telephony, as well. + + For more information on the project itself, please visit the Asterisk +[home page] and the official [wiki]. In addition you'll find lots +of information compiled by the Asterisk community at [voip-info.org]. + + 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 +the [asteriskdocs.org] web site. + +## SUPPORTED OPERATING SYSTEMS + +### Linux + + The Asterisk Open Source PBX is developed and tested primarily on the +GNU/Linux operating system, and is supported on every major GNU/Linux +distribution. + +### Others + + Asterisk has also been 'ported' and reportedly runs properly on other +operating systems as well, including Sun Solaris, Apple's Mac OS X, Cygwin, +and the BSD variants. + +## GETTING STARTED + + 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. + +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 + +### UPGRADING FROM AN EARLIER VERSION + + 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 +and configuration options that you will have to change, even though we +made every effort possible to maintain backwards compatibility. + + In order to discover new features to use, please check the configuration +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. + +### NEW INSTALLATIONS + + Ensure that your system contains a compatible compiler and development +libraries. Asterisk requires either the GNU Compiler Collection (GCC) version +3.0 or higher, or a compiler that supports the C99 specification and some of +the gcc language extensions. In addition, your system needs to have the C +library headers available, and the headers and libraries for ncurses. + + There are many modules that have additional dependencies. To see what +libraries are being looked for, see `./configure --help`, or run +`make menuselect` to view the dependencies for specific modules. + + On many distributions, these dependencies are installed by packages with names +like 'glibc-devel', 'ncurses-devel', 'openssl-devel' and 'zlib-devel' +or similar. + +So, let's proceed: +1. Read this file. + + 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 +guides in the [configs] directory. + +2. Run `./configure` + + Execute the configure script to guess values for system-dependent +variables used during compilation. + +3. Run `make menuselect` _\[optional]_ + + This is needed if you want to select the modules that will be compiled and to +check dependencies for various optional modules. + +4. Run `make` + +Assuming the build completes successfully: + +5. Run `make 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: + +6. Run `make samples` + + Doing so will overwrite any existing configuration files you have installed. + +7. Finally, you can launch Asterisk in the foreground mode (not a daemon) with: +``` + # asterisk -vvvc +``` + 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 +you specified the "c" then you'll get a command line console, that looks +like this: +``` + *CLI> +``` + 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 ". To start the PBX using +your sound card, you can type "console dial" to dial the PBX. Then you can use +"console answer", "console hangup", and "console dial" to simulate the actions +of a telephone. Remember that if you don't have a full duplex sound card +(and Asterisk will tell you somewhere in its verbose messages if you do/don't) +then it won't work right (not yet). + + "man asterisk" at the Unix/Linux command prompt will give you detailed +information on how to start and stop Asterisk, as well as all the command +line options for starting Asterisk. + + 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. + +### ABOUT CONFIGURATION FILES + + All Asterisk configuration files share a common format. Comments are +delimited by ';' (since '#' of course, being a DTMF digit, may occur in +many places). A configuration file is divided into sections whose names +appear in []'s. Each section typically contains two types of statements, +those of the form 'variable = value', and those of the form 'object => +parameters'. Internally the use of '=' and '=>' is exactly the same, so +they're used only to help make the configuration file easier to +understand, and do not affect how it is actually parsed. + + Entries of the form 'variable=value' set the value of some parameter in +asterisk. For example, in [chan_dahdi.conf], one might specify: +``` + switchtype=national +``` + 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 +instantiations which occur below its specification. For example, if the +configuration file read: +``` + switchtype = national + channel => 1-4 + channel => 10-12 + switchtype = dms100 + channel => 25-47 +``` + + The "national" switchtype would be applied to channels one through +four and channels 10 through 12, whereas the "dms100" switchtype would +apply to channels 25 through 47. + + The "object => parameters" instantiates an object with the given +parameters. For example, the line "channel => 25-47" creates objects for +the channels 25 through 47 of the card, obtaining the settings +from the variables specified above. + +### SPECIAL NOTE ON TIME + + Those using SIP phones should be aware that Asterisk is sensitive to +large jumps in time. Manually changing the system time using date(1) +(or other similar commands) may cause SIP registrations and other +internal processes to fail. If your system cannot keep accurate time +by itself use [NTP] 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 +is synchronized to "real time" rather than by jumping the time and +causing discontinuities. Most Linux distributions include precompiled +versions of NTP. Beware of some time synchronization methods that get +the correct real time periodically and then manually set the system +clock. + + Apparent time changes due to daylight savings time are just that, +apparent. The use of daylight savings time in a Linux system is +purely a user interface issue and does not affect the operation of the +Linux kernel or Asterisk. The system clock on Linux kernels operates +on UTC. UTC does not use daylight savings time. + + Also note that this issue is separate from the clocking of TDM +channels, and is known to at least affect SIP registrations. + +### FILE DESCRIPTORS + + Depending on the size of your system and your configuration, +Asterisk can consume a large number of file descriptors. In UNIX, +file descriptors are used for more than just files on disk. File +descriptors are also used for handling network communication +(e.g. SIP, IAX2, or H.323 calls) and hardware access (e.g. analog and +digital trunk hardware). Asterisk accesses many on-disk files for +everything from configuration information to voicemail storage. + + Most systems limit the number of file descriptors that Asterisk can +have open at one time. This can limit the number of simultaneous +calls that your system can handle. For example, if the limit is set +at 1024 (a common default value) Asterisk can handle approximately 150 +SIP calls simultaneously. To change the number of file descriptors +follow the instructions for your system below: + +#### PAM-BASED LINUX SYSTEM + + If your system uses PAM (Pluggable Authentication Modules) edit +`/etc/security/limits.conf`. Add these lines to the bottom of the file: +```text +root soft nofile 4096 +root hard nofile 8196 +asterisk soft nofile 4096 +asterisk hard nofile 8196 +``` + +(adjust the numbers to taste). You may need to reboot the system for +these changes to take effect. + +#### GENERIC UNIX SYSTEM + + If there are no instructions specifically adapted to your system +above you can try adding the command `ulimit -n 8192` to the script +that starts Asterisk. + +## MORE INFORMATION + + See the [doc] directory for more documentation on various features. +Again, please read all the configuration samples that include documentation +on the configuration options. + + Finally, you may wish to visit the [support] site and join the [mailing +list] if you're interested in getting more information. + +Welcome to the growing worldwide community of Asterisk users! +``` + Mark Spencer, and the Asterisk.org development community +``` + +--- + +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 + -- cgit v1.2.3