From d312e28cc4e7f72096799ba1d3d74b8d6e2c315b Mon Sep 17 00:00:00 2001 From: Merlin Carter Date: Thu, 15 Aug 2019 17:17:09 +0200 Subject: [PATCH] OTA-3562: fixing aktualizr repo renamed aktulir repo to uptane generator Signed-off-by: Merlin Carter --- docs/aktualizr-repo.adoc | 1 - .../modules/ROOT/pages/uptane-generator.adoc | 117 ++++++++++++++++++ docs/ota-client-guide/modules/nav.adoc | 106 ++++++++++++++++ 3 files changed, 223 insertions(+), 1 deletion(-) delete mode 120000 docs/aktualizr-repo.adoc create mode 100644 docs/ota-client-guide/modules/ROOT/pages/uptane-generator.adoc create mode 100644 docs/ota-client-guide/modules/nav.adoc diff --git a/docs/aktualizr-repo.adoc b/docs/aktualizr-repo.adoc deleted file mode 120000 index b954e2d76c..0000000000 --- a/docs/aktualizr-repo.adoc +++ /dev/null @@ -1 +0,0 @@ -./ota-client-guide/modules/ROOT/pages/aktualizr-repo.adoc \ No newline at end of file diff --git a/docs/ota-client-guide/modules/ROOT/pages/uptane-generator.adoc b/docs/ota-client-guide/modules/ROOT/pages/uptane-generator.adoc new file mode 100644 index 0000000000..01d1969435 --- /dev/null +++ b/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 ` + +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 ``. + +=== 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 ` + +== 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 --command generate +``` + +2. Add a target to the images metadata: ++ +``` +uptane-generator --path --command image --filename --targetname --hwid +``` ++ +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 --command addtarget --targetname --hwid --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 --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 --command adddelegation --dname --dpattern +``` + +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 --command image --filename --targetname --hwid --dname +``` + +==== 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 --command image --targetname --targetsha256 --targetsha512 --targetlength --hwid +``` + +==== 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 --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 --command oldtargets +``` + +==== Sign arbitrary metadata + +To sign arbitrary metadata with one of the Uptane keys, use the `sign` command: +``` +uptane-generator --path --command sign --repotype --keyname < +``` + +==== Add custom URLs + +To add a custom URL to an image in the Targets metadata of the Images repository: +``` +uptane-generator --path --command image --filename --targetname --hwid --url +``` + +To add a custom URL to an image in the Targets metadata of the Director: +``` +uptane-generator --path --command addtarget --targetname --hwid --serial --url +``` + +If a custom URL is set in both sets of metadata, libaktualizr will use the URL from the Director. diff --git a/docs/ota-client-guide/modules/nav.adoc b/docs/ota-client-guide/modules/nav.adoc new file mode 100644 index 0000000000..03a5eb0a9f --- /dev/null +++ b/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] + +