diff --git a/site/content/3.12/develop/http-api/administration.md b/site/content/3.12/develop/http-api/administration.md index afc71ea747..b46d1785a9 100644 --- a/site/content/3.12/develop/http-api/administration.md +++ b/site/content/3.12/develop/http-api/administration.md @@ -658,6 +658,134 @@ assert(response.parsedBody.deployment.servers !== undefined); logJsonResponse(response); ``` +## Startup options + +### Get the startup option configuration + +```openapi +paths: + /_admin/options: + get: + operationId: getEffectiveStartupOptions + description: | + Return the effective configuration of the queried _arangod_ instance as + set by startup options on the command-line and via a configuration file. + + {{}} + This endpoint may reveal sensitive information about the deployment! + {{}} + + The endpoint can only be accessed via the `_system` database. + In addition, the `--server.options-api` startup option controls the + required privileges to access the option endpoints and allows you to + disable them entirely. The option can have the following values: + - `disabled`: the option endpoints are disabled + - `jwt`: the option endpoints can only be accessed using a superuser JWT (default) + - `admin`: the option endpoints can only be accessed by users with + *Administrate* access level for the `_system` database + - `public`: every user with access to the `_system` database can access + the option endpoints + responses: + '200': + description: | + An object with startup option names as keys and their effective + value as values. The values can be of different data types, typically + numbers, strings, or arrays thereof. + content: + application/json: + schema: + type: object + tags: + - Administration +``` + +### Get the available startup options + +```openapi +paths: + /_admin/options-description: + get: + operationId: getAvailableStartupOptions + description: | + Return the startup options available to configure the queried _arangod_ + instance, similar to the `--dump-options` startup option. + + The endpoint can only be accessed via the `_system` database. + In addition, the `--server.options-api` startup option controls the + required privileges to access the option endpoints and allows you to + disable them entirely. The option can have the following values: + - `disabled`: the option endpoints are disabled + - `jwt`: the option endpoints can only be accessed using a superuser JWT (default) + - `admin`: the option endpoints can be accessed by admin users in the `_system` + database only. + - `public`: every user with access to the `_system` database can access + the option endpoints. + responses: + '200': + description: | + An object with startup option names as keys and sub-objects as values. + The structure of each sub-object is as follows: + - `section` (string): The part before the dot of a startup option + (`--section.param`), or `""` if it is a general option that doesn't + belong to a section + - `description` (string): A succinct explanation of the startup option + - `longDescription` (string, *optional*): Additional details about the + startup option if available + - `category` (string): Either `"option"` for regular options or `"command"` + if using the option performs an action and then terminates the process + - `hidden` (boolean): Whether the option is uncommon. If yes, then + the `--help` command does not list it, but `--help-all` lists every + startup option + - `type` (string): the data type of the option, typically one of + `"uint64"`, `"uint32"`, `"int64"`, `"int32"`, `"double"`, `"boolean"`, + `"string"`, `"string..."` + - `experimental` (boolean): Whether the option relates to a feature + that is not ready for production yet + - `obsolete` (boolean): Whether the option has been deprecated and + no effect anymore + - `enterpriseOnly` (boolean): Whether the option is only available in + the Enterprise Edition. The Community Edition does have most of the + Enterprise Edition startup options and they are thus not reported + - `requiresValue` (boolean): Whether the option can be specified + without a value to enable it + - `os` (array of strings): The operating systems the startup option + is supported on, typically `["linux", "macos", "windows"]`. On an + OS that does not support a specific option, the option is not + reported + - `component` (array of strings): A list of server roles the startup + option is available on. If it is supported by all cluster node types + as well as the single server deployment mode, then the value is + `["coordinator", "dbserver", "agent", "single"]` + - `introducedIn` (array of strings\|null): A list of versions the + startup option has been added in. Does not include later minor and + major versions then the current version, and the information may + get removed once all listed versions reach their end of life + - `deprecatedIn` (array of strings\|null): A list of versions the + startup option has been marked for deprecation in. It can still + be used until fully removed. Does not include later minor and + major versions then the current version, and the information may + get removed once all listed versions reach their end of life + - `values` (string, *optional*): + A description of the possible values you can set + - `default` (any, *optional*): The standard value if the option is not set + - `dynamic` (boolean): Whether the default value is calculated based + on the target host configuration, e.g. available memory + - `required` (boolean): Whether the option must be specified + - `base` (number, *optional*): the unit for a numeric option + - `minValue` (number, *optional*): The minimum value for a numeric option + - `maxValue` (number, *optional*): The maximum value for a numeric option + - `minInclusive` (boolean, *optional*): Whether the minimum value is + included in the allowed value range + - `maxInclusive` (boolean, *optional*): Whether the maximum value is + included in the allowed value range + content: + application/json: + schema: + type: object + tags: + - Administration +``` + ## Server mode ### Return whether or not a server is in read-only mode diff --git a/site/content/3.12/operations/administration/configuration.md b/site/content/3.12/operations/administration/configuration.md index 1cda852751..a5b5063690 100644 --- a/site/content/3.12/operations/administration/configuration.md +++ b/site/content/3.12/operations/administration/configuration.md @@ -330,15 +330,6 @@ instance, or adjusted at runtime via an API call. Examples: ## Fetch Current Configuration Options -To list the configuration options of a running `arangod` instance, you can -connect with an [ArangoShell](../../components/tools/arangodb-shell/_index.md) and invoke a -[Transaction](../../develop/transactions/_index.md) by calling `db._executeTransaction()` -and providing a JavaScript function to retrieve the server options: - -```js ---- -name: listCurrentConfigOpts -description: '' ---- -db._executeTransaction({ collections: {}, action: function() {return require("internal").options(); } }) -``` +Use the [`GET /_admin/options` HTTP API](../../develop/http-api/administration.md#startup-options) +to retrieve the effective configuration of the queried _arangod_ instance as +set by startup options on the command-line and via a configuration file. diff --git a/site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md b/site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md index cd5cda57ed..2f22a342bc 100644 --- a/site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md +++ b/site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md @@ -111,7 +111,18 @@ The default value remains 128 MiB. ### Endpoints added +#### Effective and available startup options +The new `GET /_admin/options` and `GET /_admin/options-description` HTTP API +endpoints allow you to return the effective configuration and the available +startup options of the queried _arangod_ instance. + +Previously, it was only possible to [fetch the current configuration](../../operations/administration/configuration.md#fetch-current-configuration-options) +on single servers and Coordinators using a JavaScript transaction, and to list +the available startup options with `--dump-options`. + +See the [HTTP interface for administration](../../develop/http-api/administration.md#startup-options) +for details. ### Endpoints augmented diff --git a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md index f4e5c37885..6cdafccf53 100644 --- a/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md +++ b/site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md @@ -227,6 +227,19 @@ indexes have been allowing to index and store the `_id` system attribute. ## Server options +### Effective and available startup options + +The new `GET /_admin/options` and `GET /_admin/options-description` HTTP API +endpoints allow you to return the effective configuration and the available +startup options of the queried _arangod_ instance. + +Previously, it was only possible to fetch the current configuration on +single servers and Coordinators using a JavaScript Transaction, and to list +the available startup options with `--dump-options`. + +See the [HTTP interface for administration](../../develop/http-api/administration.md#startup-options) +for details. + ### Protocol aliases for endpoints You can now use `http://` and `https://` as aliases for `tcp://` and `ssl://`