Platform Team/Server Kit/sugar-client - Revision history

Alsroot at 12:30, 12 June 2013

2013-06-12T12:30:08Z

← Older revision		Revision as of 08:30, 12 June 2013
Line 1:		Line 1:
			{{Note/warning\|Caution\|The '''sugar-client''' application exits only in [[Deployment_Platform/1.1\|1.x]] releases of the [[Deployment Platform]] (originally named as Sugar Server Kit).<br>For the planing 2.0 release, '''sugar-client''' functionality is split into several Shell [[Deployment_Platform/Shell_Plugins\|plugins]].}}

	== Summary ==		== Summary ==

Alsroot: Alsroot moved page Platform Team/Server Kit/sugar-client/1.2 to Platform Team/Server Kit/sugar-client

2013-06-12T08:49:42Z

Alsroot moved page Platform Team/Server Kit/sugar-client/1.2 to Platform Team/Server Kit/sugar-client

← Older revision		Revision as of 04:49, 12 June 2013
(No difference)

M anish at 18:51, 23 April 2013

2013-04-23T18:51:34Z

← Older revision		Revision as of 14:51, 23 April 2013
Line 165:		Line 165:
	* Current stable binary [http://download.sugarlabs.org/packages/Server:/1/ packages].		* Current stable binary [http://download.sugarlabs.org/packages/Server:/1/ packages].
	* Development binary [http://download.sugarlabs.org/packages/Server:/Factory/ packages].		* Development binary [http://download.sugarlabs.org/packages/Server:/Factory/ packages].

	~~=== Subpages ===~~
	~~{{Special:PrefixIndex/{{PAGENAME}}/}}~~

M anish at 18:51, 23 April 2013

2013-04-23T18:51:15Z

← Older revision		Revision as of 14:51, 23 April 2013
Line 165:		Line 165:
	* Current stable binary [http://download.sugarlabs.org/packages/Server:/1/ packages].		* Current stable binary [http://download.sugarlabs.org/packages/Server:/1/ packages].
	* Development binary [http://download.sugarlabs.org/packages/Server:/Factory/ packages].		* Development binary [http://download.sugarlabs.org/packages/Server:/Factory/ packages].

			=== Subpages ===
			{{Special:PrefixIndex/{{PAGENAME}}/}}

Alsroot: /* Stats configuration */

2012-09-13T08:35:26Z

Stats configuration

← Older revision		Revision as of 04:35, 13 September 2012
Line 71:		Line 71:
	==== Stats configuration ====		==== Stats configuration ====

	~~Stats~~ related configuration ~~is being~~ stored in [[#Configuration\|sugar-client.conf]] configuration file in {{Code\|[stats]}} section:		After enabling stats gathering (after the first successful server connection), all stats related configuration will be stored in [[#Configuration\|sugar-client.conf]] configuration file in {{Code\|[stats]}} section. Enable this configuration manually if you need to enable stats gathering before the first connection to the server.

	[stats]		[stats]

Alsroot: /* Troubleshooting */

2012-09-13T07:54:39Z

Troubleshooting

← Older revision		Revision as of 03:54, 13 September 2012
Line 141:		Line 141:

	== Troubleshooting ==		== Troubleshooting ==

			'''Debugging'''

			To enable debug logging, add the following lines to [[#Configuration\|configuration file]]:

			[main]
			debug = 3

			'''Direct launch'''

	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:		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:

Alsroot: /* Usage statistics */

2012-09-13T07:44:25Z

Usage statistics

← Older revision		Revision as of 03:44, 13 September 2012
Line 68:		Line 68:

	It is important to use secure connection with server, specify server's certificate via {{Code\|stats-ca-certs}} parameter.		It is important to use secure connection with server, specify server's certificate via {{Code\|stats-ca-certs}} parameter.

			==== Stats configuration ====

			Stats related configuration is being stored in [[#Configuration\|sugar-client.conf]] configuration file in {{Code\|[stats]}} section:

			[stats]
			rras = ["RRA:AVERAGE:0.5:1:4320", "RRA:AVERAGE:0.5:5:2016"]
			step = 60
			enabled = true

	== Background operations ==		== Background operations ==

Alsroot: /* Resources */

2012-08-30T11:50:48Z

Resources

← Older revision		Revision as of 07:50, 30 August 2012
Line 144:		Line 144:
	== Resources ==		== Resources ==

	* [http://git.sugarlabs.org/~~server~~/client Sources].		* [http://git.sugarlabs.org/desktop/stats/commits/sugar-client-1.2 Sources].
	* Current stable binary [http://download.sugarlabs.org/packages/Server:/1/ packages].		* Current stable binary [http://download.sugarlabs.org/packages/Server:/1/ packages].
	* Development binary [http://download.sugarlabs.org/packages/Server:/Factory/ packages].		* Development binary [http://download.sugarlabs.org/packages/Server:/Factory/ packages].

Alsroot: Created 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..."

2012-08-28T09:06:32Z

Created 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..."

New page

== 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]]. 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. 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]] if {{Code|auto-restore}} is {{Code|True}}.
* Process regular unattended packages update. 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]]. 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}} utility from Dextrose-2 to process native packages updates.
* {{Code|journal-backup}} Journal backup from Dextrose-2.
* {{Code|journal-restore}} Journal restore from Dextrose-2.
* {{Code|ds-backup.sh}} and {{Code|ds-backup.py}} 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 the main program that implements entirely functionality as DBus services for Client API;
* {{Code|sugar-client}} utility to call DBus API from the console;
* {{Code|.service}} files 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}} system-wide configuration file,
* {{Code|~/.config/sugar-client/config}} user-wide configuration file,
* {{Code|~/.sugar/''current-profile''/sugar-client.conf}} 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].