YaST/Bootloader API

From openSUSE

Interface between yast2-bootloader and perl-Bootloader

There exist file Bootloader_API.pm which is API between yast2-bootloader and perl-Bootloader:

yast2-bootloader includes lib_iface.ycp for calling function from Bootloader_API.pm

Files:

• /trunk/bootloader/src/modules/Bootloader_API.pm
• /trunk/bootloader/src/routines/lib_iface.ycp

FIXME:

• delete duplicated examples - use only links
• better description of maps from examples - new design... it is really bad now
• add missing information...

Bootloader_API.pm

Version: 11.1

Link to API documentation for Opensuse 11.1.

sub setLoaderType($)

• the function is calling during initialization of yast2-bootloader and set bootloader type to internal cache of the library
• argument is string and it is type of bootloader for example “grub”, “lilo”...
• return undef if fail (but now never fail )

sub updateBootloader()

• update the bootloader settings
• argument is boolean ( specify if activate saved settings( does nothing for grub ) )
• return true on success

sub initializeBootloader()

• initialize the boot loader (eg. modify firmware, depending on architecture)

first time initialization of firmware/bios specific code

• without arguments
• return true on success

sub readSettings()

• read the files from the system to internal cache of the library
• argument is boolean and if it is true do not read device.map but use internal data
• return true on success

sub writeSettings()

• flush the internal cache of the library to the disk
• without arguments
• return true on success

sub getMetaData()

• get data format and type description as far as available for specific bootloader
• without arguments
• return a map of meta data for global and section entries e.g.:

$[
    "%global_options%activate":"bool:Set active Flag in Partition Table for Boot Partition:true",
    "%global_options%boot":"multi:Boot Loader Locations:",
    "%global_options%boot_boot":"bool:Boot from Boot Partition:true",
    "%global_options%boot_custom":"selectdevice:Custom Boot Partition::/dev/sda1:/dev/sda2:/dev/sdb1:/dev/sdb2:/dev/sdb3:/dev/sdb4:/dev/sdc1:/dev/sdc2:/dev/sdc3",
    "%global_options%boot_extended":"bool:Boot from Extended Partition:true",
    "%global_options%boot_mbr":"bool:Boot from Master Boot Record:false",
    "%global_options%boot_root":"bool:Boot from Root Partition:true",
    "%global_options%debug":"bool:Debugging flag:false",
    "%global_options%default":"string:Default Boot Section:Linux",
    "%global_options%fallback":"string:Fallback sections if default fails:1",
    "%global_options%former_default_image_flavor":"string:Former default Image Flavor:default",
    "%global_options%generic_mbr":"bool:Write generic Boot Code to MBR:true",
    "%global_options%gfxmenu":"path:Graphical menu file:/boot/message",
    "%global_options%hiddenmenu":"bool:Hide menu on boot:false",
    "%global_options%password":"password:Password for the Menu Interface:",
    "%global_options%serial":"string:Serial connection parameters:",
    "%global_options%terminal":"string:Terminal definition:",
    "%global_options%timeout":"int:Timeout in Seconds:8:0:3600",
    "%section_options%image_append":"string:Optional kernel command line parameter",
    "%section_options%image_image":"path:Kernel image:/boot/vmlinux",
    "%section_options%image_initrd":"path:Initial RAM disk:/boot/initrd",
    "%section_options%image_noverifyroot":"bool:Do not verify filesystem before booting:false",
    "%section_options%image_root":"selectdevice:Root device::/dev/sda2:/dev/sdb2:/dev/sdb3:/dev/sdc1:/dev/sdc2",
    "%section_options%image_vgamode":"string:Vga Mode",
    "%section_options%menu_configfile":"path:Menu description file:/boot/grub/menu.lst",
    "%section_options%menu_root":"select:Partition of menu file:::/dev/sda1:/dev/sda2:/dev/sdb1:/dev/sdb2:/dev/sdb3:/dev/sdb4:/dev/sdc1:/dev/sdc2:/dev/sdc3",
    "%section_options%other_blockoffset":"int:Block offset for chainloading:1:0:32",
    "%section_options%other_chainloader":"selectdevice:Other system::/dev/sda1:/dev/sda2:/dev/sdb1:/dev/sdb2:/dev/sdb3:/dev/sdb4:/dev/sdc1:/dev/sdc2:/dev/sdc3",
    "%section_options%other_lock":"bool:Use password protection:false",
    "%section_options%other_makeactive":"bool:Activate this partition when selected for boot:false",
    "%section_options%other_noverifyroot":"bool:Do not verify filesystem before booting:false",
    "%section_options%type_image":"bool:Image section",
    "%section_options%type_menu":"bool:Menu section",
    "%section_options%type_other":"bool:Chainloader section",
    "%section_options%type_xen":"bool:Xen section",
    "%section_options%xen_append":"string:Optional kernel command line parameter",
    "%section_options%xen_image":"path:Kernel image:/boot/vmlinux",
    "%section_options%xen_initrd":"path:Initial RAM disk:/boot/initrd",
    "%section_options%xen_root":"select:Root device::/dev/sda2:/dev/sdb2:/dev/sdb3:/dev/sdc1:/dev/sdc2",
    "%section_options%xen_vgamode":"string:Vga Mode",
    "%section_options%xen_xen":"select:Hypervisor:/boot/xen.gz:/boot/xen.gz:/boot/xen-pae.gz",
    "%section_options%xen_xen_append":"string:Additional Xen Hypervisor Parameters:",
    "arch":"x86"
]

sub getDeviceMapping()

• get the device mapping (/boot/grub/device.map)
• yast2-bootloader is responsible for creating device map (mapping devices to hdX/fdX)
• hd0, hd1, hd2... is the order of disks by BIOS, it means (in this case) that /dev/sdb2 is the first disk in order, the second is /dev/sdc and finally /dev/sda
• without arguments
• return a map from Linux device to Firmware device identification e.g.

$[
    "/dev/fd0":"fd0",
    "/dev/sda":"hd2",
    "/dev/sdb":"hd0",
    "/dev/sdc":"hd1"
]

sub setDeviceMapping($)

• set the device mapping
• argument is a map from Linux device to Firmware device identification

$[
    "/dev/fd0":"fd0",
    "/dev/sda":"hd2",
    "/dev/sdb":"hd0",
    "/dev/sdc":"hd1"
]

• return true on success

sub getGlobalSettings()

• get global bootloader options
• without arguments
• return a map of global bootloader options e.g.

$[
    "boot_mbr":"true",
    "default":"openSUSE 11.0 - 2.6.25.5-1.1",
    "gfxmenu":"/boot/message",
    "lines_cache_id":"5",
    "timeout":"8"
]

global options in map

    "generic_mbr":"true", → write generic code to MBR
    "activate":"false", → set activating flag to MBR for partition
    "boot_boot":"false", → boot from boot partition
    "boot_extended":"false", → boot from extended partition
    "boot_mbr":"true", → write GRUB/LILO to MBR
    "boot_root":"false" → boot from root partition
    "console":"string" → definition of console
    "default":"openSUSE 11.0 – 2.6.25.5-1.1", → name of default boot section
    "gfxmenu":"/boot/message", → grafical screen for bootloader (can be prefixed by disk specification (e.g. (hd0,1))
    "lines_cache_id":"5", → last index of section +1 - it is added by Bootloader_API.pm and it means the order number
    "setkeys":reference to hash, → hash with key remapping (only in grub)
    "timeout":"8" → timeout for starting boot from default boot section (waiting time)
    "terminal":"string" → definition of terminal
    "trusted_grub":"true" → user select use trusted grub

    specials for PPC (???only one or more keys in global???)
    "boot_file":"/test" → boot from file
    "boot_~arch~_custom":"/dev/sda2" → architecture dependent boot (replace ~arch~ with architecture like iseries, chrp, pmac)
    "boot_slot":"A" → boot from slot [A-D]

sub setGlobalSettings($)

• set global bootloader options
• argument is a map of global bootloader options e.g.

$[
    "boot_mbr":"true",
    "default":"openSUSE 11.0 - 2.6.25.5-1.1",
    "gfxmenu":"/boot/message",
    "lines_cache_id":"5",
    "timeout":"8"
]

• return true on success

sub getSections()

• get boot loader sections
• without arguments
• return a list of all loader sections (as maps) e.g.

[
    $[
       "append":"resume=/dev/sda3 splash=silent showopts nmi_watchdog=0",
       "image":"/var/Data/boot/vmlinuz-2.6.22.9-0.4-default",
       "initial":"1",
       "initrd":"/var/Data/boot/initrd-2.6.22.9-0.4-default",
       "lines_cache_id":"5",
       "name":"openSUSE 10.3 - 2.6.22.9-0.4",
       "original_name":"linux",
       "root":"/dev/disk/by-id/scsi-SATA_SAMSUNG_SP0802NS00JJ70XC85113-part2",
       "type":"image",
       "vgamode":"0x31a"
    ],
    $[
       "append":"showopts ide=nodma apm=off acpi=off noresume nosmp noapic maxcpus=0 edd=off 3",
       "image":"/var/Data/boot/vmlinuz-2.6.22.9-0.4-default",
       "initrd":"/var/Data/boot/initrd-2.6.22.9-0.4-default",
       "lines_cache_id":"6",
       "name":"Failsafe -- openSUSE 10.3 - 2.6.22.9-0.4",
       "original_name":"failsafe",
       "root":"/dev/disk/by-id/scsi-SATA_SAMSUNG_SP0802NS00JJ70XC85113-part2",
       "type":"image",
       "vgamode":"normal"
    ],
    $[
       "blockoffset":"1",
       "chainloader":"/dev/sda1",
       "lines_cache_id":"8",
       "name":"Windows",
       "noverifyroot":"true",
       "original_name":"windows",
       "type":"other"
    ],
    $[
       "blockoffset":"1",
       "chainloader":"/dev/fd0",
       "lines_cache_id":"9",
       "name":"Diskette",
       "noverifyroot":"true",
       "original_name":"floppy",
       "type":"other"
    ]
]

options in map for section

• universal keys:

$[
       "__modified":"1" → specify if something in section is changed (if nothing then use __lines)
       "__lines":array of structure(comment_before, comment_after, key, value) → lines readed from configuration file for this section.
                 If nothing modified, then write as is. If something change edit some keys in place, but some keys must be recreated.
]

• image section:

$[
       "append":"resume=/dev/sda3 splash=silent showopts nmi_watchdog=0", → kernel args
       "console":"ttyS0,9800", → communicate via serial console
       "image":"/var/Data/boot/vmlinuz-2.6.22.9-0.4-default", → image of kernel (sometimes key can be kernel instead of image – it is bug)
       "imagepcr":"8", → pcr for image (only trusted grub)
       "initial":"1", → it means that section is default
       "initrd":"/var/Data/boot/initrd-2.6.22.9-0.4-default", → initrd
       "initrdpcr":"8", → pcr for initrd (only trusted grub)
       "lines_cache_id":"5",  → index of section - it is added by Bootloader_API.pm and it means the order number
       "measure":["/etc/security/selinux/policy.17 9"], → reference to array of measure lines (only trusted grub)
       "name":"openSUSE 10.3 – 2.6.22.9-0.4", → name or title of section
       "original_name":"linux", → type of section read from YaST commnet in config file
       "root":"/dev/disk/by-id/scsi-SATA_SAMSUNG_SP0802NS00JJ70XC85113-part2", → root device in kernel args
       "type":"image", → type section
       "vgamode":"0x31a" → vga mode in kernel args
]

• chainloader section:

$[
       "blockoffset":"1", → offset in chainloader (used only in grub)
       "chainloader":"/dev/sda1", → partition part for chainloader (so chainloader+blockoffset get final chainloader item in grub)
       "chainloaderpcr":"8", → pcr for chainloader (only trusted grub)
       "lines_cache_id":"3", → index of section - it is added by Bootloader_API.pm and it means the order number
       "measure":["/etc/security/selinux/policy.17 9"], → reference to array of measure lines (only trusted grub)
       "name":"Windows", → name or title of section
       "noverifyroot":"true", → without checking
       "original_name":"windows", → name parsed from YaST comment in config file
       "type":"other" → type of section
       "remap":"true" -> it is special for windows and it means remapping disk make the second disk the first e.g. map (hd0) (hd1) map (hd1) (hd0)
       "makeactive":"true" -> add makeactive argument for chainloader section
]

• xen section

$[
       "append":"resume=/dev/sda1 splash=silent showopts", → kernel args
       "console":"ttyS0,9800", → communicate via serial console (create append both to kernel and xen)
       "image":"/boot/vmlinuz-2.6.25.4-8-xen", → xen kernel image
       "imagepcr":"8", → pcr for image (only trusted grub)
       "initrd":"/boot/initrd-2.6.25.4-8-xen", → xen initrd
       "initrdpcr":"8", → pcr for initrd (only trusted grub)
       "lines_cache_id":"0", → index of section - it is added by Bootloader_API.pm and it means the order number
       "name":"Xen -- openSUSE 11.0 – 2.6.25.4-8", → name or title of boot section
       "nounzip":"2" → bit code of what module shouldn't be unziped...first byte is image and second is initrd, so 1 is don't unzip image. 2 don't unzip initrd and 3 for both.
       "original_name":"xen", → type of section read from YaST comment in config file
       "root":"/dev/sda2", → root device for kernel args
       "type":"xen", → type of section
       "vgamode":"0x31a" → vga mode in kernel args
       "xen":"/boot/xen.gz", → module
       "xen_append":"" → args for xen module
       "xenpcr":"9", → pcr for xen module (only trusted grub)
]

• menu section (only in ZIPL)

$[
       "default":"1", → default entry in menu
       "list":"ipl, Failsafe", → comma separated list of menu entries
       "prompt":"" → Show boot menu (boolean)
       "target":"/boot/zipl", → Target directory for menu section
       "timeout":"10", → timeout in seconds
       "type":"menu", → type of section
]

• dump section (only in ZIPL)

$[
       "dumpto":"/dev/dasd/0.0.0200/disc1" , → Dump device
       "dumptofs":"/dev/zfcp" , → SCSI Dump device
       "target":"/boot/zipl", → Target directory for menu section
       "type":"dump", → type of section
]

• configfile section

FIXME: add example with comments

sub setSections($)

• set boot loader sections
• argument is a list of all loader sections (as maps) e.g.

[
    $[
       "append":"resume=/dev/sda1 splash=silent showopts",
       "image":"/boot/vmlinuz",
       "initrd":"/boot/initrd",
       "name":"openSUSE 11.0",
       "original_name":"linux",
       "root":"/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2",
       "type":"image"
    ],
    $[
       "append":"resume=/dev/sda1 splash=silent showopts",
       "image":"/boot/vmlinuz-xen",
       "initrd":"/boot/initrd-xen",
       "name":"XEN",
       "original_name":"xen",
       "root":"/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2",
       "type":"xen",
       "xen":"/boot/xen.gz",
       "xen_append":""
    ],
    $[
       "append":"showopts ide=nodma apm=off acpi=off noresume edd=off x11failsafe",
       "image":"/boot/vmlinuz",
       "initrd":"/boot/initrd",
       "name":"Failsafe -- openSUSE 11.0",
       "original_name":"failsafe",
       "root":"/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2",
       "type":"image"
    ]
]

• return true on success

sub getFilesContents()

• get contents of files from the library cache
• without arguments
• return a map filename -> contents, empty map in case of fail e.g.

$[
    "/boot/grub/device.map":"(hd0)\t    /dev/sda",
    "/boot/grub/menu.lst":"
        # Modified by YaST2. Last modification on Tue Jun  3 10:03:54 MDT 2008\n
        default 0\n
        timeout 8\n
        gfxmenu (hd0,1)/boot/message\n
        ##YaST - activate\n\n
        
        ###Don't change this comment - YaST2 identifier: Original name: linux###\n
        title openSUSE 11.0\n    
            root (hd0,1)\n
            kernel /boot/vmlinuz root=/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2 resume=/dev/sda1 splash=silent showopts\n    
            initrd /boot/initrd\n\n

        ###Don't change this comment - YaST2 identifier: Original name: xen###\n
        title XEN\n    
            root (hd0,1)\n    
            kernel /boot/xen.gz \n    
            module /boot/vmlinuz-xen root=/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2 resume=/dev/sda1 splash=silent showopts\n    
            module /boot/initrd-xen\n\n

        ###Don't change this comment - YaST2 identifier: Original name: failsafe###\n
        title Failsafe -- openSUSE 11.0\n    
            root (hd0,1)\n    
            kernel /boot/vmlinuz root=/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2 showopts ide=nodma apm=off acpi=off noresume edd=off x11failsafe\n    
            initrd /boot/initrd",
    "/etc/grub.conf":"setup --stage2=/boot/grub/stage2 (hd0,1) (hd0,1)\n
                      quit"
]

sub setFilesContents($)

• set the contents of all files to library cache
• argument is a map filename -> contents e.g.

$[
    "/boot/grub/device.map":"(hd0)\t    /dev/sda",
    "/boot/grub/menu.lst":"
        # Modified by YaST2. Last modification on Tue Jun  3 10:03:54 MDT 2008\n
        default 0\n
        timeout 8\n
        gfxmenu (hd0,1)/boot/message\n
        ##YaST - activate\n\n
        
        ###Don't change this comment - YaST2 identifier: Original name: linux###\n
        title openSUSE 11.0\n    
            root (hd0,1)\n
            kernel /boot/vmlinuz root=/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2 resume=/dev/sda1 splash=silent showopts\n    
            initrd /boot/initrd\n\n

        ###Don't change this comment - YaST2 identifier: Original name: xen###\n
        title XEN\n    
            root (hd0,1)\n    
            kernel /boot/xen.gz \n    
            module /boot/vmlinuz-xen root=/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2 resume=/dev/sda1 splash=silent showopts\n    
            module /boot/initrd-xen\n\n

        ###Don't change this comment - YaST2 identifier: Original name: failsafe###\n
        title Failsafe -- openSUSE 11.0\n    
            root (hd0,1)\n    
            kernel /boot/vmlinuz root=/dev/disk/by-id/scsi-SATA_HDT722516DLA380_VDK71BTCDSL81K-part2 showopts ide=nodma apm=off acpi=off noresume edd=off x11failsafe\n    
            initrd /boot/initrd",
    "/etc/grub.conf":"setup --stage2=/boot/grub/stage2 (hd0,1) (hd0,1)\n
                      quit"
]

• return true on success

sub setMountPoints($)

• retrieve the mount points for perl-Bootloader library from yast2-storage module
• argument is a map of mount points e.g.

$[
    "/":"/dev/sda2",
    "/home":"/dev/sda3"
]

• return true on success (but yast2-bootloader doesn't check return value)

sub setPartitions($)

• retrieve the partitions for perl-Bootloader library from yast2-storage module
• argument is a list of partitions e.g.

[
    [
      "/dev/sda1",
      "/dev/sda",
      "1",
      "130",
      "Linux swap",
      "`primary",
      "0",
      "262"
    ],
    [
      "/dev/sda2",
      "/dev/sda",
      "2",
      "131",
      "Linux native",
      "`primary",
      "262",
      "2611"
    ],
    [
      "/dev/sda3",
      "/dev/sda",
      "3",
      "131",
      "Linux native",
      "`primary",
      "2873",
      "17150"
    ]
]

• return true on success (but yast2-bootloader doesn't check return value)

sub setMDArrays($)

• In perlBootloader it is DefineMDArrays
• retrieve info about MD-RAID for perl-Bootloader library from yast2-storage module
• argument is a map of MD_RAID e.g.

[
    "/dev/md0":[
                 "/dev/sdb1",
                 "/dev/sdc1"
    ],
    "/dev/md1":[
                 "/dev/sdb2",
                 "/dev/sdc2"
    ],
    "/dev/md2":[
                 "/dev/sdb3",
                 "/dev/sdc3"
    ]
]

• return true on success (but yast2-bootloader doesn't check return value)

sub DetectThinkpadMBR($)

• tries detect thinkpadMBR
• retrive true or false, true if finded thinkpad
• argument is disk location as string e.g. "/dev/sda"

sub WriteThinkpadMBR($)

• writes generic MBR code to thinkpad MBR (need special handling due to special MBR)
• retrive undef if fail
• argument is disk location as string e.g. "/dev/sda"

sub CountGRUBPassword($)

• counts password-recognizer for grub password command
• retrive hash or undef if fail
• argument is password e.g. "password"
• NOTE - every call return another recognizer( more here