github.com/Jeffail/benthos/v3@v3.65.0/website/docs/components/inputs/nats_stream.md

---
title: nats_stream
type: input
status: stable
categories: ["Services"]
---

<!--
     THIS FILE IS AUTOGENERATED!

     To make changes please edit the contents of:
     lib/input/nats_stream.go
-->

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';


Subscribe to a NATS Stream subject. Joining a queue is optional and allows
multiple clients of a subject to consume using queue semantics.


<Tabs defaultValue="common" values={[
  { label: 'Common', value: 'common', },
  { label: 'Advanced', value: 'advanced', },
]}>

<TabItem value="common">

```yaml
# Common config fields, showing default values
input:
  label: ""
  nats_stream:
    urls:
      - nats://127.0.0.1:4222
    cluster_id: test-cluster
    client_id: benthos_client
    queue: benthos_queue
    subject: benthos_messages
    durable_name: benthos_offset
    unsubscribe_on_close: false
```

</TabItem>
<TabItem value="advanced">

```yaml
# All config fields, showing default values
input:
  label: ""
  nats_stream:
    urls:
      - nats://127.0.0.1:4222
    cluster_id: test-cluster
    client_id: benthos_client
    queue: benthos_queue
    subject: benthos_messages
    durable_name: benthos_offset
    unsubscribe_on_close: false
    start_from_oldest: true
    max_inflight: 1024
    ack_wait: 30s
    tls:
      enabled: false
      skip_cert_verify: false
      enable_renegotiation: false
      root_cas: ""
      root_cas_file: ""
      client_certs: []
    auth:
      nkey_file: ""
      user_credentials_file: ""
```

</TabItem>
</Tabs>

Tracking and persisting offsets through a durable name is also optional and
works with or without a queue. If a durable name is not provided then subjects
are consumed from the most recently published message.

When a consumer closes its connection it unsubscribes, when all consumers of a
durable queue do this the offsets are deleted. In order to avoid this you can
stop the consumers from unsubscribing by setting the field
`unsubscribe_on_close` to `false`.

### Metadata

This input adds the following metadata fields to each message:

``` text
- nats_stream_subject
- nats_stream_sequence
```

You can access these metadata fields using
[function interpolation](/docs/configuration/interpolation#metadata).

### Authentication

There are several components within Benthos which utilise NATS services. You will find that each of these components
support optional advanced authentication parameters for [NKeys](https://docs.nats.io/nats-server/configuration/securing_nats/auth_intro/nkey_auth)
and [User Credentials](https://docs.nats.io/developing-with-nats/security/creds).

An in depth tutorial can be found [here](https://docs.nats.io/developing-with-nats/tutorials/jwt).

#### NKey file

The NATS server can use these NKeys in several ways for authentication. The simplest is for the server to be configured
with a list of known public keys and for the clients to respond to the challenge by signing it with its private NKey
configured in the `nkey_file` field.

More details [here](https://docs.nats.io/developing-with-nats/security/nkey).

#### User Credentials file

NATS server supports decentralized authentication based on JSON Web Tokens (JWT). Clients need an [user JWT](https://docs.nats.io/nats-server/configuration/securing_nats/jwt#json-web-tokens)
and a corresponding [NKey secret](https://docs.nats.io/developing-with-nats/security/nkey) when connecting to a server
which is configured to use this authentication scheme.

The `user_credentials_file` field should point to a file containing both the private key and the JWT and can be
generated with the [nsc tool](https://docs.nats.io/nats-tools/nsc).

More details [here](https://docs.nats.io/developing-with-nats/security/creds).

## Fields

### `urls`

A list of URLs to connect to. If an item of the list contains commas it will be expanded into multiple URLs.


Type: `array`  
Default: `["nats://127.0.0.1:4222"]`  

```yaml
# Examples

urls:
  - nats://127.0.0.1:4222

urls:
  - nats://username:password@127.0.0.1:4222
```

### `cluster_id`

The ID of the cluster to consume from.


Type: `string`  
Default: `"test-cluster"`  

### `client_id`

A client ID to connect as.


Type: `string`  
Default: `"benthos_client"`  

### `queue`

The queue to consume from.


Type: `string`  
Default: `"benthos_queue"`  

### `subject`

A subject to consume from.


Type: `string`  
Default: `"benthos_messages"`  

### `durable_name`

Preserve the state of your consumer under a durable name.


Type: `string`  
Default: `"benthos_offset"`  

### `unsubscribe_on_close`

Whether the subscription should be destroyed when this client disconnects.


Type: `bool`  
Default: `false`  

### `start_from_oldest`

If a position is not found for a queue, determines whether to consume from the oldest available message, otherwise messages are consumed from the latest.


Type: `bool`  
Default: `true`  

### `max_inflight`

The maximum number of unprocessed messages to fetch at a given time.


Type: `int`  
Default: `1024`  

### `ack_wait`

An optional duration to specify at which a message that is yet to be acked will be automatically retried.


Type: `string`  
Default: `"30s"`  

### `tls`

Custom TLS settings can be used to override system defaults.


Type: `object`  

### `tls.enabled`

Whether custom TLS settings are enabled.


Type: `bool`  
Default: `false`  

### `tls.skip_cert_verify`

Whether to skip server side certificate verification.


Type: `bool`  
Default: `false`  

### `tls.enable_renegotiation`

Whether to allow the remote server to repeatedly request renegotiation. Enable this option if you're seeing the error message `local error: tls: no renegotiation`.


Type: `bool`  
Default: `false`  
Requires version 3.45.0 or newer  

### `tls.root_cas`

An optional root certificate authority to use. This is a string, representing a certificate chain from the parent trusted root certificate, to possible intermediate signing certificates, to the host certificate.


Type: `string`  
Default: `""`  

```yaml
# Examples

root_cas: |-
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
```

### `tls.root_cas_file`

An optional path of a root certificate authority file to use. This is a file, often with a .pem extension, containing a certificate chain from the parent trusted root certificate, to possible intermediate signing certificates, to the host certificate.


Type: `string`  
Default: `""`  

```yaml
# Examples

root_cas_file: ./root_cas.pem
```

### `tls.client_certs`

A list of client certificates to use. For each certificate either the fields `cert` and `key`, or `cert_file` and `key_file` should be specified, but not both.


Type: `array`  
Default: `[]`  

```yaml
# Examples

client_certs:
  - cert: foo
    key: bar

client_certs:
  - cert_file: ./example.pem
    key_file: ./example.key
```

### `tls.client_certs[].cert`

A plain text certificate to use.


Type: `string`  
Default: `""`  

### `tls.client_certs[].key`

A plain text certificate key to use.


Type: `string`  
Default: `""`  

### `tls.client_certs[].cert_file`

The path to a certificate to use.


Type: `string`  
Default: `""`  

### `tls.client_certs[].key_file`

The path of a certificate key to use.


Type: `string`  
Default: `""`  

### `auth`

Optional configuration of NATS authentication parameters.


Type: `object`  

### `auth.nkey_file`

An optional file containing a NKey seed.


Type: `string`  
Default: `""`  

```yaml
# Examples

nkey_file: ./seed.nk
```

### `auth.user_credentials_file`

An optional file containing user credentials which consist of an user JWT and corresponding NKey seed.


Type: `string`  
Default: `""`  

```yaml
# Examples

user_credentials_file: ./user.creds
```