diff --git a/.vscode/settings.json b/.vscode/settings.json index c827452b9..e52c927b3 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -15,6 +15,7 @@ "vale.valeCLI.config": "${workspaceFolder}/.vale.ini", "vale.valeCLI.minAlertLevel": "warning", "cSpell.words": [ - "influxctl" + "influxctl", + "preconfigured" ] } \ No newline at end of file diff --git a/content/influxdb3/core/admin/tokens/admin/preconfigured.md b/content/influxdb3/core/admin/tokens/admin/preconfigured.md new file mode 100644 index 000000000..5e319be4d --- /dev/null +++ b/content/influxdb3/core/admin/tokens/admin/preconfigured.md @@ -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 +--- + + diff --git a/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md b/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md index 37f212eff..9ab898932 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md +++ b/content/influxdb3/core/reference/cli/influxdb3/create/token/admin.md @@ -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: diff --git a/content/influxdb3/core/reference/cli/influxdb3/serve.md b/content/influxdb3/core/reference/cli/influxdb3/serve.md index ba971238d..a66a59209 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/core/reference/cli/influxdb3/serve.md @@ -38,13 +38,17 @@ influxdb3 serve [OPTIONS] --node-id | | `--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)_ | diff --git a/content/influxdb3/enterprise/admin/tokens/admin/preconfigured.md b/content/influxdb3/enterprise/admin/tokens/admin/preconfigured.md new file mode 100644 index 000000000..0eeabd02d --- /dev/null +++ b/content/influxdb3/enterprise/admin/tokens/admin/preconfigured.md @@ -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 +--- + + diff --git a/content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md b/content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md new file mode 100644 index 000000000..a8d636cb7 --- /dev/null +++ b/content/influxdb3/enterprise/admin/tokens/resource/preconfigured.md @@ -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 %}})_ + + + +```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**: (Optional) + _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**: (Optional) 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 %}} + + +```bash { placeholders="path/to/admin-token.json" } +influxdb3 serve \ + # ... \ + --permission-tokens-file path/to/admin-token.json +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```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. diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md index e6a0f8168..da56a933f 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/admin.md @@ -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: diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission.md index b3e03a926..4961adc22 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/token/permission.md @@ -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 --name [OPTIONS] ## Options -| Option | | Description | -| :----- | :----------- | :----------------------------- | -| | `--permission ` | Permissions in `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example, `db:*:read,write`, `system:*:read`. `--permission` may be specified multiple times | -| | `--name ` | Name of the token | -| `-H` | `--host ` | The host URL of the running InfluxDB 3 Enterprise server [env: INFLUXDB3_HOST_URL=] [default: http://127.0.0.1:8181] | -| | `--token ` | The {{% token-link "enterprise" "admin" %}} [env: INFLUXDB3_AUTH_TOKEN=] | -| | `--expiry ` | The token expiration time as a duration (for example, 1h, 7d, 1y). If not set, the token does not expire until revoked | -| | `--tls-ca ` | An optional arg to use a custom CA for testing with self-signed certs [env: INFLUXDB3_TLS_CA=] | -| | `--format ` | Output format (`json` or `text` _(default)_) | -| `-h` | `--help` | Print help information | -| | `--help-all` | Print detailed help information | +| Option | | Description | +| :----- | :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| | `--permission ` | Permissions in `RESOURCE_TYPE:RESOURCE_NAMES:ACTIONS` format--for example, `db:*:read,write`, `system:*:read`. `--permission` may be specified multiple times | +| | `--name ` | Name of the token | +| `-H` | `--host ` | The host URL of the running InfluxDB 3 Enterprise server [env: INFLUXDB3_HOST_URL=] [default: http://127.0.0.1:8181] | +| | `--token ` | The {{% token-link "enterprise" "admin" %}} [env: INFLUXDB3_AUTH_TOKEN=] | +| | `--expiry ` | The token expiration time as a duration (for example, 1h, 7d, 1y). If not set, the token does not expire until revoked | +| | `--tls-ca ` | An optional arg to use a custom CA for testing with self-signed certs [env: INFLUXDB3_TLS_CA=] | +| | `--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)_ + + +```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. diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md b/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md index 40a97edd4..c44102dd3 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/serve.md @@ -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)_ | diff --git a/content/shared/influxdb3-admin/tokens/admin/preconfigured.md b/content/shared/influxdb3-admin/tokens/admin/preconfigured.md new file mode 100644 index 000000000..00c1f1130 --- /dev/null +++ b/content/shared/influxdb3-admin/tokens/admin/preconfigured.md @@ -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 %}})_ + + + +```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**: (Optional) 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 %}} + + +```bash { placeholders="path/to/admin-token.json" } +influxdb3 serve \ + # ... \ + --admin-token-file path/to/admin-token.json +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + + +```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. diff --git a/content/shared/influxdb3-cli/config-options.md b/content/shared/influxdb3-cli/config-options.md index 522bc7b5d..be8ce2e7e 100644 --- a/content/shared/influxdb3-cli/config-options.md +++ b/content/shared/influxdb3-cli/config-options.md @@ -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: + + +```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 + + + +```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 + + + +```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) diff --git a/content/shared/influxdb3-cli/create/token/admin.md b/content/shared/influxdb3-cli/create/token/admin.md index 6a91594d8..dc333f9e0 100644 --- a/content/shared/influxdb3-cli/create/token/admin.md +++ b/content/shared/influxdb3-cli/create/token/admin.md @@ -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 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`] | -| `-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" %}} -```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" %}} - -```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)_ + + + +```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 >}}