Documentation updates (#807)

Co-authored-by: Aniruddha Kanhere <[email protected]>
Co-authored-by: Archit Gupta <[email protected]>

docs/design/gg-architecture-drawings/readme.txt

@@ -0,0 +1 @@
+support drawings for the gg-architecture document.

docs/spec/executable/iotcored.md

@@ -7,63 +7,100 @@ by the `iotcored` daemon.
 
 For information on MQTT, see <https://mqtt.org/mqtt-specification/>.
 
-- [iotcored-1] The daemon handles the `aws_iot_mqtt` core-bus interface.
-- [iotcored-2] The daemon connects to AWS IoT Core on startup and maintains the
-  connection.
-- [iotcored-3] On disconnect, the daemon tries to reconnect indefinitely with
-  backoff.
-- [iotcored-4] On auth failure, the daemon exits with error.
-- [iotcored-5] When the number of subscriptions exceeds the AWS IoT Core
-  per-connection maximum, additional connections will be used.
-- [iotcored-6] A compile time flag is available to set the maximum number of
-  connections used (default 1).
-- [iotcored-7] Configuration values will be pulled from the config over core-bus
-  unless overridden by a CLI parameter.
-
-## Config keys
-
-TODO
-
-## CLI parameters
-
-### endpoint
-
-- [iotcored-param-endpoint-1] The endpoint argument configures the endpoint the
-  daemon connects to.
-- [iotcored-param-endpoint-2] The endpoint argument can be provided by
-  `--endpoint` or `-e`.
-- [iotcored-param-endpoint-3] The endpoint argument is optional.
+### 1.0 general
 
-### id
-
-- [iotcored-param-id-1] The id argument specifies the MQTT client identifier to
-  use. This may be suffixed with `_{N}`, for some integer `N`, if additional
-  connections are needed due to exceeding the maximum number of subscriptions
-  allowed by AWS IoT Core per connection.
-- [iotcored-param-id-2] The id argument can be provided by `--id` or `-i`.
-- [iotcored-param-id-3] The id argument is optional.
-
-### rootca
-
-- [iotcored-param-rootca-1] The rootca argument specifies the path to the root
-  CA certificate file used to validate the AWS IoT Core endpoint, in PEM format.
-  Ensure that it has the trailing newline character, as some SSL libraries do
-  not support PEM files with missing trailing newline.
-- [iotcored-param-rootca-2] The rootca argument can be provided by `--rootca` or
-  `-r`.
-- [iotcored-param-rootca-3] The rootca argument is optional.
-
-### cert
-
-- [iotcored-param-cert-1] The cert argument specifies the path to the client
-  certificate PEM file to be used for TLS mutual auth with AWS IoT Core to
-  authenticate the device.
-- [iotcored-param-cert-2] The cert argument can be provided by `--cert` or `-c`.
-- [iotcored-param-cert-3] The cert argument is optional.
+- [iotcored-1.1] The daemon handles the `aws_iot_mqtt` core-bus interface.
+- [iotcored-1.2] The daemon connects to AWS IoT Core on startup and maintains
+  the connection.
+- [iotcored-1.3] On disconnect, the daemon tries to reconnect indefinitely with
+  backoff.
+- [iotcored-1.4] On auth failure, the daemon exits with error.
 
-### key
+### 2.0 autoscaling
 
-- [iotcored-param-key-1] The key argument specifies the path to the private key
-  PEM file corresponding to the `cert` argument.
-- [iotcored-param-key-2] The key argument can be provided by `--key` or `-k`.
-- [iotcored-param-key-3] The key argument is optional.
+- [iotcored-2.1] When the number of subscriptions exceeds the AWS IoT Core
+  per-connection maximum, additional connections will be used.
+- [iotcored-2.2] The maximum number of auto-scaling connections may be set by a
+  compile time value.
+- [iotcored-2.3] The maximum number of auto-scaling connections may be set by a
+  command line argument.
+- [iotcored-2.4] The maximum number of auto-scaling connections may be set by a
+  configuration value.
+- [iotcored-2.5] The maximum value of the autoscaling connection count is set
+  according to the following priority:
+
+1. command line argument (optional)
+2. configuration value (optional)
+3. compile time value. (required)
+
+- [iotcored-2.6] The maximum value of the autoscaling connection count shall not
+  exceed the compile time value.
+
+### 3.0 endpoints
+
+The endpoint refers to the AWS IoT Core address used to establish an MQTT
+connection.
+
+- [iotcored-3.1] The AWS endpoint target may be specified by an optional command
+  line argument.
+- [iotcored-3.2] The AWS endpoint target shall be specified by the configuration
+  system if no command line argument is present.
+- [iotcored-3.3] `iotcored` shall exit with a error forwarded from the
+  configuration system if no endpoint is available.
+- [iotcored-3.4] The endpoint target command line argument shall be `--endpoint`
+  or `-e`.
+- [iotcored-3.5] The configuration path shall be
+  `services/aws.greengrass.NucleusLite/configuration/iotDataEndpoint`.
+
+### 4.0 client id
+
+The client id refers to the device identification presented to AWS IoT core.
+This id must be unique. The client id is also called the `thing name` in IoT
+Core.
+
+- [iotcored-4.1] The client id may be specified by an optional command line
+  argument.
+- [iotcored-4.2] The client id shall be specified by the configuration system.
+- [iotcored-4.3] The configuration path shall be `system/thingName`.
+- [iotcored-4.4] The client id will get the suffix `_{N}` during autoscaling.
+  The value of `N` is the autoscaling connection number.
+- [iotcored-4.5] The client id for connection 0 shall be the bare client id
+  without a connection number suffix.
+- [iotcored-4.6] The client id argument may be provided by `--id` or `-i`.
+
+### 5.0 rootca
+
+The rootca is a PEM file used for authenticating AWS IoT Core to the device.
+
+- [iotcored-5.1] The rootca argument specifies the path to the root CA
+  certificate file.
+- [iotcored-5.2] The rootca must be in PEM format.
+- [iotcored-5.4] The rootca argument may be provided by `--rootca` or `-r`.
+- [iotcored-5.6] The rootca argument is optional.
+- [iotcored-5.7] The configuration path shall be `system/rootCaPath`.
+
+### 6.0 client certificate
+
+The client certificate is a PEM file used for authenticating the device AWS IoT
+Core.
+
+- [iotcored-6.1] The certificate file path argument specifies the path to the
+  client certificate PEM file.
+- [iotcored-6.2] The certificate must be in PEM format.
+- [iotcored-6.2] The cert argument may be provided by `--cert` or `-c`.
+- [iotcored-6.3] The cert argument is optional.
+- [iotcored-6.4] The certificate file path shall be specified by the
+  configuration system.
+- [iotcored-6.5] The configuration path shall be `system/certificateFilePath`.
+
+### 7.0 Private Key
+
+The private key is used to generate keys during TLS and certificate rotation
+operations.
+
+- [iotcored-7.1] The key argument specifies the path to the private key PEM
+  file.
+- [iotcored-7.2] The key must be in PEM format.
+- [iotcored-7.3] The key argument can be provided by `--key` or `-k`.
+- [iotcored-7.4] The key argument is optional.
+- [iotcored-7.5] The configuration path shall be `system/privateKeyPath`.

misc/dictionary.txt

@@ -4,6 +4,7 @@ argp
 armv
 awsiotsdk
 boto
+cbmc
 cgexec
 clientfd
 clientv
@@ -88,6 +89,7 @@ NOLINTNEXTLINE
 NOMEM
 NOPASSWD
 nproc
+ostree
 parentid
 pidfd
 pkgs