Merge pull request #12858 from ru-fu/LXD-563-server-api-docs

Add API instructions for the server/client section

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 <key> <value>
@@ -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": {
+        "<key>": "<value>",
+        "<key>": "<value>"
+      }
+    }'
+
+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=<cluster_member>
+
+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 '<server_configuration>'
+
+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=<cluster_member> '<server_configuration>'
+
+See [`PUT /1.0`](swagger:/server/server_put) for more information.
+```
+````

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": "<client_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": [
+              "<server_address>"
+           ],
+           "fingerprint": "<fingerprint>",
+           ...
+           "secret": "<secret>"
+        },
+       ...
+       }
+
+   Use this information to generate the trust token:
+
+       echo -n '{"client_name":"<client_name>","fingerprint":"<fingerprint>",'\
+       '"addresses":["<server_address>"],'\
+       '"secret":"<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 <remote_name> <token>
 
    % Include content from [../authentication.md](../authentication.md)
-```{include} ../authentication.md
-    :start-after: <!-- Include start NAT authentication -->
-    :end-before: <!-- Include end NAT authentication -->
-```
+   ```{include} ../authentication.md
+       :start-after: <!-- Include start NAT authentication -->
+       :end-before: <!-- Include end NAT authentication -->
+   ```
+   ````
+   ````{group-tab} API
+   On the client, generate a certificate to use for the connection:
+
+       openssl req -x509 -newkey rsa:2048 -keyout "<keyfile_name>" -nodes \
+       -out "<crtfile_name>" -subj "/CN=<client_name>"
+
+   Then send a POST request to the `/1.0/certificates?public` endpoint to authenticate:
+
+       curl -k -s --key "<keyfile_name>" --cert "<crtfile_name>" \
+       -X POST https://<server_address>/1.0/certificates \
+       --data '{ "password": "<trust_token>" }'
+
+   See [`POST /1.0/certificates?public`](swagger:/certificates/certificates_post_untrusted) for more information.
+   ````
+   `````
 
 See {ref}`authentication` for detailed information and other authentication methods.

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.