Sugar on a Stick/Sugar Clone

From Sugar Labs
< Sugar on a Stick
Revision as of 12:18, 18 July 2011 by Satellit (talk | contribs) (Notes: update link to mirabelle)
Jump to: navigation, search

Es icon.jpg la versión revisada español

Latest news:

10 February 2011: A new bundle, named SoaS-remix, is an installable .iso system image file builder. It includes, a launcher named 'liveos-disk-to-iso', and temporary versions of,, (pending livecd-tools acceptance).

The SoaS-remix bundle will inject itself into the image, unbundle itself into /tmp,
launch (with editable options), build a new iso, then cleanup /tmp.

Sugar Clone is now in a Sugar on a Stick repository clone at

28 January 2011: An alpha version of a python script that allows one to rebuild a custom iso image from a running image by 1.) staging the build on an attached hard drive and then 2.) copy only the content already on the current image. See See below.


Sugar Clone makes it easy to share your personally-customized version of Sugar on a Stick.

  1. Start with a fresh install of Sugar on a Stick (or use your current or favorite working image).
    (For greatest flexibility and reliability, use the livecd-iso-to-disk option, --home-size-mb NNN )
  2. Add Activities, change Home favorites, save Browse bookmarks, Etoys projects, Physics model templates, download distributable ebooks, ... ...
  3. Plug in a second, target USB/SD stick.
  4. Switch to the Terminal Activity and execute 3 simple commands.

Voilà, you have a Sugar Clone! And the Sugar Clone can make new Sugar Clones with just 1 simple, Terminal command.

Some technicalities

Sugar Clone is, at this point in time, a Bash script (August 2010) that aids in the copying of a customized LiveOS image, such as Sugar on a Stick, to a secondary device. It works from within a booted LiveOS image to copy that image. Or it may be used to copy a LiveOS image between 2 attached USB/SD storage devices. It is intended to support the Sugar customization kit projects.

A small, utility script, Sugar Cellar, is available in the bundle, or separately. It is used to report on the storage space available on the persistent overlay, home directory, and other file spaces attached to the running image.

A python script (alpha version) has been added in January 2011 that uses an attached hard drive to stage the creation of a new iso image installation file of the running SoaS instance. This permits system overlay refreshing and easy distribution of customized images.

See this announcement post, And this follow-on discussion thread,
Most recent post:


Test Usage

Pre-boot installation option:

  1. Obtain the SugarClone script at
  2. Before booting the SoaS device that will be the source of the new Sugar Clone, copy the SugarClone script to the root, '/', folder at the base of the filesystem for the device, or, to /mnt/live (from the perspective of a running LiveOS image).


Boot the computer from the USB stick into SoaS, and insert, or have a second USB device inserted, into the computer.


In the Terminal Activity Activity-terminal.png of that running SoaS image, enter the command,

If there is more than one USB/SD storage device available, a menu of the devices will appear allowing for selection of the target device.

The scripts will copy the currently running image to the target device. When that device is booted, a new, Sugar Learner sign-in will be triggered. The previously customized Journal and operating system will be present on the Sugar Clone.

Live USB installation option

On a running LiveOS image, the root folder of the parent USB/SD device is available at the /mnt/live mount point. The SugarClone script can be obtained (assuming Internet connectivity) as follows:

In the Terminal Activity Activity-terminal.png,
change the working directory:

cd /mnt/live

Get the SugarClone script file:




Possible Use Cases

Curriculum packaging

  1. A teacher wants to prepare a SoaS image with a custom set of installed Activity bundles or a Journal of Activity instances for an upcoming class term.
  2. The teacher modifies their current working image by adding or deleting Activity bundles from their Home view and adding or removing Journal entries with specific content (such as a Physics model template or Etoys project), even saving distributable ebooks, or bookmarks in Browse Activity instances that are named for specific sets of local web destinations (a class portal perhaps for deployments lacking Internet connectivity).
  3. The teacher scrubs out any personal passwords or other history that should not be shared in the new copies.
  4. A fresh or recycled USB stick is inserted into the computer running the customized SoaS image and the SugarClone script is executed.

Full image backup or sharing

  1. A Learner has modified their environment, perhaps adding Activity bundles and prepared specific instances such as a Activities/Physics simulation.
  2. Their modifications include changes to their operating system installed through yum or RPM to obtain some new core functionality.
  3. The Learner wants to archive or share this image with friends or for a backup.
  4. Personal or private information is scrubbed from the Journal or Browse history and other potential stores.
  5. The User creates one or more Sugar Clones.

This method of backup has the advantage that it copies Learner changes to the core operating system as well as the Journal. A LiveOS image using a separate persistent home folder could be partially cloned with either the operating system overlay or home folder without the other, should that be desired.

Ubiquitous Sugar

An overarching vision is to be able to use and share Learners' Sugar environment wherever there are computing devices (see Project Essence and Core Challenges.) Sugar then becomes a platform for continuous learning. Working out the technical and social challenges of near-instantly resumable and portable learning with software is our challenge. The separation of the system and Learner's Journal and Activities opens more opportunities for simpler solutions.

See also

  • Other neat uses for the modified_livecd-iso-to-disk script.


These scripts have been tested with SoaS-Mirabelle (available at but should work with other versions of SoaS.

The current version of the script has the /bin/bash shell specified without the -x (xtrace) option. Set this option, #!/bin/bash -x in the first line of the script to aid testing. When set, the script will show a lot of output on the screen as it runs.

The script is copied to any new Sugar Clone devices prepared with this script so that Sugar Clone images can easily propagate themselves. This also applies to all new SoaS installations that are prepared with these scripts.

Needs and future:

  1. More review and testing.
    • SD cards
ONE PROBLEM on Acer Aspire One 532H:
"Turns out the SD adapter uses the PCIe bus"
and is not recognized by Sugar or your Script
anyway to detect this in the script? (It is being used in test deployments now.)
The SD slot is NOT bootable on this model but could be used to make clone custom SD's for use on other netbooks (EeePC900)
satellit 04/26/2010
  1. Submission of the modified_livecd-iso-to-disk script upstream.
  2. Modifications for XOs.
  3. Modifications for Intel Macintosh computers.
  4. Extraction of the Learner's Sugar image name for labeling the Clone. (available 14 April 2010)
  5. A Sugar Activity that calls or controls the scripts. See Activities/Toaster.
  6. A way to automatically identify extra partitions on devices with more than one available partition.
  7. A way to automatically identify live media images on secondary devices and partitions that could be used as sources for a Sugar Clone.
  8. Bundling of the scripts for convenience until they are included in SoaS. (available 23 April 2010)
  9. Write custom iso image files to refresh the SoaS installation with an empty system overlay and permit redistribution of the customized system iso. (available 28 January 2011)
  10. Extend the facility to any Sugar image.
  11. Allow Learner account/stick swapping without rebooting.
  12. Allow multi-architecture distributions for larger capacity devices.

These all should help us better prepare a SoaS customization kit.


Sugar Clone

The script is available at and is displayed from there below.
Embedded help, which describes the script and its usage in greater detail, is available in the script below (There is a 'shortusage()' section followed by a more complete 'usage()' section).

Sugar Cellar

A small, utility script, available in the bundle, or separately. It is used to report on the storage space available on the persistent overlay, home directory, and other file spaces attached to the running image.



  • The edit-liveos script can be thought of as a "liveos-disk-to-iso" script. It takes the currently installed system and converts it back into an iso9660 image file—but with all the current customizations to the system and Learner files.
  • It is recommended that you use a separate, home.img file for the Learner's /home/liveuser directory to maximize your "mileage" with the consumable storage in the system overlay file.
    • This installation variation is only available currently from the livecd-iso-to-disk script packaged on the installation iso at either /LiveOS/ or /mnt/live/LiveOS/ (from inside a running installation) or, in standard Fedora LiveOS Spins, in /LiveOS/ in the device's outer filesystem (this is equivalent to /mnt/live/LiveOS/ from within the running installation).
    • livecd-iso-to-disk uses the --home-size-mb NNN options to specify the home.img installation.
  • With edit-liveos (disk-to-iso), a nearly-consumed overlay can be refreshed by rebuilding the system into a new, SquashFS image that resparses the system files and repackages them into an iso installation file for reuse or distribution.


SoaS-remix is a bundle of and supporting scripts to make testing and use easier.

The bundle will change with development. As of 10 February 2011 it contains,

  • - the primary remix builder
  • liveos-disk-to-iso - a Bash launcher script for
  •,, - temporary modules from livecd-tools with pending squashfs-compression_type() functionality

Get the SoaS-remix bundle:



  1. Having used the livecd-iso-to-disk with --home-size-mb NNN to install my SoaS iso onto a Live USB device, I proceed to customize my working Stick with new Activites, content, or system settings as described above in step 2.
  2. Before copying SoaS-remix to the Live USB, it may be easiest to open it in an editor and adjust the set command statement at line 86 to something appropriate for your system.
    # Example command line. Edit and uncomment the set statement below to suit.
    # set -- -v -n SoaSremix -o /media/WD-ext4 -t /media/WD-ext4 -i /GPL \
    #        -r /boot/olpc_build --builder fgrose --clone /dev/live
  3. I then copy SoaS-remix onto the USB device bearing a SoaS installation (to the /LiveOS/ folder on the device's filesystem).
  4. Before running the SoaS-remix script bundle, I run these 2 system updates:
    • yum install rsync
    • yum update livecd-tools
      (Together, these operations consume about 8 MiB of overlay capacity, so be sure to have that available.
      You can use #Sugar Cellar to check.)
  5. I boot my Sugar Stick on a system with a hard disc bearing an ext4-formatted partition with well over 5 GiB of free space.
  6. Once booted, I mount the partition from a Terminal activity with the root user account:
    • su -
    • mount /dev/sdb2 /media/ext4
      (The device node and mountpoint names will depend on your resource names. You might find the device node by issuing df -Th or cat /proc/partitions and knowing something about your disc resources.)
  7. If you didn't edit the set command before copying, you can use the vi editor or just invoke SoaS-remix with suitable parameters, such as,
    /mnt/live/LiveOS/SoaS-remix -v -n SoaSremix -o /media/ext4 -t /media/ext4 -i /GPL -r /boot/olpc-build --builder fgrose --clone /dev/live
  8. Otherwise, with a proper set command statement, SoaS-remix may be invoked simply with this command line:

Common options:

 -v requests a slightly more verbose output,
 -n names the remix,
 -o designates the output file location,
 -t designates the temporary directory to use,
 -i designates files from the outer USB device's filesystem to include in the build.
    Multiple files may be included with this syntax: -i "/f1, /d/f2, /d[/d.../f3]"
 -r designates releasefile names in the image that may need adjustment,
 --builder names the builder,
 --clone flags the cloning feature to be invoked by the script on the
 /dev/live device partition (the currently running image).

 -h (alone) will show you some more options

The script will launch and provide limited process reporting. (I open another Terminal tab and list the contents of my temporary directory to see the changes occurring.)

After about 10 minutes (on my system) the product iso file will be ready in the file, /media/ext4/SoaSremix-x86_64-YYYYMMDD.HHMM.iso

  • This iso holds, in the /LiveOS/ directory, the home.img from the booted Live USB Stick, and the fresh squashfs.img osmin.img files.

The livecd-iso-to-disk script should be used to install the new build, but it currently doesn't propagate a home.img file from the iso, so you will have to manually move the home.img file to the /LiveOS/ folder of a new USB device.

(With a GNU/Linux system, the iso image file can be auto-mounted in Nautilus and one can see the file to copy in the /LiveOS/ folder under the iso-image device.)

If one only wants to refresh the source Live USB stick, then the home folder does not need to be transferred. The following commands will refresh the overlay and system image:

  • Boot into another image (such as from another SoaS device) with the target SoaS device inserted into a second USB connection port.
  • From a root user Terminal activity or console session, issue this installation command:
    /path/to/livecd-iso-to-disk --overlay-size-mb NNN /path/to/refreshed/image.iso /dev/sd?1
  • One needs to determine the proper paths on the working systems.
    For example, on a booted Mango Lassi, the path is /LiveOS/livecd-iso-to-disk.

If the source Live USB was installed without a separate home.img, the above commands will also refresh your image, but it will consume the overlay more rapidly as all Activity storage is in the write-once overlay storage. Even deleting Activities will consume more of the storage! (See LiveOS image.) Because the home folder (Learner's Journal and Activities) are mixed into the system SquashFS image file in this configuration, that portfolio as a whole will be less easily swapped or shared from one device or machine to another.

Testing of any of the above would be appreciated.

The script code is below: