local system sites

input/system-cli/site-configuration.md

@@ -51,7 +51,15 @@ Installing the skupper command-line interface (CLI) provides a simple method to
    * `docker`
    * `linux`
 
-2. Create a site:
+2. Install the controller for Podman and Docker sites:
+
+   ```bash
+   skupper system install
+   ```
+   This runs a container to support site, link and service operations.
+   This feature is not available on Linux local system sites (systemd).
+
+3. Create a site:
 
    ```bash
    skupper site create <site-name>
@@ -66,10 +74,17 @@ Installing the skupper command-line interface (CLI) provides a simple method to
    While the site is created, the site is not running at this point.
    To run the site:
    ```bash
-   skupper system setup
+   skupper system start
    ```
 
-  📌 NOTE: On non-Kubernetes sites, you can create multiple sites per-user by specifying a *namespace*.
+By default, all sites are created with the namespace `default`.
+On non-Kubernetes sites, you can create multiple sites per-user by specifying a *namespace*, for example you can create multiple sites with different platforms as follows:
+
+```bash
+skupper site create systemd-site -p linux -n linux-ns
+skupper site create docker-site -p docker -n docker-ns
+```
+
 
 <a id="system-deleting-site-cli"></a>
 ## Deleting a site using the CLI on local systems
@@ -82,7 +97,77 @@ Installing the skupper command-line interface (CLI) provides a simple method to
 
 1. Enter the following command to delete a site:
    ```bash
-   skupper system teardown
+   skupper site delete <sitename>
+   skupper system stop
+   ```
+
+2. You can also uninstall the controller after deleting all existing sites:
+   ```bash
+   skupper system uninstall
+   ```
+
+<a id="system-creating-site-bundle"></a>
+## Creating a site bundle using the CLI on local systems
+
+Sometimes, you might want to create all the configuration for a site and apply it automatically to a remote host.
+To support this, Skupper allows you create a `.tar.gz` file with all the required files and an `install.sh` script to start the remote site.
+
+
+**Prerequisites**
+
+* The `skupper` CLI is installed. The CLI is not required on the remote site.
+
+**Procedure**
+
+1. Set the `SKUPPER_PLATFORM` for type of site you want to install:
+
+   * `podman`
+   * `docker`
+   * `linux`
+
+2. Install the controller for Podman and Docker sites:
+
+   ```bash
+   skupper system install
+   ```
+   This runs a container to support site, link and service operations.
+   This feature is not available on Linux local system sites (systemd).
+
+3. Create a site:
+
+   ```bash
+   skupper site create <site-name>
+   ```
+   For example:
+   ```bash
+   skupper site create remote-site
+
+   Waiting for status...
+   Site "remote-site" is ready.
+   ```
+   While the site is created, the site is not running and that is not a requirement for this usecase.
+
+4. Create the bundle:
+   ```bash
+    skupper system generate-bundle remote-site
+   ```
+   The output shows the location of the generated `.tar.gz` file, for example:
+   ```
+   Site "remote-site" has been created (as a distributable bundle)
+   Installation bundle available at: /home/user/.local/share/skupper/bundles/remote-site.tar.gz
+   Default namespace: default
+   Default platform: podman
+   ```
+5. Transfer the bundle file to the remote location and uncompress the file in an appropriate location:
+   ```bash
+   tar -xzvf remote-site.tar.gz
+   ```
+
+6. Start the site:
+   ```bash
+   install.sh
    ```
+   The site is now running, you can verify with `skupper site status` if the CLI is installed at that location.
+
 
 [cli-ref]: https://skupperproject.github.io/refdog/commands/index.html

input/system-cli/site-linking.md

@@ -6,10 +6,128 @@ The link direction is not significant, and is typically determined by ease of co
 
 Once sites are linked, services can be exposed and consumed across the application network without the need to open ports or manage inter-site connectivity.
 
-
 A *local system* includes Docker, Podman or Linux system.
 
-In this release, the CLI does not support issuing or redeeming tokens.
-In this release, the CLI does not support generating `link` resource files.
+In this release, the CLI does not support issuing tokens for local systems.
+However, you can redeem tokens on a local system, and you can create and use 'link' resources.
+
+<a id="system-token-cli"></a>
+## Linking to Kubernetes sites using a token
+
+A token provides a secure method to link sites.
+By default, a token can only be used once and must be used within 15 minutes to link sites.
+This procedure describes how to issue a token from a Kubernetes site and redeem that token on a local system site to create a link.
+
+**Prerequisites**
+
+* A local system site and a Kubernetes site.
+* A Kubernetes site with `enable-link-access` enabled.
+
+To link sites, you create a token on the Kubernetes site and redeem that token on the local system site to create the link.
+
+**Procedure**
+
+1. On the Kubernetes site where you want to issue the token, make sure link access is enabled:
+   ```bash
+   skupper site update --enable-link-access
+   ```
+2. Create a token:
+   ```bash
+   skupper token issue <filename>
+   ```
+   where `<filename>` is the name of a YAML file that is saved on your local filesystem.
+
+   This file contains a key and the location of the site that created it.
+
+   **📌 NOTE**
+   Access to this file provides access to the application network. 
+   Protect it appropriately.
+   A token can be restricted by any combination of:
+
+   * Time - prevents token reuse after a specified period.
+
+     For example, to allow a token to be used for 1 hour after it is issued:
+     ```
+     skupper token issue build/west.yaml --expiration-window 60m
+     ```
+   * Usage - prevents creating multiple links from a single token.
+
+     For example, to allow a token to be used 3 times:
+     ```
+     skupper token issue output/west.yaml --redemptions-allowed 3
+     ```
+
+   All inter-site traffic is protected by mutual TLS using a private, dedicated certificate authority (CA).
+   A token is not a certificate, but is securely exchanged for a certificate during the linking process.
+
+3. Redeem the token on a local system site to create a link:
+   ```bash
+   skupper token redeem <filename>
+   ```
+   where `<filename>` is the name of a YAML file that is saved on your local filesystem.
+
+4. Check the status of the link:
+   ```bash
+   skupper link status
+   ```
+   You might need to issue the command multiple times before the link is ready:
+   ```
+   $ skupper link status
+   NAME                                            STATUS  COST    MESSAGE
+   west-12f75bc8-5dda-4256-88f8-9df48150281a       Pending 1       Not Operational
+   $ skupper link status
+   NAME                                            STATUS  COST    MESSAGE
+   west-12f75bc8-5dda-4256-88f8-9df48150281a       Ready   1       OK
+   ```
+   You can now expose services on the application network.
+
+There are many options to consider when linking sites using the CLI, see [CLI Reference][cli-ref], including *frequently used* options.
+
+<a id="kube-link-cli"></a>
+## Linking sites using a `link` resource
+
+An alternative approach to linking sites using tokens is to create a `link` resource YAML file using the CLI, and to apply that resource to another site.
+
+**Prerequisites**
+
+* Two sites
+* At least one site with `enable-link-access` enabled.
+
+To link sites, you create a `link` resource YAML file on one site and apply that resource on the other site to create the link.
+
+**Procedure**
+
+1. On the site where you want to create a link , make sure link access is enabled:
+   ```bash
+   skupper site update --enable-link-access
+   skupper site reload
+   ```
+2. Create a `link` resource YAML file:
+   ```bash
+   skupper link generate > <filename>
+   ```
+   where `<filename>` is the name of a YAML file that is saved on your local filesystem.
+
+3. Apply the `link` resource YAML file on a different site to create a link:
+   ```bash
+   skupper system apply -f <filename>
+   ```
+   where `<filename>` is the name of a YAML file that is saved on your local filesystem.
+
+4. Check the status of the link:
+   ```bash
+   skupper link status
+   ```
+   You might need to issue the command multiple times before the link is ready:
+   ```
+   $ skupper link status
+   NAME                                            STATUS  COST    MESSAGE
+   west                                            Pending 1       Not Operational
+   $ skupper link status
+   NAME                                            STATUS  COST    MESSAGE
+   west                                            Ready   1       OK
+   ```
+   You can now expose services on the application network.
+
+There are many options to consider when linking sites using the CLI, see [CLI Reference][cli-ref], including *frequently used* options.
 
-To link a local system site to a Kubernetes site, see [Linking sites on local systems using YAML](../system-yaml/site-linking.html)