Replication Monitor User s Guide

Transcription

1 Replication Monitor User s Guide Version (041209) DOC Marimba Product Line

2 Copyright BMC Software, Inc. All rights reserved. This publication is protected by copyright and international treaty. No part of this publication may be reproduced in any form by any means, or provided to any third party, without prior written authorization from BMC Software, Inc. Protected by or for use under one or more of the following patents: U.S. Patent Nos. 5,919,247, 6,272,536, 6,367,075, 6,381,631, and 6,430,608. Other Patents Pending. RESTRICTED RIGHTS LEGEND: As defined in U.S. Federal Acquisition Regulations (FAR) section and U.S. Defense Federal Acquisition Regulations (DFARs) section (a)(1) and DFAR section (a)(5)(or otherwise), the documentation and any related software are deemed to be commercial items and commercial computer software and commercial computer software documentation. Consistent with DFAR section and FAR section , any use, modification, reproduction, release, performance, display, or disclosure of such commercial software or commercial software documentation by the U.S. Government shall be prohibited except to the extent expressly and mutually agreed to by the U.S. Government and BMC Software, Inc. TRADEMARKS: Marimba, Castanet, Timbale, UpdateNow, Powered by Marimba and related logos are registered trademarks or trademarks of BMC Software, Inc. in the U.S. and/or certain other countries. All other product, service, or company names mentioned herein are trademarks of their respective companies. THIS PUBLICATION (AND ANY RELATED SOFTWARE) IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON- INFRINGEMENT. THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN, THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. BMC SOFTWARE, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCTS AND/OR THE PROGRAMS DESCRIBED IN THIS PUBLICATION AT ANY TIME. BMC Software, Marimba Product Line 440 Clyde Avenue Mountain View, CA

3 Contents DOC Introduction What Is Replication Monitor? Audience Related Documentation Conventions Using Replication Monitor Prerequisites Installing Replication Monitor Specifying Transmitter Information Running Replication Monitor Command-Line Options for Replication Monitor Understanding Replication Monitor Output Appendix A: Configuration File Syntax and Examples Replication Monitor DTD Sample XML Configuration Files Example 1 Using a Load Balancer Example 2 Using Access Control and SSL Required Information Supplying Credentials for Access Control Administration Access Control Replication Access Control Replication User Name and Password Names of Channels to Exclude from Replication XML Listing Access Control Replication Monitor User s Guide 3

4 Description of XML Syntax The <architecture> Tag The <master> Tag The <mirrors> Tag The <repeaters> Tag The <transmitter> Tag The <exclude> Tag Appendix B: Output and Status Messages Replication Monitor Output Error Codes Command-line Output Status Messages Sample Output Example 1 All transmitters Are Synchronized Example 2 Failure to Connect to Master Transmitter Example 3 Access Is Denied to Master Transmitter Example 4 Failure to Connect to a Repeater Example 5 Not Synchronized: Missing Channel Example 6 Not Synchronized: Extra Channel Example 7 Not Synchronized: Channel Version Mismatch Index 4 Replication Monitor User s Guide

5 Introduction DOC Replication Monitor is one of the tools in the Marimba Resource Kit. System administrators can use this kit to diagnose problems with Desktop/Mobile Management and Server Management components, such as tuners and transmitters. This chapter provides an overview of Replication Monitor. What Is Replication Monitor? Replication Monitor indicates whether or not all the transmitters (master, mirrors, and repeaters) in your infrastructure are synchronized. The master transmitter, mirrors, and repeaters in an infrastructure are deemed synchronized if they meet the following conditions: They contain the same set of channels. That is, all channels on the master transmitter are successfully replicated to the mirrors, and the appropriate channels are also replicated to repeaters. The versions of their channels match. That is, the versions of all channels on the mirrors and repeaters match the versions of the channels on the master transmitter. This is determined by comparing the index ID of the channel segments. Introduction 5

6 What Is Replication Monitor? Note: Replication Monitor only indicates whether or not the transmitters in your infrastructure are synchronized. It does not synchronize these transmitters for you. Replication Monitor contacts the master, then mirrors, and then repeaters in your infrastructure as shown below. Master Transmitter Channels on Master Transmitter Channels on Mirror or Repeater Compare Mirrors Replication Monitor Repeaters Figure 1. Overview of How Replication Monitor Works It is beneficial to use Replication Monitor when you first set up your transmitter infrastructure, and periodically after this (for example, after every replication interval) to ensure that your infrastructure is replicating as it should. Replication Monitor resides on a network node that has a tuner running on it and that can connect to all the transmitters in your infrastructure. Replication Monitor can work in an infrastructure that includes load balancers and where SSL is enabled. 6 Replication Monitor User s Guide

7 Audience Audience This guide is for system administrators who want to ensure that the repeaters and mirrors in their infrastructure have the same set and same versions of channels as the master transmitter. To use this guide, you should know: Basic XML Basic concepts about repeaters, mirrors, and transmitters How to configure transmitter replication the transfer of channels from a master transmitter to mirrors or repeaters (or both) Related Documentation On Marimba s Documentation page ( you can find a variety of documents both online books and PDF versions of some of the online help. You will find it beneficial to read the following related document: Marimba Infrastructure Administrator s Guide describes how to use the runchannel program. General concepts about repeaters and mirrors are also covered. This guide also describes how to configure and administer individual transmitters within your network. Conventions The following formatting conventions are used in Marimba documentation. Example Click Apply. Choose Edit > Cut setup.exe cd \data <your_file> [-title] quiet verbose The kernel provides Explanation Names of menus, commands, buttons, and other user interface elements appear in bold in instructional procedures. This notation means (in this example) choose Cut from the Edit menu. File names, directory names, paths, code samples, and command-line text appear in a monospaced font. Where necessary to differentiate it from text the computer displays, text you type appears in a bold monospaced font. Text variables are italic and enclosed in angle brackets. For example, if the documentation states, Type some.exe -f <your_file>, you might type some.exe -f mystuff.txt. Command-line options that you can include or omit are enclosed in square brackets. Vertical bar separates a choice of command-line options in this example, either quiet or verbose. New terms appear in italics. Introduction 7

8 Conventions 8 Replication Monitor User s Guide

9 Using Replication Monitor DOC This chapter describes how to subscribe to and use Replication Monitor. The following topics are discussed: Prerequisites on page 9 Installing Replication Monitor on page 10 Specifying Transmitter Information on page 11 Running Replication Monitor on page 12 Understanding Replication Monitor Output on page 14 You will use the command-line runchannel program to install and run Replication Monitor. If you are unfamiliar with the runchannel program, read the Related Documentation on page 7. Note: Remember that runchannel is case-sensitive! Prerequisites You must meet the following prerequisites in order to use Replication Monitor. Requirements for transmitters. Make sure that your transmitters satisfy the following prerequisites: Compatible transmitter versions See the Marimba Resource Kit Release Notes and the System Requirements document, located on Marimba s Documentation page ( Using Replication Monitor 9

10 Installing Replication Monitor It is assumed that you have only one master transmitter in the infrastructure that you want to check. If you have a 3-tiered infrastructure which includes a master transmitter, mirrors and repeaters the mirrors and the master transmitter must be located behind a load balancer. The master transmitter must not require client-side certificates when using SSL. Requirements for Replication Monitor. Make sure that the machine that hosts Replication Monitor satisfies the following prerequisites: Replication Monitor is hosted on a machine that has one of the supported platforms. Replication Monitor runs on all the platforms supported for the transmitter. For more information, see the System Requirements document, located on Marimba s Documentation page ( A tuner must be installed on the machine from which you are running Replication Monitor. You do not need a transmitter on this machine. The network node on which Replication Monitor is installed must be able to make connections to all the transmitters (master, mirrors, repeaters) in your infrastructure. Installing Replication Monitor Subscribing to Replication Monitor installs it on a machine s hard drive. You must install Replication Monitor on a machine that already has a tuner installed on it and that is able to make connections to all the transmitters (master, mirrors, repeaters) in your infrastructure. In this section, you subscribe to Replication Monitor from the command line by using runchannel. To subscribe to Replication Monitor from the command line: 1 Use Channel Copier (or the 6.0.x Transmitter Administrator s Add Channel feature) to copy the Replication Monitor channel from Marimba s products transmitter to your own master transmitter. The URL to this channel is: For instructions on using Channel Copier, see the Channel Copier Help. 10 Replication Monitor User s Guide

11 Specifying Transmitter Information Tip: The location (URLs) of Replication Monitor and all the other channels included in the Marimba Resource Kit are provided in the Marimba Resource Kit release notes, available on Marimba s Documentation page ( 2 Open a command prompt, and go to the directory where you installed the tuner. The default on Windows is C:\Program Files\Marimba\Tuner. 3 Enter the following command: runchannel -subscribe <Replication_Monitor_URL> where <ReplicationMonitor_URL> is the channel URL for Replication Monitor, and has the following format: Here, <host> is the host name or IP address of the transmitter that you copied Replication Monitor to, and <port> is the port of this transmitter. If you do not specify a port number, 80 is used by default. For example, if the transmitter s host name and port are mytrans.mycompany.com:80, Replication Monitor s channel URL might be: In this case, to subscribe to Replication Monitor, you would type the following in the command line: runchannel -subscribe Note: The above example is typed on one line in the command line, without carriage returns. Specifying Transmitter Information Before running Replication Monitor, you need to specify information about the transmitters in your infrastructure in an XML configuration file. For information on creating this configuration file, read Appendix A: Configuration File Syntax and Examples on page 15. This appendix contains the following information: Replication Monitor DTD Sample XML configuration files Information required in the configuration file Explanation of the XML syntax You can save this configuration file using any file name, extension, and path. Using Replication Monitor 11

12 Running Replication Monitor Running Replication Monitor In order to run Replication Monitor, you must specify an XML configuration file that contains information about the transmitters in your infrastructure. Important! Replication Monitor only indicates whether or not the transmitters in your environment are synchronized. It does not synchronize these transmitters for you. To run Replication Monitor: 1 Create the XML file that contains the configuration settings you need. For instructions, see Appendix A: Configuration File Syntax and Examples on page Open a command prompt, and go to the directory where you installed the tuner. The default on Windows is C:\Program Files\Marimba\Tuner. 3 Enter the following command: runchannel <Replication_Monitor_URL> -cfg <file> [<options>] where <Replication_Monitor_URL> is the channel URL for Replication Monitor. For more information, see Installing Replication Monitor on page 10. -cfg <file> specifies the relative or absolute file name and path for Replication Monitor s XML configuration file, which is described in detail in Appendix A: Configuration File Syntax and Examples on page 15. <options> are any additional command-line options for Replication Monitor. Descriptions of these options are provided in Command-Line Options for Replication Monitor on page 13. (Or you can use the command-line -help option to get a list of the options.) Example of a Replication Monitor command: The following command starts Replication Monitor on your machine (after it has already been subscribed to or installed there): runchannel -cfg env2.xml When you run Replication Monitor, it connects to the master transmitter, then to the mirrors, and then to the repeaters. It then prints a status report to standard output, at the command line. For more information, see Understanding Replication Monitor Output on page Replication Monitor User s Guide

13 Running Replication Monitor Command-Line Options for Replication Monitor In addition to the required command-line option -cfg, which gives the full path to the XML configuration file, you can use the following options, if desired: -checkunknown specifies that you want Replication Monitor to auto-discover (or check) for new (or unknown) repeaters; that is, repeaters that might not be listed in Replication Monitor s XML configuration file, but that your mirrors do nevertheless include in their repeater lists. By default, this type of checking is disabled because in many cases, repeaters have NAT-ed addresses (that is, they use network address translation for their IP addresses). In the case of NAT-ed addresses, if you use the -checkunknown option, then Replication Monitor would autodiscover a NAT-ed address and mistakenly assume it was a new, unknown repeater. If your repeaters use NAT, then do not use the -checkunknown option, and when you write your XML configuration file, use whatever address is appropriate to access the transmitter from the endpoint where Replication Monitor is running. -concurrency <connections> -help specifies the maximum number of concurrent connections to a transmitter when getting a channel listing from the transmitter. The default is 50. If your transmitter hosts hundreds of channels and Replication Monitor cannot parse the XML listing within the timeout period, you might need to increase the number of connections. (In addition, you might need to increase the timeout period, by using the -timeout option.) lists the command-line options available for Replication Monitor. -timeout <seconds> -verbose specifies the timeout period, in seconds, when getting a channel listing from the transmitter. The default is 60. If your transmitter hosts hundreds of channels and Replication Monitor cannot parse the XML listing within the timeout period, you might need to increase the number of seconds. (In addition, you might need to increase the number of concurrent connections, by using the -concurrency option.) specifies that you want more detailed information about any unknown repeaters that might be found. Using Replication Monitor 13

14 Understanding Replication Monitor Output Understanding Replication Monitor Output Replication Monitor returns the following information about the transmitters in your infrastructure: Status Report. Replication Monitor displays (on the command-line console) a status report about all the transmitters in your infrastructure. This report is also stored in Replication Monitor channel s history log (located in the tuner s workspace directory under the Replication Monitor channel directory). The path to this file is: <tuner_workspace_dir>\ch.x\history-x.log where <tuner_workspace_dir> is the tuner s workspace directory, and Ch.X specifies the channel number for the Replication Monitor channel. (On Windows, the default location of the tuner s workspace is c:\program Files\Marimba\Tuner\.marimba\<keyword>\. On UNIX, the default is /opt/marimba/tuner/.marimba/<keyword>/. In the path, <keyword> is the endpoint s keyword, which was assigned during installation. The default keyword is the profile name.) To determine the channel number for Replication Monitor, open the map.txt file in the workspace. Error Codes. Replication Monitor returns one of the following error codes: 0, 1, 2, 3, or 4 (which are stored in the tuner s history log located in the tuner s workspace directory). A description of all status messages, error codes, as well as sample output, is provided in Appendix B: Output and Status Messages on page Replication Monitor User s Guide

15 DOC Appendix A: Configuration File Syntax and Examples Use the information in this appendix to create Replication Monitor s XML configuration file. The following topics are discussed: Replication Monitor DTD on page 15 Sample XML Configuration Files on page 16 Required Information on page 17 Description of XML Syntax on page 21 Replication Monitor DTD Replication Monitor s configuration file must be a well-formed and valid XML file that conforms to the following DTD. <!ELEMENT architecture (master, mirrors?, repeaters?)> <!ELEMENT master (transmitter)> <!ELEMENT mirrors (transmitter*)> <!ELEMENT repeaters (transmitter*)> <!ELEMENT transmitter (exclude*)> <!ELEMENT exclude (#PCDATA)> <!ATTLIST master name CDATA #IMPLIED> <!ATTLIST transmitter url CDATA #REQUIRED user CDATA #IMPLIED password CDATA #IMPLIED replication-user CDATA #IMPLIED replication-password CDATA #IMPLIED xml-user CDATA #IMPLIED xml-password CDATA #IMPLIED version CDATA "4.7" Appendix A: Configuration File Syntax and Examples 15

16 Sample XML Configuration Files Sample XML Configuration Files This section discusses two sample Replication Monitor configuration files. Example 1 Using a Load Balancer The following configuration file shows an infrastructure with one master and one mirror located behind a load balancer, and two repeaters. The presence of a load balancer affects the way you specify information for the master transmitter. The <master> tag s name attribute specifies the host name and port of the load balancer to which repeaters connect, and the <transmitter> tag s url attribute specifies the host name and port of the master transmitter. In contrast, note that when a mirror is located behind a load balancer, you still specify information for the mirror as you would normally. <?xml version="1.0"?> <!DOCTYPE architecture PUBLIC "-//Marimba, Inc.//DTD Replication Monitor 1.0//EN" " <architecture> <master name="mytx:5282"> <transmitter url=" user="admin" password="admin" /> </master> <mirrors> <transmitter url=" /> </mirrors> <repeaters> <transmitter url=" /> <transmitter url=" /> </repeaters> </architecture> 16 Replication Monitor User s Guide

17 Required Information Example 2 Using Access Control and SSL The following example shows an infrastructure with one master and three repeaters. All transmitters are configured to use SSL. The master transmitter has administration access control enabled. The user and password attributes of the <transmitter> tag specify the administration user name and password. (Instructions for enabling administration access control are provided in Administration Access Control on page 18.) Also, because the master transmitter has replication access configured, the replication-user and replication-password attributes specify the user name and password that repeaters use to replicate the channels and folders on the master transmitter. (Instructions for enabling replication access control are provided in Replication Access Control on page 19.) <?xml version="1.0"?> <!DOCTYPE architecture PUBLIC "-//Marimba, Inc.//DTD Replication Monitor 1.0//EN" " <architecture> <master> <transmitter url=" user="admin" password="admin" /> </master> <repeaters> <transmitter url=" replicationuser="user4" replication-password="user4" /> <transmitter url=" replicationuser="user5" replication-password="user5" /> <transmitter url=" replicationuser="user6" replication-password="user6" /> </repeaters> </architecture> Required Information This section describes the information that you are required to include in the Replication Monitor configuration file. The configuration file must be a well-formed and valid XML document that conforms to the Replication Monitor DTD shown under Replication Monitor DTD on page 15. Appendix A: Configuration File Syntax and Examples 17

18 Supplying Credentials for Access Control You can save the configuration file using any file name, extension, and path. In the configuration file, you must: Include a line that sets the DOCTYPE so that the XML can be validated. This line is shown in the examples of XML configuration files provided in this appendix. List all the transmitters in your infrastructure that you want to check. Replication Monitor checks all the transmitters listed in this file. In addition, if you use the -checkunknown option, Replication Monitor also checks other repeaters of which the mirrors are aware. (Using this option is not recommended if your repeaters use network address translation, or NAT.) List exactly one master transmitter, and zero or more mirrors and repeaters in the Replication Monitor configuration file. Because you can set several types of access controls for your transmitters, you need to provide user names and passwords so that Replication Monitor can access certain information on the transmitters. For more information, see Supplying Credentials for Access Control on page 18. Supplying Credentials for Access Control The following sections describe the kinds of access control Replication Monitor needs to account for: Administration Access Control on page 18 Replication Access Control on page 19 XML Listing Access Control on page 21 Administration Access Control Your master transmitter might have an administration user name and password configured (that is, the master transmitter does not allow anonymous administration). In this case, Replication Monitor must provide the administration user name and password in order to retrieve all required information from the master transmitter. That is, you need to include the user name and password in the XML configuration file that Replication Monitor uses. You can use Transmitter Administrator to connect to the master transmitter and find out whether administration access has been set, or to enable it, as follows. 18 Replication Monitor User s Guide

19 Supplying Credentials for Access Control To find out whether administration access is set: 1 Log in to the Marimba console, and from the tab menu in the upper-right portion of the browser page, click Applications > Infrastructure > Transmitter Administration. 2 On the Connect to a Transmitter page, specify which master transmitter you want to connect to, enter administration access credentials, if necessary, and click Edit Settings. Important: If administration access has not yet been set, you will be able to connect anonymously. If access has been set, then the credentials you must enter here are the same ones you must use in Replication Monitor s XML configuration file. 3 On the Edit Transmitter Settings page that appears, click the Security tab. Replication Access Control The Administration Access sub-tab is displayed. It tells you what authentication method is being used and allows you to change the settings. Your master transmitter or mirror might have replication access control configured to protect certain folders, channels, or the entire contents of the master transmitter or of the mirror from being replicated. When replication access control is enabled, Replication Monitor needs to provide one of the following types of information: Replication User Name and Password on page 20 Names of Channels to Exclude from Replication on page 20 Using either of these strategies ensures that Replication Monitor checks only the list of channels that the repeater or mirror is allowed to replicate against those on the master transmitter. Appendix A: Configuration File Syntax and Examples 19

20 Supplying Credentials for Access Control Replication User Name and Password You can use Transmitter Administrator to connect to the repeater and find out whether replication access has been set, and if so, the user name, as follows. To find out the replication user name: 1 Log in to the Marimba console, and from the tab menu in the upper-right portion of the browser page, click Applications > Infrastructure > Transmitter Administration. 2 On the Connect to a Transmitter page, specify which repeater you want to connect to, enter administration access credentials, if necessary, and click Edit Settings. 3 On the Edit Transmitter Settings page that appears, click the Advanced tab. The Transmitter Options sub-tab is displayed. It lists the source transmitter, folders, or channels that are to be replicated on this repeater. It also lists the user name used by the repeater to access the source. You need to provide these user names and their corresponding passwords in the XML configuration file that Replication Monitor uses. Names of Channels to Exclude from Replication Use this alternative if you do not have the ability to find out the replication user name and/or password, or if you find this alternative easier. You can use Transmitter Administrator to connect to the master transmitter and find out which channels you want to exclude, as follows. To find out which channels you want to exclude from monitoring: 20 Replication Monitor User s Guide 1 Log in to the Marimba console, and from the tab menu in the upper-right portion of the browser page, click Applications > Infrastructure > Transmitter Administration. 2 On the Connect to a Transmitter page, specify which master transmitter you want to connect to, enter administration access credentials, if necessary, and click Manage Channels. 3 On the Manage Channels page that appears, click the Security tab. 4 Expand the folders as necessary and use the Replication column to view the replication permission settings on the folders and channels you are interested in. Tip: If replication permission is set to a specific user or group, you need to select that channel or folder and click Edit Permissions to find out the name of the user or group.

21 Description of XML Syntax 5 Based on this information, if you find that the replication permission on some channels or folders are such that you would want to exclude them from monitoring, then note the URLs of these so that you can specify them in your XML file. XML Listing Access Control (Applies to very few cases.) If your transmitter s XML listing is protected (which is not the default), Replication Monitor needs to provide the user name and password required to access the XML listing for that transmitter. For more information, consult Marimba Customer Support. Description of XML Syntax The following section describes the syntax for Replication Monitor s configuration file. The <architecture> Tag (Required) The <architecture> tag is the root tag. Example. Following is an example that shows how to use the <architecture> tag. <architecture> <master> <transmitter url= user="admin" password="admin" /> </master> <mirrors> <transmitter url= /> <transmitter url= /> </mirrors> <repeaters> <transmitter url= /> <transmitter url= /> <transmitter url= /> </repeaters> </architecture> Appendix A: Configuration File Syntax and Examples 21

22 Description of XML Syntax The <master> Tag (Required) Use the <master> tag to specify the master transmitter used in your infrastructure. You must have only one <master> tag in the configuration file. If you do not list a master transmitter, Replication Monitor does not check any transmitter in your infrastructure. Required tags to include. The <master> tag must contain exactly one <transmitter> tag, which specifies information about your master transmitter. Optional attributes. If the master transmitter is located behind a load balancer, use the name attribute to specify the name of the load balancer, as shown in example 2, which follows. Example 1. Following is an example that shows how to use the <master> tag. <master> <transmitter url=" user="admin" password="admin" /> </master> Example 2. If the master transmitter is located behind a load balancer, the name of the master as seen by the repeaters does not match the name of the actual master transmitter. In this case, you must specify the host name and port of the load balancer using the name attribute of the <master> tag, and must use the url attribute of the <transmitter> tag to specify the host name and port of the master transmitter. <master name= > <transmitter url=" user="admin" password="admin" /> </master> Note: For more examples, see The <transmitter> Tag on page Replication Monitor User s Guide

23 Description of XML Syntax The <mirrors> Tag (Optional) Use the <mirrors> tag to specify the mirrors used in your infrastructure, if you have any. You can have only one <mirrors> tag in your configuration file. Note: If you have a three-tiered infrastructure which includes a master transmitter, mirrors, and repeaters the mirrors and the master transmitter must be located behind a load balancer. Required tags to include. The <mirrors> tag can contain one or more <transmitter> tags, with each one specifying information about a mirror in your infrastructure. Example. Following is an example that shows how to use the <mirrors> tag. <mirrors> <transmitter url=" /> <transmitter url=" /> </mirrors> The <repeaters> Tag Note: For more examples, see The <transmitter> Tag on page 24. (Optional) Use the <repeaters> tag to specify the repeaters used in your infrastructure, if you have any. You can have only one <repeaters> tag in your configuration file. In addition, if you use the -checkunknown option, Replication Monitor also checks other repeaters of which the mirrors are aware; that is, the repeaters that are included in the mirrors list of repeaters. (Using this option is not recommended if your repeaters use network address translation, or NAT.) When Replication Monitor finds a repeater that is not included in the configuration file, it displays "Found an unknown repeater: and reports the repeater s status as part of the output. Required tags to include. The <repeaters> tag can contain one or more <transmitter> tags, with each one specifying information about a repeater in your infrastructure. Appendix A: Configuration File Syntax and Examples 23

24 Description of XML Syntax Example. Following is an example that shows how to use the <repeaters> tag. <repeaters> <transmitter url=" /> <transmitter url=" /> <transmitter url=" /> </repeaters> The <transmitter> Tag Note: For more examples, see The <transmitter> Tag on page 24. (Required if you have a <master>, <mirrors>, or <repeaters> tag.) Use the <transmitter> tag to specify information about a transmitter (which can be a master, mirror, or repeater) used in your infrastructure. The <transmitter> tag can an appear under any of the following tags: <master> only one <transmitter> tag can appear under the <master> tag. <mirrors> one or more <transmitter> tags can appear under the <mirrors> tag. <repeaters> one or more <transmitter> tags can appear under the <repeaters> tag. Optional tags to include. The <transmitter> tag can contain one or more <exclude> tags, which are useful when you want to specify channels or folders that repeaters or mirrors do not have permission to replicate. Alternatively, you can use the replication-user and replication-password attributes described below. Attributes. Following is a list of the required and optional attributes you can use with the <transmitter> tag. url (Required. Applies to all transmitters.) The host name or IP address and port of the transmitter, specified in the following format: Note that if your transmitter is configured to use SSL, you must specify its URL with instead of (If you omit this prefix, Replication Monitor uses by default.) Also, you must specify the fully qualified host name of the transmitter. 24 Replication Monitor User s Guide

25 Description of XML Syntax user (Optional. Applies to master transmitter.) If the master transmitter has access control configured, use this attribute to specify the administration user name set for the master transmitter. password (Optional. Applies to master transmitter.) If the master transmitter has access control configured, use this attribute to specify the administration password set for the master transmitter. replication-user (Optional. Applies to repeaters and mirrors.) If the master transmitter or mirror has replication access control configured (for replicating the entire transmitter, certain folders or channels), use this attribute to specify the replication user name required by that transmitter. Note that this is the replication user name that a repeater provides in order to replicate channels from either a master transmitter or a mirror, or it is the user name that a mirror provides in order to replicate channels from the master transmitter. Alternatively, you can use the <exclude> tag. For more information, see Replication Access Control on page 19 and The <exclude> Tag on page 27. replication-password (Optional. Applies to repeaters and mirrors.) If the master transmitter or mirror has replication access control configured (for replicating the entire transmitter, certain folders or channels), use this attribute to specify the replication password set for that transmitter. Note that this is the replication password that a repeater provides in order to replicate channels from either a master transmitter or a mirror, or it is the password that a mirror provides in order to replicate channels from the master transmitter. Alternatively, you can use the <exclude> tag. For more information, see Replication Access Control on page 19 and The <exclude> Tag on page 27. version (Optional. Applies to all transmitters.) Specifies the version of the transmitter. The version can contain 1-4 digits, with or without periods (.) between them. For example, "600" Default: "6.0" xml-user (Optional. Applies to all transmitters) If the master transmitter, mirror, or repeater has its XML listing protected, use this attribute to specify the user name to access this XML listing. xml-password (Optional. Applies to all transmitters.) If the master transmitter, mirror, or repeater has its XML listing protected, use this attribute to specify the password to access this XML listing. Appendix A: Configuration File Syntax and Examples 25

26 Description of XML Syntax Example 1: Replication credentials. The master transmitter has access control configured for certain channels and folders. In this case, the replication user name and password used by the repeater are provided. <repeaters> <transmitter url=" replication-user="test" replication-password="marimba" /> <transmitter url=" /> <transmitter url=" /> </repeaters> Example 2: Exclude tag. Similar to Example 1: Replication credentials. The master transmitter has access control configured for certain channels and folders. In this case, the replication user name and password used by the repeater are provided., the master transmitter has access control configured for certain channels and folders. In this case, the <exclude> tag lists folders and channels to which the repeater does not have access. <repeaters> <transmitter url=" <exclude>folder1/*</exclude> <exclude>mychannels/channel3</exclude> </transmitter> <transmitter url=" /> <transmitter url=" /> </repeaters> Example 3: Credentials for the XLM listing. The master transmitter does not allow anonymous administration, and has its XML listing protected. In this case, the user name and password required for administration and for accessing the XML listing are provided. For more information, consult Marimba Customer Support. <master> <transmitter url=" user="admin" password="mgpsh500" xml-user="user" xml-password="password" /> </master> 26 Replication Monitor User s Guide

27 Description of XML Syntax The <exclude> Tag (Optional) In the case where the master transmitter or mirror has replication access control configured, you can list the channels and folders that a repeater or mirror does not have permission to replicate. This ensures that Replication Monitor checks only the list of channels that the repeater or mirror is allowed to replicate. Note that this is the list of channels that a repeater is not allowed to replicate either from a master transmitter or from a mirror, or it is the list of channels that a mirror is not allowed to replicate from the master transmitter. Alternatively, you can specify the replication user name and/or password using the <transmitter> tag. For more information, see Replication Access Control on page 19 and The <transmitter> Tag on page 24. Example. In this example, Replication Monitor does not check the following channels that are located on the master transmitter or mirror: all the channels under the folder called Folder1, and the channel called Channel3 under the MyChannels folder. <mirrors> <transmitter url=" <exclude>folder1/*</exclude> <exclude>mychannels/channel3</exclude> </transmitter> <transmitter url=" /> <transmitter url=" /> </mirrors> Appendix A: Configuration File Syntax and Examples 27

28 Description of XML Syntax 28 Replication Monitor User s Guide

29 Appendix B: Output and Status Messages DOC This appendix describes Replication Monitor s output. The following topics are discussed: Replication Monitor Output on page 29 Status Messages on page 31 Sample Output on page 33 Replication Monitor Output Error Codes When run, Replication Monitor returns an error code and displays output of the command-line console. This section describes these error codes and the contents of the command-line output. Replication Monitor returns one of the following error codes. (These are stored in the tuner s history log located in the tuner s workspace directory.) Table 1. Replication Monitor Error Codes Error Code Description 0 Indicates that all transmitters are synchronized. 1 Indicates that all transmitters are not synchronized. Appendix B: Output and Status Messages 29

30 Replication Monitor Output Table 1. Replication Monitor Error Codes Command-line Output Error Code Description 2 Indicates that the XML document is well-formed, but it is not valid (that is, it does not conform with the Replication Monitor DTD). 3 Indicates that a configuration file was not specified. 4 Indicates one of the following: Either the file does not exist or it points to a directory instead of a file. An error occurred while parsing the XML configuration file. An I/O error occurred while reading the XML configuration file. Replication Monitor outputs (to the command-line console) information about each transmitter specified in your configuration file. In Replication Monitor s output, the transmitters in your infrastructure are divided into and listed under the following sections: MASTER MIRRORS REPEATERS Note: In addition, if you use the -checkunknown option, Replication Monitor also checks other repeaters of which the mirrors are aware; that is, the repeaters that are included in the mirrors list of repeaters. (Using this option is not recommended if your repeaters use network address translation, or NAT.) When Replication Monitor finds a repeater that is not included in the configuration file, it displays "Found an unknown repeater: and reports the repeater s status as part of the output. The following information appears for each transmitter: Transmitter Indicates the host name or IP address and port number of the transmitter being checked. Checked Indicates the date and time when the transmitter s XML listing is checked. If Replication Monitor is unable to check this transmitter (because of network or I/O issues), it displays the transmitter as being checked Never. 30 Replication Monitor User s Guide

31 Replication Monitor Output Channels Indicates the total number of channels and the number of segments checked on the transmitter. The number of segments checked is listed in parentheses (). Status Indicates the status of the transmitter, channels, and channel segments being checked. For a full list of Replication Monitor status messages, read Status Messages on page 31. Status Messages Replication Monitor displays a status message for each transmitter that it checks. The following table lists all the possible Replication Monitor status messages. Table 2. Description of Status Messages Status Message OK Is not replicating transmitter <host>:<port> Not synchronized Can't find a network path to <host> Description Indicates that Replication Monitor successfully connected to all the transmitters, retrieved their XML listings, and compared them to the master transmitter s XML listing without finding any discrepancies. (Repeaters Only) Indicates that the repeater is not replicating the specified master transmitter at all. (Mirrors and Repeaters Only) Indicates that some channels or channel segments have not been replicated properly (or have not been replicated yet). This message also includes the channels or channel segments that are missing or whose versions do not match those on the master transmitter. Indicates that there was no network path available to reach the machine hosting the specified transmitter. Unknown host <host> Can't connect to <host>:<port> Indicates that the specified host name is unknown (that is, the host name cannot be resolved to an IP address). Indicates that Replication Monitor could not connect to the transmitter running on the specified host name and port. This could occur, for example, either when the transmitter is not running or when it is not responding. Appendix B: Output and Status Messages 31

32 Replication Monitor Output Table 2. Description of Status Messages Status Message Invalid URL: <url> Access Denied. Verify user name/password. Description Indicates that the specified transmitter URL is invalid, for example, because its host name, IP address, or port contains illegal characters, such as forward-slash (/) or colon (:). If this appears for the master transmitter, it indicates that: The administration user name and password are invalid OR The XML listing user name and password are invalid If this appears for mirrors or repeaters, it indicates that the provided XML listing user name and password are invalid. Reply terminated. HTTP Error: <http error code> Indicates that the stream of data from the transmitter was unexpectedly cut off. Specifies a generic error message for HTTP errors. IO Error: <message> Error parsing XML: <message> Specifies a generic error message for I/O errors that occur while connecting to the remote transmitter. This could indicate things such as dropped connections. Specifies a generic error message for errors that occur while parsing the XML listing retrieved from the remote transmitter. 32 Replication Monitor User s Guide

33 Sample Output Sample Output This section provides some examples of Replication Monitor s output (displayed on the command line console). Example 1 All transmitters Are Synchronized The following output indicates that all the channels and segments on the master transmitter, mirrors, and repeaters are synchronized. Notice that a total number of two channels and two segments were checked. --- MASTER --- Transmitter: Checked: 2002/06/05 09:21:40 Channels: 2 (2 segments) Status: OK --- MIRRORS --- Transmitter: Checked: 2002/06/05 09:21:40 Channels: 2 (2 segments) Status: OK --- REPEATERS --- Transmitter: Checked: 2002/06/05 09:21:40 Channels: 2 (2 segments) Status: OK Appendix B: Output and Status Messages 33

34 Sample Output Example 2 Failure to Connect to Master Transmitter The following output indicates that Replication Monitor was unable to connect to the master transmitter either because that transmitter was not running or because it was not responding. Notice that if Replication Monitor is unable to connect to the master transmitter, it does not attempt connecting to and checking the mirrors and repeaters. --- MASTER --- Transmitter: Checked: 2002/06/05 09:22:51 Channels: - Status: Can't connect to : MIRRORS --- Transmitter: Checked: Never Channels: - Status: Not checked --- REPEATERS --- Transmitter: Checked: Never Channels: - Status: Not checked 34 Replication Monitor User s Guide

35 Sample Output Example 3 Access Is Denied to Master Transmitter The following output indicates that Replication Monitor was unable to access the master transmitter because of either an incorrect administration user name and password or an incorrect XML listing user name and password. Notice that if Replication Monitor is unable to access the master transmitter s XML listing, it does not attempt connecting to and checking the mirrors and repeaters. --- MASTER --- Transmitter: Checked: 2002/06/05 09:24:08 Channels: - Status: Access Denied. Verify username/password. --- MIRRORS --- Transmitter: Checked: Never Channels: - Status: Not checked --- REPEATERS --- Transmitter: Checked: Never Channels: - Status: Not checked Appendix B: Output and Status Messages 35

36 Sample Output Example 4 Failure to Connect to a Repeater The following output indicates that Replication Monitor was unable to connect to the specified repeater either because that transmitter was not running or because it was not responding. Notice that unlike the case with the master transmitter (see Example 2 Failure to Connect to Master Transmitter and Example 3 Access Is Denied to Master Transmitter), Replication Monitor continues to check the remainder of the repeaters in your infrastructure. This is also the case if Replication Monitor is unable to connect to a mirror. --- MASTER --- Transmitter: Checked: 2002/06/05 09:25:02 Channels: 2 (2 segments) Status: OK --- MIRRORS --- Transmitter: Checked: 2002/06/05 09:25:02 Channels: 2 (2 segments) Status: OK --- REPEATERS --- Transmitter: Checked: 2002/06/05 09:25:02 Channels: - Status: Can't connect to :5002 Transmitter: Checked: 2002/06/05 09:25:02 Channels: 2 (2 segments) Status: OK 36 Replication Monitor User s Guide