1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
.. Documentaion on bootloader plugins
.. include:: global.rst.inc
==================
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 :py:class:`~weresync.plugins.IBootPlugin` and at least implement
the method :py:func:`~weresync.plugins.IBootPlugin.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 <https://github.com/DonyorM/weresync/blob/master/src/weresync/plugins/weresync_grub2.py>`_.
Method Implementations
++++++++++++++++++++++
All plugins should extend :py:func:`~weresync.plugins.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:
* :py:func:`~weresync.plugins.IBootPlugin.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.
* :py:func:`~weresync.plugins.IBootPlugin.install_bootloader` is called to
install the bootloader. This should do the majority of the work. Implementing
this method is required.
* :py:func:`~weresync.plugins.IBootPlugin.deactivate` is called after
bootloader installation is complete. Implementing this method is not
required.
:py:class:`~weresync.plugins.IBootPlugin` contains one more method,
:py:func:`~weresync.plugins.IBootPlugin.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 :py:func:`~weresync.plugins.IBootPlugin.install_bootloader`
provides access to a
:py:class:`~weresync.device.DeviceCopier` instance. This instance then provides
access to :py:class:`~weresync.device.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 :py:func:`~weresync.device.DeviceCopier.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 :py:func:`weresync.device.multireplace`
to update the UUIDs of any given string, for example one from a file.
The function :py:func:`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
:py:class:`~weresync.device.LVMDeviceManager` objects, but can generally be
treated like ordinary DeviceManager objects.
Builtin Bootloaders
-------------------
UUID Copy
+++++++++
.. automodule:: weresync.plugins.weresync_uuid_copy
Grub2
+++++
.. automodule:: weresync.plugins.weresync_grub2
Syslinux
++++++++
.. automodule:: weresync.plugins.weresync_syslinux
|
