3b7db9e4dd47a4a61d79fe335420795d9de1963e
[asterisk/asterisk.git] / UPGRADE-1.6.txt
1 =========================================================
2 === Information for upgrading from Asterisk 1.4 to 1.6
3 ===
4 ===
5 === UPGRADE-1.2.txt -- Upgrade info for 1.0 to 1.2
6 === UPGRADE-1.4.txt -- Upgrade info for 1.2 to 1.4
7 =========================================================
8
9 AEL:
10
11 * Macros are now implemented underneath with the Gosub() application.
12   Heaven Help You if you wrote code depending on any aspect of this!
13   Previous to 1.6, macros were implemented with the Macro() app, which
14   provided a nice feature of auto-returning. The compiler will do its
15   best to insert a Return() app call at the end of your macro if you did
16   not include it, but really, you should make sure that all execution
17   paths within your macros end in "return;".
18
19 * The conf2ael program is 'introduced' in this release; it is in a rather
20   crude state, but deemed useful for making a first pass at converting
21   extensions.conf code into AEL. More intelligence will come with time.
22
23 Core:
24
25 * The 'languageprefix' option in asterisk.conf is now deprecated, and
26   the default sound file layout for non-English sounds is the 'new
27   style' layout introduced in Asterisk 1.4 (and used by the automatic
28   sound file installer in the Makefile).
29
30 * The ast_expr2 stuff has been modified to handle floating-point numbers.
31   Numbers of the format D.D are now acceptable input for the expr parser, 
32   Where D is a string of base-10 digits. All math is now done in "long double",
33   if it is available on your compiler/architecture. This was half-way between
34   a bug-fix (because the MATH func returns fp by default), and an enhancement.
35   Also, for those counting on, or needing, integer operations, a series of
36   'functions' were also added to the expr language, to allow several styles
37   of rounding/truncation, along with a set of common floating point operations,
38   like sin, cos, tan, log, pow, etc. The ability to call external functions
39   like CDR(), etc. was also added, without having to use the ${...} notation.
40  
41 * The delimiter passed to applications has been changed to the comma (','), as
42   that is what people are used to using within extensions.conf.  If you are
43   using realtime extensions, you will need to translate your existing dialplan
44   to use this separator.  To use a literal comma, you need merely to escape it
45   with a backslash ('\').  Another possible side effect is that you may need to
46   remove the obscene level of backslashing that was necessary for the dialplan
47   to work correctly in 1.4 and previous versions.  This should make writing
48   dialplans less painful in the future, albeit with the pain of a one-time
49   conversion.  If you would like to avoid this conversion immediately, set
50   pbx_realtime=1.4 in the [compat] section of asterisk.conf.  After
51   transitioning, set pbx_realtime=1.6 in the same section.
52
53 * For the same purpose as above, you may set res_agi=1.4 in the [compat]
54   section of asterisk.conf to continue to use the '|' delimiter in the EXEC
55   arguments of AGI applications.  After converting to use the ',' delimiter,
56   change this option to res_agi=1.6.
57
58 * The logger.conf option 'rotatetimestamp' has been deprecated in favor of
59   'rotatestrategy'.  This new option supports a 'rotate' strategy that more
60   closely mimics the system logger in terms of file rotation.
61
62 * The concise versions of various CLI commands are now deprecated. We recommend
63   using the manager interface (AMI) for application integration with Asterisk.
64
65 * The following core commands dealing with dialplan has been deprecated: 'core
66   show globals', 'core set global' and 'core set chanvar'. Use the equivalent
67   'dialplan show globals', 'dialplan set global' and 'dialplan set chanvar'
68   instead.
69
70 * The silencethreshold used for various applications is now settable via a
71   centralized config option in dsp.conf.
72
73 * The logical value of spaces immediately preceding a standalone 0 previously
74   evaluated to true.  It now evaluates to false.  This has confused a good
75   many people in the past (typically because they failed to realize the space
76   had any significance).  Since this violates the Principle of Least Surprise,
77   it has been changed.
78
79 * The default console now will use colors according to the default background
80   color, instead of forcing the background color to black.  If you are using a
81   light colored background for your console, you may wish to use the option
82   flag '-W' to present better color choices for the various messages.  However,
83   if you'd prefer the old method of forcing colors to white text on a black
84   background, the compatiblity option -B is provided for this purpose.
85
86 Voicemail:
87
88 * The voicemail configuration values 'maxmessage' and 'minmessage' have
89   been changed to 'maxsecs' and 'minsecs' to clarify their purpose and
90   to make them more distinguishable from 'maxmsgs', which sets folder
91   size.  The old variables will continue to work in this version, albeit
92   with a deprecation warning.
93
94 * If you use any interface for modifying voicemail aside from the built in
95   dialplan applications, then the option "pollmailboxes" *must* be set in
96   voicemail.conf for message waiting indication (MWI) to work properly.  This
97   is because Voicemail notification is now event based instead of polling
98   based.  The channel drivers are no longer responsible for constantly manually
99   checking mailboxes for changes so that they can send MWI information to users.
100   Examples of situations that would require this option are web interfaces to
101   voicemail or an email client in the case of using IMAP storage.
102
103 * The externnotify script should accept an additional (last) parameter
104   containing the number of urgent messages in the INBOX.
105
106 Applications:
107
108 * SendImage() no longer hangs up the channel on transmission error or on
109   another type of error; in those cases, a FAILURE status is stored in 
110   SENDIMAGESTATUS and dialplan execution continues.  The possible return values
111   stored in SENDIMAGESTATUS are: SUCCESS, FAILURE, and UNSUPPORTED. ('OK' has
112   been replaced with 'SUCCESS', and 'NOSUPPORT' has been replaced with
113   'UNSUPPORTED').  This change makes the SendImage application more consistent
114   with other applications.
115
116 * ChanIsAvail() now has a 't' option, which allows the specified device
117   to be queried for state without consulting the channel drivers. This
118   performs mostly a 'ChanExists' sort of function.
119
120 * ChannelRedirect() will not terminate the channel that fails to do a
121   channelredirect as it has done previously. Instead CHANNELREDIRECT_STATUS
122   will reflect if the attempt was successful of not.
123
124 * SetCallerPres() has been replaced with the CALLERPRES() dialplan function
125   and is now deprecated.
126
127 * DISA()'s fifth argument is now an options argument.  If you have previously
128   used 'NOANSWER' in this argument, you'll need to convert that to the new
129   option 'n'.
130
131 * Macro() is now deprecated.  If you need subroutines, you should use the
132   Gosub()/Return() applications.  To replace MacroExclusive(), we have
133   introduced dialplan functions LOCK(), TRYLOCK(), and UNLOCK().  You may use
134   these functions in any location where you desire to ensure that only one
135   channel is executing that path at any one time.  The Macro() applications
136   are deprecated for performance reasons.  However, since Macro() has been
137   around for a long time and so many dialplans depend heavily on it, for the
138   sake of backwards compatibility it will not be removed .  It is also worth
139   noting that using both Macro() and GoSub() at the same time is _heavily_
140   discouraged.
141
142 * Read() now sets a READSTATUS variable on exit.  It does NOT automatically
143   return -1 (and hangup) anymore on error.  If you want to hangup on error,
144   you need to do so explicitly in your dialplan.
145
146 * Privacy() no longer uses privacy.conf, so any options must be specified
147   directly in the application arguments.
148
149 * MusicOnHold application now has duration parameter which allows specifying
150   timeout in seconds.
151
152 * WaitMusicOnHold application is now deprecated in favor of extended MusicOnHold.
153
154 * SetMusicOnHold is now deprecated. You should use Set(CHANNEL(musicclass)=...)
155   instead.
156
157 * While app_directory has always relied on having a voicemail.conf or users.conf file
158   correctly set up, it now is dependent on app_voicemail being compiled as well.
159
160 * The arguments in ExecIf changed a bit, to be more like other applications.
161   The syntax is now ExecIf(<cond>?appiftrue(args):appiffalse(args)).
162
163 * The behavior of the Set application now depends upon a compatibility option,
164   set in asterisk.conf.  To use the old 1.4 behavior, which allowed Set to take
165   multiple key/value pairs, set app_set=1.4 in [compat] in asterisk.conf.  To
166   use the new behavior, which permits variables to be set with embedded commas,
167   set app_set=1.6 in [compat] in asterisk.conf.  Note that you can have both
168   behaviors at the same time, if you switch to using MSet if you want the old
169   behavior.
170
171 Dialplan Functions:
172
173 * QUEUE_MEMBER_COUNT() has been deprecated in favor of the QUEUE_MEMBER() function. For
174   more information, issue a "show function QUEUE_MEMBER" from the CLI.
175
176 CDR:
177
178 * The cdr_sqlite module has been marked as deprecated in favor of
179   cdr_sqlite3_custom.  It will potentially be removed from the tree
180   after Asterisk 1.6 is released.
181
182 * The cdr_odbc module now uses res_odbc to manage its connections.  The
183   username and password parameters in cdr_odbc.conf, therefore, are no
184   longer used.  The dsn parameter now points to an entry in res_odbc.conf.
185
186 * The uniqueid field in the core Asterisk structure has been changed from a
187   maximum 31 character field to a 149 character field, to account for all
188   possible values the systemname prefix could be.  In the past, if the
189   systemname was too long, the uniqueid would have been truncated.
190
191 * The cdr_tds module now supports all versions of FreeTDS that contain
192   the db-lib frontend.  It will also now log the userfield variable if
193   the target database table contains a column for it.
194
195 Formats:
196
197 * format_wav: The GAIN preprocessor definition and source code that used it
198   is removed.  This change was made in response to user complaints of
199   choppiness or the clipping of loud signal peaks.  To increase the volume
200   of voicemail messages, use the 'volgain' option in voicemail.conf
201
202 Channel Drivers:
203
204 * SIP: a small upgrade to support the "Record" button on the SNOM360,
205   which sends a sip INFO message with a "Record: on" or "Record: off" 
206   header. If Asterisk is set up (via features.conf) to accept "One Touch Monitor"
207   requests (by default, via '*1'), then the user-configured dialpad sequence
208   is generated, and recording can be started and stopped via this button. The
209   file names and formats are all controlled via the normal mechanisms. If the
210   user has not configured the automon feature, the normal "415 Unsupported media type"
211   is returned, and nothing is done.
212
213 * SIP: The "call-limit" option is marked as deprecated. It still works in this version of
214   Asterisk, but will be removed in the following version. Please use the groupcount functions
215   in the dialplan to enforce call limits. The "limitonpeer" configuration option is
216   now renamed to "counteronpeer".
217
218 * SIP: The "username" option is now renamed to "defaultuser" to match "defaultip".
219   These are used only before registration to call a peer with the uri 
220         sip:defaultuser@defaultip
221   The "username" setting still work, but is deprecated and will not work in 
222   the next version of Asterisk.
223
224 * SIP: All of the functionality in SIPCHANINFO() has been implemented in CHANNEL(),
225   and you should start using that function instead for retrieving information about
226   the channel in a technology-agnostic way.
227
228 * chan_local.c: the comma delimiter inside the channel name has been changed to a
229   semicolon, in order to make the Local channel driver compatible with the comma
230   delimiter change in applications.
231
232 * H323: The "tos" setting has changed name to "tos_audio" and "cos" to "cos_audio"
233   to be compatible with settings in sip.conf. The "tos" and "cos" configuration
234   is deprecated and will stop working in the next release of Asterisk.
235
236 * Console: A new console channel driver, chan_console, has been added to Asterisk.
237   This new module can not be loaded at the same time as chan_alsa or chan_oss.  The
238   default modules.conf only loads one of them (chan_oss by default).  So, unless you
239   have modified your modules.conf to not use the autoload option, then you will need
240   to modify modules.conf to add another "noload" line to ensure that only one of
241   these three modules gets loaded.
242
243 * DAHDI: The chan_zap module that supported PSTN interfaces using
244   Zaptel has been renamed to chan_dahdi, and only supports the DAHDI
245   telephony driver package for PSTN interfaces. See the
246   Zaptel-to-DAHDI.txt file for more details on this transition.
247
248 * DAHDI: The "msdstrip" option has been deprecated, as it provides no value over
249   the method of stripping digits in the dialplan using variable substring syntax.
250
251 Configuration:
252
253 * pbx_dundi.c: tos parameter changed to use new values. Old values like lowdelay,
254   lowcost and other is not acceptable now. Look into qos.tex for description of 
255   this parameter.
256
257 * queues.conf: the queue-lessthan sound file option is no longer available, and the
258   queue-round-seconds option no longer takes '1' as a valid parameter.
259
260 * If you have any third party modules which use a config file variable whose
261   name ends in a '+', please note that the append capability added to this
262   version may now conflict with that variable naming scheme.  An easy
263   workaround is to ensure that a space occurs between the '+' and the '=',
264   to differentiate your variable from the append operator.  This potential
265   conflict is unlikely, but is documented here to be thorough.
266
267 * skinny.conf now has seperate sections for lines and devices.
268   Please have a look at configs/skinny.conf.sample and update
269   your skinny.conf.
270
271 Manager:
272
273 * Manager has been upgraded to version 1.1 with a lot of changes. 
274   Please check doc/manager_1_1.txt for information
275
276 * The IAXpeers command output has been changed to more closely resemble the
277   output of the SIPpeers command.
278
279 * cdr_manager now reports at the "cdr" level, not at "call"  You may need to
280   change your manager.conf to add the level to existing AMI users, if they
281   want to see the CDR events generated.
282
283 * The Originate command now requires the Originate write permission.  For
284   Originate with the Application parameter, you need the additional System
285   privilege if you want to do anything that calls out to a subshell.
286
287 Queues:
288
289 * New queue log events ADDMEMBER and REMOVEMEMBER have been added.  Also, a
290   new value has been added to the TRANSFER event that indicates the caller's
291   original position in the queue they are being transfered from.
292
293 * Prior to Asterisk 1.6.2, queue names were treated in a case-sensitive
294   manner, meaning that queues with names like "sales" and "sALeS" would
295   be seen as unique queues. The parsing logic has changed to use case-
296   insensitive comparisons now when originally hashing based on queue
297   names, meaning that now the two queues mentioned as examples earlier
298   will be seen as having the same name.
299
300 iLBC Codec:
301
302 * Previously, the Asterisk source code distribution included the iLBC
303   encoder/decoder source code, from Global IP Solutions
304   (http://www.gipscorp.com). This code is not licensed for
305   distribution, and thus has been removed from the Asterisk source
306   code distribution. If you wish to use codec_ilbc to support iLBC
307   channels in Asterisk, you can run the contrib/scripts/get_ilbc_source.sh
308   script to download the source and put it in the proper place in
309   the Asterisk build tree. Once that is done you can follow your normal
310   steps of building Asterisk. You will need to run 'menuselect' and enable
311   the iLBC codec in the 'Codec  Translators' category.