README

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