[Asterisk-code-review] README: Convert to README.md. (asterisk[15])
Joshua Colp
asteriskteam at digium.com
Thu Nov 23 10:15:38 CST 2017
Joshua Colp has submitted this change and it was merged. ( https://gerrit.asterisk.org/7345 )
Change subject: README: Convert to README.md.
......................................................................
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
---
D README
A README.md
2 files changed, 272 insertions(+), 296 deletions(-)
Approvals:
Kevin Harwell: Looks good to me, but someone else must approve
Joshua Colp: Looks good to me, approved
Jenkins2: Approved for Submit
diff --git a/README b/README
deleted file mode 100644
index a1ccf2c..0000000
--- a/README
+++ /dev/null
@@ -1,296 +0,0 @@
-===============================================================================
-=== The Asterisk(R) Open Source PBX
-===
-=== by Mark Spencer <markster at digium.com>
-=== 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 at:
-
- https://www.asterisk.org
-
- The official Asterisk wiki can be found at:
-
- 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
-License. It is available in book stores as well as in a downloadable version on
-the http://www.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 (www.digium.com)
- * 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 README 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. They are all 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) "make samples"
-
- Doing so will overwrite any existing configuration files you have installed.
-
- 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 <command>". 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 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 (http://www.ntp.org/) 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:
-
-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.
-
- If this release of Asterisk was downloaded from a tarball, then some
-additional documentation should have been included.
- * 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
-you're interested in getting more information.
-
- 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.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..4ed9b3e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,272 @@
+# The Asterisk(R) Open Source PBX
+```text
+ By Mark Spencer <markster at digium.com> 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 <command>". 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
+
--
To view, visit https://gerrit.asterisk.org/7345
To unsubscribe, visit https://gerrit.asterisk.org/settings
Gerrit-Project: asterisk
Gerrit-Branch: 15
Gerrit-MessageType: merged
Gerrit-Change-Id: I7d13131764a9a9026e5f8a6ddb245a01bbd788e7
Gerrit-Change-Number: 7345
Gerrit-PatchSet: 1
Gerrit-Owner: Corey Farrell <git at cfware.com>
Gerrit-Reviewer: Jenkins2
Gerrit-Reviewer: Joshua Colp <jcolp at digium.com>
Gerrit-Reviewer: Kevin Harwell <kharwell at digium.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20171123/e5df670d/attachment-0001.html>
More information about the asterisk-code-review
mailing list