diff options
author | Gatis Paeglis <gatis.paeglis@qt.io> | 2017-01-04 11:10:05 +0100 |
---|---|---|
committer | Gatis Paeglis <gatis.paeglis@qt.io> | 2017-01-05 08:50:45 +0000 |
commit | 7e24f7a9c233184b52c11ce9598cc923e9aa61d5 (patch) | |
tree | d6f28f7846c60cc8b9da413fd53149281c0d85eb | |
parent | 21703b921dc113bee64e65e3e63bb5482a15c734 (diff) |
doc: improve several sections
Change-Id: Idfccb574f67b7bdef45bbd88fed62fe865d1fdfb
Reviewed-by: Topi Reiniƶ <topi.reinio@qt.io>
-rw-r--r-- | doc/ota.qdoc | 124 | ||||
-rwxr-xr-x | qt-ostree/qt-ostree | 5 | ||||
-rw-r--r-- | src/imports/pluginmain.cpp | 2 | ||||
-rw-r--r-- | src/lib/qotaclient.cpp | 5 | ||||
-rw-r--r-- | src/lib/qotarepositoryconfig.cpp | 2 |
5 files changed, 69 insertions, 69 deletions
diff --git a/doc/ota.qdoc b/doc/ota.qdoc index d8282b8..073d287 100644 --- a/doc/ota.qdoc +++ b/doc/ota.qdoc @@ -136,18 +136,29 @@ Build your product on top of the \B2Q stack, or build your own custom embedded linux image. When the image is ready for the \e {first release}, continue to the - \l {Enabling OTA Functionality on a Device}. + \l {Enabling OTA Functionality on a Device}. Your product should also pre-integrate + an updater based on the Qt OTA Update module. You can find demo updater applications + in the \c SDK_INSTALL_DIR/Tools/ota/examples/ directory. Alternatively, you can + install an updater at a later point as a non-system application. \section2 Enabling OTA Functionality on a Device When preparing a device for shipping and subsequent updates are to be delivered - via OTA, you first need to enable this feature in the \e sysroot: + via OTA, you first need to enable this feature in the sysroot: \list 1 \li Generate OSTree boot compatible initramfs image (skip this step if not using initramfs for booting). + The device should be powered on, booted into your current product (the sysroot to be + released), and connected to a machine from which you will run the \c generate-initramfs + tool. The \l {https://en.wikipedia.org/wiki/Dracut_(software)} {Dracut} framework is + used to generate the initramfs image based on the currently running kernel. The image + uses systemd as an init system. You can, of course, provide your own (not necessarily + Dracut-based) initramfs, as long as you include the required \l {The Booting Process} + {OSTree boot logic}. + To generate the initramfs image, run: \badcode @@ -155,17 +166,8 @@ ./generate-initramfs \endcode - \b {Important:} The device should be powered on, booted into your current - product (the sysroot to be released), and connected to a machine from - which you will run the \c generate-initramfs tool. \l {https://en.wikipedia.org/wiki/Dracut_(software)} - {Dracut} generates the initramfs image based on the currently running kernel. - You can, of course, provide your own (not necessarily dracut based) initramfs, - as long as you include the required OSTree logic from the provided dracut module - (installed in \c {/usr/lib/dracut/modules.d/}). The generated image uses - systemd as an init system. - This will produce an \c initramfs-${device}-${release} file in the - working directory. The initramfs file will be needed in the later steps. + working directory. The generated initramfs file will be needed in the later steps. \target Boot loader integration. \li Boot loader integration. @@ -173,7 +175,7 @@ OSTree maintains bootloader-independent drop-in configuration files in a format as defined by \l {https://www.freedesktop.org/wiki/Specifications/BootLoaderSpec/} {The Boot Loader Specification}. Not all boot loaders support The Boot Loader - Specification, so OSTree contains code to generate native configurations files + Specification, so OSTree contains code to generate native configuration files from the bootloader-independent configurations. The boot script used by your device has to be changed to use the configurations that are @@ -201,8 +203,9 @@ \li \c ${kernel_image}: Path to the Linux kernel image. \li \c ${ramdisk_image}: Path to the initramfs image (optional). \li \c ${bootargs}: Parameters passed to the kernel command line. - \li \c ${bootdir}: Path to other files that belong to the same release - and should be accessible from U-Boot (DTBs, boot scripts). + \li \c ${bootdir}: Path to other files in the \c {\boot} directory + that belong to the same release and should be accessible + from U-Boot (DTBs, boot scripts). \endlist An example \c uEnv.txt when booting with initramfs: @@ -244,12 +247,6 @@ the path and the file name changes. If the original script uses the \c bootm command for loading the kernel image, then the OSTree-enabled script should use \c bootm too. - \note You should expect to find all the files that are required for the - boot process under the \c ${bootdir} path. Before starting to write - U-Boot integration code, you can run the \c qt-ostree tool without - providing the \c --uboot-env-file argument and \l {The generated sysroot} {examine} - the generated sysroot (see step 3). - \li \b {GRUB 2} Whenever the boot loader configuration files need to be updated on a GRUB 2 based system, @@ -262,8 +259,19 @@ \endlist + You should expect to find all the files that are required for the boot process under the + \c {/boot} directory. Before starting to write the boot loader integration code, you can + run the \c qt-ostree tool without providing any boot loader specific files and + \l {The generated sysroot} {examine} the generated sysroot (see step 3). Particularly, + inspect what gets installed in the \c {/boot} directory, as this location is of special + interest to the boot loader integration code. The \c {/boot} directory may contain symbolic + links to files in the \c {loader/} directory (for example, \c {uEnv.txt -> loader/uEnv.txt}). + It is safe to read these symbolic links, as OSTree will ensure that the link target + changes atomically on system updates and rollbacks. + For more examples refer to \l {Device Integration Examples}. + \target The Booting Process \b {The Booting Process} OSTree includes a special \c ostree= kernel argument that points to the corresponding tree @@ -388,7 +396,7 @@ \section2 Preparing a New Update for an OTA Enabled Device - When preparing a new update for a device that already has OTA enabled, the + When preparing a \e {new update} for a device that already has OTA enabled, the workflow is as follows: \list 1 @@ -411,8 +419,8 @@ The above command will create a new commit in the OSTree repository at \c {WORKDIR/ostree-repo/}, or create a new repository if one does not exist. Use the \c --ostree-repo argument to provide a custom path. This repository - is the OTA update and can be copied to a production server at any time. OSTree - repositories can be served via a static HTTP server. + is the OTA update source and can be exported to a production server at any time. + OSTree repositories can be served via a static HTTP server. Notes on the arguments passed to \c {qt-ostree}: @@ -429,10 +437,7 @@ It is advised to regenerate initramfs for each new kernel release, so that the kernel and initramfs - versions \e match. On U-Boot systems: If the new kernel/initramfs - is \b {not compatible} with the boot script on a device, - it \b must be updated as well (see the \c --uboot-env-file - notes below). + versions \e match. \endlist As before, if not using initramfs, it may be necessary to provide @@ -442,30 +447,27 @@ \list \li Provide a path to the \e {new version} of your sysroot. \endlist - \li \b {\c --uboot-env-file} - \list - \li Updating u-boot environment file is supported only for - major releases - when kernel/initramfs versions change. - - The kernel/initramfs version is considered to change when - \c bootcsum changes in the following expression: - \badcode - bootcsum=$(cat vmlinuz initramfs | sha256sum | cut -f 1 -d ' ') - \endcode - \endlist \li \b {\c --start-trivial-httpd} \list \li Starts a simple web server which you can access on the local host at address specified in \c WORKDIR/httpd/httpd-address - file. Entering this address into a web browser lists the - contents of your OSTree repository. This command line - argument is useful for quick testing purposes, in production - with more advanced requirements (TLS authentication) you - will need to use a different web server solution, like - Apache. + file. This command line argument is useful for quick testing purposes, + in production with more advanced requirements (for example, TLS + authentication) you will need to use a different web server solution. \endlist \endlist + Updating the contents of the \c {/boot} directory is supported only for major releases - + when kernel/initramfs versions change. The kernel/initramfs version is considered to + change when \c bootcsum changes in the following expression: + + \badcode + bootcsum=$(cat vmlinuz initramfs | sha256sum | cut -f 1 -d ' ') + \endcode + + \l {The generated sysroot} {Examine} the generated sysroot to see which files are installed + in this directory by \c {qt-ostree} and might need to be updated together with kernel/initramfs. + \li Use Qt OTA APIs to update devices. \li Go back to step 1. @@ -474,13 +476,12 @@ \section2 Securing a Delivery of an Update - OTA is a component of a system and not a security framework. If handled - correctly (GPG and TLS are used properly, the keys are generated and handled - properly and the servers in question are secure to known vulnerabilies and - exploits) OTA is considered secure against realistic attacks. + OTA is a component of a system and not a security framework. It is always the final product + that needs to be analyzed for security implications and requirements. The Qt OTA Update module + supports the following security/authentication mechanisms: \list - \li \b {GPG Signing} + \li \b {GNU Privacy Guard (GPG)} GPG signing helps to ensure that the data was transmitted in-full, without damage or file corruption and that the data was sent by a trusted party. A @@ -493,17 +494,16 @@ sudo apt-get install gnupg2 \endcode - \li \b {TLS Authentication} + \li \b {Transport Layer Security (TLS)} - TLS protects data from tampering and eavesdropping. System administrators use - this to restrict the access to the server (client authentication) and client - devices use this to verify the identitiy of an update server (server authentication). + TLS protects data from tampering and eavesdropping. TLS authentication can be used on the + server side to restrict the access to the server (client authentication) and on client side + to verify the identitiy of an update server (server authentication). Look for \c {--tls-*} command line arguments in the output of \c {./qt-ostree --help}. \endlist - It is advised to use both GPG and TLS in hostile environments. To learn more about the - security topics from the above list, consult dedicated resources. For the corresponding - client side API see OtaRepositoryConfig. + To learn more about the security topics from the above list, consult dedicated resources. + For the corresponding client side API see OtaRepositoryConfig. \section2 Offline Updates and Custom Delivery Mechanisms @@ -515,7 +515,7 @@ a self-contained update package is required when: \list \li A device has no network connection and is intended to be - updated via external media such as a USB drive, or + updated via external media such as a USB drive. \li Some other protocol or proprietary mechanism is used to deliver software to a device. \endlist @@ -524,7 +524,7 @@ \section1 Layout of an OTA Enabled Sysroot - There are only two directories on a device for a safe storage of local files: + There are two directories on a device for a safe storage of local files: \c {/var} and \c {/etc}. The sysroot generated by OTA tools adds convenience symbolic links in the \c {/} root directory, including symbolic links pointing to the \c {/var}. @@ -544,7 +544,7 @@ \li Everything that is part of the OS - mounted read-only to prevent inadvertent corruption. It's recommended that an operating system - ships all of its content in /usr. Contents of this directory are + ships all of its content in /usr. The contents of this directory are updated via OTA. \row \li \c {/etc} @@ -591,11 +591,11 @@ \row \li \c /sysroot - \li Physical / root directory. + \li Physical / root directory mount point. \row \li \c / - \li Versioned filesystem tree's root. + \li Versioned filesystem tree's mount point. \endtable diff --git a/qt-ostree/qt-ostree b/qt-ostree/qt-ostree index 295f321..3789079 100755 --- a/qt-ostree/qt-ostree +++ b/qt-ostree/qt-ostree @@ -166,7 +166,8 @@ usage() echo echo "--uboot-env-file FILE" echo - echo " OSTree boot compatible u-boot environment file." + echo " OSTree boot compatible u-boot environment file. If the filename is 'uEnv.txt'," + echo " then it will be appended to the OSTree's managed uEnv.txt" echo echo "--grub2-cfg-generator FILE" echo @@ -1056,7 +1057,7 @@ detect_target_device() case "${DEVICE}" in # Intel NUC requires a special handling as it is quite different from - # other boot2qt-meta reference devices. + # other meta-boot2qt reference devices. *intel-corei7*|*nuc*) BOOTLOADER="grub2" BOOTFS_TYPE="vfat" diff --git a/src/imports/pluginmain.cpp b/src/imports/pluginmain.cpp index 2087b93..1af643f 100644 --- a/src/imports/pluginmain.cpp +++ b/src/imports/pluginmain.cpp @@ -396,7 +396,7 @@ QT_BEGIN_NAMESPACE \qmlproperty string OtaRepositoryConfig::url This property holds a URL for accessing remote OSTree repository. - The supported schemes at the moment are \c http and \c https. + The supported schemes are \c http and \c https. */ /*! diff --git a/src/lib/qotaclient.cpp b/src/lib/qotaclient.cpp index 329c545..18cf787 100644 --- a/src/lib/qotaclient.cpp +++ b/src/lib/qotaclient.cpp @@ -92,7 +92,6 @@ void QOtaClientPrivate::handleStateChanges() void QOtaClientPrivate::setBootedMetadata(const QString &bootedRev, const QString &bootedMetadata) { - Q_Q(QOtaClient); m_bootedRev = bootedRev; m_bootedMetadata = bootedMetadata; } @@ -369,7 +368,6 @@ bool QOtaClient::fetchRemoteMetadata() */ bool QOtaClient::update() { - Q_D(const QOtaClient); if (!d->m_otaEnabled || !updateAvailable()) return false; @@ -404,7 +402,8 @@ bool QOtaClient::rollback() //! [update-offline] Uses the provided self-contained update package to update the system. Updates the local metadata cache, if it has not been already updated - by calling updateRemoteMetadataOffline(). + by calling updateRemoteMetadataOffline(). This method is an offline + counterpart for update(). This method is asynchronous and returns immediately. The return value holds whether the operation was started successfully. The \a packagePath diff --git a/src/lib/qotarepositoryconfig.cpp b/src/lib/qotarepositoryconfig.cpp index f2049ee..b06edd6 100644 --- a/src/lib/qotarepositoryconfig.cpp +++ b/src/lib/qotarepositoryconfig.cpp @@ -161,7 +161,7 @@ void QOtaRepositoryConfig::setUrl(const QString &url) \property QOtaRepositoryConfig::url \brief a URL for accessing remote OSTree repository. - The supported schemes at the moment are \c http and \c https. + The supported schemes are \c http and \c https. */ QString QOtaRepositoryConfig::url() const { |