diff --git a/website/source/docs/agent/checks.html.markdown b/website/source/docs/agent/checks.html.markdown index 19789910e7..336b6e99fb 100644 --- a/website/source/docs/agent/checks.html.markdown +++ b/website/source/docs/agent/checks.html.markdown @@ -31,6 +31,20 @@ There are three different kinds of checks: It is possible to configure a custom HTTP check timeout value by specifying the `timeout` field in the check definition. +* TCP + Interval - These checks make an TCP connection attempt every Interval + (e.g. every 30 seconds) to the specified IP/hostname and port. The status of + the service depends on whether the connection attempt is successful (ie - the + port is currently accepting connections). If the connection is accepted, the + status is `success`, otherwise the status is `critical`. In the case of a + hostname that resolves to both IPv4 and IPv6 addresses, an attempt will be + made to both addresses, and the first successful connection attempt will + result in a successful check. This type of check should be preferred over a + script that uses `netcat` or another external process to check a simple socket + operation. By default, TCP checks will be configured with a request timeout + equal to the check interval, with a max of 10 seconds. It is possible to + configure a custom TCP check timeout value by specifying the `timeout` field + in the check definition. + * Time to Live (TTL) - These checks retain their last known state for a given TTL. The state of the check must be updated periodically over the HTTP interface. If an external system fails to update the status within a given TTL, the check is @@ -75,6 +89,20 @@ A HTTP check: } ``` +A TCP check: + +```javascript +{ + "check": { + "id": "ssh", + "name": "SSH TCP on port 22", + "tcp": "localhost:22", + "interval": "10s", + "timeout": "1s" + } +} +``` + A TTL check: ```javascript @@ -102,7 +130,7 @@ Checks may also contain a `token` field to provide an ACL token. This token is used for any interaction with the catalog for the check, including [anti-entropy syncs](/docs/internals/anti-entropy.html) and deregistration. -Both script and HTTP checks must include an `interval` field. This field is +Script, TCP and HTTP checks must include an `interval` field. This field is parsed by Go's `time` package, and has the following [formatting specification](http://golang.org/pkg/time/#ParseDuration): > A duration string is a possibly signed sequence of decimal numbers, each with diff --git a/website/source/docs/agent/http/agent.html.markdown b/website/source/docs/agent/http/agent.html.markdown index 0b16d5bc3f..4f3670b715 100644 --- a/website/source/docs/agent/http/agent.html.markdown +++ b/website/source/docs/agent/http/agent.html.markdown @@ -224,8 +224,8 @@ The endpoint always returns 200. The register endpoint is used to add a new check to the local agent. There is more documentation on checks [here](/docs/agent/checks.html). -Checks may be of script, HTTP, or TTL type. The agent is responsible for managing -the status of the check and keeping the Catalog in sync. +Checks may be of script, HTTP, TCP, or TTL type. The agent is responsible for +managing the status of the check and keeping the Catalog in sync. The register endpoint expects a JSON request body to be PUT. The request body must look like: @@ -237,13 +237,14 @@ body must look like: "Notes": "Ensure we don't oversubscribe memory", "Script": "/usr/local/bin/check_mem.py", "HTTP": "http://example.com", + "TCP": "example.com:22", "Interval": "10s", "TTL": "15s" } ``` -The `Name` field is mandatory, as is one of `Script`, `HTTP` or `TTL`. -`Script` and `HTTP` also require that `Interval` be set. +The `Name` field is mandatory, as is one of `Script`, `HTTP`, `TCP` or `TTL`. +`Script`, `TCP` and `HTTP` also require that `Interval` be set. If an `ID` is not provided, it is set to `Name`. You cannot have duplicate `ID` entries per agent, so it may be necessary to provide an `ID`. @@ -258,6 +259,14 @@ be a URL) every `Interval`. If the response is any `2xx` code, the check is `pas If the response is `429 Too Many Requests`, the check is `warning`. Otherwise, the check is `critical`. +An `TCP` check will perform an TCP connection attempt against the value of `TCP` +(expected to be an IP/hostname and port combination) every `Interval`. If the +connection attempt is successful, the check is `passing`. If the connection +attempt is unsuccessful, the check is `critical`. In the case of a hostname +that resolves to both IPv4 and IPv6 addresses, an attempt will be made to both +addresses, and the first successful connection attempt will result in a +successful check. + If a `TTL` type is used, then the TTL update endpoint must be used periodically to update the state of the check. diff --git a/website/source/docs/agent/services.html.markdown b/website/source/docs/agent/services.html.markdown index 79327201c6..1b589b31b0 100644 --- a/website/source/docs/agent/services.html.markdown +++ b/website/source/docs/agent/services.html.markdown @@ -62,13 +62,14 @@ the DNS interface as well. If a service is failing its health check or a node has any failing system-level check, the DNS interface will omit that node from any service query. -The check must be of the script, HTTP, or TTL type. If it is a script type, `script` -and `interval` must be provided. If it is a HTTP type, `http` and -`interval` must be provided. If it is a TTL type, then only `ttl` must be -provided. The check name is automatically generated as -`service:`. If there are multiple service checks registered, the -ID will be generated as `service::` where `` is an -incrementing number starting from `1`. +The check must be of the script, HTTP, TCP or TTL type. If it is a script type, +`script` and `interval` must be provided. If it is a HTTP type, `http` and +`interval` must be provided. If it is a TCP type, `tcp` and `interval` must be +provided. If it is a TTL type, then only `ttl` must be provided. The check name +is automatically generated as `service:`. If there are multiple +service checks registered, the ID will be generated as +`service::` where `` is an incrementing number starting +from `1`. Note: there is more information about [checks here](/docs/agent/checks.html).