mirror of https://github.com/hashicorp/consul
35 lines
7.3 KiB
HTML
35 lines
7.3 KiB
HTML
<!DOCTYPE html> <html lang=en> <head> <meta charset=utf-8> <meta name=viewport content="width=device-width, initial-scale=1.0"> <meta name=description content=""> <meta name=author content=""> <title>Event Handlers - Serf</title> <link href="/stylesheets/bootstrap.min-82fe1490.css" media=screen rel=stylesheet /><link href="/stylesheets/main-e5014f86.css" media=screen rel=stylesheet /> <!--[if lt IE 9]><script src="/javascripts/html5shiv-310dd184.js"></script> <script src="/javascripts/respond.min-88c91176.js"></script><![endif]--> <script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-45101516-1', 'serfdom.io');
|
|
ga('send', 'pageview');
|
|
|
|
</script> </head> <body class="page-Event Handlers"> <div id=header> <div class=container> <a class="navbar-brand logo" href="/"> <span></span> </a> <a class="navbar-brand text rls-l" href="/">SERF</a> <ul class="buttons nav navbar-nav navbar-right rls-sb"> <li class=first><a href="/downloads.html">Download</a></li> <li><a href="https://github.com/hashicorp/serf">Github</a></li> </ul> <ul class="main-links nav navbar-nav navbar-right rls-sb"> <li><a href="/intro/index.html">Intro</a></li> <li><a href="/docs/index.html">Docs</a></li> <li><a href="/community.html">Community</a></li> </ul> </div> </div> <div class=container> <div class=col-md-4> <div class="docs-sidebar hidden-print affix-top" role=complementary> <ul class="nav docs-sidenav"> <li> <a href="/intro/index.html">What is Serf?</a> </li> <li> <a href="/intro/use-cases.html">Use Cases</a> </li> <li> <a href="/intro/vs-other-sw.html">Serf vs. Other Software</a> <ul class=nav> <li> <a href="/intro/vs-zookeeper.html">ZooKeeper, doozerd, etcd</a> </li> <li> <a href="/intro/vs-chef-puppet.html">Chef, Puppet, etc.</a> </li> <li> <a href="/intro/vs-fabric.html">Fabric</a> </li> <li> <a href="/intro/vs-custom.html">Custom Solutions</a> </li> </ul> </li> <li class=active> <a href="/intro/getting-started/install.html">Getting Started</a> <ul class=nav> <li> <a href="/intro/getting-started/install.html">Install Serf</a> </li> <li> <a href="/intro/getting-started/agent.html">Run the Agent</a> </li> <li> <a href="/intro/getting-started/join.html">Join a Cluster</a> </li> <li class=active> <a href="/intro/getting-started/event-handlers.html">Event Handlers</a> </li> <li> <a href="/intro/getting-started/user-events.html">Custom User Events</a> </li> <li> <a href="/intro/getting-started/next-steps.html">Next Steps</a> </li> </ul> </li> </ul> </div> </div> <div class=col-md-8 role=main> <div class=bs-docs-section> <h1 id=toc_0>Event Handlers</h1> <p>We've now seen how to start Serf agents and join them into a cluster. While this is cool to see on its own, the true power and utility of Serf is being able to react to membership changes and other events that Serf invokes. By specifying <em>event handlers</em>, Serf will invoke custom scripts whenever an event is received.</p> <h2 id=toc_1>Our First Event Handler</h2> <p>To start, let's create our first event handler. Create a shell script named <code>handler.sh</code> with the following contents and make sure that it is set to be executable (<code>chmod +x handler.sh</code>).</p> <pre><code class="bash">#!/bin/bash
|
|
|
|
echo
|
|
echo "New event: ${SERF_EVENT}. Data follows..."
|
|
while read line; do
|
|
printf "${line}\n"
|
|
done
|
|
</code></pre> <p>This will be the script that we'll tell Serf to invoke for any event. The script outputs the event, which Serf puts into the <code>SERF_EVENT</code> environmental variable. The data for a Serf event always comes in via stdin, so the script then reads stdin and outputs any data it received.</p> <p>By sending data to stdin, Serf works extremely well with standard Unix tools such as <code>grep</code>, <code>sed</code>, <code>awk</code>, etc. Shell commands work when specifying event handlers, so by using standard Unix methodologies, complex event handlers can often be built up without resorting to custom scripts.</p> <h2 id=toc_2>Specifying an Event Handler</h2> <p>With the event handler written, let's start an agent with that event handler. By setting the log-level to "debug", Serf will output the stdout/stderr of the event handlers, so we can see them being run:</p> <pre><code>$ serf agent -log-level=debug -event-handler=handler.sh
|
|
==> Starting Serf agent...
|
|
==> Serf agent running!
|
|
Node name: ''
|
|
Bind addr: '0.0.0.0:7946'
|
|
RPC addr: '127.0.0.1:7373'
|
|
|
|
==> Log data will now stream in as it occurs:
|
|
|
|
2013/10/22 06:54:04 [INFO] Serf agent starting
|
|
2013/10/22 06:54:04 [INFO] serf: EventMemberJoin: mitchellh 127.0.0.1
|
|
2013/10/22 06:54:04 [INFO] Serf agent started
|
|
2013/10/22 06:54:04 [INFO] agent: Received event: member-join
|
|
2013/10/22 06:54:04 [DEBUG] Event 'member-join' script output:
|
|
New event: member-join. Data follows...
|
|
mitchellh.local 127.0.0.1
|
|
</code></pre> <p>As you can see from the tail end of the output, the event script was executed and displayed the event that was run along with the data of that event. In this case, the event was a "member-join" event and the data was a single member, ourself.</p> <p>In practice, an event script would do something like adding a web server to a load balancer, monitoring that node with Nagios, etc.</p> <h2 id=toc_3>Types of Events</h2> <p>There are currently four types of events that Serf invokes:</p> <ul> <li><code>member-join</code> - One or more members have joined the cluster.</li> <li><code>member-leave</code> - One or more members have gracefully left the cluster.</li> <li><code>member-failed</code> - One or more members have failed, meaning that they didn't properly respond to ping requests.</li> <li><code>user</code> - A custom user event, covered later in this guide.</li> </ul> <h2 id=toc_4>Multiple Event Scripts, Filtering, And More</h2> <p>For the purposes of introduction, we showed how to use a single event handler with Serf. This event handler responded to all events. However, the event handling system is actually far more robust: Serf is able to invoke multiple event handlers as well as invoke certain event handlers for only certain Serf events.</p> <p>To learn more about these features, see the full documentation section of <a href="/docs/agent/event-handlers.html">event handlers</a>.</p> </div> </div> </div> <div id=footer> <div class=container> <div class=footer-links> <ul class="main-links nav navbar-nav rls-sb"> <li><a href="/intro/index.html">Intro</a></li> <li class=active><a href="/docs/index.html">Docs</a></li> <li><a href="/community.html">Community</a></li> </ul> <ul class="buttons nav navbar-nav rls-sb"> <li class=first><a href="/downloads.html">Download</a></li> <li><a href="https://github.com/hashicorp/serf">Github</a></li> </ul> </div> <div class=footer-logo> <span></span> </div> <div class="footer-hashi os"> <span>© 2013. A <a href="//www.hashicorp.com">HashiCorp</a> Project.</span> <a href="//www.hashicorp.com"><img src="/images/hashi-logo-s-3644fe63.png"></a> </div> </div> </div> <script src="javascripts/lib/d3.v3.min.js"></script> <script src="javascripts/app/deploy/site.js"></script> <script>
|
|
Serf.initialize();
|
|
</script> </body> </html> |