Ecarson/rest graphql intro

docs/config_domain-based_web_filter.md

@@ -208,7 +208,7 @@ When matching a session to a service, the list below represents the priority ord
 - category
 
 The SSR obtains the category and subcategory for the URL and domain from Websense, which is then used for the service matching algorithm described below. 
-
+<!-- markdown-link-check-disable -->
 For example, on the URL: http://www.google.com/doodles/doodle-champion-island-games-september-05, matching will be performed in the following order. 
 
 1.  Does any child service URL list contain a match for this URL, including any wild-card patterns for URLs? 
@@ -226,7 +226,7 @@ For example, on the URL: http://www.google.com/doodles/doodle-champion-island-ga
             exit
         exit
 ```
-
+<!-- markdown-link-check-enable -->
 2. If there was no match to the first query, then does any child service match the domain in the URL? 
 - Yes, the following domain based service matches the URL:
 
@@ -278,7 +278,7 @@ In this case, `google.com` does not fall into the category of Technology.
 ### Matching Order Algorithm
 
 The matching order algorithm is the same for scenarios when all the web filtering config options are used across different child services under the parent, or used on the same child service. For example, consider the following service:
-
+<!-- markdown-link-check-disable -->
 ```
         service  block-search.internet
             name                search.internet
@@ -300,7 +300,7 @@ The `block-search.internet` child service will match the various URLs as follows
 | http://www.google.com/doodles/doodle-champion-island-games-september-05 | By URL<br /> http://www.google.com/doodles/* | The wild-card URL is the best match in this case. |
 | http://www.google.com | By domain *google.com | The URL is not a match, but the domain is and the overall child service is a match as a result. |
 | http://www.bing.com | By subcategory Search Engines and Portals. | The URL matches neither the configured URL or domain pattern, however, it is a Search Engine and matches the child service. |
-
+<!-- markdown-link-check-enable -->
 ## Configuring Web Filtering using the GUI
 
 To enable Web Filtering, configure application identification, a parent service, a child service, and access policies to allow or deny traffic. In many cases, you may have pieces of this procedure already in place, such as  the *internet* service configured as an example below. 

docs/howto_router_migration.md

@@ -53,4 +53,15 @@ When using the GUI, a **Migrate** button is visible for Routers that are possibl
 After the migration command is run, you will see a **Connected** state on the conductor showing the migration was successful. The router(s) will transition to running after a few minutes. If a router does not migrate successfully, an error message will be displayed and no action will be taken.
 
 - Verify that the TCP ports 930, 4505 and 4506 on the conductor are enabled. The routers use these ports to communicate with the conductor.
-- If there is a firewall in front of the conductor, these same TCP ports must be enabled.
+- If there is a firewall in front of the conductor, these same TCP ports must be enabled.
+
+### Additional Considerations When Strict Host Key Checking Is Enabled
+
+If the router is configured for strict `inter-router` host key checking (`host-key-checking` is `yes`), there are some additional considerations when performing a migration to the new conductor. It will be necessary to manually provision the new conductor key **prior** to migrating the router. This will require the administrator to retrieve the host key of each node of the new conductor and configure this in the router prior to migration.
+
+On the new conductor, identify each nodes `Key` using the command `show system connectivity host-keys node all`.
+
+On the router, each conductor key can be then be pre-provisioned by using the follow command:
+`create system connectivity known-hosts node <node> <conductor address> ssh-rsa <key> <comment>`
+
+where, `<node>` is the router node (should be added on each router node in an HA pair), `<conductor address>` is the conductor address (should be added for each conductor address of an HA conductor pair), `<key>` is the `Key` retrieved from the previous step and, optionally a comment `<comment>` to identify what this key is, for example `Production Conductor1`.

docs/intro_otp_iso_install.mdx

@@ -24,11 +24,11 @@ Basic configuration parameters are encoded within an encrypted file. For each no
 
 ### Disk Cloning
 
-Disk Cloning allows you to create a generic router platform image that can be used to perform multiple installations quickly and efficiently. After the initial ISO installation and power off, the platform is generic and can be cloned to a disk to create a copy of that platform. 
+Disk Cloning allows you to create a generic router platform image that can be used to perform multiple installations quickly and efficiently. After the initial ISO installation and power off, the platform is generic and can be cloned to a disk to create a copy of that platform.
 :::note
 When using cloned images, an identical hardware platform must be used. Create a new disk image for each hardware variation.
 :::
-The cloned platform disk is then used to install the filesystem and SSR software on any number of other identical hardware platforms. 
+The cloned platform disk is then used to install the filesystem and SSR software on any number of other identical hardware platforms.
 
 The general process for disk cloning is as follows:
 
@@ -57,7 +57,7 @@ To install the Router using the OTP workflow, use the arrow keys to select the *
 Not all hardware has video support. Booting to the serial console 115200 baud is the default, and is automatically selected after 30 seconds. When using the serial console, the terminal size is 80x25 - anything smaller may result in abnormal navigation behavior.
 
 Selecting the wrong type of console (Serial or VGA) may result in garbled characters being displayed, and if left to continue will result in an incorrect installation. If the wrong console is selected, reboot the target system and select the correct line for the target hardware.
-::: 
+:::
 
 #### SSR System via Serial Console
 
@@ -147,14 +147,14 @@ Changing password for user t128
 Changing password for t128
 (current)UNIX password:
 New password:
-Retype new password: 
+Retype new password:
 passwd: all authentication tokens updated successfully.
-[t128@test-router ~]$ su - 
+[t128@test-router ~]$ su -
 Password:
 [root@test-router ~]# passwd
 Changing password for user root.
 New password:
-Retype new password: 
+Retype new password:
 passwd: all authentication tokens updated successfully.
 [root@test-router ~]#
 ```
@@ -172,7 +172,7 @@ The scriptlets must have executable permissions to be executed properly.
 Any stdout/stderr output generated from the scriptlets is logged in `/var/log/128T-bootstrap/<scriptlet-name>-scriptlet.log`.
 
 ### Bootstrapping Flow Chart
-The diagram below shows the procedure the Bootstrap utility follows during the first bootup of the platform after the ISO installation completes. 
+The diagram below shows the procedure the Bootstrap utility follows during the first bootup of the platform after the ISO installation completes.
 
 <Flowchart
   chartCode={`
@@ -246,3 +246,14 @@ Or, if you want to test a specific url:
 ```
 $ bootstrap128t rest-test -i <test-identifier> --url <a-fully-qualified-url>
 ```
+
+### Additional Considerations When Strict Host Key Checking Is Enabled
+
+If the router is configured for strict `inter-router` host key checking (`host-key-checking` is `yes`), there are some additional considerations when onboarding to the conductor. It will be necessary to manually provision the new conductor key **prior** to successful communication to the conductor. This will require the administrator to retrieve the host key of each node of the new conductor and configure this in the router.
+
+On the new conductor, identify each nodes `Key` using the command `show system connectivity host-keys node all`.
+
+On the router PCLI, each conductor key can be then be provisioned by using the follow command:
+`create system connectivity known-hosts node <node> <conductor address> ssh-rsa <key> <comment>`
+
+where, `<node>` is the router node (should be added on each router node in an HA pair), `<conductor address>` is the conductor address (should be added for each conductor address of an HA conductor pair), `<key>` is the `Key` retrieved from the previous step and, optionally a comment `<comment>` to identify what this key is, for example `Conductor1`.

docs/intro_rest_graphql_apis.md

@@ -0,0 +1,53 @@
+---
+title: Introduction to REST and GraphQL APIs
+sidebar_label: REST and GraphQL APIs
+---
+
+The SSR provides Application Programming Interfaces (APIs) that can be used to interact with the SSR from an external application. The two primary interfaces are REST and GraphQL.
+
+A REST API (Representational State Transfer Application Programming Interface) is a set of rules and conventions for building and interacting with web services. It uses standard HTTP methods such as GET, POST, PUT, DELETE, etc., to perform operations on resources, which are typically represented in formats like JSON or XML.
+
+The GraphQL API is an alternative to REST and allows clients to use queries to request exactly the data they need. The server then populates the items in the query.
+
+:::note
+The examples shown in this document use the `curl` command-line application; any HTTP client can be used.
+:::
+
+## Authentication Tokens
+
+The REST and GraphQL APIs are authorized and authenticated securely using authorization tokens. Tokens are granted using the username and password of a suitably priviliged user, and passed to each API call. The SSR uses the token to determine authorization for each API call. The RBAC privileges of the user determine access to the resources being accessed by the API.
+
+The `/api/v1/login` REST API is used to generate these tokens, as shown below:
+`curl --request POST -k --url 'https://192.168.0.1/api/v1/login' -H "Content-Type: application/json" -d '{ "username": "admin", "password":"128Tadmin"}'`
+
+In this example, the address of the SSR is `192.168.0.1` and the username is `admin` with password `128Tadmin`. Additionally the `-H "Content-Type: application/json"` specifies a `Content-Type` header that the client is passing and accepting JSON data.
+
+If the login attempt is successful a token is returned, as shown below:
+```
+{"token":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiYWRtaW4iLCJyb2xlcyI6WyJhZG1pbiJdLCJzY29wZXMiOlsiY29uZmlndXJlIiwic2hvdy1jb21tYW5kcyJdLCJjYXBhYmlsaXRpZXMiOlsiY29uZmlnLXJlYWQiLCJjb25maWctd3JpdGUiLCJwcm92aXNpb25pbmciXSwiYXBwbGljYXRpb24iOiJ1bmtub3duIiwidXNlckFnZW50IjoiThiSaintAR31lt0k3njI5LjAlc3MiOiIxMjcuMC4wLjEiLCJpc3MiOiJSVFJfRUFTVF9DT05EVUNUT1IiLCJpYXQiOjE3MjY1NDQ5Mzd9.NoEgcSzm752k1PWsvi5WtyFVCA825WI_fFMfOVeoNXvK1jsyW6UKiwGD8gSJFuQrtNYISgZWlBrqD3bhpiii33-DnAzOOEIuDXpbNGKAw2KwiuVKHoDIj8iWRi1grBERFpDFKCgjO15sR0q2JAb88k_EIkIHLeuS1bLSpi1mGfjRGeNcDh8DkCjQM1jH-DbPXf5oJ7pAq79pflLR-yS5WcWpeeQRaO_xrwWnd9cS4R31T-T0p1q0SYJanB9IQ3YUtue3zqArJmb4qHT46HJ_rctpp6NLXUih2Q7LEe7-DQB3yV9nDoB5vIAZn1PThiSaintAR31lt0k3ndH_KZxkuQQ"}
+```
+
+This token can be passed via an `Authorization` header to subsequent API calls for authorization. For example:
+`curl --request GET -k --url 'https://192.168.0.1/api/v1/version' -H "Content-Type: application/json" -H 'Authorization: Bearer <token>`
+
+In this example, the address of the SSR is `192.168.0.1`, the API being called is `/api/v1/version`, and an `Authorization` header is specifying a `Bearer` token. The value returned from the `/api/v1/login` API should replace `<token>`. For example:
+```
+curl --request GET -k --url 'https://192.168.0.1/api/v1/version' -H "Content-Type: application/json" -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiYWRtaW4iLCJyb2xlcyI6WyJhZG1pbiJdLCJzY29wZXMiOlsiY29uZmlndXJlIiwic2hvdy1jb21tYW5kcyJdLCJjYXBhYmlsaXRpZXMiOlsiY29uZmlnLXJlYWQiLCJjb25maWctd3JpdGUiLCJwcm92aXNpb25pbmciXSwiYXBwbGljYXRpb24iOiJ1bmtub3duIiwidXNlckFnZW50IjoiY3VybC83LjIThiSaintAR31lt0k3nlc3MiOiIxMjcuMC4wLjEiLCJpc3MiOiJSVFJfRUFTVF9DT05EVUNUT1IiLCJpYXQiOjE3MjY1NDQ5Mzd9.NoEgcSzm752k1PWsvi5WtyFVCA825WI_fFMfOVeoNXvK1jsyW6UKiwGD8gSJFuQrtNYISgZWlBrqD3bhpiii33-DnAzOOEIuDXpbNGKAw2KwiuVKHoDIj8iWRi1grBERFpDFKCgjO15sR0q2JAb88k_EIkIHLeuS1bLSpi1mGfjRGeNcDh8DkCjQM1jH-DbPXf5oJ7pAq79pflLR-yS5WcWpeeQRaO_xrwWnd9cS4R31T-T0p1q0SYJanB9IQ3YUtue3zqArJmb4qHT46HJ_rctpp6NLXUih2Q7LEe7-DQB3yV9nDoB5vIAZn1PThiSaintAR31lt0k3ndH_KZxkuQQ'
+```
+
+## Built In Product Documentation
+
+There are numerous APIs in the SSR. The API documentation is available from the `About This System` page in the GUI.
+
+There are separate documentation pages for REST and GraphQL. The documentation pages feature interactive elements that allow the APIs to be dynamically tested from the GUI.
+
+The REST APIs are documented using Swagger and are found here:
+`https://<SSR address>/documentation/swagger`
+
+The GraphQL APIs are documented using an interactive explorer and are found here:
+`https://<SSR address>/documentation/graphql`
+
+
+## Tips
+
+The PCLI `trace` command can be used to see the API calls made for a given PCLI command. This can be useful to determine which data is available for common use cases.

sidebars.js

@@ -305,6 +305,8 @@ module.exports = {
       "config_command_guide",
       "config_reference_guide",
       "cli_stats_reference",
+      "intro_rest_graphql_apis",
+
     ],
     "Installer/Initializer Reference": [
       "installer_cli_reference",