diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/debugging.rst | 51 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 21 |
2 files changed, 55 insertions, 17 deletions
diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst index e03f3f81..e443feee 100644 --- a/docs/contributing/debugging.rst +++ b/docs/contributing/debugging.rst @@ -131,28 +131,49 @@ Useful commands are: Config Migration Scripts ------------------------ -When writing a new configuration migrator it may happen that you see an error -when you try to invoke it manually on a development system. This error will -look like: +Starting with VyOS 1.5 a new mechanism is used for config migration whichwill improve +migration performance. New migrators only exist in the new format with a migration() +function. + +.. code-block:: python + + from vyos.configtree import ConfigTree + base = ['vpn', 'ipsec'] + def migrate(config: ConfigTree) -> None: + if not config.exists(base): + # Nothing to do + return + # do your stuff here + +New style migrations scripts can no longer be executed on their own. The new +handler of the entire migration subsystem on the other hand comes with a handy +test kit: .. code-block:: none - vyos@vyos:~$ /opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1 /tmp/config.boot - Traceback (most recent call last): - File "/opt/vyatta/etc/config-migrate/migrate/ssh/0-to-1", line 31, in <module> - config = ConfigTree(config_file) - File "/usr/lib/python3/dist-packages/vyos/configtree.py", line 134, in __init__ - raise ValueError("Failed to parse config: {0}".format(msg)) - ValueError: Failed to parse config: Syntax error on line 240, character 1: Invalid syntax. + vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --help + usage: run-config-migration.py [-h] [--test-script TEST_SCRIPT] [--output-file OUTPUT_FILE] [--force] config_file + + positional arguments: + config_file configuration file to migrate -The reason is that the configuration migration backend is rewritten and uses -a new form of "magic string" which is applied on demand when real config -migration is run on boot. When running individual migrators for testing, -you need to convert the "magic string" on your own by: + options: + -h, --help show this help message and exit + --test-script TEST_SCRIPT + test named script + --output-file OUTPUT_FILE + write to named output file instead of config file + --force force run of all migration scripts + + +So in order to test your migrator you can run this as simple as: .. code-block:: none - vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --virtual --set-vintage vyos /tmp/config.boot + vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --test-script /opt/vyatta/etc/config-migrate/migrate/quagga/11-to-12 --output-file /tmp/foo /tmp/static-route-basic + vyos@vyos:~$ cat /tmp/foo + +Where `/tmp/foo` will contain the migrated configuration. Configuration Error on System Boot ---------------------------------- diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index e39af3a5..c5df8b12 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -290,7 +290,7 @@ device if you happen to be a crazy scientist. from vyos.config import Config from vyos import ConfigError - def get_config(): + def get_config(config=None): if config: conf = config else: @@ -306,7 +306,6 @@ device if you happen to be a crazy scientist. # Verify that configuration is valid if invalid: raise ConfigError("Descriptive message") - return True def generate(config): # Generate daemon configs @@ -385,6 +384,24 @@ For easy orientation we suggest you take a look on the ``ntp.py`` or ``interfaces-bonding.py`` (for tag nodes) implementation. Both files can be found in the vyos-1x_ repository. +Other considerations: vyos-configd +---------------------------------- + +All scripts now run under the config daemon and must conform to the +following: + +1. The signature and initial four lines of ``get_config(...)`` `must` be as + above. + +2. Each of ``get_config``, ``verify``, ``apply``, ``generate`` `must` + appear, with signatures as above, even if they are a no-op. + +3. Instantiations of ``Config`` other than that in ``get_config`` `must not` + appear. + +4. The legacy function ``my_set`` `must not` appear: modifications of the + active config `should not` appear in new code (if absolutely necessary, + alternative mechanisms may be used). XML (used for CLI definitions) ============================== |