diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/debugging.rst | 151 | ||||
| -rw-r--r-- | docs/contributing/documentation.rst | 331 | ||||
| -rw-r--r-- | docs/contributing/index.rst | 2 |
3 files changed, 0 insertions, 484 deletions
diff --git a/docs/contributing/debugging.rst b/docs/contributing/debugging.rst deleted file mode 100644 index a4c73d15..00000000 --- a/docs/contributing/debugging.rst +++ /dev/null @@ -1,151 +0,0 @@ -.. _debugging: - -######### -Debugging -######### - -There are two flags available to aid in debugging configuration scripts. -Since configuration loading issues will manifest during boot, the flags are -passed as kernel boot parameters. - -System Startup -============== - -The system startup can be debugged (like loading in the configuration -file from ``/config/config.boot``. This can be achieve by extending the -Kernel command-line in the bootloader. - -Kernel ------- - -* ``vyos-debug`` - Adding the parameter to the linux boot line will produce - timing results for the execution of scripts during commit. If one is seeing - an unexpected delay during manual or boot commit, this may be useful in - identifying bottlenecks. The internal flag is ``VYOS_DEBUG``, and is found - in vyatta-cfg_. Output is directed to ``/var/log/vyatta/cfg-stdout.log``. - -* ``vyos-config-debug`` - During development, coding errors can lead to a - commit failure on boot, possibly resulting in a failed initialization of the - CLI. In this circumstance, the kernel boot parameter ``vyos-config-debug`` - will ensure access to the system as user ``vyos``, and will log a Python - stack trace to the file ``/tmp/boot-config-trace``. - File ``boot-config-trace`` will generate only if config loaded with a failure status. - -Live System -=========== - -A number of flags can be set up to change the behaviour of VyOS at runtime. -These flags can be toggled using either environment variables or creating -files. - -For each feature, a file called ``vyos.feature.debug`` can be created to -toggle the feature on. If a parameter is required it can be placed inside -the file as its first line. - -The file can be placed in ``/tmp`` for one time debugging (as the file -will be removed on reboot) or placed in '/config' to stay permanently. - -For example, ``/tmp/vyos.ifconfig.debug`` can be created to enable -interface debugging. - -It is also possible to set up the debugging using environment variables. -In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG. - -For example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vbash, -will have the same effect as ``touch /tmp/vyos.ifconfig.debug``. - -* ``ifconfig`` - Once set, all commands used, and their responses received - from the OS, will be presented on the screen for inspection. - -* ``command`` - Once set, all commands used, and their responses received - from the OS, will be presented on the screen for inspection. - -* ``developer`` - Should a command fail, instead of printing a message to the - user explaining how to report issues, the python interpreter will start a - PBD post-mortem session to allow the developer to debug the issue. As the - debugger will wait from input from the developer, it has the capacity to - prevent a router to boot and therefore should only be permanently set up - on production if you are ready to see the OS fail to boot. - -* ``log`` - In some rare cases, it may be useful to see what the OS is doing, - including during boot. This option sends all commands used by VyOS to a - file. The default file is ``/tmp/full-log`` but it can be changed. - -.. note:: In order to retrieve the debug output on the command-line you need to - disable ``vyos-configd`` in addition. This can be run either one-time by calling - ``sudo systemctl stop vyos-configd`` or make this reboot-safe by calling - ``sudo systemctl disable vyos-configd``. - -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: - -.. 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. - -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 runnint individual migrators for testing, -you need to convert the "magic string" on your own by: - -.. code-block:: none - - vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --virtual --set-vintage vyos /tmp/config.boot - -Configuration Error on System Boot ----------------------------------- - -Beeing brave and running the latest rolling releases will sometimes trigger -bugs due to corner cases we missed in our design. Those bugs should be filed -via Phabricator_ but you can help us to narrow doen the issue. Login to your -VyOS system and change into configuration mode by typing ``configure``. Now -re-load your boot configuration by simply typing ``load`` followed by return. - -You shoudl now see a Python backtrace which will help us to handle the issue, -please attach it to the Phabricator_ task. - -Boot Timing ------------ - -During the migration and extensive rewrite of functionality from Perl into -Python a significant increase in the overall system boottime was noticed. The -system boot time can be analysed and a graph can be generated in the end which -shows in detail who called whom during the system startup phase. - -This is done by utilizing the ``systemd-bootchart`` package which is now -installed by default on the VyOS 1.3 (equuleus) branch. The configuration is -also versioned so we get comparable results. ``systemd-bootchart`` is configured -using this file: bootchart.conf_ - -To enable boot time graphing change the Kernel commandline and add the folowing -string: ``init=/usr/lib/systemd/systemd-bootchart`` - -This can also be done permanently by changing ``/boot/grub/grub.cfg``. - -Priorities -========== - -VyOS CLI is all about priorities. Every CLI node has a corresponding ``node.def`` -file and possibly an attached script that is executed when the node is present. -Nodes can have a priority, and on system bootup - or any other ``commit`` to the -config all scripts are executed from lowest to higest priority. This is good as -this gives a deterministic behavior. - -To debug issues in priorities or to see what's going on in the background you can -use the ``/opt/vyatta/sbin/priority.pl`` script which lists to you the execution -order of the scripts. - -.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg -.. _bootchart.conf: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf - -.. include:: /_include/common-references.txt diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst deleted file mode 100644 index f1dc8095..00000000 --- a/docs/contributing/documentation.rst +++ /dev/null @@ -1,331 +0,0 @@ -.. _documentation: - -############# -Documentation -############# - -As most software projects we also have a lack in documentation. We encourage -every VyOS user to help us improve our documentation. This will not only be -beneficial for you (when reading something up) but also for the whole world. - -If you are willing to contribute to our documentation this is the definite -guide how to do so. - -.. note:: In contrast to submitting code patches, there is no requirement that - you open up a Phabricator_ task prior to submitting a Pull-Request to the - documentation. - -Forking Workflow -================ - -The Forking Workflow is fundamentally different than other popular Git -workflows. Instead of using a single server-side repository to act as the -"central" codebase, it gives every developer their own server-side repository. -This means that each contributor has not one, but two Git repositories: a -private local one and a public server-side one. - -The main advantage of the Forking Workflow is that contributions can be -integrated without the need for everybody to push to a single central -repository. Developers push to their own server-side repositories, and only the -project maintainer can push to the official repository. This allows the -maintainer to accept commits from any developer without giving them write -access to the official codebase. - -.. note:: Updates to our documentation should be delivered by a GitHub - pull-request. This requires you already have a GitHub account. - -* Fork this project on GitHub https://github.com/vyos/vyos-documentation/fork - -* Clone fork to local machine, then change to that directory``$ cd vyos-documentation`` - -* Install the requirements ``$ pip install -r requirements.txt`` (or something similar) - -* Create new branch for your work, use a descriptive name of your work: - ``$ git checkout -b <branch-name>`` - -* Make all your changes - please keep our commit rules in mind - (:ref:`prepare_commit`). This mainly applies to proper commit messages - describing your change (how and why). Please check out the documentation of - Sphinx-doc_ or reStructuredText_ if you are not familiar with it. This is used - for writing our docs. Additional directives how to write in RST can be obtained - from reStructuredTextDirectives_. - -* Check your changes by locally building the documentation ``$ make html``. - Sphinx will build the html files in the ``docs/_build`` folder. We provide - you with a Docker container for an easy to use user experience. Check the - README.md_ file of this repository. - -* View modified files by calling ``$ git status``. You will get an overview of - all files modified by you. You can add individual files to the Git Index in - the next step. - -* Add modified files to Git index ``$ git add path/to/filename`` or add all - unstaged files ``$ git add .``. All files added to the Git index will be part - of you following Git commit. - -* Commit your changes with the message, ``$ git commit -m "<commit message>"`` - or use ``$ git commit -v`` to have your configured editor launched. You can - type in a commit message. Again please make yourself comfortable with out - rules (:ref:`prepare_commit`). - -* Push commits to your GitHub project: ``$ git push -u origin <branch-name>`` - -* Submit pull-request. In GitHub visit the main repository and you should - see a banner suggesting to make a pull request. Fill out the form and - describe what you do. - -* Once pull resquests have been approved, you may want to locally update - your forked repository too. First you'll have to add a second remote - called `upstream` which points to our main repository. ``$ git remote add - upstream https://github.com/vyos/vyos-documentation.git`` - - Check your configured remote repositories: - - .. code-block:: none - - $ git remote -v - origin https://github.com/<username>/vyos-documentation.git (fetch) - origin https://github.com/<username>/vyos.documentation.git (push) - upstream https://github.com/vyos/vyos-documentation.git (fetch) - upstream https://github.com/vyos/vyos-documentation.git (push) - - Your remote repo on Github is called ``origin``, while the original repo you - have forked is called ``upstream``. Now you can locally update your forked - repo. - - .. code-block:: none - - $ git fetch upstream - $ git checkout master - $ git merge upstream/master - -* If you want to update your fork on GitHub, too use the following: ``$ git - push origin master`` - -Style Guide -=========== - -Formating and Sphinxmarkup --------------------------- - -TOC Level -^^^^^^^^^^ - -We use the following syntax for Headlines. - -.. code-block:: none - - ##### - Title - ##### - - ******** - Chapters - ******** - - Sections - ======== - - Subsections - ----------- - - Subsubsections - ^^^^^^^^^^^^^^ - - Paragraphs - """""""""" - -Address space -^^^^^^^^^^^^^ - -Note the following RFCs (:rfc:`5737`, :rfc:`3849`, :rfc:`5389` and -:rfc:`7042`), which describe the reserved public IP addresses and autonomous -system numbers for the documentation: - - * ``192.0.2.0/24`` - * ``198.51.100.0/24`` - * ``203.0.113.0/24`` - * ``2001:db8::/32`` - * 16bit ASN: ``64496 - 64511`` - * 32bit ASN: ``65536 - 65551`` - * Unicast MAC Addresses: ``00-53-00`` to ``00-53-FF`` - * Multicast MAC-Addresses: ``90-10-00`` to ``90-10-FF`` - -Please don't use other public address space. - - -Line length -^^^^^^^^^^^ - -Limit all lines to a maximum of 79 characters. - -Except in ``.. code-block::`` because it will use the html tag ``<pre>`` -which have the save line format as in the rst file. - - -Custom Sphinx-doc Markup -^^^^^^^^^^^^^^^^^^^^^^^^ - -When writing the documentation custom commands have been developed. Please -make yourself comfortable with those commands as this eases the way we -render the documentation. - -cfgcmd -"""""" - -When documenting CLI commands use the ``.. cfgcmd::`` directive -for all configuration mode commands. An explanation of the described command -should be added below this statement. -Replace all variable contents with <value> or somthing similar. - -With those custom commands it will be possible to render them in a more -descriptive way in the resulting HTML/PDF manual. - -.. code-block:: none - - .. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress> - - This will configure a static ARP entry always resolving `192.0.2.100` to - `00:53:27:de:23:aa`. - -For a inline configuration level command use ``:cfgcmd:`` - -.. code-block:: none - - :cfgcmd:`set interface ethernet eth0` - -opcmd -""""" - -When documenting operational level command use the ``.. opcmd::`` directive. -An explanation of the described command should be added below this statement. - -With those custom commands it will be possible to render them in a more -descriptive way in the resulting HTML/PDF manual. - -.. code-block:: none - - .. opcmd:: show protocols static arp - - Display all known ARP table entries spanning across all interfaces - -For a inline operational level command use ``:opcmd:`` - -.. code-block:: none - - :opcmd:`add system image` - -cmdinclude -"""""""""" - -To minimize redundancy there is a special include directive. It include a txt -file and replace the ``{{ var0 }}`` - ``{{ var9 }}`` with the correct value - -.. code-block:: none - - .. cmdinclude:: /_include/interface-address.txt - :var0: ethernet - :var1: eth1 - -the content of interface-address.txt looks like this - -.. code-block:: none - - .. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp | - dhcpv6> - - Configure interface `<interface>` with one or more interface - addresses. - - * **address** can be specified multiple times as IPv4 and/or IPv6 - address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64 - * **dhcp** interface address is received by DHCP from a DHCP server - on this segment. - * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6 - server on this segment. - - Example: - - .. code-block:: none - - set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24 - set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24 - set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64 - set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64 - -vytask -"""""" - -When referencing to VyOS Phabricator Tasks, there is a custom Sphinx Markup -command called ``vytask`` which automatically renders to a proper Phabricator -URL. This is heavily used in the :ref:`release-notes` section. - -.. code-block:: none - - * :vytask:`T1605` Fixed regression in L2TP/IPsec server - * :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly - -Page content ------------- - -The documentation have 3 different types of pages, the same kind of pages must -have the same structure to achieve a recognition factor. - -All RST files must follow the same TOC Level syntax and have to start with - -.. code-block:: - - ##### - Titel - ##### - -Configuration mode pages -^^^^^^^^^^^^^^^^^^^^^^^^ - -A configuration mode folder and article covers a specific level of a command. -The exact level depends on the command. This should provide stability for URLs -used in the forum or blogpost. - -For example: - - * ``set zone-policy`` is written in ``zone-policy/index.rst`` - * ``set interfaces ethernet`` is written in ``interfaces/ethernet.rst`` - -The article starts with a short intruducing about the command or the technologie. -Please include some helpfull links or background informations. - -After this a optional section follows. Some commands have requirements like the -compatible hardware (e.g. Wifi) or some commands you have to set before. For -example it is recommended to set a route-map before configure bgp. - -In the configuration part of the page all possible confiuration options -should be documented. Use ``.. cfgcmd::`` like described above. - -Related Operation command must be documented in the next part of the article. -Use ``::opcmd..`` for these commands. - -If there some troubleshooting guides releated to the commands. Explain it in the -next optional part. - -Operation mode pages -^^^^^^^^^^^^^^^^^^^^ - -Operation mode commands, which didn't fit in a related configuraton mode command -must documented in this part of the documentation. - -General concepts for troubleshooting belong here as well as detailed process -descriptions. - -Anything else -^^^^^^^^^^^^^ - -Anything else what is not a configuration or a operation command have no -predefined structure. - - -.. _Sphinx-doc: https://www.sphinx-doc.org -.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _reStructuredTextDirectives: https://docutils.sourceforge.io/docs/ref/rst/directives.html -.. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md - -.. include:: /_include/common-references.txt diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index c3bb2688..2ecbcb5f 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -6,8 +6,6 @@ Contributing :maxdepth: 2 build-vyos - debugging development - documentation issues-features upstream-packages
\ No newline at end of file |