Bootloader Plugins

Bootloader plugins allow WereSync to have special process to install specific bootloaders, allowing support for a wider variety of bootloaders.

The default bootloader plugin, UUID Copy, simply changes the UUIDs in each file in the /boot folder. UUIDs in /etc/fstab are always updated, regardless of boot plugin.

Installing

Bootloader plugins can be installed to two different locations: /usr/local/weresync/plugins and the python site-packages directory. This means that plugins can be installed as pip packages or installed manually.

Creating Bootloader Plugins

Bootloader plugins are very simple files. They must be a single python file that fits the form “weresync_<plugin name>.py”. Inside this file, a class must extend IBootPlugin and at least implement the method install_bootloader().

No other files are necessary, but other files may be packaged with a plugin for it to call within its process.

For an example plugin see the Grub2 Plugin.

Method Implementations

All plugins should extend IBootPlugin(), as mentioned above (signature: class MyPlugin(IBootPlugin)). They should all call super().__init__(name, prettyName) where name is the portion of the file name after the “weresync_” prefix but before the “.py” extension (weresync_<this part>.py). prettyName can be anything, but should be human readable. Currently this is only displayed by the GUI.

For any given bootloader plugin, the following methods are called in this order:

  • activate() is called before bootloader installation. All files will be exactly the same as the source drive at this point. Implementing this method is not required.

  • install_bootloader() is called to install the bootloader. This should do the majority of the work. Implementing this method is required.

  • deactivate() is called after bootloader installation is complete. Implementing this method is not required.

IBootPlugin contains one more method, get_help(), this is an optional method that should return a string describing what the plugin accomplishes (i.e. what bootloader it installs).

Helpful Functions

Several important methods are available to plugin developers. The copier parameter of install_bootloader() provides access to a DeviceCopier instance. This instance then provides access to DeviceManager instances through the copier.source and copier.target fields. These instances allow a plugin to mount and umnount partitions and get information about the drives in question.

The method get_uuid_dict() of the copier parameter returns a dictionary relating the UUIDs of the source drive with those of the target drive. This can be used in conjunction with weresync.device.multireplace() to update the UUIDs of any given string, for example one from a file.

The function weresync.plugins.translate_uuid() makes use of the above two functions to step recursively through the passed folder and update the UUIDs of every text file.

LVM

Your bootloader will be expected to support LVM systems as well. One can test if Logical Volume Groups are being copied by testing if the lvm_source field of the copier object is not None:

if copier.lvm_source is not None:
    # Handle copying VG

The lvm_source and lvm_target fields will be LVMDeviceManager objects, but can generally be treated like ordinary DeviceManager objects.

Builtin Bootloaders

UUID Copy

This modules contains the code to simply translate the UUIDs of all text files to the new drive. It does not change anything else.

In order to save RAM, uuid_copy will not copy files larger than 200 MB. This works for many bootloaders.

Grub2

Installs the Grub2 bootloader. This works on both UEFI and MBR systems.

Syslinux

Installs the syslinux bootloader. This bootloader plugin requires the “root partition” option to be defined.

Setups using syslinux’s altmbr setup are currently not supported.

This plugin assumes that the boot folder is in /boot/syslinux. If this is not the case a symbolic link should be created before WereSync is run.

This plugin depends on Extlinux being installed.

On UEFI systems this simply runs the UUID Copy plugin.