github.com/outbrain/consul@v1.4.5/website/source/intro/getting-started/agent.html.md (about) 1 --- 2 layout: "intro" 3 page_title: "Run the Agent" 4 sidebar_current: "gettingstarted-agent" 5 description: > 6 The Consul agent can run in either server or client mode. Each datacenter 7 must have at least one server, though a cluster of 3 or 5 servers is 8 recommended. A single server deployment is highly discouraged in production 9 as data loss is inevitable in a failure scenario. 10 --- 11 12 # Run the Consul Agent 13 14 After Consul is installed, the agent must be run. The agent can run either 15 in server or client mode. Each datacenter must have at least one server, 16 though a cluster of 3 or 5 servers is recommended. A single server deployment 17 is _**highly**_ discouraged as data loss is inevitable in a failure scenario. 18 19 All other agents run in client mode. A client is a very lightweight 20 process that registers services, runs health checks, and forwards queries to 21 servers. The agent must be running on every node that is part of the cluster. 22 23 For more detail on bootstrapping a datacenter, see 24 [this guide](/docs/guides/bootstrapping.html). 25 26 ## Starting the Agent 27 28 For simplicity, we'll start the Consul agent in development mode for now. This 29 mode is useful for bringing up a single-node Consul environment quickly and 30 easily. It is **not** intended to be used in production as it does not persist 31 any state. 32 33 ```text 34 -$ consul agent -dev 35 ==> Starting Consul agent... 36 ==> Starting Consul agent RPC... 37 ==> Consul agent running! 38 Version: 'v0.7.0' 39 Node name: 'Armons-MacBook-Air' 40 Datacenter: 'dc1' 41 Server: true (bootstrap: false) 42 Client Addr: 127.0.0.1 (HTTP: 8500, HTTPS: -1, DNS: 8600, RPC: 8400) 43 Cluster Addr: 127.0.0.1 (LAN: 8301, WAN: 8302) 44 Gossip encrypt: false, RPC-TLS: false, TLS-Incoming: false 45 46 ==> Log data will now stream in as it occurs: 47 48 2016/09/15 10:21:10 [INFO] raft: Initial configuration (index=1): [{Suffrage:Voter ID:127.0.0.1:8300 Address:127.0.0.1:8300}] 49 2016/09/15 10:21:10 [INFO] raft: Node at 127.0.0.1:8300 [Follower] entering Follower state (Leader: "") 50 2016/09/15 10:21:10 [INFO] serf: EventMemberJoin: Armons-MacBook-Air 127.0.0.1 51 2016/09/15 10:21:10 [INFO] serf: EventMemberJoin: Armons-MacBook-Air.dc1 127.0.0.1 52 2016/09/15 10:21:10 [INFO] consul: Adding LAN server Armons-MacBook-Air (Addr: tcp/127.0.0.1:8300) (DC: dc1) 53 2016/09/15 10:21:10 [INFO] consul: Adding WAN server Armons-MacBook-Air.dc1 (Addr: tcp/127.0.0.1:8300) (DC: dc1) 54 2016/09/15 10:21:13 [DEBUG] http: Request GET /v1/agent/services (180.708µs) from=127.0.0.1:52369 55 2016/09/15 10:21:13 [DEBUG] http: Request GET /v1/agent/services (15.548µs) from=127.0.0.1:52369 56 2016/09/15 10:21:17 [WARN] raft: Heartbeat timeout from "" reached, starting election 57 2016/09/15 10:21:17 [INFO] raft: Node at 127.0.0.1:8300 [Candidate] entering Candidate state in term 2 58 2016/09/15 10:21:17 [DEBUG] raft: Votes needed: 1 59 2016/09/15 10:21:17 [DEBUG] raft: Vote granted from 127.0.0.1:8300 in term 2. Tally: 1 60 2016/09/15 10:21:17 [INFO] raft: Election won. Tally: 1 61 2016/09/15 10:21:17 [INFO] raft: Node at 127.0.0.1:8300 [Leader] entering Leader state 62 2016/09/15 10:21:17 [INFO] consul: cluster leadership acquired 63 2016/09/15 10:21:17 [DEBUG] consul: reset tombstone GC to index 3 64 2016/09/15 10:21:17 [INFO] consul: New leader elected: Armons-MacBook-Air 65 2016/09/15 10:21:17 [INFO] consul: member 'Armons-MacBook-Air' joined, marking health alive 66 2016/09/15 10:21:17 [INFO] agent: Synced service 'consul' 67 ``` 68 69 As you can see, the Consul agent has started and has output some log 70 data. From the log data, you can see that our agent is running in server mode 71 and has claimed leadership of the cluster. Additionally, the local member has 72 been marked as a healthy member of the cluster. 73 74 ~> **Note for OS X Users:** Consul uses your hostname as the 75 default node name. If your hostname contains periods, DNS queries to 76 that node will not work with Consul. To avoid this, explicitly set 77 the name of your node with the `-node` flag. 78 79 ## Cluster Members 80 81 If you run [`consul members`](/docs/commands/members.html) in another terminal, you 82 can see the members of the Consul cluster. We'll cover joining clusters in the next 83 section, but for now, you should only see one member (yourself): 84 85 ```text 86 $ consul members 87 Node Address Status Type Build Protocol DC 88 Armons-MacBook-Air 172.20.20.11:8301 alive server 0.6.1dev 2 dc1 89 ``` 90 91 The output shows our own node, the address it is running on, its 92 health state, its role in the cluster, and some version information. 93 Additional metadata can be viewed by providing the `-detailed` flag. 94 95 The output of the [`members`](/docs/commands/members.html) command is based on 96 the [gossip protocol](/docs/internals/gossip.html) and is eventually consistent. 97 That is, at any point in time, the view of the world as seen by your local 98 agent may not exactly match the state on the servers. For a strongly consistent 99 view of the world, use the [HTTP API](/api/index.html) as it forwards the 100 request to the Consul servers: 101 102 ```text 103 $ curl localhost:8500/v1/catalog/nodes 104 [{"Node":"Armons-MacBook-Air","Address":"127.0.0.1","TaggedAddresses":{"lan":"127.0.0.1","wan":"127.0.0.1"},"CreateIndex":4,"ModifyIndex":110}] 105 ``` 106 107 In addition to the HTTP API, the [DNS interface](/docs/agent/dns.html) can 108 be used to query the node. Note that you have to make sure to point your DNS 109 lookups to the Consul agent's DNS server which runs on port 8600 by default. 110 The format of the DNS entries (such as "Armons-MacBook-Air.node.consul") will 111 be covered in more detail later. 112 113 ```text 114 $ dig @127.0.0.1 -p 8600 Armons-MacBook-Air.node.consul 115 ... 116 117 ;; QUESTION SECTION: 118 ;Armons-MacBook-Air.node.consul. IN A 119 120 ;; ANSWER SECTION: 121 Armons-MacBook-Air.node.consul. 0 IN A 127.0.0.1 122 ``` 123 124 ## <a name="stopping"></a>Stopping the Agent 125 126 You can use `Ctrl-C` (the interrupt signal) to gracefully halt the agent. 127 After interrupting the agent, you should see it leave the cluster 128 and shut down. 129 130 By gracefully leaving, Consul notifies other cluster members that the 131 node _left_. If you had forcibly killed the agent process, other members 132 of the cluster would have detected that the node _failed_. When a member leaves, 133 its services and checks are removed from the catalog. When a member fails, 134 its health is simply marked as critical, but it is not removed from the catalog. 135 Consul will automatically try to reconnect to _failed_ nodes, allowing it 136 to recover from certain network conditions, while _left_ nodes are no longer contacted. 137 138 Additionally, if an agent is operating as a server, a graceful leave is important 139 to avoid causing a potential availability outage affecting the 140 [consensus protocol](/docs/internals/consensus.html). See the 141 [guides section](/docs/guides/index.html) for details on how to safely add 142 and remove servers. 143 144 ## Next Steps 145 146 Your simple Consul cluster is up and running. Let's give it some 147 [services](services.html)!