Sonic Install

PROGRESS
SONIC

Installation and Upgrade Guide

Progress Sonic Installation and Upgrade Guide 8.5
2011 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.
These materials and all Progress software products are copyrighted and all rights are reserved by Progress
Software Corporation. The information in these materials is subject to change without notice, and Progress
Software Corporation assumes no responsibility for any errors that may appear therein. The references in these
materials to specific platforms supported are subject to change.
Actional, Apama, Artix, Business Empowerment, Business Making Progress, DataDirect (and design), DataDirect
Connect, DataDirect Connect64, DataDirect Technologies, DataDirect XML Converters, DataDirect XQuery,
DataXtend, Dynamic Routing Architecture, EdgeXtend, Empowerment Center, Fathom, Fuse Mediation Router,
Fuse Message Broker, Fuse Services Framework, IntelliStream, IONA, Making Software Work Together,
Mindreef, ObjectStore, OpenEdge, Orbix, PeerDirect, POSSENET, Powered by Progress, PowerTier, Progress,
Progress DataXtend, Progress Dynamics, Progress Business Empowerment, Progress Empowerment Center,
Progress Empowerment Program, Progress OpenEdge, Progress Profiles, Progress Results, Progress Software
Business Making Progress, Progress Software Developers Network, Progress Sonic, ProVision, PS Select,
Savvion, SequeLink, Shadow, SOAPscope, SOAPStation, Sonic, Sonic ESB, SonicMQ, Sonic Orchestration
Server, SpeedScript, Stylus Studio, Technical Empowerment, WebSpeed, Xcalia (and design), and Your Software,
Our Technology-Experience the Connection are registered trademarks of Progress Software Corporation or one of
its affiliates or subsidiaries in the U.S. and/or other countries. AccelEvent, Apama Dashboard Studio, Apama Event
Manager, Apama Event Modeler, Apama Event Store, Apama Risk Firewall, AppsAlive, AppServer, ASPen, ASP-
in-a-Box, BusinessEdge, Cache-Forward, CloudEdge, DataDirect Spy, DataDirect SupportLink, Fuse, FuseSource,
Future Proof, GVAC, High Performance Integration, ObjectStore Inspector, ObjectStore Performance Expert,
OpenAccess, Orbacus, Pantero, POSSE, ProDataSet, Progress Arcade, Progress CloudEdge, Progress Control
Tower, Progress ESP Event Manager, Progress ESP Event Modeler, Progress Event Engine, Progress RFID,
Progress RPM, PSE Pro, SectorAlliance, SeeThinkAct, Shadow z/Services, Shadow z/Direct, Shadow z/Events,
Shadow z/Presentation, Shadow Studio, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects,
SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer,
SmartWindow, Sonic Business Integration Suite, Sonic Process Manager, Sonic Collaboration Server, Sonic
Continuous Availability Architecture, Sonic Database Service, Sonic Workbench, Sonic XML Server, The Brains
Behind BAM, WebClient, and Who Makes Progress are trademarks or service marks of Progress Software
Corporation and/or its subsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of
Oracle and/or its affiliates. Any other marks contained herein may be trademarks of their respective owners.
Third Party Acknowledgements:

Progress Sonic v8.5 incorporates Model Objects Framework v2.0 from ModelObjects Group. Such technology is
subject to the following terms and conditions: The ModelObjects Group Software License, Version 1.0 - Copyright
(c) 2000-2001 ModelObjects Group. All rights reserved. Redistribution and use in source and binary forms, with
or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source
code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions
in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution. 3. The end-user documentation included with
the redistribution, if any, must include the following acknowledgement: "This product includes software developed
by the ModelObjects Group (http://www.modelobjects.com)." Alternatively, this acknowledgement may appear in
the software itself, if and wherever such third-party acknowledgements normally appear. 4. The name
"ModelObjects" must not be used to endorse or promote products derived from this software without prior written
permission. For written permission, please contact djacobs@modelobjects.com. 5. Products derived from this
software may not be called "ModelObjects", nor may ModelObjects" appear in thier name, without prior written
permission of the ModelObjects Group. THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE MODEL OBJECTS GROUP OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
Progress Sonic v8.5 incorporates OpenSAML Java Distribution v1.0.1. Such technology is subject to the following
terms and conditions: The OpenSAML License, Version 1. Copyright (c) 2002 - University Corporation for
Advanced Internet Development, Inc. All rights reserved. Redistribution and use in source and binary forms, with
or without modification, are permitted provided that the following conditions are met: Redistributions of source
code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in
binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution, if any, must include the following
acknowledgment: "This product includes software developed by the University Corporation for Advanced Internet
Development (http://www.ucaid.edu)Internet2 Project. Alternately, this acknowledegement may appear in the
software itself, if and wherever such third-party acknowledgments normally appear. Neither the name of
OpenSAML nor the names of its contributors, nor Internet2, nor the University Corporation for Advanced Internet
Development, Inc., nor UCAID may be used to endorse or promote products derived from this software without
specific prior written permission. For written permission, please contact opensaml@opensaml.org. Products
derived from this software may not be called OpenSAML, Internet2, UCAID, or the University Corporation for
Advanced Internet Development, nor may OpenSAML appear in their name, without prior written permission of
the University Corporation for Advanced Internet Development. THIS SOFTWARE IS PROVIDED BY THE
COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND WITH ALL FAULTS. ANY EXPRESS OR
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE
DISCLAIMED AND THE ENTIRE RISK OF SATISFACTORY QUALITY, PERFORMANCE, ACCURACY,
AND EFFORT IS WITH LICENSEE. IN NO EVENT SHALL THE COPYRIGHT OWNER, CONTRIBUTORS
OR THE UNIVERSITY CORPORATION FOR ADVANCED INTERNET DEVELOPMENT, INC. BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Progress Sonic v8.5 incorporates BasicLogin.java, SimpleCallbackHandler.java, SimplePasswordUser.java,
SampleLoginModule.java, SamplePrincipal.java from Sun Microsystems, Inc. These technologies are subject to
the following terms and conditions: Copyright 2000-2002 Sun Microsystems, Inc. All Rights Reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met: -Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer. -Redistribution in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation and/or other materials provided with the
distribution. Neither the name of Sun Microsystems, Inc. or the names of contributors may be used to endorse or
promote products derived from this software without specific prior written permission. This software is provided
"AS IS," without a warranty of any kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS
AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR
A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN AND ITS
LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES OR LIABILITIES SUFFERED BY LICENSEE
AS A RESULT OF OR RELATING TO USE, MODIFICATION OR DISTRIBUTION OF THE SOFTWARE
OR ITS DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST
REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL,
INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF
LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS
BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You acknowledge that Software is not
designed, licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility.
Progress Sonic v8.5 incorporates Saxon XSLT and XQuery Processor v8.9.0.4 from Saxonica Limited
(http://www.saxonica.com/) which is available from SourceForge (http://sourceforge.net/projects/saxon/). PSC
will, at Licensee's request, provide copies of the source code for this third party technology, including
modifications, if any, made by PSC. PSC may charge reasonable shipping and handling charges for such
distribution. Licensee may also obtain the source code through http://communities.progress.com/pcom/docs/DOC-
16051 by following the instructions set forth therein. - Mozilla Public License Version 1.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.mozilla.org/MPL. Software distributed under the License is distributed on an "AS IS" basis,
WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language
governing rights and limitations under the License. The Original Code of Saxon comprises all those components
which are not explicitly attributed to other parties. The Initial Developer of the Original Code is Michael Kay. Until
February 2001 Michael Kay was an employee of International Computers Limited (now part of Fujitsu Limited),
and original code developed during that time was released under this license by permission from International
Computers Limited. From February 2001 until February 2004 Michael Kay was an employee of Software AG, and
code developed during that time was released under this license by permission from Software AG, acting as a
"Contributor". Subsequent code has been developed by Saxonica Limited, of which Michael Kay is a Director,
again acting as a "Contributor". A small number of modules, or enhancements to modules, have been developed by
other individuals (either written specially for Saxon, or incorporated into Saxon having initially been released as
part of another open source product). Such contributions are acknowledged individually in comments attached to
the relevant code modules. All Rights Reserved.
Progress Sonic v8.5 incorporates Mozilla Rhino v1.5R3. The contents of this file are subject to the Netscape Public
License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may
obtain a copy of the License at http://www.mozilla.org/NPL/. Software distributed under the License is distributed
on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the
specific language governing rights and limitations under the License. The Original Code is Mozilla Communicator
client code, released March 31, 1998. The Initial Developer of the Original Code is Netscape Communications
Corporation. Portions created by Netscape are Copyright (C) 1998-1999 Netscape Communications Corporation.
All Rights Reserved. PSC will, at Licensee's request, provide copies of the source code for this third party
technology, including modifications, if any, made by PSC. PSC may charge reasonable shipping and handling
charges for such distribution. Licensee may also obtain the source code through
http://communities.progress.com/pcom/docs/DOC-16051 by following the instructions set forth therein.
Progress Sonic v8.5 incorporates Apache Ant-Contrib 1.0B3. Such technology is subject to the following terms
and conditions: The Apache Software License, Version 1.1 - Copyright (c) 2001-2003 Ant-Contrib project. All
rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted
provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the
above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution. 3. The end-user documentation included with the redistribution, if any,
must include the following acknowlegement: "This product includes software developed by the Ant-Contrib
project (http://sourceforge.net/projects/ant-contrib)." Alternately, this acknowlegement may appear in the software
itself, if and wherever such third-party acknowlegements normally appear. 4. The name Ant-Contrib must not be
used to endorse or promote products derived from this software without prior written permission. For written
permission, please contact ant-contrib-developers@lists.sourceforge.net. 5. Products derived from this software
may not be called "Ant-Contrib" nor may "Ant-Contrib" appear in their names without prior written permission of
the Ant-Contrib project. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
SHALL THE ANT-CONTRIB PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.
Progress Sonic v8.5 incorporates Xalan Java XSLT Parser v2.4.1 from the Apache Foundation. Such technology
is subject to the following terms and conditions: The Apache Software License, Version 1.1 - Copyright (c) 1999
The Apache Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following conditions are met: 1. Redistributions of source
code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions
in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the
the redistribution, if any, must include the following acknowledgment: "This product includes software developed
by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in
the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xalan" and
"Apache Software Foundation" must not be used to endorse or promote products derived from this software without
prior written permission. For written permission, please contact apache@apache.org. 5. Products derived from this
software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of
the Apache Software Foundation. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR
SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
==========================================
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software
Foundation and was originally based on software copyright (c) 1999, Lotus Development Corporation.,
http://www.lotus.com. For more information on the Apache Software Foundation, please see
(http://www.apache.org/).
Progress Sonic v8.5 incorporates Xerces v2.6.2 from the Apache Foundation. Such technology is subject to the
following terms and conditions: The Apache Software License, Version 1.1 - Copyright (c) 1999-2004 The Apache
Software Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must
retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary
form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the
the redistribution, if any, must include the following acknowledgment: "This product includes software developed
by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in
the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xerces" and
software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of
the Apache Software Foundation. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR
================================================================
Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc.,
http://www.ibm.com. For more information on the Apache Software Foundation, please see
Progress Sonic v8.5 incorporates RSS4J v0.9.2. Such technology is subject to the following terms and conditions:
Copyright (c) 1999-2002 ChurchillObjects.com All rights reserved. Redistribution and use in source and binary
forms, with or without modification, are permitted provided that the following conditions are met: Redistributions
of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the
copyright holder nor the names of its contributors may be used to endorse or promote products derived from this
software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT
HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT, INC
Progress Sonic v8.5 incorporates Crimson v1.1.3. Such technology is subject to the following terms and
conditions: The Apache Software License, Version 1.1. Copyright (c) 1999-2003 The Apache Software
Foundation. All rights reserved. Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the
above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must
reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution. 3. The end-user documentation included with the
redistribution, if any, must include the following acknowledgment: "This product includes software developed by
the * Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in
the software itself, if and wherever such third-party acknowledgments normally appear. 4. The names "Xerces" and
software may not be called "Apache", nor may "Apache" appear in their name, without prior written * permission
of the Apache Software Foundation. THIS SOFTWARE IS PROVIDED `ÀS IS'' AND ANY EXPRESSED OR
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND * ON ANY
====================================================================
Foundation and was * originally based on software copyright (c) 1999, International * Business Machines, Inc.,
http://www.ibm.com. For more * information on the Apache Software Foundation, please see *
Progress Sonic v8.5 incorporates Jing 20030619 and Trang 20030619. Such technology is subject to the following
terms and conditions: Copyright (c) 2002, 2003 Thai Open Source Software Center Ltd. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
following conditions are met: Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation and/or other materials provided with the
distribution. Neither the name of the Thai Open Source Software Center Ltd nor the names of its contributors may
be used to endorse or promote products derived from this software without specific prior written permission. THIS
SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY
Progress Sonic v8.5 incorporates RSSUTILS v1.1. Such technology is subject to the following terms and
conditions: Copyright 2003 Sun Microsystems, Inc. ALL RIGHTS RESERVED Use of this software is authorized
pursuant to the terms of the license found at http://developer.java.sun.com/berkeley_license.html Copyright 2003
Sun Microsystems, Inc. All Rights Reserved. Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
-Redistribution of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
-Redistribution in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Sun Microsystems, Inc. or the names of contributors may be used to endorse or promote
products derived from this software without specific prior written permission. This software is provided "AS IS,"
without a warranty of any kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A
PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. SUN MICROSYSTEMS,
INC. ("SUN") AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY
LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE,
PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR
PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY,
ARISING OUT OF THE USE OF OR INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You acknowledge that this software is not designed,
licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility.
Progress Sonic v8.5 incorporates DSTC Xs3P version 1.1 from DSTC Pty Ltd. PSC will, at Licensee's request,
provide copies of the source code for this third party technology, including modifications, if any, made by PSC.
PSC may charge reasonable shipping and handling charges for such distribution. Licensee may also obtain the
source code through http://communities.progress.com/pcom/docs/DOC-16051 by following the instructions set
forth therein. - DSTC Public License. The contents of this file are subject to the DSTC Public License Version 1.1
(the 'License') (provided herein); you may not use this file except in compliance with the License. Software
distributed under the License is distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, either
express or implied. See the License for the specific language governing rights and limitations under the License.
The Original Code is xs3p. The Initial Developer of the Original Code is DSTC. Portions created by DSTC are
Copyright (c) 2001, 2002 DSTC Pty Ltd. All Rights Reserved.
August 2011
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
About This Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Progress Sonic Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
SonicMQ Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Other SonicMQ Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Sonic ESB Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Worldwide Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Chapter 1: Overview of Installations and Upgrades . . . . . . . . . . . . . . . . . . 25

About Sonic Installation Maintenance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Types of Progress Sonic 8.5 Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Installer Run Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
About Centralized Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Host Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Container Launcher Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
How Centralized Installation Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Exploring Centralized Installation on One Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
About Zero-Downtime Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
About Dynamic Deployment of Upgrades and Patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Enhancements to the ConfigAdmin Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Progress Sonic Licenses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
File Structure of a Progress Sonic Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Start Menu Commands (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Shell Commands Under Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Shell Commands Under UNIX and Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Accessing Progress Sonic Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Accessing Sonic Workbench Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Progress Sonic Installation and Upgrade Guide 8.5 11

Contents
Chapter 2: Using Progress Sonic Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Planning the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Planning for Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Checklist Before Installing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Licensed for Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Licensed for Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Licensed for Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Using the Sonic Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
About Unattended Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Starting the Sonic Installer in GUI Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Running the Sonic Installer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Initial Panels in the Progress Sonic Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Installing Development Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
Installing a Progress Sonic Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Installing SonicMQ for Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Creating a Runtime Infrastructure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Installing a Domain Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Installing Administration Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Using the Administration Tools After Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Administrative Tasks After Installing Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Extending an Existing Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Chapter 3: Using Progress Sonic Launcher Installer . . . . . . . . . . . . . . . .107

Installing Sonic Container Launcher. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Starting the Sonic Container Launcher Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Running the Container Launcher Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Installing The Sonic Launcher on Distributed Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Chapter 4: Setting Up Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

About the Sonic Launcher and Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Use Sonic Launcher to Setup, Launch, and Add Configuration. . . . . . . . . . . . . . . . . . . . . . . 124
Configure a Container, then Use a Host Manager to Run Setup . . . . . . . . . . . . . . . . . . . . . . 125
Configure Container, Generate Setup File, then Run Setup. . . . . . . . . . . . . . . . . . . . . . . . . . 126
Create Setup File, Run Setup, then Launch to Add Configuration . . . . . . . . . . . . . . . . . . . . 127
Properties in a Setup File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
Running the Container Setup Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
12 Progress Sonic Installation and Upgrade Guide 8.5

Contents
Running Setup Again for a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Windows Services in a Containers Working Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Shutting Down a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Chapter 5: Using Response Files with Installers. . . . . . . . . . . . . . . . . . . . . 135

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Sonic Installer Parameters and Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Capturing Response Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Running Silent Installs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Contents of a Sonic Installer Response File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Response File Parameters for Types of Sonic Installations . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Using a Response File for a Sonic Workbench Installation . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Using a Response File for a SonicMQ Developer Installation . . . . . . . . . . . . . . . . . . . . . . . . 142
Using a Response File for a Sonic Domain Manager Installation . . . . . . . . . . . . . . . . . . . . . 144
Using a Response File for a Sonic Admin Tools Installation . . . . . . . . . . . . . . . . . . . . . . . . . 147
Sonic Updater Parameters and Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Contents of a Response File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Editing a Response File for an Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Sonic Container Launcher Parameters and Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Contents of a Response File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Editing a Response File for a Container Launcher Install. . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Creating Scripted Launcher Installations for Host Managers . . . . . . . . . . . . . . . . . . . . . . . . . 158
Chapter 6: Upgrade Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Planning Sonic Upgrades. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Preparing for Upgrades to Development Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Preparing for Upgrades to Runtime Infrastructures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Version Support in an 8.5 Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Domain-specific configuration objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Distributed Systems Supported in the Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Compatibilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Compatibilities of Administration Tools to an 8.5 Domain . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Compatibilities of Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Compatibilities of Management Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Compatibilities of Clients to 8.5 Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Contents
Chapter 7: Upgrading Version 8 Domains and Tools . . . . . . . . . . . . . . . .173

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .174
Upgrading a Sonic Workbench 8.5 Evaluation License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Phases of Upgrades from Sonic 8.0 to Sonic 8.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Phase I: Upgrade Sonic 8.0 Domain Installations to 8.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Phase II: Install Tools for Deployment Domain Administrators . . . . . . . . . . . . . . . . . . . . . . 184
Phase III: Upgrade 8.0 Components in the 8.5 Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Chapter 8: Upgrading from 7.5 or 7.6 to 8.5 . . . . . . . . . . . . . . . . . . . . . . . . . . .187

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Phases of Upgrades from 7.5 and 7.6 to Sonic 8.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Phase I: Perform 8.5 Installations on 7.5 and 7.6 Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Phase II: Upgrade the 7.5 or 7.6 Domain Manager to 8.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Phase III: Upgrade 7.5 and 7.6 Components To 8.5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Zero-Downtime Upgrades of 7.5 and 7.6 Clusters and Replicated Brokers . . . . . . . . . . . . . . . . . . . .206
Upgrading a Cluster of Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Upgrading Replicated (Fault Tolerant) Broker Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Upgrading a Cluster of Replicated Brokers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Upgrading a Fault Tolerant Management Framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
Upgrading Other Configuration Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Upgrading Activation Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Upgrading Collections Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Upgrading Template Derived Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Verification and Housekeeping Tasks After Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Updating Links to Tools & Integrated Development Environments . . . . . . . . . . . . . . . . . . . 217
Updating Paths to Certificates for the Upgraded Location. . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Updating Paths to External Security Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Encrypting Domain Manager Boot Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Resolving the Status of the Old Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Chapter 9: Updating Sonic Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221

About Sonic Installer Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
Downloading a Sonic Updater . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223
Accessing Java for the Updater. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223
Performing an Update on a Sonic Installer Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .223
Performing Updates on a Fault Tolerant Domain Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224

Contents
Chapter 10: Uninstalling Progress Sonic Products. . . . . . . . . . . . . . . . . . 225
Appendix A: Characters in Progress Sonic Names. . . . . . . . . . . . . . . . . . 227

General Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Naming Rules for Sonic Configuration Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Appendix B: Troubleshooting Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Contents

Preface
This Preface contains the following sections:

About This Guide describes this manual and its intended audience.
Typographical Conventions describes the text formatting, syntax notation, and
flags used in this guide.
Worldwide Technical Support provides information on contacting technical
support.

Preface
About This Guide

This guide provides the prerequisites, procedures, and options used in installation and
upgrading of Progress Sonic development and distributed components. The audience for
this book is the people that perform the tasks of physical installations and configurations.
This guide has the following chapters and appendices:
Chapter 1, Overview of Installations and Upgrades, which describes the topology
of Progress Sonic installations through the various types of product licenses and
installation types. The chapter also describes how to start installed products, and how
to access product documentation, tutorials, and support.
Chapter 2, Using Progress Sonic Installer, details planning and installation of
products for evaluation, development, and deployment for runtime infrastructures.
Chapter 3, Using Progress Sonic Launcher Installer, details installation of
distributed runtime containers, and use of utilities that configure, setup, and launch
new containers.
Chapter 4, Setting Up Containers, shows how the setup of 8.5 containers that was
performed by the Sonic Installer and the Sonic Launcher called a setup utility
application that you can run to set up additional containers. The complete properties
and parameters used by the setup utility are presented and discussed.
Chapter 5, Using Response Files with Installers, shows how the underlying
response files of each of the installers can preset the prompts for unattended
installations that silently use the specified prompts to complete their task.
Chapter 6, Upgrade Planning, describes general planning and compatibilities for all
Sonic upgrades.
Chapter 7, Upgrading Version 8 Domains and Tools, describes techniques for
advancing Version 8 Progress Sonic installations up to Sonic 8.5.
Chapter 8, Upgrading from 7.5 or 7.6 to 8.5, describes the more complex
techniques that bring version 7 Progress Sonic installations up to Sonic 8.5.
Chapter 9, Updating Sonic Installations, describes how to apply service packs to
Sonic Domain Managers, and tools.
Chapter 10, Uninstalling Progress Sonic Products, describes steps to remove and
unregister installed Progress Sonic components from systems.
Appendix A, Characters in Progress Sonic Names, details the naming restrictions
for configuration objects.
Appendix B, Troubleshooting Installations, describes some tips and techniques
when working directly with installations.

Typographical Conventions
Typographical Conventions
This section describes the text formatting conventions used in this guide and a description
of notes, warnings, and important messages. This guide uses the following typographical
conventions:
Bold typeface in this font indicates keyboard key names (such as Tab or Enter) and
the names of windows, menu commands, buttons, and other Sonic user interface
elements. For example, From the File menu, choose Open.
Bold typeface in this font emphasizes new terms when they are introduced.
Monospace typeface indicates text that might appear on a computer screen other than
the names of Sonic user-interface elements, including:
Code examples and code that the user must enter
System output such as responses and error messages
Filenames, pathnames, and software component names, such as method names
Bold monospace typeface emphasizes text that would otherwise appear in monospace
typeface to emphasize some computer input or output in context.
Monospace typeface in italics or Bold monospace typeface in italics (depending
on context) indicates variables or placeholders for values you supply, or that might
vary from one case to another.
This guide uses the following syntax notation conventions:
Brackets ([ ]) in syntax statements indicate parameters that are optional.
Braces ({ }) indicate that one (and only one) of the enclosed items is required. A
vertical bar (|) separates the alternative selections.
Ellipses (...) indicate that you can choose one or more of the preceding items.
This guide highlights special types of information by shading the information area, and
indicating the type of alert in the left margin.
Note Note indicates information that complements the main text flow. Such information is
especially important for understanding the concept or procedure being discussed.
Important Important indicates information that must be acted upon within the given context in order
for the procedure or task (or other) to be successfully completed.
Warning Warning indicates information that can cause loss of data or other damage if ignored.

Preface
Progress Sonic Documentation

Sonic installations always have a welcome page that provides links to Sonic
documentation, release notes, communities, and support. See the releases Product
Update Bulletin book to see whats new and whats changed since prior releases.
The Sonic documentation set includes the following books and API references.
SonicMQ Documentation
SonicMQ installations provide the following documentation:
Progress Sonic Installation and Upgrade Guide The essential guide for installing,
upgrading, and updating SonicMQ on distributed systems, using the graphical,
console or silent installers, and scripted responses. Describes on-site tasks such as
defining additional components that use the resources of an installation, defining a
backup broker, creating activation daemons and encrypting local files. Also describes
the use of characters and provides local troubleshooting tips.
Getting Started with Progress SonicMQ Provides an introduction to the scope and
concepts of SonicMQ messaging. Describes the features and benefits of SonicMQ
messaging in terms of its adherence to the JavaSoft JMS specification and its rich
extensions. Provides step by step instructions for sample programs that demonstrate
JMS behaviors and usage scenarios. Concludes with a glossary of terms used
throughout the SonicMQ documentation set.
Progress SonicMQ Configuration and Management Guide Describes the
configuration toolset for objects in a domain. Also shows how to use the JNDI store
for administered objects, how integration with Progerss Actional is implemented, and
how to use JSR 160 compliant consoles. Shows how to manage and monitor deployed
components including metrics and notifications.
Progress SonicMQ Deployment Guide Describes how to architect components in
broker clusters, the Sonic Continuous Availability Architecture and Dynamic
Routing Architecture. Shows how to use the protocols and security options that
make your deployment a resilient, efficient, controlled structure. Covers all the facets
of HTTP Direct, a Sonic technique that enables SonicMQ brokers to send and receive
pure HTTP messages.
Progress SonicMQ Administrative Programming Guide Shows how to create
applications that perform management, configuration, runtime and authentication
functions.
Progress SonicMQ Application Programming Guide Takes you through the Java
sample applications to describe the design patterns they offer for your applications.

Progress Sonic Documentation
Details each facet of the client functionality: connections, sessions, transactions,

producers and consumers, destinations, messaging models, message types and
message elements. Complete information is included on hierarchical namespaces,
recoverable file channels and distributed transactions.
Progress SonicMQ Performance Tuning Guide Illustrates the buffers and caches
that control message flow and capacities to help you understand how combinations of
parameters can improve both throughput and service levels. Shows how to tune TCP
under Windows and Linux for the Sonic Continuous Availability Architecture.
SonicMQ API Reference Online JavaDoc compilation of the exposed SonicMQ
Java messaging client APIs.
Management Application API Reference Online JavaDoc compilation of the
exposed SonicMQ management configuration and runtime APIs.
Metrics and Notifications API Reference Online JavaDoc of the exposed SonicMQ
management monitoring APIs.
Progress Sonic Event Monitor Users Guide Packaged with the SonicMQ installer,
this guide describes the Progress Sonic logging framework to track, record or redirect
metrics and notifications that monitor and manage applications.
Other SonicMQ Documentation

The Progress Sonic download site provides access to additional client, and JCA adapter
products and documentation:
Progress SonicMQ .NET Client Guide Packaged with the SonicMQ .NET client
download, this guide takes you through the C# sample applications and describes the
design patterns they offer for your applications. Details each facet of the client
functionality: connections, sessions, transactions, producers and consumers,
destinations, messaging models, message types and message elements. Includes
complete information on hierarchical namespaces and distributed transactions. The
package also includes online API reference for the Sonic .NET client libraries, and
samples for C++ and VB.NET.
Progress SonicMQ C Client Guide Packaged with the SonicMQ C/C++/COM
client download, this guide presents the C sample applications and shows how to
enhance the samples, focusing on connections, sessions, messages, producers and
consumers in both the point-to-point and publish/subscribe messaging models.
Provides tips and techniques for C programmers and gives detailed information about
releasing objects and about using XA resources for distributed transactions. The
package also includes online API reference for the SonicMQ C client.

Preface
Progress SonicMQ C++ Client Guide Packaged with the SonicMQ C/C++/COM
client download, this guide presents the C++ sample applications and shows how to
enhance the samples, focusing on connections, sessions, messages, producers and
consumers in both the point-to-point and publish/subscribe messaging models.
Provides tips and techniques for C++ programmers and gives detailed information
about using XA resources for distributed transactions. The package also includes
online API reference for the SonicMQ C++ client.
Progress SonicMQ COM Client Guide Packaged with the SonicMQ C/C++/COM
client download for Windows, this guide presents the COM sample applications
under ASP, and Visual C++. Shows how to enhance the samples, focusing on
connections, sessions, messages, producers and consumers in both the point-to-point
and publish/subscribe messaging models. Provides tips and techniques for COM
programmers. The package also includes online API reference for the SonicMQ
COM client.
Progress SonicMQ 8.5 Resource Adapter for JCA Users Guide for WebSphere
Packaged with this JCA adapter in a separate download, this guide describes the
Sonic Resource Adapter for JCA and using it with a WebSphere application server.
Progress SonicMQ 8.5 Resource Adapter for JCA Users Guide for Weblogic
Sonic Resource Adapter for JCA and using it with a Weblogic application server.
Progress SonicMQ 8.5 Resource Adapter for JCA Users Guide for JBoss
Sonic Resource Adapter for JCA and using it with a JBoss application server.
Sonic ESB Documentation

The Sonic ESB product family provides the following documentation:
Progress Sonic Installation and Upgrade Guide Provides information about
installing, updating, and upgrading Sonic ESB components.
Progress Sonic Workbench User Guide (Progress Sonic Workbench Online Help)
Provides information about developing, testing, and debugging applications on the
Progress Sonic Workbench. Describes the Sonic Workbench, its editors, and tools.
Provides information about how to get started with each component of the Sonic ESB
Product Family and describes sample applications.
Progress Sonic ESB Configuration and Management Guide Provides information
about configuring and managing components used by the Sonic ESB Product Family.
Describes deployment configurations for Sonic ESB, Sonic Database Service, and
Sonic BPEL Server

Worldwide Technical Support
Progress Sonic ESB Deployment Guide Provides information about moving

development projects into test and production environments. Describes
recommended build procedures, domain mappings, and reporting features.
Progress Sonic BPEL Server: Management API Guide Describes how to use the
management API to programatically access BPEL server functionality.
Sonic ESB API Reference Online JavaDoc compilation of the Sonic ESB APIs.
Worldwide Technical Support

Progress Softwares Sonic support staff can provide assistance using the resources on
their Web site at www.progress.com/sonic. There you can access technical support for
licensed Progress Sonic editions to help resolve technical problems that you encounter
when installing or using Progress Sonic products.
When contacting Technical Support, please have the following information available:
The release version number and serial number of SonicMQ that you are using. This
information is listed on the license addendum. It is also at the top of the SonicMQ
Broker console window and might appear as follows:
SonicMQ Continuous Availability Edition [Serial Number nnnnnnn]
Release nnn Build Number nnn Protocol nnn
The release version number and serial number of Sonic ESB that you are using. This
information is listed on the license addendum. It is also near the top of the console
window for a Sonic ESB Container. For example:
Sonic ESB Continuous Availability Edition [Serial Number: nnnnnnn]
Release nnn Build Number nnn
The platform on which you are running Progress Sonic products, and any other
relevant environment information.
The Java Virtual Machine (JVM) your installation uses.
Your name and, if applicable, your company name.
E-mail address, telephone, and fax numbers for contacting you.

Preface

Chapter 1 Overview of Installations and Upgrades
This overview gives the basic ideas in of Progress Sonic installations, in these sections:
About Sonic Installation Maintenance
Types of Progress Sonic 8.5 Installations
About Centralized Installation
About Zero-Downtime Upgrades
About Dynamic Deployment of Upgrades and Patches
Progress Sonic Licenses
File Structure of a Progress Sonic Installation
Start Menu Commands (Windows)
Shell Commands Under Windows
Accessing Progress Sonic Documentation

Chapter 1: Overview of Installations and Upgrades
About Sonic Installation Maintenance

Sonic installation maintenance involves inital installation of Sonic products, and
upgrading existing installations to the current release:
Installing Installation sets up the required software for Sonic development, the
central resources for distributed domains, and the administrative tools. A separate
installer installs the minimal software for remote machines managed in the domain.
Installation procedures in graphical mode are outlined in this chapter, and presented
in detail in Chapter 2 for the Sonic Installer, and Chapter 3 for the Sonic Container
Launcher Installer. Chapter 4 details the setup software that configure containers in
the Directory Service, sets up a containers launch files and working directory, and
enables quick setup of Windows Services. Additional information in Chapter 5
describes unattended, scripted installations for both installers.
Upgrading In this release, Version 8.5, upgrading from 8.0 is easy. Upgrade
development environments and administration-only installs on the machines where
they are installed, but for distributed deployment topologies, you only need to
upgrade the primary Domain Managerall the remote locations are upgraded
through the Sonic Management Console. The distributed systems will be provisioned
with the upgraded software for their container launcher and their components from
the centralized configuration store.
However, if you have domains that are currently in 7.5 or 7.6 runtime infrastructures,
the transition does require installing a 8.5 Domain Manager or Workbench, and some
tasks to advance the version 7 domain and tools to 8.5. Each system that hosts
distributed components also requires an installation of the container launcher and
upgrade toolset.
The transition takes advantage of the new functionality that lets clusters and
replicated brokers function in mismatched versions, greatly simplifying what had
always been a delicate task for complex configurations, and allowing for no downtime
whatsoever in clusters and replicated brokers as they are upgraded.
Upgrade procedures are outlined in this chapter, and presented in detail in Chapter 6.
Updating In Sonic 8.5, updates are similar to upgrades:
An update is applied to installations created by the Sonic Installerdevelopment
environments, deployment domains, and tools.
An update is not applied to distributed deployments created by the Sonic
Container Launcher Installer. The distributed deployments will be provisioned by
their updated domain to update the remote machines launcher files and archives
for deployed components.
Update procedures are outlined in this chapter, and presented in detail in Chapter 9.


The types of installations you can do with the Sonic installers are:
Category Type
Development Sonic Workbench Installs the Sonic ESB development environment.
Environments Includes: Eclipse, Domain Manager, Administration Tools, Launcher, Sonic
Deployment Manager, and JMS Java Client.
SonicMQ Development Installs the SonicMQ development environment and the

SonicMQ sample Java applications.
Includes: Domain Manager, Administration Tools, Launcher, Sonic Deployment
Manager, and JMS Java Client.
Deployment Domain Manager Installs a runtime deployment domain.

Environment Includes: Domain Manager, Administration Tools, Launcher, Sonic Deployment
Manager and JMS Java Client.
Administration Tools Installs tools that configure and manage a domain.

Includes: Sonic Deployment Manager, and JMS Java Client
Launcher Creates an environment to set up and launch management containers that

connect to their Domain Manager to access configuration and runtime artifacts.
Whats a SonicMQ domain? A SonicMQ domain is an administrative grouping of

distributed Progress Sonic management containers, brokers, and resources administered
by one central management node, its Domain Manager. The Domain Manager is defined
by its components:
A management container that provides caching facilities, communicates with its
management node (the broker it hosts, and possibly other brokers in a cluster), and
hosts the other components of the Domain Manager.
A broker dedicated to management communications for the Domain Managers two
essential functions, the Directory Service and the Agent Manager.
A Directory Service that provides centralized storage, and access to configuration
information and runtime artifacts.
An Agent Manager that monitors the state of all containers managed in the domain.
For information about the domain manager, see the Introduction to Configuration
chapter in the Progress SonicMQ Configuration and Management Guide and the
Distributing Components chapter in the Progress SonicMQ Deployment Guide

When SonicMQ is installed as part of the Progress Sonic Workbench, it always performs
a complete, security-enabled SonicMQ installationDomain Manager, management
broker, tools, and client functionality. You can customize some settings such as the
installation location, and port numbers for communications and connection requests.
Important Java Runtime Environment Under Windows, the installer can install the Java Runtime
Environment or you can identify a JVM that is already installed; however, on systems
other than Windows, you must have pre-installed a local Java Virtual Machine as the
installers do not provide one.
If your installation is on UNIX or Linux, first look at the UNIX specific and Linux
specific information in Types of Progress Sonic 8.5 Installations on page 27, as well as
Installation Issues in the release notes. Also, browse to the Support page at
progress.com/sonic and go to the current Supported Platforms page for Sonic Operating
System Version and JVM Vendor Version information.
Installer Run Modes

The installers run in graphical or silent modes, as described:
Without With
response file response file
Mode parameter parameter
Graphical Supported. Not supported.
Silent Not supported. Supported.
Console Not supported. Not supported.


Sonic 8.5 offers centralized installation and associated features that greatly simplify the
configuration and management of distributed deployments.
Centralized installation replaces a set of administrative tasks scattered across the
domains topology with a simple install on each distributed system, and configuration
functions that enable remote administrators to provision distributed systems with their
required resources. Consider how key installation and setup functions have changed:
Function Before centralized installation With centralized installation

Domain Manager Required a sequence of installations All licensed products are installed in one
Setup on the Domain Manager system. process.
Administration Required a sequence of installations All products are installed in one process
Tools Setup on each administrators system. with no license keys needed.
Distributed Required a sequence of appropriate Generic minimal installation creates a
Components installations and license keys on each container that connects to the domain.
system. No license key needed.
Activation Daemons Required a manual configuration task Optional during initial container creation.
on remote system.
Windows Services Required a manual configuration task Optional during initial container creation.
on remote system.
Initial Container Manual commandline action. Optional during initial container creation.
Startup
Data Isolation and Various folders within an installation. Each container maintains all its data in its
Backup own folder. Backing up the Containers
folder backs up all user data.
Sonic Deployment Ran on each distributed system from Runs on the Domain Manager to define the
Manager the model to install appropriate configurations on logical hosts. The
product features and configurations. Domain Manager handles the provisioning
of the distributed systems for the specified
product features.

Host Manager
Sonic 8.0 introduced the Host Manager configuration object, a framework component that
is hosted in a container on a machine to provide a conduit for remote setup and launching
of containers. This minimal configuration running on a remote host enables
administrators to directly set up remote containers that will be automatically provisioned
for the components that the container hosts.
A Host Manager in a container on a remote machine lets you map topology definitions
you create in Sonic Deployment Manager models to machines. There, the running Host
Manager will setup other containers and their components that will be provisionedand
later, remotely upgradedby the Domain Managers.
Container Launcher Installer

Sonic 8.0 introduced the Container Launcher Installer to install lightweight resources on
systems that run 8.0 containers. The Container Launcher Installer can setup a container
during its installation. The container can include an Activation Daemon and a Host
Manager as components, and can setup a Windows Service, encrypt the container
initialization file, and then start the configured container to connect to the domains
Directory Service to insert the configuration.
You can even define a response file with connection information so that you can run a
script to pick up the local machines hostname and use it as the container name to
configure in the domains Directory Service.
With minimal technical expertise required to enable a machine and its role in a domains
deployment topology, the container launcher focuses the complexity of a distributed
computing environment on the administrators from their remote locations.

How Centralized Installation Works

Consider a domain that involves several machines. First you install the Domain Manager
on a machine. Then you install the Container Launcher on several other systems,
specifying that a container is created that defines connection to the Domain Manager,
includes a Host Manager object, and then starts the container.
The following illustration depicts two launcher installations that each setup a container
(ct) with a Host Manager (Hm) and set up a unique name by adding the machine name:
Domain
Mgmt
Domain Broker Host Manager Host Manager
Manager
HOST HOST
Directory MANAGER MANAGER
Service
Container Container
DomainManager ctHmmachineone ctHmmachinetwo
machinezero machineone machinetwo
When an administrator defines the containers for replicating brokers, the configurations
can be pushed through a machines Host Manager to set up the container (as illustrated)

and start the brokers. The new brokers will automatically initialize their store and start
replicationwithout any additional actions at the remote systems.
Domain
Client
Administration
Tools Application
Mgmt Broker
Broker
Domain Broker Backup
Manager br1 br1
Directory Container Container
Service
ct1 ct2
DomainManager
Host Manager Host Manager

HOST HOST
MANAGER MANAGER
Container Container
ctHmmachineone ctHmmachinetwo
machinezero machineone machinetwo
To emphasize how easy that was, consider the case where additional machines are running
containers with a Host Manager, awaiting provisioning. When a catastrophic failure
occurs, the lost broker can reconfigure its replication connection to new machine, and
thenby simply setting up and then launching the lost brokers container through the

recovery machines Host Managerrecovers the broker and synchronizes with the peer
that has been standing alone.
Domain
Client
Administration
Tools Application
Mgmt Broker
Broker Broker
Domain Broker Backup
Manager br1 br1 br1
Container
Service
ct1 ct2 ct1
DomainManager
Host Manager Host Manager Host Manager

HOST HOST HOST
MANAGER MANAGER MANAGER
Container Container Container
ctHmmachineone ctHmmachinetwo ctHmmachinethree
machinezero machineone machinetwo machinethree
Sonic documentation provides a video demonstration of these steps across multiple hosts.

Exploring Centralized Installation on One Machine

You can explore centralized installation on one machine with the understanding that:
One Launcher Installer represents all the remote hosts.
One installed container and Host Manager is used for all the setups.
The broker ports need to be adjusted so that they do not conflict. In distributed
deployments, the host names will need to be distinguished but not the ports.
The lost broker is represented by stopping its container and then deleting its entire
working directory.
The example shows how an administrator can use several distributed containers to
manage real business deployments with no need to access the host systems directly.
The following pages describe and illustrate these procedures:
1. Installing and Running a Domain Manager
2. Installing and Running a Container and Host Manager
3. Configuring a Messaging Broker for a Remote System
4. Deploying the Messaging Broker on a Remote System
5. Configuring a Backup Broker
6. Deploying the Backup Broker on a Remote System
7. Setting up Replication Connections for the Broker Peers
8. Recovering from Catastrophic Failure Gracefully

Installing and Running a Domain Manager

First, create a runtime infrastructure by installing a Domain Manager.
Domain
Mgmt
Domain Broker
Manager
Directory
Service
DomainManager
To install and run a Domain Manager for the example:

1. On the computer you will use for the example, run the Sonic Installer, choose either
Sonic Development or Sonic Domain.
2. Enter a SonicMQ control number.
3. Accept all default values.
4. When the installation completes, start the Domain Manager container.
The Domain Manager is installed and running.

Installing and Running a Container and Host Manager

While you could use the Domain Managers installation to create additional containers,
this example will use a separate installation as though it were a remote host. Using a host
manager will make it easy to setup and launch additional containers.
Domain
Mgmt
Domain Broker
Manager
Directory
Service
DomainManager
Host Manager
HOST MANAGER
Container
ctHmremoteHost
To install and setup a container that has a host manager:

1. On the same computer, run the Sonic Container Launcher Installer.
2. Accept the default location.
3. Choose to configure a container, and then click Next.
4. Accept the connection information, and then click Next.
The default settings will connect to your local Domain Manager.
5. Set the container path and name to /Containers/ctHmremoteHost.
6. Select to create the container configuration if it does not exist.
7. Choose to configure a Host Manager in the container. Accept the HM Path as is.
8. Click Next.
9. Choose to launch the container process.
10. Click Next, and then click Install.
The containers host manager will provide administrative access to setup and launch other
containers in the installation location. It is now configured in the domain and running.

Configuring a Messaging Broker for a Remote System

To illustrate broker replication, configure a container that hosts a broker. You need to
provide a SonicMQ broker license key that supports Continuous Availability to achieve
broker replication.
To configure a broker for the example:

1. Start the Sonic Management Console.
2. Connect to Domain1 at tcp://hostname:2506 where hostname is the local system.
The example is not security enabled so you do not need a username or password.
3. On the Configure tab:
a. Right-click on the Containers folder, and then choose New > Configuration.
Choose Shortcut to Container. In the dialog box, enter the name ct1. Click OK.
b. Right-click on the Brokers folder, and then choose New > Configuration.
Choose Shortcut to Broker. In the dialog box, enter the name br1 and enter a
SonicMQ control key that supports Continuous Availability. Click OK.
c. To avoid port conflicts in this all-on-one-system example, you need to assign the
new broker a different port. Expand the Broker A configuration, and the click on
Acceptors. In the right panel, double-click on TCP_ACCEPTOR. Change the port to
2516. Click OK.
4. In the Containers folder, right-click on ct1, and then choose Add component. Enter
any name, such as Broker 1 Primary. Locate br1, and then click OK.
Next, you will use the Host Manager on the remote host to setup the container on the
remote host, and then launch it.

Deploying the Messaging Broker on a Remote System

With the broker configuration complete, you can now setup the container on a remote
system.
Domain
Client
Administration
Tools Application
Mgmt Broker
Domain Broker
Manager
br1
Directory Container
Service
ct1
DomainManager
Host Manager
HOST MANAGER
Container
ctHmremoteHost
To deploy the configured broker for the example:

1. In the Sonic Management Console, select the Manage tab.
2. Expand the Containers folder, and then click on ctHmremoteHost.
3. On the right panel, right click on HOST MANAGER, and then choose Operations > Setup
Container, as shown:

4. Choose to Setup an already configured container, and then enter (or navigate to) the
container configuration /Containers/ct1, as shown:
5. Click OK. The container is setup on the remote system.

6. Right click on HOST MANAGER, and then choose Operations > Launch Container.
7. Enter ct1, as shown:
8. Click OK.
The container that you set up on the remote host is launched. The container starts, and
then starts the broker it hosts, andbecause it is a new deploymentcreates the tables in
the brokers data store.
The broker console indicates the broker is started and accepting connections.

Configuring a Backup Broker

A backup broker enables data replication between the active broker and its standby so that
the standby is always ready to assume the active role standing alone if its peer becomes
unavailable.
In the example, the broker is running in container ct1. While it is running, you can create,
deploy, and provision a backup broker in container ct2, and define the replication
connection between the peers. Then, an orderly restart of primary brokers container gets
replication underway.
Domain
Client
Administration
Tools Application
Mgmt Broker
Broker
Domain Broker Replication
Backup
Manager br1 Connection (s) br1
Service
ct1 ct2
DomainManager
Host Manager
HOST MANAGER
Container
ctHM_RemoteHost
To create a backup broker to replicate the running broker for the example:
1. In the Sonic Management Consoles Configure tab, right-click on the Brokers folder,
and then right-click on br1.
2. Choose Create Backup Broker. In the dialog box, click OK.
3. On the Configure tab:
a. Right-click on the Containers folder, and then choose New > Configuration.
Choose Shortcut to Container. In the dialog box, enter the name ct2. Click OK.
b. To avoid port conflicts in this all-on-one-system example, you need to assign the
backup broker a different port. Expand the br1 (Backup) configuration, and the
click on Acceptors. In the right panel, double-click on TCP_ACCEPTOR. Change the
port to 2526. Click OK.
4. In the Containers folder, right-click on ct2, and then choose Add component. Enter
any name, such as br1 Backup. Locate br1 (Backup), and then click OK.

Deploying the Backup Broker on a Remote System

Similar to the deployment of the primary broker, use the running Host Manager to set up
this container.
To deploy the configured backup broker for the example:

Container.
container configuration /Containers/ct2.
7. Enter ct2, and then click OK.
The broker console indicates the broker is started and accepting connections.
But the brokers are not replicating. You must define the replication connections.

Setting up Replication Connections for the Broker Peers

The replication connection defines the hosts and ports for replication. For this example,
you enter the actual host name and differentiated port numbers.
To setup replication connections and initiate replication between the brokers:

1. In the Brokers folder, expand br1. Right-click on Replication Connections, and then
choose New Replication Connection. Enter the values shown:
where:
the value hostname (not localhost!) is replaced by the systems host name
the port values are different (because the example is on a single system).
2. Click OK.
The brokers are ready but the primary broker needs to reload
3. On the Manage tab, expand the Containers folder, and then expand ct1.
4. Right-click on the broker name, and then choose Operations > Reload.
5. Observe in the container windows of ct1 and ct2 that the brokers connect and
synchronize:
Container ct1 indicates in its console window that br1 is seeking its peer.
Container ct2 indicates in its console window that br1 (Backup) has left WAITING
state, and is performing deep synchronization with its peer.
The brokers are setup, running, and replicating. The primary broker takes the ACTIVE role,
and its backup takes the STANDBY role.

Recovering from Catastrophic Failure Gracefully

It happens. Anomalies cause systems to become unavailable. In that case, the other broker
stands alone, awaiting resumption of the broker. But in catastrophic situations, the lost
broker cannot recover. Another system will have to pick up the precise installation and
configuration of the lost peer as soon as possible.
Domain
Client
Administration
Tools Application
Broker
Mgmt Broker Broker
Domain Broker Backup Replication
Manager
br1 br1 Connection (s) br1
Directory Container Container Container

Service
ct1 ct2 ct1
DomainManager
Host Manager
HOST MANAGER
Container
ctHmremoteHost
To emulate a catastrophic failure of a replicating broker, and then fully recover:

1. On the Manage tab, expand the Containers folder, right-click on ct1, and then choose
Operations > Shutdown. Failover occurs as br1 in ct2 takes the STANDALONE role,
ensuring continuous availability of the broker.
2. In the installation directory (on Windows, the default location is c:\Program
files\Progress\Sonic), open the Containers directory.
3. Delete the directory Domain1.ct1.
That emulates the loss of the remote system. In a broader topology, you would use a
different machine to recover the broker.
To deploy the lost broker for the example:

Container.

container configuration that was lostin this example, /Containers/ct1.
7. Enter ct1, and then click OK.
The broker console indicates the broker is started and accepting connections and
replicating.
Note In a broader topology, you would delete the replication connection and define a new one
with the machine names of the current machines that host the primary and backup
brokers. If the lost machine was rediscovered and attempted to resume replication, it
would be stalled in WAITING state.
8. Observe in the container windows of ct2 and ct3 that they connect and synchronize:
Container ct2 indicates in its console window that Broker A is seeking its peer.
Container ct3 indicates in its console window that Broker A (Backup) has left
WAITING state, and is performing deep synchronization with its peer.
The brokers are setup, running, and replicating. The primary broker takes the STANDBY role,
and its backup takes the ACTIVE role.
The container cache was provisioned with the libraries to run a broker, created the
brokers data stores, and then completely recovered the continuous availability brokers
with no loss of data, andif the clients specified fault tolerant connectionsno loss of
session states.


The Sonic Continuous Availability Architecture provides enterprise deployments with
resilient, scalable, and virtually 100% production reliability. Previously, when clustered
and replicated brokers were scheduled for upgrades, they were required to all stop,
upgrade, and restart. So unscheduled outages could achieve 100% but scheduled
downtime is still downtime, and service-level agreements often were unforgiving.
Sonic now allows zero-downtime upgrades of clusters and replicated brokers. Consider
the SonicMQ deployment topology in the following illustration:
Domain1
DOMAIN MANAGER 1 CLUSTER OF REPLICATED BROKERS
6
Client Mgmt
Administration 2 Broker
Application
Tools
P B
DS
AM P B
P B
Node C
Node A Node E
BROKER 3 CLUSTER OF BROKERS 4 REPLICATED BROKERS 5

ACTIVE STANDBY
Messaging PRIMARY
BACKUP
Broker Messaging Messaging
Broker Broker
CLUSTER OF BROKERS
Node B Node C Node D
The stages of a version upgrade are:

1. Domain Manager (Node A) The management node can be upgraded while all its
brokers and replication functions are running. The upgrade logic stops the prior
version briefly, and then automatically starts the upgraded version.
2. Administration Tools The toolsets that administrators use must stop, get promptly
upgraded, and then connect to the upgraded Domain Manager.
3. Standalone Brokers (Node B) A standalone broker can be running while its
upgrade is setup. The upgrade logic stops the prior version briefly, and then
automatically starts the upgraded version.

Clusters and replicated brokers are advanced groupings of brokers that are designed
specifically to ensure continuity and scalability.
4. Cluster of Brokers (Node C) All the member brokers of a cluster can be running
as each broker is upgraded. The cluster tolerates other cluster members that continue
to run in the prior version, as each one in turn is upgraded. The cluster node never
stops.
5. Replicated Brokers (Node D) When broker replication is functioning, one peer is
in the ACTIVE mode while the other is in STANDBY mode. The upgrade of the primary
peer completes by restarting its upgraded version, forcing failover to the peer, and
then resumption of replication between the peers. Then, when the upgrade of the other
peer is performed, the upgrade of the node is complete.
Throughout the upgrade process, the node was always available. Fault-tolerant clients
handle transitions between the peers, keeping session and transaction states intact.
6. Cluster of Replicated Brokers (Node E) Combining the benefits of clusters and
replicated brokers provides the most resilient and scalable node structure. Implicitly,
architects of such topologies want zero-downtime. And they can achieve it.
The Zero-Downtime Upgrade feature takes enterprise resilience to a new level, one where
staying up to date on product releases, and striving for 100% non-stop processing can both
be optimized in service level agreements.


Upgrades of Sonic 7.5 and 7.6 installations requires some tasksinstalling a launcher and
running an upgrade utilityon each host system to bring them into compliance with the
centralized installation and provisioning paradigm.
Going forward, upgrades and patches will no longer require any actions on distributed
systems in the domain. Importing upgrade and patch libraries into the Directory Services
Sonic File System will automatically provision the deployed components upon container
restart. Any additional upgrade or update actions will be performed through the
connection to the Domain Manager.
Rollout of changes can be controlled so that large scale deployments can specify a set of
hosts to upgrade, verify the results, and then apply changes to another set.
Enhancements to the ConfigAdmin Utility

The ConfigAdmin utility (located in MQ8.5/bin) has been enhanced to provide support for
centrally installing and dynamically deploying upgrades and patches.
To help support the centralized installation of upgrades and patches, new operations have
been added for manipulating the Directory Service's Sonic File System:
import-files <fromFSPath> <toDSPath>

copy-files <fromDSPath> <toDSPath>
create-folder <folderPath>
delete-files <dsPath>
rename-folder <oldPath> <newPath>
rename-file <oldPath> <newPath>
New operations have also been added to help centrally manage and optimize the
incremental deployment of upgrades and patches on a container-by-container basis:
copy-ds-files-to-container-caches <ds-path>
<container-list-file>|all-containers [exclude]
modify-archive-search-path <new-path>
<container-list-file>|all-containers [exclude]
where:
<container-list-file> is a text file where each line is one container path
[exclude] when specified, uses containers in the list as an exclusion list

Progress Sonic Licenses

Many Progress Sonic installations require one or more license keys (control numbers) that
determine the configuration options available to you:
When you register for evaluation at www.progress.com/sonic, a license key for an
Evaluation Edition is sent to your e-mail address. Note that an evaluation license key
expires at the end of the evaluation period.
For Progress Software customers, the license key is in the License Addendum
included with the product.
Product packagings (SKUs) might include several types of licenses.
The license keys entered for various Progress Sonic installation types are:
Installation Type Evaluation License Runtime Licenses

Development Sonic Workbench Sonic Workbench
Environment
SonicMQ SonicMQ Professional Developer
Deployment SonicMQ SonicMQ Continuous Messaging

Environment Sonic ESB CAA SonicMQ Messaging
Sonic ESB
Sonic ESB CAA
Sonic BPEL Server
Administration
Tools
Launcher
The features that distinguish the SonicMQ runtime licenses are:

License Type Evaluation licenses provide time-delimited full access to the product
functionality. Platform and user restrictions for each license type are detailed in the
End User License Agreement, installed at progress_sonic_license.txt.
Continuous Availability When a SonicMQ messaging broker does not have this
functionality, clients requests for fault tolerant connections are downgraded. Also,
broker replication is not functional unless the peer brokers are licensed for
Continuous Availability.
You need a SonicMQ evaluation license for deployment evaluation, and a Sonic ESB
evaluation license to evaluate ESB in a deployment environment.

All Progress SonicMQ licenses enable:

Broker clustering.
Progress Sonics Dynamic Routing Architecture.
Unlimited number of connections
HTTP Direct acceptors and routings that enable inbound JMS messaging from HTTP
documents and outbound JMS messages to be transformed into HTTP documents.
Extended client functionality for client persistence and large message support through
recoverable file channels.

The layout of files installed by the Progress Sonic installers is based on best practices for
data management. The following screen capture illustrates a Sonic Workbench
installation, and a closer look at the contents of a container folder:
Notice the following aspects of the installation:

Archives directory which maintains the sets of libraries that support the functionality
that the container hosted components require. The contents of this directory are
provisioned to the remote location by the domain that manages the installation.
Containers directory with a subdirectory for each domain.container set up to launch
from this installation location. Each subdirectory is the working directory for that
containers process, and the default location for the containers cache, log files, and

the stores of hosted components such as a broker or a BPEL server. The Containers
directory should be backed up routinely.
Versioned product directories
Launcher directory contains the scripts and libraries used to setup and launch
containers from this installation location.
The following table describes the usage, installation, and installed functionality of Sonic
8.5 components.
Table 1. Functions installed by Sonic Installer types and Sonic Launcher
Usage Development Environments Deployment Domain and Distributed Functions
Installer Sonic Installer 8.5
Sonic
Development: Sonic Sonic Sonic
Workbench Development: Administration Container
Install Type key MQ key Sonic Domain Tools Launcher
Details Page 76 Page 82 Page 87 Page 91 Page 108
Archives Y Y Y
BPELServer8.5 Y Key required No key required
Containers Y Y Y Y
DBService8.5 Y No key required No key required
ESB8.5 Y Key required No key required
jre (on Windows) Y Y Y Y Y
Launcher Y Y Y Y
MQ8.5 Y (Dev edition) Key required Key required No key required
(Dev edition)
SDM8.5 No key required No key required No key required No key required
Uninstall Y Y Y Y Y
Upgrade Y Y Y
(utilities for migration
of earlier versions)
Workbench Key required
(plus Eclipse)
JMS Java Client

The JMS client is installed with every type of Sonic Installer installation. The JMS Client
installs libraries and scripts for the SonicMQ Java Client, andon Windowsa
supported Java Virtual Machine. A complete development environment for SonicMQ Java
applications requires a Java SDK (specifically, an appropriate Java compiler, javac.exe)
so that you can compile Java applications. Compiled Java bytecode can then be ported to

other platforms to run under that platforms recommended Java Runtime Environment.
The Sonic JMS Java client libraries and their supporting libraries are listed in Table 2:
Table 2. Functionality Provided by SonicMQ JMS Client Libraries
Functionality Sonic Library Supporting Libraries

Basic SonicMQ client sonic_Client.jar -
Message selection sonic_Selector.jar -
XMLMessage and MultipartMessage sonic_XMessage.jar XML messages:

xmlParserAPIs.jar;
xercesImpl.jar
Multipart messages:
activation.jar
Local persistence sonic_SF.jar -
Recoverable File Channels sonic_Channel.jar -
SonicStream sonic_Client_ext.jar -
XA resources sonic_XA.jar -
Consumer connection to App Servers sonic_ASPI.jar -
Authentication and QoP sonic_Crypto.jar -
Enable Secure Socket Layer protocols sonic_SSL.jar -
Tracing sonic_tracing.jar aspectjrt.jar

aspectjweaver.jar
Note Dynamic Classpaths While Sonic components manage their class loading, client
installations could have a long classpath statement in their command line to load all the
client and security JARs. To relieve this problem, the sonic_Client.jar loads its classes
and then dynamically attempts to load all the Sonic libraries listed in Table 2.
Note Other SonicMQ JMS Clients Other SonicMQ JMS clients are packaged in separate
download packages:
C / C++/COM Clients The SonicMQ C/C++/COM clients are packaged in separate
archives for each supported Windows, UNIX, and Linux platform.
.NET Client SonicMQ .NET client provides SonicMQ client functionality for C#
and.NET applications, certified on several Windows platforms.


The Start menu for Progress provide access to the following commands for the installed
Sonic products. The following examples describe a Sonic Workbench installation:
Launching the Sonic Domain Manager Starts the domain so that the management
broker, Directory Service, and Agent Manager are available to administrative tools
and managed components.
Note Before starting the Sonic Workbench, start the Domain Manager. If you do not, you
are prompted to do so after you launch the Workbench.
To launch the Domain Manager, choose:
Launching the Sonic Workbench Once the Domain Manager has started, launch
the Sonic Workbench. Choose:
Accessing the Progress Sonic Tools The JMS test client is common to all Start
menus. The Workbench, Domain Manager, and Administration Tools also include a
command prompt set at the ESB8.5 installation root, the ESB admin tool, and the
graphical ESB export and import tools. Choose Tools, and then choose a tool:

Launching the Management Console The Sonic Management Console (SMC)

provides the configuration and management of configured components. Choose:
Stopping the Sonic Domain Manager You can perform an orderly shutdown of the
Domain from a Windows Start menu by choosing Stop Domain Manager. When
running the Sonic Workbench, exit the Sonic Workbench, and then choose:
Accessing Documentation Choose Documentation to open the documentation

welcome page that links to documentation and support resources (except the online
Workbench help, embedded in the Eclipse help system):

Shell Commands Under Windows

Shell commands on Windows are usuallly not needed as the Start menu commands
manage these as shortcuts. However, in circumstances where no shortcuts were created by
the installerfor example, not configuring the domain at installation, and then creating
the domain through the Sonic Deployment Manageror shortcuts have been corrupted,
you can use shell commands to launch the same scripts the shortcuts would run. In a
Command Prompt located at the specified location in your Sonic installation, enter the
command you want from the following table:
Component Function Location Command
SonicMQ Start Domain sonic_install_dir/Containers Domain1.DomainManager\launchcontainer.bat

Manager
SonicMQ Stop Domain sonic_install_dir/Containers Domain1.DomainManager\shutdowncontainer.bat

Manager
SonicMQ Management sonic_install_dir/MQ8.5 bin\startmc.bat

Console
SonicMQ JMS Test sonic_install_dir/MQ8.5 bin\testClient.bat

Client
Sonic ESB ESB Admin sonic_install_dir/ESB8.5 bin\esbadmin.bat

Tool
Sonic ESB Deployment sonic_install_dir/ESB8.5 bin\deployExport.bat

Export Tool
Sonic ESB Deployment sonic_install_dir/ESB8.5 bin\deployImport.bat

Import Tool
Sonic Start Sonic sonic_install_dir/Workbench8.5/eclipse eclipse.exe --launcher.ini SonicLauncher.ini

Workbench Workbench (note that you must enter two dashes)

Shell Commands Under UNIX and Linux
Shell Commands Under UNIX and Linux

Shell commands on UNIX and Linux launch the Sonic components and tools, as listed in
the following table:
Component Function Location Command
SonicMQ Start Domain sonic_install_dir/Containers . ./Domain1.DomainManager/launchcontainer.sh

Manager
SonicMQ Stop Domain sonic_install_dir/Containers . ./Domain1.DomainManager/shutdowncontainer.sh

Manager
SonicMQ Management sonic_install_dir/MQ8.5 . ./bin/startmc.sh

Console
SonicMQ JMS Test sonic_install_dir/MQ8.5 . ./bin/testClient.sh

Client
Sonic ESB ESB Admin sonic_install_dir/ESB8.5 . ./bin/esbadmin.sh

Tool
Sonic ESB Deployment sonic_install_dir/ESB8.5 . ./bin/deployExport.sh

Export Tool
Sonic ESB Deployment sonic_install_dir/ESB8.5 . ./bin/deployImport.sh

Import Tool
Sonic Start Sonic sonic_install_dir/Workbench8.5 . ./startworkbench.sh

Workbench Workbench


Every installation of Progress Sonic 8.5 products includes progress_sonic_welcome.htm
at the root of the installation. The documentation welcome page points to the versions
documentation location, download site, and other Progress resources.
To access a welcome page, do any of the following:

In a browser, open sonic_install_dir/progress_sonic_welcome.htm.
On Windows, select Start > Programs > Progress > Sonic8.5 > Documentation.
On Sonic Workbench, choose Help > Sonic Documentation.
The Progress Sonic 8.5 Welcome page opens, as shown:

The links on the Welcome page connect to the following Progress web locations:
Access Documentation Opens the Sonic 8.5 documentation page at its remote
site.
Download Documentation Packages Downloads of the complete set of books and
APIs, focused documentation subsets, and online access to the most current
documentation.
View the Release Notes Complete reporting of known issues and resolved issues
in all the Sonic 8.5 products. (You can access earlier Sonic 8 release notes at PSDN.)
Download Software The Electronic Software Download Site (ESD) provides
Progress Software customers and prospects controlled access to all Progress Software
products.
Go to Sonic Communities and Forums Check in with a vibrant community for
discussions, code sharing, whitepapers, and webinars
Go to the Progress Sonic web site Sonic's home page links to success stories,
solutions, resources, support, news, and events.
Get Support Sonic's support page lets you find the currently supported platforms,
resources, knowledgebase, and technical support offerings that you need.
Contact Progress Software Request information, and locate Progress Software
offices worldwide.
Important Documentation on Media If you are denied access to the public internet, request the
Progress Sonic 8.5 Documentation disk from your Progress representative.
Accessing Sonic Workbench Documentation

Ther are alternate formats of Sonic Workbench online help. In an installed and running
Sonic Workbench:
Choose Help > Help Contents to access the online help in the Workbench.
Choose Help > Sonic Documentation to access the Progress Sonic 8.5 Welcome
page where you can connect to the 8.5 documentation page at its remote site to:
Read and download Sonic Workbench Online Help formatted in PDF books
Connect to the remote Infocenter of the Sonic Workbench online help.
The Progress Sonic Infocenter provides an Eclipse-independent deployment
of the Sonic Workbench online help in the Progress Sonic Workbench User
Guide. With just a browser, access the Infocenter at:
http://documentation.progress.com/infocenter/sonic/8.5


Chapter 2 Using Progress Sonic Installer
This chapter describes how to install Progress Sonic software and configurations and
contains the following sections:
Planning the Installation
Checklist Before Installing
Using the Sonic Installer
Running the Sonic Installer
Installing Development Environments
Creating a Runtime Infrastructure
Using the Administration Tools After Installation
Extending an Existing Installation

Chapter 2: Using Progress Sonic Installer

Before installing Sonic, consider the following issues:
Platform requirements
Software downloads and other software components
Character sets
Security
These issues are covered in the following sections.
Hardware Requirements
Hardware requirements for Sonic involve the memory and disk resources on a computer
and the operating system in use.
Memory and Disk Requirements

The amount of random-access memory (RAM) and overall hard disk space required
depends on your disk cluster size, anticipated message traffic volume, the size of your
messages, the number of other applications running, and the number of brokers running.
The following system characteristics are guidelines:
Complete installation and evaluation on one system:
512 MB RAM
1.5 GB of disk space
Deployed components and brokers:
256 MB RAM
500 MB-1 GB of disk space
Client components:
16 MB RAM
64 MB of disk space

Supported Operating Systems

See the Progress Software support page at www.progress.com/sonic for a complete list of
currently supported platforms and any special platform requirements.
Warning For components that write to disk (a brokers persistent store and recovery logs, each
containers cache, and the Directory Service store), do not use buffered disk writes or
network drives in virtually all circumstances. Buffered disk writes (write caching)
couldunder an unanticipated power outagecorrupt data in the write cache before the
data is written to disk. However, some sophisticated data storage systems (such as top-
end SCSI RAID arrays) provide reliable write caching that is suitable for use with Sonic.
Software
Progress Sonic is designed to interface with specified third-party software. The
distribution software provides a complete Sonic installation yet also allows for interfacing
with compatible software.
Eclipse
Sonic 8.5 Workbenchs Eclipse development environment requires Eclipse 3.6.
The Sonic Installer will install Eclipse 3.6 as the preferred Eclipse.
Java Under Windows

The Sonic installers provide the Java Virtual Machine (JVM) they need to run the
installer software. It also can copy the recommended JVM for Windows platforms to the
target system. (Refer to the Progress Sonic supported platforms page for specifics.) If you
prefer to use a different runtime environment that is already installed on the target system,
refer to the Sonic Release Notes to determine whether the selected version has known
issues when running Sonic.
Java Under UNIX or Linux

Under UNIX and Linux, the Sonic installation routines do not install Java Virtual
Machine software. You need Java to run the Java-based installer software and you also
need the appropriate Java installed and on the path and set as Java home for the product
runtime. Preferably, use a Java version for installation that is supported for the runtime of
the installed software. See www.progress.com/sonic for more information about supported
platforms.

You can review the Java installation on your target UNIX or Linux system in a new
terminal window by entering java -version (java -v or which java on some systems).
If there is a response, note if it is an appropriate version. If it is not, obtain an appropriate
version and install it.
Note When selecting a JVM, the installer confirms your selection is a valid path, but not
whether it is a supported platform.
If you are choosing a supported 64-bit JVM, suppliers that provide a separate JVM
download and installation for 32-bit and 64-bit are evaluated correctly; however, some
JVM suppliers (such as AMD) provide a dual-mode JVM. After you install the JVM
pointing to the root of the JVM folder (where /bin is a subdirectory), set the -d64
argument on the Environment tab of the containers properties to force the JVM into 64-
bit mode.
Note Other Progress Sonic Products Other products in the Progress Sonic family can
extend the range and functionality of your complete deployment. See the Sonic Web site
for information about SonicMQ C/C++/COM and .NET clients, as well as the Sonic
Workbenchthe development environment for Sonic ESB, Sonic BPEL Server, and
Sonic Database Service.
Planning for Security

Implementing security requires planning for its scope and resources. The installations that
form a deployment must set up and integrate the technologies and the procedures that
make security work, for example:
Authentication and authorization
Quality of Protection
HTTP tunneling and proxy servers.
Ciphers and encryption used in message Quality of Protection and SSL/HTTPS
channel encryption.


Progress Sonic 8.5 is installed from one installer program, and includes the Eclipse
environment, Sonic plugins, all the Sonic products, and all the Sonic tools. The
requirements and options for Progress Sonic Workbench are streamlined for evaluation
licenses, while development licenses allow for several options, including the opportunity
to initiate an upgrade to an existing installation.
Licensed for Evaluation

Progress Sonic allows for time-delimited evaluation of the Sonic Workbench and
SonicMQ.
Checklist in preparation for evaluation of Progress Sonic 8.5:

1. [ ] Required license keys You must have license keys to install evaluation
software.
Sonic Workbench install Its evaluation license key provides corresponding
time-delimited licensing for each of the component products.
SonicMQ Developer install Its evaluation license key provides time-delimited
licensing for SonicMQ.
2. [ ] Supported platform Confirm that the system where you plan to perform an
installation is a supported platform. For more information, see the Progress Sonic
Web page, www.progress.com/Sonic.
3. [ ] Disk space available Confirm that you have adequate disk space (and, under
Linux, available disk quota in your target directory) for the installation. If you are
installing from media, you need at least 1.5 GB and should have at least another
400 MB available disk space for data files and logs.
4. [ ] Installation location is not in use An existing target directory should be a new
directory or cleared of any residual artifacts from a previous Sonic installation.
5. [ ] Default port available Check whether the default port value, 2506, is in use. You
can choose any port you want to use but the selected port number must not be in use.
A Sonic Workbench evaluation installation can be upgraded to a registered development
license through utility software. A SonicMQ evaluation installation can be upgraded to a
development license by updating the control code of each broker.

Licensed for Development

Sonic Workbench and SonicMQ offer development licensing. A license for Sonic
Workbench development allows you to choose an existing Eclipse installation on the
target system.
Checklist in preparation for development installation of Progress Sonic 8.5:

1. [ ] Required license keys You must have license keys to install development
software.
Sonic Workbench install Its developer license key encompasses corresponding
licensing for each of the component products
SonicMQ Developer install A SonicMQ Professional Developer license key is
required.
can choose any port you want but the selected port number must not be in use.
6. [ ] Determine if you want to use an existing Eclipse installation While the Sonic
installer will install a complete Eclipse tool set for Sonic development, you can
choose to install Sonic Workbench tools into an existing Eclipse environment.
Set your Eclipse to the workspace you want to use for Sonic development before
starting the installation.
Important If you choose to use your existing Eclipse environment, you are encouraged to make
a complete backup of it as well as its workspaces.

Licensed for Deployment

A license for deployment allows the installer to offer greater options in names, locations,
and JVM.
Checklist in preparation for deployment installation of Progress Sonic 8.5:

1. [ ] Required license keys You must have license keys to install deployment
software:
Domain Manager install Deployment license keys:
Requires a SonicMQ deployment license key.
Adding a Sonic ESB license key provides support for ESB deployments.
Adding a Sonic BPEL Server license key extends ESB deployments for
developed Sonic BPEL Servers.
Administration Tools install None of the tools require license keys.
can choose any port you want but the selected port number must not be in use.
6. [ ] Launcher Installer is available to setup distributed hosts The Sonic Container
Launcher will need to be installed on distributed systems that will host containers.
The Launcher installer requires no license keys and can create a management
container that includes a Host Manager as a component.


The Progress Sonic Installer provides the Progress Sonic software required to develop,
deploy, and administrate Sonic domains and distributed brokers, applications, and
services.A Java Runtime Environment is required by the installed software, and the
preferred JRE for Windows can be installed during the procedure.
The installer software supports two techniques for installation:
Graphical Installer wizard.
Unattended install with tailored data.
In each of these techniques you are prompted with information that you can change to
tailor the characteristics of the current installation.
Note Tailoring the Prompts in the Installer The prompts presented in the installer can be
tailored in advance so that your preferred prompts are displayed. Tailoring all the prompts
for an installation also enables running the installer and complete the process unattended.
See Chapter 5, Using Response Files with Installers, for information on capturing,
preparing, and running response files.
About Unattended Installation

An unattended installation, also called a batch or silent installation, presents no GUI and
can be run unattended. You can use it in a script so that many installations can be
performed without user intervention.
Because unattended installation has no interactive elements, the following chapter,
Chapter 5, Using Response Files with Installers, describes how to define and use a
response file that will provide the information used by the installer.

Starting the Sonic Installer in GUI Mode

The startup instructions are described separately for Windows, UNIX, and Red Hat Linux.
To start the Installer wizard on Windows:

1. Mount the distribution media or unpack the installer package on the local system.
2. Open a command prompt at the folder that has install.exe.
3. Run install.exe.
The installer starts. Follow the procedures for Running the Sonic Installer on page 69.
To start the Installer wizard on UNIX:

Note These instructions are Solaris-specific. Some steps might vary slightly for other versions
of UNIX. See your operating system manual for information about installing software.
1. If you are installing from distribution media, put the media into your machines
CD/DVD drive.
Important The mount command or procedure that you use must support mixed case and file
names that are not restricted to eight characters with a three-character extension.
Consult with your IT department to define the command syntax or procedure that
supports mixed case and longer file names when mounting the CD/DVD drive.
2. The Sonic Installer requires a JVM to run. Confirm that you have a JVM installed and
in your PATH. Refer to the Progress Sonic Web site for the supported JVMs for your
UNIX brand.
3. Open a console window and locate it in the directory that contains install.bin.
Note When using remote login, and using an X-Session that accepts remote connections,
you might need to enter the command DISPLAY=hostname:0;export DISPLAY before
launching the installer.
4. Run install.bin.

To start the Installer wizard on Red Hat Linux:

1. Access and install the appropriate JVM for the installer. Refer to the Progress Sonic
Web site for the supported platforms for the Sonic installer and for the installation.
2. If you are installing from distribution media, put the disk into your machines
CD/DVD drive.
3. In a terminal window, change directories to the directory where install.bin is

located.
4. Confirm that the correct Java for the installer is the first Java in the path by entering
which java or java -version.
5. Launch the installer startup script: install.bin.



You can install the Progress Sonic 8.5 development and deployment products with the
Sonic Installer.
The Sonic Deployment Manager (SDM) is installed with every installation type in the
Sonic Installer. For more information, see the Progress Sonic Deployment Manager
Users Guide 8.5
Initial Panels in the Progress Sonic Installer

Once you start the Sonic Installer (described on page 65), its Java process opens the
Progress Sonic 8.5 Installer window at the Introduction panel.
1. Click Next.

The Readme panel opens.
2. Determine if you have required license keys and whether you want to access the
documentation before proceeding.
3. Click Next.

The License Agreement panel opens.
4. After you read, understand and agree to the license terms, click that you accept the
agreement, and then click Next.

The Choose Installation Location panel opens.
5. Choose whether you are adding features to an existing installation, or creating a new
installation:
Select Add features to an installation location when an installation skipped some
products. Choose this option to extend the installation to include additional
products.
You must then choose the existing Install Location to extend.
See Extending an Existing Installation on page 101 for more information.
Select Install into a new location to specify an empty or non-existent folder for
the installation.
Specify the path on a local drive that is a new or empty folder.
The default folder on Windows is C:\Program Files\Progress\Sonic, and the
default folder on UNIX and Linux is /opt/user/Progress/Sonic.
Important Spaces in Path Names Spaces are allowed in Windows location paths.
Spaces are not allowed in UNIX and Linux location paths.

Note Characters in installation location names The installer does not accept some
characters that, while acceptable as folder names on the target platform, can
create problems in evaluation of names in SonicMQ and the Sonic ESB product
family.
The filtered characters are: ampersand (&), semicolon(;), caret (^), equal sign (=),
plus sign (+), comma (,), tilde (~), bang (!), at sign (@), pound (#), dollar sign ($),
percent (%), open/close parentheses (( )), open/close brackets ([ ]), and open/close
braces ({ }).
While spaces in names are not filtered, a good practice is to avoid spaces, using
an underscore (_) as a separator, such as my_folder/my_subfolder.
Uppercase and camelCase in names is valid but you can minimize potential
issues on disparate platforms by maintaining all names in lowercase.
Keep the path name brief andwhile embedded spaces are supported for this use
in Progress Sonicusing spaces in a path name is not advised as it might require
you to place path statements in quotation marks in custom scripts and other
toolsets. As an example, you might install in the path E:\dev\Sonic.
6. Specified the preferred installation location, and then click Next.

The Choose Installation Type panel opens.
Figure 1. Sonic Installers Choose Installation Type panel
7. The type of installation guides the installer to select appropriate options and
parameters for the software it will install. Choose the installation type you want, and
then advance to the corresponding instructions:
Installing Development Environments on page 75
For Sonic ESB development, choose Sonic Development, and then click
Next. Go toInstalling a Progress Sonic Workbench on page 76 to continue.
For SonicMQ development, choose Sonic Development, and then click Next.
Go to Installing SonicMQ for Development on page 82 to continue.
Creating a Runtime Infrastructure on page 86
Choose Sonic Domain, and then click Next.
Go to Installing a Domain Manager on page 87 to continue.
Choose Sonic Administration Tools, and then click Next.
Go to Installing Administration Tools on page 91 to continue.
In order to establish distributed deployments of runtime components, use the other
Progress Sonic 8.5 installer, the Progress Sonic Container Launcher Installer 8.5.
See Starting the Sonic Container Launcher Installer on page 108 for more information.


Sonic provides both time-limited evaluation and full usage licensing of two development
environments:
Sonic Workbench A complete development platform for web services and
enterprise services, that includes all the Sonic tools and products:
Eclipse development platform with perspectives for Sonic development and
testing
Sonic ESB products (Sonic ESB, Sonic Connect, Sonic BPEL Server, and Sonic
Database Service) and samples
SonicMQ as the underlying messaging infrastructure. Includes the SonicMQ with
messaging and management samples
Sonic Administration Tools including the Sonic Management Console, and the
JMS Test Client
Sonic Deployment Manager (SDM) and the SDM sample models
On Windows, the preferred Java Runtime Environment (optional)
See Installing a Progress Sonic Workbench on page 76 for this type of installation.
SonicMQ Development A complete development platform for secure messaging
applications, and deployment of framework components and messaging brokers, that
includes the following Sonic tools and products:
SonicMQ with messaging and management samples
Sonic Administration Tools including the Sonic Management Console, and the
JMS Test Client
Sonic Deployment Manager (SDM) and the SDM sample models
On Windows, the preferred Java Runtime Environment (optional)
See Installing SonicMQ for Development on page 82 for this type of installation.

Installing a Progress Sonic Workbench

When you choose Sonic Development on the Sonic Installers Choose Installation Type
panel on page 74, the next panel is the Progress Sonic License Keys panel.
A Sonic Workbench license key for evaluation or development will focus the
installation on Sonic Workbench. A Sonic Workbench key is a composite code. The
key you enter will generate corresponding evaluation or development keys for the
Sonic products on the Workbench:
SonicMQ
Sonic ESB
Sonic BPEL Server
1. Enter the license key provided to you for Progress Sonic Workbench 8.5.
Click Next.

The Sonic Workbench Configuration panel opens.
2. If you are installing this Sonic Workbench as the basis for upgrading an installed
Sonic Workbench, select the option Do not configure at this time. The upgrade utility
will configure the domain in its migration process. As appropriate, see:
Upgrading Version 8 Domains and Tools on page 173, or
Upgrading from 7.5 or 7.6 to 8.5 on page 187, or
3. The management broker in the underlying messaging infrastructure specifies a port
on which it will accept management connections. The same connection is also used
for client messaging connections, in the development environment. As many preset
samples and examples use the preset port value 2506, try to make that port available
to Sonic rather than changing the port value.
Specify the management brokers port value (between 1024 and 65536).
4. Click Next.

The Choose Eclipse panel opens.
The preset option is to have the installer install the preferred version of the Eclipse
open development platform, version 3.6.0, within the installation directory.
The installer will attempt to discover qualified Eclipse installations that could be
used. To choose one such Eclipse, click Choose an existing Progress Eclipse
installation, and then click on your preferred Eclipse.
To locate an installed Eclipse that is not displayed, click Choose another Eclipse
installation, and then click Browse. Navigate to the /Eclipse directory you want to
use, and then click Choose. The installer will verify that you selected an acceptable
Eclipse.
5. Specified the preferred Eclipse for this Sonic Workbench, and then click Next.

The Choose Java Virtual Machine panel opens.
On Windows, the preset option is to have the installer create a Java Runtime
Environment (JRE) within the installation directory.
On any platform, the installer will attempt to discover qualified JREs that could be
used. To choose one such JRE, click Choose a Java VM already installed on this
system, and then click on you preferred JVM.
To locate an installed JVM that is not displayed, click Choose another Java VM, and
then click Browse. Navigate to the /jre/bin directory of the chosen JRE, and then
choose java.exe. When you click OK, the installer will verify that you selected an
acceptable JVM.
Important Your selection of an installed JVM applies to use by the runtime software.
6. Specify the preferred JVM option and location, and then click Next.

On Windows systems, the Choose Shortcut Location panel opens.
While the Start menu will always be created as Progress > Sonic 8.5, you can choose
to also place the Workbench launch shortcut on the Windows desktop and the
Windows Quick Launch toolbar.
7. Select your preferred Workbench shortcut locations, and then click Next.

The Pre-Installation Summary panel opens
As all the steps to this point have caused no changes on the target system, you are
provided a review point to review the selections and the data requirements before
starting the actual installation.
8. Click Previous to go back through the panels and make changes, or
click Install to start installation.
When the install process finishes, the Install Complete panel opens.
9. Click Done.
The Progress Sonic Installer 8.5 closes.
Open the progress_sonic_welcome.htm file at the installation root to connect to
documentation and other Progress Sonic resources.

Installing SonicMQ for Development

When you choose Sonic Development on the Sonic Installers Choose Installation Type
panel on page 74, the next panel is the Progress Sonic License Keys panel.
A SonicMQ evaluation or development license key (control number) will focus the
installation on SonicMQ.
1. Enter the license key provided to you for Progress SonicMQ 8.5.
Click Next.

The Configure Domain Manager panel opens.
The option to not configure the domain as a part of the installation process should not
be selected in a development install.
2. Enter a Domain Name, or accept the default name, Domain1.
3. Enter a Management Container Name, or accept the default name, DomainManager.
4. Enter a Management Broker Name, or accept the default name, MgmtBroker.
5. As many preset samples and examples use the preset port value 2506 on the broker,
try to make that port available to Sonic rather than changing the port value.
Specify the Management Port value (between 1024 and 65536).
6. Security is not enabled by default on a SonicMQ management broker. You can choose
to enable security by checking this option. If you are evaluating SonicMQ, you will
find that enabling security adds a level of complexity to some samples.
Choose whether to Enable Security on the management broker.
7. Click Next.

system, and then click on you preferred JVM.
acceptable JVM.
Important Your selection of an installed JVM applies to use by the runtime software..

As all the steps to this point have caused no changes on the target system, you can
review the selections and the data requirements before starting the actual installation.
10. Click Done. The Progress Sonic Installer 8.5 closes.



A runtime infrastructure is comprised of one or more Domain Managers, distributed
installations of runtime components, administration tools, and clients to support
applications.
A runtime infrastructure includes:
Sonic Domain Manager The central point of component provisioning, upgrades,
and updates. The license keys entered for a Domain Manager enable it to configure
and manage distributed components. They also enable the Domain Manager to deploy
a component by simply adding the components configuration to a management
container. Upgrades and updates simply added to the Directory Service store
propagate to the appropriate components dynamically.
Sonic Administration Tools The toolset for all the products can be on every
administrators system so that they can authenticate and connect on multiple domains.
Through a separate installer, the Sonic Container Launcher provides all the local
resources on distributed systems that enable them to setup and launch containers. The
Container Launcher also can setup a management container configuration during
installation, and then launch the container to record its configuration in the domains
Directory Service. You can choose to add an activation daemon and a host manager,
andon Windows a Windows Service.
Important JMS Clients Java applications running on remote systems require a Java runtime
environment and Sonic client libraries. While JMS client was an installation type in Sonic
releases before 8.5, in practice, SonicMQ applications are typically packaged with their
supporting Sonic client libraries and, often, the appropriate JVM. Every installation type
created by the Sonic Installer includes the complete SonicMQ client libraries.

Installing a Domain Manager

When you choose to install a Sonic Domain on the Sonic Installers Choose Installation
Type panel on page 74, the next panel is the Progress Sonic License Keys panel.
License keys (control numbers) are your identification to Progress Sonic Technical
Support.
Important Required Keys You must have a SonicMQ key to proceed. A Sonic ESB key
extends the domain for ESB products. You can then also add a BPEL key.
Note Adding Keys To add keys not previously added, choose Add Features to an
existing installation location on the Installation Location panel (see page 72), and
then point to the location you want to update to add the additional features.
1. Enter the license keys provided to you for Progress Sonic 8.5 products.
Click Next.

The Configure Domain Manager panel opens.
2. You can choose to not configure the domain manager and Directory Service as a part
of the installation process.
This is useful when you are using the Sonic Deployment Manager and your model
defines the Domain Manager configuration. Also this is the technique that enables
upgrades from Version 7see Upgrading a Fault Tolerant Management
Framework on page 211 for more information.
Otherwise, leave the option unchecked. Enter the remaining properties on this panel.
3. Enter a Domain Name, or accept the default name, Domain1.
4. Enter a Management Container Name, or accept the default name, DomainManager.
5. Enter a Management Broker Name, or accept the default name, MgmtBroker.
6. Specify a Management Broker Port value (1024 > 65536), or accept the default port,
2506.
7. Security is not enabled by default on a SonicMQ management broker. You can choose
to enable security by checking this option. Note that the domain will be able to create
security on brokers you create later whether you choose this option now. Also, you
can later enable security on the management broker through a few initialization steps.
Choose whether to Enable Security on the management broker.

8. Click Next.
system, and then click on your preferred JVM.
acceptable JVM.
Important Your selection of an installed JVM applies to use by the runtime software.

As all the steps to this point have caused no changes on the target system, you are
provided a review point to review the selections and the data requirements before
starting the actual installation.


Installing Administration Tools

When you choose Sonic Administration Tools on the Sonic Installers Choose
Installation Type panel on page 74, the next panel is Progress Sonic License Keys.
Tools do not require any license keys.

Important It is a good practice to install all the tools. Connection from an Administration Tools
install to domains such as Sonic Workbench will not access products for which tools
are not installed locally.
SonicMQ tools and the Sonic Deployment Manager (with its sample models) are
always installed with Sonic Administration Tools.
Note The Sonic Deployment Manager installed with Administration Tools is the complete
toolset; however, the underlying assets that enable creation of a directory service are
not available. As such, updateDomain performs as expected, but cleanDomain will
remove an existing domain manager on the local machine that is in the the SDMs
install location, as well remote containers in that domain. It will then fail to create a
new domain. You might want to remove the SDM cleanDomain command on
administration-only machines.
1. Choose Sonic ESB to add ESB tools.

2. If you choose ESB, you can also choose Sonic BPEL Server.

3. Click Next.
choose java.exe. When you click OK, the installer will verify the JVM.
4. Specify the preferred JVM option and location, and then click Next. The Pre-
Installation Summary panel opens
5. Click Previous to make changes, or click Install to start installation. When the install
process finishes, the Install Complete panel opens.
Open progress_sonic welcome.htm at the installation root to connect to documentation
and other Progress Sonic resources.


The Sonic administration tools can connect to multiple 8.5 Domain Managers
concurrently, displaying each domain in a separate workspace. Administration Tool
installs the graphical Sonic Management Console, which includes the JMS test client, and
the JMS administered object tool. Administrative tools are a client. They do not need a
local broker or a container. They do install the JMS client libraries and require a JVM.
Note SSL for management communications You can set the management communications
for the Sonic Management Console to use SSL. See the SSL and HTTPS Tunneling
Protocols chapter of the Progress SonicMQ Deployment Guide for information about
setting up an SSL acceptor on the management broker, and adding -DSSL parameters to
the startup script for the Sonic Management Console, startmc. Then, when you start the
Sonic Management Console, specifying the port of the SSL acceptor will enable SSL.
After the Administration Tools are installed, start the Sonic Management Console.
To start the Sonic Management Console:

On Windows, choose:
Start > Programs > Progress > Sonic 8.5 > Sonic Management Console
On UNIX or Linux, open a console window to the MQ8.5 installation directory then
enter ../bin/startmc.sh
The Create Connection dialog box opens when the Sonic Management Console starts.
The values after a domain installation that accepted the defaults are:
Domain Name: Domain1.
Connection URL: tcp://DomainManager_hostname:2506.
If security is enabled, use the default user Administrator, password Administrator.
To connect to a domain from the Sonic Management Console:

1. Enter any text string as the Connection Name.
2. Revise the other connection parameters to define your management connection.
The Sonic Management Console connects to the domain.
Administrative Tasks After Installing Components

There are a few tasks that are best done as soon as possible after installing a domain and
components. With the administration toolset installed and connected to the domain, you
can perform these tasks.
Domain: Resetting the Administrator Password on page 96
Broker: Enabling Security on an Installed Messaging Broker on page 98
Broker: Disabling Security on an Installed Messaging Broker on page 98
Broker: Resetting Quality of Protection (QoP) Cipher Suites on page 99
Broker: Enabling Broker Security Without Enabling Quality of Protection on page 100

Important Actions Requiring Initialization of a Brokers Data Store Before management brokers
start accepting management communications and messaging brokers start accepting
message traffic, you should review whether your configurations to see if you need to
make any adjustments that require you to initialize a brokers data store.
Review and adjust the following parameters and consider the following actions on new
broker configurations:
Broker: Enabling Security on an Installed Messaging Broker on page 98
Broker: Resetting Quality of Protection (QoP) Cipher Suites on page 99
Broker: Enabling Broker Security Without Enabling Quality of Protection on
page 100
Changing the broker name
Decreasing the size of the recovery log (You can make it larger later, but you cannot
decrease it later without re-initializing the store.)
Modifying the type of data store parameters
These actions require initialization of the data store. Each of the following procedures
shows the remote techniques you can apply through the management console for
messaging brokers as well as the onsite technique using dbtool and an edited db.ini file.
For some actions, such as the changing the broker name, and changing the security
option, you might consider uninstalling the configuration and then installing again with
your preferred name and security option.
Note The following procedures are applicable to management brokers as well but you will
need to use direct connection to the directory service and initialize the data store with
dbtool. See also Domain: Resetting the Administrator Password on page 96.

Domain: Resetting the Administrator Password

After you install a Domain Manager with security enabled, every containers connection
information must specify valid administrative credentials. The best way to expedite use
of your preferred user name and secret password is to change the password of the user
Administrator.
You could also create a new user assigned to the Administrator group (but you cannot
delete the user Administrator.) Use the modified administrator credentials on new broker
installations and be sure to update the container.ini in the management brokers working
directory with the new credentials (otherwise INAUTHENTIC_CLIENT errors occur.)
The following procedures describe resetting the password for the Administrator user
record, as well as creating a new administrative user, and then updating every containers
connection password, and every administrative tool connection.
To reset the password for the default user, Administrator:

1. Start the Sonic Management Console and connect to the domain.
2. On the Configure tab, expand the Security folder.
3. Expand Default Authentication, and then select Users.
4. Right click on the Administrator user, and choose Properties.
5. In the user properties dialog box, select the General tab, and click Set Password.
6. In the Set Password dialog box, enter your preferred password for the Administrator
user, and then click OK in both dialog boxes.
To create a new administrative user:

1. Continuing from above, right-click Users, and then select New User.
2. Enter a new user name, such as Container_Admin.
3. Click Set Password, and then enter and confirm the password for this user.
4. Select the Group Memberships tab, choose Add, then select Administrators.
Important This is a sensitive point in this task. Continue to setting the new password on container
configurations, and on management tool and administrative client connections. Until you
reconfigure the Domain Managers container, you cannot restart it.

To change the authentication credentials used by the Domain Managers container:

1. On the Configure tab in the Sonic Management Console connected to the running
Domain Manager, expand the Containers folder.
2. Select the DomainManager container, then right-click and choose Properties.
3. Enter the preferred administrative user or accept the current User Name
Administrator, and then click Set Password.
4. In the Set Password dialog box, enter the password you set for the administrative
Because the Domain Managers container is running, its revised connection information
updates the Domain Managers launch files in its working directory.
To change the authentication credentials used by administrative tools:

1. In the Sonic Management Console, create a new connection that uses the preferred
administrative user information, and then reconnect to the domain.
2. Close the session that used the previously acceptable credentials.
3. Similarly adjust the connection information used by administrative applications.
To change the authentication credentials of containers managed in the domain:

1. On the Configure tab in the Sonic Management Console, select a running container,
then right-click and choose Properties.
Important If a container is not running when you change the password in its configuration, you
will have to resetup the already-configured container through the steps in either
Configure a Container, then Use a Host Manager to Run Setup on page 125
orConfigure Container, Generate Setup File, then Run Setup on page 126.
2. Enter the preferred administrative user or accept the current User Name
Administrator, and then click Set Password.
3. In the Set Password dialog box, enter the password you set for the administrative
Because the selected container is running, its revised connection information is updated
in the launch files in its working directory.
See the chapter Configuring Security in the Progress SonicMQ Configuration and
Management Guide for information on creating users, changing user passwords, and
assigning users to groups.

Broker: Enabling Security on an Installed Messaging Broker

If you did not enable security on a messaging broker at the time of installation, and you
want to change that decision, you need change the configuration and then initialize the
brokers storage.
To configure an installed messaging broker to use security:
1. On the local system, stop the container.
2. In the Management Console, connect to the brokers domain.
3. On the Configure tab, right click on the broker, then choose Properties.
4. Select Security, choose an Authentication Domain and an Authorization Policy, then
click OK.
5. In the diretory sonic_install_dir\Containers\domainName.containerName,
delete the log and SonicMQStore folders.
When you restart the container that hosts the broker, the broker store is created with
security enabled.
Broker: Disabling Security on an Installed Messaging Broker

If you enabled security on a messaging broker at the time of installation, and you want to
change that decision, you need change the configuration and then initialize the brokers
storage.
To configure an installed messaging broker to no longer use security:
1. On the local system, stop the container that hosts the broker.
2. In the Sonic Management Console, connect to the brokers domain.
3. On the Configure tab, right click on the broker, and then choose Properties.
4. Clear the setting Security, then click OK.
5. In the diretory sonic_install_dir\Containers\domainName.containerName,
delete the log and SonicMQStore folders.
When you restart the container that hosts the broker, the broker store is created with
security disabled.

Broker: Resetting Quality of Protection (QoP) Cipher Suites

To define custom cipher suites for Quality of Protection on a broker, the brokers
persistent storage mechanism must be initialized after you set your preferred cipher suites.
To reset the QoP Cipher Suites for a broker:

4. Click Set QoP Cipher Suite. Follow the steps for installing and specifying your
preferred cipher suite and provider for QoP as described in the Progress SonicMQ
Deployment Guide.
5. Initialize the brokers store on the local system, as follows:
a. Copy the file db.ini from MQ8.5_install_root and paste it into the brokers
container folder, install_root\Containers\domainName.containerName
b. Edit the file to indicate the locations of the brokers store and the security settings:
Set the broker's name to the name of the broker you are working on:
BROKER_NAME=brokerName
Set the location for the db connection:
LOG_PATH=install_root\Containers\domainName.containerName\log
Specify security parameters (in agreement with the broker configuration
settings):
ENABLE_SECURITY=true
ENABLE_QOPSECURITY=true
Message store location:
MQSTORE_DB_CONNECT=
install_root\Containers\domainName.containerName\SonicMQStore
c. Save the modified db.ini in the

install_root\Containers\domainName.containerName folder.
d. In a console window opened at MQ8.5__install_dir, enter:
bin\dbtool /f ..\Containers\domainName.containerName\db.ini /r all
Under UNIX or Linux, the commandline is:
bin/dbtool -f ../Containers/domainName.containerName/db.ini -r all
When you restart the container that hosts the broker, your QoP provider and cipher suites
are enabled on the broker.

Broker: Enabling Broker Security Without Enabling Quality of Protection

The QoP aspect of security creates a performance overhead when it is enabled, even when
you select the QoP setting QOP_NONE. QoP can be turned off in a security-enabled broker
configuration, resulting in better performance. Turning off QoP overrides QoP settings on
individual and patterns of topic names or queue names. When security is not enabled, this
broker property is ignored regardless of its setting. When security is enabled, this
parameter defaults to true unless the advanced parameter explicitly sets it to false.
To enable broker security without enabling Quality of Protection

4. Choose the Advanced tab, and then click Edit.
Enter the Name BROKER_SECURITY_PARAMETERS.ENABLE_QOP_SECURITY.
Enter the Value false. Click OK.
5. Initialize the brokers store on the local system, as follows:
a. Copy the file db.ini from MQ8.5_install_root and paste it into the brokers
container folder, install_root\Containers\domainName.containerName
b. Edit the file to indicate the locations of the brokers store and the security settings:
Set the broker's name to the name of the broker you are working on:
BROKER_NAME=brokerName
Set the location for the db connection:
LOG_PATH=install_root\Containers\domainName.containerName\log
Specify security parameters (in agreement with the broker configuration):
ENABLE_QOPSECURITY=false
Message store location:
MQSTORE_DB_CONNECT=install_root\Containers\domainName.containerName\
SonicMQStore
c. Save the modified db.ini file.

d. In a console window opened at MQ8.5__install_dir, enter:
bin\dbtool /f .\Containers\domainName.containerName\db.ini /r all
Under UNIX or Linux, the commandline is:
bin/dbtool -f ./Containers/domainName.containerName/db.ini -r all


At the time of a Sonic 8.5 installation, each type of installation requires and installs a
fundamental set of software. Other features can be added by selection or license key at the
time of installation.
If, however, an installation is complete, and you later obtain licenses for additional Sonic
8.5 products, you can extend an existing installation to include that product.
The following table describes the required features and license keys at the time of
installation, and which features can be added later.
Table 3. Extensions to Installed Locations
SonicMQ
Install Type >> Workbench Development Domain Manager Admin Tools
Sonic Products
v
Sonic Installation
Workbench requires WB
license key.
SonicMQ Installation requires Installation requires Always installed.
MQ license key. MQ deployment
license key.
Sonic ESB Optional at Optional at
installation. Can be installation. Can be
added later. Requires added later
ESB deployment
license key.
Sonic BPEL Optional at Optional at
Server installation. Can be installation. Can be
added later. Requires added later
BPEL deployment
license key.
Sonic Database
Service
The decision to extend an installation is specified on the Installers Choose Installation

Location panel by choosing Add features to an existing install location, as shown:
See page 73 to learn how to start the installer, and advance to this panel.

When you click Next on the Choose Installation Location panel after deciding to add
features, and pointing to the existing the installation location, the installer first provides
the appropriate panel for the existing installation.
The installer steps proceed as follows:
1. The Additional Progress Sonic License Keys panel opens.
The keys that are already specified for the installation location are presented in light
gray and are not modifiable. You cannot remove features.
2. Enter the keys for additional features that you want to install at this time, and then
click Next.
The Sonic Domain Manager Registration panel opens.
You can choose to record the changes in the Directory Service through a management
connection to the management broker, or through a direct connection to the Directory
Service.
3. Choose:
Register the objects offline when you are on the same machine as the Directory
Service installation
Enable connection to the DM and update the DS when you want to use the
management broker to facilitate the update.

4. Click Next.
5. If you decided to register the objects offline, the Sonic Domain Manager - Connection
details panel opens as shown.
a. Enter the Domain Name. The default name in Domain1.

b. For the Directory Service Configuration, enter or locate the path to the Directory
Service bootfile, ds.xml, on the local system. The default on Windows is:
C:\Program Files\Progress\Sonic\Containers\Domain1.DomainManager\ds.xml.
c. Confirm that the Domain Manager is not running.

d. Click Next.

6. If you decided to connect to the management broker to update the domains Directory
Service, the Sonic Domain Manager - Connection details panel opens as shown.
a. Enter the Domain Name. The default name in Domain1.

b. For the Management Connection URL, enter the URL of a management broker in
that services the domain. The default protocol is tcp, and the default port is 2506.
c. Confirm that the Domain Manager is running.
d. Click Next.

When extending installations that are in the Directory Service, and security is enabled
on the management broker, the Administrative Credentials for Domain Access panel
opens.
The management broker must have valid administrative credentials before it will
allow the features to be added. The default administrative user is Administrator with
the password Administrator.
7. Enter a username and password that will allow administrative changes to the
Directory Service, and then click Next.
8. The Pre-Installation Summary panel opens
You can review the selections before starting the actual installation.
Note You might see a notice that a restart is required, perhaps because a file in the
installation directory was open when you added the new license keys.
10. Click Done.

The Progress Sonic Installer 8.5 closes.


Chapter 3 Using Progress Sonic Launcher Installer
The Progress Sonic Container Launcher establishes the resources on a distributed system
that support a Sonic management container. The Launcher folder is a consistent
foundation for Sonic component installations. There is a Launcher folder in Sonic
Workbench, SonicMQ Development, and Domain Manager. The Sonic Container
Launcher Installer provides the same launcher functionality in its installed location, and
lets you configure a management container with additional framework components (an
activation daemon and a host manager) and set up a Windows service.
Once the local launcher configures and sets up a management container, administrative
tools can define and maintain configurations such as brokers and ESB services in the
Directory Service store that, as components of the container, are provisioned dynamically
to the containers working directory.
The chapter contains the following sections:
Installing Sonic Container Launcher describes how get the installer to run on
various platforms.
Running the Container Launcher Installer describes the graphical installer wizard
that installs the launcher and can also setup container in a domain.
See the Chapter 4, Setting Up Containers. for detailed procedures on setting up
Activation Daemon, Host Manager components, and other management container
properties.

Chapter 3: Using Progress Sonic Launcher Installer
Installing Sonic Container Launcher

The Sonic Container Launcher Installer provides the Progress Sonic software required to
setup, launch, and upgrade Sonic management containers on systems where it is installed.
The installation procedure also lets you configure a new container. A Java Runtime
Environment is required by the installed software, and the preferred JRE for Windows can
be installed during the procedure.
The installer software supports two techniques for installation:
Graphical Installer wizard.
Unattended install with tailored data.
In each of these techniques you are prompted with information that you can change to
tailor the characteristics of the current installation.
Note Tailoring the Prompts in the Installer The prompts you get in the installer can be
tailored in advance so that your preferred prompts are displayed. Tailoring the prompts
for an installation enables running the installer with the set of prompts to complete the
process unattended. The following chapter, Chapter 5, Using Response Files with
Installers, describes how to capture and prepare response files.
The following section on the graphical installer wizard describes the sequence and data
entry that is entered through all the installer techniques.
Starting the Sonic Container Launcher Installer

The Sonic Container Launcher Installer does not require license keys (control codes).
However, if you intend to create a container configuration as part of installation, you must
know the connection URL of the Domain Manager (or a management routing node) that
will manage the container, andif the management broker is security enabledyou need
authentication credentials.
The startup instructions are described separately for Windows, UNIX, and Red Hat Linux.
To start the Installer wizard on Windows:

1. Mount the distribution media or unpack the installer package on the local system.
2. Open a console at the folder that has install_container_launcher.exe.
3. Run install_container_launcher.exe.
The installer starts. Follow the procedures for Running the Container Launcher Installer
on page 111.
Starting the Sonic Container Launcher Installer
To start the Installer wizard on UNIX:

Note These instructions are Solaris-specific. Some steps might vary slightly for other versions
of UNIX. See your operating system manual for information about installing software.
1. If you are installing from distribution media, put the media into your machines CD-
DVD drive, and change the directory to your CD/DVD directory.
2. The Sonic Container Launcher installer requires a JVM to run. Confirm that you have
a JVM installed and in your PATH. Refer to the Progress Sonic Web site for the
supported JVMs for your UNIX brand.
3. Open a console window and locate it in the directory that contains
install_container_launcher.bin.
4. Run install_container_launcher.bin.
on page 111.

To start the Installer wizard on Red Hat Linux:

1. Access and install the appropriate JVM for the installer. Refer to the Progress Sonic
Web site for the supported platforms for the Sonic installer and for the installation.
2. If you are installing from distribution media, put the disk into your machines
CD/DVD drive, and change the directory to that directory.
supports mixed case and longer file names when mounting the CD-DVD drive.
3. In a terminal window, change directories to the directory where

install_container_launcher.bin is located.
4. Confirm that the correct Java for the installer is the first Java in the path by entering
which java or java -version.
5. Launch the installer startup script: install_container_launcher.bin.

on page 111.

Running the Container Launcher Installer

You can install just the launcher or configure a management container at the same time.
Installing The Sonic Launcher on Distributed Hosts

Once you start the Sonic Container Launcher Installer, its Java process opens the
Progress Sonic Container Launcher 8.5 window.
1. Read the introductory comments to confirm that this is the product you want to install,
and then click Next.

The License Agreement panel opens.
2. After you read, understand and agree to the license terms, click that you accept the
agreement, and then click Next.

The Choose Install Folder panel opens.
Determines the installation root on a local drive for the Launcher software and any
associated container configurations. Define an explicit path to a folder that does not
contain any other files. The default folder on Windows is C:\Program Files\Progress
SonicLauncher, and the default folder on UNIX and Linux is
/opt/user/Progress/SonicLauncher.
3. Enter or browse to the preferred installation location, and then click Next.

acceptable JVM.
Important Your selection of an installed JVM applies to use by the runtime software. On
Windows, the installer always installs a JVM for use by the uninstaller, so there is no
saving in disk space by selecting the same JVM version in another location.

The Configure and Launch Container panel opens.
The installer assumes that you want to configure a container at this time.
5. Clear the option Yes, I want to configure a container if:
This Launcher installation is the basis of a Version 7 upgrade on this system.
See Sequence of 7.5 and 7.6 to 8.5 Component Upgrade Tasks on page 196 for
more information.
You intend to use utility applications on the local system to set up containers.
See Setting Up Containers on page 121 for more information.
6. Click Next. If you chose to not configure a container, skip to where The Pre-
Installation Summary panel opens. on page 120.

The Domain Manager Connection Properties panel opens.
These properties define administrative connection to the domain that will manage the
container. Enter the Domain Name and Connection URL (or a comma-delimited list
when management brokers are clustered) for connection. Provide authentication
credentials if the management node is security enabled.
Important Establish Good Credentials at Setup Time The credentials on remote containers
are easy to setup but are one of the few things that are difficult to revise remotely.
While setting up distributed containers with the user Administrator and the password
Administrator is appropriatein fact, it is recommended during exploration of
remote hosts and the Sonic Deployment Manager. But in preparation for deployment
rollout, maintain the target domain so that you can either use a secret password for
the default administrator, or defined administrator identities for containers such as
ctConnect_NA, ctConnect_EMEA, ctConnect_APAC, etc., each with a unique password.
7. Enter connection information, and then click Next

The Container Configuration Properties panel opens.
8. Enter the Container Paththe container path and container name within the
domains Directory Service. Path names always start with a forward slash (/). The
default is the Containers folder with the container taking the host name of the system
on which you are running the installer (shown here as thisRemoteHost). You can enter
a preferred path or container name but the container name must be unique in the
domain.
9. Select Create container configuration if container does not exist for creating the
container configuration or setting up a container configuration that already exists in
the Directory Service. For a container configuration that you are adding to the
Directory Service, you can have it create and host additional configuration objects:
a. Activation Daemon An activation daemon enables you to add containers to
remote system, and to start those containers remotely. To choose this feature,
choose Configure Activation Daemon, and then, in AD Path, specify the path and
activation daemon name you want. The name must be unique within a folder.
b. Host Manager A host manager provides a conduit to the remote installation
location to setup additional containers. It is a key point of binding for Sonic
Deployment Manager topologies. To choose this feature, choose Configure Host
Manager, and then, in HM Path, specify the path and host manager name you
want. The name does not have to be unique.

10. Whether you are creating the container configuration in the domain or not, you can
define a Windows Service for the container. If you want to create a Windows Service
for the container, choose Register Container as a Windows Service, and then, in
Service Name, enter a name for the Windows Service that is unique on the local
system.
11. You can encrypt the container.ini file that will be created in the containers
installation location by entering text in the INI Encryption Password entry area.
12. When you have specified the container configuration, click Next
You can choose all the options on this panel. The following example shows how a
designer wanted a hierarchy of regions and divisions with all the related objects in
specific directories:
The selected options created the following objects in the domain:
Note that folder hierarchies that do not exist are defined as the objects are created.

The Launch Container Process panel opens.
When you choose the option Yes, I want to launch the container process, the installer
will insert its configurations into the domains Directory Service, and then launches
the container.
When you do not choose this option, the working directory for this container is
created in the local Containers directory, but the configuration objects are not added
to the domain and the local caches are not updated. Running the launchcontainer
script in the containers local installation directory performs this task.
13. Choose whether to launch the defined container, and then click Next.
The process continues at the Pre-Installation Summary panel, as described on page 120.

The Pre-Installation Summary panel opens.
As all the steps to this point have caused no changes on the target system, you can
review the selections and the data requirements before starting the actual installation.
Important You might receive alerts during the processing if you were creating a container
configuration with incorrect connection or configuration information.
15. Note whether the installation was successful, and then click Done.
The Progress Sonic Container Launcher 8.5 Installer closes.
If there were installation or configuration errors, look at installation logs for details.
Open progress_sonic_welcome.htm at the installation root to connect to documentation
and other Progress Sonic resources.

Chapter 4 Setting Up Containers

About the Sonic Launcher and Setup
Properties in a Setup File
Running the Container Setup Utility
Running Setup Again for a Container
Windows Services in a Containers Working Directory
Shutting Down a Container
See the Progress SonicMQ Configuration and Management Guide for more information
about Windows Services, and management container properties.
See the Progress Sonic Deployment Manager Guide for information about how it uses
Host Manager components in deployments.

Chapter 4: Setting Up Containers

The Sonic Launcher lets remote systems easily and consistently configure, set up, and
launch Sonic management containers. The concepts are:
Configuring a container in the Directory Service
Setting up the container on the remote system that will host it.
Launching the container.
Domain Manager System Remote System
Domain Manager Installation Launcher Installation
A B'
Sonic Management Console
B
A'
C'
Figure 2. Container1 configured, set up, and launched on a remote system
Figure 2 shows the relevant files on the Domain Manager system and the remote system,
as well as the Configure and Manage views of a Sonic Management Console connected
to the Domain Manager.

The key concepts presented are:

The Domain1 folder (A) on the Domain Manager system is the store of the domains
Directory Service. The containers configuration (A) is added to the Directory
Service.
The remote system has been enabled to setup and launch containers by an installation
of the Sonic Container Launcher (B) and its utility that sets up containers (B) in
individual working directories in the Launchers installation location.
Each container has a launch script (C) to connect to the domain where its
configuration can be updated, the containers cache refreshed, and indicate its run
status in the Sonic Management Console (C).
The steps can be done in various sequences:
Setup, then launch. The configuration process is automatic.
Configure, then setup, then launch
The following sections describe the essential techniques and their flow.

Use Sonic Launcher to Setup, Launch, and Add Configuration

The Sonic Container Launcher always installs the Launcher and its utilities. In addition,
you can choose to create a container configuration. The container information will run the
setup utility with the parameters you enter, and lets you choose to also launch the
container. Launching the container will connect it to the domain toif the option to
CREATE_IF_DOES_NOT_EXIST is selectedadd the new container configuration into the
Directory Service, and then to note the host system.
Domain Manager System Distributed System
CREATE_IF_DOES_NOT_EXIST=true
3
1
Figure 3. Use (1) Sonic Launcher to (2) Setup, (3) Launch, and (4) Add Configuration
If you deselect any of those options when you run the Sonic Launcher Installer, you have
to setup containers on the remote system through other techniques. See Using Progress
Sonic Launcher Installer on page 107 for more information.

Configure a Container, then Use a Host Manager to Run Setup

When you create a container configuration through the Sonic Management Console, the
container is not manifested in a physical location until you set up the container. If you
have an installation of a container with a Host Manager already setup on the system where
you want to locate the new container, you can use a Host Manager to do the setup
remotely.

3
Figure 4. (1) Configure Container, (2) Use a Host Manager to Run Setup, (3) Container Folder
The Host Manager as a component of a running container enables you to later set up
another configured container on that host, by right-clicking on the HOST MANAGER runtime
component, choosing Setup Container, and then locating the container configuration.

Configure Container, Generate Setup File, then Run Setup

If you have a defined container configuration that has not been setup on its designated
host, you can generate the parameters into a setup file that can then be transported to the
remote system that will host it. Right-click on the container name in the Configure view,
and then choose Generate Setup File, as shown:

3
1
2
Figure 5. (1) Configure Container, (2) Generate Setup File, (3) Run Setup
In a Sonic Launcher installation on the remote system, use the setup utility with the
.setup file to set up the container.

Create Setup File, Run Setup, then Launch to Add Configuration

Setup files are text files. There are cases where you might want to simply create the file
in your preferred editor, and then run the setup utility to create the container setup folder.
When you launch the container in its working directory, it will use the specified
management connection to connect to the Directory Service, andif the parameter to
CREATE_IF_DOES_NOT_EXIST=true is in the setup filewill insert the new container
configuration into the Directory Service.
Domain Manager System Distributed System

3
Text Editor
Figure 6. (1) Create Setup File, (2) Run Setup, (3) Container Folder, (4) Launch Container


A setup properties file is a text file that you either generate from a container configuration
or create in a text editor as name=value pairs.
Table 4. Required Container Setup Properties
Category Property Name Description Default Value

Domain Manager DOMAIN_NAME The domain that will manage the Domain1
Connection configuration
Properties
ConnectionURLs List of connection URLs for tcp://localhost:2506
brokers in the management node.
CONTAINER_PATH Directory Service folder path /Containers/hostname
(starting with /) and the name of the
container.
Container CREATE_IF_DOES_NOT_EXIST When true, creates the container false
Properties configuration in the domains
Directory Service.
LOG_FILE Defaults to a relative location in the ./{DOMAIN_NAME}.
{CONTAINER_NAME}.log
containers working directory.
Required when it is located
elsewhere.
Table 5. Optional and Special Use Container Setup Properties

Additional ACTIVATION_DAEMON_PATH Adding the property with a Directory
Components in Service folder path creates the
the Container component.
Name must be unique in domain.
HOST_MANAGER_PATH Adding the property with a Directory
Service folder path creates the
component. Can be a common
component such as
/Framework Components/HOST MANAGER

Table 5. Optional and Special Use Container Setup Properties (continued)

Windows Service WINDOWS_SERVICE_NAME Adding the property with a service Sonic CONTAINER_NAME
Setup name creates the service. Service
WS_TIMEOUT Elapsed time (in seconds) to wait for 360

the Windows Service to start.
WS_AUTOSTART_OPTION Set to -a to set the Windows Service -a
to AutoStart
Optional CONNECT_TIMEOUT Elapsed time (in seconds) to wait for 10
Container connection to the management broker.
Properties
REQUEST_TIMEOUT Maximum time (in seconds) for 30
roundtrip management requests.
LoadBalancing Selects load balancing for container true
connections to the management node.
SOCKET_CONNECT_TIMEOUT Elapsed time (in seconds) to wait for 0
individual socket connect attempts.
Special Use: MANAGEMENT_NODE Name of the management node when
Management using management routing nodes.
Routing over
DRA CENTRAL_CONNECTION Enables the parameters and false
functionality when the container is
hosting a broker that is doing the
routing for a management routing
node.
Java System SystemProperty When the container launches, the one
Properties .property_name or more specified system properties
will be passed to the JVM.
For example:
SystemProperty.
java.protocol.handler.pkgs
=progress.message.net

Note Containers That Connect Over Management Routing Nodes When you are defining
a container that intends to use a management routing nodes.
On the broker that will route to the management node, the required properties are:
CENTRAL_CONNECTION Set to true
On the containers that will connect to the local broker connected to the management node
to handle management routing, the required properties are:
DOMAIN_NAME The domain that will manage the configuration.
ConnectionURLs List of acceptors on brokers in the management routing node.
CONTAINER_PATH Folder path and name of the container plus @ followed by the
routing node name.
MANAGEMENT_NODE Specifies the routing definition for the management node on the
management routing brokers.
To create a setup file for a new container configuration

1. In your preferred text editor, enter name=value pairs for at least the required setup
properties. For example, for container ct001 that does not exist in the domain:
DOMAIN_NAME=Domain1
ConnectionURLs=tcp://myDMhost:2506
CONTAINER_PATH=/Containers/ct001
LOG_FILE=./Domain1.ct001.log
2. Add other properties as appropriate.

3. Save the file in the form container_name.setup. For this example, ct001.setup.
4. Position the file so that it can be read on its intended host system where a Sonic
Launcher installation is available.
To edit a generated setup file for a container

1. In your preferred text editor, open the generated setup file.
2. Do not change the specified properties as the file was generated from an existing
configuration.
3. Confirm that the property CREATE_IF_DOES_NOT_EXIST is either not in the file, orif it
is in the fileit is set to false.
4. Add additional properties as appropriate.

5. Save the file without changing its name.

6. Position the file so that it can be read on its intended host system where a Sonic
Launcher installation is available.

The container setup utility creates the working directory for the container. Parameters of
the setup command locate the setup file, provide the credentials for the administrator to
connect to the domain, and optionally encrypt the container.ini file in the containers
working directory. The parameters are:
propertiesFile The path for the text file that provides the container setup
properties in the domain that will manage the container. Required. If any part of the
path contains a space, delimit the name in quotes; e.g., /c C:\New Container.setup
user The username to be used to establish a direct connection to the management
broker(s). The user must have administrative permissions for this task. Required if the
management broker is security enabled. Default value is Administrator.
userPassword The connection user's password to authenticate the users
credentials in the management brokers authentication domain. Required if the
management broker is security enabled. Default value is Administrator.
encryptionPwd An encryption key is derived from this password and used to
encrypt the container.ini file generated by the setup to the containers working
directory. If you choose encryption, be sure to note the container name and password
in a secured location. Encryption is not required.
To setup a container on Windows:

1. Open a console window in an installations Launcher directory.
2. Change to the appropriate versions directory, such as, 8.5.0.392
3. Change to the container_setup directory
4. Enter setup.bat with the appropriate parameters in the form:
setup.bat /c propertiesFile /u user /p userPassword /e encryptionPwd
The container is setup and, if the option to create a Windows Service was selected, the
Windows Service is setup, named Sonic container_name Service.
To setup a container on UNIX/Linux:

1. Open a console window in an installations Launcher directory.
2. Change to the appropriate versions directory, such as, 8.5.0.392

3. Change to the container_setup directory
4. Enter setup.sh with the appropriate parameters in the form:
setup.sh -c propertiesFile -u user -p userPassword -e encryptionPwd
The container is setup.
Running Setup Again for a Container

Once you have setup and launched a container, the domain will maintain the Launcher
versioning, and update the caches and container.ini file automatically. If you performed
significant changes that would impact a containers container.ini (such as the
authentication credentials) when the container was not running, run setup again on the
same host through a host manager or a setup file generated since the changes occurred.
Note Do not edit a Containers container.ini File A container.ini file is not intended for
edits. The naming conventions and sequence of parameters are not intended for user
interface. There are very few circumstances where a minor edit might be required; in such
cases, documentation will guide you to the specific changes needed.
Windows Services in a Containers Working Directory

Every container working directory includes a winservice script to assist in managing the
container as a Windows Services. The preset name of the Windows service is Sonic
container_name Service.
To use a containers winservice script:

1. Open a console window in a containers working directory.
2. Enter winservice and one of the following parameters:
/install
/start
/wait_for_stop
/stop
/remove
The requested Windows Service action occurs.


Every container working directory includes a shutdowncontainer script. The script
performs an orderly shutdown of that container and its hosted components


Chapter 5 Using Response Files with Installers

Overview describes the general procedure for using response files.
Sonic Installer Parameters and Procedures
Sonic Updater Parameters and Procedures
Sonic Container Launcher Parameters and Procedures

Chapter 5: Using Response Files with Installers
Overview
A text file can provide the preferred responses for each the parameter that defines the
tailoring of an installation. While they provide convenience and consistency in graphical
installations, a response file is the only means of providing parameter values to an
unattended installation.
While you can author a response file as a text file, it is convenient to record the responses
made during a prototype installation, or to just dump all the response parameters. Then,
tailoring the response file lets you re-use the response file, perhaps with command line
parameters to provide installation-specific variables.
The procedure for using response files to tailor the Sonic installers prompts in silent
installations involves three steps:
1. Capture a response file from the installer you want to use by performing one of the
following:
Sonic installer:
Windows install.exe -r file
UNIX/Linux ./install.bin -r file
Sonic container launcher installer:
Windows install_container_launcher.exe -r file
UNIX/Linux ./install_container_launcher.bin -r file
2. Tailor the response file as appropriate for the next installation you want to perform
and save the tailored file.
3. Use tailored responses to run setup for a silent install using the edited response file:
Sonic installer:
Windows install.exe -i silent -f file
UNIX/Linux ./install.bin -i silent -f file
Sonic container launcher installer:
Windows install_container_launcher.exe -i silent -f file
UNIX/Linux ./install_container_launcher.bin -i silent -f file
The following sections detail these steps for each of the installers.
Important Use response files only for silent installations Using a response file without the
-i silent parameter will attempt to use the response file in the GUI interface. As that is
not a supported usage of a response file, the values prompted by the GUI installer might
be different from the ones in the response file.


The Sonic Installer provides five types of Sonic installations, all of which can use
response files and run silent installations.
Capturing Response Files

You can capture the responses you use during an installation for tailoring and reuse.
To record your responses when you run the Sonic Installer:

1. In a console window opened to the folder where the setup file is located, enter:
install.exe -r file
where file is the name of file on an explicit path where you have write access. For
example: D:\>install.exe -r C:\Installer8.5Windows.rsp
The installer opens the graphical installer wizard.
2. Proceed through the panels to set the values for the installation, then complete the
installation. The installer must complete the installation successfully in order for the
recording to be saved.
Running Silent Installs

A response file provides your preferred prompts to the silent installer.
To use your response file to run the Sonic Installer:

1. Place your edited response file in the installer location.
2. In a console window opened to the folder of the installers setup file is located, enter:
install.exe -i silent -f file
where file is the name of the response file. For example:
D:\>install.exe -i silent -f C:\Installer8.5Windows.rsp
3. When the install completes, the install directory has been created.
Tips Be sure that the target location is empty. If you are rerunning an install, do an
uninstall, and clear any remaining files before starting the new install.
On Windows, if your silent install does not complete, go to C:\Documents and
settings\user\Local Settings\Temp where text files at that rootsuch as
Sonic_SilentInstallFailed.txt or Sonic 8.5 Admin
Tools_SilentInstallFailed.txt.will detail the reason

Contents of a Sonic Installer Response File

A Sonic installer response file is a series name=value parameter statements. For a silent
install, you must have all the parameters that are used by the installation you intend to
perform. The types of installations performed by the Sonic Installer are Workbench, MQ
Development, deployment Domain, and Administrative Tools. While there are common
parameters, there are distinguishing patterns, described later in this chapter.
A response file is a series name=value parameter statements, as shown in the following
example where a Domain Manager was installed on a Windows system with licenses for
SonicMQ, and Sonic ESB:
Code Sample 1. Example of a Sonic Installer response file for a Domain Manager
# {timestamp}
# Replay feature output
# ---------------------
# This file was built by the Replay feature of InstallAnywhere.
# It contains variables that were set by Panels, Consoles or Custom Code.
#Accept License Agreement

#------------------------
ACCEPT_LICENSE_AGREEMENT=true
#Choose Installation Location

#----------------------------
INSTALL:_TYPE=new
INSTALL_LOCATION=C:\\Program Files\\Progress\\Sonic
#Chosen Install Set

#------------------
USER_CHOSEN_INSTALL_SET=domainmanager
#Progress Sonic License Keys - MQ

#---------------------------
MQ_KEY=*********
#Progress Sonic License Keys - ESB

#---------------------------
ESB_KEY=*********
#Configure Domain Manager

#------------------------
CONFIGURE_DOMAIN=true
DOMAIN_NAME=Domain1
CONTAINER_NAME=DomainManager
BROKER_NAME=MgmtBroker
MGMT_BROKER_PORT=2506
ENABLE_SECURITY=false
#Chosen JVM Home directory

#-------------------------
CHOSEN_JVM_HOME=C:\\Program Files\\Progress\\Sonic\\jre

Response File Parameters for Types of Sonic Installations

This section of this chapter excerpts the patterns of response fields that relate to specific
installation scenarios in the Sonic Installer so that you can copy the parameters, follow
instructions on how to edit them, and use them to perform a tailored install.
The Sonic Installer types in this chapter are:
Using a Response File for a Sonic Workbench Installation on page 139
Using a Response File for a SonicMQ Developer Installation on page 142
Using a Response File for a Sonic Domain Manager Installation on page 144
Using a Response File for a Sonic Admin Tools Installation on page 147
Using a Response File for a Sonic Workbench Installation

The parameters in a Workbench response file are a record of the values entered in the GUI
panels. The following table describes each parameter and its default value.
The parameter DEV_OPTION is derived from the DEV_KEY so including it in a response file is
a comment that provides insight into the development key.
Table 6. Response file parameters used in the Sonic Installer for Sonic Workbench
Installer Group
(GUI Panel) Parameter Details Default Value
License ACCEPT_LICENSE_AGREEMENT Required, set to true
Agreement true
Installation INSTALL_TYPE new or new

Location existing.
INSTALL_LOCATION Required. Windows:

Explicit path C:\\Program Files\\Progress\\Sonic
UNIX/Linux: /usr/opt/Progress/Sonic
Install Set USER_CHOSEN_INSTALL_SET Required. development
Progress Sonic DEV_KEY Required. A Sonic Workbench 8.5 key includes

License Keys development/evaluation licenses for
SonicMQ, Sonic ESB, and Sonic BPEL
Server
DEV_OPTION Information esb
only.

Table 6. Response file parameters used in the Sonic Installer for Sonic Workbench (continued)
Installer Group
Sonic CONFIGURE_DOMAIN true or false true
Development
DOMAIN_NAME Required. Domain1
Configuration
CONTAINER_NAME Required. DomainManager
BROKER_NAME Required. MgmtBroker
MGMT_BROKER_PORT Required. 2506
ENABLE_SECURITY true or false true
Directory Service SECURITY_USER_NAME Required. Administrator

Authentication
SECURITY_PASSWORD Required. Administrator
Choose Eclipse CHOSEN_ECLIPSE_HOME Windows:install_location\\Workbench8.5\\eclipse

UNIX/Linux:install_location/Workbench8.5/eclipse
Choose Java CHOSEN_JVM_HOME Windows:install_location\\jre
Virtual Machine UNIX/Linux:install_location/jre
Shortcuts DESKTOP_SHORTCUT true or false false
(Workbench on
QUICK_LAUNCH_SHORTCUT true or false false
Windows only)

To edit a response file to install Sonic Workbench:

1. Use a captured response file from a Sonic Workbench install, or copy Code Sample 2.
Code Sample 2. Response File parameters for Installing Sonic Workbench on Windows
INSTALL_TYPE=new
USER_CHOSEN_INSTALL_SET=development
DEV_KEY=**********
# DEV_OPTION=esb
DOMAIN_NAME=Domain1
CONTAINER_NAME=DomainM<anager
SECURITY_USER_NAME=Administrator
SECURITY_PASSWORD=Administrator
CHOSEN_ECLIPSE_HOME=C:\\Program Files\\Progress\\Sonic\\Workbench8.5\\eclipse
DESKTOP_SHORTCUT=false
QUICK_LAUNCH_SHORTCUT=false
2. Enter your Sonic Workbench 8.5 development or evaluation license key as the
DEV_KEY value.
3. As appropriate, adjust the locations.

4. Save the file as a text file.
For example, c:\WB8.5_Windows.rsp or /opt/user/WB8.5_Linux.rsp.
5. On the target machine, enter the following command at the root of the Sonic Installer:
Windows: install.exe -i silent -f c:\WB8.5_Windows.rsp
UNIX/Linux: ./install.bin -i silent -f /opt/user/WB8.5_Linux.rsp

Using a Response File for a SonicMQ Developer Installation

The parameters in a SonicMQ Developer response file are a record of the values entered
in the GUI panels. The following table describes each parameter and its default value.
The parameter DEV_OPTION is derived from the DEV_KEY so including it in a response file is
a comment that provides insight into the development key.
Table 7. Response file parameters used in the Sonic Installer for SonicMQ Developer
Installer Group
Agreement true

Location existing.

UNIX/Linux:
/usr/opt/Progress/Sonic
Install Set USER_CHOSEN_INSTALL_SET Required. development
Progress Sonic DEV_KEY Requires a -

License Keys SonicMQ 8.5
key
DEV_OPTION Information mq
only.
Configure CONFIGURE_DOMAIN true or false true
Domain Manager
DOMAIN_NAME Domain1
CONTAINER_NAME DomainManager
BROKER_NAME MgmtBroker
MGMT_BROKER_PORT 2506
ENABLE_SECURITY true or false false

Table 7. Response file parameters used in the Sonic Installer for SonicMQ Developer
Installer Group
Directory Service SECURITY_USER_NAME Required when Administrator
Authentication security is
SECURITY_PASSWORD Administrator
enabled
Choose Java CHOSEN_JVM_HOME Windows:install_location\\jre
Virtual Machine
To edit a response file to install SonicMQ Developer Install:

1. Use a captured response file from a SonicMQ Developer install, or copy Code
Sample 3.
Code Sample 3. Response File parameters for Installing SonicMQ Developer
INSTALL_TYPE=new
USER_CHOSEN_INSTALL_SET=development
DEV_KEY=***************
# DEV_OPTION=mq
DOMAIN_NAME=Domain1
ENABLE_SECURITY=false
2. Enter your SonicMQ 8.5 development or evaluation license key as the DEV_KEY value.
For example, c:\MQ8.5_Windows.rsp or /opt/user/MQ8.5_Linux.rsp.
Windows: install.exe -i silent -f c:\MQ8.5_Windows.rsp
UNIX/Linux: ./install.bin -i silent -f /opt/user/MQ8.5_Linux.rsp

Using a Response File for a Sonic Domain Manager Installation

The parameters in a Domain Manager response file are a record of the values entered in
the GUI panels. The following table describes each parameter and its default value..
Table 8. Response file parameters used in the Sonic Installer for Domain Manager
Installer Group
Agreement true

Location existing.

UNIX/Linux:
Install Set USER_CHOSEN_INSTALL_SET Required. domainmanager
Progress Sonic MQ_KEY Required. -

License Keys
ESB_KEY Optional. -
Required to
install ESB.
Depends on a
valid MQ_KEY
value
BPEL_KEY Optional. -
Required to
install BPEL.
Depends on a
valid ESB_KEY
value.

Table 8. Response file parameters used in the Sonic Installer for Domain Manager (continued)
Installer Group
Configure CONFIGURE_DOMAIN true or false true
Domain Manager
DOMAIN_NAME Domain1
CONTAINER_NAME DomainManager
BROKER_NAME MgmtBroker
MGMT_BROKER_PORT 2506
ENABLE_SECURITY true or false false
Directory Service SECURITY_USER_NAME Required when Administrator

Authentication security is
SECURITY_PASSWORD Administrator
enabled
Choose Java CHOSEN_JVM_HOME install_location/jre (Windows)
Virtual Machine
Adding products REGISTER_ONLINE true or false false

to a Domain
DS_DOMAIN -
Manager
MANAGEMENT_CONNECTION_URL -
SECURITY_USER_NAME Required when -

management
SECURITY_USER_PASSWORD -
node is security
enabled.

To edit a response file to install Sonic Domain Manager:

1. Use a captured response file from a Domain Manager install, or copy Code Sample 4.
Code Sample 4. Response File parameters for Installing a Domain Manager
INSTALL_TYPE=new
MQ_KEY=***********
ESB_KEY=
BPEL_KEY=
USER_CHOSEN_INSTALL_SET=domainmanager
DOMAIN_NAME=Domain1
2. Only products for which you have licenses will be installed. Enter license keys:
a. Enter an MQ_KEY.
b. An ESB_KEY is required for Sonic ESB and to support a BPEL_KEY.
c. Delete any key name lines for which you have no key value.
3. As appropriate, adjust the location.
For example, c:\DM8.5_Windows.rsp or /opt/user/DM8.5_Linux.rsp.
Windows: install.exe -i silent -f c:\DMB8.5_Windows.rsp
UNIX/Linux: . ./install.bin -i silent -f /opt/user/DM8.5_Linux.rsp

Using a Response File for a Sonic Admin Tools Installation

The parameters in an Administration Tools response file are a record of the values entered
in the GUI panels. The following table describes each parameter and its default value.
Table 9. Response file parameters used in the Sonic Installer for Administration Tools
Installer Group
Agreement true

Location existing.

UNIX/Linux:
Install Set USER_CHOSEN_INSTALL_SET Required. admintools
Progress Sonic INSTALL_ESB_TOOLS 1 (true) 0 (false)

License Keys
INSTALL_BPEL_TOOLS 0 (false)
Choose Java CHOSEN_JVM_HOME install_location/MQ8.5/jre (Windows)

Virtual Machine
To edit a response file to install Sonic Administration Tools:

1. Use a captured response file from an Admin Tools install, or copy Code Sample 5.
Code Sample 5. Response File parameters for Installing Admin Tools
INSTALL_TYPE=new
USER_CHOSEN_INSTALL_SET=admintools
INSTALL_ESB_TOOLS=1
INSTALL_BPEL_TOOLS=1
CHOSEN_JVM_HOME=c:\\Program Files\\Progress\\Sonic\\jre
2. Choose the tools you want to install (no license required). The ESB_TOOLS value must
be 1 (true) to administrate Sonic ESB and to support BPEL_TOOLS when they are set to
1 (true.) Any tools that you do not want to install must be set to 0 (false.)
3. As appropriate, adjust the location and JVM home.


For example, c:\Admin8.5_Windows.rsp or /opt/user/Admin8.5_Linux.rsp.
Windows: install.exe -i silent -f c:\Admin8.5_Windows.rsp
UNIX/Linux: ./install.bin -i silent -f /opt/user/Admin8.5_Linux.rsp


When a Sonic 8.5 Service Pack is announced, you can download it, and then capture the
parameters used in a Sonic Updater session to edit them for reuse. You could simply
create a response file in your preferred text editor using the values and examples provided
in this section.
Important You can reuse the same file for updates on multiple systems provided that the
platform/path information is appropriate

You can capture the responses you use during an update for tailoring and reuse.
To record your responses when you run the Sonic Updater:

install.exe -r file
where file is the name of file on an explicit path where you have write access.
For example, when SP 1 is available:
install.exe -r c:\8.5_updaterWindows.rsp

2. Proceed through the panels to set the values for the update, then complete the update.
The updater must complete the update successfully in order for the recording to be
saved.

Contents of a Response File

A response file is a series name=value parameter statements.
Code Sample 6. Example of a Sonic Updater response file
# {timestamp}
# Replay feature output
# ---------------------

#------------------------
#Sonic Install Location

#-----------------------
INSTALL_LOCATION=C:\\Program Files\\Progress\\Sonic8.5
#Sonic Directory Service Update

#------------------------------#---------------------------------
UPDATE_DS=true
DOMAIN_NAME=Domain1
MANAGEMENT_CONNECTION_URL=tcp://localhost:2506
The parameters in the response file are displayed in the GUI panels. The following table describes
each parameter and its default value.
Table 10. Response File parameters for the Sonic Updater
Installer Group
License ACCEPT_LICENSE_AGREEMENT Required, set to true true
Agreement
Choose Install INSTALL_LOCATION Explicit path for the update. Windows:

Folder C:\\Program
Files\\Progress\\Sonic
UNIX/Linux:
Update UPDATE_DS Choose to not update the false

Directory Directory Service, usually
Service because the Sonic Deploymemt
Manager will update the DS later.
Values are false or true.

Table 10. Response File parameters for the Sonic Updater (continued)
Installer Group
Domain DOMAIN_NAME Name of the domain that will be Domain1
Manager updated.
Connection
Properties MANAGEMENT_CONNECTION_URL When the Domain Manager is tcp://localhost:2506
running, the URL for connection
to the domains management
broker.
When the Domain Manager is not
running, the explicit path to the
DS boot file, ds.xml.
Editing a Response File for an Update

To edit a response file to update a Sonic 8.5 installation:
1. Copy Code Sample 7.
Code Sample 7. Response File for Updating a Sonic Installation where DM is online
#------------------------
#Sonic Install Location
#-----------------------
#Sonic Directory Service Update
#------------------------------#---------------------------------
UPDATE_DS=true
DOMAIN_NAME=Domain1
MANAGEMENT_CONNECTION_URL=tcp://localhost:2506

For example, c:\851_updater_Windows.rsp or /opt/user/851_updater_Linux.rsp.
Windows: install.exe -i silent -f c:\851_updater_Windows.rsp
UNIX/Linux: ./install.bin -i silent -f /opt/user/851_updater_Linux.rsp


You can capture the parameters used in a Sonic Container Launcher installation session
to edit them for reuse. You could simply create a response file in your preferred text editor
using the values and examples provided in this section.
Important You can reuse the same file for installations on multiple systems provided that the
platform/path information is appropriate HOWEVER every container in a domain must
have a unique name. Naming a container after a systems hostname shouldin most
enterprise structuresdefine a unique name.

You can capture the responses you use during an installation for tailoring and reuse.
To record your responses when you run the Sonic Container Launcher Installer:
install_container_launcher.exe -r file
where file is the name of file on an explicit path where you have write access. For
example:
install_container_launcher.exe -r c:\LauncherWindows.rsp

2. Proceed through the panels to set the values for the installation, then complete the
installation. The installer must complete the launcher installation successfully in
order for the recording to be saved.

Contents of a Response File

The parameters in the response file are displayed in the GUI panels. The following table describes
each parameter and its default value.
Table 11. Response File parameters for the Sonic Container Launcher
Installer Group
License ACCEPT_LICENSE_AGREEMENT Required, set to true true
Agreement
Choose Install INSTALL_LOCATION Explicit path for the Windows:

Folder installation C:\\Program
Files\\Progress\\SonicLauncher
UNIX/Linux:
/usr/opt/Progress/SonicLaunche
r
Java Virtual CHOSEN_JVM_HOME Path to the JVM directory C:\\Program

Machine Files\\Progress\\SonicLauncher
chosen by user.
\\jre
Configure CREATE_CONTAINER_CONFIG Elects to create a true

Container container configuration
during this installation
procedure. Value is true
or false

Table 11. Response File parameters for the Sonic Container Launcher (continued)
Installer Group
Domain DOMAIN_NAME Name of the domain that Domain1
Manager will manage the
Connection configuration.
Properties
CONNECTION_URLS The URL for connection tcp://localhost:2506
to the configurations
domain.
SECURITY_USER_NAME The administrative user Administrator
for connection to the
configurations domain.
SECURITY_PASSWORD The administrative users 75752F2B3E1A1011311A7B2B387D1F
293C1A1F19
password for
authentication in the ("Administrator" encrypted)
configurations domain.

Installer Group
Container CONTAINER_NAME Name of the container to hostname
Configuration configure
Properties
CONTAINER_PATH Path for the configured /Containers/hostname
container in the Directory
Service.
CONFIGURE_CONTAINER Create the container false
configuration in the
Directory Service? Value
is true or false.
ACTIVATION_DAEMON_PATH Path for the activation /Framework Components
/AD_hostname
daemon in the domains
Directory Service.
ACTIVATION_DAEMON_ENABLED Create the specified false
activation daemon object
and host it in this
container?
Value is true or false.
HOST_MANAGER_PATH Path of host manager in /Framework Components
/HOST MANAGER
the domains Directory
Service.
HOST_MANAGER_ENABLED Create the specified host false
manager object? Value is
true or false.
WINDOWS_SERVICE_NAME Name for the Windows Sonic{hostname}Service

Service
INI_ENCRYPT_PASSWORD Password that encrypts -
this containers bootfile

Installer Group
WINDOWS_SERVICE_ENABLED Create the specified false
Windows Service? Value
is true or false.
Launch LAUNCH_CONTAINER Elects to start the defined true
Container configuration after
Process installation completes
successfully, andif
choseninsert its
configuration into the
specified domains
Directory Service. Value
is true or false.

Editing a Response File for a Container Launcher Install

To edit a response file to install a Sonic Container Launcher and a fully-featured
container:
1. Copy Code Sample 8.
Code Sample 8. Response File for Installing a Sonic Launcher and a Container
INSTALL_LOCATION=C:\\Program Files\\Progress\\SonicLauncher
CHOSEN_JVM_HOME=C:\\Program Files\\Progress\\SonicLauncher\jre
CREATE_CONTAINER_CONFIG=true
DOMAIN_NAME=Domain1
CONNECTION_URLS=tcp://localhost:2506
CONTAINER_NAME=hostname
CONTAINER_PATH=/Containers/hostname
CONFIGURE_CONTAINER=true
ACTIVATION_DAEMON_PATH=/Framework Components/AD_hostname
ACTIVATION_DAEMON_ENABLED=true
HOST_MANAGER_PATH=/Framework Components/HOST MANAGER
HOST_MANAGER_ENABLED=true
WINDOWS_SERVICE_NAME=Sonic hostname Service
WINDOWS_SERVICE_ENABLED=true
LAUNCH_CONTAINER=true
2. Replace hostname with a unique name for the container in the domain such as the
actual host name or a name pattern such ct001.
For example, c:\Launcher_ct001_Windows.rsp or
/opt/user/Launcher_ct001_Linux.rsp.
Windows:
install_container_launcher.exe -i silent
-f c:\Launcher_ct001_Windows.rsp
UNIX/Linux:
./install_container_launcher.bin -i silent
-f /opt/user/Launcher_ct001_Linux.rsp

Creating Scripted Launcher Installations for Host Managers

Centralized installation provides many strategies that remove the burden of distributed
installation and upgrade of widely dispersed machines:
The Domain Manager is the central repository of licensed components, provisioning
remote machines with required libraries without any intervention at remote sites.
The Sonic Deployment Manager acts on the Domain Manager system to map
configurations in its models to machines in the distributed topology through Host
Manager objects running on the remote machines.
The Sonic Launcher provides easy installation of Sonic container resources and can
setup a container that connects to its assigned domain.
That last step can still be error prone. Until the container is given a name that will be
unique in the domain and the configuration is set up and running, remote administrators
cannot perform any maintenance functions.
The following techniques describe how, on Windows systems, a simple script and a
properties file installed on a machine can set up Sonic resources, configure a container
that uses the hosts name, start it, and connect it to its assigned domain, silently, with no
user input whatsoever.
Consider the following scenario for this example:
1. One or more Domain Managers are installed at various locations in the enterprise.
2. In some domains, the containers are grouped on management lines, perhaps as
regions.
3. The network identity of machines that will cooperate in a domain are defined with
unique names by the systems and network teams.
4. The optimal setup on a distributed machine would be a container that contains a Host
Manager, and that is setup as a Windows Service. The container would always be
running and would be accessible to administrators for deploying additional containers
and assets on the remote system.
The following properties file was created as a response file from a Container Launcher
installation, then edited to:
Specify a standard installation location and to use the installed JRE.
Specify connection information for the assigned domain.
Stub the container name and path, and the Windows Service name.

The properties file is as shown using the defaults and the Domain Managers dmhostname:
Code Sample 9. Properties for a silent launcher installation with a container
#Choose Install Folder
#---------------------
INSTALL_LOCATION=C:\\Program Files\\Progress\\SonicLauncher
#Configure Container
#-------------------
CONFIGURE_CONTAINER=true
#Domain Manager Connection Properties

#------------------------------------
DOMAIN_NAME=Domain1
CONNECTION_URLS=tcp://dmhostname:2506
SECURITY_USER=Administrator
#The name of the container to configure

#--------------------------------------
CONTAINER_NAME=scripted
#The path for the configured container

#-------------------------------------
CONTAINER_PATH=/scripted/scripted
#Determine if the container configuration should be created if it does not exist

#-----------------------------------------------------------------------------
CREATE_CONTAINER_CONFIG=true
#The path for the host manager

#-----------------------------
HOST_MANAGER_PATH=/Framework Components/HOST MANAGER
#Should the host manager be configured?

#--------------------------------------
HOST_MANAGER_ENABLED=true
#The name of the Windows Service

#-------------------------------
WINDOWS_SERVICE_NAME=scripted
#Should the Windows Service be created?

#--------------------------------------
WINDOWS_SERVICE_ENABLED=true
#Chosen JVM Home directory

#-------------------------
CHOSEN_JVM_HOME=C:\\Program Files\\Progress\\SonicLauncher\\jre
#Launch Container Process

#------------------------
LAUNCH_CONTAINER=true
#------------------------
INI_ENCRYPT_PASSWORD=secret

The script that will run the launcher installer in this example is in the same folder as the
script and the properties file.
The script gets the hostname, puts in a variable, and then uses the hostname in the key
variables that an installation to customize:
The container name
The container path (and folder hierarchy)
The Windows Service name
The adjusted variables are passed into the silent installation as overrides to the values in
the properties file.
In this example, the container path name defines a folder hierarchy in the Directory
Service, shown here as Region1.
Code Sample 10. Script to apply the hostname to a new container
@echo off
setlocal
for /f %%h in ('hostname') do set HOSTNAME=%%h

echo Setting up Sonic container with host manager for hostname '%HOSTNAME%'
install_container_launcher.exe -i silent \
-D$CONTAINER_NAME$="ctHm%HOSTNAME%" \
-D$CONTAINER_PATH$="/Region1/Containers/ctHm_%HOSTNAME%" \
-D$WINDOWS_SERVICE_NAME$="Sonic %HOSTNAME% Service" \
-f "%~dp0install.launcher.Domain1.properties"
endlocal
The script runs, displaying its message until the installation completes. The container is
then started, connects to the domain, and records the configuration. Rerunning the script
will fail when trying to install in the same location.
Security Considerations in Silent Container Installations

The properties file that provided the responses for the silent installation contained
connection information that includes an administrator name and password. If you
distribute the silent setup package or leave it on host systems, you should be concerned if
you have enabled security in the management node.
You can avoid this situation when systems and network personnel run the script from a
secure server at the time the system is imaged and assigned its hostname. By choosing to
encrypt the container INI file with a secret password, the installation exposes no
credentials

Using Script and Property Sets to Run Container/Host Manager Installs

The examples concepts for running container and host manager setup in multiple
domains and folder hierarchies could be structured as follows:
install_container_launcher.exe
install_launcher.Domain1.properties
install_launcher.Domain1.Region1.bat
install_launcher.Domain2.properties
Launching the script for the domain and region for a host will connect to the preferred
domain and place configurations into the preferred folder. For example:
When the domain is available at the time of setup, the configuration is placed in the
domain. After distribution to its runtime location, restarting the system will start the
container through its Windows Service.
If you prefer to not see the configuration in the domain until the system is in place, run
the script at imaging time but without a network connection. When the system starts up
in a networked location, it will start up and connect to the domain.


Chapter 6 Upgrade Planning
This chapter is for users that have installed Progress Sonic components are now planning
to upgrade those components to Progress Sonic 8.5. This chapter describes the general
concepts of upgrades and the compatibilities of 8.5 with components that are at earlier
releases. The chapter is followed by a chapter specific to upgrading domains that are at
8.0, and then a chapter on upgrading domains that are advancing from 7.5 or 7.6.
Note Upgrading from versions prior to 7.5.0 is not supported in this release. If you are at an
earlier version and want to advance to this release, consult with your Progress
representative.
This chapter contains the following sections:

Introduction
Planning Sonic Upgrades
Preparing for Upgrades to Development Environments
Preparing for Upgrades to Runtime Infrastructures
Version Support in an 8.5 Domain
Distributed Systems Supported in the Domain
Compatibilities

Chapter 6: Upgrade Planning
Introduction
The general rule for upgrades is:
Components that are version 8.0.n can be upgraded to 8.5. These are referred to as
Version 8 installations. See Upgrading Version 8 Domains and Tools on page 173.
Components that are version 7.5.n or 7.6.n can be upgraded to 8.5. These are referred
to as Version 7 installations. See Upgrading from 7.5 or 7.6 to 8.5 on page 187.
Components that are version 7.0.2 or earlier should upgrade to 8.0, and then upgrade
to this release.
Some product versions represent transition points. They are exceptions to the rule:
End-of-Life products Sonic Workbench and Sonic ESB Version 8 deployment
editions do not provide upgrades for Sonic XML Server, Sonic Orchestration Server,
or Sonic Collaboration Server in development or deployment installations.
Contact your Progress Sonic representative before you upgrade any domains,
configurations, or physically upgrade installation locations that involve Sonic XML
Server, Sonic Orchestration Server, or Sonic Collaboration Server.
Change in default SSL provider Sonic no longer packages RSA libraries in its
releases. If you were using RSA and achieving FIPS compliance through the
advanced broker setting ENABLE_TLSV1_ONLY, you need to select specific cipher suites.
See the release note on this matter. (RSA libraries can be used and are available from
RSA Security.)
Planning Sonic Upgrades

Before you start upgrades, get prepared.
Getting Familiar with Sonic 8.5

Sonic 8.5 introduces several new features. These are outlined in the Progress Sonic
Update Bulletin. You might want to install Sonic 8.5 in a testbed environment to explore
the new features, and learn from its documentation set before performing upgrades.
License Requirements
License keys (control numbers) for Sonic 8.5 are required to perform Domain Manager
installationsSonic Workbench, SonicMQ Development, and Sonic Domain features.
No earlier license keys are valid in the 8.5 installation and upgrade process.

Software
The version of Eclipse in the Sonic Workbench and the version of Java that runs Java
Virtual Machines evolve from one release to the next. While you must adhere to the
supported version of these third-party products, the minor version updates of these
products might have slightly different memory profiles that could effect your runtime
components. Test your specific supported JVM with your most robust applications and
services (where possible, before you upgrade) to ensure that you get optimal performance
after upgrade.
Hardware
Upgrade of a Sonic installation creates a new directory structure for the 8.5 installation
and does not modify or delete the existing installation. The required disk space for the new
installation, application software and required JVMs make the total disk requirement for
upgrade on a system approximately two to three times the current requirements.
If a systems disk space is at a premium or if you have very large databases, consider the
disk impact of alternative tacticscopy, move, or leavefor upgrade of a brokers
datastore and logs, as described in the upgrade properties

As Sonic Workbench and SonicMQ development environments are typically monolithic
structuresa Domain Manager where the management broker also handles the
messaging traffic of the development applicationsan upgrade of those Domain
Managers completes the upgrade operations in one pass.
One consideration is the timeliness and universality of development upgrades. Consider
backing up and tagging the development source repositories before starting the upgrades
to development environments. You should strive to upgrade all users interacting on
development artifacts to upgrade within a narrow time window.
Preparing for Upgrades to Runtime Infrastructures

Runtime infrastructures managed by deployment Domain Managers must first upgrade
the Domain Manager and then administrators tools. The domain will then reflect the
compatible supported versions of the distributed components it manages.
You might need to bring some existing distributed components up to a version that is
within the scope of the compatibilities supported in 8.5

Version Support in an 8.5 Domain

If you need to continue support of older configurations, Sonic 8.5 enables creation,
management and identification of Sonic version 7.5, 7.6, and 8.0 configurations in a Sonic
8.5 Directory Service.
Versioning means that the Sonic Management Console can configure and manage older
components to the extent of their versions functionality. Creating older configured
objects in the 8.5 Sonic Management Console provides the user options and parameters
appropriate to each version as described in that versions Sonic Configuration and
Management Guide.
Once you create older configuration objects and a container boot file, use that versions
installer on the system that will host the physical installation but do not attempt to update
the Directory Service. Instead, replace the new installations boot file with the one you
generated for the configuration. That boot file binds the runtime configuration and
management communication information to the configuration maintained in the 8.5
Directory Service.
The versions of configuration objects must be consistent. For example, if you want to
extend a 7.6 cluster, create a 7.6 broker configuration as the new member, and then create
a version 7.6 container to host the broker component.
Domain-specific configuration objects

Configuration objects that are local to the Domain Manager are maintained in a Sonic 8.5
Directory Service only as 8.5 objects. New configurations can only be 8.5. When you
upgrade a Version 7 Domain Manager to 8.5, all these objects (as well as the management
container, broker, and cluster) are upgraded. The domain-specific configurations are:
Agent Manager
Authentication Domain
Authentication SPI
Authorization Policy
Certificates Store
Component Collection
Container Collection
Directory Service
Management SPI
Web Service Protocol


Configuration objects that are deployed on distributed systems managed in the domain
can be supported in the domain. New configurations can be created in a supported prior
version but require that the corresponding installer version then establishes the
appropriate products and features on the distributed system. Prior version installers cannot
connect to the newer Domain Managerthey will connect when their bootfile or setup
file is generated from the Directory Service, and then applied into their installation
location.
The supported Version 7.5 through 8.0.n configurations are:
Activation Daemon
Broker (require a license key for the selected version)
Cluster (as an aggregation of like-versioned brokers)
Collections Monitor
Container
Logger (require a license key for versions prior to 8.5)
The supported Version 8.0.n configuration is:
Host Manager
Compatibilities
A Sonic 8.5 domain lets you maintain as well as create configuration objects that are
7.5.n, 7.6.n, 8.0.n, as well as 8.5. The compatibilities of such objects to other objects are
described in the following sections.
Compatibilities of Administration Tools to an 8.5 Domain

The following compatibilities should be reviewed before you start upgrades. Once
connected to the domain, the tools can manage objects in the 8.5 domain that are 7.5 or
newer.
Compatibility of Sonic Management Console with Directory Services

The Sonic Management Console must be the same major.minor version as a Directory
Service to which it intends to connect.

Compatibility of Configuration API Applications to the Directory Service

Configuration API applications must be the same major.minor version as the Directory
Service the application wants to update.
Compatibility of Sonic JNDI API Applications to the Directory Service

Applications that use the JNDI API from 7.5 and 7.6 can access a 8.5 Directory Service
but the 8.5 JNDI API cannot access older Directory Service versions.
JNDI API Version Directory Service Version Supported?

Earlier than 7.5 8.5 No
7.5 through 8.5 8.5 Yes
8.5 Earlier than 8.5 No
Compatibility of Sonic Management API Applications to Containers

Versions of the management runtime APIs can interact with corresponding supported
container versions in the Directory Service. The older versions are limited to the Runtime
APIs functionality and the 8.5 Runtime API can only use functionality in each older
version container.
Compatibilities of Brokers
Compatibility Between Clustered Brokers
Broker Version Broker Version Supported?

7.5 through 7.6.n 8.5 Limited**
8.5 8.5 Yes
**Limited Support Clustered brokers can take advantage of Sonics Zero-Downtime

feature so that a cluster run non-stop while you upgrade the member brokers. For clusters
of brokers as far back as version 7.5, you can stop a cluster member, upgrade it to 8.5, and
then restart it. The cluster will run with mixed versions during the upgrade process. Do

Compatibilities
not use 8.5 features in the 8.5 cluster members until the cluster is fully upgraded.
Upgrading all the brokers in the cluster should be completed promptly.
Compatibility Between Replicating Brokers

7.5 through 7.6.n 8.5 Limited**
8.5 8.5 Yes
**Limited Support Replicating brokers can take advantage of Sonics Zero-Downtime

feature so that the peers take turns standing alone while the other is upgraded. For
replicating brokers as far back as version 7.5, you can upgrade a running broker that is
actively replicating. The upgrade process will stop the broker being upgraded, causing a
failover to its peer, just at the point where the version 7 data store is transferred to 8.5. The
upgrade restarts the broker in its 8.5 configuration and location. The mixed-version
brokers will resynchronize. The same process on the other peer completes the upgrade of
the replicated pair. Do not use 8.5 features in the 8.5 broker peers until both peers are fully
upgraded and synchronized. Upgrading both peer brokers should be completed promptly.
Compatibility Between Brokers for Dynamic Routing

Version 7.5 and newer brokers can perform Dynamic Routing to 8.5 brokers.


Compatibilities of Management Containers
Compatibility of Management Containers to the Domain Manager

A Domain Manager broker accepts management connections from management
containers that are supported versions in the Directory Service.
Management Container Domain Manager

Version Broker Supported?
7.5.0 through 8.5 8.5 Yes
Compatibility of Components with Management Containers

Componentssuch as brokers and ESB Containersmust be deployed in a management
container of the same version.
Compatibility of Activation Daemons to Management Containers

Management containers that are intended for launching through an activation daemon
must be of the same version as the activation daemon.
Compatibilities of Clients to 8.5 Brokers
Compatibility of Java Clients to Brokers

Generally, SonicMQ Java clients that are a few versions behind the current version are
supported by a current versions broker. An older supported client is limited to its
versions client functionality. However, 8.5 clients are not supported by any earlier
versions brokers.
You should plan to upgrade clients after upgrading messaging brokers. Clients that use
client-side persistence should force a clients 8.5 persistent store to be flushed before

Compatibilities
upgrading to 8.5. Clients that use Recoverable File Channels should complete all transfers
that are in process before upgrading to 8.5.
Java Client Version Broker Version Supported?

Compatibility of C/C++/COM Clients with Brokers

8.5 brokers accept connections from C/C++/COM clients that are 6.1 through 8.5.
Compatibility of .NET Clients with Brokers

8.5 brokers accept connections from .NET (C#) clients that are 6.1 through 8.5.
Note Java Client Code Changes The code changes required for SonicMQ applications that
were written and compiled under 7.5 or 7.6 to run under 8.5 libraries are minimal.
Applications that used the SonicMQ API, the Management API, and the Metrics and
Notifications API require no changes or recompilation.
Applications that used the Configuration API require some changes, and then
compilation. Those changes are described in the Progress SonicMQ Administrative
Programming Guide.
Important Templates If you use templates in your domain configurations, evaluate how they
interact with clusters and replicated brokers before you start performing upgrades. Each
of these forces related configurations to be upgraded concurrently. See Upgrading
Template Derived Objects on page 216 for more information.
Next,
See Upgrading Version 8 Domains and Tools on page 173.
See Upgrading from 7.5 or 7.6 to 8.5 on page 187.


Chapter 7 Upgrading Version 8 Domains and Tools
This chapter is for users that have installed Progress Sonic 8.0 domains and are now
planning to upgrade those components to Progress Sonic 8.5. This chapter contains the
following sections:
Introduction
Upgrading a Sonic Workbench 8.5 Evaluation License
Phases of Upgrades from Sonic 8.0 to Sonic 8.5

Chapter 7: Upgrading Version 8 Domains and Tools
Introduction
The upgrade procedure for Sonic Version 8 installations takes place on each Domain
ManagerSonic Workbench, SonicMQ Development, or deployment primary Sonic
Domain Managerthat is at 8.0 or higher. The Domain Manager must be running. The
upgrade will be interspersed into the existing installation directory, with new version-
identified folders for each product. The update procedure is a few tasks that extract the
existing Directory Service, stop the existing domain, and then start the upgraded domain
and import the configurations.
Administration Tools are a tools-only install with no date stores. You can simply install
the newer tools in a different location. You must use 8.5 Administration Tools to access
an 8.5 Domain Manager.
The upgrade processes differ significantly for Version 8 Domain Manager systems, and
distributed components:
Domain Manager Systems Distributed Components

Scope Management containers that host a Management containers that have a
Domain Manager: Launcher installation and are
Sonic Workbench managed in the Version 8 domain
that will be upgraded.
SonicMQ Development
deployment Domain Managers
Installation The appropriate Sonic Installer No action required.
Type installation type, but choosing to not
configure the Domain Manager.
Upgrade Located in the installations
utilities MQ8.5/bin directory
Upgrade Migrates the 8.0 Domain Managers

process container, Directory Service, and
management broker to the 8.5
installation location.


If you have the Sonic Workbench Version 8.5 Evaluation Edition, contact Progress Sonic
to get licensed as a developer for the Sonic Workbench Version 8 Developer Edition.
When you get your updated license key, running a script in the existing installation
records the new license even if the existing evaluation license has expired.
To upgrade a Version 8.5 Sonic Workbench Evaluation license:
1. Stop all containers in the installation.
2. Open a console window at the sonic_install_dir/Workbench8.5 root.
3. Enter: bin\eval_upgrade [.bat | .sh ] -b host:port -u name -p password
-d domain -c newLicenseKey -ds path-to-ds.xml
where:
host:port is the system name and port of the management broker
name is the username of an administrator in the domain
password is the usernames password
domain is the domain of the installation
newLicenseKey is the new license key
path-to-ds.xml is the absolute location of the domains Directory Service boot
file, typically sonic_install_dir\Containers\Domain1.DomainManager\ds.xml
Using default values for all but the new license key, this entry is:
On Windows (as one line):
bin\eval_upgrade.bat -b localhost:2506 -u Administrator -p Administrator
-d Domain1 -c newLicenseKey
-ds c:\Program Files\Progress\Sonic\Containers\Domain1.DomainManager\ds.xml
On Linux (as one line):
bin/eval_upgrade.sh -b localhost:2506 -u Administrator -p Administrator
-d Domain1 -c newLicenseKey
-ds /opt/user/Progress/Sonic/Containers/Domain1.DomainManager/ds.xml
4. When you are prompted to start the container that hosts the Domain Manager, choose,
on Windows, Start > Programs > Progress > Sonic 8.5 > Start Domain Manager,
or, on Linux, enter the command:
sonic_install_dir/Containers/Domain1.DomainManager/launchcontainer.sh
5. Once the startup indicates that it is complete, press Enter in the console window to
complete the upgrade.
The process upgrades the licenses of the products in the Sonic Workbench. When it
completed, you can resume working on the Sonic Workbench under the new license.


The phases of upgrade a Sonic 8.0 domain, its configured objects and deployments are:
Phase I Perform upgrade operations on the Domain Manager. The Sonic Installer
installs all the licensed products and the administration tools on Workbench, MQ
Development, and deployment Domain Manager systems. The configuration of the
8.5 Domain Manager is not done at the time of installationthe upgrade process will
connect to the 8.0 domain to migrate the entire Directory Service to 8.5. Finally, the
task of updating classloading paths in service types completes the phase.
Phase II Perform upgrade operations on tools-only machines. After a deployment
Domain Manager has been upgraded, tools installed on other machines must be
upgraded. See Installing Administration Tools on page 91
Phase III Perform upgrade on managed components through administration tools
to provision archives and launchers on distributed hosts. After a deployment Domain
Manager has been upgraded, components and tools installed on other machines must
be upgraded.
Phase I: Upgrade Sonic 8.0 Domain Installations to 8.5

The sequence of actions involves inserting the 8.5 product folders into the 8.0 installation
location without configuring the domain.
Important Whats running? For a Workbench, stop everything on the Domain Manager machine.
For other Domain Manger types (MQ Development, deployment Domain Manager), the
Domain Manager must be running.
The operations described in this phase are:

1. Specific installation instructions for each Domain Manager type:
Adding Sonic 8.5 Workbench into a Sonic 8.0 Workbench Location.
Adding Sonic 8.5 Domain Manager into a Sonic 8.0 MQ Dev Location.
Adding Sonic 8.5 Domain Manager into a Sonic 8.0 Deployment Domain.
2. Extracting the 8.0 Domain Managers Properties on page 179
3. When appropriate, Unencrypting Domain Manager Boot Files on page 180
4. Editing an 8.0 Domain Managers upgrade.properties file on page 181
5. Running a Domain Manager Upgrade on page 181
6. Updating Classloading Paths in Service Types on page 182
7. Restoring Encrypted Domain Manager Boot Files on page 183
If your deployment Domain Manager is a fault-tolerant management framework,

finish by Completing an Upgrade of a Fault Tolerant Management Framework on
page 183
Adding Sonic 8.5 Workbench into a Sonic 8.0 Workbench Location

Important The existing Eclipse environment needs to have fully started and gracefully shutdown so
that it creates the settings files that the upgrade procedure uses.
To upgrade Sonic Workbench 8.0 to 8.5:

1. Stop the Workbenchs Eclipse environment.
2. Stop the Workbenchs Domain Manager.
3. Stop the Sonic Management Console.
4. Use the Sonic Installer to point to an existing Sonic 8.0 installation location of Sonic
Workbench. Installing a Progress Sonic Workbench on page 76.
5. Choose Sonic Development, and then enter your Sonic Workbench 8.5 license key.
6. On the Configure Sonic Workbench panel, select the Do not configure domain at this
time option. The other values on that panel will be ignored, so click Next.
7. Choose an Eclipse. Choosing an existing Eclipse will determine whether it is
supported.
8. Choose a Java VM. Choosing an existing JVM will confirm whether it is supported.
9. Click Install and complete the installation.
10. Proceed to Extracting the 8.0 Domain Managers Properties on page 179.
Adding Sonic 8.5 Domain Manager into a Sonic 8.0 MQ Dev Location
To upgrade SonicMQ Development 8.0 to 8.5:
1. Start the Sonic 8.0 Domain Manager you want to upgrade.
2. If you have any Sonic Management Consoles running, shut them down.
3. Use the Sonic Installer to point an existing Sonic 8.0 installation location of SonicMQ
Development. Installing SonicMQ for Development on page 82.
4. Choose Sonic Development, and then enter your SonicMQ 8.5 license key.
5. On the Configure MQ Development panel, select the Do not configure domain at this

8. Proceed to Extracting the 8.0 Domain Managers Properties on page 179.
Adding Sonic 8.5 Domain Manager into a Sonic 8.0 Deployment Domain
To upgrade a Sonic Domain 8.0 to 8.5:
1. Start the Sonic 8.0 Domain Manager you want to upgrade.
2. If you have any Sonic Management Consoles running, shut them down.
3. If you are using a fault-tolerant management framework, confirm that the primary and
the backup are running, that replication connections are functioning, and that the
primary Domain Manager is in the active role.
4. Use the Sonic Installer to point an existing Sonic 8.0 installation location of a primary
deployment domain manager. Installing a Domain Manager on page 87.
5. Choose Sonic Domain, and then enter your SonicMQ 8.5 deployment license key.
Add Sonic ESB, and Sonic BPEL Server 8.5 deployment keys if they are available to
you.
6. On the Configure Domain panel, select the Do not configure domain at this time
option. The other values on that panel will be ignored, so click Next.
9. Proceed to Extracting the 8.0 Domain Managers Properties on page 179

Extracting the 8.0 Domain Managers Properties

To extract the properties of the 8.0 Domain Manager:
1. Open a console window to the 8.5_install_root/MQ8.5/bin location.
2. Enter:
upgradeProps -url conn -d domain -u user -p pwd -f file -rt secs /ds_path
where:
-url is a connection URL on the Sonic 8.0 management broker
Note For a SonicMQ Development or Domain Manager upgrade, the Sonic 8.0
connection URL is in the form protocol://host:port, where a default
installation would use tcp://localhost:2506.
For a Sonic Workbench upgrade, the Sonic 8.0 connection is a direct access
to the stopped Directory Servicethe installation path to the Directory
Service boot file, typically
sonic8_install_dir\Containers\Domain1.DomainManagerL/ds.xml.
-d is the domain name. The default value is Domain1.

-u is an administrative user (typically, Administrator)
-p is the administrative users password (optional if security is not enabled)
(For a Sonic Workbench upgrade, enter the ds.xml password if it is encrypted.)
-f is a preferred output file name (default is upgrade.properties)
-rt is the number of seconds that the script will wait to invoke a methods on the
Directory Service before timing out. (default is 60 seconds)
/ds_path is the Directory Service location of the container that hosts the
Directory Service in the 8.0 domain (typically, /Containers/DomainManager)
The process runs, creating a text file in the 8.5_install_root/MQ8.5/bin folder named
upgrade.properties (or the name you specified in the -f parameter) which contains the
Version 8 license keys you entered and the explicit file system path to the Domain
Managers management container.

Unencrypting Domain Manager Boot Files

If you have encrypted the Directory Service boot file and its container boot file, you must
decrypt them for the duration of the upgrade process. (Whether you have encrypted the
Directory Service store is not relevantthe decrypted DS boot file will contain the
appropriate DS encryption password if it is encrypted.)
You need to know the password that encrypted the boot files.
You will restore these encrypted files as-is after the upgrade has completed successfully.
Note You may want to use explicit paths for the location in the following commands and files.
To temporarily decrypt the Domain Managers boot files:

1. Open a command prompt in the Domain Managers working directory, typically
C:\Program Files\Progress\Sonic\Containers\Domain1.DomainManager.
2. Create a subdirectory named encrypted.

3. Move the files ds.xml, container.ini, and set_encryption_pwd.* into the encrypted
directory.
4. Enter the following commands:
On Windows, enter:
..\..\MQ8.5\bin\pbetool /m decrypt
/c container.ini
/e encrypted\container.ini /p pwd
..\..\MQ8.5\bin\pbetool /m decrypt
/c ds.xml
/e encrypted\ds.xml /p pwd
On UNIX/Linux, enter:
../../MQ8.5/bin/pbetool.sh -m decrypt
-c container.ini
-e encrypted/container.ini -p pwd
../../MQ8.5/bin/pbetool.sh -m decrypt
-c ds.xml
-e encrypted/ds.xml -p pwd
The active boot files are decrypted, and the encrypted files are in the encrypted folder.

Editing an 8.0 Domain Managers upgrade.properties file

An 8.0 Domain Managers upgrade.properties file typically requires no edits.
Note Upgrade Properties The upgrade properties for Domain Managers are a more
significant issue in upgrading Version 7 Domain Manager and components. They are
listed in that chapter at General Properties in an upgrade.properties file on page 200
and Container-specific Properties in an upgrade.properties file on page 202.
You will however need to edit it before running the Domain Manager upgrade:
If the HOST_DIRECTORY value in the Directory Service boot file (ds.xml) is a relative
value. It is actually the working directory that needs to be specified. Edit the property
DomainManager_container.previous.working.directory to add the explicit path.
There are no other edits that you should perform to this file unless instructed to do so.
Important Use forward slashes '/' in path values on Windows. For instance, c:/Sonic/MQ8.0/ct01.xml.
Running a Domain Manager Upgrade

To perform the upgrade of the Domain Manager:
1. Use the console window that is open at the 8.5_install_root/MQ8.5/bin location.
2. Enter:
upgrade upgrade.properties [previous_workbench_location]
where:
upgrade.properties is the default name of the file that provides the properties for
the upgrade process. If you used the -f parameter when you ran upgradeProps, use
that file name instead.
previous_workbench_location is the explicit path to the 8.0 Sonic Workbench
installation root. Optional, needed only in a Sonic Workbench upgrade where the
workspace is to be migrated from the old installation to the new one, and both the
old and new workbench contain Eclipse that Sonic installed.
The Domain Manager components and stores are upgraded to 8.5. The upgrade proceeds
to upgrade its Directory Service. If the brokers store needs upgrades, they are performed
in place. The upgrade logic stops the running 8.0 Domain Manager, and then starts the 8.5
Domain Manager to complete the upgrade.

Results of a Domain Manager Upgrade

The Domain Manager container and the components it hosts are all Version 8.5.
The following components were upgraded automatically to Version 8.5:
WebService Protocol configurations
Component Collection configurations
Container Collection configurations
Agent Manager configurations
Directory Service configurations
Authentication Domain configurations
Authentication SPI configurations
Management SPI configurations
Authorization Policy configurations
Updating Classloading Paths in Service Types

The service types in the Directory Service need to have their classloading information
upgraded. You accomplish this through an export/remap/import set of steps.
Note You can exclude specified services from this procedure by editing
sonic_install_dir/ESB8.5/bin/upgrade/exportServices.xml. If you do that, you might
need to manually adjust the classloading configuration for those services later.
To update service classpaths:

1. On the Domain Manager machine you are upgrading, start the ESB Admin tool:
Choose Start > Programs > Progress > Sonic8.5 > Tools> ESB Admin Tool
Enter a shell command for sonic_install_dir/ESB8.5/bin/esbadmin.bat or .sh.
2. Enter a connect command such as:
connect Domain1 tcp://localhost:2506 Administrator Administrator
3. Execute the following commands, using appropriate paths for your machine:
export archive c:/temp/services80.xar upgrade/exportServices.xml
applyMap -xar c:/temp/services80.xar -xar c:/temp/services85.xar

-map upgrade/upgradeMap.xml -log c:/temp/applyMap.log
import archive c:/temp/services85.xar override

When you have completed the procedure, all references to 8.0 system jars have been
upgraded and their configurations are supported in any 8.0 or 8.5 ESB container.

Restoring Encrypted Domain Manager Boot Files

If you performed the task of Unencrypting Domain Manager Boot Files on page 180,
and the upgraded Domain Manager has started successfully, you can restore the encrypted
Directory Service boot file and its container boot file.
To restore the Domain Managers encrypted boot files:

1. Open a command prompt in the Domain Managers working directory, typically
C:\Program Files\Progress\Sonic\Containers\Domain1.DomainManager.
2. Rename ds.xml to ds_CLEAR.xml.

3. Rename container.ini to container_CLEAR.ini.
4. Copy the encrypted files (ds.xml, container.ini, and set_encryption_pwd.*) from
the encrypted folder to the working directory.
5. Restart the Domain Manager.
6. When the Domain Manager completes a successful startup, you can delete the
cleartext workfiles ds_CLEAR.xml and container_CLEAR.ini. It is a good practice to
maintain the encrypted folder as a backup of the encrypted boot files.
Completing an Upgrade of a Fault Tolerant Management Framework

When you initiated upgrade on a primary Domain Manager, the primary Domain
Manager sets the read-only flag for the backup, restarts it in read-only mode, shuts down
the primary, upgrades Directory Service storage, shuts down the backup, and then restarts
the primary.
To complete the upgrade of the backup Domain Manager:

1. On the backup Domain Manager machine, delete the Directory Service Storage.
(Typically, C:\Program Files\Progress\Sonic\Containers\Domain1.DomainManager\
Domain1 folder).
2. Restart the container that hosts the backup Domain Manager.

When the backup Domain Manager connects to the primary, the updated Directory
Service store is transferred to the backup location.

Phase II: Install Tools for Deployment Domain Administrators

For deployment domains, the administrators with machines that will connect to the
Domain Manager remotely, install the 8.5 Administration Tools as soon as possible. See
Installing Administration Tools on page 91 for instructions.
To administrate a Version 8.5 Domain Manager:

1. Start the Version 8.5 Sonic Management Consoles, or administrative tools.
2. Connect to the upgraded domain.
Phase III: Upgrade 8.0 Components in the 8.5 Domain

Container-based components maintained in the Version 8.5 domain can be upgraded
through the Sonic 8.5 Management Console.
Important Version 7 components in an 8.0 Domain If you updated a Domain Manager to 8.0 but
retained version 7 installations and managed components in the domain, ones that are
7.5.n or 7.6.n must be upgraded through the Version 7 to Version 8 steps described in
Phase III: Upgrade 7.5 and 7.6 Components To 8.5 on page 195. If you have earlier
7.0.n installations, they must be upgraded to 8.0 and then to 8.5.
The procedure below describes an upgrade of an independent broker configurations. It

applies equally well to ESB services.
Upgrading Deployed Version 8 Containers and their Components

The Sonic Management Console makes it easy to upgrade remote Version 8 deployments.
To upgrade an 8.0 container and its components:

1. Start the Version 8.5 Sonic Management Console, and then connect to the 8.5 domain.
2. On the Configure tab, locate an 8.0 container configuration you want to upgrade.

3. Right-click on the container name, and then choose Upgrade, as shown for ctData0:
:
4. The Confirm Upgrade dialog box opens, as shown:

:
5. Review the list of containers and components that will be forced to upgrade as a result
of this upgrade so that tightly-bound components such as replicated brokers are all at
the same version.
Clustered brokers are not forced to upgrade; however, you are advised to always
operate clusters of brokers at the same version and patch level.
6. If a broker is hosted in this container, enter an 8.5 SonicMQ license key.

7. Click OK.
When you restart this container, the remote location will be provisioned with:
The containers 8.5 configuration
The 8.5 archives required for the components hosted in that container
The resources that advance the remote locationss Container Launcher to 8.5
8. Restart all the other deployed containers that were listed as dependencies when you
upgraded the container. This a zero-downtime operation. You are encouraged to
restart peers of upgraded replicating brokers as soon as possible, and then all cluster
members.
The selected Domain has been upgraded to Sonic 8.5.

Chapter 8 Upgrading from 7.5 or 7.6 to 8.5
This chapter is for users that have installed Progress Sonic components at 7.5 or 7.6 and
are now planning to upgrade those components to Progress Sonic 8.5. This chapter
contains the following sections:
Introduction
Phases of Upgrades from 7.5 and 7.6 to Sonic 8.5
Zero-Downtime Upgrades of 7.5 and 7.6 Clusters and Replicated Brokers
Upgrading a Fault Tolerant Management Framework
Upgrading Other Configuration Objects
Verification and Housekeeping Tasks After Upgrading
Note Upgrading from versions prior to 7.5.0 is not supported in this release. If your at an earlier
version and want to advance to this release, consult with your Progress representative.

Chapter 8: Upgrading from 7.5 or 7.6 to 8.5
Introduction
For Sonic 7.5 and 7.6 installations, the advantages of Sonic 8.5 centralized installation
and provisioning (see About Sonic Installation Maintenance on page 26) are not
realized until the development environments and distributed hosts each have the minimal
functionality that enables participation in the new paradigm. Similar to prior upgrades, an
installation is required on each system. However, unlike previous versions updates, the
8.5 installers do not embed the upgrade logic. Instead, you perform an installation on each
Domain Manager and each system that hosts components managed in the domain.
The upgrade processes differ significantly for Domain Manager systems, and distributed
components:
Domain Manager Systems Distributed Components

Scope Management containers that host a Management containers that do not
Domain Manager: host a Domain Manager, and that
Sonic Workbench are root containersa container
that is started by a script or a
SonicMQ Development
windows service on a host, not by an
deployment Domain Managers
activation daemon.
Installation The appropriate Sonic Installer A Sonic Container Launcher
Type installation type, but choosing to not installation with no container
configure the Domain Manager. defined.
Upgrade Located in the installations Located in the installations
utilities MQ8.5/bin directory Upgrade directory
Upgrade Migrates the 7.5 or 7.6 Domain Migrates 7.5 and 7.6 containers and
process Managers container, Directory their hosted components to the
Service, and management broker to installations Containers directory,
the 8.5 installation location. and then update the version in the
8.5 Directory Service.


The phases of preparation for upgrade of a Sonic 7.5 or 7.6 domain and its configured
objects and deployments are:
Phase I Perform appropriate Sonic 8.5 installations on every system that
participates in the domain.
Phase II Perform upgrade operations on the Domain Manager, and then use
Version 8 management tools to administrate the Sonic 8.5 domain.
Phase III Perform upgrade operations on components managed by the domain on
their respective host systems.
The flow of procedures in a complete upgrade include:

1. Upgrade Domain Managers The Sonic Installer installs all the licensed products
and the administration tools on Workbench, MQ Development, and deployment
Domain Manager systems. The configuration of the 8.5 Domain Manager is not done
at the time of installationthe upgrade process will connect to the 7.5 or 7.6 domain
to migrate the entire Directory Service to 8.5.
If you have a fault-tolerant management framework, see Upgrading a Fault Tolerant
Management Framework on page 211.
2. Upgrade Distributed Components and Tools in a Deployment Domain
After a deployment Domain Manager has been upgraded, components and tools
installed on other machines must be upgraded:
Install Administration Tools While the Domain Manager installations already
have the 8.5 administrative toolset, remote administrators with just the tools need
the latest tools installed so that they can connect to the upgraded Domain
Manager when it comes online. See Installing Administration Tools on
page 91.
Upgrade Brokers:
Independent messaging brokers Phase III: Upgrade 7.5 and 7.6
Components To 8.5 on page 195
Clusters of Brokers See Upgrading a Cluster of Brokers on page 207.
Replicated Brokers See Upgrading Replicated (Fault Tolerant) Broker
Pairs on page 208.
Clusters of Replicated Brokers See Upgrading a Cluster of Replicated
Brokers on page 209

Upgrade ESB Services Sonic ESB services, as well as extensions to BPEL and
Database Services. Each management container will be upgraded. See Phase III:
Upgrade 7.5 and 7.6 Components To 8.5 on page 195
3. Upgrade the remaining Version 7 components:
Upgrading Activation Daemons on page 215
Upgrading Collections Monitors on page 216
Upgrading Template Derived Objects on page 216
4. Complete the Verification and Housekeeping Tasks After Upgrading on page 217
Phase I: Perform 8.5 Installations on 7.5 and 7.6 Systems

Perform an appropriate Version 8 installation in a new directory on each system that hosts
7.5 and 7.6 components or tools:
Sonic Installer: Sonic

Upgrade Container
Installation Type
Sequence Launcher Option
Domain Managers Sonic Workbench Choose to not configure the
Domain during the
SonicMQ installation.
Development Enter all 8.5 license keys
Domain Manager
Admin Tools Administration Tools
Brokers Every non-DM Choose to not configure a

system that container during the installation.
Clusters has 7.5 or 7.6
Replicated Brokers containers and
components
Clusters of
Replicated Brokers
ESB Services
See Chapter 2, Using Progress Sonic Installer, and Chapter 3, Using Progress Sonic
Launcher Installer, for more information on the installers and their options.

Phase II: Upgrade the 7.5 or 7.6 Domain Manager to 8.5

The first steps of a Domain Manager upgrade are specific to the type of Domain Manager:
Sonic Workbench
SonicMQ Development
Deployment Domain Manager
Note If your deployment Domain Manager is a fault-tolerant management framework, go

directly toUpgrading a Fault Tolerant Management Framework on page 211.
Establishing a 8.5 Sonic Workbench on a 7.5 or 7.6 System

Important The existing Eclipse environment needs to have fully started and gracefully shutdown so
that it creates the settings files that the upgrade procedure uses.
To establish the 8.5 Workbench location:

1. Stop the Workbenchs Eclipse environment.
2. Stop the Workbenchs Domain Manager.
3. Stop the Sonic Management Console.
4. Use the Sonic Installer to create a new installation location for Sonic Workbench on
the same system as the 7.5 or 7.6 installation. Installing a Progress Sonic
Workbench on page 76.
5. Enter your Sonic Workbench 8.5 license key.
6. On the Configure Installation Type panel, select the Do not configure domain at this
7. Choose an Eclipse. Choosing an existing Eclipse will determine whether it is
supported.
8. Choose a Java VM. Choosing an existing JVM will determine whether it is supported
Java Runtime Environment.
10. Proceed to Extracting the 7.5 or 7.6 Domain Managers Properties on page 193.

Establishing a 8.5 SonicMQ Development on a 7.5 or 7.6 System

To establish the 8.5 SonicMQ Development location:
1. Start the7.5 or 7.6 Domain Manager you want to upgrade.
2. If you have any 7.5 or 7.6 Sonic Management Consoles running, shut them down.
3. Use the Sonic Installer to create a new installation location for SonicMQ
Development on the same system as the 7.5 or 7.6 installation. Installing SonicMQ
for Development on page 82.
4. Enter your SonicMQ 8.5 license key.
Establishing a 8.5 Domain Manager on a 7.5 or 7.6 System

To establish the 8.5 deployment Domain Manager location:
1. Start the 7.5 or 7.6 Domain Manager you want to upgrade.
2. If you have any 7.5 or 7.6 Sonic Management Consoles running, shut them down.
3. Use the Sonic Installer to create a new installation location for Domain Manager on
the same system as the Version 7 installation. Installing SonicMQ for Development
on page 82.
4. Enter your Sonic 8.5 license keys. You must enter SonicMQ 8.5 key. Add ESB, and
BPEL Service keys if they are available.

Extracting the 7.5 or 7.6 Domain Managers Properties

To extract the properties of the Domain Manager:
2. Enter:
upgradeProps -url conn -d domain -u user -p pwd -f file -rt secs /ds_path
where:
-url is a connection URL on the Version 7 management broker
Note For a SonicMQ Development or Domain Manager upgrade, the Sonic 7
connection URL is in the form protocol://host:port, where a default
installation would use tcp://localhost:2506.
For a Sonic Workbench upgrade, the Sonic 7 connection is a direct access to
the stopped Directory Servicethe installation path to the Directory Service
boot file, typically sonic7_install_dir/MQ7.n/ds.xml.

-u is an administrative user in the Version 7 domain (typically, Administrator)
(For a Sonic Workbench upgrade, enter the ds.xml password if it is encrypted.)
-f is a preferred output file name (default is upgrade.properties)
-rt is the number of seconds that the script will wait to invoke a methods on the
Directory Service before timing out. (default is 60 seconds)
/ds_path is the Directory Service location of the container that hosts the
Directory Service in the Version 7 domain (typically,
/Containers/DomainManager)
upgrade.properties (or the name you specified in the -f parameter) which contains the
Version 8 license keys you entered and the explicit file system path to the Domain
Managers management container.
The upgrade properties for Domain Managers and non-Domain Managers are listed in
General Properties in an upgrade.properties file on page 200 and Container-specific
Properties in an upgrade.properties file on page 202.

Editing a Domain Managers upgrade.properties file

A Domain Managers upgrade.properties file typically requires no edits.
You will however need to edit it before running the Domain Manager upgrade:
If the HOST_DIRECTORY value in the Directory Service boot file (ds.xml) is a relative
value. It is actually the working directory that needs to be specified. Edit the property
DomainManager_container.previous.working.directory to add the explicit path.
If the paths to the management brokers data store and logs are relative paths, add the
explicit path to the DomainManager_container.previous.working.directory property.
If you have XML Server service instances, remove any containers in the upgrade.list
that contain ESB containers with XMLService service instances.
There are no other edits that you should perform to this file unless instructed to do so.
Running a Domain Manager Upgrade

To perform the upgrade of the Domain Manager:
2. Enter:
upgrade upgrade.properties [previous_workbench_location]
where:
upgrade.properties is the default name of the file that provides the properties for
the upgrade process. If you used the -f parameter when you ran upgradeProps, use
that file name instead.
previous_workbench_location is the explicit path to Version 7 Sonic Workbench
installation root. Optional, needed only in a Sonic Workbench upgrade where the
workspace is to be migrated from the old installation to the new one, and both the
old and new workbench contain Eclipse that Sonic installed.
The Domain Manager components and stores are moved to the 8.5 location and file
structure, and then upgraded.
The upgrade proceeds to upgrade and migrate its Directory Service. The upgrade logic
stops a running Version 7 Domain Manager when it is ready to move the brokers store,
and then starts the 8.5 Domain Manager to complete the upgrade.

To administrate the Version 8 Domain Manager:

1. Start the 8.5 Sonic Management Consoles, or administrative tools.
2. Connect to the upgraded domain.
Results of a Domain Manager Upgrade

The Domain Manager container and the components it hosts are all 8.5.
The following components were upgraded automatically to 8.5:
WebService Protocol configurations
Component Collection configurations
Container Collection configurations
Agent Manager configurations
Directory Service configurations
Authentication Domain configurations
Authentication SPI configurations
Management SPI configurations
Authorization Policy configurations
Installing Administration Tools for Deployment Domain Administrators

For deployment domains, the administrators with systems independent of the installed
Domain Manager, install the appropriate set of Administration tools as soon as possible.
See Installing Administration Tools on page 91 for installation instructions.
Phase III: Upgrade 7.5 and 7.6 Components To 8.5

Container-based components maintained in the 8.5 domain can be upgraded from 7.5 or
7.6 to 8.5 as time allows. The 8.5 domain supports all 7.5 and 7.6 container-based
components, and the zero-downtime feature of 8.5 enables clustered and replicating
brokers to cooperate during their series of upgrades.
The Version 7 and 8.5 handling of containers and upgrades require understanding of the
following container concepts:
Root containers The 7.5 and 7.6 containers that are launched by the 7.5 or 7.6
MQ7.n/bin/startcontainer script are root containers; also containers launched by a
Windows service.
Working directory In 7.5 and 7.6, the single container start script meant that the
container boot file could be anywhere on the system, and the original startcontainer
scriptif used without modificationsfixed every containers working directory at

the installations MQ7.n root. The configuration of the container (cache and log) and
the broker (recovery log and data store) were relative offsets from the canonical
working directory.
In 8.5, each container has a unique subdirectory in the installations Containers
directory that contains the configuration file and the launch script for the container as
well as the containers cache and log, and the brokers recovery log and data store.
This transition requires that the upgrade properties for a container that are extracted
need to locate the 7.5 or 7.6 installations MQ7.0 root. You will edit each
upgrade.properties file to add the explicit path to the 7.5 or 7.6 working directory.
License keys The remote systems do not have license keys for the products they
are upgrading. You will edit each upgrade.properties file to add its 8.5 keys.
Whats running, whats not running The 8.5 Domain Manager should be running
during all upgrades of container-based components. A brokers container does not
have to be shutdown if it is upgraded through the upgrade tool and the tool has a
management connection. The upgrade tool will shutdown the container when the time
comes to copy the broker database.
Sequence of 7.5 and 7.6 to 8.5 Component Upgrade Tasks

The tasks for container and component upgrades after the Domain Manager has been
upgraded are:
1. Start the containers in each 7.5 and 7.6 installation that will be upgraded.
2. Install the 8.5 Sonic Container Launcher on each system to be upgraded.
a. Specify a new installation location.
b. Choose to not install a container.
3. Open a command prompt to the Launcher installations Upgrade/bin directory.
4. Use the upgradeProps script to extract the information about a container and its
components from the upgraded 8.5 Directory Service.
5. Edit the extracted upgrade.properties file to specify the 7.5 or 7.6 working directory
(if needed), the 8.5 license keys, and possibly other available properties.
6. Use the upgrade script to initiate the migration of the configuration and stores, and the
provisioning of the installation with 8.5 functionality.

The procedure below describes an upgrade of an independent broker configurations. It

applies equally well to ESB services. The process is identical for installations created by
the Sonic installers and ones created by the Sonic Depoloyment Manager.
Using the upgradeProps Script to Extract a Container Configuration

To extract the properties of a container and its hosted components:
1. On a local system that has a 7.5 or 7.6 installation, and a 8.5 Sonic Container
Launcher installation (see Installing The Sonic Launcher on Distributed Hosts on
page 111), open a window to the 8.5_launcher_install_root/Upgrade/bin location.
2. Enter: upgradeProps -url broker -d domain -u user -p pwd /container_path
where:
/dm_container_path is the path of the container in the domains Directory
Service. For example, /Containers/ct11.
The process runs, creating a text file in the 8.5_launcher_install_root/Upgrade/bin
directory named upgrade.properties.

The upgrade.properties file for a container named ct01 would look something like this:
!NOTE: Use forward slashes '/' in path values on Windows.

!For instance, c:/Sonic/MQ7.0/ct01.xml
!*****************************************************************
!*************** debug flag - set to true to enable debugging output
migrate.debug=false
!*************** Tool connection properties

ds.url=tcp://localhost:2506
ds.username=Administrator
ds.password=
ds.domain=Domain1
connection_node=
request.timeout=60
connection.system.properties=
!*************** Control Numbers

sonic.mq.controlNumber=*************
sonic.esb.controlNumber=
workbench.controlNumber=
!*************** Root container configurations

root.list=/Containers/ct01
!*************** Configurations to be upgraded

upgrade.list=/Containers/ct01
!*************** Properties for container /Containers/ct01

ct01.boot.file.password=
ct01.central.connection.url=
ct01.central.connection.username=
ct01.central.connection.password=
ct01.central.connection.request.timeout=
ct01.central.connection.connect.timeout=
ct01.central.connection.socket.connect=
ct01.central.connection.load.balancing=
ct01.central.connection.system.properties=
ct01.cache.dir=C:/Program Files/Progress/SonicLauncher/Containers/Domain1.ct01
ct01.log.dir=C:/Program Files/Progress/SonicLauncher
/Containers/Domain1.ct01/Domain1.ct01.log
ct01.db.action=COPY
ct01.mqstore.db.connect=C:/Program Files/Progress/SonicLauncher
/Containers/Domain1.ct01/SonicMQStore
ct01.recovery.log.file=/Program Files/Progress/SonicLauncher/Containers/Domain1.ct01/log
ct01.windows.service.name=
ct01.previous.working.directory=

Editing a non-Domain Manager upgrade.properties file

The result of extracting an upgrade.properties file for a container and its hosted
components can provides the migration tool all the information needed for the upgrade.
You might need to perform some edits to the upgrade.properties file before running the
upgrade:
Add 8.5 license keys for SonicMQ broker components in the product.controlNumber
properties.
If the container includes a broker with paths to the brokers data store and logs as
relative paths, add the explicit path to the container.previous.working.directory
property.
Extend the root.list to include multiple containers on the local host, and then add
container-specific properties for each additional container.
For management over Dynamic Routing, add a management routing nodes central
connection properties, and add the local connection and management node to
containers that use a management routing node.
Adjust broker database and log actions and locations for the upgrade.
Specify paths to SSL paths to certificates
Establish a Windows Service for a container
The tables of upgrade properties are distinguished as general properties and container-
specific properties.
Running a non-Domain Manager Upgrade

To perform the upgrade of the container:
1. Open a console window at the 8.5_launcher_install_root/Upgrade/bin location that
contains the upgrade properties file you want to run.
2. Enter:
upgrade upgrade.properties
The container and its components and their stores are migrated to the 8.5 subdirectory of
the 8.5 Launchers Containers directory.

General Properties in an upgrade.properties File

These are properties that apply to all containers specified in the root.list.
Table 12. General Properties in an upgrade.properties file
Property Description of value Required Notes

Debug Flag
migrate.debug true No. When set to true, the upgrade tool
false (default) prints extensive diagnostic messages.
Reserve this property for debugging.
Tool Connection properties
ds.url For connection URL, Required. Establishes management connection
the host:port (assumes TCP) for configuration upgrades.
For direct connection,
the explicit path of ds.xml
ds.username Administrative username Required.
ds.password Administrative users Required if
password MgmtBroker is
security enabled.
ds.domain Name of the domain. Required.
For example, Domain1.
connection_node Routing node name Required when
connection over
DRA. The
management
node must be
running.
request.timeout Time, in seconds, that the Optional. Default value is 60 (seconds).
upgrade process will wait
for a connection to the
Domain Manager.
connection.system. Any system properties that Optional. For example, SSL properties.
properties
need to be set for
management.

Table 12. General Properties in an upgrade.properties file (continued)

Control Numbers (License Keys)
sonic.mq. SonicMQ 8.5 Broker license Required when a
controlNumber
key container being
upgraded hosts a
broker.
sonic.esb. Sonic ESB 8.5 license key Required when a Enables the migration tool to load
controlNumber
container being plugins and ESB archive files into
upgraded hosts the Directory Service.
an ESB
container.
Container lists
root.list A comma-delimited list of Required. The configuration dependencies of
containers on the local host each container are extracted, and
that will be setup in the 8.5 those configurations are setup.
location. All containers in the root.list and
upgrade.list will be upgraded.
In a Workbench upgrade (when
workbench.controlCode was entered
in the 8.5 installation), the root list
can be empty: all containers are
upgraded in that case.
If the containers in root.list cannot
be located by the upgrade tool, an
exception is thrown.
upgrade.list A comma-delimited list of Required. The configuration dependencies of
containers on the local host each container are extracted, and
that need to be upgraded. those configurations will be
upgraded.
If the containers in upgrade.list
cannot be located by the upgrade
tool, an exception is thrown.

Table 12. General Properties in an upgrade.properties file (continued)

template.list A comma-delimited list of As generated. Do not modify this file.
non-container templates that
need to be upgraded.
Container-specific Properties in an upgrade.properties File.

The properties Table 13 are specified by container names (which are unique in a domain.)
For example, for container ct01, the first property would be ct01.boot.file.password.
Table 13. Container-specific Properties in an upgrade.properties file
Property for
container name Description of value Required Notes
Version 7 Working Directory
name. The working directory of the Required if the -
previous.working.
management container configured
directory
before the migration location of the
logs, cache, and
broker data store
are relative paths.
Broker data store and recovery logs
name.db.action Determines how to handle If not specified, -
the broker database and logs the database and
in the migration. logs remain in
One of: their 7.5 or 7.6
locations.
COPY
MOVE
LEAVE

Table 13. Container-specific Properties in an upgrade.properties file (continued)
Property for
name.mqstore. Path to the new broker Required when Might also require edits to
db.connect
database name.db.action is name.previous.working.directory.
COPY or MOVE For db.action of COPY or MOVE,
name. Path to the new broker
recovery.log.file (else an exception locates the 7.5 or 7.6 files.
recovery log
is thrown) For db.action of LEAVE, sets the
absolute path to the Version 8
stores and logs.
Container cache and log locations
name.cache.dir The location of the new If not specified, For a root container, the directory
container cache the 7.5 or 7.6 name is validated on the local host.
configured value is
name.log.dir The location of the container
used.
log
Encryption of files that contain passwords
name.boot.file. The clear-text password Optional. In a Domain Manager upgrade, also
password
used to encrypt generated encrypts the Directory Service boot
container.ini files, and the file, ds.xml.
DS boot file.
Central connection for a management routing node
name. URL for direct connection Required. Only for containers that host a broker
central.connection.
to the management node in a management routing node that
url
will connect to the management node
over DRA.
name. Username for direct Required. For more about central connections,
central.connection.
connection to the see Setting Up Central
username
management node Connections in the Progress
SonicMQ Deployment Guide, and
name. Password for direct Required if Configuring Containers in the
central.connection.
connection to the MgmtBroker is Progress SonicMQ Configuration
password
management node security enabled. and Management Guide.

Property for
name. Timeout per request on this Optional.
central.connection.
connection, defaults to
request.timeout
30000 ms
name. Timeout for the initial Optional.

central.connection.
connection, defaults to
connect.timeout
10000 ms
name. Defaults to 0. Settable on a Optional.

central.connection.
management connection
socket.connect.
timeout
name. Defaults to true Optional.

central.connection.
load.balancing
name. Comma separated Required for root These properties are prefixed by
central.connection.
property=value pairs. containers for CentralConnection and are set in the
system.properties
System properties to be set support of JVM arguments attribute of the
when the central connection properties such as container configuration. The upgrade
is used. SSL connection will set these properties in the
properties. container configuration, and the
container.ini file for the container
will contain this information.
Set up as a Windows Service
name. The name of the Windows Required to install If a windows service by that name
windows.service.
Service to install for this a Windows existed before, it is removed and this
name
container Service to start the Windows Service is installed.
container. If not
given, no windows
service will be
installed.

Property for
Directory Service Location (Domain Manager upgrades only)
name.host.directory The location of the Optional. For DS locations outside the default
Directory Service store. location. When not specified, the
In fault-tolerant default location is usedthe
management frameworks, container directory of the Domain
applies to the Primary DS as Manager in the 8.5 installation.
well as the Backup DS on Might also require specifying the
their local hosts. Domain Managers name.previous.
working.directory.
After extracting an upgrade.properties file on a system, edit the file to specify the
required changes to add and modify properties, and to add other containers and their
properties.
Note You could choose to extract and upgrade multiple containers on a host in a series of
extractions and migrations. If you choose to do that, you might want to rename the
extracted files to note their container name, and then use that name in the run. For
example, upgrade.properties.ct01 and then run upgrade upgrade.properties.ct01.

Zero-Downtime Upgrades of 7.5 and 7.6 Clusters and

Replicated Brokers
In version 7, upgrades could not be applied to a running cluster or replicated brokers. You
had to stop all the brokers, then upgrade them as a unit. For clustered brokers, it meant
that the entire node was out briefly, all the configurations were forced to upgrade, and that
the node did not return to full force until all the member broker installations had been
upgraded. For replicated brokers, it meant that the peers were both offline until they were
both upgraded.
In version 8, the Launcher installed on every system that runs components in the domain
means that administrators will never have to run upgrade software on each system ever
again. The Domain Manager is where the upgrade takes place. Then, the Domain
Manager provisions the remote systems with the upgraded software.
The transition from version 7 to version 8 does require installation of the 8.5 Launcher on
each system to establish participation in the new paradigm. And it does require running
some scripted tasks to complete the change for each container, hosted component, and
data store.
Sonic 8.5 simplifies the upgrade of clusters and replicated brokers by enabling a Sonic 8.5
domain to tolerate both version 7 and version 8 brokers cooperating in different versions.
You install a Launcher on a system where a broker member is running, extract its
configuration from the domain, and then run a smart upgrade that stops the version 7
broker at the moment when it needs perform database actions, and then restarts the broker
as a 8.5 container. That provides administrators with a resilient non-stop topology that can
be fully upgraded from version 7 to 8.5 at a more measured pace. You dont have to have
administrators all dispersed at systems that host participating cluster members or
replicated peers, trying to orchestrate a simultaneous upgrade event.
The upgrade functions on distributed hosts require that the Domain Manager has been
upgraded to 8.5. Administrative tools must also be Version 8 to monitor the Domain but
have no actual role in the upgrade process.
The upgrade process first connects to the 8.5 Domain Manager to extract the 7.5 or 7.6
configuration, and then to upgrade the configuration and provision the 8.5 installation
location with the appropriate 8.5 functionality.

Upgrading a Cluster of Brokers

A cluster is a configuration object that enables multiple brokers in a domain to act as a
single node, providing load balancing andthrough sophisticated interbroker
connectionsto provide clusterwide messaging functions. The following illustration
shows three brokers in a cluster.
The upgrade tasks are the same for any non Domain Manager installation (as described
Sequence of 7.5 and 7.6 to 8.5 Component Upgrade Tasks on page 196). The flow
through the cluster members is the point of interest.
To upgrade a Version 7 cluster and its members to Version 8:

1. In the Sonic Management Console, review the cluster to see that the member brokers
are running and performing as expected.
2. Choose a system that hosts a running cluster member to upgrade it.
3. Perform the upgrade tasks:
a. Install the Sonic 8.5 Container Launcher
b. Extract the brokers containers properties.
c. Enter the 8.5 SonicMQ license in the upgrade.properties file.
d. Specify the working directory if the Version 7 data store and log locations are
relative paths.
e. Run the upgrade.
When the broker comes back online, that broker is Version 8 and the cluster is Version
8, while the other members are still Version 7. Do not use any features introduced in
Version 8 until all the cluster members have been upgraded.
4. Access, in turn, the system of each of the cluster members that are Version 7, and then
perform the upgrade tasks.
When all the members have been upgraded, the cluster is fully upgraded, and can perform
Version 8 functions.

Upgrading Replicated (Fault Tolerant) Broker Pairs

While a standalone broker can be licensed for fault tolerance and enable fault tolerant
client connections, fault tolerant broker pairs replicate data from the active member to the
standby, as illustrated.
As continuous availability is the obvious goal of this strategy, Sonic lets you upgrade the
peers hotafter you upgrade one, it synchronizes with the other even though their
versions do not match, and then stands alone until the other peer resumes after its upgrade.
To upgrade 7.5 or 7.6 fault tolerant replicated brokers to 8.5:

1. In the Sonic Management Console, review the broker peers to see they are performing
as expectedboth running, one in the ACTIVE role and the other in the STANDBY role.
2. Confirm that the primary broker has the STANDBY role. If not, force failover by
restarting the primary brokers container.
3. On the primary brokers system, perform the broker upgrade tasks:
c. Enter the 8.5 SonicMQ CAA license in the upgrade.properties file.
d. Specify the working directory if the Version 7 data store and log locations are
relative paths.
e. Run the upgrade. When the 7.5 or 7.6 broker is stopped, the backup broker is
STANDALONE. When the upgrade logic brings the broker up in 8.5, it passes through
STANDBY_SYNC and then takes the STANDBY role. The backup resumes the ACTIVE
role.
The upgrade forced upgrade of backup broker. The primary brokers installation is
8.5, while its backup is version 7. Do not use any features introduced in 8.5 until all
the cluster members have been upgraded.

4. Broker logs both provide Pre-8.5 comments until the other peer is upgraded.
5. At the location of the backup peer, confirm that the primary broker still has the
STANDBY role. If not, force failover by restarting the primary brokers container.
6. On the backup brokers system, perform the broker upgrade tasks:

c. Specify the working directory if it is not the default MQ7.n root.
d. Run the upgrade. When the 7.5 or 7.6 broker is stopped, the primary broker is
STANDALONE. When the upgrade logic brings the broker up in 8.5, it passes through
STANDBY_SYNC and then takes the STANDBY role. The primary takes the ACTIVE role.
When both peers have been upgraded, the replicated brokers are fully upgraded, and can
perform Version 8 functions.
Note Reverting to Version 7 In the unlikely circumstance that you are compelled to revert
to Version 7, the installations are still intact, anddespite having lost message traffic in
the interim the peers can return to the moment when the Version 7 backup broker
stopped. The procedure of setting the roles of the peers through the upgrade ensured that
the Version 7 backup would restart in the ACTIVE role, and the primary in the STANDBY role.
Upgrading a Cluster of Replicated Brokers

Adding the resilience of replicated broker pairs to cluster members enables a highly
scalable and continuously available messaging node. This configuration combines the
tactics for both clustered brokers and replicated brokers.

To upgrade a 7.5 or 7.6 cluster when its members are replicated brokers:
1. In the Sonic Management Console, review the broker peers in the cluster to see they
are performing as expectedboth running, one in the ACTIVE role and the other in the
STANDBY role.
2. Confirm that the primary broker has the STANDBY role. If not, force failover by
restarting the primary brokers container.
3. On that primary brokers system, perform the broker upgrade tasks described in
Upgrading Replicated (Fault Tolerant) Broker Pairs on page 208.
4. While it is preferred that you complete the upgrade of the upgraded brokers peer, if
it is more convenient, you could upgrade other primary brokers on their respective
systems as you progress through the all the participants in the cluster.
Once you have upgraded all the replicated broker pairs in the cluster, review their states
and their logs to be sure that all are upgraded and all are operative. The cluster of
replicated brokers can perform Version 8 functions.


Sonic 8.5 offers the same fault tolerant management framework functionality available in
7.6, yet transformed it to use the new container startup and file structures. In V7.5,
Progress Sonic introduced Directory Service Replication, enabling the complete Domain
Manager and Directory Service to be identical in two separate locations. This model
continues to be the strategy.
The following procedure describes upgrading a fully functional 7.5 or 7.6 fault tolerant
management framework to 8.5.
Important Handling of a DS store location outside the Sonic install directory When the
Directory Service store in 7.5 or 7.6 is in a directory outside of the Sonic install directory,
if the previous Directory Service storage directory and the new Directory Service storage
directory are identical, the primary and backup installations are handled as follows:
Primary Domain Manager The version 7 store will be upgraded in place. This case
makes it even more important to backup the store before starting its upgrade.
Backup Domain Manager As the completion of the upgrade of the backup is
intended to leave the backup without any DS store (so that the primary is forced to
create a new one and synchronize it), the existing version 7 DS store must be archived
and then the entire domain_name folder deleted so that the directory is empty. When
the container that hosts the backup DM starts, its DS store will be initialized by the
primary into the same directory that was used before the upgrade.

Upgrading a V7.5 or V7.6 Fault Tolerant Management Framework to 8.5

If you are using a V7.5 or V7.6 fault tolerant management framework topology, the
following steps prepare your management installation for the transition such that you can
rollback to the pre-upgrade topology while establishing the new one.
To prepare a V7.5 or V7.6 fault tolerant management framework for upgrade:

1. On the Manage tab of the Sonic Management Console connected to the domain to be
upgraded, expand the container that hosts the Domain Manager, right-click on
DIRECTORY SERVICE, and then choose Properties, as shown:
2. In the Edit Runtime Directory Service Properties dialog box,

select the Fault Tolerance tab.
3. Verify that you have a functioning topology:
One of the components has the Primary role and the other has the Backup role.
One of the components has the Active state and the other has the Standby state.
On the General tab, both containers indicate that they are Online.
The state of the Agent Manager in each container matches the state of its
Directory Service component.
4. If the component in the Primary role is not the one in the Active state, induce failover
by selecting the container hosting the DS in the Backup role, and then choosing
Operations > Restart. The Primary components assume the Active state.
5. Right-click on the Directory Service in the Primary role, and then choose
Operations > Perform Online Backup. Archive the Directory Service backup folder.
6. Stop the 7.5 or 7.6 Sonic Management Console.

With the fault tolerant management framework fully functional, and the Primary
components in the Active state, you can proceed with the upgrade.
To establish the 8.5 primary Domain Manager location:

1. Use the Sonic Installer to create a new installation location for a Domain Manager on
the same system as the 7.5 or 7.6 primary Domain Manager. (See Installing a
Domain Manager on page 87 for details.)
2. Enter your 8.5 SonicMQ Key. Enter other keys if you have them available.
3. On the Configure Domain Manager panel, select the Do not configure domain at this
4. Choose a Java VM.

To extract the properties of the primary Domain Manager:

2. Enter: upgradeProps -url broker -d domain -u user -p pwd /dm_container_path
where:
(typically, tcp://primaryDM_host:2506)
/dm_container_path is the DS location of the container that hosts the primary
Directory Service in the Version 7 domain
(typically, /Containers/DomainManager)
upgrade.properties.
To perform the upgrade of the primary Domain Manager:

2. Enter:
The primary Domain Manager components and stores are moved to the 8.5 location and
file structure, and then upgraded.
The upgrade proceeds to perform the upgrade, moving the version 7 components and
stores of the primary Domain Manager to the 8.5 installation location. When that step has

completed, the upgrade utility stops the version 7 primary and backup components, and
then immediately starts the 8.5 primary Domain Managerit takes the ACTIVE state.
The upgrade process on the backup Domain Managers system will first connect to the 8.5
primary Domain Managers broker to access the backups component properties in the
Directory Service.
To extract the properties of the backup Domain Manager:

1. Use the Sonic Installer to create a new installation location for a Domain Manager on
the same system as the version 7 backup Domain Manager. (See Installing a Domain
Manager on page 87 for details.)
2. On the Configure Domain Manager panel, select the Do not configure domain at this
3. Choose a Java VM.

6. Enter: upgradeProps -url broker -d domain -u user -p pwd /dm_container_path
where:
-url is a connection URL on the 8.5 primary management broker (typically,
tcp://primaryDM_host:2506)
-u is an administrative user in the domain (typically, Administrator)
/dm_container_path is the DS location of the container that hosts the backup
Directory Service in the 8.5 domain (typically,
/Containers/BackupDomainManagerBU)
upgrade.properties.

To perform the updgrade of the backup Domain Manager:

1. On the backup Domain Manager system, use the console window that is open at the
8.5_install_root/MQ8.5/bin location.
2. Enter:
The backup Domain Manager components and stores are moved to the 8.5 location
and file structure, and then upgraded.
3. Start the upgraded backup Domain Manager.
When the Directory Services finish synchronizing, the 8.5 Domain Manager is
running with the primary in ACTIVE state and the backup in STANDBY state.
4. Start the 8.5 Sonic Management Console, and connect to the upgraded Domain
Manager.
The upgrade of the fault tolerant management framework is complete.

A few other deployed components need additional handling to be upgraded.
Note Sonic Event Monitor -- In releases prior to 8.5, Sonic Event Monitor was a separately
licensed product. As of 8.5, that is no longer the case; a license key is not required for
creating, using or upgrading to a release 8.5 or newer Sonic Event Monitor 8.5.
Upgrading Activation Daemons

Upgrading the container that hosts an activation daemon and upgrading the containers that
the daemon can launch effectively upgrades a daemon instance.
If you use activation daemons in your deployments, note that upgrading an activation
daemons configuration (through the Sonic Management Console), its container, or any
object on the daemons activation list forces upgrade of the configuration of all the
containers in its activation list and any components that those containers host. If you
cannot manage the volume of changes that could follow from such a set of configuration
installations that require corresponding physical code installations on their respective host
systems, you might want to clear the activation list until the other objects get upgraded,
and then upgrade the daemon and reconstruct its activation list.

Upgrading Collections Monitors

Collections monitors are typically distributed to remote installation locations. When you
upgrade the container that hosts a collections monitor, it upgrades the collection monitor
configuration.
If you specified any location for the Collection Monitors storage other than the current
location, you must adjust that value in the updated configuration of the collections
monitor configuration in the Storage tab, as shown:
Upgrading Template Derived Objects

When you create templates for configurations, you can derive instances of the template
that will reflect parameter changes in the template. The set of objects that can be templates
are containers, brokers, clusters, activation daemons and loggers.
Whenever a template derived object is upgraded, the configuration of its template and the
configuration of all the other instances derived from the template are also upgraded.
Important When templated container configurations are upgraded, you must correspondingly
upgrade the physical installation locations where the containers run. Note the set of
instances that derive from the template at the time of the first upgraded templated
configuration, and then be sure to promptly update all their locations.


Perform the following tasks after an upgrade session to complete some of the minor
maintenance tasks that might be part of your deployment:
If you had links to SDKs or IDEs, see Updating Links to Tools & Integrated
Development Environments on page 217.
If you have special locations for certificates, see Updating Paths to Certificates for
the Upgraded Location on page 217.
If you use external security mechanisms, see Updating Paths to External Security
Resources on page 217.
If you had encrypted Domin Manager boot files, or want to do so now, see
Encrypting Domain Manager Boot Files on page 218.
If you need to recover space on a system where upgrades were performed, see
Resolving the Status of the Old Installation on page 218.
Updating Links to Tools & Integrated Development Environments

If your supporting tools used paths to tools such as Java SDKs or integrated development
environments and these referenced the Sonic installation location, you need to update
those references to point to the upgrade installation location.
Updating Paths to Certificates for the Upgraded Location

Unless you set up your certificate folders and files outside the installation directory, you
need to either move the certificates and folders into the upgraded installation structure or
retain the old installation structure as a repository for the certificates. The latter could be
the preferred solution if you specified absolute paths for certificate chains and client
authentication in a large set of SSL and HTPS acceptors on the broker. But if you do
choose to use the existing repository, you need to be careful to not delete the prior
versions installation directory.
Updating Paths to External Security Resources

If you are using external authentication SPIs and management SPIs and you stored them
in the structure of the installation, you need to move them to the upgraded installation
location, and then update their classpath statements in their configuration objects.

Encrypting Domain Manager Boot Files

The upgrade process created new Domain Manager boot filesds.xml and
container.inithat are unencrypted. If you want to encrypt them in the 8.5 installation,
see the corresponding procedures in the Encrypting the Directory Service and its Boot
Files section of the Configuring Framework Components chapter in the Progress
SonicMQ Configuration and Management Guide.
Resolving the Status of the Old Installation

You can retain the original installation if you think you might want to revert to it for any
reason. Unless you intend to point to resources in the old installation (such as certificates
as described in the previous item), you should prevent the old installation from being
started inadvertently. You could rename the bootfile by appending _beforeV8Upgrade to its
name or such.
Alternately, you could archive the installation directory, and then uninstall that version
and delete any residual files. You can still retrieve individual files that you might want
from the archive.
Deleting a Prior Installation After Upgrade

After you have completed an upgrade and you are sure you do not want to revert the
upgrade, you can delete the 7.5 or 7.6 installation but there are some considerations. There
are several functions that might have been maintained in the prior installations directory
structure and that could adversely impact the upgraded installation.
Important If any configurations on a system are not yet upgraded to 8.5, you need to maintain the
environment and scripts in the physical installation that will support those configurations.
It is good practice to archive the prior installations directory, purge the unused portions,
and then, when the upgraded installation is seen to operate correctly, delete the archive.

Checklist for determining the continuing use of a prior installations directory:

1. Did the upgrade choose to use the existing data store (the Leave option) in the prior
installation directory structure? [ ] Yes [ ] No
2. Did the upgrade choose to use the existing recovery logs (the Leave option) in the
prior installation directory structure? [ ] Yes [ ] No
3. Are there one or more added broker data stores that are in the prior installations
directory structure (instead of being moved to the upgraded installation location)?
[ ] Yes [ ] No
4. Were the certificate stores in the prior installation left in place, pointed to from the
upgraded installation location? [ ] Yes [ ] No
If you checked Yes on any of these items, then refrain from deleting any files.
Consult with Sonic technical support for tips and techniques that will provide the best
result.
Warning Enabling Roll Back of Upgrades Your ability to revert to using the installations from
prior versions is dependent on reinstating the configurations in the Directory Service.
Tactics to achieve this include:
Because an existing Directory Service installation (as well as its broker and
container) is unmodified during its upgrade, you can revert the entire domain to
its pre-upgrade image.
Consider doing an online backup of the Directory Service store immediately
after the Domain Manager has been upgraded so that all the distributed
containers and their components are in their pre-update configurations.
Consider blocking inadvertent startup of an inactive domain by, for example,
renaming its boot file from container.xml to container_76_INACTIVE.xml.


Chapter 9 Updating Sonic Installations
This chapter contains the following sections:

About Sonic Installer Updates
Downloading a Sonic Updater
Performing an Update on a Sonic Installer Location
Performing Updates on a Fault Tolerant Domain Manager
Progress Sonic Installation and Upgrade Guide 8.5

Chapter 9: Updating Sonic Installations
About Sonic Installer Updates

A Sonic installer update contains new features requested by customers and provides
resolution to critical defects (patches). Updates modify a specific version installation
directly, and do not impact version compatibilities. A Sonic product update does not
require a license key.
When designated as a service pack, the updater incorporates prior service packs for the
underlying version. Updating V8.5 to V8.5 SP2 will be equivalent to updating V8.5 to
V8.5 SP1 and then to V8.5 SP2.
Sonic product updates do not update Java or Eclipse distributions. They update Sonic
product files and libraries, Sonic Workbench Sonic plugins, and online help.
Updated installations can apply and use the new features in the update. Non-updated
installations cannot use those features, yet they can interact with information stored or
transferred by updated installations.
The technique of updates for various Sonic 8.5 installations will be as follows:
Originally installed by
Package Installation Type Technique for updating
Sonic Installer 8.5 Sonic Workbench Download and run Sonic Updater for
(download or media) the latest Sonic 8.5 Service Pack
SonicMQ Development
Sonic Domain
Sonic Administration
Tools
Sonic Container Launcher Installer 8.5 None. Container connections to a

(download or media) updated domain will have their
launcher updated, all management
containers updated, and all
components provisioned with updated
libraries.
Sonic C/C++/COM Client 8.5 (download) Download and unpack the products
8.5 .n package instead.
Sonic .NET Client 8.5 (download)
Sonic JCA Adapter 8.5 (download)


Sonic updaters will be available from the Progress Electronic Download Site, accessible
on the Web at http://www.progress.com/esd. You can browse through the offerings, but
to perform downloads, you must be registered. If you are not a member, and want to
download service packs, click the register link on the Web page.
When an appropriate download is available, and you choose to download it, unpack the
download archive into either a local temporary directory or a network accessible location
for reuse.
Accessing Java for the Updater

Unlike Sonic installers, Sonic updaters and patches generally do not include the
appropriate Java to run the updater itself. In most cases where the target is a 64-bit
Windows machine, reference a 32-bit Java runtime to run the updater.
Performing an Update on a Sonic Installer Location

The update procedure does not require any license keys yet does require acceptance of the
end user license agreement for the updated software.
To update a Sonic installation with an 8.5 Service Pack:

1. On a machine that has a Sonic 8.5 installation, confirm that an appropriate JVM is on
the path. (You might need to put it in the PATH of the system environment variables.)
2. For a Domain Manager updateSonic Workbench, SonicMQ Development, or
deployment Domain Managerconfirm that the Domain Manager is running.
3. For an update of any Sonic installation, stop administration tools and clients that are
using that installation.
4. Launch the updater:
On Windows, double-click on install.exe.
On UNIX or Linux, open a terminal window to the root of the unpacked updater
files and then enter:
. ./install.bin

Chapter 9: Updating Sonic Installations
5. In the updaters panels, read the Readme file, agree to the license, and then point the
updater to the Sonic installation location you want to update. The default location
under Windows is C:\Program Files\Progress\Sonic.
Note The updater determines the products and product features to be updated. You cannot
choose the products to update and you cannot change the installed features.
6. Enter the domain name, connection URLs, and credentials for the running Domain
Manager so that you can connect to it online to apply the update.
7. Click Install. The updater applies the service pack update.
8. Restart the Domain Managers container to apply the update to the Domain Manager.
9. Restart remote deployments that are managed by this Domain Manager installation to
provision each of them with the latest libraries.
Performing Updates on a Fault Tolerant Domain Manager

When your Domain Manager is fault tolerant management framework, you have two
installations to update. The procedure for the two updates will bring the active peer to be
active alone, update it and restart it. When the backup restarts, the Directory Service
updates the its libraries, and the fault-tolerance mechanisms resume replication.
The procedures in the Service Packs update bulletin will guide you through preparation
for these update tasks, updating the primary installation, and then confirming that the
updated configurations are operational.

Chapter 10 Uninstalling Progress Sonic Products
If you want to remove a Sonic installation from a system, stop the running components on
that system before starting the uninstall script.
Note The uninstaller might inform you that you need to reboot to complete the uninstall if any
files in the installation location are open in any application or editor. After reboot, the
installer will complete its deletions.
To uninstall Progress Sonic on Windows:

1. Back up any files you want to retain.
2. Choose one of the following:
Start > Programs > Progress > Sonic8.5 > Sonic Uninstaller.
In the sonic_install_root\Uninstall* directory, run the Uninstall*.exe.
For example:
C:\Program Files\Progress\Sonic\Uninstall_Sonicx\Uninstall_Sonicx.exe.
3. You can choose to save any remaining files and then clean up by deleting the
remaining files and folders.
To uninstall Sonic on UNIX or Linux:

1. Back up any files you want to retain.
2. In the sonic_install_root/Uninstall* directory, run the Uninstall* shell script.
3. You can choose to save any remaining files and then clean up by invoking rm -r

Chapter 10: Uninstalling Progress Sonic Products

Appendix A Characters in Progress Sonic Names
General Rules
Some rules that apply generally in naming components in Sonic are the following:
Names are case sensitive. For example, you can have two distinct users named
Administrator and administrator.
When a name includes spaces, references to that name in scripts or command lines
must be enclosed in double quotes (" ").
Restrictions in some names (such as, collections, components, containers, and
domains) might not be enforced at the time when the configuration name is created.
Character Sets
SonicMQ stores message data in Blob fields. Other field types used by SonicMQ include
char, varchar2, and long. SonicMQ is 100% Java, and Java completely supports Unicode.
It is important that each persistent storage mechanism must be installed and set up to use
the character set (code page) that is appropriate for the language used in the messaging
application.
Some persistent storage mechanism vendors let you choose character sets at install time
so that the selections exist for every persistent storage mechanism created under that
particular installation. For many persistent storage mechanisms, the character set chosen
when the persistent storage mechanism is created cannot be changed without re-creating
the persistent storage mechanism. Therefore the character set chosen should always be a
superset of the intended language or the equivalent of the messaging clients operating
systems native character set. Consult the vendors documentation for details on character
sets and national language support.

Appendix A: Characters in Progress Sonic Names
Naming Rules for Sonic Configuration Elements

Table 14 lists naming rules and allowed characters in Sonic configuration names. The
phrase alphanumeric characters, ASCII punctuation and symbols describes the
characters x0032 through x007E in ISO/IEC 646.
Table 14. Naming Rules and Allowed Characters in Sonic
Max
Configuration Name Size Allowed Characters and Special Use
Access Control Lists - All alphanumeric characters, ASCII punctuation and symbols are allowed
(ACLs) pattern except slash (/).
Note that asterisk (*) and pound sign (#) have wildcard meaning.
Broker - All alphanumeric characters, ASCII punctuation and symbols are allowed
(management or except double quote ("), pound (#), dollar sign ($), percent sign (%),
messaging) asterisk (*), period (.), slash (/), and backslash (\).
ClientID - All alphanumeric characters, ASCII punctuation and symbols are allowed
except pound (#), dollar sign ($), percent sign (%), asterisk (*), and
period (.).
Cluster - All alphanumeric characters, ASCII punctuation and symbols are allowed
except pound (#), dollar sign ($), percent sign (%), asterisk (*), period (.),
slash (/), and backslash (\).
Collection - All alphanumeric characters, ASCII punctuation and symbols are allowed
except percent sign (%), and slash (/).
Component - Only alphanumeric characters and space, underscore (_), and dash (-).
Configuration Folder - Only alphanumeric characters and underscore (_), dash (-), and
at sign (@).
ConnectID - All alphanumeric characters, ASCII punctuation and symbols are allowed
except pound (#), dollar sign ($), asterisk (*), period (.), and slash (/).
Container - Only alphanumeric characters and space, underscore (_), dash (-), and at
sign (@). The @ character is allowed in container names where the node
name is specified in containerName@nodeName format.
Domain - Only alphanumeric characters and space, underscore (_), and dash (-).

Naming Rules for Sonic Configuration Elements
Table 14. Naming Rules and Allowed Characters in Sonic (continued)
Max
Durable subscription - All alphanumeric characters, ASCII punctuation and symbols are allowed
except dollar sign ($), period (.), slash (/), and backslash (\).
Group of users - All alphanumeric characters, ASCII punctuation and symbols are allowed
(internal group) except pound (#), dollar sign ($), asterisk (*), period (.), slash (/), and
backslash (\).
Group of users - All alphanumeric characters, ASCII punctuation and symbols are allowed
(group map between except pound (#), dollar sign ($), asterisk (*), period (.), slash (/),
internal and external backslash (\), equal sign (=), and comma (,).
groups; group-name
generated using PASS
SPI)
Quality of Protection - All alphanumeric characters, ASCII punctuation and symbols are allowed
(QoP) pattern except slash (/).
Queue - All alphanumeric characters, ASCII punctuation and symbols are allowed
except backslash (\), and dollar sign ($).
Note that:
Asterisk (*) and pound sign (#) have wildcard meaning when
specifying ranges of queue names in subscription names and ACLs.
Adjacent colons (::) are reserved for delimiting sections of global
routing names.
Slash (/) is allowed in client applications to designate an HTTP(S)
protocol for a URL. The slash character should be avoided in
configurations; starting a queue name with http:// or https:// in a
configuration will result in a queue that applications cannot access.
Routing node 256 All alphanumeric characters, ASCII punctuation and symbols are allowed
except asterisk (*), pound (#), dollar sign ($), slash (/), backslash (\),
double colon (::), and double quote (") .

Appendix A: Characters in Progress Sonic Names
Table 14. Naming Rules and Allowed Characters in Sonic (continued)
Max
Topic 256 All alphanumeric characters, ASCII punctuation and symbols are allowed
except backslash (\) and dollar sign ($).
Note that:
Asterisk (*) and pound sign (#) have wildcard meaning.
Colon (:) is reserved for a remote topic name.
Adjacent colons (::) are reserved for delimiting sections of global
routing names.
Double brackets ([[ ]]) enclose a shared subscription identifier.
Names that begin the character string SonicMQ are reserved for
system use.
Slash (/) is allowed in client applications to designate an HTTP(S)
protocol for a URL. The slash character should be avoided in
configurations; starting a topic name with http:// or https:// in a
configuration will result in a topic that applications cannot access.
User - All alphanumeric characters, ASCII punctuation and symbols are allowed
(internal or external) except asterisk (*), pound (#), dollar sign ($), slash (/), and backslash (\).
Important Characters in installation location names The installer does not accept some
characters that, while acceptable as folder names on the target platform, can create
problems in evaluation of names in SonicMQ and the Sonic ESB product family.
The filtered characters are: ampersand (&), semicolon(;), caret (^), equal sign (=),
plus sign (+), comma (,), tilde (~), bang (!), at sign (@), pound (#), dollar sign ($),
percent (%), open/close parentheses (( )), open/close brackets ([ ]), and open/close
braces ({ }).
While spaces in names are not filtered, a good practice is to avoid spaces, using an
underscore (_) as a separator, such as my_folder/my_subfolder.
Uppercase and camelCase in names is valid but you can minimize potential issues on
disparate platforms by maintaining all names in lowercase.

Appendix B Troubleshooting Installations
The following tips and techniques can help you resolve some of the problems that might
come up, especially while you are doing installations and upgrades:
Accessing the Directory Service without connecting to the management broker
If you are attempting special functions such as upgrading a fault tolerant management
framework, or if you made a configuration error on the broker that provides
management connections for the Directory Service, you need to connect to the
Directory Service directly. The user Administrator can access the Directory Service
on the system where it is installed by opening the Sonic Management Console
(provided that the tool is installed on that system in the same directory as the Domain
Manager) and connecting to the explicit path of ds.xml instead of the brokers
protocol and host port. Where you would normally enter the connection URL as
tcp://this_host:2506, use
install_root/Containers/domain_name.domain_manager_container/ds.xml. For
example, using the default installation location under Windows, C:\Program
Files\Progress\Sonic\Containers\Domain1.DomainManager\ds.xml. (You might need
to use quotes when there are spaces in the location path name.)
When you connect to the Directory Service this way, the functions on the Manage tab
such as metrics, notifications, and operational actions are not available.
Also, note that you cannot connect directly to the DS this way if the management
broker is running and you cannot start the management broker when you are still
connected directly to the DS this way. When you have resolved the configuration
issues, disconnect from this direct way of accessing the DS and resume connection
through the management connection.
Note If the Directory Service boot file has been encrypted, enter its password in the
password parameter of the connection. However, if it is not encrypted and you
provide a password, you get an error about decrypting. If renamed from its default
name, the Directory Service boot filewhether encrypted or notmust have the
extension .xml in order for this command to succeed.
See Connecting Off Line in the Configuring Framework Components chapter of

the Progress SonicMQ Configuration and Management Guide.

Appendix B: Troubleshooting Installations
Completing creation of a backup broker Do the physical installation of the backup

broker and setup any special configuration for redundant networks for replication
connections as soon as possible. Neither the primary broker nor the backup broker
will start until each can locate its peer for Continuous Availability on the defined
replication connection.

Sonic Install

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Sonic Install

Uploaded by

Copyright:

Available Formats

PROGRESS

Installation and Upgrade Guide

Third Party Acknowledgements:

Chapter 1: Overview of Installations and Upgrades . . . . . . . . . . . . . . . . . . 25

Progress Sonic Installation and Upgrade Guide 8.5 11

Chapter 2: Using Progress Sonic Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Chapter 3: Using Progress Sonic Launcher Installer . . . . . . . . . . . . . . . .107

Chapter 4: Setting Up Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121

12 Progress Sonic Installation and Upgrade Guide 8.5

Running Setup Again for a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Chapter 5: Using Response Files with Installers. . . . . . . . . . . . . . . . . . . . . 135

Chapter 6: Upgrade Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Progress Sonic Installation and Upgrade Guide 8.5 13

Chapter 7: Upgrading Version 8 Domains and Tools . . . . . . . . . . . . . . . .173

Chapter 8: Upgrading from 7.5 or 7.6 to 8.5 . . . . . . . . . . . . . . . . . . . . . . . . . . .187

Chapter 9: Updating Sonic Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221

14 Progress Sonic Installation and Upgrade Guide 8.5

Chapter 10: Uninstalling Progress Sonic Products. . . . . . . . . . . . . . . . . . 225

Appendix A: Characters in Progress Sonic Names. . . . . . . . . . . . . . . . . . 227

Appendix B: Troubleshooting Installations . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Progress Sonic Installation and Upgrade Guide 8.5 15

16 Progress Sonic Installation and Upgrade Guide 8.5

This Preface contains the following sections:

Progress Sonic Installation and Upgrade Guide 8.5 17

About This Guide

18 Progress Sonic Installation and Upgrade Guide 8.5

Progress Sonic Installation and Upgrade Guide 8.5 19

Progress Sonic Documentation

20 Progress Sonic Installation and Upgrade Guide 8.5

Details each facet of the client functionality: connections, sessions, transactions,

Other SonicMQ Documentation

Progress Sonic Installation and Upgrade Guide 8.5 21

Sonic ESB Documentation

22 Progress Sonic Installation and Upgrade Guide 8.5

Progress Sonic ESB Deployment Guide Provides information about moving

Worldwide Technical Support

Progress Sonic Installation and Upgrade Guide 8.5 23

24 Progress Sonic Installation and Upgrade Guide 8.5

Progress Sonic Installation and Upgrade Guide 8.5 25

About Sonic Installation Maintenance

26 Progress Sonic Installation and Upgrade Guide 8.5

Types of Progress Sonic 8.5 Installations

SonicMQ Development Installs the SonicMQ development environment and the

Deployment Domain Manager Installs a runtime deployment domain.

Administration Tools Installs tools that configure and manage a domain.

Launcher Creates an environment to set up and launch management containers that

Whats a SonicMQ domain? A SonicMQ domain is an administrative grouping of

Progress Sonic Installation and Upgrade Guide 8.5 27

Installer Run Modes

28 Progress Sonic Installation and Upgrade Guide 8.5

About Centralized Installation

Function Before centralized installation With centralized installation

Progress Sonic Installation and Upgrade Guide 8.5 29

Container Launcher Installer

30 Progress Sonic Installation and Upgrade Guide 8.5

How Centralized Installation Works

machinezero machineone machinetwo

Progress Sonic Installation and Upgrade Guide 8.5 31

Host Manager Host Manager

machinezero machineone machinetwo

32 Progress Sonic Installation and Upgrade Guide 8.5

Host Manager Host Manager Host Manager

machinezero machineone machinetwo machinethree

Progress Sonic Installation and Upgrade Guide 8.5 33