### Install Key Command Response

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example response after successfully installing a new encryption key.

```json
{
        "Messages": {
            "node1": "message from node1",
            "node2": "message from node2"
        },
        "NumErr": 0,
        "NumNodes": 2,
        "NumResp": 2
    }
```

--------------------------------

### Install Key Command Request

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example request to install a new encryption key.

```json
{"Key": "5K9OtfP7efFrNKe5WCQvXvnaXJ5cWP0SvXiwe0kkjM4="}
```

--------------------------------

### Verify Serf Installation

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/getting-started/install.html.markdown

After installing Serf, verify the installation worked by opening a new terminal session and checking that `serf` is available. By executing `serf` you should see help output similar to that below:

```bash
$ serf
usage: serf [--version] [--help] <command> [<args>]

Available commands are:
    agent           Runs a Serf agent
    event           Send a custom event through the Serf cluster
    force-leave     Forces a member of the cluster to enter the "left" state
    info            Provides debugging information for operators
    join            Tell Serf agent to join cluster
    keygen          Generates a new encryption key
    keys            Manipulate the internal encryption keyring used by Serf
    leave           Gracefully leaves the Serf cluster and shuts down
    members         Lists the members of a Serf cluster
    monitor         Stream logs from a Serf agent
    query           Send a query to the Serf cluster
    reachability    Test network reachability
    tags            Modify tags of a running Serf agent
    version         Prints the Serf version

```

--------------------------------

### Example Configuration File

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/options.html.markdown

An example of a Serf agent configuration file in JSON format.

```json
{
  "tags": {
    "role": "load-balancer",
    "datacenter": "east"
  },
  "event_handlers": [
    "handle.sh",
    "user:deploy=deploy.sh"
  ]
}
```

--------------------------------

### Simple Observability with Serf Queries

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/use-cases.html.markdown

Serf provides a query mechanism for simple request/response. This example shows how to query all nodes in a cluster to get their load averages by calling the 'uptime' command.

```bash
serf query load
```

--------------------------------

### Start the cluster

Source: https://github.com/hashicorp/serf/blob/master/demo/vagrant-cluster/README.md

Command to start the Vagrant cluster.

```bash
$ vagrant up
```

--------------------------------

### Example Keyring File

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/options.html.markdown

An example of a Serf keyring file, which is a JSON-formatted text file containing encryption keys.

```javascript
[
  "HvY8ubRZMgafUOWvrOadwOckVa1wN3QWAo46FVKbVN8=",
  "T9jncgl9mbLus+baTTa7q7nPSUrXwbDi2dhbtqir37s=",
  "5K9OtfP7efFrNKe5WCQvXvnaXJ5cWP0SvXiwe0kkjM4="
]
```

--------------------------------

### Start First Serf Agent

Source: https://github.com/hashicorp/serf/blob/master/README.md

Starts the first Serf agent in a terminal session.

```bash
$ serf agent -node=foo -bind=127.0.0.1:5000 -rpc-addr=127.0.0.1:7373
...
```

--------------------------------

### Installing Serf command-line agent

Source: https://github.com/hashicorp/serf/blob/master/README.md

Command to install the Serf command-line agent independently.

```bash
go get -u github.com/hashicorp/serf/cmd/serf
```

--------------------------------

### Install Serf using Homebrew on OS X

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/getting-started/install.html.markdown

If you are using homebrew as a package manager, than you can install serf as simple as:

```bash
brew install serf

```

--------------------------------

### Help for a specific command

Source: https://github.com/hashicorp/serf/blob/master/docs/commands/index.html.markdown

To get help for any specific command, pass the `-h` flag to the relevant subcommand. For example, to see help about the `members` subcommand.

```bash
$ serf members -h
Usage: serf members [options]

  Outputs the members of a running Serf agent.

Options:

  -rpc-addr=127.0.0.1:7373  RPC address of the Serf agent.

```

--------------------------------

### Starting Serf Agent with Event Handler

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/getting-started/event-handlers.html.markdown

Command to start a Serf agent with debug logging and a specified event handler script.

```bash
$ serf agent -log-level=debug -event-handler=handler.sh
==> Starting Serf agent...
==> Serf agent running!
    Node name: 'foobar'
    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
```

--------------------------------

### RTT Command Output Example

Source: https://github.com/hashicorp/serf/blob/master/docs/commands/rtt.html.markdown

Examples of the output from the 'serf rtt' command when coordinates are available.

```bash
$ serf rtt n1 n2
Estimated n1 <-> n2 rtt: 0.610 ms

$ serf rtt n2 # Running from n1
Estimated n1 <-> n2 rtt: 0.610 ms
```

--------------------------------

### Starting the Serf Agent

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/getting-started/agent.html.markdown

This command starts a single Serf agent and shows the initial log output, indicating the agent is running and has joined the cluster.

```bash
$ serf agent
==> Starting Serf agent...
==> Serf agent running!
    Node name: 'foobar'
    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/21 18:57:15 [INFO] Serf agent starting
2013/10/21 18:57:15 [INFO] serf: EventMemberJoin: mitchellh.local 10.0.1.60
2013/10/21 18:57:15 [INFO] Serf agent started
2013/10/21 18:57:15 [INFO] agent: Received event: member-join

```

--------------------------------

### Start the second agent

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/getting-started/join.html.markdown

Starts the second Serf agent on the new node, setting the bind address to match the IP of the second node.

```bash
$ serf agent -node=agent-two -bind=172.20.20.11
...
```

--------------------------------

### Shell Forking Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/event-handlers.html.markdown

Example of forking a background process in shell, redirecting output to /dev/null and detaching.

```shell
sleep 5 &>/dev/null &
```

--------------------------------

### Starting the Serf Agent

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/basics.html.markdown

The agent is started with the `serf agent` command. This command blocks, running forever or until told to quit. The agent command takes a variety of configuration options but the defaults are usually good enough. When running `serf agent`, you should see output similar to that below:

```bash
$ serf agent
==> Starting Serf agent...
==> Starting Serf agent RPC...
==> Serf agent running!
 Node name: 'mitchellh.local' 
 Bind addr: '0.0.0.0:7946' 
 RPC addr: '127.0.0.1:7373' 
 Encrypted: false 
 Snapshot: false 
 Profile: lan 
 Message Compression Enabled: true 

==> Log data will now stream in as it occurs: 

2013/10/22 10:35:33 [INFO] Serf agent starting
2013/10/22 10:35:33 [INFO] serf: EventMemberJoin: mitchellh.local 127.0.0.1
2013/10/22 10:35:33 [INFO] Serf agent started
2013/10/22 10:35:33 [INFO] agent: Received event: member-join
...
```

--------------------------------

### Request Header Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of a request header format for RPC communication.

```json
{"Command": "handshake", "Seq": 0}
```

--------------------------------

### Response Header Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of a response header format for RPC communication.

```json
{"Seq": 0, "Error": ""}
```

--------------------------------

### Start Second Serf Agent

Source: https://github.com/hashicorp/serf/blob/master/README.md

Starts the second Serf agent in another terminal session.

```bash
$ serf agent -node=bar -bind=127.0.0.1:5001 -rpc-addr=127.0.0.1:7374
...
```

--------------------------------

### Start the first agent

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/getting-started/join.html.markdown

Starts the first Serf agent on the first node, specifying a unique node name and a bind address accessible by other nodes.

```bash
$ serf agent -node=agent-one -bind=172.20.20.10
...
```

--------------------------------

### Ruby Forking Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/event-handlers.html.markdown

Example of detaching a process in Ruby by reopening stdout and stderr to /dev/null.

```ruby
$stdout.reopen('/dev/null', 'w')
$stderr.reopen('/dev/null', 'w')
```

--------------------------------

### Start Serf Agent with Uptime Tag

Source: https://github.com/hashicorp/serf/blob/master/docs/recipes/agent-uptime.html.markdown

This command starts a Serf agent and adds a tag 'start_time' with the current UNIX timestamp.

```shell
serf agent -tag start_time=`date +%s`
```

--------------------------------

### Membership Event Data Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/event-handlers.html.markdown

Example of the data format for membership-related events, showing member name, address, role, and tags.

```shell
mitchellh.local    127.0.0.1    web    role=web,datacenter=east
```

--------------------------------

### Respond Command Request

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example request to subscribe to queries and then respond.

```json
{"ID": 1023, "Payload": "my response"}
```

--------------------------------

### Auth Request Body Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of an authentication request body, including the authorization key.

```json
{"AuthKey": "my-secret-auth-token"}
```

--------------------------------

### Event Request Body Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of an event request body, used for firing new user events.

```json
{"Name": "foo", "Payload": "test payload", "Coalesce": true}
```

--------------------------------

### Sending an Event

Source: https://github.com/hashicorp/serf/blob/master/docs/commands/event.html.markdown

Example of sending an event with a name.

```bash
serf event NAME
```

--------------------------------

### Python Forking Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/event-handlers.html.markdown

Example of detaching a process in Python by reopening stdout and stderr to /dev/null.

```python
out_log = file('/dev/null', 'a+')
os.dup2(out_log.fileno(), sys.stdout.fileno())
os.dup2(out_log.fileno(), sys.stderr.fileno())
```

--------------------------------

### Go Example: Compute Distance Between Coordinates

Source: https://github.com/hashicorp/serf/blob/master/docs/internals/coordinates.html.markdown

A complete example in Go showing how to compute the distance between two coordinates using the Vivaldi algorithm.

```go
import (
    "github.com/hashicorp/serf/coordinate"
    "math"
    "time"
)

func dist(a *coordinate.Coordinate, b *coordinate.Coordinate) time.Duration {
    // Coordinates will always have the same dimensionality, so this is
    // just a sanity check.
    if len(a.Vec) != len(b.Vec) {
        panic("dimensions aren't compatible")
    }

    // Calculate the Euclidean distance plus the heights.
    sumsq := 0.0
    for i := 0; i < len(a.Vec); i++ {
        diff := a.Vec[i] - b.Vec[i]
        sumsq += diff * diff
    }
    rtt := math.Sqrt(sumsq) + a.Height + b.Height

    // Apply the adjustment components, guarding against negatives.
    adjusted := rtt + a.Adjustment + b.Adjustment
    if adjusted > 0.0 {
        rtt = adjusted
    }

    return time.Duration(rtt) * time.Second
}
```

--------------------------------

### Stream Command Response - Query Event Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of a 'query' event message received via the 'stream' command.

```json
    {
        "Event": "query",
        "ID": 1023,
        "LTime": 125,
        "Name": "load",
        "Payload": "15m",
    }
```

--------------------------------

### Stream Command Response - User Event Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of a 'user' event message received via the 'stream' command.

```json
    {
        "Event": "user",
        "LTime": 123,
        "Name": "deploy",
        "Payload": "9c45b87",
        "Coalesce": true,
    }
```

--------------------------------

### Query Command Request

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example request to issue a new query with various filters and options.

```json
{
        "FilterNodes": ["foo", "bar"],
        "FilterTags": {"role": ".*web.*"},
	    "RequestAck": true,
        "Timeout": 0,
        "Name": "load",
        "Payload": "15m"
    }
```

--------------------------------

### Sending an Event with Payload

Source: https://github.com/hashicorp/serf/blob/master/docs/commands/event.html.markdown

Example of sending an event with a name and a payload.

```bash
serf event deploy 1234567890
```

--------------------------------

### Monitor Command Response with Log

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of log messages received after issuing a monitor command.

```json
{"Seq": 50, "Error": ""}
    {"Log": "2013/12/03 13:06:53 [INFO] agent: Received event: member-join"}
```

--------------------------------

### Monitor Command Request

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example request to subscribe to log messages from the Agent.

```json
{"LogLevel": "DEBUG"}
```

--------------------------------

### Building Serf

Source: https://github.com/hashicorp/serf/blob/master/README.md

Instructions on how to build the Serf executable after cloning the repository.

```bash
$ make
...
$ bin/serf
...
```

--------------------------------

### List of available commands

Source: https://github.com/hashicorp/serf/blob/master/docs/commands/index.html.markdown

To view a list of the available commands at any time, just run `serf` with no arguments.

```bash
$ serf
usage: serf [--version] [--help] <command> [<args>]

Available commands are:
    agent           Runs a Serf agent
    event           Send a custom event through the Serf cluster
    force-leave     Forces a member of the cluster to enter the "left" state
    info            Provides debugging information for operators
    join            Tell Serf agent to join cluster
    keygen          Generates a new encryption key
    keys            Manipulate the internal encryption keyring used by Serf
    leave           Gracefully leaves the Serf cluster and shuts down
    members         Lists the members of a Serf cluster
    monitor         Stream logs from a Serf agent
    query           Send a query to the Serf cluster
    reachability    Test network reachability
    rtt             Estimates network round trip time between nodes
    tags            Modify tags of a running Serf agent
    version         Prints the Serf version

```

--------------------------------

### Running Tests

Source: https://github.com/hashicorp/serf/blob/master/README.md

Command to run tests for Serf.

```bash
make test
```

--------------------------------

### Telemetry Output Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/telemetry.html.markdown

An example of the telemetry information dumped to stderr when a USR1 signal is sent to the Serf process.

```text
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.num_goroutines': 19.000
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.alloc_bytes': 755960.000
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.malloc_count': 7550.000
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.free_count': 4387.000
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.heap_objects': 3163.000
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.total_gc_pause_ns': 1151002.000
[2014-01-29 10:56:50 -0800 PST][G] 'serf-agent.runtime.total_gc_runs': 4.000
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.agent.ipc.accept': Count: 5 Sum: 5.000
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.agent.ipc.command': Count: 10 Sum: 10.000
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.serf.events': Count: 5 Sum: 5.000
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.serf.events.foo': Count: 4 Sum: 4.000
[2014-01-29 10:56:50 -0800 PST][C] 'serf-agent.serf.events.baz': Count: 1 Sum: 1.000
[2014-01-29 10:56:50 -0800 PST][S] 'serf-agent.memberlist.gossip': Count: 50 Min: 0.007 Mean: 0.020 Max: 0.041 Stddev: 0.007 Sum: 0.989
[2014-01-29 10:56:50 -0800 PST][S] 'serf-agent.serf.queue.Intent': Count: 10 Sum: 0.000
[2014-01-29 10:56:50 -0800 PST][S] 'serf-agent.serf.queue.Event': Count: 10 Min: 0.000 Mean: 2.500 Max: 5.000 Stddev: 2.121 Sum: 25.000
```

--------------------------------

### Enable Encryption

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/encryption.html.markdown

Start the Serf agent with the `-encrypt` flag and the generated key. The output will confirm if encryption is enabled.

```bash
$ serf agent -encrypt=pUqJrVyVRj5jsiYEkM/tFQYfWyJIv4s3XkvDwy7Cu5s=
==> Starting Serf agent...
==> Serf agent running!
    Node name: 'mitchellh.local'
    Bind addr: '0.0.0.0:7946'
     RPC addr: '127.0.0.1:7373'
    Encrypted: true
...
```

--------------------------------

### Force-Leave Request Body Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of a force-leave request body, used to remove failed nodes from a cluster.

```json
{"Node": "failed-node-name"}
```

--------------------------------

### Handshake Request Body Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of a handshake request body, specifying the client's IPC version.

```json
{"Version": 1}
```

--------------------------------

### Formatting Code

Source: https://github.com/hashicorp/serf/blob/master/README.md

Command to format code according to Go standards.

```bash
make format
```

--------------------------------

### Triggering Deploys with Serf Events

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/use-cases.html.markdown

Serf can send custom events to a Serf cluster. This example shows how to trigger a deploy across a cluster of web applications by sending a 'deploy' event.

```bash
serf event deploy
```

--------------------------------

### Stream Command Response - Member Join Event Example

Source: https://github.com/hashicorp/serf/blob/master/docs/agent/rpc.html.markdown

Example of a 'member-join' event message received via the 'stream' command.

```json
    {
        "Event": "member-join",
        "Members": [
            {
                "Name": "TestNode"
                "Addr": [127, 0, 0, 1],
                "Port": 5000,
                "Tags": {
                    "role": "test"
                },
                "Status": "alive",
                "ProtocolMin": 0,
                "ProtocolMax": 3,
                "ProtocolCur": 2,
                "DelegateMin": 0,
                "DelegateMax": 1,
                "DelegateCur": 1,
            },
            ...
        ]
    }
```

--------------------------------

### Check Serf Version and Protocol Support

Source: https://github.com/hashicorp/serf/blob/master/docs/upgrading.html.markdown

This command shows the Serf version and the agent protocol it supports, including the earliest protocol version it can understand.

```bash
serf -v
```

--------------------------------

### Example Event Handler Script

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/getting-started/event-handlers.html.markdown

A basic shell script that outputs the event type and any data received via stdin.

```bash
#!/bin/bash

echo
echo "New event: ${SERF_EVENT}. Data follows..."
while read line; do
    printf "${line}\n"
done
```

--------------------------------

### Serf Leave Usage

Source: https://github.com/hashicorp/serf/blob/master/docs/commands/leave.html.markdown

Shows the basic usage of the serf leave command.

```bash
Usage: serf leave
```

--------------------------------

### Sending a custom event

Source: https://github.com/hashicorp/serf/blob/master/docs/intro/getting-started/user-events.html.markdown

This command sends a custom event named 'hello-there' to the Serf cluster.

```bash
$ serf event hello-there
```