Update UPGRADE.txt file for Asterisk 12

This simply pulls in the changes that were breaking from the CHANGES file
and updates a few other areas accordingly. It also removes the 10 => 11
notes, which are traditionally removed from each major version and stored
in the appropriate UPGRADE-X.txt file.
........

Merged revisions 398100 from http://svn.asterisk.org/svn/asterisk/branches/12


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@398101 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 433 insertions, 0 deletions

diff --git a/UPGRADE-12.txt b/UPGRADE-12.txt
new file mode 100644
index 000000000..426b1a979
--- /dev/null
+++ b/UPGRADE-12.txt
@@ -0,0 +1,433 @@
+===========================================================
+===
+=== Information for upgrading between Asterisk versions
+===
+=== These files document all the changes that MUST be taken
+=== into account when upgrading between the Asterisk
+=== versions listed below. These changes may require that
+=== you modify your configuration files, dialplan or (in
+=== some cases) source code if you have your own Asterisk
+=== modules or patches. These files also include advance
+=== notice of any functionality that has been marked as
+=== 'deprecated' and may be removed in a future release,
+=== along with the suggested replacement functionality.
+===
+=== UPGRADE-1.2.txt -- Upgrade info for 1.0 to 1.2
+=== UPGRADE-1.4.txt -- Upgrade info for 1.2 to 1.4
+=== UPGRADE-1.6.txt -- Upgrade info for 1.4 to 1.6
+=== UPGRADE-1.8.txt -- Upgrade info for 1.6 to 1.8
+=== UPGRADE-10.txt  -- Upgrade info for 1.8 to 10
+=== UPGRADE-11.txt  -- Upgrade info for 10 to 11
+===
+===========================================================
+
+There are many significant architectural changes in Asterisk 12. It is
+recommended that you not only read through this document for important
+changes that affect an upgrade, but that you also read through the CHANGES
+document in depth to better understand the new options available to you.
+
+Additional information on the architectural changes made in Asterisk can be
+found on the Asterisk wiki (https://wiki.asterisk.org)
+
+Of particular note, the following systems in Asterisk underwent significant
+changes. Documentation for the changes and a specification for their
+behavior in Asterisk 12 is also available on the Asterisk wiki.
+ - AMI: Many events were changed, and the semantics of channels and bridges
+        were defined. In particular, how channels and bridges behave under
+        transfer scenarios and situations involving multiple parties has
+        changed significantly. See https://wiki.asterisk.org/wiki/x/dAFRAQ
+        for more information.
+ - CDR: CDR logic was extracted from the many locations it existed in across
+        Asterisk and implemented as a consumer of Stasis message bus events.
+        As a result, consistency of records has improved significantly and the
+        behavior of CDRs in transfer scenarios has been defined in the CDR
+        specification. However, significant behavioral changes in CDRs resulted
+        from the transition. The most significant change is the addition of
+        CDR entries when a channel who is the Party A in a CDR leaves a bridge.
+        See https://wiki.asterisk.org/wiki/x/pwpRAQ for more information.
+ - CEL: Much like CDRs, CEL was removed from the many locations it existed in
+        across Asterisk and implemented as a consumer of Stasis message bus
+        events. It now closely follows the Bridging API model of channels and
+        bridges, and has a much closer consistency of conveyed events as AMI.
+        For the changes in events, see https://wiki.asterisk.org/wiki/x/4ICLAQ.
+
+Build System:
+ - Removed the CHANNEL_TRACE development mode build option. Certain aspects of
+   the CHANNEL_TRACE build option were incompatible with the new bridging
+   architecture.
+
+ - Asterisk now depends on libjansson, libuuid and optionally (but recommended)
+   libxslt and uriparser.
+
+ - The new SIP stack and channel driver uses a particular version of PJSIP.
+   Please see https://wiki.asterisk.org/wiki/x/J4GLAQ for more information on
+   configuring and installing PJSIP for use with Asterisk.
+
+AgentLogin and chan_agent:
+ - Along with AgentRequest, this application has been modified to be a
+   replacement for chan_agent. The chan_agent module and the Agent channel
+   driver have been removed from Asterisk, as the concept of a channel driver
+   proxying in front of another channel driver was incompatible with the new
+   architecture (and has had numerous problems through past versions of
+   Asterisk). The act of a channel calling the AgentLogin application places the
+   channel into a pool of agents that can be requested by the AgentRequest
+   application. Note that this application, as well as all other agent related
+   functionality, is now provided by the app_agent_pool module.
+
+ - This application no longer performs agent authentication. If authentication
+   is desired, the dialplan needs to perform this function using the
+   Authenticate or VMAuthenticate application or through an AGI script before
+   running AgentLogin.
+
+ - The agents.conf schema has changed. Rather than specifying agents on a
+   single line in comma delineated fashion, each agent is defined in a separate
+   context. This allows agents to use the power of context templates in their
+   definition.
+
+ - A number of parameters from agents.conf have been removed. This includes
+   maxloginretries, autologoffunavail, updatecdr, goodbye, group, recordformat,
+   urlprefix, and savecallsin. These options were obsoleted by the move from
+   a channel driver model to the bridging/application model provided by
+   app_agent_pool.
+
+ - The AGENTUPDATECDR channel variable has also been removed, for the same
+   reason as the updatecdr option.
+
+ - The endcall and enddtmf configuration options are removed.  Use the
+   dialplan function CHANNEL(dtmf-features) to set DTMF features on the agent
+   channel before calling AgentLogin.
+
+AgentMonitorOutgoing
+ - This application has been removed. It was a holdover from when
+   AgentCallbackLogin was removed.
+
+ControlPlayback
+ - The channel variable CPLAYBACKSTATUS may now return the value
+   'REMOTESTOPPED' when playback is stopped by an external entity.
+
+DumpChan:
+ - The output of DumpChan no longer includes the DirectBridge or IndirectBridge
+   fields. Instead, if a channel is in a bridge, it includes a BridgeID field
+   containing the unique ID of the bridge that the channel happens to be in.
+
+ForkCDR:
+ - Nearly every parameter in ForkCDR has been updated and changed to reflect
+   the changes in CDRs. Please see the documentation for the ForkCDR
+   application, as well as the CDR specification on the Asterisk wiki.
+
+NoCDR:
+ - The NoCDR application has been deprecated. Please use the CDR_PROP function
+   to disable CDRs on a channel.
+
+ParkAndAnnounce:
+ - The app_parkandannounce module has been removed. The application
+   ParkAndAnnounce is now provided by the res_parking module. See the
+   Parking changes for more information.
+
+ResetCDR:
+ - The 'w' and 'a' options have been removed. Dispatching CDRs to registered
+   backends occurs on an as-needed basis in order to preserve linkedid
+   propagation and other needed behavior.
+ - The 'e' option is deprecated. Please use the CDR_PROP function to enable
+   CDRs on a channel that they were previously disabled on.
+ - The ResetCDR application is no longer a part of core Asterisk, and instead
+   is now delivered as part of app_cdr.
+
+Queues:
+ - Queue strategy rrmemory now has a predictable order similar to strategy
+   rrordered. Members will be called in the order that they are added to the
+   queue.
+
+ - Removed the queues.conf check_state_unknown option.  It is no longer
+   necessary.
+
+ - It is now possible to play the Queue prompts to the first user waiting in a
+   call queue. Note that this may impact the ability for agents to talk with
+   users, as a prompt may still be playing when an agent connects to the user.
+   This ability is disabled by default but can be enabled on an individual
+   queue using the 'announce-to-first-user' option.
+
+ - The configuration options eventwhencalled and eventmemberstatus have been
+   removed.  As a result, the AMI events QueueMemberStatus, AgentCalled,
+   AgentConnect, AgentComplete, AgentDump, and AgentRingNoAnswer will always be
+   sent.  The "Variable" fields will also no longer exist on the Agent* events.
+   These events can be filtered out from a connected AMI client using the
+   eventfilter setting in manager.conf.
+
+ - The queue log now differentiates between blind and attended transfers. A
+   blind transfer will result in a BLINDTRANSFER message with the destination
+   context and extension. An attended transfer will result in an
+   ATTENDEDTRANSFER message. This message will indicate the method by which
+   the attended transfer was completed: "BRIDGE" for a bridge merge, "APP"
+   for running an application on a bridge or channel, or "LINK" for linking
+   two bridges together with local channels. The queue log will also now detect
+   externally initiated blind and attended transfers and record the transfer
+   status accordingly.
+
+ - When performing queue pause/unpause on an interface without specifying an
+   individual queue, the PAUSEALL/UNPAUSEALL event will only be logged if at
+   least one member of any queue exists for that interface.
+
+SetAMAFlags
+ - This application is deprecated in favor of CHANNEL(amaflags).
+
+VoiceMail:
+ - The voicemail.conf configuration file now has an 'alias' configuration
+   parameter for use with the Directory application. The voicemail realtime
+   database table schema has also been updated with an 'alias' column. Systems
+   using voicemail with realtime should update their schemas accordingly.
+
+Channel Drivers:
+ - When a channel driver is configured to enable jiterbuffers, they are now
+   applied unconditionally when a channel joins a bridge. If a jitterbuffer
+   is already set for that channel when it enters, such as by the JITTERBUFFER
+   function, then the existing jitterbuffer will be used and the one set by
+   the channel driver will not be applied.
+
+chan_bridge
+ - chan_bridge is removed and its functionality is incorporated into ConfBridge
+   itself.
+
+chan_dahdi:
+ - Analog port dialing and deferred DTMF dialing for PRI now distinguishes
+   between 'w' and 'W'.  The 'w' pauses dialing for half a second.  The 'W'
+   pauses dialing for one second.
+
+ - The default for inband_on_proceeding has changed to no.
+
+ - The CLI command 'dahdi destroy channel' is now 'dahdi destroy channels'.
+   A range of channels can be specified to be destroyed. Note that this command
+   should only be used if you understand the risks it entails.
+
+chan_local:
+ - The /b option has been removed.
+
+ - chan_local moved into the system core and is no longer a loadable module.
+
+chan_sip:
+ - The 'callevents' parameter has been removed. Hold AMI events are now raised
+   in the core, and can be filtered out using the 'eventfilter' parameter
+   in manager.conf.
+
+ - Dynamic realtime tables for SIP Users can now include a 'path' field. This
+   will store the path information for that peer when it registers. Realtime
+   tables can also use the 'supportpath' field to enable Path header support.
+
+ - LDAP realtime configurations for SIP Users now have the AstAccountPathSupport
+   objectIdentifier. This maps to the supportpath option in sip.conf.
+
+Core:
+ - Masquerades as an operation inside Asterisk have been effectively hidden
+   by the migration to the Bridging API. As such, many 'quirks' of Asterisk
+   no longer occur. This includes renaming of channels, "<ZOMBIE>" channels,
+   dropping of frame/audio hooks, and other internal implementation details
+   that users had to deal with. This fundamental change has large implications
+   throughout the changes documented for this version. For more information
+   about the new core architecture of Asterisk, please see the Asterisk wiki.
+
+ - The following channel variables have changed behavior which is described in
+   the CHANGES file: TRANSFER_CONTEXT, BRIDGEPEER, BRIDGEPVTCALLID,
+   ATTENDED_TRANSFER_COMPLETE_SOUND, DYNAMIC_FEATURENAME, and DYNAMIC_PEERNAME.
+
+AMI (Asterisk Manager Interface):
+ - Version 1.4 - The details of what happens to a channel when a masquerade
+   happens (transfers, parking, etc) have changed.
+   - The Masquerade event now includes the Uniqueid's of the clone and original
+     channels.
+   - Channels no longer swap Uniqueid's as a result of the masquerade.
+   - Instead of a shell game of renames, there's now a single rename, appending
+     <ZOMBIE> to the name of the original channel.
+
+ - *Major* changes were made to both the syntax as well as the semantics of the
+   AMI protocol. In particular, AMI events have been substantially modified
+   and improved in this version of Asterisk. The major event changes are listed
+   below.
+   - NewPeerAccount has been removed. NewAccountCode is raised instead.
+   - Reload events have been consolidated and standardized.
+   - ModuleLoadReport has been removed.
+   - FaxSent is now SendFAX; FaxReceived is now ReceiveFAX. This standardizes
+     app_fax and res_fax events.
+   - MusicOnHold has been replaced with MusicOnHoldStart and MusicOnHoldStop.
+   - JabberEvent has been removed.
+   - Hold is now in the core and will now raise Hold and Unhold events.
+   - Join is now QueueCallerJoin.
+   - Leave is now QueueCallerLeave.
+   - Agentlogin/Agentlogoff is now AgentLogin/AgentLogoff, respectively.
+   - ChannelUpdate has been removed.
+   - Local channel optimization is now conveyed via LocalOptimizationBegin and
+     LocalOptimizationEnd.
+   - BridgeAction and BridgeExec have been removed.
+   - BlindTransfer and AttendedTransfer events were added.
+   - Dial is now DialBegin and DialEnd.
+   - DTMF is now DTMFBegin and DTMFEnd.
+   - Bridge has been replaced with BridgeCreate, BridgeEnter, BridgeLeave, and
+     BridgeDestroy
+   - MusicOnHold has been replaced with MusicOnHoldStart and MusicOnHoldStop
+   - AGIExec is now AGIExecStart and AGIExecEnd
+   - AsyncAGI is now AsyncAGIStart, AsyncAGIExec, and AsyncAGIEnd
+
+ - The 'MCID' AMI event now publishes a channel snapshot when available and
+   its non-channel-snapshot parameters now use either the "MCallerID" or
+   'MConnectedID' prefixes with Subaddr*, Name*, and Num* suffixes instead
+   of 'CallerID' and 'ConnectedID' to avoid confusion with similarly named
+   parameters in the channel snapshot.
+
+ - The 'Channel' key used in the 'AlarmClear', 'Alarm', and 'DNDState' has been
+   renamed "DAHDIChannel" since it does not convey an Asterisk channel name.
+
+ - All AMI events now contain a 'SystemName' field, if available.
+
+ - Local channel information in events is now prefixed with 'LocalOne' and
+   'LocalTwo'. This replaces the suffix of '1' and '2' for the two halves of
+   the Local channel. This affects the 'LocalBridge', 'LocalOptimizationBegin',
+   and 'LocalOptimizationEnd' events.
+
+ - The 'RTCPSent'/'RTCPReceived' events have been significantly modified from
+   previous versions. They now report all SR/RR packets sent/received, and
+   have been restructured to better reflect the data sent in a SR/RR. In
+   particular, the event structure now supports multiple report blocks.
+
+ - The deprecated use of | (pipe) as a separator in the channelvars setting in
+   manager.conf has been removed.
+
+ - The SIP SIPqualifypeer action now sends a response indicating it will qualify
+   a peer once a peer has been found to qualify.  Once the qualify has been
+   completed it will now issue a SIPqualifypeerdone event.
+
+ - The AMI event 'Newexten' field 'Extension' is deprecated, and may be removed
+   in a future release. Please use the common 'Exten' field instead.
+
+ - The AMI events 'ParkedCall', 'ParkedCallTimeOut', 'ParkedCallGiveUp', and
+   'UnParkedCall' have changed significantly in the new res_parking module.
+   - The 'Channel' and 'From' headers are gone. For the channel that was parked
+     or is coming out of parking, a 'Parkee' channel snapshot is issued and it
+     has a number of fields associated with it. The old 'Channel' header relayed
+     the same data as the new 'ParkeeChannel' header.
+   - The 'From' field was ambiguous and changed meaning depending on the event.
+     for most of these, it was the name of the channel that parked the call
+     (the 'Parker'). There is no longer a header that provides this channel name,
+     however the 'ParkerDialString' will contain a dialstring to redial the
+     device that parked the call.
+   - On UnParkedCall events, the 'From' header would instead represent the
+     channel responsible for retrieving the parkee. It receives a channel
+     snapshot labeled 'Retriever'. The 'from' field is is replaced with
+     'RetrieverChannel'.
+   - Lastly, the 'Exten' field has been replaced with 'ParkingSpace'.
+
+ - The AMI event 'Parkinglot' (response to 'Parkinglots' command) in a similar
+   fashion has changed the field names 'StartExten' and 'StopExten' to
+   'StartSpace' and 'StopSpace' respectively.
+
+ - The AMI 'Status' response event to the AMI Status action replaces the
+   'BridgedChannel' and 'BridgedUniqueid' headers with the 'BridgeID' header to
+   indicate what bridge the channel is currently in.
+
+CDR (Call Detail Records)
+ - Significant changes have been made to the behavior of CDRs. The CDR engine
+   was effectively rewritten and built on the Stasis message bus. For a full
+   definition of CDR behavior in Asterisk 12, please read the specification
+   on the Asterisk wiki (wiki.asterisk.org).
+
+ - CDRs will now be created between all participants in a bridge. For each
+   pair of channels in a bridge, a CDR is created to represent the path of
+   communication between those two endpoints. This lets an end user choose who
+   to bill for what during bridge operations with multiple parties.
+
+ - The duration, billsec, start, answer, and end times now reflect the times
+   associated with the current CDR for the channel, as opposed to a cumulative
+   measurement of all CDRs for that channel.
+
+CEL:
+ - The Uniqueid field for a channel is now a stable identifier, and will not
+   change due to transfers, parking, etc.
+
+ - CEL has undergone significant rework in Asterisk 12, and is now built on the
+   Stasis message bus. Please see the specification for CEL on the Asterisk
+   wiki at https://wiki.asterisk.org/wiki/x/4ICLAQ for more detailed
+   information. A summary of the affected events is below:
+   - BRIDGE_START, BRIDGE_END, BRIDGE_UPDATE, 3WAY_START, 3WAY_END, CONF_ENTER,
+     CONF_EXIT, CONF_START, and CONF_END events have all been removed. These
+     events have been replaced by BRIDGE_ENTER/BRIDGE_EXIT.
+   - BLINDTRANSFER/ATTENDEDTRANSFER events now report the peer as NULL and
+     additional information in the extra string field.
+
+Dialplan:
+ - All channel and global variable names are evaluated in a case-sensitive
+   manner. In previous versions of Asterisk, variables created and evaluated in
+   the dialplan were evaluated case-insensitively, but built-in variables and
+   variable evaluation done internally within Asterisk was done
+   case-sensitively.
+
+ - Asterisk has always had code to ignore dash '-' characters that are not
+   part of a character set in the dialplan extensions.  The code now
+   consistently ignores these characters when matching dialplan extensions.
+
+ - BRIDGE_FEATURES channel variable is now casesensitive for feature letter
+   codes. Uppercase variants apply them to the calling party while lowercase
+   variants apply them to the called party.
+
+Features:
+ - The features.conf [applicationmap] <FeatureName>  ActivatedBy option is
+   no longer honored.  The feature is always activated by the channel that has
+   DYNAMIC_FEATURES defined on it when it enters the bridge. Use predial to set
+   different values of DYNAMIC_FEATURES on the channels
+
+ - Executing a dynamic feature on the bridge peer in a multi-party bridge will
+   execute it on all peers of the activating channel.
+
+ - There is no longer an explicit 'features reload' CLI command. Features can
+   still be reloaded using 'module reload features'.
+
+ - It is no longer necessary (or possible) to define the ATXFER_NULL_TECH in
+   features.c for atxferdropcall=no to work properly. This option now just
+   works.
+
+Parking:
+ - Parking has been extracted from the Asterisk core as a loadable module,
+   res_parking.
+
+ - Configuration is found in res_parking.conf. It is no longer supported in
+   features.conf
+
+ - The arguments for the Park, ParkedCall, and ParkAndAnnounce applications 
+   have been modified significantly. See the application documents for 
+   specific details.
+
+ - Numerous changes to Parking related applications, AMI and CLI commands and
+   internal inter-workings  have been made. Please read the CHANGES file for 
+   the detailed list.
+
+Security Events Framework:
+ - Security Event timestamps now use ISO 8601 formatted date/time instead of
+   the "seconds-microseconds" format that it was using previously.
+
+AGENT:
+ - The password option has been disabled, as the AgentLogin application no
+   longer provides authentication.
+
+AUDIOHOOK_INHERIT:
+ - Due to changes in the Asterisk core, this function is no longer needed to
+   preserve a MixMonitor on a channel during transfer operations and dialplan
+   execution. It is effectively obsolete.
+
+CDR: (function)
+ - The 'amaflags' and 'accountcode' attributes for the CDR function are
+   deprecated. Use the CHANNEL function instead to access these attributes.
+
+ - The 'l' option has been removed. When reading a CDR attribute, the most
+   recent record is always used. When writing a CDR attribute, all non-finalized
+   CDRs are updated.
+
+ - The 'r' option has been removed, for the same reason as the 'l' option.
+
+ - The 's' option has been removed, as LOCKED semantics no longer exist in the
+   CDR engine.
+
+res_rtp_asterisk:
+ - ICE/STUN/TURN support in res_rtp_asterisk has been made optional. To enable
+   them, an Asterisk-specific version of PJSIP needs to be installed.
+   Tarballs are available from https://github.com/asterisk/pjproject/tags/.
+
+
+===========================================================
+===========================================================