Update README to reflect modern Asterisk features and requirements
[asterisk/asterisk.git] / README
1 The Asterisk Open Source PBX
2 by Mark Spencer <markster@digium.com>
3 Copyright (C) 2001-2005 Digium, Inc.
4 ================================================================
5 * SECURITY
6   It is imperative that you read and fully understand the contents of
7   the SECURITY file before you attempt to configure an Asterisk server.
8
9 * WHAT IS ASTERISK
10   Asterisk is an Open Source PBX and telephony toolkit.  It is, in a
11 sense, middleware between Internet and telephony channels on the bottom,
12 and Internet and telephony applications at the top.  For more information
13 on the project itself, please visit the Asterisk home page at:
14
15            http://www.asterisk.org
16
17 In addition you'll find lots of information compiled by the Asterisk
18 community on this Wiki:
19
20            http://www.voip-info.org/wiki-Asterisk
21
22 * LICENSING
23   Asterisk is distributed under GNU General Public License.  The GPL also
24 must apply to all loadable modules as well, except as defined below.
25
26   Digium, Inc. (formerly Linux Support Services) retains copyright and/or a
27 sufficient license to all components of the core Asterisk system, and therefore
28 can grant, at its sole discretion, the ability for companies, individuals, or
29 organizations to create proprietary or Open Source (but non-GPL'd) modules
30 which may be dynamically linked at runtime with the portions of Asterisk which
31 fall under our copyright/license umbrella, or are distributed under more
32 flexible licenses than GPL.  
33
34   If you wish to use our code in other GPL programs, don't worry -- there
35 is no requirement that you provide the same exemption in your GPL'd
36 products (although if you've written a module for Asterisk we would
37 strongly encourage you to make the same exemption that we do).
38
39   Specific permission is also granted to OpenSSL and OpenH323 to link with
40 Asterisk.
41
42   If you have any questions, whatsoever, regarding our licensing policy,
43 please contact us.
44
45   Modules that are GPL-licensed and not available under Digium's 
46 licensing scheme are added to the Asterisk-addons CVS module.
47   
48 * OPERATING SYSTEMS
49
50 == Linux ==
51   The Asterisk Open Source PBX is developed and tested primarily on the
52 GNU/Linux operating system, and is supported on every major GNU/Linux
53 distribution.
54
55 == Others ==
56   Asterisk has also been 'ported' and reportedly runs properly on other
57 operating systems as well, including Sun Solaris, Apple's Mac OS X, and
58 the BSD variants.
59
60 * GETTING STARTED
61
62   First, be sure you've got supported hardware (but note that you don't need
63 ANY special hardware, not even a soundcard) to install and run Asterisk.
64
65   Supported telephony hardware includes:
66
67         * All Wildcard (tm) products from Digium (www.digium.com)
68         * QuickNet Internet PhoneJack and LineJack (http://www.quicknet.net)
69         * any full duplex sound card supported by ALSA or OSS
70         * ISDN4Linux compatible ISDN card
71         * VoiceTronix OpenLine products
72
73 Hint: CAPI compatible ISDN cards can be run using the add-on channel chan_capi.
74
75   Second, ensure that your system contains a compatible compiler and development
76 libraries.  Asterisk requires either the GNU Compiler Collection (GCC) version
77 3.0 or higher, or a compiler that supports the C99 specification and some of
78 the gcc language extensions.  In addition, your system needs to have the C
79 library headers available, and the headers and libraries for OpenSSL and zlib.
80 On many distributions, these files are installed by packages with names like
81 'libc-devel', 'openssl-devel' and 'zlib-devel' or similar.
82
83   So let's proceed:
84
85 1) Run "make"
86
87   Assuming the build completes successfully:
88
89 2) Run "make install"
90
91   Each time you update or checkout from CVS, you are strongly encouraged 
92 to ensure all previous object files are removed to avoid internal 
93 inconsistency in Asterisk. Normally, this is automatically done with 
94 the presence of the file .cleancount, which increments each time a 'make clean'
95 is required, and the file .lastclean, which contains the last .cleancount used. 
96
97   If this is your first time working with Asterisk, you may wish to install
98 the sample PBX, with demonstration extensions, etc.  If so, run:
99
100 3) "make samples"
101
102   Doing so will overwrite any existing config files you have. If you are lacking a
103 soundcard you won't be able to use the DIAL command on the console, though.
104
105   Finally, you can launch Asterisk with:
106
107 # asterisk -vvvc
108
109   You'll see a bunch of verbose messages fly by your screen as Asterisk
110 initializes (that's the "very very verbose" mode).  When it's ready, if
111 you specified the "c" then you'll get a command line console, that looks
112 like this:
113
114 *CLI>
115
116   You can type "help" at any time to get help with the system.  For help
117 with a specific command, type "help <command>".  To start the PBX using
118 your sound card, you can type "dial" to dial the PBX.  Then you can use
119 "answer", "hangup", and "dial" to simulate the actions of a telephone.
120 Remember that if you don't have a full duplex sound card (and Asterisk
121 will tell you somewhere in its verbose messages if you do/don't) then it
122 won't work right (not yet).
123
124   Feel free to look over the configuration files in /etc/asterisk, where
125 you'll find a lot of information about what you can do with Asterisk.
126
127 * ABOUT CONFIGURATION FILES
128
129   All Asterisk configuration files share a common format.  Comments are
130 delimited by ';' (since '#' of course, being a DTMF digit, may occur in
131 many places).  A configuration file is divided into sections whose names
132 appear in []'s.  Each section typically contains two types of statements,
133 those of the form 'variable = value', and those of the form 'object =>
134 parameters'.  Internally the use of '=' and '=>' is exactly the same, so 
135 they're used only to help make the configuration file easier to
136 understand, and do not affect how it is actually parsed.
137
138   Entries of the form 'variable=value' set the value of some parameter in
139 asterisk.  For example, in zapata.conf, one might specify:
140
141         switchtype=national
142
143 in order to indicate to Asterisk that the switch they are connecting to is
144 of the type "national".  In general, the parameter will apply to
145 instantiations which occur below its specification.  For example, if the
146 configuration file read:
147
148         switchtype = national
149         channel => 1-4
150         channel => 10-12
151         switchtype = dms100
152         channel => 25-47
153
154 the "national" switchtype would be applied to channels one through
155 four and channels 10 through 12, whereas the "dms100" switchtype would
156 apply to channels 25 through 47.
157   
158   The "object => parameters" instantiates an object with the given
159 parameters.  For example, the line "channel => 25-47" creates objects for
160 the channels 25 through 47 of the card, obtaining the settings
161 from the variables specified above.
162
163 * MORE INFORMATION
164
165   See the doc directory for more documentation.
166
167   Finally, you may wish to visit the web site and join the mailing list if
168 you're interested in getting more information.
169
170    http://www.asterisk.org/index.php?menu=support
171
172   Welcome to the growing worldwide community of Asterisk users!
173
174 Mark Spencer