5,705
edits
Changes
Jump to navigation
Jump to search
Platform Team/Server Kit/sugar-client (view source)
Revision as of 05:06, 28 August 2012
, 05:06, 28 August 2012Created page with "== Summary == A program to run on Sugar clients side to interact with Sugar Server Kit based school server. It implements the Client API f..."
== Summary ==
A program to run on Sugar clients side to interact with [[Sugar Server Kit]] based school server. It implements the [[Sugar_Server_Kit/Client_API|Client API]] for usage, e.g. in Sugar Shell, and the {{Code|sugar-client}} utility to get access to the same API from the console.
== Functionality ==
The high level functionality is described by DBus [[Sugar_Server_Kit/Client_API|API]] sugar-client provides. These DBus services will be accessible right after installing {{Code|sugar-client}} package, e.g., to reuse them in Sugar Shell code. To call the same functionality from the command line, use {{Code|sugar-client}} utility.
=== Registration on a school server ===
That's the first operation that should be processed to let the rest of sugar-client functionality working properly. The key configuration option here, is {{Code|api-url}} that points to [[Sugar_Server_Kit/sugar-server#Services|sugar-server's API]]. If {{Code|api-url}} was not explicitly specified, the default one, {{Code|http://schoolserver:8000}}, will be used. If {{Code|api-url}} was explicitly specified, it will be [[#Configuration|kept]] for later usage.
The result of registration will be:
* Setting the {{Code|/desktop/sugar/collaboration/jabber_server}} GConf key with Jabber server url to support Sugar collaboration;
* School server reply will be formed as a regular {{Code|sugar-client.conf}} configuration file and placed to user's profile directory. This configuration will be [[#Configuration|reused]] for all other sugar-client functionality.
If {{Code|auto-register}} configuration option is set, sugar-client will try to make auto-registration on a server on Sugar [[#Background_operations|startup]]. Auto-registration will happen if client is not registered at all or registration is outdated (school server asked clients to process re-registration).
To process registration, either call [[Sugar_Server_Kit/Client_API#org.sugarlabs.client.Server|DBus API]] or use {{Code|sugar-client}} utility:
sugar-client register [''<api-url>'']
=== Auto Journal restore ===
The affected usecase:
* a XO processed several [[#Background operations|auto]] backups (the regular practice in the field),
* and was reflashed,
* XO was '''not''' restored manually before the first auto backup,
* the first auto backup will cleanup backuped Journal on the server (Journal after reflashing is empty),
* any later restore using UI will restore empty Journal (though, it is possible to restore Journal for particular date using CLI tools).
Since disabling auto backups will be considered as a regression, sugar-client needs to provide a way to
auto restore Journal after reflashing.
The implementation will be:
* {{Code|auto-register}} option needs to be more than {{Code|0}},
* {{Code|backup-timeout}} needs to be more than {{Code|0}},
* {{Code|auto-restore}} needs to be {{Code|True}},
* Journal should be empty,
* right after registering newly reflashed XO, sugar-client will start restoring the Journal.
=== Usage statistics ===
Summary:
* Implementation is based on [[Sugar_Server_Kit/sugar-stats|sugar-stats]] library.
* Client behaviour is entirely controlled by [[Sugar_Server_Kit/sugar-stats#Stats_server|stats server]].
To activate stats client activity, [[#Background operations|background operations]] need to be activated. The procedures are:
* sugar-client requests server for stats parameters in {{Code|stats-timeout}} period, in particular:
** should stats gathering process start or stop,
** client side storage parameters;
* if server needs stats, client start gathering process;
* during the server interaction, client sends already collected stats.
To start stats activity, client side should have the following [[#Configuration|configuration]]:
* {{Code|stats-url}}, HTTP(S) url to the stats server,
* {{Code|stats-timeout}}, how frequent (in seconds) client should connect to stats server to upload new information and correct current behaviour.
The stats gathering process might be initiated manually by the command:
sugar-client -d monitor [OPTIONS]
It is important to use secure connection with server, specify server's certificate via {{Code|stats-ca-certs}} parameter.
== Background operations ==
Sugar-client might process background operations. To make it possible, add
sugar-client session
command line call to, e.g., {{Code|~/.sugar/debug}} file, to let it run on Sugar Shell startup. It is important to let sugar-client know about environment variables like {{Code|DISPLAY}} and {{Code|DBUS_SESSION_BUS_ADDRESS}}. This command will start, if it was not started before, DBus service on session bus.
Background operations are:
* Process auto-[[#Registration on a school server|registration]].<br>If {{Code|auto-register}} option is {{Code|1}}, sugar-client will process auto-registration for never registered clients. If {{Code|auto-register}} option is more than {{Code|1}}, sugar-client will check if auto-registration is needed on every start.
* Process regular Journal backup.<br>If {{Code|backup-timeout}} option is more than {{Code|0}}, sugar-client will try to backup the Journal periodically in {{Code|backup-timeout}} seconds.
* Process automatic Journal [[#Auto Journal restore|restore]]<br>if {{Code|auto-restore}} is {{Code|True}}.
* Process regular unattended packages update.<br>If {{Code|update-timeout}} option is more than {{Code|0}}, sugar-client will try to call update process periodically in {{Code|update-timeout}} seconds;
* Process stats [[#Usage statistics|monitoring]].<br>If {{Code|stats-url}} is set.
In all cases, periodical operations will be triggered only once within the same timeout period, even after Sugar session restart.
Background operations will be processed from DBus service. While working, such DBus service will log into {{Code|~/.sugar/''current-profile''/logs/sugar-client.log}} file.
== Backwards compatibility ==
=== Sugar Shell code ===
The sugar-client initiative is intended to replace several client side tools to collect all server interaction functionality in the same place and provide it via DBus API. To support already existed tools, sugar-client provides the same name programs that forward the processing to {{Code|sugar-client}} utility:
* {{Code|dextrose-updater}}<br>utility from Dextrose-2 to process native packages updates.
* {{Code|journal-backup}}<br>Journal backup from Dextrose-2.
* {{Code|journal-restore}}<br>Journal restore from Dextrose-2.
* {{Code|ds-backup.sh}} and {{Code|ds-backup.py}}<br>Journal backup from OLPC XS distribution.
=== Treating UUIDs ===
While interacting with a [[Sugar_Server_Kit/sugar-server#User_identity_models|sugar-server]], sugar-client is different, in case of treating UUIDs while registration, with Sugar Shell code. The UUID value will be a hash of SSH public key (how it is being used for JIDs in Sugar Shell). After registration, UUID value will be kept in {{Code|~/.sugar/''profile''/sugar-client.conf}} file as a sugar-client's {{Code|uuid}} configuration option.
=== OLPC XS ===
In addition to [[Sugar Server Kit]] based solutions, sugar-client will interoperate with OLPC XS school servers.
''TODO''
== Distribution ==
The sugar-client distribution contains:
* {{Code|sugar-client-service}} utility<br>the main program that implements entirely functionality as DBus services for Client API;
* {{Code|sugar-client}} utility<br>to call DBus API from the console;
* {{Code|.service}} files<br>to run {{Code|sugar-client-service}} for each exported DBus interface;
* backwards compatibility command wrappers.
== Configuration ==
The configuration occurs based on several sources (sorted by applied order):
* {{Code|/etc/sugar-client.conf}}<br>system-wide configuration file,
* {{Code|~/.config/sugar-client/config}}<br>user-wide configuration file,
* {{Code|~/.sugar/''current-profile''/sugar-client.conf}}<br>configuration got after registration on a server,
Configuration files contain option names equal to command-line arguments. To get the current configuration, call:
sugar-client-service config
== Troubleshooting ==
In special cases, it is possible to execute sugar-client operations directly, instead of calling DBus service. For that reason, {{Code|-d|--direct}} command-line argument needs to be passed:
sugar-client -d update
== Getting involved ==
* [http://bugs.sugarlabs.org/newticket?component=sugar-server-kit Report] on bugs.
* Read the [http://git.sugarlabs.org/server/client/blobs/master/HACKING HACKING] file to know how to contribute with code.
== Resources ==
* [http://git.sugarlabs.org/server/client Sources].
* Current stable binary [http://download.sugarlabs.org/packages/Server:/1/ packages].
* Development binary [http://download.sugarlabs.org/packages/Server:/Factory/ packages].
A program to run on Sugar clients side to interact with [[Sugar Server Kit]] based school server. It implements the [[Sugar_Server_Kit/Client_API|Client API]] for usage, e.g. in Sugar Shell, and the {{Code|sugar-client}} utility to get access to the same API from the console.
== Functionality ==
The high level functionality is described by DBus [[Sugar_Server_Kit/Client_API|API]] sugar-client provides. These DBus services will be accessible right after installing {{Code|sugar-client}} package, e.g., to reuse them in Sugar Shell code. To call the same functionality from the command line, use {{Code|sugar-client}} utility.
=== Registration on a school server ===
That's the first operation that should be processed to let the rest of sugar-client functionality working properly. The key configuration option here, is {{Code|api-url}} that points to [[Sugar_Server_Kit/sugar-server#Services|sugar-server's API]]. If {{Code|api-url}} was not explicitly specified, the default one, {{Code|http://schoolserver:8000}}, will be used. If {{Code|api-url}} was explicitly specified, it will be [[#Configuration|kept]] for later usage.
The result of registration will be:
* Setting the {{Code|/desktop/sugar/collaboration/jabber_server}} GConf key with Jabber server url to support Sugar collaboration;
* School server reply will be formed as a regular {{Code|sugar-client.conf}} configuration file and placed to user's profile directory. This configuration will be [[#Configuration|reused]] for all other sugar-client functionality.
If {{Code|auto-register}} configuration option is set, sugar-client will try to make auto-registration on a server on Sugar [[#Background_operations|startup]]. Auto-registration will happen if client is not registered at all or registration is outdated (school server asked clients to process re-registration).
To process registration, either call [[Sugar_Server_Kit/Client_API#org.sugarlabs.client.Server|DBus API]] or use {{Code|sugar-client}} utility:
sugar-client register [''<api-url>'']
=== Auto Journal restore ===
The affected usecase:
* a XO processed several [[#Background operations|auto]] backups (the regular practice in the field),
* and was reflashed,
* XO was '''not''' restored manually before the first auto backup,
* the first auto backup will cleanup backuped Journal on the server (Journal after reflashing is empty),
* any later restore using UI will restore empty Journal (though, it is possible to restore Journal for particular date using CLI tools).
Since disabling auto backups will be considered as a regression, sugar-client needs to provide a way to
auto restore Journal after reflashing.
The implementation will be:
* {{Code|auto-register}} option needs to be more than {{Code|0}},
* {{Code|backup-timeout}} needs to be more than {{Code|0}},
* {{Code|auto-restore}} needs to be {{Code|True}},
* Journal should be empty,
* right after registering newly reflashed XO, sugar-client will start restoring the Journal.
=== Usage statistics ===
Summary:
* Implementation is based on [[Sugar_Server_Kit/sugar-stats|sugar-stats]] library.
* Client behaviour is entirely controlled by [[Sugar_Server_Kit/sugar-stats#Stats_server|stats server]].
To activate stats client activity, [[#Background operations|background operations]] need to be activated. The procedures are:
* sugar-client requests server for stats parameters in {{Code|stats-timeout}} period, in particular:
** should stats gathering process start or stop,
** client side storage parameters;
* if server needs stats, client start gathering process;
* during the server interaction, client sends already collected stats.
To start stats activity, client side should have the following [[#Configuration|configuration]]:
* {{Code|stats-url}}, HTTP(S) url to the stats server,
* {{Code|stats-timeout}}, how frequent (in seconds) client should connect to stats server to upload new information and correct current behaviour.
The stats gathering process might be initiated manually by the command:
sugar-client -d monitor [OPTIONS]
It is important to use secure connection with server, specify server's certificate via {{Code|stats-ca-certs}} parameter.
== Background operations ==
Sugar-client might process background operations. To make it possible, add
sugar-client session
command line call to, e.g., {{Code|~/.sugar/debug}} file, to let it run on Sugar Shell startup. It is important to let sugar-client know about environment variables like {{Code|DISPLAY}} and {{Code|DBUS_SESSION_BUS_ADDRESS}}. This command will start, if it was not started before, DBus service on session bus.
Background operations are:
* Process auto-[[#Registration on a school server|registration]].<br>If {{Code|auto-register}} option is {{Code|1}}, sugar-client will process auto-registration for never registered clients. If {{Code|auto-register}} option is more than {{Code|1}}, sugar-client will check if auto-registration is needed on every start.
* Process regular Journal backup.<br>If {{Code|backup-timeout}} option is more than {{Code|0}}, sugar-client will try to backup the Journal periodically in {{Code|backup-timeout}} seconds.
* Process automatic Journal [[#Auto Journal restore|restore]]<br>if {{Code|auto-restore}} is {{Code|True}}.
* Process regular unattended packages update.<br>If {{Code|update-timeout}} option is more than {{Code|0}}, sugar-client will try to call update process periodically in {{Code|update-timeout}} seconds;
* Process stats [[#Usage statistics|monitoring]].<br>If {{Code|stats-url}} is set.
In all cases, periodical operations will be triggered only once within the same timeout period, even after Sugar session restart.
Background operations will be processed from DBus service. While working, such DBus service will log into {{Code|~/.sugar/''current-profile''/logs/sugar-client.log}} file.
== Backwards compatibility ==
=== Sugar Shell code ===
The sugar-client initiative is intended to replace several client side tools to collect all server interaction functionality in the same place and provide it via DBus API. To support already existed tools, sugar-client provides the same name programs that forward the processing to {{Code|sugar-client}} utility:
* {{Code|dextrose-updater}}<br>utility from Dextrose-2 to process native packages updates.
* {{Code|journal-backup}}<br>Journal backup from Dextrose-2.
* {{Code|journal-restore}}<br>Journal restore from Dextrose-2.
* {{Code|ds-backup.sh}} and {{Code|ds-backup.py}}<br>Journal backup from OLPC XS distribution.
=== Treating UUIDs ===
While interacting with a [[Sugar_Server_Kit/sugar-server#User_identity_models|sugar-server]], sugar-client is different, in case of treating UUIDs while registration, with Sugar Shell code. The UUID value will be a hash of SSH public key (how it is being used for JIDs in Sugar Shell). After registration, UUID value will be kept in {{Code|~/.sugar/''profile''/sugar-client.conf}} file as a sugar-client's {{Code|uuid}} configuration option.
=== OLPC XS ===
In addition to [[Sugar Server Kit]] based solutions, sugar-client will interoperate with OLPC XS school servers.
''TODO''
== Distribution ==
The sugar-client distribution contains:
* {{Code|sugar-client-service}} utility<br>the main program that implements entirely functionality as DBus services for Client API;
* {{Code|sugar-client}} utility<br>to call DBus API from the console;
* {{Code|.service}} files<br>to run {{Code|sugar-client-service}} for each exported DBus interface;
* backwards compatibility command wrappers.
== Configuration ==
The configuration occurs based on several sources (sorted by applied order):
* {{Code|/etc/sugar-client.conf}}<br>system-wide configuration file,
* {{Code|~/.config/sugar-client/config}}<br>user-wide configuration file,
* {{Code|~/.sugar/''current-profile''/sugar-client.conf}}<br>configuration got after registration on a server,
Configuration files contain option names equal to command-line arguments. To get the current configuration, call:
sugar-client-service config
== Troubleshooting ==
In special cases, it is possible to execute sugar-client operations directly, instead of calling DBus service. For that reason, {{Code|-d|--direct}} command-line argument needs to be passed:
sugar-client -d update
== Getting involved ==
* [http://bugs.sugarlabs.org/newticket?component=sugar-server-kit Report] on bugs.
* Read the [http://git.sugarlabs.org/server/client/blobs/master/HACKING HACKING] file to know how to contribute with code.
== Resources ==
* [http://git.sugarlabs.org/server/client Sources].
* Current stable binary [http://download.sugarlabs.org/packages/Server:/1/ packages].
* Development binary [http://download.sugarlabs.org/packages/Server:/Factory/ packages].