2015-01-23 02:29:37 +00:00
|
|
|
Upgrade scripts
|
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
Basics
|
|
|
|
|
------
|
|
|
|
|
|
|
|
|
|
After each sysupgrade (including the initial installation), Gluon will execute all scripts
|
|
|
|
|
under ``/lib/gluon/upgrade``. These scripts' filenames usually begin with a 3-digit number
|
2017-06-08 18:59:57 +00:00
|
|
|
specifying the order of execution. Note that the script files need to be executable.
|
2015-01-23 02:29:37 +00:00
|
|
|
|
|
|
|
|
To get an overview of the ordering of all scripts of all packages, the helper script ``contrib/lsupgrade.sh``
|
|
|
|
|
in the Gluon repository can be used, which will print all upgrade scripts' filenames and directories. If executed
|
|
|
|
|
on a TTY, the filename will be highlighted in green, the repository in blue and the package in red.
|
|
|
|
|
|
|
|
|
|
Best practices
|
|
|
|
|
--------------
|
|
|
|
|
|
|
|
|
|
* Most upgrade scripts are written in Lua. This allows using lots of helper functions provided
|
2017-02-08 21:19:24 +00:00
|
|
|
by Gluon, e.g. to access the site configuration or edit UCI configuration files.
|
2015-01-23 02:29:37 +00:00
|
|
|
|
|
|
|
|
* Whenever possible, scripts shouldn't check if they are running for the first time, but just edit configuration
|
2017-06-08 18:59:57 +00:00
|
|
|
files to achieve a valid configuration (without overwriting configuration changes made by the user where desirable).
|
2015-01-23 02:29:37 +00:00
|
|
|
This allows using the same code to create the initial configuration and upgrade configurations on upgrades.
|
|
|
|
|
|
|
|
|
|
* If it is unavoidable to run different code during the initial installation, the ``sysconfig.gluon_version`` variable
|
2019-03-18 20:53:34 +00:00
|
|
|
can be checked. This variable is ``nil`` during the initial installation and contains the previously installed Gluon
|
2017-06-08 18:59:57 +00:00
|
|
|
version otherwise.
|
2015-01-23 02:29:37 +00:00
|
|
|
|
|
|
|
|
Script ordering
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
These are some guidelines for the script numbers:
|
|
|
|
|
|
|
|
|
|
* ``0xx``: Basic ``sysconfig`` setup
|
|
|
|
|
* ``1xx``: Basic system setup (including basic network configuration)
|
|
|
|
|
* ``2xx``: Wireless setup
|
|
|
|
|
* ``3xx``: Advanced network and system setup
|
|
|
|
|
* ``4xx``: Extended network and system setup (e.g. mesh VPN and next-node)
|
|
|
|
|
* ``5xx``: Miscellaneous (everything not fitting into any other category)
|
|
|
|
|
* ``6xx`` .. ``8xx``: Currently unused
|
|
|
|
|
* ``9xx``: Upgrade finalization
|
