= Operation of system image server =
== Adding a new channel ==
=== Manual channels ===
To add a new manual channel, use si-shell and run:
{{{
pub.create_channel("<channel>")
}}}

Then for each device you want in the channel, do:
{{{
pub.create_device("<channel>", "<device>")
}}}

You may then want to add the channel to etc/config to configure image expiry like this:
{{{
[channel_<channel>]
type = manual
fullcount = 15
}}}


=== Automatic channels ===
Automatic channels are those which are populated by import-images run. They first have to be created just like manual channels and then an importer configuration must be written to etc/config.

The importer (bin/import-images) processes the automatic channels, It goes through the list of files in the channel and call the listed generator for each of those. The generator returns the path to a tarball. If all the paths match the previous image, no image is generated, if one or more differ, then a new image is published. If one of the generator returns None as is the case on failure, no image is published.

The current list of generators is:
 * '''version''': Generates a new version tarball containing the channel configuration. (required, no args)
 * '''cdimage-device''': Imports a device tarball from a local cdimage server (path and series are required args)
 * '''cdimage-ubuntu''': Imports a rootfs tarball from a local cdimage server (path and series are required args)
 * '''cdimage-custom''': Imports a custom tarball from a local cdimage server (path and series are required args)
 * '''http''': Imports a .tar.xz tarball directly from a URL. (URL is a required arg)
 * '''keyring''': Meant to be applied after a rootfs tarball. Will override the system-image keyring with the local one.
 * '''system-image''': Mirrors a file from another local system-image channel. (channel and file are required args)
 * '''remote-system-image''': Same as system-image but over the network

The configuration lists all the files and then for each file the matching generator, arguments and optional parameters.
Note that it's possibly to make a file device-specific by appending ",<device>" to its name.

Here's a working example from the ubuntu-touch/rc-proposed/ubuntu channel:
{{{
[channel_ubuntu-touch/rc-proposed/ubuntu]
type = auto
versionbase = 1
fullcount = 15
deltabase = ubuntu-touch/rc/ubuntu, ubuntu-touch/rc-proposed/ubuntu, ubuntu-touch/stable/ubuntu
files = ubuntu, device,krillin, device,vegetahd, device,arale, device, custom, version
file_ubuntu = cdimage-ubuntu;/srv/cdimage.ubuntu.com/www/full/ubuntu-touch/vivid/daily-preinstalled;vivid;import=any
file_custom = cdimage-custom;/srv/cdimage.ubuntu.com/www/full/ubuntu-touch/vivid/daily-preinstalled;vivid;import=any
file_device = cdimage-device;/srv/cdimage.ubuntu.com/www/full/ubuntu-touch/vivid/daily-preinstalled;vivid;import=any
file_device,krillin = http;http://people.canonical.com/~jhm/barajas/master/device_krillin.tar.xz;name=device,monitor=http://people.canonical.com/~jhm/barajas/master/device_krillin.build
file_device,vegetahd = http;http://people.canonical.com/~jhm/barajas/master/device_vegetahd.tar.xz;name=device,monitor=http://people.canonical.com/~jhm/barajas/master/device_vegetahd.build
file_device,arale = http;http://people.canonical.com/~alextu/tangxi/master/device_arale.tar.xz;name=device,monitor=http://people.canonical.com/~alextu/tangxi/master/device_arale.build
file_version = version
}}}

The example above defines an automatic channel with numbering starting at image 1, storing up to 15 full images and publishing deltas both from itself (previous image to new image) and from the ubuntu-touch/rc/ubuntu and ubuntu-touch/stable/ubuntu channels (so deltas don't have to be generated on copies).
The channel is made of 4 tarballs, an ubuntu rootfs, a device tarball, a customization tarball and a version tarball. A device specific override is present for the device tarball so that the krillin, vegetahd and arale targets get a separate one imported over http rather than coming from cdimage.


=== Copying configuration from an existing channel ===
When creating a channel that must be identical in configuration to another one, you can use the following with si-shell:
{{{
pub.create_channel("<channel>")
[pub.create_device("<channel>", device) for device in pub.list_devices("<base channel>")]
}}}

And then copy/paste the configuration in etc/config, edit it and run bin/import-images.

== Hiding a channel ==
Channels can be marked as hidden so that they don't show up in any listing that may be offered to the user.
To mark a channel as hidden, use si-shell:
{{{
pub.hide_channel("<channel>")
}}}

To make the channel visible again, do:
{{{
pub.show_channel("<channel>")
}}}

== Renaming a channel ==
To rename a channel, use si-shell and do:
{{{
pub.rename_channel("<channel>", "<new name>")
}}}

This may take a little while as all the version tarballs have to be rewritten in the process to contain the updated name in their channel.ini file.

== Removing a channel ==
Removing a channel and all its content can be done with:
{{{
pub.remove_channel("<channel>")
}}}

== Phased percentage ==
=== Getting image phased percentage ===
Print out the phased percentage of the selected image:
{{{
device = pub.get_device("<channel>", "<device>")
device.get_phased_percentage(<version>)
}}}

=== Setting image phased percentage ===
To safely set the phased percentage of a selected image, use the bin/set-phased-percentage script. Remember that only the latest image in the channel can have its phased percentage modified.
{{{
$ bin/set-phased-percentage -vvv <channel> <device> <version> <percentage>
}}}

== Channel aliases and redirect ==
=== Aliases ===
Aliases are working channels which the client can use as if they were regular channels but which return content mirrored from another channel. Aliases can be retargeted at any time and when that happens, the clients will simply do a full image update ot the new alias target.

To create a new alias, use si-shell and do:
{{{
pub.create_channel_alias("<alias name>", "<target name>")
}}}

To remove an alias, just use remove_channel as documented above.

To re-target an alias, use:
{{{
pub.change_channel_alias("<alias name>", "<new target name>")
}}}

All alias operations will typically take a little while as all the version tarballs have to be regenerated to contain an updated channel.ini file.

An alias will always use the same set of devices as its target so device operations on an alias channel will be reverted the next time the import-images script runs.

=== Redirects ===
A channel redirect is a simple redirection typically used when a channel was renammed and the old name needs to stay valid for a transition period. Anyone flashing or updating from a redirect will receive a channel.ini file containing the new name of the channel, which means that the next time they update, they'll be querying for the new channel name.

A redirect can be setup using:
{{{
pub.create_channel_redirect("<redirect name>", "<target name>")
}}}

Removing can be done using remove_channel as documented above. There is no re-targeting function as this will typically never happen. If you do need to re-target a redirect, simply remove it and re-create it.

== Reverting a bad image ==
=== Removing an image ===
In the very rare event that you are sure no client will have updated to the image or that if they did, there's no way for them to recover from it, then you can simply remove the image using si-shell.

For each affected device do:
{{{
device = pub.get_device("<channel>", "<device>")
version = <version>
for type, version, base in [(image['type'], image['version'], image.get("base", None))
                            for image in device.list_images()
                            if image['version'] == version]:
    device.remove_image(type, version, base)
}}}

=== Reverting an image ===
To revert an image, you can simply copy a good build as a new image.
To do this, simply use copy-image, passing it the channel, device and version of a good build and the name of the target channel (possibly itself).

Note that if the channel is set to auto-import, the bad image will be re-imported almost immediately, so you need to make sure to turn off any automated imports until a fixed image is ready for import.

Once that's done, you may want to completely remove the bad image from the server using the instructions above.

== Tagging an image ==
Appending (or removing) a tag from an image can be done with the bin/tag-image script. This will result in a new image being generated.
{{{
$ bin/tag-image -vvv <channel> <device> <version> "<tag>"
}}}