Skip to content

Commit

Permalink
copy jaro pr (#8)
Browse files Browse the repository at this point in the history 
questdb/questdb.io#2352
  • Loading branch information
@goodroot
goodroot authored Jul 15, 2024
1 parent 0b5318e commit e53854d
Show file tree
Hide file tree
Showing 3 changed files with 70 additions and 127 deletions.
8 changes: 8 additions & 0 deletions configuration-utils/_http.config.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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."
Expand Down
128 changes: 21 additions & 107 deletions reference/api/ilp/overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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.

<Tabs defaultValue="macos" values={[ { label: "macOS", value: "macos" },
{ label: "Debian", value: "debian" }, { label: "Ubuntu", value: "ubuntu" }, ]}>

<TabItem value="macos">

```bash
brew install jose
brew install jq
```

</TabItem>

<TabItem value="debian">

```bash
yum install jose
yum install jq
```

</TabItem>

<TabItem value="ubuntu">

```bash
apt install jose
apt install jq
```

</TabItem>

</Tabs>

##### 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`).
Expand Down Expand Up @@ -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
Expand Down
61 changes: 41 additions & 20 deletions reference/api/rest.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:

<Tabs defaultValue="csv" values={[
{ label: "CSV", value: "csv" },
{ label: "Table", value: "table" },
{ label: "CSV", value: "csv" },
{ label: "Table", value: "table" },
]}>

<TabItem value="csv">
Expand Down Expand Up @@ -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.

<Tabs defaultValue="curl" values={[
{ label: "cURL", value: "curl" },
{ label: "Python", value: "python" },
{ label: "NodeJS", value: "nodejs" },
{ label: "Go", value: "go" },
{ label: "cURL", value: "curl" },
{ label: "Python", value: "python" },
{ label: "NodeJS", value: "nodejs" },
{ label: "Go", value: "go" },
]}>

<TabItem value="curl">
Expand Down Expand Up @@ -117,10 +117,10 @@ parameterized queries that are necessary to avoid SQL injection issues. Prefer
inserts.

<Tabs defaultValue="curl" values={[
{ label: "cURL", value: "curl" },
{ label: "Python", value: "python" },
{ label: "NodeJS", value: "nodejs" },
{ label: "Go", value: "go" },
{ label: "cURL", value: "curl" },
{ label: "Python", value: "python" },
{ label: "NodeJS", value: "nodejs" },
{ label: "Go", value: "go" },
]}>

<TabItem value="curl">
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.

:::

Expand Down Expand Up @@ -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
```

0 comments on commit e53854d

Please sign in to comment.