1--- 2layout: "docs" 3page_title: "Agent" 4sidebar_current: "docs-agent-running" 5description: |- 6 The Serf agent is the core process of Serf. The agent maintains membership information, propagates events, invokes event handlers, detects failures, and more. The agent must run on every node that is part of a Serf cluster. 7--- 8 9# Serf Agent 10 11The Serf agent is the core process of Serf. The agent maintains membership 12information, propagates events, invokes event handlers, detects failures, 13and more. The agent must run on every node that is part of a Serf cluster. 14 15## Running an Agent 16 17The agent is started with the `serf agent` command. This command blocks, 18running forever or until told to quit. The agent command takes a variety 19of configuration options but the defaults are usually good enough. When 20running `serf agent`, you should see output similar to that below: 21 22``` 23$ serf agent 24==> Starting Serf agent... 25==> Serf agent running! 26 Node name: 'mitchellh.local' 27 Bind addr: '0.0.0.0:7946' 28 RPC addr: '127.0.0.1:7373' 29 Encrypted: false 30 Snapshot: false 31 Profile: lan 32 33==> Log data will now stream in as it occurs: 34 352013/10/22 10:35:33 [INFO] Serf agent starting 362013/10/22 10:35:33 [INFO] serf: EventMemberJoin: mitchellh.local 127.0.0.1 372013/10/22 10:35:33 [INFO] Serf agent started 382013/10/22 10:35:33 [INFO] agent: Received event: member-join 39... 40``` 41 42There are six important components that `serf agent` outputs: 43 44* **Node name**: This is a unique name for the agent. By default this 45 is the hostname of the machine, but you may customize it to whatever 46 you'd like using the `-node` flag. 47 48* **Bind addr**: This is the address and port used for communication between 49 Serf agents in a cluster. Every Serf agent in a cluster does not have to 50 use the same port. 51 52* **RPC addr**: This is the address and port used for RPC communications 53 for other `serf` commands. Other Serf commands such as `serf members` 54 connect to a running agent and use RPC to query and control the agent. 55 By default, this binds only to localhost on the default port. If you 56 change this address, you'll have to specify an `-rpc-addr` to commands 57 such as `serf members` so they know how to talk to the agent. This is also 58 the address other applications can use over [RPC to control Serf](/docs/agent/rpc.html). 59 60* **Encrypted**: This shows if Serf is encrypting all traffic that it 61 sends and expects to receive. It is a good sanity check to avoid sending 62 non-encrypted traffic over any public networks. You can read more about 63 [encryption here](/docs/agent/encryption.html). 64 65* **Snapshot**: This shows if Serf snapshotting is enabled. The snapshot 66 file enables Serf to automatically re-join a cluster after failure and 67 prevents replay of events that have already been seen. It requires storing 68 state on disk, and [must be configured](/docs/agent/options.html) 69 using a CLI flag or in the configuration directory. If it is not provided, 70 other nodes will still attempt to reconnect on recovery, however the node 71 will take longer to join the cluster and will replay old events. 72 73* **Profile**: The profile controls various timing values which should 74 be appropriate to the environment Serf is running in. It defaults to 75 optimizing for a LAN environment, but can also be set for WAN or 76 local-only communication. The profile can be set in 77 the [configuration](/docs/agent/options.html). 78 79## Stopping an Agent 80 81An agent can be stopped in two ways: gracefully or forcefully. To gracefully 82halt an agent, send the process an interrupt signal, which is usually 83`Ctrl-C` from a terminal. When gracefully exiting, the agent first notifies 84the cluster it intends to leave the cluster. This way, other cluster members 85notify the cluster that the node has _left_. 86 87Alternatively, you can force kill the agent by sending it a kill signal. 88When force killed, the agent ends immediately. The rest of the cluster will 89eventually (usually within seconds) detect that the node has died and will 90notify the cluster that the node has _failed_. 91 92The difference between a node _failing_ and a node _leaving_ may not be 93important for your use case. For example, for a web server and load 94balancer setup, both result in the same action: remove the web node 95from the load balancer pool. But for other situations, you may handle 96each scenario differently. 97