---
title: Set up InfluxDB Clustered
description: Learn how to set up InfluxDB Clustered for the “Get started with InfluxDB” tutorial and for general use.
url: https://docs.influxdata.com/influxdb3/clustered/get-started/setup/
estimated_tokens: 1466
publisher: InfluxData
canonical: https://docs.influxdata.com/influxdb3/clustered/get-started/setup/
date: '2026-05-15T15:46:14-06:00'
lastmod: '2026-05-15T15:46:14-06:00'
---

* 1 / 3

As you get started with this tutorial, do the following to make sure everything
you need is in place.

* [Install and configure your InfluxDB cluster](#install-and-configure-your-influxdb-cluster)
* [Download, install, and configure the influxctl CLI](#download-install-and-configure-the-influxctl-cli)
* [Create a database](#create-a-database)
* [Create a database token](#create-a-database-token)
* [Configure authentication credentials](#configure-authentication-credentials)

## Install and configure your InfluxDB cluster

Follow the [Install InfluxDB Clustered](/influxdb3/clustered/install/) guide to
install prerequisites and set up your cluster.

## Download, install, and configure the influxctl CLI

The [`influxctl` CLI](/influxdb3/clustered/reference/cli/influxctl/)lets you manage your InfluxDB cluster from a
command line and perform administrative tasks such as managing
databases and tokens.

1. [Download and install the `influxctl` CLI](/influxdb3/clustered/reference/cli/influxctl/#download-and-install-influxctl).

2. **Create a connection profile and provide your InfluxDB Clustered connection credentials**.

   The `influxctl` CLI uses [connection profiles](/influxdb3/clustered/reference/cli/influxctl/#configure-connection-profiles)to connect to and authenticate with your InfluxDB cluster.

   Create a file named `config.toml` at the following location depending on
   your operating system.

   |Operating system|       Default profile configuration file path       |
   |----------------|-----------------------------------------------------|
   |     Linux      |          `~/.config/influxctl/config.toml`          |
   |     macOS      |`~/Library/Application Support/influxctl/config.toml`|
   |    Windows     |          `%APPDATA%\influxctl\config.toml`          |

   > [!Note]
> If stored at a non-default location, include the `--config` flag with each`influxctl` command and provide the path to your profile configuration file.

3. **Copy and paste the sample configuration profile code** into your `config.toml`:

```toml
[[profile]]
  name = "default"
  product = "clustered"
  host = "cluster-host.com"
  port = "PORT"

[profile.auth.oauth2]
  client_id = "OAUTH_CLIENT_ID"
  scopes = [""]
  token_url = "OAUTH_TOKEN_URL"
  device_url = "OAUTH_DEVICE_URL"
```

Replace the following with your InfluxDB Clustered credentials:

* `PORT`: the port to use to access your InfluxDB cluster
* `OAUTH_CLIENT_ID`: the client URL of your OAuth2 provider
  (for example: `https://identityprovider/oauth2/v2/token`)
* `OAUTH_DEVICE_ID`: the device URL of your OAuth2 provider
  (for example: `https://identityprovider/oauth2/v2/auth/device`)

*For detailed information about `influxctl` profiles, see[Configure connection profiles](/influxdb3/clustered/reference/cli/influxctl/#configure-connection-profiles)*.

## Create a database

Use the[`influxctl database create` command](/influxdb3/clustered/reference/cli/influxctl/database/create/)to create a database. You can use an existing database or create a new one
specifically for this getting started tutorial.*Examples in this getting started tutorial assume a database named `get-started`.*

#### Authenticate with your cluster

The first time you run an `influxctl` CLI command, you are directed
to login to your **OAuth provider**. Once logged in, your OAuth provider issues
a short-lived (1 hour) management token for the `influxctl` CLI that grants
administrative access to your InfluxDB cluster.

Provide the following:

* Database name.
* *Optional:* Database[retention period](/influxdb3/clustered/admin/databases/#retention-periods)as a duration value. If no retention period is specified, the default is infinite.

```sh
influxctl database create --retention-period 1y get-started
```

## Create a database token

Use the[`influxctl token create` command](/influxdb3/clustered/reference/cli/influxctl/token/create/)to create a database token with read and write permissions for your database.

Provide the following:

* Permission grants
  * `--read-database`: Grants read access to a database
  * `--write-database` Grants write access to a database

* Token description

```sh
influxctl token create \
  --read-database get-started \
  --write-database get-started \
  "Read/write token for get-started database"
```

The command returns the token ID and the token string.
Store the token string in a safe place.
You’ll need it later.**This is the only time the token string is available in plain text.**

#### Store secure tokens in a secret store

Token strings are returned *only* on token creation.
We recommend storing database tokens in a **secure secret store**.
For example, see how to [authenticate Telegraf using tokens in your OS secret store](https://github.com/influxdata/telegraf/tree/master/plugins/secretstores/os).

## Configure authentication credentials

Code samples in later sections assume you assigned the token string to an`INFLUX_TOKEN` environment variable–for example:

#### MacOS and Linux ####

```sh
export INFLUX_TOKEN=DATABASE_TOKEN
```

```powershell
$env:INFLUX_TOKEN = "DATABASE_TOKEN"
```

```
set INFLUX_TOKEN=DATABASE_TOKEN
# Make sure to include a space character at the end of this command.
```

Replace `DATABASE_TOKEN`with your [database token](#create-a-database-token) string.

[Get started](/influxdb3/clustered/get-started/)[Write data](/influxdb3/clustered/get-started/write/)

#### Related

* [Manage databases](/influxdb3/clustered/admin/databases/)
* [influxctl](/influxdb3/clustered/reference/cli/influxctl/)
| Operating system | Default profile configuration file path |
| --- | --- |
| Operating system | Default profile configuration file path |
| Linux | ~/.config/influxctl/config.toml |
| macOS | ~/Library/Application Support/influxctl/config.toml |
| Windows | %APPDATA%\influxctl\config.toml |