diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/_static/images/nat_before_vpn_topology.png | bin | 0 -> 19015 bytes | |||
| -rw-r--r-- | docs/appendix/commandtree/configmode.rst (renamed from docs/commandtree/configmode.rst) | 0 | ||||
| -rw-r--r-- | docs/appendix/commandtree/index.rst (renamed from docs/commandtree/index.rst) | 4 | ||||
| -rw-r--r-- | docs/appendix/commandtree/operationmode.rst (renamed from docs/commandtree/operationmode.rst) | 0 | ||||
| -rw-r--r-- | docs/appendix/examples/dmvpn.rst (renamed from docs/examples/dmvpn.rst) | 0 | ||||
| -rw-r--r-- | docs/appendix/examples/index.rst (renamed from docs/examples/index.rst) | 4 | ||||
| -rw-r--r-- | docs/appendix/examples/zone-policy.rst (renamed from docs/examples/zone-policy.rst) | 0 | ||||
| -rw-r--r-- | docs/appendix/releasenotes.rst (renamed from docs/releasenotes.rst) | 4 | ||||
| -rw-r--r-- | docs/appendix/troubleshooting.rst (renamed from docs/troubleshooting.rst) | 4 | ||||
| -rw-r--r-- | docs/appendix/vyos-on-baremetal.rst (renamed from docs/vyos-on-baremetal.rst) | 9 | ||||
| -rw-r--r-- | docs/build-vyos.rst | 1 | ||||
| -rw-r--r-- | docs/contributing/coding_guidelines.rst | 144 | ||||
| -rw-r--r-- | docs/contributing/development.rst | 18 | ||||
| -rw-r--r-- | docs/contributing/index.rst | 377 | ||||
| -rw-r--r-- | docs/contributing/issues_features.rst | 27 | ||||
| -rw-r--r-- | docs/contributing/vyos_cli.rst | 264 | ||||
| -rw-r--r-- | docs/index.rst | 16 | ||||
| -rw-r--r-- | docs/nat.rst | 2 |
18 files changed, 488 insertions, 386 deletions
diff --git a/docs/_static/images/nat_before_vpn_topology.png b/docs/_static/images/nat_before_vpn_topology.png Binary files differnew file mode 100644 index 00000000..ae23c92d --- /dev/null +++ b/docs/_static/images/nat_before_vpn_topology.png diff --git a/docs/commandtree/configmode.rst b/docs/appendix/commandtree/configmode.rst index abb20f98..abb20f98 100644 --- a/docs/commandtree/configmode.rst +++ b/docs/appendix/commandtree/configmode.rst diff --git a/docs/commandtree/index.rst b/docs/appendix/commandtree/index.rst index 040e6f03..c3bca008 100644 --- a/docs/commandtree/index.rst +++ b/docs/appendix/commandtree/index.rst @@ -1,7 +1,7 @@ .. _commandtree: -Appendix C - Command tree -========================= +Command tree +============ See the the full Command tree in Operational mode and Configuration mode diff --git a/docs/commandtree/operationmode.rst b/docs/appendix/commandtree/operationmode.rst index 487df032..487df032 100644 --- a/docs/commandtree/operationmode.rst +++ b/docs/appendix/commandtree/operationmode.rst diff --git a/docs/examples/dmvpn.rst b/docs/appendix/examples/dmvpn.rst index d3bf45c7..d3bf45c7 100644 --- a/docs/examples/dmvpn.rst +++ b/docs/appendix/examples/dmvpn.rst diff --git a/docs/examples/index.rst b/docs/appendix/examples/index.rst index e976affd..c6e10eeb 100644 --- a/docs/examples/index.rst +++ b/docs/appendix/examples/index.rst @@ -1,7 +1,7 @@ .. _examples: -Appendix B - Configuration Examples -=================================== +Configuration Examples +====================== This chapter contains various configuration Examples diff --git a/docs/examples/zone-policy.rst b/docs/appendix/examples/zone-policy.rst index d159d02d..d159d02d 100644 --- a/docs/examples/zone-policy.rst +++ b/docs/appendix/examples/zone-policy.rst diff --git a/docs/releasenotes.rst b/docs/appendix/releasenotes.rst index 7adc5839..a2d9616e 100644 --- a/docs/releasenotes.rst +++ b/docs/appendix/releasenotes.rst @@ -1,7 +1,7 @@ .. _releasenotes: -Appendix E - Release notes -########################## +Release notes +############# 1.2 (Crux) ========== diff --git a/docs/troubleshooting.rst b/docs/appendix/troubleshooting.rst index 80a46932..e5b9b7a9 100644 --- a/docs/troubleshooting.rst +++ b/docs/appendix/troubleshooting.rst @@ -1,7 +1,7 @@ .. _troubleshooting: -Appendix A - Troubleshooting -============================ +Troubleshooting +=============== Sometimes things break or don't work as expected. This section describes several troubleshooting tools provided by VyOS that can help when something diff --git a/docs/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst index 0c2868e7..bda81116 100644 --- a/docs/vyos-on-baremetal.rst +++ b/docs/appendix/vyos-on-baremetal.rst @@ -1,7 +1,10 @@ .. _vyosonbaremetal: -Appendix D - Running on Bare Metal -################################## +Running on Bare Metal +##################### + +Intel Atom C3000 +**************** I opted to get one of the new Intel Atom C3000 CPUs to spawn VyOS on it. Running VyOS on an UEFI only device is supported as of VyOS release 1.2. @@ -66,4 +69,4 @@ Pictures .. figure:: /_static/images/1u_vyos_front_10ge_open_4.jpg :scale: 25 % - :alt: CSE-505-203B w/ 10GE Open + :alt: CSE-505-203B w/ 10GE Open diff --git a/docs/build-vyos.rst b/docs/build-vyos.rst index a6cc57bc..f373006f 100644 --- a/docs/build-vyos.rst +++ b/docs/build-vyos.rst @@ -47,6 +47,7 @@ Running the container and building the ISO user@build:~$ docker run --rm -it --privileged -v $(pwd):/vyos -w /vyos vyos-builder bash root@d4220bb519a0:/vyos# ./configure --architecture amd64 --build-by "your@email.tld" --build-type release --version 1.2.0 + root@d4220bb519a0:/vyos# make iso You may use these options to customize you ISO diff --git a/docs/contributing/coding_guidelines.rst b/docs/contributing/coding_guidelines.rst new file mode 100644 index 00000000..ff863d61 --- /dev/null +++ b/docs/contributing/coding_guidelines.rst @@ -0,0 +1,144 @@ +.. _coding_guidelines: + +Python Coding Guidelines +======================== + +The switch to the Python programming language for new code is not merely a change +of the language, but a chance to rethink and improve the programming approach. + +Let's face it: VyOS is full of spaghetti code where logic for reading the VyOS +config, generating daemon configs, and restarting processes is all mixed up. + +Python (or any other language, for that matter) does not provide automatic protection +from bad design, so we need to also devise design guidelines and follow them to +keep the system extensible and maintainable. + +Configuration script structure and behaviour +-------------------------------------------- + +.. code-block:: python + + import sys + + from vyos.config import Config + from vyos.util import ConfigError + + def get_config(): + vc = Config() + # Convert the VyOS config to an abstract internal representation + config = ... + return config + + def verify(config): + # Verify that configuration is valid + if invalid: + raise ConfigError("Descriptive message") + return True + + def generate(config): + # Generate daemon configs + pass + + def apply(config): + # Apply the generated configs to the live system + pass + + try: + config = get_config() + verify(config) + except ConfigError as e: + print(e) + sys.exit(1) + +The **get_config()** function must convert the VyOS config to an abstract internal +representation. No other function is allowed to call ``vyos.config.Config`` object +methods directly. The rationale for it is that when config reads are mixed with +other logic, it's very hard to change the config syntax since you need to weed +out every occurence of the old syntax. If syntax-specific code is confined to a +single function, the rest of the code can be left untouched as long as the +internal representation remains compatible. + +Another advantage is testability of the code. Mocking the entire config subsystem +is hard, while constructing an internal representation by hand is way simpler. + +The **verify()** function takes an internal representation of the config and checks +if it's valid, otherwise it must raise ``VyOSError`` with an error message that +describes the problem and possibly suggests how to fix it. It must not make any +changes to the system. The rationale for it is again testability and, in the +future when the config backend is ready and every script is rewritten in this +fashion, ability to execute commit dry run ("commit test" like in JunOS) and abort +commit before making any changes to the system if an error is found in any component. + +The **generate()** function generates config files for system components. + +The **apply()** function applies the generated configuration to the live system. +It should use non-disruptive reload whenever possible. It may execute disruptive +operations such as daemon process restart if a particular component does not +support non-disruptive reload, or when the expected service degradation is minimal +(for example, in case of auxillary services such as LLDPd). In case of high impact +services such as VPN daemon and routing protocols, when non-disruptive reload is +supported for some but not all types of configuration changes, scripts authors +should make effort to determine if a configuration change can be done in a +non-disruptive way and only resort to disruptive restart if it cannot be avoided. + +Unless absolutely necessary, configuration scripts should not modify the active +configuration of system components directly. Whenever at all possible, scripts +should generate a configuration file or files that can be applied with a single +command such as reloading a service through systemd init. Inserting statements +one by one is particularly discouraged, for example, when configuring netfilter +rules, saving them to a file and loading it with iptables-restore should always +be preferred to executing iptables directly. + +The **apply()** and **generate()** functions may ``raise ConfigError`` if, for +example, the daemon failed to start with the updated config. It shouldn't be a +substitute for proper config checking in the **verify()** function. All reasonable +effort should be made to verify that generated configuration is valid and will +be accepted by the daemon, including, when necessary, cross-checks with other +VyOS configuration subtrees. + +Exceptions, including ``VyOSError`` (which is raised by ``vyos.config.Config`` on +improper config operations, such as trying to use ``list_nodes()`` on a non-tag +node) should not be silenced or caught and re-raised as config error. Sure this +will not look pretty on user's screen, but it will make way better bug reports, +and help users (and most VyOS users are IT professionals) do their own debugging +as well. + +Coding guidelines +----------------- + +Language +******** + +Python 3 **shall** be used. How long can we keep Python 2 alive anyway? + +No considerations for Python 2 compatibility **should** be taken. + +Formatting +********** + +Tabs **shall not** be used. Every indentation level should be 4 spaces. + +Text generation +*************** + +Template processor **should** be used for generating config files. Built-in +string formatting **may** be used for simple line-oriented formats where every +line is self-contained, such as iptables rules. Template processor **must** be +used for structured, multi-line formats such as those used by ISC DHCPd. + +The default template processor for VyOS code is jinja2. + +Code policy +----------- + +When modifying the source code, remember these rules of the legacy elimination +campaign: + + * No new features in Perl + * No old style command definitions + * No code incompatible with Python3 + +.. _process: https://blog.vyos.io/vyos-development-digest-10 +.. _vyos-1x: https://github.com/vyos/vyos-1x/blob/current/schema/ +.. _VyConf: https://github.com/vyos/vyconf/blob/master/data/schemata + diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst new file mode 100644 index 00000000..14f0856a --- /dev/null +++ b/docs/contributing/development.rst @@ -0,0 +1,18 @@ +.. _development: + +Development +=========== + +The source code is hosted on GitHub under VyOS organization `github.com/vyos`_ + +The code is split into modules. VyOS is composed of multiple individual packages, +some of them are periodically synced with upstream, so keeping the whole source +under a single repository would be very inconvenient and slow. There is now an +ongoing effort to consolidate all VyOS-specific packages into vyos-1x package, +but the basic structure is going to stay the same, just with fewer submodules. + +The repository that contains the ISO build script is vyos-build_. The README will +guide you to use the this toplevel repository. + +.. _github.com/vyos: https://github.com/vyos +.. _vyos-build: https://github.com/vyos/vyos-build diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst index d3c5cb57..82d1b588 100644 --- a/docs/contributing/index.rst +++ b/docs/contributing/index.rst @@ -1,371 +1,10 @@ .. _contributing_index: - -Bug Reports and Feature Requests -================================ - -For Bug Reports and Feature Requests please take a look at Phabricator here: - -https://phabricator.vyos.net - - -Bug Report ----------- - -| To create a Bugreport use the quick link in the left side under the specific project. -| Please think about the next points: - - * provide as much information as you can - * which version you use - * what is to do to reproduce the bug - - -Feature Request ---------------- - -To send a Feature Request please search in Phabricator if there is already a Feature Request. You can enhance it or if you don't find one create a new one by use the quick link in the left side under the specific project. - - -Development -=========== - -The source code is hosted on github under VyOS organization: `github.com/vyos`_ - -The code is split into git submodules. Submodules is a mechanism for keeping subprojects in separate git repos while being able to access them from the main project. - -VyOS is composed of multiple individual packages, some of them are periodically synced with upstream, so keeping the whole source under a single repository would be very inconvenient and slow. There is now an ongoing effort to consolidate all VyOS-specific packages into vyos-1x package, but the basic structure is going to stay the same, just with fewer submodules. - -The repository that contains the ISO build scripts and links to all submodules is vyos-build_. The README will guide you to use the this toplevel repository. - - -VyOS CLI -======== - -The bash completion in VyOS is defined in *templates*. Templates are text files stored in a directory tree, where directory names define command names, and template files define command behaviour. -Befor VyOS 1.2.x this files were created by hand. After a complex redesing process_ the new style template are in XML. - -| XML interface definitions for VyOS come with a RelaxNG schema and are located here vyos-1x_ -| This schema is a slightly modified schema from VyConf_ alias VyOS 2.0 -| So VyOS 1.2.x interface definitions will be reusable in Nextgen VyOS Versions with very minimal changes. - -The great thing about schemas is not only that people can know the complete grammar for certain, but also that it can be automatically verified. -The scripts/build-command-templates script that converts the XML definitions to old style templates also verifies them against the schema, so a bad definition will cause the package build to fail. -I do agree that the format is verbose, but there is no other format now that would allow this. Besides, a specialized XML editor can alleviate the issue with verbosity. - -Example XML File ----------------- - - -.. code-block:: xml - - <?xml version="1.0"?> - <!-- Cron configuration --> - <interfaceDefinition> - <node name="system"> - <children> - <node name="task-scheduler"> - <properties> - <help>Task scheduler settings</help> - </properties> - <children> - <tagNode name="task" owner="${vyos_conf_scripts_dir}/task_scheduler.py"> - <properties> - <help>Scheduled task</help> - <valueHelp> - <format><string></format> - <description>Task name</description> - </valueHelp> - <priority>999</priority> - </properties> - <children> - <leafNode name="crontab-spec"> - <properties> - <help>UNIX crontab time specification string</help> - </properties> - </leafNode> - <leafNode name="interval"> - <properties> - <help>Execution interval</help> - <valueHelp> - <format><minutes></format> - <description>Execution interval in minutes</description> - </valueHelp> - <valueHelp> - <format><minutes>m</format> - <description>Execution interval in minutes</description> - </valueHelp> - <valueHelp> - <format><hours>h</format> - <description>Execution interval in hours</description> - </valueHelp> - <valueHelp> - <format><days>d</format> - <description>Execution interval in days</description> - </valueHelp> - <constraint> - <regex>[1-9]([0-9]*)([mhd]{0,1})</regex> - </constraint> - </properties> - </leafNode> - <node name="executable"> - <properties> - <help>Executable path and arguments</help> - </properties> - <children> - <leafNode name="path"> - <properties> - <help>Path to executable</help> - </properties> - </leafNode> - <leafNode name="arguments"> - <properties> - <help>Arguments passed to the executable</help> - </properties> - </leafNode> - </children> - </node> - </children> - </tagNode> - </children> - </node> - </children> - </node> - </interfaceDefinition> - -Configuration mode command definitions --------------------------------------- - -Command definitions are purely declarative, and cannot contain any logic. All logic for generating config files for target applications, restarting services and so on is implemented in configuration scripts instead. - -Command syntax guidelines -************************* - -Use of numbers -^^^^^^^^^^^^^^ - -Use of numbers in command names **should** be avoided unless a number is a part of a protocol name or similar. Thus, "protocols ospfv3" is perfectly fine, but something like "server-1" is questionable at best. - - -Help string guidelines -********************** - -To ensure uniform look and feel, and improve readability, we should follow a set of guidelines consistently. - -Capitalization and punctuation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The first word of every help string **must** be capitalized. There **must not** be a period at the end of help strings. Rationale: this seems to be the unwritten standard in network device CLIs, and a good aesthetic compromise. - -Examples: - - * Good: "Frobnication algorithm" - * Bad: "frobnication algorithm" - * Bad: "Frobnication algorithm." - * Horrible: "frobnication algorithm." - -Use of abbreviations and acronyms -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Abbreviations and acronyms **must** be capitalized. - -Examples: - - * Good: "TCP connection timeout" - * Bad: "tcp connection timeout" - * Horrible: "Tcp connectin timeout" - -Acronyms also **must** be capitalized to visually distinguish them from normal words: - -Examples: - - * Good: RADIUS (as in remote authentication for dial-in user services) - * Bad: radius (unless it's about the distance between a center of a circle and any of its points) - -Some abbreviations are traditionally written in mixed case. Generally, if it contains words "over" or "version", the letter **should** be lowercase. If there's an accepted spelling (especially if defined by an RFC or another standard), it **must** be followed. - -Examples: - - * Good: PPPoE, IPsec - * Bad: PPPOE, IPSEC - * Bad: pppoe, ipsec - -Use of verbs -^^^^^^^^^^^^ - -Verbs **should** be avoided. If a verb can be omitted, omit it. - -Examples: - - * Good: "TCP connection timeout" - * Bad: "Set TCP connection timeout" - -If a verb is essential, keep it. For example, in the help text of "set system ipv6 disable-forwarding", "Disable IPv6 forwarding on all interfaces" is a perfectly justified wording. - -Prefer infinitives -^^^^^^^^^^^^^^^^^^ - -Verbs, when they are necessary, **should** be in their infinitive form. - -Examples: - - * Good: "Disable IPv6 forwarding" - * Bad: "Disables IPv6 forwarding" - - -Mapping from the old node.def style to the new XML definitions --------------------------------------------------------------- - - -.. list-table:: - :widths: 25 25 50 - :header-rows: 1 - - * - Old concept/syntax - - New syntax - - Notes - * - mynode/node.def - - <node name="mynode"> </node> - - Leaf nodes (nodes with values) use <leafNode> tag instead - * - mynode/node.tag , tag: - - <tagNode name="mynode> </node> - - - * - help: My node - - <properties> <help>My node</help> - - - * - val_help: <format>; some string - - <properties> <valueHelp> <format> format </format> <description> some string </description> - - Do not add angle brackets around the format, they will be inserted automatically - * - syntax:expression: pattern - - <properties> <constraint> <regex> ... - - <constraintErrorMessage> will be displayed on failure - * - syntax:expression: $VAR(@) in "foo", "bar", "baz" - - None - - Use regex - * - syntax:expression: exec ... - - <properties> <constraint> <validator> <name ="foo" argument="bar"> - - "${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed, <constraintErrorMessage> will be displayed on failure - * - syntax:expression: (arithmetic expression) - - None - - External arithmetic validator may be added if there's demand, complex validation is better left to commit-time scripts - * - priority: 999 - - <properties> <priority>999</priority> - - Please leave a comment explaining why the priority was chosen (e.g. "after interfaces are configured") - * - multi: - - <properties> <multi/> - - Only applicable to leaf nodes - * - allowed: echo foo bar - - <properties> <completionHelp> <list> foo bar </list> - - - * - allowed: cli-shell-api listNodes vpn ipsec esp-group - - <properties> <completionHelp> <path> vpn ipsec esp-group </path> ... - - - * - allowed: /path/to/script - - <properties> <completionHelp> <script> /path/to/script </script> ... - - - * - default: - - None - - Move default values to scripts - * - commit:expression: - - None - - All commit time checks should be in the verify() function of the script - * - begin:/create:/delete: - - None - - All logic should be in the scripts - -Python coding guidelines -======================== - -The switch to the Python programming language for new code is not merely a change of the language, but a chance to rethink and improve the programming approach. - -Let's face it: VyOS is full of spaghetti code where logic for reading the VyOS config, generating daemon configs, and restarting processes is all mixed up. -Python (or any other language, for that matter) does not provide automatic protection from bad design, so we need to also devise design guidelines and follow them to keep the system extensible and maintainable. - -Configuration script structure and behaviour --------------------------------------------- - -.. code-block:: python - - import sys - - from vyos.config import Config - from vyos.util import ConfigError - - - def get_config(): - vc = Config() - # Convert the VyOS config to an abstract internal representation - config = ... - return config - - def verify(config): - # Verify that configuration is valid - if invalid: - raise ConfigError("Descriptive message") - return True - - def generate(config): - # Generate daemon configs - pass - - def apply(config): - # Apply the generated configs to the live system - pass - - try: - config = get_config() - verify(config) - except ConfigError as e: - print(e) - sys.exit(1) - -The **get_config()** function must convert the VyOS config to an abstract internal representation. No other function is allowed to call vyos.config.Config object methods directly. The rationale for it is that when config reads are mixed with other logic, it's very hard to change the config syntax since you need to weed out every occurence of the old syntax. If syntax-specific code is confined to a single function, the rest of the code can be left untouched as long as the internal representation remains compatible. - -Another advantage is testability of the code. Mocking the entire config subsystem is hard, while constructing an internal representation by hand is way simpler. - -The **verify()** function takes an internal representation of the config and checks if it's valid, otherwise it must raise VyOSError with an error message that describes the problem and possibly suggests how to fix it. It must not make any changes to the system. The rationale for it is again testability and, in the future when the config backend is ready and every script is rewritten in this fashion, ability to execute commit dry run ("commit test" like in JunOS) and abort commit before making any changes to the system if an error is found in any component. - -The **generate()** function generates config files for system components. - -The **apply()** function applies the generated configuration to the live system. It should use non-disruptive reload whenever possible. It may execute disruptive operations such as daemon process restart if a particular component does not support non-disruptive reload, or when the expected service degradation is minimal (for example, in case of auxillary services such as LLDPd). In case of high impact services such as VPN daemon and routing protocols, when non-disruptive reload is supported for some but not all types of configuration changes, scripts authors should make effort to determine if a configuration change can be done in a non-disruptive way and only resort to disruptive restart if it cannot be avoided. - -Unless absolutely necessary, configuration scripts should not modify the active configuration of system components directly. Whenever at all possible, scripts should generate a configuration file or files that can be applied with a single command such as reloading a service through systemd/SysV init. Inserting statements one by one is particularly discouraged, for example, when configuring netfilter rules, saving them to a file and loading it with iptables-restore should always be preferred to executing iptables directly. - -The **apply()** and **generate()** functions may raise ConfigError if, for example, the daemon failed to start with the updated config. It shouldn't be a substitute for proper config checking in the **verify()** function. All reasonable effort should be made to verify that generated configuration is valid and will be accepted by the daemon, including, when necessary, cross-checks with other VyOS configuration subtrees. - -Exceptions, including VyOSError (which is raised by vyos.config.Config on improper config operations, such as trying to use **list_nodes()** on a non-tag node) should not be silenced or caught and re-raised as config error. Sure this will not look pretty on user's screen, but it will make way better bug reports, and help users (and most VyOS users are IT professionals) do their own debugging as well. - -Coding guidelines ------------------ - -Language -******** - -| Python 3 **shall** be used. How long can we keep Python 2 alive anyway? -| No considerations for Python 2 compatibility **should** be taken. - -Formatting -********** - -Tabs **shall not** be used. Every indentation level should be 4 spaces. - -Text generation -*************** - -| Template processor **should** be used for generating config files. Built-in string formatting **may** be used for simple line-oriented formats where every line is self-contained, such as iptables rules. Template processor **must** be used for structured, multi-line formats such as those used by ISC DHCPd. -| The default template processor for VyOS code is jinja2. - -Code policy ------------ - -When modifying the source code, remember these rules of the legacy elimination campaign: - - * No new features in Perl - * No old style command definitions - * No code incompatible with Python3 - - -.. _github.com/vyos: https://github.com/vyos -.. _vyos-build: https://github.com/vyos/vyos-build -.. _process: https://blog.vyos.io/vyos-development-digest-10 -.. _vyos-1x: https://github.com/vyos/vyos-1x/blob/current/schema/ -.. _VyConf: https://github.com/vyos/vyconf/blob/master/data/schemata +.. toctree:: + :maxdepth: 2 + :hidden: + + issues_features + development + vyos_cli + coding_guidelines diff --git a/docs/contributing/issues_features.rst b/docs/contributing/issues_features.rst new file mode 100644 index 00000000..de55128e --- /dev/null +++ b/docs/contributing/issues_features.rst @@ -0,0 +1,27 @@ +.. _issues_features: + +Issues and Feature requests +=========================== + +For Bug Reports and Feature Requests please take a look at Phabricator here: + +https://phabricator.vyos.net + +Bug Report / Issue +------------------ + +To create a Bugreport use the quick link in the left side under the specific +project. Please think about the next points: + +* provide as much information as you can +* which version you use +* what is to do to reproduce the bug + +Feature Request +--------------- + +To send a Feature Request please search Phabricator if there is already a +feature request targeting your request. You can enhance it or if you don't find +one create a new one by use the quick link in the left side under the specific +project. + diff --git a/docs/contributing/vyos_cli.rst b/docs/contributing/vyos_cli.rst new file mode 100644 index 00000000..f539efda --- /dev/null +++ b/docs/contributing/vyos_cli.rst @@ -0,0 +1,264 @@ +.. _vyos_cli: + +VyOS CLI +======== + +The bash completion in VyOS is defined in *templates*. Templates are text files +stored in a directory tree, where directory names define command names, and +template files define command behaviour. Befor VyOS 1.2.x this files were created +by hand. After a complex redesing process_ the new style template are in XML. + +XML interface definitions for VyOS come with a RelaxNG schema and are located +in the vyos-1x_ module. This schema is a slightly modified schema from VyConf_ +alias VyOS 2.0 So VyOS 1.2.x interface definitions will be reusable in Nextgen +VyOS Versions with very minimal changes. + +The great thing about schemas is not only that people can know the complete +grammar for certain, but also that it can be automatically verified. The +`scripts/build-command-templates` script that converts the XML definitions to +old style templates also verifies them against the schema, so a bad definition +will cause the package build to fail. I do agree that the format is verbose, but +there is no other format now that would allow this. Besides, a specialized XML +editor can alleviate the issue with verbosity. + +Example XML File +---------------- + +.. code-block:: xml + + <?xml version="1.0"?> + <!-- Cron configuration --> + <interfaceDefinition> + <node name="system"> + <children> + <node name="task-scheduler"> + <properties> + <help>Task scheduler settings</help> + </properties> + <children> + <tagNode name="task" owner="${vyos_conf_scripts_dir}/task_scheduler.py"> + <properties> + <help>Scheduled task</help> + <valueHelp> + <format><string></format> + <description>Task name</description> + </valueHelp> + <priority>999</priority> + </properties> + <children> + <leafNode name="crontab-spec"> + <properties> + <help>UNIX crontab time specification string</help> + </properties> + </leafNode> + <leafNode name="interval"> + <properties> + <help>Execution interval</help> + <valueHelp> + <format><minutes></format> + <description>Execution interval in minutes</description> + </valueHelp> + <valueHelp> + <format><minutes>m</format> + <description>Execution interval in minutes</description> + </valueHelp> + <valueHelp> + <format><hours>h</format> + <description>Execution interval in hours</description> + </valueHelp> + <valueHelp> + <format><days>d</format> + <description>Execution interval in days</description> + </valueHelp> + <constraint> + <regex>[1-9]([0-9]*)([mhd]{0,1})</regex> + </constraint> + </properties> + </leafNode> + <node name="executable"> + <properties> + <help>Executable path and arguments</help> + </properties> + <children> + <leafNode name="path"> + <properties> + <help>Path to executable</help> + </properties> + </leafNode> + <leafNode name="arguments"> + <properties> + <help>Arguments passed to the executable</help> + </properties> + </leafNode> + </children> + </node> + </children> + </tagNode> + </children> + </node> + </children> + </node> + </interfaceDefinition> + +Configuration mode command definitions +-------------------------------------- + +Command definitions are purely declarative, and cannot contain any logic. All +logic for generating config files for target applications, restarting services +and so on is implemented in configuration scripts instead. + +Command syntax guidelines +************************* + +Use of numbers +^^^^^^^^^^^^^^ + +Use of numbers in command names **should** be avoided unless a number is a part +of a protocol name or similar. Thus, ``protocols ospfv3`` is perfectly fine, but +something like ``server-1`` is questionable at best. + +Help string guidelines +********************** + +To ensure uniform look and feel, and improve readability, we should follow a set +of guidelines consistently. + +Capitalization and punctuation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The first word of every help string **must** be capitalized. There **must not** +be a period at the end of help strings. + +Rationale: this seems to be the unwritten standard in network device CLIs, and +a good aesthetic compromise. + +Examples: + + * Good: "Frobnication algorithm" + * Bad: "frobnication algorithm" + * Bad: "Frobnication algorithm." + * Horrible: "frobnication algorithm." + +Use of abbreviations and acronyms +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Abbreviations and acronyms **must** be capitalized. + +Examples: + + * Good: "TCP connection timeout" + * Bad: "tcp connection timeout" + * Horrible: "Tcp connectin timeout" + +Acronyms also **must** be capitalized to visually distinguish them from normal +words: + +Examples: + + * Good: RADIUS (as in remote authentication for dial-in user services) + * Bad: radius (unless it's about the distance between a center of a circle and + any of its points) + +Some abbreviations are traditionally written in mixed case. Generally, if it +contains words "over" or "version", the letter **should** be lowercase. If there's +an accepted spelling (especially if defined by an RFC or another standard), it +**must** be followed. + +Examples: + + * Good: PPPoE, IPsec + * Bad: PPPOE, IPSEC + * Bad: pppoe, ipsec + +Use of verbs +^^^^^^^^^^^^ + +Verbs **should** be avoided. If a verb can be omitted, omit it. + +Examples: + + * Good: "TCP connection timeout" + * Bad: "Set TCP connection timeout" + +If a verb is essential, keep it. For example, in the help text of `set system ipv6 +disable-forwarding`, "Disable IPv6 forwarding on all interfaces" is a perfectly +justified wording. + +Prefer infinitives +^^^^^^^^^^^^^^^^^^ + +Verbs, when they are necessary, **should** be in their infinitive form. + +Examples: + + * Good: "Disable IPv6 forwarding" + * Bad: "Disables IPv6 forwarding" + +Mapping old node.def style to new XML definitions +------------------------------------------------- + +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * - Old concept/syntax + - New syntax + - Notes + * - mynode/node.def + - <node name="mynode"> </node> + - Leaf nodes (nodes with values) use <leafNode> tag instead + * - mynode/node.tag , tag: + - <tagNode name="mynode> </node> + - + * - help: My node + - <properties> <help>My node</help> + - + * - val_help: <format>; some string + - <properties> <valueHelp> <format> format </format> <description> some + string </description> + - Do not add angle brackets around the format, they will be inserted + automatically + * - syntax:expression: pattern + - <properties> <constraint> <regex> ... + - <constraintErrorMessage> will be displayed on failure + * - syntax:expression: $VAR(@) in "foo", "bar", "baz" + - None + - Use regex + * - syntax:expression: exec ... + - <properties> <constraint> <validator> <name ="foo" argument="bar"> + - "${vyos_libexecdir}/validators/foo bar $VAR(@)" will be executed, + <constraintErrorMessage> will be displayed on failure + * - syntax:expression: (arithmetic expression) + - None + - External arithmetic validator may be added if there's demand, complex + validation is better left to commit-time scripts + * - priority: 999 + - <properties> <priority>999</priority> + - Please leave a comment explaining why the priority was chosen (e.g. "after + interfaces are configured") + * - multi: + - <properties> <multi/> + - Only applicable to leaf nodes + * - allowed: echo foo bar + - <properties> <completionHelp> <list> foo bar </list> + - + * - allowed: cli-shell-api listNodes vpn ipsec esp-group + - <properties> <completionHelp> <path> vpn ipsec esp-group </path> ... + - + * - allowed: /path/to/script + - <properties> <completionHelp> <script> /path/to/script </script> ... + - + * - default: + - None + - Move default values to scripts + * - commit:expression: + - None + - All commit time checks should be in the verify() function of the script + * - begin:/create:/delete: + - None + - All logic should be in the scripts + +.. _process: https://blog.vyos.io/vyos-development-digest-10 +.. _vyos-1x: https://github.com/vyos/vyos-1x/blob/current/schema/ +.. _VyConf: https://github.com/vyos/vyconf/blob/master/data/schemata + diff --git a/docs/index.rst b/docs/index.rst index c4932c88..e9b1e262 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,11 +31,17 @@ as a router and firewall platform for cloud deployments. clustering.rst image-mgmt.rst commandscripting.rst - troubleshooting.rst - examples/index.rst - commandtree/index.rst - vyos-on-baremetal.rst - releasenotes.rst + +.. toctree:: + :maxdepth: 2 + :caption: Appendix: + :includehidden: + + appendix/releasenotes.rst + appendix/troubleshooting.rst + appendix/examples/index.rst + appendix/commandtree/index.rst + appendix/vyos-on-baremetal.rst .. toctree:: :maxdepth: 2 diff --git a/docs/nat.rst b/docs/nat.rst index 33e1efc4..66fb783e 100644 --- a/docs/nat.rst +++ b/docs/nat.rst @@ -337,7 +337,7 @@ Example Network Here's one example of a network environment for an ASP. The ASP requests that all connections from this company should come from 172.29.41.89 - an address that is assigned by the ASP and not in use at the customer site. -.. figure:: _static/images/nat_befor_vpn_topology.png +.. figure:: _static/images/nat_before_vpn_topology.png :scale: 100 % :alt: NAT before VPN Topology |
