<div class="wiki-content maincontent"><h2 id="SharedFileSystemMasterSlave-SharedFileSystemMasterSlave">Shared File System Master Slave</h2><p>If you have a SAN or shared file system it can be used to provide <em>high availability</em> such that if a broker is killed, another broker can take over immediately.</p><div class="confluence-information-macro confluence-information-macro-warning"><p class="title">Ensure your shared file locks work</p><span class="aui-icon aui-icon-small aui-iconfont-error confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Note that the requirements of this failover system are a distributed file system like a SAN for which exclusive file locks work reliably. If you do not have such a thing available then consider using <a shape="rect" href="masterslave.xml">MasterSlave</a> instead which implements something similar but working on commodity hardware using local file systems which ActiveMQ does the replication.</p><div class="confluence-information-macro confluence-information-macro-note"><p class="title">OCFS2 Warning</p><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Was testing using OCFS2 and both brokers thought they had the master lock - this is because "OCFS2 only supports locking with 'fcntl' and not 'lockf and flock', therefore mutex file locking from Java isn't supported."</p><p>From <a shape="rect" class="external-link" href="http://sources.redhat.com/cluster/faq.html#gfs_vs_ocfs2" rel="nofollow">http://sources.redhat.com/cluster/faq.html#gfs_vs_ocfs2</a> :<br clear="none"> OCFS2: No cluster-aware flock or POSIX locks<br clear="none"> GFS: fully supports Cluster-wide flocks and POSIX locks and is supported.<br clear="none"> See this JIRA for more discussion: <a shape="rect" class="external-link" href="https://issues.apache.org/jira/browse/AMQ-4378">https://issues.apache.org/jira/browse/AMQ-4378</a></p></div></div><div class="confluence-information-macro confluence-information-macro-note"><p class="title">NFSv3 Warning</p><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>In the event of an abnormal NFSv3 client termination (i.e., the ActiveMQ master broker), the NFSv3 server will not timeout the lock that is held by that client. This effectively renders the ActiveMQ data directory inaccessible because the ActiveMQ slave broker can't acquire the lock and therefore cannot start up. The only solution to this predicament with NFSv3 is to reboot all ActiveMQ instances to reset everything.</p><p>Use of NFSv4 is another solution because its design includes timeouts for locks. When using NFSv4 and the client holding the lock experiences an abnormal termination, by design, the lock is released after 30 seconds, allowing another client to grab the lock. For more information about this, see <a shape="rect" class="external-link" href="http://blogs.netapp.com/eislers_nfs_blog/2008/07/part-i-since-nf.html" rel="nofollow">this blog entry</a>.</p></div></div></div></div><p>Basically you can run as many brokers as you wish from the same shared file system directory. The first broker to grab the exclusive lock on the file is the master broker. If that broker dies and releases the lock then another broker takes over. The slave brokers sit in a loop trying to grab the lock from the master broker.</p><p>The following example shows how to configure a broker for Shared File System Master Slave where <strong>/sharedFileSystem</strong> is some directory on a shared file system. It is just a case of configuring a file based store to use a shared directory.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[    &lt;persistenceAdapter&gt;
      &lt;kahaDB directory=&quot;/sharedFileSystem/sharedBrokerData&quot;/&gt;
    &lt;/persistenceAdapter&gt;
]]></script>
</div></div><p>or:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[    &lt;persistenceAdapter&gt;
      &lt;levelDB directory=&quot;/sharedFileSystem/sharedBrokerData&quot;/&gt;
    &lt;/persistenceAdapter&gt;
]]></script>
</div></div><p>or:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[    &lt;persistenceAdapter&gt;
      &lt;amqPersistenceAdapter directory=&quot;/sharedFileSystem/sharedBrokerData&quot;/&gt;
    &lt;/persistenceAdapter&gt;
]]></script>
</div></div><h3 id="SharedFileSystemMasterSlave-Startup">Startup</h3><p>On startup one master grabs an exclusive lock on the broker file directory - all other brokers are slaves and pause waiting for the exclusive lock.</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="shared-file-system-master-slave.data/Startup.png" data-image-src="/confluence/download/attachments/35958/Startup.png?version=1&amp;modificationDate=1153806958000&amp;api=v2" data-unresolved-comment-count="0" data-linked-resource-id="3240" data-linked-resource-version="1" data-linked-resource-type="attachment" data-linked-resource-default-alias="Startup.png" data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png" data-linked-resource-container-id="35958" data-linked-resource-container-version="22"></span></p><p>Clients should be using the <a shape="rect" href="failover-transport-reference.xml">Failover Transport</a> to connect to the available brokers. e.g. using a URL something like the following</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: java; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[failover:(tcp://broker1:61616,tcp://broker2:61616,tcp://broker3:61616)
]]></script>
</div></div><p>Only the master broker starts up its transport connectors and so the clients can only connect to the master.</p><h3 id="SharedFileSystemMasterSlave-Masterfailure">Master failure</h3><p>If the master looses the exclusive lock then it immediately shuts down. If a master shuts down or fails, one of the other slaves will grab the lock and so the topology switches to the following diagram</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="shared-file-system-master-slave.data/MasterFailed.png" data-image-src="/confluence/download/attachments/35958/MasterFailed.png?version=1&amp;modificationDate=1153806959000&amp;api=v2" data-unresolved-comment-count="0" data-linked-resource-id="3255" data-linked-resource-version="1" data-linked-resource-type="attachment" data-linked-resource-default-alias="MasterFailed.png" data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png" data-linked-resource-container-id="35958" data-linked-resource-container-version="22"></span></p><p>One of the other other slaves immediately grabs the exclusive lock on the file system to them commences becoming the master, starting all of its transport connectors.</p><p>Clients loose connection to the stopped master and then the failover transport tries to connect to the available brokers - of which the only one available is the new master.</p><h3 id="SharedFileSystemMasterSlave-Masterrestart">Master restart</h3><p>At any time you can restart other brokers which join the cluster and start as slaves waiting to become a master if the master is shutdown or a failure occurs. So the following topology is created after a restart of an old master...</p><p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="shared-file-system-master-slave.data/MasterRestarted.png" data-image-src="/confluence/download/attachments/35958/MasterRestarted.png?version=1&amp;modificationDate=1153806958000&amp;api=v2" data-unresolved-comment-count="0" data-linked-resource-id="3247" data-linked-resource-version="1" data-linked-resource-type="attachment" data-linked-resource-default-alias="MasterRestarted.png" data-base-url="https://cwiki.apache.org/confluence" data-linked-resource-content-type="image/png" data-linked-resource-container-id="35958" data-linked-resource-container-version="22"></span></p><h3 id="SharedFileSystemMasterSlave-SchedulerSupport">Scheduler Support</h3><p>ActiveMQ maintains information about schedules independent to the settings in the persistence adapter. With a shared file-system it is therefore important to tell ActiveMQ expressly where to store scheduler information. To do this, set the&#160;<code>dataDirectory</code> attribute on the&#160;<code>broker</code>, for example:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<script class="brush: xml; gutter: false; theme: Default" type="syntaxhighlighter"><![CDATA[&lt;broker xmlns=&quot;http://activemq.apache.org/schema/core&quot;
dataDirectory=&quot;/some/location&quot;
brokerName=&quot;mmuserb2&quot; useJmx=&quot;true&quot; advisorySupport=&quot;false&quot;
persistent=&quot;true&quot; deleteAllMessagesOnStartup=&quot;false&quot;
useShutdownHook=&quot;false&quot; schedulerSupport=&quot;true&quot;&gt;]]></script>
</div></div></div>