Image Configurations - KickStart Files

Latest revision as of 09:55, 8 July 2011

Kickstart (.ks) configuration files are passed to MIC2 to create tailored images. Kickstart files specify what repos to pull from, what packages to include, what post-scripts to run and what type of images to create.

For more details about the kickstart format, see http://fedoraproject.org/wiki/Anaconda/Kickstart.

Note that not all Kickstart directives and options are supported for creating MeeGo images. MIC2 also adds some specific directives and options. More explained below

Official MeeGo .ks files

The official MeeGo .ks files are here:

Formal release: http://repo.meego.com/MeeGo/releases/1.2.0/builddata/image-configs/

Weekly build: http://repo.meego.com/MeeGo/builds/trunk/latest/builddata/image-configs/

You can download and use them as a base for the MeeGo images you create. Modify these .ks files as you wish to create tailored images.

We suggest you to create .ks files by kickstarter tool with image-configurations pkg as a formal usage.

Modify your .ks

Developers may want to modify the .ks files to create their own custom images. Here are the main options and sections within the .ks file.

You can also find in-depth .ks option information here: http://fedoraproject.org/wiki/Anaconda/Kickstart#Chapter_2._Kickstart_Options

Change Partition, Setup and Bootloader options

These are mostly self-explanatory and set up important things such as partition size, filesystem type, kernel paramters, etc. You can change these depending on what your needs are. Example

lang en_US.UTF-8
keyboard us
timezone --utc America/New_York
auth --useshadow --enablemd5
part / --size 1500 --ondisk sda --fstype=ext3
rootpw meego
xconfig --startxonboot
bootloader --timeout=0 --append="quiet"
desktop --autologinuser=meego  --defaultdesktop=xfce
user --name meego  --groups audio,video --password meego

Specify Repos

This is where you can specify the yum repositories that you want MIC2 to search and pull your packages from which to make up your image. You can add official MeeGo repos, other remote repos, or your own local repos on your dev machine.

Example

# This is a comment

# My first repo
repo   --name=trunk  --baseurl=http://mytrunk.myrepo.com

# My second repo
#repo   --name=<repo-name-2>  --baseurl=< url | local-repo-dir >

NOTE: --name of the repo can be any unique alphanumeric name you give your repo, it can be anything. Just make sure you don't use the same name twice for any of the listed repos, remember they have to be unique.

To create a repo you can point to on your local developer machine, you can run the following command:

createrepo -d <local-dir>

Where 'local-dir' is a local directory on your machine that contains the rpms you want include in your local directory.

Add Packages Groups and Packages

• Groups

This specifies exactly what packages will be included in your image. Package groups can be specified with a "@" preceding it, as you can see from the example below:

%packages
# Example adding pkg groups
@Core
@X for Netbooks
@Base
@Development Tools
@<my-PkgGroup1>
@<my-PkgGroup2>

Package groups are defined in the 'patterns.xml' file, it defines the group names, and what packages are included in each package group, for example: http://repo.meego.com/MeeGo/releases/1.2.0/repos/oss/ia32/packages/repodata/patterns.xml

The MeeGo package groups are standard and common for MeeGo image creation. You can define your own package groups in your own non-meego repos in local, if you are using those.

Please see here for more info in repositories about MeeGo package groups defination: https://meego.gitorious.org/meego-os-base/package-groups/

• Packages

You can also add individual packages to the image, for example.

%packages
# Example adding individual pkgs
kernel-netbook
xorg-x11-server-Xorg-setuid
carrick
xorg-x11-drv-evtouch
<my-pkg-1>
<my-pkg-2>
%end

How MIC2 picks a package when different versions are available

A common question is that, a packageA may has more than one copy with different versions residing in a repo(s) that your .ks is pointing to. How will the MIC2 know which one to pick?

• select the package with highest version number by default

Example:

In the repo(s) these are different versions of PackageA:

PackageA-1.0
PackageA-2.0
PackageA-3.0

MIC2 will pick the PackageA with the highest version number (PackageA-3.0 in this case).

• select the package through "Epoch" version

There is one way to get around that, and that is to set the 'Epoch' version within a package .spec file, such as:

Name: <name>
Summary: <summary>
Epoch: 1
Version: <version>

MIC2 will first look to compare the 'Epoch' version of the packages. All MeeGo official packages do not include an 'Epoch' version, so if you set the 'Epoch' number within your .spec file to any positive integer, no matter if your package version is smaller, MIC2 will choose your package.

Example:

PackageA-1.0 (Epoch not set)
PackageA-2.0 (Epoch = 1)
PackageA-3.0 (Epoch not set)

MIC2 will choose PackageA-2.0 in this case. And it follow that:

Example:

PackageA-1.0 (Epoch=100)
PackageA-2.0 (Epoch = 1)
PackageA-3.0 (Epoch not set)

MIC2 will choose PackageA-1.0.

Remember that MeeGo packages will not have 'Epoch' set, so if you set 'Epoch' in your own package to any positive integer, it will be the one MIC2 chooses to pull down and include in an image.

Remove Packages

If you would like to make sure that a pkg should NOT be included, you can specify that with a '-' preceding the package name.

Example: packages 'carrick' and 'package-xyz' will _not_ be included in the image

%packages
# Example pkg groups
@Core

# Example adding individual pkgs
kernel-netbook

# Example removing individual pkgs
-carrick
-package-xyz
%end

Note: all packages that depend on the package you want to remove should be removed also, otherwise MIC2 will ignore your request and keep that package in the image. For example, if 'carrick' depends on 'package-xyz', and you specified only to remove 'package-xyz', and keep carrick, MIC2 will ignore the request to remove package-xyz (since carrick depends on it), and it will include both of these pgks in the image.

Post scripts

You can also specify post-scripts to be run after the image is created.

Example:

%post
# Example - saving some space
rm -f /boot/initrd*
rm -f /core*

# Example - Install working xorg.conf
if [ -f /usr/share/my.conf ]; then
    cp /usr/share/my.conf /etc/X11/xorg.conf
fi

# Example - Tell alsa the correct audio card to use for your platform
echo -e "options snd-hda-intel index=0\noptions snd-timbi2s index=1" > /etc/modp
robe.d/alsa.conf
%end

Generate .ks file from Kickstarter

You can also create .ks files by kickstarter from image-configurations.

Kickstarter

Kickstarter is a tool for create kickstart files to build meego images.

You can download it here: http://repo.meego.com/MeeGo/tools/repos/meego/trunk/noarch/

This tool is also maintained by MeeGo OBS, in Trunk project: http://build.meego.com/package/show?package=kickstarter&project=Trunk

Example:

 kickstarter  --configs configurations.yaml --repos repos.yaml 

Configuration file: The "configuration.yaml" file here is an example only, for meego kickstart files, please get from the image-configurations package.

This file has the definition of configurations. The Configurations inherit from platforms first then from the DEFAULT section. The image configurations override the all other settings (in DEFAULT and platform sections).

Repo file: This file contains a list of repositories to be used in the kickstart files.

image-configurations

Image-configurations is a package used to manage the configurations of images under different platforms, it provides yaml type configs.

You can get image-configurations noarch package here: http://download.meego.com/live/Trunk/standard/noarch/

The package of image-configurations also maintained by MeeGo OBS, in Trunk project: http://build.meego.com/package/show?package=image-configurations&project=Trunk

The organization of image-configurations:

 configuration.yaml -- default and platform generic configs, also point to external platform path, it's the entrance for kickstart.
 repos.yaml         -- a list of repositories to be used in the kickstart files
 core               -- path for image-configs under 'core' platform 
 compliance         -- path for image-configs under 'compliance' platform 
 ivi                -- path for image-configs under 'ivi' platform 
 handset            -- path for image-configs under 'handset' platform 
 netbook            -- path for image-configs under 'netbook' platform 
 tablet             -- path for image-configs under 'tablet' platform 
 custom/part        -- store partition definition
 custom/scripts     -- store postscripts definition

The followings are how does image-configurations manage those parts in .ks files.

This configurations.yaml file has a generic definition of configurations. The Configurations inherit from platforms first then from the DEFAULT section. The image configurations override all other settings (in DEFAULT and platform sections).

Basically all common options should go to the DEFAULT section. If an options is related to a specific platform, then that option should be added to the platform section. Try to keep platforms clean and very generic, if needed, create a new platform section and use it when many options for a new platform are common.

Detail for the keywords

"Name": description of the configuration file

 Name: MeeGo Netbook/Nettop  

"Schedule": When should this image be generated:

 # *: always
 # 0: Monday
 # 1: Tuesday
 # ...
 # If no schedule keyword is present, then image will not be created

 Schedule: "*"

"Active": if this image is active

 Active: True

"Platform": Inherit from platform

 Platform: NETBOOK

"Part": Partition specific configs

 Part: qemu
 
 # Part are stored in custom/part and referenced by part name

"Kernel": Based kernel

 Kernel: kernel-adaptation-mrst

"Architecture": Based architecture

 Architecture: ia32

"Mic2Options": MIC2 options to be used when creating this image

 Mic2Options: "-f livecd"

"Desktop": Desktop type

 Desktop: None 

"Timezone"

 Timezone: America/New_York

"FileName": The name of the configuration file

 FileName: netbook-ia32

"Groups": package groups

 Groups:
    - MeeGo Netbook Desktop
    - MeeGo Core
    - Printing
    - Games

"ExtraPackages": Additional packages that are not part of any group

 ExtraPackages:
    - chromium
    - adobe-release
    - flash-plugin

"Repos": Repos to use in addition to default repos, those are define in the repos.yaml file

 Repos:
    - adobe

"PostScripts": Post-scripts to be run after the image is installed

 PostScripts:
    - meegotouch-n900
    - bootchart
    - fstab-n900
    - arch-armv7hl
 
 # post-scripts are stored in custom/scripts and referenced by post-scripts name