OTA-3562: fixing aktualizr repo

renamed aktulir repo to uptane generator

Signed-off-by: Merlin Carter <merlin.carter@here.com>

docs/ota-client-guide/modules/ROOT/pages/uptane-generator.adoc

@@ -0,0 +1,117 @@
+= Aktualizr repo
+
+The uptane-generator directory contains a basic implementation of an Uptane server. It is comprised of three tools:
+
+. link:../src/uptane_generator/run/create_repo.sh[`create_repo.sh`] is a script to generate a new Uptane metadata repository, an OSTree repository, and all associated credentials and configuration.
+. link:../src/uptane_generator/run/serve_repo.py[`serve_repo.py`] is a script for running a minimalistic Uptane server.
+. link:../src/uptane_generator/main.cc[`uptane-generator`] is a low-level tool to generate and control an Uptane repository. It can be used to manipulate the repo created with `create_repo.sh`, or it can be used entirely independently.
+
+== create_repo.sh
+
+`create_repo.sh` generates the whole Uptane repo together with client and server certificates and OSTree repo that can be used both by meta-updater and by the device. `create_repo.sh` uses `uptane-generator`, so make sure it's in `PATH`.
+
+=== Usage
+
+`create_repo.sh <repo path> <hostname>`
+
+Make sure that the repository path doesn't already exist and the machine where `serve_repo.py` will be running is accessible from the device specified by `<hostname>`.
+
+=== Integration with bitbake
+
+`create_repo.sh` can work with bitbake running on the same machine. Copy `site.conf` from the generated directory to your `build/conf` or append it to your existing `site.conf`. `bitbake` will then commit the built rootfs to the generated OSTree repository and provision devices to automatically connect to `serve_repo.py`.
+
+== serve_repo.py
+
+`serve_repo.py` serves Uptane metadata and OSTree objects to the devices.
+
+=== Usage
+
+`serve_repo.py <port number> <repo path>`
+
+== uptane-generator
+
+`uptane-generator` can generate and control Uptane metadata. It is used by `create_repo.sh` and many aktualizr tests, but can also be used manually. See `uptane-generator --help` for basic usage details or the examples below for greater detail.
+
+=== Basic usage example
+
+1. Generate a new Uptane repository:
++
+```
+uptane-generator --path <repo path> --command generate
+```
+
+2. Add a target to the images metadata:
++
+```
+uptane-generator --path <repo path> --command image --filename <image name> --targetname <target name> --hwid <hardware ID>
+```
++
+This step can be repeated as many times as necessary for each target. `--targetname` is optional. If it is not provided, it is assumed to be the same as the image name provided to `--filename`.
+
+3. Prepare director targets metadata for a given device:
++
+```
+uptane-generator --path <repo path> --command addtarget --targetname <image name> --hwid <hardware ID> --serial <ECU serial>
+```
++
+This step can be repeated as many times as necessary for each target and ECU.
+
+4. Sign the director targets metadata and schedule the prepared update:
++
+```
+uptane-generator --path <repo path> --command signtargets
+```
+
+=== Advanced usage examples
+
+==== Delegations
+
+`uptane-generator` supports first-order delegations. All delegations are therefore marked as terminating. To add a delegated role, use this:
+```
+uptane-generator --path <repo path> --command adddelegation --dname <delegated role name> --dpattern <delegated path pattern>
+```
+
+To add a target to a delegated role, add the `--dname` parameter to the `image` command. The targetname must match the pattern supplied in `--dpattern` to the `adddelegation` command.
+```
+uptane-generator --path <repo path> --command image --filename <image name> --targetname <target name> --hwid <hardware ID> --dname <delegated role name>
+```
+
+==== Generating metadata without a real file
+
+To add a target to the images metadata without providing an actual file, you can supply alternative parameters to the `image` command:
+```
+uptane-generator --path <repo path> --command image --targetname <target name> --targetsha256 <target SHA256 hash> --targetsha512 <target SHA512 hash> --targetlength <target length> --hwid <hardware ID>
+```
+
+==== Advanced director metadata control
+
+To reset the director targets metadata or to prepare empty targets metadata, use the `emptytargets` command. If you then sign this metadata with `signtargets`, it will schedule an empty update.
+```
+uptane-generator --path <repo path> --command emptytargets
+```
+
+To populate the director targets metadata with the currently signed metadata (with the previous signature removed), use the `oldtargets` command. You can then add more targets with `addtarget` and re-sign with `signtargets`.
+```
+uptane-generator --path <repo path> --command oldtargets
+```
+
+==== Sign arbitrary metadata
+
+To sign arbitrary metadata with one of the Uptane keys, use the `sign` command:
+```
+uptane-generator --path <repo path> --command sign --repotype <director|image> --keyname <role name of key> < <input data>
+```
+
+==== Add custom URLs
+
+To add a custom URL to an image in the Targets metadata of the Images repository:
+```
+uptane-generator --path <repo path> --command image --filename <image name> --targetname <target name> --hwid <hardware ID> --url <URL>
+```
+
+To add a custom URL to an image in the Targets metadata of the Director:
+```
+uptane-generator --path <repo path> --command addtarget --targetname <image name> --hwid <hardware ID> --serial <ECU serial> --url <URL>
+```
+
+If a custom URL is set in both sets of metadata, libaktualizr will use the URL from the Director.

docs/ota-client-guide/modules/nav.adoc

@@ -0,0 +1,106 @@
+// MC: NOTE ABOUT TOC 
+// Adding "pageroot" attr so that TOC that will also work directly in GitHub. Because...
+// In Antora the "pages" subdir is implcit added to the xref path at build time.
+// if you add "/pages" Antora will intepret it as "pages/pages".
+// The pages subdir is NOT implicit when viewing source files in Github.
+
+ifdef::env-github[:pageroot: pages/]
+ifndef::env-github[:pageroot:]
+
+.Introduction to the Developer Tools
+* xref:{pageroot}index.adoc[Introduction]
+* xref:{pageroot}developer-tools.adoc[Developer Tools]
+* xref:{pageroot}workflow-overview.adoc[Basic OTA update workflow]
+* xref:{pageroot}evaluation-to-prod.adoc[Moving from Evaluation to Production]
+// NEW topics
+
+.Key Concepts
+// NEW/updated topics
+* xref:{pageroot}software-management.adoc[Software Management]
+** xref:{pageroot}supporting-technologies.adoc[Supporting technologies]
+** xref:{pageroot}yocto.adoc[Yocto]
+// ---
+** xref:{pageroot}ostree-and-treehub.adoc[OSTree, and TreeHub]
+// ---
+* xref:{pageroot}security.adoc[Security]
+** xref:{pageroot}pki.adoc[Key Management]
+** xref:{pageroot}uptane.adoc[The Uptane security specification]
+// future iteration: * xref:{pageroot}prod-intro[Testing and production environments]
+* xref:{pageroot}client-provisioning-methods.adoc[Device provisioning]
+
+.Evaluate OTA Connect
+* xref:{pageroot}intro-evaluate.adoc[Evaluating OTA Connect]
+* xref:{pageroot}download-prov-key.adoc[Get a provisioning Key]
+* xref:{pageroot}build-images.adoc[Use our sample recipes to build disk images]
+** xref:{pageroot}build-raspberry.adoc[Build for a Raspberry Pi]
+** xref:{pageroot}build-quemu.adoc[Build for QEMU]
+** xref:{pageroot}build-agl.adoc[Build for Automotive Grade Linux]
+* xref:{pageroot}simulate-device-basic.adoc[Simulate a device without building a disk image]
+* xref:{pageroot}pushing-updates.adoc[Upload a sample software version]
+* xref:{pageroot}update-single-device.adoc[Update a second device with the sample software]
+
+.Build your own OTA-enabled solution
+* xref:{pageroot}intro-prep.adoc[Recommended Steps]
+* xref:{pageroot}recommended-clientconfig.adoc[Recommended configurations]
+* xref:{pageroot}account-setup.adoc[Set up multiple accounts]
+
+* xref:{pageroot}libaktualizr-why-use.adoc[Integrate libaktualizr into your solution]
+** xref:{pageroot}libaktualizr-getstarted.adoc[Get Started with libaktualizr]
+** xref:{pageroot}libaktualizr-update-secondary.adoc[Updating a Secondary ECU with libaktualizr]
+
+* xref:{pageroot}build-ota-enabled-images.adoc[Build and deploy OTA-enabled disk images]
+** xref:{pageroot}supported-boards.adoc[Supported boards]
+** xref:{pageroot}add-ota-functonality-existing-yocto-project.adoc[Add OTA functionality to a Yocto project]
+** xref:{pageroot}libaktualizr-integrate.adoc[Add libaktualizr integration to a Yocto project]
+
+* xref:{pageroot}device-cred-prov-steps.adoc[Provision devices]
+** xref:{pageroot}generate-selfsigned-root.adoc[Generate a self-signed root certificate]
+** xref:{pageroot}provide-root-cert.adoc[Register your root certificate]
+** xref:{pageroot}generate-devicecert.[Generate device certificates]
+** xref:{pageroot}enable-device-cred-provisioning.adoc[Enable and install device certificates]
+
+* xref:{pageroot}secure-software-updates.adoc[Secure your software repository]
+** xref:{pageroot}install-garage-sign-deploy.adoc[Install the Garage Deploy tool]
+** xref:{pageroot}rotating-signing-keys.adoc[Manage keys for software metadata]
+** xref:{pageroot}metadata-expiry.adoc[Manage metadata expiry dates]
+
+.Deploy your OTA-enabled solution
+* xref:{pageroot}deploy-checklist.adoc[Deploying to Production]
+
+
+.How to
+* xref:{pageroot}cross-deploy-images.adoc[Transfer software to another repository]
+* xref:{pageroot}simulate-device-cred-provtest.adoc[Simulate device credentials]
+* xref:{pageroot}enable-shared-cred-provisioning.adoc[Configure devices to use shared-credential provisioning]
+* xref:{pageroot}how-can-i-check-which-ostree-version-is-installed.adoc[Check which OSTree commit is deployed]
+* xref:{pageroot}use-your-own-deviceid.adoc[Configure your own device IDs]
+* xref:{pageroot}build-only-ostree.adoc[Build only the OSTree part]
+
+// Dev-authored topics
+* xref:{pageroot}fault-injection.adoc[Simulate installation failures for testing]
+* xref:{pageroot}posix-secondaries-bitbaking.adoc[Simulate a Primary and Secondary ECU]
+** xref:{pageroot}posix-secondaries.adoc[Configuration and emulation on a local host]
+* xref:{pageroot}fault-injection.adoc[Simulate installation failures for testing]
+* xref:{pageroot}rollback.adoc[Set up rollback  behavior]
+* xref:{pageroot}deb-package-install.adoc[Install the client from a deb package]
+* xref:{pageroot}uptane-generator.adoc[Simulate Uptane metadata transactions]
+//----
+
+.Reference
+// MC: Do in second iteration: * xref:{pageroot}otaconnect-identifiers.adoc[Identifiers]
+* xref:{pageroot}aktualizr-config-options.adoc[Configuration Options]
+* xref:{pageroot}aktualizr-runningmodes-finegrained-commandline-control.adoc[Client Commands]
+* xref:{pageroot}provisioning-methods-and-credentialszip.adoc[Contents of the credentials file]
+* xref:{pageroot}useful-bitbake-commands.adoc[Bitbake commands]
+* xref:{pageroot}ostree-usage.adoc[OSTree commands]
+
+.Troubleshooting
+* xref:{pageroot}troubleshooting.adoc[Troubleshooting]
+
+.For Contributors
+// Dev-authored topics
+* xref:{pageroot}deb-package-install.adoc[Packaging an aktualizr Release on github]
+* xref:{pageroot}schema-migrations.adoc[Add a schema migration]
+* xref:{pageroot}debugging-tips.adoc[Debugging the Client]
+
+