From b19135ee51f7088bc81ec089658d97159d07ac20 Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Fri, 9 Feb 2024 17:41:35 +0100 Subject: [PATCH 1/3] doc: clarify how to interact with different remotes through the API Signed-off-by: Ruth Fuchss --- doc/remotes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/remotes.md b/doc/remotes.md index 05d81bb47ebc..c58edea1f1a7 100644 --- a/doc/remotes.md +++ b/doc/remotes.md @@ -3,6 +3,8 @@ Remote servers are a concept in the LXD command-line client. By default, the command-line client interacts with the local LXD daemon, but you can add other servers or clusters to interact with. +If you are using the API, you can interact with different remotes by using their exposed API addresses. + One use case for remote servers is to distribute images that can be used to create instances on local servers. See {ref}`remote-image-servers` for more information. From 12dd1b1eef32922bb6f49399fb28e2c6e2148446 Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Fri, 9 Feb 2024 17:42:40 +0100 Subject: [PATCH 2/3] doc/server: add API instructions for configuring the server Signed-off-by: Ruth Fuchss --- doc/howto/server_configure.md | 63 +++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/doc/howto/server_configure.md b/doc/howto/server_configure.md index 5dde3b51265f..ae8ad1cb9c8e 100644 --- a/doc/howto/server_configure.md +++ b/doc/howto/server_configure.md @@ -8,6 +8,8 @@ In the {ref}`server` option tables, options that apply to the cluster are marked ## Configure server options +````{tabs} +```{group-tab} CLI You can configure a server option with the following command: lxc config set @@ -20,19 +22,80 @@ In a cluster setup, to configure a server option for a cluster member only, add For example, to configure where to store image tarballs on a specific cluster member, enter a command similar to the following: lxc config set storage.images_volume my-pool/my-volume --target member02 +``` +```{group-tab} API +Send a PATCH request to the `/1.0` endpoint to update one or more server options: + + lxc query --request PATCH /1.0 --data '{ + "config": { + "": "", + "": "" + } + }' + +For example, to allow remote access to the LXD server on port 8443, send the following request: + + lxc query --request PATCH /1.0 --data '{ + "config": { + "core.https_address": ":8443" + } + }' + +In a cluster setup, to configure a server option for a cluster member only, add the `target` parameter to the query. +For example, to configure where to store image tarballs on a specific cluster member, send a request similar to the following: + + lxc query --request PATCH /1.0?target=member02 --data '{ + "config": { + "storage.images_volume": "my-pool/my-volume" + } + }' + +See [`PATCH /1.0`](swagger:/server/server_patch) for more information. +``` +```` ## Display the server configuration +````{tabs} +```{group-tab} CLI To display the current server configuration, enter the following command: lxc config show In a cluster setup, to show the local configuration for a specific cluster member, add the `--target` flag. +``` +```{group-tab} API +Send a GET request to the `/1.0` endpoint to display the current server environment and configuration: + + lxc query --request GET /1.0 + +In a cluster setup, to show the local environment and configuration for a specific cluster member, add the `target` parameter to the query: + + lxc query --request GET /1.0?target= + +See [`GET /1.0`](swagger:/server/server_get) for more information. +``` +```` ## Edit the full server configuration +````{tabs} +```{group-tab} CLI To edit the full server configuration as a YAML file, enter the following command: lxc config edit In a cluster setup, to edit the local configuration for a specific cluster member, add the `--target` flag. +``` +```{group-tab} API +To update the full server configuration, send a PUT request to the `/1.0` endpoint: + + lxc query --request PUT /1.0 --data '' + +In a cluster setup, to update the full server configuration for a specific cluster member, add the `target` parameter to the query: + + lxc query --request PUT /1.0?target= '' + +See [`PUT /1.0`](swagger:/server/server_put) for more information. +``` +```` From e3f7b4c56cb6089ecebec0037c2a2246302e237a Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Fri, 9 Feb 2024 17:43:00 +0100 Subject: [PATCH 3/3] doc/server: add API instructions for authenticating Signed-off-by: Ruth Fuchss --- doc/howto/server_expose.md | 85 ++++++++++++++++++++++++++++++++++---- 1 file changed, 78 insertions(+), 7 deletions(-) diff --git a/doc/howto/server_expose.md b/doc/howto/server_expose.md index 1935e7a9aa7a..d73485ba67fb 100644 --- a/doc/howto/server_expose.md +++ b/doc/howto/server_expose.md @@ -6,9 +6,20 @@ By default, LXD can be used only by local users through a Unix socket and is not To expose LXD to the network, you must configure it to listen to addresses other than the local Unix socket. To do so, set the {config:option}`server-core:core.https_address` server configuration option. -For example, to allow access to the LXD server on port `8443`, enter the following command: +For example, allow access to the LXD server on port `8443`: +````{tabs} +```{group-tab} CLI lxc config set core.https_address :8443 +``` +```{group-tab} API + lxc query --request PATCH /1.0 --data '{ + "config": { + "core.https_address": ":8443" + } + }' +``` +```` To allow access through a specific IP address, use `ip addr` to find an available address and then set it. For example: @@ -50,20 +61,80 @@ There are several authentication methods; see {ref}`authentication` for detailed The recommended method is to add the client's TLS certificate to the server's trust store through a trust token. To authenticate a client using a trust token, complete the following steps: -1. On the server, enter the following command: +1. On the server, generate a trust token. + + ````{tabs} + ```{group-tab} CLI + To generate a trust token, enter the following command on the server: lxc config trust add Enter the name of the client that you want to add. The command generates and prints a token that can be used to add the client certificate. -1. On the client, add the server with the following command: + ``` + ```{group-tab} API + To generate a trust token, send a POST request to the `/1.0/certificates` endpoint: + + lxc query --request POST /1.0/certificates --data '{ + "name": "", + "token": true, + "type": "client" + }' + + See [`POST /1.0/certificates`](swagger:/certificates/certificates_post) for more information. + + The return value of this query contains an operation that has the information that is required to generate the trust token: + + { + "class": "token", + ... + "metadata": { + "addresses": [ + "" + ], + "fingerprint": "", + ... + "secret": "" + }, + ... + } + + Use this information to generate the trust token: + + echo -n '{"client_name":"","fingerprint":"",'\ + '"addresses":[""],'\ + '"secret":"","expires_at":"0001-01-01T00:00:00Z"}' | base64 -w0 + ``` + ```` + +1. Authenticate the client. + + `````{tabs} + ````{group-tab} CLI + On the client, add the server with the following command: lxc remote add % Include content from [../authentication.md](../authentication.md) -```{include} ../authentication.md - :start-after: - :end-before: -``` + ```{include} ../authentication.md + :start-after: + :end-before: + ``` + ```` + ````{group-tab} API + On the client, generate a certificate to use for the connection: + + openssl req -x509 -newkey rsa:2048 -keyout "" -nodes \ + -out "" -subj "/CN=" + + Then send a POST request to the `/1.0/certificates?public` endpoint to authenticate: + + curl -k -s --key "" --cert "" \ + -X POST https:///1.0/certificates \ + --data '{ "password": "" }' + + See [`POST /1.0/certificates?public`](swagger:/certificates/certificates_post_untrusted) for more information. + ```` + ````` See {ref}`authentication` for detailed information and other authentication methods.