upgrade.rst 2.1 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243
  1. Upgrade scripts
  2. ===============
  3. Basics
  4. ------
  5. After each sysupgrade (including the initial installation), Gluon will execute all scripts
  6. under ``/lib/gluon/upgrade``. These scripts' filenames usually begin with a 3-digit number
  7. specifying the order of execution.
  8. To get an overview of the ordering of all scripts of all packages, the helper script ``contrib/lsupgrade.sh``
  9. in the Gluon repository can be used, which will print all upgrade scripts' filenames and directories. If executed
  10. on a TTY, the filename will be highlighted in green, the repository in blue and the package in red.
  11. Best practices
  12. --------------
  13. * Most upgrade scripts are written in Lua. This allows using lots of helper functions provided
  14. by Gluon, e.g. to access the site configuration or edit UCI configuration files.
  15. * Whenever possible, scripts shouldn't check if they are running for the first time, but just edit configuration
  16. files to achive a valid configuration (without overwriting configuration changes made by the user where desirable).
  17. This allows using the same code to create the initial configuration and upgrade configurations on upgrades.
  18. * If it is unavoidable to run different code during the initial installation, the ``sysconfig.gluon_version`` variable
  19. can be checked. This variable is ``nil`` during the initial installation and contains the previously install Gluon
  20. version otherwise. The package ``gluon-legacy`` (which is responsible for upgrades from the old firmwares of
  21. Hamburg/Kiel/Lübeck) uses the special value ``legacy``; other packages should handle this value just as any other
  22. string.
  23. Script ordering
  24. ---------------
  25. These are some guidelines for the script numbers:
  26. * ``0xx``: Basic ``sysconfig`` setup
  27. * ``1xx``: Basic system setup (including basic network configuration)
  28. * ``2xx``: Wireless setup
  29. * ``3xx``: Advanced network and system setup
  30. * ``4xx``: Extended network and system setup (e.g. mesh VPN and next-node)
  31. * ``5xx``: Miscellaneous (everything not fitting into any other category)
  32. * ``6xx`` .. ``8xx``: Currently unused
  33. * ``9xx``: Upgrade finalization