Commit 1994ce9e authored by Aard's avatar Aard

[doc] Use consistent spelling of ssu vs. SSU

To avoid confusion, "ssu" should be used for this software,
"SSU" for the concept of seamless software updates
parent 3ad96b5e
### Don't edit this file manually. Update it in git, if there's a good reason to do so ###
#
# This file is used by SSU to find out which device (or device variant) it's
# This file is used by ssu to find out which device (or device variant) it's
# running on, and use this information to look for device family, and device
# specific adaptation(s). The last two values are used when resolving URLs,
# and therefore change depending on vendor setup.
#
# To avoid quoting in the search strings SSU will do each checks on the
# To avoid quoting in the search strings ssu will do each checks on the
# _value_, and return the key, if successful. The device model returned
# my either be the device model, or a variant. Before resolving the family
# and adaptations variants will be resolved through entries under the
......
......@@ -8,9 +8,9 @@
#ifndef _CONSTANTS_H
#define _CONSTANTS_H
/// The group ID SSU expects to run as. This is usually the GID of the main phone user
/// The group ID ssu expects to run as. This is usually the GID of the main phone user
#define SSU_GROUP_ID 1000
/// Path to the main SSU configuration file
/// Path to the main ssu configuration file
#define SSU_REPO_CONFIGURATION "/usr/share/ssu/repos.ini"
/// Path to board / device family mappings file
#define SSU_BOARD_MAPPING_CONFIGURATION "/var/cache/ssu/board-mappings.ini"
......@@ -18,7 +18,7 @@
#define SSU_BOARD_MAPPING_CONFIGURATION_DIR "/usr/share/ssu/board-mappings.d"
/// Directory where all the non-user modifiable data sits
#define SSU_DATA_DIR "/usr/share/ssu/"
/// The SSU protocol version used by the ssu client libraries
/// The ssu protocol version used by the ssu client libraries
#define SSU_PROTOCOL_VERSION "1"
/// Maximum recursion level for resolving variables
#define SSU_MAX_RECURSION 1024
......
/*! @mainpage SSU
/*! @mainpage ssu
@section intro Introduction
ssu provides low level glue to offer "Seamless Software Updates" (SSU)
utilizing standard components (like Zypper and PackageKit). ssu provides
the basic configuration and package selection hints, but is not directly
involved in package handling.
\ref rndssu "Using SSU in RnD setups"
In documentation (and code) the all lowercase term "ssu" should be used
when referring to this software, the all uppercase term "SSU" when
referring to the update concept.
- \ref rndssu "Using ssu in RnD setups"
*/
\ No newline at end of file
/*! @page rndssu Overview of SSU RnD features
/*! @page rndssu Overview of ssu RnD features
@section intro Introduction
SSU offers the ability to run in a special RnD mode for use during development. The main features are:
ssu offers the ability to run in a special RnD mode for use during development. The main features are:
- use a different set of repositories than for the published product
- allow using private (password-protected) repositories
......@@ -24,31 +24,31 @@ See the \ref rndssu_clientprotocol client protocol definition for protocol detai
@subsection rndssu_registration Device registration
- The client sends a registration request with (LDAP) account credentials to the SSU backend; the client forgets about the credentials directly after sending the request
- The SSU backend verifies the credentials, and on success, creates a client certificate which gets sent to the client
- The client stores the certificate, and uses it for future requests for authentication. This allows for user specific per-device registrations which can be individually revoked on the SSU backend without keeping parts of the regular account credentials on the device
- The client sends a registration request with (LDAP) account credentials to the ssu backend; the client forgets about the credentials directly after sending the request
- The ssu backend verifies the credentials, and on success, creates a client certificate which gets sent to the client
- The client stores the certificate, and uses it for future requests for authentication. This allows for user specific per-device registrations which can be individually revoked on the ssu backend without keeping parts of the regular account credentials on the device
The username may be sent together with a domain (like user\@example), with the SSU backend in charge of mapping that domain to a different LDAP organization, accounts database, or anything else useful for the given organization. The domain will be stored on both device and SSU backend, and allows for using different repository configurations for members of different organizations as well as limiting repository access for some domains.
The username may be sent together with a domain (like user\@example), with the ssu backend in charge of mapping that domain to a different LDAP organization, accounts database, or anything else useful for the given organization. The domain will be stored on both device and ssu backend, and allows for using different repository configurations for members of different organizations as well as limiting repository access for some domains.
The client-side implementation for this is in libssu, available through the SSU CLI and the ssud DBUS API.
The client-side implementation for this is in libssu, available through the ssu CLI and the ssud DBUS API.
@subsection rndssu_repo_protection Protecting RnD repositories
Zypper only allows using user/password pairs for authentication. To avoid patching zypper this method of authentication is used, the device retrieves authentication tokens from the SSU server after successfully authenticating there with the client certificate.
Zypper only allows using user/password pairs for authentication. To avoid patching zypper this method of authentication is used, the device retrieves authentication tokens from the ssu server after successfully authenticating there with the client certificate.
Additional benefits of this method are easier deployment of repositories -- maintaining a huge list of individual credentials on the repository server can be tricky, especially on CDNs. Authenticating against a list of client certificates in such a scenario would be even more problematic.
The repository protection should change the passwords in regular intervals, and keep the passwords on the repository server and SSU backend in sync. Validity of old and new credentials should overlap slightly. As devices are sharing credentials for repository access this is the week point in this setup, so credentials should be changed often enough to make them useless before they are discovered/used on leaks.
The repository protection should change the passwords in regular intervals, and keep the passwords on the repository server and ssu backend in sync. Validity of old and new credentials should overlap slightly. As devices are sharing credentials for repository access this is the week point in this setup, so credentials should be changed often enough to make them useless before they are discovered/used on leaks.
@subsection rndssu_credentialsupdate Updating on-device credentials
Updating of on-device credentials happens within the URL resolver plugin for Zypper. On repository refresh,
- before returning the URL SSU checks if this repository requires authentication
- before returning the URL ssu checks if this repository requires authentication
- checks the time of last credentials update
- if the stored credentials are too old, authenticate to the SSU backend with the client certificate, and request a new set of credentials
- if the stored credentials are too old, authenticate to the ssu backend with the client certificate, and request a new set of credentials
- store the credentials on disk for Zypper to use
- return the resolved URL, and hand over to Zypper
The SSU backend checks if the user is still a valid (LDAP) user, and removes the registration for deleted/locked users. The device side removes on-device credentials if the SSU backend authentication fails.
The ssu backend checks if the user is still a valid (LDAP) user, and removes the registration for deleted/locked users. The device side removes on-device credentials if the ssu backend authentication fails.
*/
\ No newline at end of file
/*! @page rndssu_clientprotocol Client protocol definition for RnD SSU
/*! @page rndssu_clientprotocol Client protocol definition for RnD ssu
@section intro Introduction
This page contains the protocol definition used between a SSU client on a device and a SSU server. The client-side of this protocol is implemented in libssu and the SSU CLI. The server side heavily depends on the available infrastructure, and is not available in public. See \ref rndssu_implementation_notes "the implementation notes for RnD SSU" for additional details required to implement a SSU server.
This page contains the protocol definition used between a ssu client on a device and a ssu server. The client-side of this protocol is implemented in libssu and the ssu CLI. The server side heavily depends on the available infrastructure, and is not available in public. See \ref rndssu_implementation_notes "the implementation notes for RnD ssu" for additional details required to implement a ssu server.
$DEVICEID in the following examples is a variable filled by the SSU client before making the request, replaced by the devices IMEI (QSystemDeviceInfo::imei()), or a unique device ID (QSystemDeviceInfo::uniqueDeviceID()), if the IMEI is not available (netbooks, SDK, ...)
$DEVICEID in the following examples is a variable filled by the ssu client before making the request, replaced by the devices IMEI (QSystemDeviceInfo::imei()), or a unique device ID (QSystemDeviceInfo::uniqueDeviceID()), if the IMEI is not available (netbooks, SDK, ...)
@section registration Device registration
- The client sends a POST request to https://ssu.example.com/ssu/device/$DEVICEID/register.xml
- The client MUST verify the servers certificate against the configured CA for this SSU server
- The client MUST verify the servers certificate against the configured CA for this ssu server
- The client MUST send HTTP basic auth information with the request, containing (LDAP) account credentials queried from the user
- The client MUST NOT save (LDAP) account credentials obtained from the user on the device
- The client MAY send additional parameters in the requests body as content type application/x-www-form-urlencoded. Valid parameters are:
......
......@@ -361,14 +361,14 @@ void Ssu::sendRegistration(QString usernameDomain, QString password){
ssuCaCertificate = SsuRepoManager::caCertificatePath();
if (ssuCaCertificate.isEmpty()){
setError("CA certificate for SSU not set ('_ca-certificate in domain')");
setError("CA certificate for ssu not set ('_ca-certificate in domain')");
return;
}
if (!settings->contains("register-url")){
ssuRegisterUrl = repoUrl("register-url");
if (ssuRegisterUrl.isEmpty()){
setError("URL for SSU registration not set (config key 'register-url')");
setError("URL for ssu registration not set (config key 'register-url')");
return;
}
} else
......@@ -573,7 +573,7 @@ void Ssu::updateCredentials(bool force){
QString ssuCaCertificate, ssuCredentialsUrl;
ssuCaCertificate = SsuRepoManager::caCertificatePath();
if (ssuCaCertificate.isEmpty()){
setError("CA certificate for SSU not set ('_ca-certificate in domain')");
setError("CA certificate for ssu not set ('_ca-certificate in domain')");
return;
}
......
......@@ -63,7 +63,7 @@ class Ssu: public QObject {
QHash<QString, QString> parametersOverride=QHash<QString, QString>());
/**
* Unregister a device. This will clean all registration data from a device,
* though will not touch the information on SSU server; the information there
* though will not touch the information on ssu server; the information there
* has to be manually cleaned for a device we don't own anymore, but will be
* overwritten next time the device gets registered
*/
......
......@@ -13,12 +13,12 @@
#include "ssu.h"
#ifndef SSU_CONFIGURATION
/// Path to the main SSU configuration file
/// Path to the main ssu configuration file
#define SSU_CONFIGURATION "/etc/ssu/ssu.ini"
#endif
#ifndef SSU_DEFAULT_CONFIGURATION
/// Path to the main SSU configuration file
/// Path to the main ssu configuration file
#define SSU_DEFAULT_CONFIGURATION "/usr/share/ssu/ssu-defaults.ini"
#endif
......@@ -72,7 +72,7 @@ class SsuCoreConfig: public SsuSettings {
Q_INVOKABLE bool isRegistered();
/**
* Return the date/time when the credentials to access internal
* SSU servers were updated the last time
* ssu servers were updated the last time
*/
Q_INVOKABLE QDateTime lastCredentialsUpdate();
/**
......
......@@ -53,7 +53,7 @@ class SsuDeviceInfo: public QObject {
*/
Q_INVOKABLE QString deviceModel();
/**
* Calculate the device ID used in SSU requests
* Calculate the device ID used in ssu requests
* @return QSystemDeviceInfo::imei(), if available, or QSystemDeviceInfo::uniqueDeviceID()
*/
Q_INVOKABLE QString deviceUid();
......@@ -67,7 +67,7 @@ class SsuDeviceInfo: public QObject {
*
* See Ssu::DeviceTypes for supported types.
*
* If not configured the model name used by SSU will be returned instead
* If not configured the model name used by ssu will be returned instead
* for product and type.
* If no manufacturer is found UNKNOWN is returned.
* For an invalid type an empty string is returned.
......
......@@ -19,12 +19,12 @@
#include "../constants.h"
#ifndef SSU_FEATURE_CONFIGURATION
/// Path to the main SSU configuration file
/// Path to the main ssu configuration file
#define SSU_FEATURE_CONFIGURATION "/var/cache/ssu/features.ini"
#endif
#ifndef SSU_FEATURE_CONFIGURATION_DIR
/// Path to the main SSU configuration file
/// Path to the main ssu configuration file
#define SSU_FEATURE_CONFIGURATION_DIR "/usr/share/ssu/features.d"
#endif
......
......@@ -14,12 +14,12 @@
</case>
</set>
<set name="repomanager" description="Test to determine if ssu repository management works properly" feature="repomanager">
<case name="ut_repomanager" type="Functional" description="SSU repo management test" timeout="1000" subfeature="">
<case name="ut_repomanager" type="Functional" description="ssu repo management test" timeout="1000" subfeature="">
<step expected_result="0">/opt/tests/ssu/runtest.sh ut_repomanager</step>
</case>
</set>
<set name="ssucli" description="Test to determine if ssu command line tool works properly" feature="ssucli">
<case name="ut_ssucli" type="Functional" description="SSU command line utility test" timeout="1000" subfeature="">
<case name="ut_ssucli" type="Functional" description="ssu command line utility test" timeout="1000" subfeature="">
<step expected_result="0">/opt/tests/ssu/runtest.sh ut_ssucli</step>
</case>
</set>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment