<commit_before>---
version: 0.19
category: "Reference Docs"
title: "Clients"
next:
  url: "checks"
  text: "checks"
---

# Overview

This reference document provides information to help you:

- Understand what a Sensu client is
- Understand what a Sensu client does
- Write a Sensu client definition
- Manage the Sensu client process on Linux
- Manage the Sensu client process on Windows

# What are Sensu clients? {#what-are-sensu-clients}

Sensu clients are monitoring agents, running on every machine that needs to be monitored. The client is responsible for registering the machine with Sensu and executing monitoring checks. Each client has a set of subscriptions, a list of roles/responsibilities the machine has (e.g. webserver), these subscriptions determine which monitoring checks are executed. The Sensu client publishes every check execution result to the message bus to be processed elsewhere. Sensu clients publish keepalives every 20 seconds, to help detect machines in an unhealthy state. Client keepalives contain the local client definition, to update the client registry, and provide additional context in event data.

# Client definition

The following is an example Sensu client definition, a JSON configuration file located at `/etc/sensu/conf.d/client.json`. This client definition provides Sensu with information about the machine on which it resides. This is a production machine, running a web server and a database.

## Example client definition

~~~ json
{
  "client": {
    "name": "i-424242",
    "address": "8.8.8.8",
    "subscriptions": [
      "production",
      "webserver",
      "mysql"
    ]
  }
}
~~~

# Anatomy of a client definition

The client definition uses the `"client": {}` definition scope.

### Definition attributes

name
: description
  : A unique name for the client. The name cannot contain special characters or spaces.
: required
  : true
: type
  : String
: validation
  : `/^[\w\.-]+$/`
: example
  : ~~~ shell
    "name": "i-424242"
    ~~~

address
: description
  : An address to help identify and reach the client. This is only informational, usually an IP address or hostname.
: required
  : true
: type
  : String
: example
  : ~~~ shell
    "address": "8.8.8.8"
    ~~~

subscriptions
: description
  : An array of client subscriptions that check requests will be sent to. The array cannot be empty and its items must each be a string.
: required
  : true
: type
  : Array
: example
  : ~~~ shell
    "subscriptions": ["production", "webserver"]
    ~~~

safe_mode
: description
  : If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request and execute the check.
: required
  : false
: type
  : Boolean
: default
  : `false`
: example
  : ~~~ shell
    "safe_mode": true
    ~~~

redact
: description
  : Client definition attributes to redact (values) when logging and sending client keepalives.
: required
  : false
: type
  : Array
: default
  : ~~~ shell
    [
      "password", "<PASSWORD>", "<PASSWORD>",
      "api_key", "api_token", "access_key",
      "secret_key", "private_key",
      "secret"
    ]
    ~~~
: example
  : ~~~ shell
    "redact": ["password", "ec2_access_key", "ec2_secret_key"]
    ~~~

socket
: description
  : A set of attributes that configure the Sensu client socket.
: required
  : false
: type
  : Hash
: example
  : ~~~ shell
    "socket": {}
    ~~~

keepalive
: description
  : A set of attributes that configure the Sensu client keepalives.
: required
  : false
: type
  : Hash
: example
  : ~~~ shell
    "keepalive": {}
    ~~~

#### Socket attributes

bind
: description
  : The address to bind the Sensu client socket to.
: required
  : false
: type
  : String
: default
  : `127.0.0.1`
: example
  : ~~~ shell
    "bind": "0.0.0.0"
    ~~~

port
: description
  : The port the Sensu client socket listens on.
: required
  : false
: type
  : Integer
: default
  : `3030`
: example
  : ~~~ shell
    "port": 3031
    ~~~

#### Keepalive attributes

handler
: description
  : The Sensu event handler (name) to use for events created by keepalives.
: required<commit_msg>[keepalive-scope] mention client keepalive attribute scope<commit_after>---
version: 0.19
category: "Reference Docs"
title: "Clients"
next:
  url: "checks"
  text: "checks"
---

# Overview

This reference document provides information to help you:

- Understand what a Sensu client is
- Understand what a Sensu client does
- Write a Sensu client definition
- Manage the Sensu client process on Linux
- Manage the Sensu client process on Windows

# What are Sensu clients? {#what-are-sensu-clients}

Sensu clients are monitoring agents, running on every machine that needs to be monitored. The client is responsible for registering the machine with Sensu and executing monitoring checks. Each client has a set of subscriptions, a list of roles/responsibilities the machine has (e.g. webserver), these subscriptions determine which monitoring checks are executed. The Sensu client publishes every check execution result to the message bus to be processed elsewhere. Sensu clients publish keepalives every 20 seconds, to help detect machines in an unhealthy state. Client keepalives contain the local client definition, to update the client registry, and provide additional context in event data.

# Client definition

The following is an example Sensu client definition, a JSON configuration file located at `/etc/sensu/conf.d/client.json`. This client definition provides Sensu with information about the machine on which it resides. This is a production machine, running a web server and a database.

## Example client definition

~~~ json
{
  "client": {
    "name": "i-424242",
    "address": "8.8.8.8",
    "subscriptions": [
      "production",
      "webserver",
      "mysql"
    ]
  }
}
~~~

# Anatomy of a client definition

The client definition uses the `"client": {}` definition scope.

### Definition attributes

name
: description
  : A unique name for the client. The name cannot contain special characters or spaces.
: required
  : true
: type
  : String
: validation
  : `/^[\w\.-]+$/`
: example
  : ~~~ shell
    "name": "i-424242"
    ~~~

address
: description
  : An address to help identify and reach the client. This is only informational, usually an IP address or hostname.
: required
  : true
: type
  : String
: example
  : ~~~ shell
    "address": "8.8.8.8"
    ~~~

subscriptions
: description
  : An array of client subscriptions that check requests will be sent to. The array cannot be empty and its items must each be a string.
: required
  : true
: type
  : Array
: example
  : ~~~ shell
    "subscriptions": ["production", "webserver"]
    ~~~

safe_mode
: description
  : If safe mode is enabled for the client. Safe mode requires local check definitions in order to accept a check request and execute the check.
: required
  : false
: type
  : Boolean
: default
  : `false`
: example
  : ~~~ shell
    "safe_mode": true
    ~~~

redact
: description
  : Client definition attributes to redact (values) when logging and sending client keepalives.
: required
  : false
: type
  : Array
: default
  : ~~~ shell
    [
      "password", "<PASSWORD>", "<PASSWORD>",
      "api_key", "api_token", "access_key",
      "secret_key", "private_key",
      "secret"
    ]
    ~~~
: example
  : ~~~ shell
    "redact": ["password", "ec2_access_key", "ec2_secret_key"]
    ~~~

socket
: description
  : A set of attributes that configure the Sensu client socket.
: required
  : false
: type
  : Hash
: example
  : ~~~ shell
    "socket": {}
    ~~~

keepalive
: description
  : A set of attributes that configure the Sensu client keepalives.
: required
  : false
: type
  : Hash
: example
  : ~~~ shell
    "keepalive": {}
    ~~~

#### Socket attributes

The following attributes are configured within the `"socket": {}` client definition attribute scope.

bind
: description
  : The address to bind the Sensu client socket to.
: required
  : false
: type
  : String
: default
  : `127.0.0.1`
: example
  : ~~~ shell
    "bind": "0.0.0.0"
    ~~~

port
: description
  : The port the Sensu client socket listens on.
: required
  : false
: type
  : Integer
: default
  : `3030`
: example
  : ~~~ shell
    "port": 3031
    ~~~

#### Keepalive attributes

The following attributes are configured within the `"keepalive": {}` client definition attribute scope.

handler
: description
  : The Sensu event handler (name) to use for events created by keepalives.
: required
{'fraction_non_alphanumeric': 0.09913186297512905, 'fraction_numerical': 0.01055842327545753, 'mean_word_length': 3.405684754521964, 'pattern_counts': {'":': 30, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1851667', 'n_tokens_mistral': 2564, 'n_tokens_neox': 2466, 'n_words': 1016}