Progress Sonic 8.5 Installation and Upgrade Guide - Product ...

® 

® 

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, ASPin-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

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 "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 

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 





(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS





================================================================ 


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 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT




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 Container’s 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 release’s Product 

Update Bulletin book to see what’s new and what’s 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 User’s 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 User’s 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 User’s Guide for Weblogic — 


Sonic Resource Adapter for JCA and using it with a Weblogic application server. 

● Progress SonicMQ 8.5 Resource Adapter for JCA User’s 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 Software’s 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 container’s 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 Manager—all 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 Installer—development 

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 machine’s launcher files and archives 

for deployed components. 

Update procedures are outlined in this chapter, and presented in detail in Chapter 9. 


Types of Progress Sonic 8.5 Installations 

Category Type 

Development 

Environments 

Deployment 

Environment 

The types of installations you can do with the Sonic installers are: 

Types of Progress Sonic 8.5 Installations 

Sonic Workbench — Installs the Sonic ESB development environment. 

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. 

Domain Manager — Installs a runtime deployment domain. 

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. 

What’s 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 Manager’s 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 installation—Domain 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: 

Mode 

Without 

response file 

parameter 

With 

response file 

parameter 

Graphical Supported. Not supported. 

Silent Not supported. Supported. 

Console Not supported. Not supported. 


About Centralized Installation 


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 

domain’s 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 

Setup 

Administration 

Tools Setup 

Distributed 

Components 

Required a sequence of installations 

on the Domain Manager system. 

Required a sequence of installations 

on each administrator’s system. 

Required a sequence of appropriate 

installations and license keys on each 

system. 

Activation Daemons Required a manual configuration task 

on remote system. 

Windows Services Required a manual configuration task 

on remote system. 

Initial Container 

Startup 

Data Isolation and 

Backup 

Sonic Deployment 

Manager 

All licensed products are installed in one 

process. 

All products are installed in one process 

with no license keys needed. 

Generic minimal installation creates a 

container that connects to the domain. 

No license key needed. 

Optional during initial container creation. 

Optional during initial container creation. 

Manual commandline action. Optional during initial container creation. 

Various folders within an installation. Each container maintains all its data in its 

own folder. Backing up the Containers 

folder backs up all user data. 

Ran on each distributed system from 

the model to install appropriate 

product features and configurations. 

Runs on the Domain Manager to define the 

configurations on logical hosts. The 

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 provisioned—and 

later, remotely upgraded—by 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 domain’s 

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 machine’s hostname and use it as the container name to 

configure in the domain’s Directory Service. 

With minimal technical expertise required to enable a machine and its role in a domain’s 

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 

Domain 

Manager 

Mgmt 

Broker 

Directory 

Service 

DomainManager 

Host Manager 

HOST 

MANAGER 

Container 

ctHmmachineone 

Host Manager 

HOST 

MANAGER 

Container 

ctHmmachinetwo 

machinezero machineone machinetwo 

When an administrator defines the containers for replicating brokers, the configurations 

can be pushed through a machine’s Host Manager to set up the container (as illustrated) 



Administration Client 

Tools Application 

and start the brokers. The new brokers will automatically initialize their store and start 

replication—without any additional actions at the remote systems. 

Domain 

Domain 

Manager 

Mgmt 

Broker 

Directory 

Service 

DomainManager 

Container 

ct1 

Container 

ct2 

Host Manager 

HOST 

MANAGER 

Container 


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 

then—by simply setting up and then launching the ‘lost’ broker’s container through the 

32 Progress Sonic Installation and Upgrade Guide 8.5 

Broker 

br1 

Host Manager 

HOST 

MANAGER 

Container 


Broker 

Backup 

br1 

machinezero machineone machinetwo




recovery machine’s Host Manager—recovers the broker and synchronizes with the peer 

that has been standing alone. 

Domain 

Domain 

Manager 

Mgmt 

Broker 

Directory 

Service 

DomainManager 

Broker 

br1 

Container 

ct1 

Host Manager 

HOST 

MANAGER 

Container 


Broker 

Backup 

br1 

Container 

ct2 

Host Manager 

HOST 

MANAGER 

Container 


machinezero machineone machinetwo 

Container 

ct1 

Sonic documentation provides a video demonstration of these steps across multiple hosts. 

Progress Sonic Installation and Upgrade Guide 8.5 33 

Broker 

br1 

Host Manager 

HOST 

MANAGER 

Container 

ctHmmachinethree 

machinethree


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 

Domain 

Manager 

Mgmt 

Broker 

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 Manager’s 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 

Domain 

Manager 

◆ 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. 

Mgmt 

Broker 

Directory 

Service 

DomainManager 

9. Choose to launch the container process. 

10. Click Next, and then click Install. 

Host Manager 

HOST MANAGER 

Container 

ctHmremoteHost 

The container’s 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 

Domain 

Manager 

Mgmt 

Broker 

Directory 

Service 

DomainManager 

Container 

ct1 

Host Manager 

HOST MANAGER 

Container 


◆ 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: 


Broker 

br1


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, and—because it is a new deployment—creates the tables in 

the broker’s 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 broker’s container gets 

replication underway. 

Domain 

Domain 

Manager 

Mgmt 

Broker 

Directory 

Service 

DomainManager 

◆ To create a backup broker to replicate the running broker for the example: 

1. In the Sonic Management Console’s 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: 

Container 

ct1 

Replication 

Connection (s) 

Container 

ct2 

Host Manager 

HOST MANAGER 

Container 

ctHM_RemoteHost 

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. 


Broker 

br1 

Broker 

Backup 

br1

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 system’s 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 

Domain 

Manager 

Mgmt 

Broker 

Directory 

Service 

DomainManager 

Broker 

br1 

Container 

ct1 

◆ 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: 

Broker 

Backup 

br1 

Container 

ct2 

Replication 

Connection (s) 


Container 

ct1 

Host Manager 

HOST MANAGER 

Container 




Container. 


Broker 

br1



container configuration that was lost—in 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 

broker’s data stores, and then completely recovered the continuous availability brokers 

with no loss of data, and—if the clients specified fault tolerant connections—no loss of 

session states. 


About Zero-Downtime Upgrades 

About Zero-Downtime Upgrades 

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: 


Client 2 

Application 

Tools 

Domain1 

DOMAIN MANAGER 

BROKER 

Messaging 

Broker 

Mgmt 

Broker 

D S 

A M 

CLUSTER OF BROKERS 

Node B 

The stages of a version upgrade are: 

Node A 

3 CLUSTER OF BROKERS 4 

Node C 

REPLICATED BROKERS 

Node D 

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. 


1 

CLUSTER OF REPLICATED BROKERS 

P B 

ACTIVE 

PRIMARY 

Messaging 

Broker 

Node C 

P B 

P B 

STANDBY 

BACKUP 

Messaging 

Broker 

6 

Node E 

5


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. 


About Dynamic Deployment of Upgrades and Patches 

About Dynamic Deployment of Upgrades and Patches 

Upgrades of Sonic 7.5 and 7.6 installations requires some tasks—installing a launcher and 

running an upgrade utility—on 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 Service’s 

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 

copy-files 

create-folder 

delete-files 

rename-folder 

rename-file 

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: 

where: 

copy-ds-files-to-container-caches 

|all-containers [exclude] 

modify-archive-search-path 

|all-containers [exclude] 

● 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 

Environment 

Deployment 

Environment 


Tools 

Launcher 

● Sonic Workbench ● Sonic Workbench 

● SonicMQ ● SonicMQ Professional Developer 

● SonicMQ 

● Sonic ESB CAA 

● SonicMQ Continuous Messaging 

● SonicMQ Messaging 

● Sonic ESB 

● Sonic ESB CAA 

● Sonic BPEL Server 

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 Sonic’s Dynamic Routing Architecture®. 

● Unlimited number of connections 

File Structure of a Progress Sonic Installation 

● 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 

container’s process, and the default location for the container’s 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 

Install Type 

Sonic 

Development: 

Workbench 

key 


Development: 

MQ key Sonic Domain 



Tools 


Container 

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 

(Dev edition) 

Key required No key required 

SDM8.5 No key required No key required No key required No key required 

Uninstall Y Y Y Y Y 

Upgrade 

(utilities for migration 

of earlier versions) 

Y Y Y 

Workbench 

(plus Eclipse) 

Key required 

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, and—on Windows—a 

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 platform’s 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: 

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 - 

xmlParserAPIs.jar; 

xercesImpl.jar 

Multipart messages: 

activation.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. 



Start Menu Commands (Windows) 

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: 


Start Menu Commands (Windows) 

● 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 installer—for example, not configuring the domain at installation, and then creating 

the domain through the Sonic Deployment Manager—or 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 

Manager 

SonicMQ Stop Domain 

Manager 

SonicMQ Management 

Console 

SonicMQ JMS Test 

Client 

Sonic ESB ESB Admin 

Tool 

Sonic ESB Deployment 

Export Tool 


Import Tool 


Workbench 

Start Sonic 

Workbench 

sonic_install_dir/Containers Domain1.DomainManager\launchcontainer.bat 

sonic_install_dir/Containers Domain1.DomainManager\shutdowncontainer.bat 

sonic_install_dir/MQ8.5 bin\startmc.bat 

sonic_install_dir/MQ8.5 bin\testClient.bat 

sonic_install_dir/ESB8.5 bin\esbadmin.bat 

sonic_install_dir/ESB8.5 bin\deployExport.bat 

sonic_install_dir/ESB8.5 bin\deployImport.bat 

sonic_install_dir/Workbench8.5/eclipse eclipse.exe --launcher.ini SonicLauncher.ini 

(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 

Manager 

SonicMQ Stop Domain 

Manager 

SonicMQ Management 

Console 

SonicMQ JMS Test 

Client 

Sonic ESB ESB Admin 

Tool 


Export Tool 


Import Tool 


Workbench 

Start Sonic 

Workbench 

sonic_install_dir/Containers . ./Domain1.DomainManager/launchcontainer.sh 

sonic_install_dir/Containers . ./Domain1.DomainManager/shutdowncontainer.sh 

sonic_install_dir/MQ8.5 . ./bin/startmc.sh 

sonic_install_dir/MQ8.5 . ./bin/testClient.sh 

sonic_install_dir/ESB8.5 . ./bin/esbadmin.sh 

sonic_install_dir/ESB8.5 . ./bin/deployExport.sh 

sonic_install_dir/ESB8.5 . ./bin/deployImport.sh 

sonic_install_dir/Workbench8.5 . ./startworkbench.sh 



Accessing Progress Sonic Documentation 

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 version’s 

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: 


Accessing Progress Sonic Documentation 

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 

Planning the Installation 

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 

Software 

Planning the Installation 

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 broker’s persistent store and recovery logs, each 

container’s cache, and the Directory Service store), do not use buffered disk writes or 

network drives in virtually all circumstances. Buffered disk writes (write caching) 

could—under an unanticipated power outage—corrupt data in the write cache before the 

data is written to disk. However, some sophisticated data storage systems (such as topend 

SCSI RAID arrays) provide reliable write caching that is suitable for use with Sonic. 

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 Workbench’s 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 container’s properties to force the JVM into 64bit 

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 

Workbench—the 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. 


Checklist Before Installing 


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. 



Using the Sonic Installer 

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 

Using the Sonic Installer 

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 machine’s 

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 machine’s 

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. 



Running the Sonic Installer 


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 

User’s 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. 




The Readme panel opens. 

2. Determine if you have required license keys and whether you want to access the 

documentation before proceeding. 



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 and—while embedded spaces are supported for this use 

in Progress Sonic—using 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 Installer’s 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 to“Installing 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. 


Installing Development Environments 


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 Installer’s 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 broker’s port value (between 1024 and 65536). 




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 Installer’s 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. 









system, and then click on you preferred 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. 





Creating a Runtime Infrastructure 

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 component’s 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 

administrator’s 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 domain’s 

Directory Service. You can choose to add an activation daemon and a host manager, 

and—on 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 Installer’s 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 7—see “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. 









system, and then click on your preferred 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 Installer’s 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 SDM’s 

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. 












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. 


Using the Administration Tools After Installation 


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 Broker’s 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 broker’s 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 container’s 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 broker’s 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 container’s 

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 Manager’s container, you cannot restart it. 



◆ To change the authentication credentials used by the Domain Manager’s 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 Manager’s container is running, its revised connection information 

updates the Domain Manager’s 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 

or“Configure 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 

broker’s 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 broker’s 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 broker’s 

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 broker’s 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 broker’s 

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 broker’s store on the local system, as follows: 

a. Copy the file db.ini from MQ8.5_install_root and paste it into the broker’s 

container folder, install_root\Containers\domainName.containerName 

b. Edit the file to indicate the locations of the broker’s 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 broker’s store on the local system, as follows: 

a. Copy the file db.ini from MQ8.5_install_root and paste it into the broker’s 

container folder, install_root\Containers\domainName.containerName 

b. Edit the file to indicate the locations of the broker’s 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 


Extending an Existing Installation 


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 

Install Type >> Workbench 

Sonic Products 

v 


Workbench 

Installation 

requires WB 

license key. 

SonicMQ Installation requires 

MQ license key. 

SonicMQ 

Development Domain Manager Admin Tools 

Installation requires 

MQ deployment 

license key. 

Sonic ESB Optional at 

installation. Can be 

added later. Requires 

ESB deployment 

license key. 

Sonic BPEL 

Server 

Sonic Database 

Service 

Optional at 


added later. Requires 

BPEL deployment 

license key. 

Always installed. 

Optional at 


added later 

Optional at 


added later 

The decision to extend an installation is specified on the Installer’s 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. 




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 domain’s 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 container’s 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, and—if the management broker is security enabled—you 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. 


◆ To start the Installer wizard on UNIX: 

Starting the Sonic Container Launcher Installer 

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 machine’s 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 machine’s 

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. 













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 appropriate—in 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 Path—the container path and container name within the 

domain’s 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 container’s 

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 domain’s 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 container’s 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 Container’s 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 

About the Sonic Launcher and Setup 

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 

A 

Sonic Management Console 

C' 

A' 

Launcher Installation 

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. 


B 

B' 

C

The key concepts presented are: 


● The Domain1 folder (A) on the Domain Manager system is the store of the domain’s 

Directory Service. The container’s 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 Launcher’s installation location. 

● Each container has a launch script (C) to connect to the domain where its 

configuration can be updated, the container’s 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 to—if the option to 

CREATE_IF_DOES_NOT_EXIST is selected—add the new container configuration into the 

Directory Service, and then to note the host system. 

Domain Manager System Distributed System 



4 


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. 


1 

2 

CREATE_IF_DOES_NOT_EXIST=true 

3


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. 




1 


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. 


2 

3


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: 




1 


Figure 5. (1) Configure Container, (2) Generate Setup File, (3) Run Setup 

2 

In a Sonic Launcher installation on the remote system, use the setup utility with the 

.setup file to set up the container. 


3


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, and—if the parameter to 

CREATE_IF_DOES_NOT_EXIST=true is in the setup file—will insert the new container 

configuration into the Directory Service. 

Domain Manager System Distributed System 



4 


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

2 


3 


1 

Text Editor


Properties in a Setup File 

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 


Connection 

Properties 

Container 

Properties 

DOMAIN_NAME The domain that will manage the 

configuration 

ConnectionURLs List of connection URLs for 

brokers in the management node. 

CONTAINER_PATH Directory Service folder path 

(starting with /) and the name of the 

container. 

CREATE_IF_DOES_NOT_EXIST When true, creates the container 

configuration in the domain’s 

Directory Service. 

LOG_FILE Defaults to a relative location in the 

container’s working directory. 

Required when it is located 

elsewhere. 

Table 5. Optional and Special Use Container Setup Properties 

Domain1 

tcp://localhost:2506 

/Containers/hostname 

false 

./{DOMAIN_NAME}. 

{CONTAINER_NAME}.log 


Additional 

Components in 

the Container 

ACTIVATION_DAEMON_PATH Adding the property with a Directory 

Service folder path creates the 

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 

Setup 

Optional 

Container 

Properties 

WINDOWS_SERVICE_NAME Adding the property with a service 

name creates the service. 

WS_TIMEOUT Elapsed time (in seconds) to wait for 

the Windows Service to start. 

WS_AUTOSTART_OPTION Set to -a to set the Windows Service 

to AutoStart 

CONNECT_TIMEOUT Elapsed time (in seconds) to wait for 

connection to the management broker. 

Properties in a Setup File 


Special Use: 

Management 

Routing over 

DRA 

Java System 

Properties 

REQUEST_TIMEOUT Maximum time (in seconds) for 

roundtrip management requests. 

LoadBalancing Selects load balancing for container 

connections to the management node. 

SOCKET_CONNECT_TIMEOUT Elapsed time (in seconds) to wait for 

individual socket connect attempts. 

MANAGEMENT_NODE Name of the management node when 

using management routing nodes. 

CENTRAL_CONNECTION Enables the parameters and 

functionality when the container is 

hosting a broker that is doing the 

routing for a management routing 

node. 

SystemProperty 

.property_name 

When the container launches, the one 

or more specified system properties 

will be passed to the JVM. 

For example: 

SystemProperty. 

java.protocol.handler.pkgs 

=progress.message.net 

Sonic CONTAINER_NAME 

Service 


360 

-a 

10 

30 

true 

0 

false


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, or—if it 

is in the file—it is set to false. 

4. Add additional properties as appropriate. 


5. Save the file without changing its name. 

Running the Container Setup Utility 

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

Launcher installation is available. 

Running the Container Setup Utility 

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 container’s 

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 user’s 

credentials in the management broker’s 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 container’s 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 installation’s Launcher directory. 

2. Change to the appropriate version’s 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 installation’s Launcher directory. 



2. Change to the appropriate version’s 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 container’s 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 Container’s 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 Container’s 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 container’s winservice script: 

1. Open a console window in a container’s working directory. 

2. Enter winservice and one of the following parameters: 

■ /install 

■ /start 

■ /wait_for_stop 

■ /stop 

■ /remove 

The requested Windows Service action occurs. 


Shutting Down a Container 

Shutting Down a Container 

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 installer’s 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. 


Sonic Installer Parameters and Procedures 


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 installer’s 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 root—such 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 


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 

Agreement 


Location 

ACCEPT_LICENSE_AGREEMENT Required, set to 

true 

INSTALL_TYPE new or 

existing. 

INSTALL_LOCATION Required. 

Explicit path 


true 

new 

Windows: 

Install Set USER_CHOSEN_INSTALL_SET Required. development 

Progress Sonic 

License Keys 

C:\\Program Files\\Progress\\Sonic 

UNIX/Linux: /usr/opt/Progress/Sonic 

DEV_KEY Required. A Sonic Workbench 8.5 key includes 

development/evaluation licenses for 

SonicMQ, Sonic ESB, and Sonic BPEL 

Server 

DEV_OPTION Information 

only. 

esb


Table 6. Response file parameters used in the Sonic Installer for Sonic Workbench (continued) 




Development 

Configuration 

Directory Service 

Authentication 

CONFIGURE_DOMAIN true or false true 

DOMAIN_NAME Required. Domain1 

CONTAINER_NAME Required. DomainManager 

BROKER_NAME Required. MgmtBroker 

MGMT_BROKER_PORT Required. 2506 

ENABLE_SECURITY true or false true 

SECURITY_USER_NAME Required. Administrator 

SECURITY_PASSWORD Required. Administrator 

Choose Eclipse CHOSEN_ECLIPSE_HOME Windows:install_location\\Workbench8.5\\eclipse 

Choose Java 

Virtual Machine 

Shortcuts 

(Workbench on 

Windows only) 

UNIX/Linux:install_location/Workbench8.5/eclipse 

CHOSEN_JVM_HOME Windows:install_location\\jre 

UNIX/Linux:install_location/jre 

DESKTOP_SHORTCUT true or false false 

QUICK_LAUNCH_SHORTCUT true or false false 


◆ 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 



CONTAINER_NAME=DomainM


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 



License 

Agreement 


Location 


true 


existing. 


Explicit path 


true 

new 

Windows: 


UNIX/Linux: 

Install Set USER_CHOSEN_INSTALL_SET Required. development 


License Keys 

Configure 


DEV_KEY Requires a 

SonicMQ 8.5 

key 

DEV_OPTION Information 

only. 


DOMAIN_NAME Domain1 

/usr/opt/Progress/Sonic 

CONTAINER_NAME DomainManager 

BROKER_NAME MgmtBroker 

MGMT_BROKER_PORT 2506 

ENABLE_SECURITY true or false false 

- 

mq

◆ To edit a response file to install SonicMQ Developer Install: 


Table 7. Response file parameters used in the Sonic Installer for SonicMQ Developer 





Choose Java 


SECURITY_USER_NAME Required when 

security is 

enabled 

1. Use a captured response file from a SonicMQ Developer install, or copy Code 

Sample 3. 

2. Enter your SonicMQ 8.5 development or evaluation license key as the DEV_KEY value. 

3. As appropriate, adjust the locations. 

Administrator 

SECURITY_PASSWORD Administrator 

CHOSEN_JVM_HOME Windows:install_location\\jre 

Code Sample 3. Response File parameters for Installing SonicMQ Developer 




USER_CHOSEN_INSTALL_SET=development 

DEV_KEY=*************** 

# DEV_OPTION=mq 






ENABLE_SECURITY=false 


4. Save the file as a text file. 

For example, c:\MQ8.5_Windows.rsp or /opt/user/MQ8.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:\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 



License 

Agreement 


Location 


true 


existing. 


Explicit path 


true 

new 

Windows: 


UNIX/Linux: 


Install Set USER_CHOSEN_INSTALL_SET Required. domainmanager 


License Keys 

MQ_KEY Required. - 

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. 

- 

-

Configure 





DOMAIN_NAME Domain1 

CONTAINER_NAME DomainManager 

BROKER_NAME MgmtBroker 

MGMT_BROKER_PORT 2506 

ENABLE_SECURITY true or false false 


security is 

enabled 


Table 8. Response file parameters used in the Sonic Installer for Domain Manager (continued) 



Choose Java 


Adding products 

to a Domain 

Manager 

Administrator 

SECURITY_PASSWORD Administrator 

CHOSEN_JVM_HOME install_location/jre (Windows) 

REGISTER_ONLINE true or false false 

DS_DOMAIN - 

MANAGEMENT_CONNECTION_URL - 


management 

node is security 

enabled. 

SECURITY_USER_PASSWORD - 


-


◆ 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 




MQ_KEY=*********** 

ESB_KEY= 

BPEL_KEY= 

USER_CHOSEN_INSTALL_SET=domainmanager 







SECURITY_USER_NAME=Administrator 

SECURITY_PASSWORD=Administrator 


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 



License 

Agreement 


Location 


true 


existing. 


Explicit path 

◆ 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. 

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. 


true 

new 

Windows: 


UNIX/Linux: 

Install Set USER_CHOSEN_INSTALL_SET Required. admintools 


License Keys 

Choose Java 


INSTALL_ESB_TOOLS 1 (true) 

0 (false) 

INSTALL_BPEL_TOOLS 


0 (false) 

CHOSEN_JVM_HOME install_location/MQ8.5/jre (Windows) 

Code Sample 5. Response File parameters for Installing Admin Tools 




USER_CHOSEN_INSTALL_SET=admintools 

INSTALL_ESB_TOOLS=1 

INSTALL_BPEL_TOOLS=1 

CHOSEN_JVM_HOME=c:\\Program Files\\Progress\\Sonic\\jre



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 


Sonic Updater Parameters and Procedures 


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 


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 



License 

Agreement 

Choose Install 

Folder 

Update 

Directory 

Service 

ACCEPT_LICENSE_AGREEMENT Required, set to true true 

INSTALL_LOCATION Explicit path for the update. Windows: 

UPDATE_DS Choose to not update the 

Directory Service, usually 

because the Sonic Deploymemt 

Manager will update the DS later. 

Values are false or true. 

C:\\Program 

Files\\Progress\\Sonic 

UNIX/Linux: 


false 


Table 10. Response File parameters for the Sonic Updater (continued) 

Editing a Response File for an Update 

◆ To edit a response file to update a Sonic 8.5 installation: 

1. Copy Code Sample 7. 




Domain 

Manager 

Connection 

Properties 

DOMAIN_NAME Name of the domain that will be 

updated. 

MANAGEMENT_CONNECTION_URL When the Domain Manager is 

running, the URL for connection 

to the domain’s management 

broker. 

When the Domain Manager is not 

running, the explicit path to the 

DS boot file, ds.xml. 

Domain1 


Code Sample 7. Response File for Updating a Sonic Installation where DM is online 


#------------------------ 


#Sonic Install Location 

#----------------------- 


#Sonic Directory Service Update 

#------------------------------#--------------------------------- 

UPDATE_DS=true 


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 



Sonic Container Launcher Parameters and Procedures 

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 system’s hostname should—in most 

enterprise structures—define 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 



License 

Agreement 

Choose Install 

Folder 

Java Virtual 

Machine 

Configure 

Container 

ACCEPT_LICENSE_AGREEMENT Required, set to true true 

INSTALL_LOCATION Explicit path for the 

installation 

CHOSEN_JVM_HOME Path to the JVM directory 

chosen by user. 

CREATE_CONTAINER_CONFIG Elects to create a 

container configuration 

during this installation 

procedure. Value is true 

or false 

Windows: 

C:\\Program 

Files\\Progress\\SonicLauncher 

UNIX/Linux: 

/usr/opt/Progress/SonicLaunche 

r 

C:\\Program 

Files\\Progress\\SonicLauncher 

\\jre 


true


Table 11. Response File parameters for the Sonic Container Launcher (continued) 



Domain 

Manager 

Connection 

Properties 

DOMAIN_NAME Name of the domain that 

will manage the 


CONNECTION_URLS The URL for connection 

to the configuration’s 

domain. 

SECURITY_USER_NAME The administrative user 

for connection to the 

configuration’s domain. 

SECURITY_PASSWORD The administrative user’s 

password for 

authentication in the 

configuration’s domain. 

Domain1 


Administrator 

75752F2B3E1A1011311A7B2B387D1F 

293C1A1F19 

("Administrator" encrypted) 






Container 

Configuration 

Properties 

CONTAINER_NAME Name of the container to 

configure 

CONTAINER_PATH Path for the configured 

container in the Directory 

Service. 

CONFIGURE_CONTAINER Create the container 

configuration in the 

Directory Service? Value 

is true or false. 

ACTIVATION_DAEMON_PATH Path for the activation 

daemon in the domain’s 


ACTIVATION_DAEMON_ENABLED Create the specified 

activation daemon object 

and host it in this 

container? 

Value is true or false. 

HOST_MANAGER_PATH Path of host manager in 

the domain’s Directory 

Service. 

HOST_MANAGER_ENABLED Create the specified host 

manager object? Value is 

true or false. 

WINDOWS_SERVICE_NAME Name for the Windows 

Service 

INI_ENCRYPT_PASSWORD Password that encrypts 

this container’s bootfile 

hostname 

/Containers/hostname 

false 

/Framework Components 

/AD_hostname 

false 

/Framework Components 

/HOST MANAGER 

false 

Sonic{hostname}Service 


-





Launch 

Container 

Process 

WINDOWS_SERVICE_ENABLED Create the specified 

Windows Service? Value 


LAUNCH_CONTAINER Elects to start the defined 

configuration after 

installation completes 

successfully, and—if 

chosen—insert its 

configuration into the 

specified domain’s 

Directory Service. Value 


false 


true


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 


CONNECTION_URLS=tcp://localhost:2506 

SECURITY_USER_NAME=Administrator 


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. 

3. As appropriate, adjust the locations. 


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 host’s 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 Manager’s 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 

#------------------------------------ 


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 example’s 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 

installations—Sonic Workbench, SonicMQ Development, and Sonic Domain features. 

No earlier license keys are valid in the 8.5 installation and upgrade process. 


Software 

Preparing for Upgrades to Development Environments 

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 system’s disk space is at a premium or if you have very large databases, consider the 

disk impact of alternative tactics—copy, move, or leave—for upgrade of a broker’s 

datastore and logs, as described in the upgrade properties 

Preparing for Upgrades to Development Environments 

As Sonic Workbench and SonicMQ development environments are typically monolithic 

structures—a Domain Manager where the management broker also handles the 

messaging traffic of the development applications—an 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 version’s 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 version’s Sonic Configuration and 

Management Guide. 

Once you create older configuration objects and a container boot file, use that version’s 

installer on the system that will host the physical installation but do not attempt to update 

the Directory Service. Instead, replace the new installation’s 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 


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 


Distributed Systems Supported in the Domain 

Distributed Systems Supported in the Domain 

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 Manager—they 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 

API’s 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 Sonic’s 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 



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 Sonic’s 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 

Version 

Compatibility of Components with Management Containers 

Components—such as brokers and ESB Containers—must 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 


Broker Supported? 


7.5.0 through 8.5 8.5 Yes 


Generally, SonicMQ Java clients that are a few versions behind the current version are 

supported by a current version’s broker. An older supported client is limited to its 

version’s client functionality. However, 8.5 clients are not supported by any earlier 

version’s brokers. 

You should plan to upgrade clients after upgrading messaging brokers. Clients that use 

client-side persistence should force a client’s 8.5 persistent store to be flushed before 



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: 


● “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 

Manager—Sonic Workbench, SonicMQ Development, or deployment primary Sonic 

Domain Manager—that is at 8.0 or higher. The Domain Manager must be running. The 

upgrade will be interspersed into the existing installation directory, with new versionidentified 

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 

Domain Manager: 

● Sonic Workbench 

● SonicMQ Development 

● deployment Domain Managers 


Type 


utilities 


process 

The appropriate Sonic Installer 

installation type, but choosing to not 

configure the Domain Manager. 

Located in the installation’s 

MQ8.5/bin directory 

Migrates the 8.0 Domain Manager’s 

container, Directory Service, and 

management broker to the 8.5 

installation location. 

Management containers that have a 

Launcher installation and are 

managed in the Version 8 domain 

that will be upgraded. 

No action required. 


Upgrading a Sonic Workbench 8.5 Evaluation License 

Upgrading a Sonic Workbench 8.5 Evaluation License 

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 

where: 

-d domain -c newLicenseKey -ds path-to-ds.xml 

■ 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 username’s password 

■ domain is the domain of the installation 

■ newLicenseKey is the new license key 

■ path-to-ds.xml is the absolute location of the domain’s 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. 



Phases of Upgrades from Sonic 8.0 to Sonic 8.5 

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 installation—the 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 What’s 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 Manager’s Properties” on page 179 

3. When appropriate, “Unencrypting Domain Manager Boot Files” on page 180 

4. “Editing an 8.0 Domain Manager’s 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 Workbench’s Eclipse environment. 

2. Stop the Workbench’s 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 Manager’s 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 Manager’s 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 Manager’s Properties” on page 179 


Extracting the 8.0 Domain Manager’s 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 Service—the 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 user’s 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 

Manager’s 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 relevant—the 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 Manager’s boot files: 

1. Open a command prompt in the Domain Manager’s 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 Manager’s upgrade.properties file 

An 8.0 Domain Manager’s 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 broker’s 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 Manager’s encrypted boot files: 

1. Open a command prompt in the Domain Manager’s 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 container’s 8.5 configuration 

■ The 8.5 archives required for the components hosted in that container 

■ The resources that advance the remote locations’s 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: 


● “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 

Domain Manager: 



● deployment Domain Managers 


Type 


utilities 


process 

The appropriate Sonic Installer 

installation type, but choosing to not 

configure the Domain Manager. 


MQ8.5/bin directory 

Migrates the 7.5 or 7.6 Domain 

Manager’s container, Directory 

Service, and management broker to 

the 8.5 installation location. 

Management containers that do not 

host a Domain Manager, and that 

are root containers—a container 

that is started by a script or a 

windows service on a host, not by an 

activation daemon. 

A Sonic Container Launcher 

installation with no container 

defined. 


Upgrade directory 

Migrates 7.5 and 7.6 containers and 

their hosted components to the 

installation’s Containers directory, 

and then update the version in the 

8.5 Directory Service. 


Phases of Upgrades from 7.5 and 7.6 to Sonic 8.5 


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 installation—the 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 


Sequence 

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: 

Installation Type 


Container 

Launcher Option 

Domain Managers Sonic Workbench ● Choose to not configure the 

SonicMQ 

Development 


Admin Tools Administration Tools 

Brokers Every non-DM 

system that 

Clusters 

has 7.5 or 7.6 

Replicated Brokers 

containers and 

components 

Clusters of 


ESB Services 

Domain during the 

installation. 

● Enter all 8.5 license keys 

Choose to not configure a 

container during the installation. 

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: 



● Deployment Domain Manager 

Note If your deployment Domain Manager is a fault-tolerant management framework, go 

directly to“Upgrading 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 Workbench’s Eclipse environment. 

2. Stop the Workbench’s 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 Manager’s 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 Manager’s 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 Service—the 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 

Manager’s 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 Manager’s upgrade.properties file 

A Domain Manager’s 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 broker’s 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. 

Important Use forward slashes '/' in path values on Windows. For instance, c:/Sonic/MQ7.0/ct01.xml. 

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 broker’s 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 



script—if used without modifications—fixed every container’s working directory at 

the installation’s 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 installation’s Containers 

directory that contains the configuration file and the launch script for the container as 

well as the container’s cache and log, and the broker’s 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 installation’s 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. 

● What’s running, what’s not running — The 8.5 Domain Manager should be running 

during all upgrades of container-based components. A broker’s 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 installation’s 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 domain’s 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 broker’s 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 node’s 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 

Important Use forward slashes '/' in path values on Windows. For instance, c:/Sonic/MQ8.5/ct01.xml. 

The tables of upgrade properties are distinguished as general properties and containerspecific 

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 Launcher’s 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 

Tool Connection properties 

false (default) 

ds.url For connection URL, 

the host:port (assumes TCP) 

For direct connection, 

the explicit path of ds.xml 

ds.username Administrative username Required. 

ds.password Administrative user’s 

password 

ds.domain Name of the domain. 

For example, Domain1. 

No. When set to true, the upgrade tool 

prints extensive diagnostic messages. 

Reserve this property for debugging. 

Required. Establishes management connection 

for configuration upgrades. 

Required if 

MgmtBroker is 


Required. 

connection_node Routing node name Required when 

connection over 

DRA. The 

management 

node must be 

running. 

request.timeout Time, in seconds, that the 

upgrade process will wait 

for a connection to the 

Domain Manager. 

connection.system. 

properties 

Any system properties that 

need to be set for 

management. 

Optional. Default value is 60 (seconds). 

Optional. For example, SSL properties. 


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


Control Numbers (License Keys) 

sonic.mq. 

controlNumber 

sonic.esb. 

controlNumber 

Container lists 

SonicMQ 8.5 Broker license 

key 


Required when a 

container being 

upgraded hosts a 

broker. 

Sonic ESB 8.5 license key Required when a 

container being 

upgraded hosts 

an ESB 

container. 

root.list A comma-delimited list of 

containers on the local host 

that will be setup in the 8.5 

location. 

upgrade.list A comma-delimited list of 

containers on the local host 

that need to be upgraded. 

Enables the migration tool to load 

plugins and ESB archive files into 

the Directory Service. 

Required. The configuration dependencies of 

each container are extracted, and 

those configurations are setup. 

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. 

Required. The configuration dependencies of 

each container are extracted, and 

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 

non-container templates that 

need to be upgraded. 

As generated. Do not modify this file. 

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. 

previous.working. 

directory 

The working directory of the 

management container 

before the migration 

Broker data store and recovery logs 

name.db.action Determines how to handle 

the broker database and logs 

in the migration. 

One of: 

● COPY 

● MOVE 

● LEAVE 

Required if the 

configured 

location of the 

logs, cache, and 

broker data store 

are relative paths. 

If not specified, 

the database and 

logs remain in 

their 7.5 or 7.6 

locations. 


- 

-

name.mqstore. 

db.connect 

Path to the new broker 

database 


Table 13. Container-specific Properties in an upgrade.properties file (continued) 

Property for 


name. 

recovery.log.file 

Path to the new broker 

recovery log 

Container cache and log locations 

name.cache.dir The location of the new 

container cache 

name.log.dir The location of the container 

log 

Encryption of files that contain passwords 

name.boot.file. 

password 

The clear-text password 

used to encrypt generated 

container.ini files, and the 

DS boot file. 

Central connection for a management routing node 

name. 

central.connection. 

url 

name. 


username 

name. 


password 

URL for direct connection 

to the management node 

Username for direct 

connection to the 

management node 

Password for direct 

connection to the 

management node 

Required when 

name.db.action is 

COPY or MOVE 

(else an exception 

is thrown) 

If not specified, 

the 7.5 or 7.6 

configured value is 

used. 

Might also require edits to 

name.previous.working.directory. 

● For db.action of COPY or MOVE, 

locates the 7.5 or 7.6 files. 

● For db.action of LEAVE, sets the 

absolute path to the Version 8 

stores and logs. 

For a root container, the directory 

name is validated on the local host. 

Optional. In a Domain Manager upgrade, also 

encrypts the Directory Service boot 

file, ds.xml. 

Required. Only for containers that host a broker 

in a management routing node that 

will connect to the management node 

over DRA. 

Required. For more about central connections, 

see “Setting Up Central 

Connections” in the Progress 

SonicMQ Deployment Guide, and 

Required if 

MgmtBroker is 


“Configuring Containers” in the 

Progress SonicMQ Configuration 

and Management Guide. 




Property for 


name. 


request.timeout 

name. 


connect.timeout 

name. 


socket.connect. 

timeout 

name. 


load.balancing 

name. 


system.properties 

Set up as a Windows Service 

name. 

windows.service. 

name 

Timeout per request on this 

connection, defaults to 

30000 ms 

Timeout for the initial 

connection, defaults to 

10000 ms 

Defaults to 0. Settable on a 

management connection 

Optional. 

Optional. 

Optional. 

Defaults to true Optional. 

Comma separated 

property=value pairs. 

System properties to be set 

when the central connection 

is used. 

The name of the Windows 

Service to install for this 

container 

Required for root 

containers for 

support of 

properties such as 

SSL connection 

properties. 

Required to install 

a Windows 

Service to start the 

container. If not 

given, no windows 

service will be 

installed. 

These properties are prefixed by 

CentralConnection and are set in the 

JVM arguments attribute of the 

container configuration. The upgrade 

will set these properties in the 

container configuration, and the 

container.ini file for the container 

will contain this information. 

If a windows service by that name 

existed before, it is removed and this 

Windows Service is installed. 




Property for 


Directory Service Location (Domain Manager upgrades only) 

name.host.directory The location of the 

Directory Service store. 

In fault-tolerant 

management frameworks, 

applies to the Primary DS as 

well as the Backup DS on 

their local hosts. 

Optional. For DS locations outside the default 

location. When not specified, the 

default location is used—the 

container directory of the Domain 

Manager in the 8.5 installation. 

Might also require specifying the 

Domain Manager’s 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 


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 don’t 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. 


Zero-Downtime Upgrades of 7.5 and 7.6 Clusters and Replicated Brokers 

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 and—through sophisticated interbroker 

connections—to 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 broker’s container’s 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 hot—after 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 expected—both 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 broker’s container. 

3. On the primary broker’s 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 broker’s 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. 


Zero-Downtime Upgrades of 7.5 and 7.6 Clusters and Replicated Brokers 

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 broker’s container. 

6. On the backup broker’s 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, and—despite 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 expected—both 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 broker’s container. 

3. On that primary broker’s 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 broker’s 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. 


Upgrading a Fault Tolerant Management Framework 


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 Manager—it takes the ACTIVE state. 

The upgrade process on the backup Domain Manager’s system will first connect to the 8.5 

primary Domain Manager’s broker to access the backup’s component properties in the 


◆ 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: 

Upgrading Other Configuration Objects 

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. 

Upgrading Other Configuration Objects 

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 

daemon’s configuration (through the Sonic Management Console), its container, or any 

object on the daemon’s 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 


If you specified any location for the Collection Monitor’s 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. 


Verification and Housekeeping Tasks After Upgrading 


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 

version’s 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 files—ds.xml and 

container.ini—that 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 installation’s 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 installation’s 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 installation’s 

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 

Sonic Installer 8.5 

(download or media) 

Technique for updating 

Sonic Workbench Download and run Sonic Updater for 

the latest Sonic 8.5 Service Pack 

SonicMQ Development 

Sonic Domain 

Sonic Administration 

Tools 

Sonic Container Launcher Installer 8.5 

(download or media) 

None. Container connections to a 

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 product’s 

8.5 .n package instead. 

Sonic .NET Client 8.5 (download) 

Sonic JCA Adapter 8.5 (download) 


Downloading a Sonic Updater 

Downloading a Sonic Updater 

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 update—Sonic Workbench, SonicMQ Development, or 

deployment Domain Manager—confirm 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 updater’s 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 Manager’s 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 Pack’s 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 client’s operating 

system’s native character set. Consult the vendor’s 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 

Configuration Name 

Access Control Lists 

(ACLs) pattern 

Broker 

(management or 

messaging) 

Max 

Size Allowed Characters and Special Use 

- All alphanumeric characters, ASCII punctuation and symbols are allowed 

except slash (/). 

Note that asterisk (*) and pound sign (#) have wildcard meaning. 


except double quote ("), pound (#), dollar sign ($), percent sign (%), 

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 (-). 


Table 14. Naming Rules and Allowed Characters in Sonic (continued) 


Naming Rules for Sonic Configuration Elements 

Durable subscription - All alphanumeric characters, ASCII punctuation and symbols are allowed 

except dollar sign ($), period (.), slash (/), and backslash (\). 


Group of users 

(internal group) 

Group of users 

(group map between 

internal and external 

groups; group-name 

generated using PASS 

SPI) 

Quality of Protection 

(QoP) pattern 

Max 



except pound (#), dollar sign ($), asterisk (*), period (.), slash (/), and 

backslash (\). 


except pound (#), dollar sign ($), asterisk (*), period (.), slash (/), 

backslash (\), equal sign (=), and comma (,). 


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) 


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 

(internal or external) 

Max 



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 broker’s 

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 file—whether encrypted or not—must 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.

Progress Sonic 8.5 Installation and Upgrade Guide - Product ...

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?