Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

InfluxDB 3.4 offline tokens (#6346) 

* update: add 3.4 notes

* update: 3.4 notes

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* Update content/shared/v3-core-enterprise-release-notes/_index.md

Co-authored-by: Scott Anderson <sanderson@users.noreply.github.com>

* feat(influxdb-3.4): added cli updates for influxdb 3.4

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix: add whitespace to influxdb3 write doc

* feat(offline-tokens): add offline tokens to config options page

* feat(offline-tokens): add task-based offline token docs

* fix(links): fixed broken links and added TOC to offline tokens guide

* Apply suggestions from code review

Co-authored-by: マルコメ <akio.muto@bnt.benextgroup.jp>

* chore(offline-tokens): add token string security standards

* chore(offline-tokens): add note about token string prefix

---------

Co-authored-by: Peter Barnett <peter.barnett03@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: マルコメ <akio.muto@bnt.benextgroup.jp>
remotes/jaal2001/patch-2
Scott Anderson 2025-08-28 07:03:03 -06:00 committed by GitHub
parent e32a8f62cf
commit 3222c7a9fb
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 739 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
.vscode/settings.json vendored
View File

@ -15,6 +15,7 @@
"vale.valeCLI.config": "${workspaceFolder}/.vale.ini",
"vale.valeCLI.minAlertLevel": "warning",
"cSpell.words": [
"influxctl"
"influxctl",
"preconfigured"
]
}

17
content/influxdb3/core/admin/tokens/admin/preconfigured.md Normal file
View File

@ -0,0 +1,17 @@
---
title: Use a preconfigured admin token
description: >
Start {{% product-name %}} with a preconfigured "offline" admin token file.
If no admin tokens already exist, InfluxDB automatically creates an admin token
using the provided admin token file.
menu:
influxdb3_core:
parent: Admin tokens
name: Use preconfigured admin token
weight: 202
source: /shared/influxdb3-admin/tokens/admin/preconfigured.md
---
<!-- The content for this page is at
// SOURCE content/shared/influxdb3-admin/tokens/admin/preconfigured.md
-->

2
content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md
View File

@ -1,5 +1,5 @@
---
title: influxdb3 create token --admin
title: influxdb3 create token \--admin
description: >
The `influxdb3 create token --admin` subcommand creates an operator token or named admin token with full administrative privileges for server actions.
menu:

4
content/influxdb3/core/reference/cli/influxdb3/serve.md
View File

@ -38,13 +38,17 @@ influxdb3 serve [OPTIONS] --node-id <HOST_IDENTIFIER_PREFIX>
| | `--object-store` | _See [configuration options](/influxdb3/core/reference/config-options/#object-store)_ |
| | `--admin-token-recovery-http-bind` | _See [configuration options](/influxdb3/core/reference/config-options/#admin-token-recovery-http-bind)_ |
| | `--admin-token-recovery-tcp-listener-file-path` | _See [configuration options](/influxdb3/core/reference/config-options/#admin-token-recovery-tcp-listener-file-path)_ |
| | `--admin-token-file` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#admin-token-file)_ |
| | `--aws-access-key-id` | _See [configuration options](/influxdb3/core/reference/config-options/#aws-access-key-id)_ |
| | `--aws-allow-http` | _See [configuration options](/influxdb3/core/reference/config-options/#aws-allow-http)_ |
| | `--aws-credentials-file` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-credentials-file)_ |
| | `--aws-default-region` | _See [configuration options](/influxdb3/core/reference/config-options/#aws-default-region)_ |
| | `--aws-endpoint` | _See [configuration options](/influxdb3/core/reference/config-options/#aws-endpoint)_ |
| | `--aws-secret-access-key` | _See [configuration options](/influxdb3/core/reference/config-options/#aws-secret-access-key)_ |
| | `--aws-session-token` | _See [configuration options](/influxdb3/core/reference/config-options/#aws-session-token)_ |
| | `--aws-skip-signature` | _See [configuration options](/influxdb3/core/reference/config-options/#aws-skip-signature)_ |
| | `--azure-allow-http` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#azure-allow-http)_ |
| | `--azure-endpoint` | _See [configuration options](/influxdb3/enterprise/reference/config-options/##azure-endpoint)_ |
| | `--azure-storage-access-key` | _See [configuration options](/influxdb3/core/reference/config-options/#azure-storage-access-key)_ |
| | `--azure-storage-account` | _See [configuration options](/influxdb3/core/reference/config-options/#azure-storage-account)_ |
| | `--bucket` | _See [configuration options](/influxdb3/core/reference/config-options/#bucket)_ |

17
content/influxdb3/enterprise/admin/tokens/admin/preconfigured.md Normal file
View File

@ -0,0 +1,17 @@
---
title: Use a preconfigured admin token
description: >
Start {{% product-name %}} with a preconfigured "offline" admin token file.
If no admin tokens already exist, InfluxDB automatically creates an admin token
using the provided admin token file.
menu:
influxdb3_enterprise:
parent: Admin tokens
name: Use preconfigured admin token
weight: 202
source: /shared/influxdb3-admin/tokens/admin/preconfigured.md
---
<!-- The content for this page is at
// SOURCE content/shared/influxdb3-admin/tokens/admin/preconfigured.md
-->

168
content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md Normal file
View File

@ -0,0 +1,168 @@
---
title: Use a preconfigured permission (resource) tokens
description: >
Start {{% product-name %}} with a preconfigured "offline" permission (resource) tokens file.
If no tokens already exist, InfluxDB automatically creates resource tokens
specified in the provided permissions (resource) tokens file.
menu:
influxdb3_enterprise:
parent: Resource tokens
name: Use preconfigured resource tokens
weight: 202
---
Start {{% product-name %}} with a preconfigured "offline" permission (resource) tokens file.
If no tokens already exist, InfluxDB automatically creates resource tokens
specified in the provided permission (resource) tokens file.
- [Generate an offline permissions (resource) tokens file](#generate-an-offline-permissions-resource-tokens-file)
- [Offline permission tokens file schema](#offline-permission-tokens-file-schema)
- [Start InfluxDB with the preconfigured permission tokens](#start-influxdb-with-the-preconfigured-permission-tokens)
## Generate an offline permissions (resource) tokens file
Use the `influxdb3 create token` command to generate an offline permission (resource)
tokens file. You can also specify corresponding databases to create when starting InfluxDB.
Include the following options:
{{% req type="key" %}}
- {{% req "\*" %}} `--name`: The name of the admin token
_(replace {{% code-placeholder-key %}}`TOKEN_NAME`{{% /code-placeholder-key %}})_
- {{% req "\*" %}} `--permissions`:
The [token permissions](/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission/#permission-format)
_(replace {{% code-placeholder-key %}}`TOKEN_PERMISSIONS`{{% /code-placeholder-key %}})_
- `--expiry`: Duration for the token to remain valid, in
[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)
format--for example `10d` for 10 days or `1y` for 1 year
_(replace {{% code-placeholder-key %}}`DURATION`{{% /code-placeholder-key %}})_
- {{% req "\*" %}} `--offline`
- `--create-databases`: Comma separated list of database names to
create when starting the server
_(replace {{% code-placeholder-key %}}`DATABASE_LIST`{{% /code-placeholder-key %}})_
- {{% req "\*" %}} `--output-file`: File path to use for the generated token file
_(replace {{% code-placeholder-key %}}`path/to/tokens.json`{{% /code-placeholder-key %}})_
<!-- pytest.mark.skip -->
```bash { placeholders="TOKEN_(NAME|PERMISSIONS)|DURATION|DATABASE_LIST|path/to/tokens.json" }
influxdb3 create token \
--name TOKEN_NAME \
--permission "TOKEN_PERMISSIONS" \
--expiry DURATION \
--offline \
--create-databases DATABASE_LIST \
--output-file path/to/tokens.json
```
> [!Note]
> #### Add multiple tokens to a permission tokens file
>
> If you write a new offline permission token to an existing permission token file,
> the command appends the new token to the existing output file.
>
> #### You can write or generate your own permission tokens file
>
> The `influxdb3 create token --offline` command makes generating an
> offline permission tokens file easy, but it is not required.
> You can write or generate your own permission tokens file using the
> [required JSON schema](#offline-permission-tokens-file-schema).
>
> ##### Token string security standards
>
> If writing or generating your own permission tokens file, ensure that token
> strings are sufficiently secure. We recommend the following:
>
> - Use a cryptographically secure pseudorandom number generator.
> - Ensure sufficient length and entropy. Generate and base64-encode a random
> string of at least 16 bytes (128 bits).
> - Prepend the generated string with `apiv3_` for InfluxDB compatibility.
> [!Important]
> #### Token file permissions
>
> Token file permissions should be restricted `0600` to protect the tokens.
### Offline permission tokens file schema
An offline permission tokens file is a JSON-formatted file that contains a single
object with the following fields:
- **create_databases**: <em class="op50">(Optional)</em>
_Array of database names to create when starting the server_
- **tokens**: _Array of token objects_
- **token**: The raw token string (must begin with `apiv3_`)
- **name**: A unique token name
- **expiry_millis**: <em class="op50">(Optional)</em> Token expiration time as a
millisecond Unix timestamp
- **permissions**: Array of [token permission](/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission/#permission-format) strings.
```json
{
"create_databases": [
"db1",
"db2",
"db3",
"db4"
],
"tokens": [
{
"token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
"name": "token-1",
"expiry_millis": 1756400061529,
"permissions": [
"db:db1,db2:read,write",
"db:db3:read"
]
},
{
"token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
"name": "token-2",
"expiry_millis": 1756400061529,
"permissions": [
"db:db4:read,write"
]
}
]
}
```
## Start InfluxDB with the preconfigured permission tokens
When starting {{% product-name %}}, include the `--permission-tokens-file`
option with the `influxdb3 serve` command or set the
`INFLUXDB3_PERMISSION_TOKENS_FILE` environment
variable to provide the preconfigured offline permission tokens file:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[CLI option](#)
[Environment variable](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash { placeholders="path/to/admin-token.json" }
influxdb3 serve \
# ... \
--permission-tokens-file path/to/admin-token.json
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash { placeholders="path/to/admin-token.json" }
INFLUXDB3_PERMISSION_TOKENS_FILE=path/to/admin-token.json
influxdb3 serve \
# ... \
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
When the server starts, you can use the preconfigured permission (resource) tokens
to write data to and query data from with your {{% product-name %}} instance or
cluster.

2
content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md
View File

@ -1,5 +1,5 @@
---
title: influxdb3 create token --admin
title: influxdb3 create token \--admin
description: >
The `influxdb3 create token --admin` subcommand creates an operator token or named admin token with full administrative privileges for server actions.
menu:

108
content/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission.md
View File

@ -1,5 +1,5 @@
---
title: influxdb3 create token --permission
title: influxdb3 create token \--permission
description: >
The `influxdb3 create token` command with the `--permission` option creates a new authentication token
with fine-grained access permissions for specific resources in {{< product-name >}}.
@ -25,19 +25,19 @@ influxdb3 create token --permission <PERMISSION> --name <NAME> [OPTIONS]
## Options
| Option | | Description |
| :----- | :----------- | :----------------------------- |
| | `--permission <PERMISSION>` | Permissions in `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example, `db:*:read,write`, `system:*:read`. `--permission` may be specified multiple times |
| | `--name <NAME>` | Name of the token |
| `-H` | `--host <HOST_URL>` | The host URL of the running InfluxDB 3 Enterprise server [env: INFLUXDB3_HOST_URL=] [default: http://127.0.0.1:8181] |
| | `--token <AUTH_TOKEN>` | The {{% token-link "enterprise" "admin" %}} [env: INFLUXDB3_AUTH_TOKEN=] |
| | `--expiry <DURATION>` | The token expiration time as a duration (for example, 1h, 7d, 1y). If not set, the token does not expire until revoked |
| | `--tls-ca <CA_CERT>` | An optional arg to use a custom CA for testing with self-signed certs [env: INFLUXDB3_TLS_CA=] |
| | `--format <FORMAT>` | Output format (`json` or `text` _(default)_) |
| `-h` | `--help` | Print help information |
| | `--help-all` | Print detailed help information |
| Option | | Description |
| :----- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| | `--permission <PERMISSION>` | Permissions in `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example, `db:*:read,write`, `system:*:read`. `--permission` may be specified multiple times |
| | `--name <NAME>` | Name of the token |
| `-H` | `--host <HOST_URL>` | The host URL of the running InfluxDB 3 Enterprise server [env: INFLUXDB3_HOST_URL=] [default: http://127.0.0.1:8181] |
| | `--token <AUTH_TOKEN>` | The {{% token-link "enterprise" "admin" %}} [env: INFLUXDB3_AUTH_TOKEN=] |
| | `--expiry <DURATION>` | The token expiration time as a duration (for example, 1h, 7d, 1y). If not set, the token does not expire until revoked |
| | `--tls-ca <CA_CERT>` | An optional arg to use a custom CA for testing with self-signed certs [env: INFLUXDB3_TLS_CA=] |
| | `--format <FORMAT>` | Output format (`json` or `text` _(default)_) |
| `-h` | `--help` | Print help information |
| | `--help-all` | Print detailed help information |
## Permission Format
## Permission format
The `--permission` option takes a value in the format `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS`.
@ -50,6 +50,16 @@ The `--permission` option takes a value in the format `RESOURCE_TYPE:RESOURCE_NA
## Examples
- [Create a token with read and write access to a database](#create-a-token-with-read-and-write-access-to-a-database)
- [Create a token with read-only access to a database](#create-a-token-with-read-only-access-to-a-database)
- [Create a token with access to multiple databases](#create-a-token-with-access-to-multiple-databases)
- [Create a token with access to all databases](#create-a-token-with-access-to-all-databases)
- [Create a token that expires in seven days](#create-a-token-that-expires-in-seven-days)
- [Create a system token for health information](#create-a-system-token-for-health-information)
- [Create a token with access to all system information](#create-a-token-with-access-to-all-system-information)
- [Create a token with multiple permissions](#create-a-token-with-multiple-permissions)
- [Generate an offline permission (resource) tokens file](#generate-an-offline-permission-resource-tokens-file)
### Create a token with read and write access to a database
```bash
@ -115,3 +125,75 @@ influxdb3 create token \
--permission "system:health:read" \
--name "Multi-permission token"
```
### Generate an offline permission (resource) tokens file
Generate an offline permission (resource) tokens file to use if no resource
tokens exist when the server starts. Once started, you can interact with the
server using the provided tokens. Offline permission tokens are designed to help
with automated deployments.
Include the following options:
- `--name` _({{% req %}})_
- `--permissions` _({{% req %}})_
- `--offline` _({{% req %}})_
- `--output-file` _({{% req %}})_
- `--create-databases` _(Optional)_
- `--expiry` _(Optional)_
<!-- pytest.mark.skip -->
```bash { placeholders="TOKEN_(NAME|PERMISSIONS)|DURATION|DATABASE_LIST|path/to/tokens.json" }
influxdb3 create token \
--name TOKEN_NAME \
--permission "TOKEN_PERMISSIONS" \
--expiry DURATION \
--offline \
--create-databases DATABASE_LIST \
--output-file path/to/tokens.json
```
Replace the following:
- {{% code-placeholder-key %}}`TOKEN_NAME`{{% /code-placeholder-key %}}:
Name for your offline permission token
- {{% code-placeholder-key %}}`TOKEN_PERMISSIONS`{{% /code-placeholder-key %}}:
[Token permissions](#permission-format).
- {{% code-placeholder-key %}}`DURATION`{{% /code-placeholder-key %}}:
Duration for the token to remain valid, in
[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)
format (for example, `10d` for 10 days or `1y` for 1 year).
- {{% code-placeholder-key %}}`DATABASE_LIST`{{% /code-placeholder-key %}}:
Comma-separated list of database names to create when starting the
{{% product-name %}} server using the generated tokens file
- {{% code-placeholder-key %}}`path/to/tokens.json`{{% /code-placeholder-key %}}:
File path to use for the generated tokens file
{{< expand-wrapper >}}
{{% expand "View example offline permission tokens file" %}}
```json
{
"create_databases": [
"db1",
"db2",
"db3"
],
"tokens": [
{
"token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
"name": "example-token",
"expiry_millis": 1756400061529,
"permissions": [
"db:db1,db2:read,write",
"db:db3:read"
]
}
]
}
```
{{% /expand %}}
{{< /expand-wrapper >}}
> [!Note]
> If you write a new offline permission token to an existing permission token file,
> the command appends the new token to the existing output file.

5
content/influxdb3/enterprise/reference/cli/influxdb3/serve.md
View File

@ -39,13 +39,17 @@ influxdb3 serve [OPTIONS] \
| :--------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
| | `--admin-token-recovery-http-bind` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#admin-token-recovery-http-bind)_ |
| | `--admin-token-recovery-tcp-listener-file-path` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#admin-token-recovery-tcp-listener-file-path)_ |
| | `--admin-token-file` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#admin-token-file)_ |
| | `--aws-access-key-id` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-access-key-id)_ |
| | `--aws-allow-http` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-allow-http)_ |
| | `--aws-credentials-file` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-credentials-file)_ |
| | `--aws-default-region` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-default-region)_ |
| | `--aws-endpoint` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-endpoint)_ |
| | `--aws-secret-access-key` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-secret-access-key)_ |
| | `--aws-session-token` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-session-token)_ |
| | `--aws-skip-signature` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#aws-skip-signature)_ |
| | `--azure-allow-http` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#azure-allow-http)_ |
| | `--azure-endpoint` | _See [configuration options](/influxdb3/enterprise/reference/config-options/##azure-endpoint)_ |
| | `--azure-storage-access-key` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#azure-storage-access-key)_ |
| | `--azure-storage-account` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#azure-storage-account)_ |
| | `--bucket` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#bucket)_ |
@ -111,6 +115,7 @@ influxdb3 serve [OPTIONS] \
| | `--parquet-mem-cache-prune-percentage` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#parquet-mem-cache-prune-percentage)_ |
| | `--parquet-mem-cache-query-path-duration` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#parquet-mem-cache-query-path-duration)_ |
| | `--parquet-mem-cache-size` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#parquet-mem-cache-size)_ |
| | `--permission-tokens-file` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#permission-tokens-file)_ |
| | `--plugin-dir` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#plugin-dir)_ |
| | `--preemptive-cache-age` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#preemptive-cache-age)_ |
| | `--query-file-limit` | _See [configuration options](/influxdb3/enterprise/reference/config-options/#query-file-limit)_ |

115
content/shared/influxdb3-admin/tokens/admin/preconfigured.md Normal file
View File

@ -0,0 +1,115 @@
Start {{% product-name %}} with a preconfigured "offline" admin token file.
If no admin tokens already exist, InfluxDB automatically creates an admin token
using the provided admin token file.
Offline tokens are designed to help with automated deployments.
- [Generate an offline admin token file](#generate-an-offline-admin-token-file)
- [Offline admin token file schema](#offline-admin-token-file-schema)
- [Start InfluxDB with the preconfigured admin token](#start-influxdb-with-the-preconfigured-admin-token)
## Generate an offline admin token file
Use the `influxdb3 create token --admin` command to generate an offline admin
token file. Include the following options:
{{% req type="key" %}}
- `--name`: The name of the admin token _(default is `_admin`)_
_(replace {{% code-placeholder-key %}}`TOKEN_NAME`{{% /code-placeholder-key %}})_
- `--expiry`: Duration for the token to remain valid, in
[humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html)
format (for example, `10d` for 10 days or `1y` for 1 year).
_(replace {{% code-placeholder-key %}}`DURATION`{{% /code-placeholder-key %}})_
- {{% req "\*" %}} `--offline`
- {{% req "\*" %}} `--output-file`: File path to use for the generated token file
_(replace {{% code-placeholder-key %}}`path/to/tokens.json`{{% /code-placeholder-key %}})_
<!-- pytest.mark.skip -->
```bash { placeholders="TOKEN_NAME|DURATION|path/to/admin-token.json" }
influxdb3 create token --admin \
--name TOKEN_NAME \
--expiry DURATION \
--offline \
--output-file path/to/admin-token.json
```
> [!Note]
> #### You can write or generate your own admin token file
>
> The `influxdb3 create token --admin --offline` command makes generating
> offline admin token files easy, but it is not required.
> You can also write or generate your own admin token files using the
> [required JSON schema](#offline-admin-token-file-schema).
>
> ##### Token string security standards
>
> If writing or generating your own admin token file, ensure that the token
> string is sufficiently secure. We recommend the following:
>
> - Use a cryptographically secure pseudorandom number generator.
> - Ensure sufficient length and entropy. Generate and base64-encode a random
> string of at least 16 bytes (128 bits).
> - Prepend the generated string with `apiv3_` for InfluxDB compatibility.
> [!Important]
> #### Token file permissions
>
> Token file permissions should be restricted `0600` to protect the token.
### Offline admin token file schema
An offline admin token file is a JSON-formatted file that contains a single
object with the following fields:
- **token**: The raw token string (must begin with `apiv3_`)
- **name**: The token name (default is `_admin`)
- **expiry_millis**: <em class="op50">(Optional)</em> Token expiration time as a
millisecond Unix timestamp
```json
{
"token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
"name": "_admin",
"expiry_millis": 1756400061529
}
```
## Start InfluxDB with the preconfigured admin token
When starting {{% product-name %}}, include the `--admin-token-file` option with the
`influxdb3 serve` command or set the `INFLUXDB3_ADMIN_TOKEN_FILE` environment
variable to provide the preconfigured offline admin token file:
{{< code-tabs-wrapper >}}
{{% code-tabs %}}
[CLI option](#)
[Environment variable](#)
{{% /code-tabs %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash { placeholders="path/to/admin-token.json" }
influxdb3 serve \
# ... \
--admin-token-file path/to/admin-token.json
```
{{% /code-tab-content %}}
{{% code-tab-content %}}
<!-- pytest.mark.skip -->
```bash { placeholders="path/to/admin-token.json" }
INFLUXDB3_ADMIN_TOKEN_FILE=path/to/admin-token.json
influxdb3 serve \
# ... \
```
{{% /code-tab-content %}}
{{< /code-tabs-wrapper >}}
When the server starts, you can use the preconfigured admin token to interact with
your {{% product-name %}}{{% show-in "enterprise" %}} cluster or{{% /show-in %}}
instance.

314
content/shared/influxdb3-cli/config-options.md
View File

@ -46,11 +46,6 @@ influxdb3 serve
- [node-id](#node-id)
{{% show-in "enterprise" %}} - [node-id-from-env](#node-id-from-env){{% /show-in %}}
- [object-store](#object-store)
- [tls-key](#tls-key)
- [tls-cert](#tls-cert)
- [tls-minimum-versions](#tls-minimum-version)
- [without-auth](#without-auth)
- [disable-authz](#disable-authz)
{{% show-in "enterprise" %}}
- [num-database-limit](#num-database-limit)
- [num-table-limit](#num-table-limit)
@ -59,6 +54,15 @@ influxdb3 serve
- [license-email](#license-email)
- [license-file](#license-file)
- [license-type](#license-type){{% /show-in %}}
- [Security](#security)
- [tls-key](#tls-key)
- [tls-cert](#tls-cert)
- [tls-minimum-versions](#tls-minimum-version)
- [without-auth](#without-auth)
- [disable-authz](#disable-authz)
- [admin-token-recovery-http-bind](#admin-token-recovery-http-bind)
- [admin-token-file](#admin-token-file)
{{% show-in "enterprise" %}}- [permission-tokens-file](#permission-tokens-file){{% /show-in %}}
- [AWS](#aws)
- [aws-access-key-id](#aws-access-key-id)
- [aws-secret-access-key](#aws-secret-access-key)
@ -113,7 +117,6 @@ influxdb3 serve
- [HTTP](#http)
- [max-http-request-size](#max-http-request-size)
- [http-bind](#http-bind)
- [admin-token-recovery-http-bind](#admin-token-recovery-http-bind)
- [Memory](#memory)
- [exec-mem-pool-bytes](#exec-mem-pool-bytes)
- [force-snapshot-mem-threshold](#force-snapshot-mem-threshold)
@ -295,8 +298,97 @@ This option supports the following values:
| :--------------------- | :----------------------- |
| `--object-store` | `INFLUXDB3_OBJECT_STORE` |
{{% show-in "enterprise" %}}
---
#### num-database-limit
Limits the total number of active databases.
Default is {{% influxdb3/limit "database" %}}.
| influxdb3 serve option | Environment variable |
| :---------------------- | :---------------------------------------- |
| `--num-database-limit` | `INFLUXDB3_ENTERPRISE_NUM_DATABASE_LIMIT` |
---
#### num-table-limit
Limits the total number of active tables across all databases.
Default is {{% influxdb3/limit "table" %}}.
| influxdb3 serve option | Environment variable |
| :--------------------- | :------------------------------------- |
| `--num-table-limit` | `INFLUXDB3_ENTERPRISE_NUM_TABLE_LIMIT` |
---
#### num-total-columns-per-table-limit
Limits the total number of columns per table.
Default is {{% influxdb3/limit "column" %}}.
| influxdb3 serve option | Environment variable |
| :------------------------------------ | :------------------------------------------------------- |
| `--num-total-columns-per-table-limit` | `INFLUXDB3_ENTERPRISE_NUM_TOTAL_COLUMNS_PER_TABLE_LIMIT` |
{{% /show-in %}}
---
{{% show-in "enterprise" %}}
### Licensing
#### license-email
Specifies the email address to associate with your {{< product-name >}} license
and automatically responds to the interactive email prompt when the server starts.
This option is mutually exclusive with [license-file](#license-file).
| influxdb3 serve option | Environment variable |
| :--------------------- | :----------------------------------- |
| `--license-email` | `INFLUXDB3_ENTERPRISE_LICENSE_EMAIL` |
---
#### license-file
Specifies the path to a license file for {{< product-name >}}. When provided, the license
file's contents are used instead of requesting a new license.
This option is mutually exclusive with [license-email](#license-email).
| influxdb3 serve option | Environment variable |
| :--------------------- | :----------------------------------- |
| `--license-file` | `INFLUXDB3_ENTERPRISE_LICENSE_FILE` |
---
#### license-type
Specifies the type of {{% product-name %}} license to use and bypasses the
interactive license prompt. Provide one of the following license types:
- `home`
- `trial`
- `commercial`
| influxdb3 serve option | Environment variable |
| :--------------------- | :----------------------------------- |
| `--license-type` | `INFLUXDB3_ENTERPRISE_LICENSE_TYPE` |
---
{{% /show-in %}}
### Security
- [tls-key](#tls-key)
- [tls-cert](#tls-cert)
- [tls-minimum-versions](#tls-minimum-version)
- [without-auth](#without-auth)
- [disable-authz](#disable-authz)
- [admin-token-recovery-http-bind](#admin-token-recovery-http-bind)
- [admin-token-file](#admin-token-file)
{{% show-in "enterprise" %}}- [permission-tokens-file](#permission-tokens-file){{% /show-in %}}
#### tls-key
The path to a key file for TLS to be enabled.
@ -349,43 +441,169 @@ Valid values are `health`, `ping`, and `metrics`.
| :--------------------- | :------------------------ |
| `--disable-authz` | `INFLUXDB3_DISABLE_AUTHZ` |
---
#### admin-token-recovery-http-bind
Enables an admin token recovery HTTP server on a separate port.
This server allows regenerating lost admin tokens without existing authentication.
The server automatically shuts down after a successful token regeneration.
> [!Warning]
> This option creates an unauthenticated endpoint that can regenerate admin tokens.
> Only use this when you have lost access to your admin token and ensure the
> server is only accessible from trusted networks.
**Default:** `127.0.0.1:8182` (when enabled)
| influxdb3 serve option | Environment variable |
| :--------------------------------- | :----------------------------------------- |
| `--admin-token-recovery-http-bind` | `INFLUXDB3_ADMIN_TOKEN_RECOVERY_HTTP_BIND` |
##### Example usage
```bash
# Start server with recovery endpoint
influxdb3 serve --admin-token-recovery-http-bind
# In another terminal, regenerate the admin token
influxdb3 create token --admin --regenerate --host http://127.0.0.1:8182
```
---
#### admin-token-file
Specifies an offline admin token file to use if no tokens exist when the server
starts. Once started, you can interact with the server using the provided token.
Offline admin tokens are designed to help with automated deployments.
| influxdb3 serve option | Environment variable |
| :--------------------- | :--------------------------- |
| `--admin-token-file` | `INFLUXDB3_ADMIN_TOKEN_FILE` |
Offline admin tokens are defined in a JSON-formatted file.
Use the following command to generate an offline admin token file:
<!-- pytest.mark.skip -->
```bash { placeholders="./path/to/admin-token.json" }
influxdb3 create token --admin \
--name "example-admin-token" \
--expiry 1d \
--offline \
--output-file ./path/to/admin-token.json
```
{{< expand-wrapper >}}
{{% expand "View example offline admin token file" %}}
```json
{
"token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
"name": "example-admin-token",
"expiry_millis": 1756400061529
}
```
{{% /expand %}}
{{< /expand-wrapper >}}
##### Example usage
<!-- pytest.mark.skip -->
```bash { placeholders="./path/to/admin-token.json" }
# Generate and admin token offline
influxdb3 create token \
--admin \
--name "example-admin-token" \
--expiry 1d \
--offline \
--output-file ./path/to/admin-token.json
# Start {{% product-name %}} using the generated token
influxdb3 serve --admin-token-file ./path/to/admin-token.json
```
---
{{% show-in "enterprise" %}}
---
#### permission-tokens-file
#### num-database-limit
Specifies an offline permission (resource) tokens file to use if no resource
tokens exist when the server starts. Once started, you can interact with the
server using the provided tokens. Offline permission tokens are designed to help
with automated deployments.
Limits the total number of active databases.
Default is {{% influxdb3/limit "database" %}}.
| influxdb3 serve option | Environment variable |
| :------------------------- | :--------------------------------- |
| `--permission-tokens-file` | `INFLUXDB3_PERMISSION_TOKENS_FILE` |
| influxdb3 serve option | Environment variable |
| :---------------------- | :---------------------------------------- |
| `--num-database-limit` | `INFLUXDB3_ENTERPRISE_NUM_DATABASE_LIMIT` |
Multiple tokens with database-level permissions can be defined.
You can also specify databases to create at startup.
Use the a command similar to the following to generate an offline permission
token file:
```bash { placeholders="./path/to/tokens.json" }
influxdb3 create token \
--name "example-token" \
--permission "db:db1,db2:read,write" \
--permission "db:db3:read" \
--expiry 1d \
--offline \
--create-databases db1,db2 \
--output-file ./path/to/tokens.json
```
{{< expand-wrapper >}}
{{% expand "View example offline permission tokens file" %}}
```json
{
"create_databases": [
"db1",
"db2",
"d3"
],
"tokens": [
{
"token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
"name": "example-token",
"expiry_millis": 1756400061529,
"permissions": [
"db:db1,db2:read,write",
"db:db3:read"
]
}
]
}
```
{{% /expand %}}
{{< /expand-wrapper >}}
> [!Note]
> If you write a new offline permission token to an existing permission token file,
> the command appends the new token to the existing output file.
##### Example usage
<!-- pytest.mark.skip -->
```bash { placeholders="./path/to/tokens.json" }
# Generate and admin token offline
influxdb3 create token \
--name "example-token" \
--permission "db:db1,db2:read,write" \
--permission "db:db3:read" \
--expiry 1d \
--offline \
--create-databases db1,db2 \
--output-file ./path/to/tokens.json
# Start {{% product-name %}} using the generated token
influxdb3 serve --permission-tokens-file ./path/to/tokens.json
```
---
#### num-table-limit
Limits the total number of active tables across all databases.
Default is {{% influxdb3/limit "table" %}}.
| influxdb3 serve option | Environment variable |
| :--------------------- | :------------------------------------- |
| `--num-table-limit` | `INFLUXDB3_ENTERPRISE_NUM_TABLE_LIMIT` |
---
#### num-total-columns-per-table-limit
Limits the total number of columns per table.
Default is {{% influxdb3/limit "column" %}}.
| influxdb3 serve option | Environment variable |
| :------------------------------------ | :------------------------------------------------------- |
| `--num-total-columns-per-table-limit` | `INFLUXDB3_ENTERPRISE_NUM_TOTAL_COLUMNS_PER_TABLE_LIMIT` |
{{% /show-in %}}
---
{{% show-in "enterprise" %}}
### Licensing
@ -1025,7 +1243,6 @@ Provides custom configuration to DataFusion as a comma-separated list of
- [max-http-request-size](#max-http-request-size)
- [http-bind](#http-bind)
- [admin-token-recovery-http-bind](#admin-token-recovery-http-bind)
#### max-http-request-size
@ -1051,31 +1268,6 @@ Defines the address on which InfluxDB serves HTTP API requests.
---
#### admin-token-recovery-http-bind
Enables an admin token recovery HTTP server on a separate port. This server allows regenerating lost admin tokens without existing authentication. The server automatically shuts down after a successful token regeneration.
> [!Warning]
> This option creates an unauthenticated endpoint that can regenerate admin tokens. Only use this when you have lost access to your admin token and ensure the server is only accessible from trusted networks.
**Default:** `127.0.0.1:8182` (when enabled)
| influxdb3 serve option | Environment variable |
| :--------------------- | :------------------- |
| `--admin-token-recovery-http-bind` | `INFLUXDB3_ADMIN_TOKEN_RECOVERY_HTTP_BIND` |
##### Example usage
```bash
# Start server with recovery endpoint
influxdb3 serve --admin-token-recovery-http-bind
# In another terminal, regenerate the admin token
influxdb3 create token --admin --regenerate --host http://127.0.0.1:8182
```
---
### Memory
- [exec-mem-pool-bytes](#exec-mem-pool-bytes)

79
content/shared/influxdb3-cli/create/token/admin.md
View File

@ -9,20 +9,27 @@ influxdb3 create token --admin [OPTIONS]
## Options {.no-shorthand}
| Option | Description |
|:-------|:------------|
| `--regenerate` | Regenerates the operator token. Requires `--token` and the current operator token |
| `--name <NAME>` | Name of the token |
| `--expiry <EXPIRY>` | Expires in `duration`--for example, 10d for 10 days 1y for 1 year |
| `--host <host>` | The host URL of the running InfluxDB 3 server [env: `INFLUXDB3_HOST_URL=`] [default: `http://127.0.0.1:8181`] |
| `--token <token>` | An existing admin token for the InfluxDB 3 server |
| `--tls-ca <tls-ca>` | An optional arg to use a custom ca for useful for testing with self signed certs |
| `--format <FORMAT>` | Output format for token [possible values: `json`, `text`] |
| `-h`, `--help` | Print help information |
| `--help-all` | Print more detailed help information |
| Option | Description |
| :-------------- | :------------------------------------------------------------------------------------------------------------ |
| `--regenerate` | Regenerates the operator token. Requires `--token` and the current operator token |
| `--name` | Name of the token |
| `--expiry` | Expires in `duration`--for example, 10d for 10 days 1y for 1 year |
| `--host` | The host URL of the running InfluxDB 3 server [env: `INFLUXDB3_HOST_URL=`] [default: `http://127.0.0.1:8181`] |
| `--token` | An existing admin token for the InfluxDB 3 server |
| `--tls-ca` | An optional arg to use a custom ca for useful for testing with self signed certs |
| `--format` | Output format for token [possible values: `json`, `text`] |
| `--offline` | Generate token without connecting to server (for automation) |
| `--output-file` | File path to save the token (required with `--offline`) |
| `-h`, `--help` | Print help information |
| `--help-all` | Print more detailed help information |
## Examples
- [Create an operator token](#create-an-operator-token)
- [Use the operator token to create a named admin token](#use-the-operator-token-to-create-a-named-admin-token)
- [Use the token to create a database](#use-the-token-to-create-a-database)
- [Generate an offline admin token](#generate-an-offline-admin-token)
### Create an operator token
The operator token is a special token that has full administrative privileges on the InfluxDB server and doesn't expire.
@ -40,17 +47,15 @@ For CLI commands, use the `--token` option or the `INFLUXDB3_AUTH_TOKEN` environ
### Use the operator token to create a named admin token
{{% code-placeholders "OPERATOR_TOKEN|TOKEN_NAME|EXPIRY" %}}
<!--pytest.mark.skip-->
```bash
```bash { placeholders="OPERATOR_TOKEN|TOKEN_NAME|EXPIRY" }
influxdb3 create token \
--admin \
--token OPERATOR_TOKEN \
--name TOKEN_NAME \
--expiry DURATION
```
{{% /code-placeholders %}}
Replace the following:
@ -60,16 +65,13 @@ Replace the following:
### Use the token to create a database
{{% code-placeholders "YOUR_ADMIN_TOKEN|DATABASE_NAME" %}}
<!--pytest.mark.skip-->
```bash
```bash { placeholders="YOUR_ADMIN_TOKEN|DATABASE_NAME" }
influxdb3 create database \
--token ADMIN_TOKEN \
DATABASE_NAME
```
{{% /code-placeholders %}}
Replace the following:
@ -83,3 +85,44 @@ Replace the following:
> ```bash
> export INFLUXDB3_AUTH_TOKEN=ADMIN_TOKEN
> ```
### Generate an offline admin token
Generate an offline admin token file to use if no tokens exist when the server
starts. Once started, you can interact with the server using the provided token.
Offline admin tokens are designed to help with automated deployments.
Include the following options:
- `--offline` _({{% req %}})_
- `--output-file` _({{% req %}})_
- `--name` _(default is `_admin`)_
- `--expiry` _(Optional)_
<!-- pytest.mark.skip -->
```bash { placeholders="TOKEN_NAME|DURATION|path/to/admin-token.json" }
influxdb3 create token --admin \
--name TOKEN_NAME \
--expiry DURATION \
--offline \
--output-file path/to/admin-token.json
```
Replace the following:
- {{% code-placeholder-key %}}`TOKEN_NAME`{{% /code-placeholder-key %}}: Name for your offline admin token
- {{% code-placeholder-key %}}`DURATION`{{% /code-placeholder-key %}}: Duration for the token to remain valid, in [humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html) format (for example, `10d` for 10 days or `1y` for 1 year).
- {{% code-placeholder-key %}}`path/to/admin-token.json`{{% /code-placeholder-key %}}: File path to use for the generated token file
{{< expand-wrapper >}}
{{% expand "View example offline admin token file" %}}
```json
{
"token": "apiv3_0XXXX-xxxXxXxxxXX_OxxxX...",
"name": "example-admin-token",
"expiry_millis": 1756400061529
}
```
{{% /expand %}}
{{< /expand-wrapper >}}