From e53854de321a3df58dbe2ae71ceefe2e2f250e88 Mon Sep 17 00:00:00 2001 From: goodroot <9484709+goodroot@users.noreply.github.com> Date: Mon, 15 Jul 2024 07:59:17 -0700 Subject: [PATCH] copy jaro pr (#8) https://github.com/questdb/questdb.io/pull/2352/ --- configuration-utils/_http.config.json | 8 ++ reference/api/ilp/overview.md | 128 +++++--------------------- reference/api/rest.md | 61 ++++++++---- 3 files changed, 70 insertions(+), 127 deletions(-) diff --git a/configuration-utils/_http.config.json b/configuration-utils/_http.config.json index 0006f8f1..1498cf81 100644 --- a/configuration-utils/_http.config.json +++ b/configuration-utils/_http.config.json @@ -7,6 +7,14 @@ "default": "0.0.0.0:9000", "description": "IP address and port of HTTP server. A value of `0` means that the HTTP server will bind to all network interfaces. You can specify IP address of any individual network interface on your system." }, + "http.user": { + "default": "N/A", + "description": "Username for HTTP Basic Authentication in QuestDB Open Source. QuestDB Enterprise Edition supports more advanced authentication mechanisms: RBAC" + }, + "http.password": { + "default": "N/A", + "description": "Password for HTTP Basic Authentication in QuestDB Open Source. QuestDB Enterprise Edition supports more advanced authentication mechanisms: RBAC" + }, "http.net.connection.limit": { "default": "64", "description": "The maximum number permitted for simultaneous TCP connection to the HTTP server. The rationale of the value is to control server memory consumption." diff --git a/reference/api/ilp/overview.md b/reference/api/ilp/overview.md index 08960a72..d2372a3a 100644 --- a/reference/api/ilp/overview.md +++ b/reference/api/ilp/overview.md @@ -21,7 +21,7 @@ The InfluxDB Line Protocol is for **data ingestion only**. For building queries, see the [Query & SQL Overview](/docs/reference/sql/overview/). -Each ILP client library also has its own language-specific documentation set. +Each ILP client library also has its own language-specific documentation set. This supporting document thus provides an overview to aid in client selection and initial configuration: @@ -157,112 +157,6 @@ Exposing these values may expose your database to bad actors. - Defaults to 10 seconds. - Not all errors are retriable. -#### TCP Parameters - -- **username**: Username for TCP authentication. -- **token** (SENSITIVE): TCP Authentication `d` parameter. - - **token_x** (SENSITIVE): TCP Authentication `x` parameter. - - Used in C/C++/Rust/Python clients. - - **token_y** (SENSITIVE): TCP Authentication `y` parameter. - - Used in C/C++/Rust/Python clients. -- **auth_timeout**: Timeout for TCP authentication with QuestDB server, in - milliseconds. - - Default 15 seconds. - -##### TCP token authentication setup - -Create `d`, `x` & `y` tokens for client usage. - -##### Prerequisites - -- `jose`: C-language implementation of Javascript Object Signing and Encryption. - Generates tokens. -- `jq`: For pretty JSON output. - - - - - -```bash -brew install jose -brew install jq -``` - - - - - -```bash -yum install jose -yum install jq -``` - - - - - -```bash -apt install jose -apt install jq -``` - - - - - -##### Server configuration - -Next, create an authentication file. - -Only elliptic curve (P-256) are supported (key type `ec-p-256-sha256`): - -```bash -testUser1 ec-p-256-sha256 fLKYEaoEb9lrn3nkwLDA-M_xnuFOdSt9y0Z7_vWSHLU Dt5tbS1dEDMSYfym3fgMv0B99szno-dFc1rYF9t0aac -# [key/user id] [key type] {keyX keyY} -``` - -Generate an authentication file using the `jose` utility: - -```bash -jose jwk gen -i '{"alg":"ES256", "kid": "testUser1"}' -o /var/lib/questdb/conf/full_auth.json - -KID=$(cat /var/lib/questdb/conf/full_auth.json | jq -r '.kid') -X=$(cat /var/lib/questdb/conf/full_auth.json | jq -r '.x') -Y=$(cat /var/lib/questdb/conf/full_auth.json | jq -r '.y') - -echo "$KID ec-p-256-sha256 $X $Y" | tee /var/lib/questdb/conf/auth.txt -``` - -Once created, reference it in the server [configuration](/docs/configuration/): - -```ini title='/path/to/server.conf' -line.tcp.auth.db.path=conf/auth.txt -``` - -##### Client keys - -For the server configuration above, the corresponding JSON Web Key must be -stored on the clients' side. - -When sending a fully-composed JWK, it will have the following keys: - -```json -{ - "kty": "EC", - "d": "5UjEMuA0Pj5pjK8a-fa24dyIf-Es5mYny3oE_Wmus48", - "crv": "P-256", - "kid": "testUser1", - "x": "fLKYEaoEb9lrn3nkwLDA-M_xnuFOdSt9y0Z7_vWSHLU", - "y": "Dt5tbS1dEDMSYfym3fgMv0B99szno-dFc1rYF9t0aac" -} -``` - -The `d`, `x` and `y` parameters generate the public key. - -For example, the Python client would be configured as outlined in the -[Python docs](https://py-questdb-client.readthedocs.io/en/latest/conf.html#tcp-auth). - #### Auto-flushing behavior - **auto_flush**: Enable or disable automatic flushing (`on`/`off`). @@ -319,6 +213,26 @@ _Optional._ - Defaults to `127`. - Related to length limits for filenames on the user's host OS. +#### TCP Parameters + +:::note + +These parameters are only useful when using ILP over TCP with authentication +enabled. Most users should use ILP over HTTP. These parameters are listed for +completeness and for users who have specific requirements. + +::: + +- **username**: Username for TCP authentication. +- **token** (SENSITIVE): TCP Authentication `d` parameter. + - **token_x** (SENSITIVE): TCP Authentication `x` parameter. + - Used in C/C++/Rust/Python clients. + - **token_y** (SENSITIVE): TCP Authentication `y` parameter. + - Used in C/C++/Rust/Python clients. +- **auth_timeout**: Timeout for TCP authentication with QuestDB server, in + milliseconds. + - Default 15 seconds. + ## Transactionality caveat As of writing, the HTTP endpoint does not provide full transactionality in all diff --git a/reference/api/rest.md b/reference/api/rest.md index 03881774..659bb8e8 100644 --- a/reference/api/rest.md +++ b/reference/api/rest.md @@ -6,14 +6,14 @@ description: REST API reference documentation. import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" -import GoImpPartial from "../../partials/_go.imp.insert.partial.mdx" -import CurlImpPartial from "../../partials/_curl.imp.insert.partial.mdx" -import NodejsImpPartial from "../../partials/_nodejs.imp.insert.partial.mdx" -import PythonImpPartial from "../../partials/_python.imp.insert.partial.mdx" -import CurlExecPartial from "../../partials/_curl.exec.insert.partial.mdx" -import GoExecPartial from "../../partials/_go.exec.insert.partial.mdx" -import NodejsExecPartial from "../../partials/_nodejs.exec.insert.partial.mdx" -import PythonExecPartial from "../../partials/_python.exec.insert.partial.mdx" +import GoImpPartial from "../../partials/\_go.imp.insert.partial.mdx" +import CurlImpPartial from "../../partials/\_curl.imp.insert.partial.mdx" +import NodejsImpPartial from "../../partials/\_nodejs.imp.insert.partial.mdx" +import PythonImpPartial from "../../partials/\_python.imp.insert.partial.mdx" +import CurlExecPartial from "../../partials/\_curl.exec.insert.partial.mdx" +import GoExecPartial from "../../partials/\_go.exec.insert.partial.mdx" +import NodejsExecPartial from "../../partials/\_nodejs.exec.insert.partial.mdx" +import PythonExecPartial from "../../partials/\_python.exec.insert.partial.mdx" The QuestDB REST API is based on standard HTTP features and is understood by off-the-shelf HTTP clients. It provides a simple way to interact with QuestDB @@ -48,8 +48,8 @@ For details such as content type, query parameters and more, refer to the Let's assume you want to upload the following data via the `/imp` entrypoint: @@ -83,10 +83,10 @@ query argument to obtain a response in JSON. You can also specify the schema explicitly. See the second example in Python for these features. @@ -117,10 +117,10 @@ parameterized queries that are necessary to avoid SQL injection issues. Prefer inserts. @@ -585,8 +585,9 @@ returned in a tabular form to be saved and reused as opposed to JSON. | Parameter | Required | Description | | :-------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `limit` | No | Paging opp parameter. For example, `limit=10,20` will return row numbers 10 through to 20 inclusive and `limit=20` will return first 20 rows, which is equivalent to `limit=0,20`. `limit=-20` will return the last 20 rows. | | `query` | Yes | URL encoded query text. It can be multi-line. | +| `limit` | No | Paging opp parameter. For example, `limit=10,20` will return row numbers 10 through to 20 inclusive and `limit=20` will return first 20 rows, which is equivalent to `limit=0,20`. `limit=-20` will return the last 20 rows. | +| `nm` | No | `true` or `false`. Skips the metadata section of the response when set to `true`. | The parameters must be URL encoded. @@ -653,7 +654,7 @@ A HTTP status code of `400` is returned with the following response body: :::note Role-based Access Control (RBAC) is available in -[QuestDB Enterprise](/enterprise/). +[QuestDB Enterprise](/enterprise/). See the next paragraph for authentication in QuestDB Open Source. ::: @@ -684,3 +685,23 @@ curl -G --data-urlencode "query=SELECT 1;" \ Refer to the [user management](/docs/operations/rbac/#user-management) page to learn more on how to generate a REST API token. + +## Authentication in QuestDB open source + +QuestDB Open Source supports HTTP basic authentication. To enable it, set the configuration +options `http.user` and `http.password` in `server.conf`. + +The following example shows how to enable HTTP basic authentication in QuestDB open source: + +```shell +http.user=my_user +http.password=my_password +``` + +Then this `curl` command executes a `SELECT 1;` query: + +```bash +curl -G --data-urlencode "query=SELECT 1;" \ + -u "my_user:my_password" \ + http://localhost:9000/exec +```