Skip to content

Commit 681ad95

Browse files
Simran-BSimran-B
authored
DOC-614 | Add Options API (#425)
* Add Options API * Remove workaround resolution
1 parent 3d7ec96 commit 681ad95

File tree

4 files changed

+155
-12
lines changed

4 files changed

+155
-12
lines changed

‎site/content/3.12/develop/http-api/administration.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -658,6 +658,134 @@ assert(response.parsedBody.deployment.servers !== undefined);
658658
logJsonResponse(response);
659659
```
660660

661+
## Startup options
662+
663+
### Get the startup option configuration
664+
665+
```openapi
666+
paths:
667+
/_admin/options:
668+
get:
669+
operationId: getEffectiveStartupOptions
670+
description: |
671+
Return the effective configuration of the queried _arangod_ instance as
672+
set by startup options on the command-line and via a configuration file.
673+
674+
{{</* security */>}}
675+
This endpoint may reveal sensitive information about the deployment!
676+
{{</* /security */>}}
677+
678+
The endpoint can only be accessed via the `_system` database.
679+
In addition, the `--server.options-api` startup option controls the
680+
required privileges to access the option endpoints and allows you to
681+
disable them entirely. The option can have the following values:
682+
- `disabled`: the option endpoints are disabled
683+
- `jwt`: the option endpoints can only be accessed using a superuser JWT (default)
684+
- `admin`: the option endpoints can only be accessed by users with
685+
*Administrate* access level for the `_system` database
686+
- `public`: every user with access to the `_system` database can access
687+
the option endpoints
688+
responses:
689+
'200':
690+
description: |
691+
An object with startup option names as keys and their effective
692+
value as values. The values can be of different data types, typically
693+
numbers, strings, or arrays thereof.
694+
content:
695+
application/json:
696+
schema:
697+
type: object
698+
tags:
699+
- Administration
700+
```
701+
702+
### Get the available startup options
703+
704+
```openapi
705+
paths:
706+
/_admin/options-description:
707+
get:
708+
operationId: getAvailableStartupOptions
709+
description: |
710+
Return the startup options available to configure the queried _arangod_
711+
instance, similar to the `--dump-options` startup option.
712+
713+
The endpoint can only be accessed via the `_system` database.
714+
In addition, the `--server.options-api` startup option controls the
715+
required privileges to access the option endpoints and allows you to
716+
disable them entirely. The option can have the following values:
717+
- `disabled`: the option endpoints are disabled
718+
- `jwt`: the option endpoints can only be accessed using a superuser JWT (default)
719+
- `admin`: the option endpoints can be accessed by admin users in the `_system`
720+
database only.
721+
- `public`: every user with access to the `_system` database can access
722+
the option endpoints.
723+
responses:
724+
'200':
725+
description: |
726+
An object with startup option names as keys and sub-objects as values.
727+
The structure of each sub-object is as follows:
728+
- `section` (string): The part before the dot of a startup option
729+
(`--section.param`), or `""` if it is a general option that doesn't
730+
belong to a section
731+
- `description` (string): A succinct explanation of the startup option
732+
- `longDescription` (string, *optional*): Additional details about the
733+
startup option if available
734+
- `category` (string): Either `"option"` for regular options or `"command"`
735+
if using the option performs an action and then terminates the process
736+
- `hidden` (boolean): Whether the option is uncommon. If yes, then
737+
the `--help` command does not list it, but `--help-all` lists every
738+
startup option
739+
- `type` (string): the data type of the option, typically one of
740+
`"uint64"`, `"uint32"`, `"int64"`, `"int32"`, `"double"`, `"boolean"`,
741+
`"string"`, `"string..."`
742+
- `experimental` (boolean): Whether the option relates to a feature
743+
that is not ready for production yet
744+
- `obsolete` (boolean): Whether the option has been deprecated and
745+
no effect anymore
746+
- `enterpriseOnly` (boolean): Whether the option is only available in
747+
the Enterprise Edition. The Community Edition does have most of the
748+
Enterprise Edition startup options and they are thus not reported
749+
- `requiresValue` (boolean): Whether the option can be specified
750+
without a value to enable it
751+
- `os` (array of strings): The operating systems the startup option
752+
is supported on, typically `["linux", "macos", "windows"]`. On an
753+
OS that does not support a specific option, the option is not
754+
reported
755+
- `component` (array of strings): A list of server roles the startup
756+
option is available on. If it is supported by all cluster node types
757+
as well as the single server deployment mode, then the value is
758+
`["coordinator", "dbserver", "agent", "single"]`
759+
- `introducedIn` (array of strings\|null): A list of versions the
760+
startup option has been added in. Does not include later minor and
761+
major versions then the current version, and the information may
762+
get removed once all listed versions reach their end of life
763+
- `deprecatedIn` (array of strings\|null): A list of versions the
764+
startup option has been marked for deprecation in. It can still
765+
be used until fully removed. Does not include later minor and
766+
major versions then the current version, and the information may
767+
get removed once all listed versions reach their end of life
768+
- `values` (string, *optional*):
769+
A description of the possible values you can set
770+
- `default` (any, *optional*): The standard value if the option is not set
771+
- `dynamic` (boolean): Whether the default value is calculated based
772+
on the target host configuration, e.g. available memory
773+
- `required` (boolean): Whether the option must be specified
774+
- `base` (number, *optional*): the unit for a numeric option
775+
- `minValue` (number, *optional*): The minimum value for a numeric option
776+
- `maxValue` (number, *optional*): The maximum value for a numeric option
777+
- `minInclusive` (boolean, *optional*): Whether the minimum value is
778+
included in the allowed value range
779+
- `maxInclusive` (boolean, *optional*): Whether the maximum value is
780+
included in the allowed value range
781+
content:
782+
application/json:
783+
schema:
784+
type: object
785+
tags:
786+
- Administration
787+
```
788+
661789
## Server mode
662790

663791
### Return whether or not a server is in read-only mode

‎site/content/3.12/operations/administration/configuration.md‎

Lines changed: 3 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -330,15 +330,6 @@ instance, or adjusted at runtime via an API call. Examples:
330330

331331
## Fetch Current Configuration Options
332332

333-
To list the configuration options of a running `arangod` instance, you can
334-
connect with an [ArangoShell](../../components/tools/arangodb-shell/_index.md) and invoke a
335-
[Transaction](../../develop/transactions/_index.md) by calling `db._executeTransaction()`
336-
and providing a JavaScript function to retrieve the server options:
337-
338-
```js
339-
---
340-
name: listCurrentConfigOpts
341-
description: ''
342-
---
343-
db._executeTransaction({ collections: {}, action: function() {return require("internal").options(); } })
344-
```
333+
Use the [`GET /_admin/options` HTTP API](../../develop/http-api/administration.md#startup-options)
334+
to retrieve the effective configuration of the queried _arangod_ instance as
335+
set by startup options on the command-line and via a configuration file.

‎site/content/3.12/release-notes/version-3.12/api-changes-in-3-12.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,18 @@ The default value remains 128 MiB.
118118

119119
### Endpoints added
120120

121+
#### Effective and available startup options
121122

123+
The new `GET /_admin/options` and `GET /_admin/options-description` HTTP API
124+
endpoints allow you to return the effective configuration and the available
125+
startup options of the queried _arangod_ instance.
126+
127+
Previously, it was only possible to [fetch the current configuration](../../operations/administration/configuration.md#fetch-current-configuration-options)
128+
on single servers and Coordinators using a JavaScript transaction, and to list
129+
the available startup options with `--dump-options`.
130+
131+
See the [HTTP interface for administration](../../develop/http-api/administration.md#startup-options)
132+
for details.
122133

123134
### Endpoints augmented
124135

‎site/content/3.12/release-notes/version-3.12/whats-new-in-3-12.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -260,6 +260,19 @@ indexes have been allowing to index and store the `_id` system attribute.
260260

261261
## Server options
262262

263+
### Effective and available startup options
264+
265+
The new `GET /_admin/options` and `GET /_admin/options-description` HTTP API
266+
endpoints allow you to return the effective configuration and the available
267+
startup options of the queried _arangod_ instance.
268+
269+
Previously, it was only possible to fetch the current configuration on
270+
single servers and Coordinators using a JavaScript Transaction, and to list
271+
the available startup options with `--dump-options`.
272+
273+
See the [HTTP interface for administration](../../develop/http-api/administration.md#startup-options)
274+
for details.
275+
263276
### Protocol aliases for endpoints
264277

265278
You can now use `http://` and `https://` as aliases for `tcp://` and `ssl://`

0 commit comments

Comments
 (0)