1# Keepalive
2
3gRPC sends http2 pings on the transport to detect if the connection is down. If
4the ping is not acknowledged by the other side within a certain period, the
5connection will be closed. Note that pings are only necessary when there's no
6activity on the connection.
7
8For how to configure keepalive, see
9https://godoc.org/google.golang.org/grpc/keepalive for the options.
10
11## Why do I need this?
12
13Keepalive can be useful to detect TCP level connection failures. A particular
14situation is when the TCP connection drops packets (including FIN). It would
15take the system TCP timeout (which can be 30 minutes) to detect this failure.
16Keepalive would allow gRPC to detect this failure much sooner.
17
18Another usage is (as the name suggests) to keep the connection alive. For
19example in cases where the L4 proxies are configured to kill "idle" connections.
20Sending pings would make the connections not "idle".
21
22## What should I set?
23
24It should be sufficient for most users to set [client
25parameters](https://godoc.org/google.golang.org/grpc/keepalive) as a [dial
26option](https://godoc.org/google.golang.org/grpc#WithKeepaliveParams).
27
28## What will happen?
29
30(The behavior described here is specific for gRPC-go, it might be slightly
31different in other languages.)
32
33When there's no activity on a connection (note that an ongoing stream results in
34__no activity__ when there's no message being sent), after `Time`, a ping will
35be sent by the client and the server will send a ping ack when it gets the ping.
36Client will wait for `Timeout`, and check if there's any activity on the
37connection during this period (a ping ack is an activity).
38
39## What about server side?
40
41Server has similar `Time` and `Timeout` settings as client. Server can also
42configure connection max-age. See [server
43parameters](https://godoc.org/google.golang.org/grpc/keepalive#ServerParameters)
44for details.
45
46### Enforcement policy
47
48[Enforcement
49policy](https://godoc.org/google.golang.org/grpc/keepalive#EnforcementPolicy) is
50a special setting on server side to protect server from malicious or misbehaving
51clients.
52
53Server sends GOAWAY with ENHANCE_YOUR_CALM and close the connection when bad
54behaviors are detected:
55 - Client sends too frequent pings
56 - Client sends pings when there's no stream and this is disallowed by server
57 config
View as plain text