diff options
Diffstat (limited to 'docs/contributing')
| -rw-r--r-- | docs/contributing/upstream-packages.rst | 62 | ||||
| -rw-r--r-- | docs/contributing/vyos_cli.rst | 71 |
2 files changed, 72 insertions, 61 deletions
diff --git a/docs/contributing/upstream-packages.rst b/docs/contributing/upstream-packages.rst index 4e602866..089ed141 100644 --- a/docs/contributing/upstream-packages.rst +++ b/docs/contributing/upstream-packages.rst @@ -3,27 +3,30 @@ Upstream packages ================= -Many base system packages are pulled straight from Debian's main and contrib repositories, but there are exceptions. +Many base system packages are pulled straight from Debian's main and contrib +repositories, but there are exceptions. vyos-netplug ------------ -Due to issues in the upstream version that sometimes set interfaces down, a modified version is used. +Due to issues in the upstream version that sometimes set interfaces down, a +modified version is used. -The source is at https://github.com/vyos/vyos-netplug +The source is located at https://github.com/vyos/vyos-netplug -In the future, we may switch to using systemd infrastructure instead. - -Building it doesn't require a special procedure. +In the future, we may switch to using systemd infrastructure instead. Building +it doesn't require a special procedure. keepalived ---------- -Keepalived normally isn't updated to newer feature releases between Debian versions, so we are building it from source. +Keepalived normally isn't updated to newer feature releases between Debian +versions, so we are building it from source. -Debian does keep their package in git, but it's upstream tarball imported into git without its original commit history. -To be able to merge new tags in, we keep a fork of the upstream repository with packaging files imported from Debian -at http://github.com/vyos/keepalived-upstream +Debian does keep their package in git, but it's upstream tarball imported into +git without its original commit history. To be able to merge new tags in, we +keep a fork of the upstream repository with packaging files imported from +Debian at http://github.com/vyos/keepalived-upstream strongswan ---------- @@ -35,11 +38,12 @@ Our StrongSWAN build differs from the upstream: The source is at https://github.com/vyos/vyos-strongswan -DMVPN patches are added by this commit: https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226d4a3e9138e7 +DMVPN patches are added by this commit: +https://github.com/vyos/vyos-strongswan/commit/1cf12b0f2f921bfc51affa3b81226 -Our op mode scripts use the python-vici module, which is not included in Debian's build, -and isn't quite easy to integrate in that build. For this reason we debianize that module by hand now, -using this procedure: +Our op mode scripts use the python-vici module, which is not included in +Debian's build, and isn't quite easy to integrate in that build. For this +reason we debianize that module by hand now, using this procedure: 0. Install https://pypi.org/project/stdeb/ 1. `cd vyos-strongswan` @@ -53,32 +57,36 @@ The package ends up in deb_dist dir. ppp --- -Properly renaming PPTP and L2TP interfaces to pptpX and l2tpX from generic and non-informative pppX requires a patch -that is neither in the upstream nor in Debian. +Properly renaming PPTP and L2TP interfaces to pptpX and l2tpX from generic and +non-informative pppX requires a patch that is neither in the upstream nor in +Debian. We keep a fork of Debian's repo at https://github.com/vyos/ppp-debian The patches for pre-up renaming are: -* https://github.com/vyos/ppp-debian/commit/e728180026a051d2a96396276e7e4ae022899e2d -* https://github.com/vyos/ppp-debian/commit/f29ba8d9ebb043335a096d70bcd07e9635bba2e3 +* https://github.com/vyos/ppp-debian/commit/e728180026a051d2a96396276e7e4ae +* https://github.com/vyos/ppp-debian/commit/f29ba8d9ebb043335a096d70bcd07e9 -Additionally, there's a patch for reopening the log file to better support logging to files, even though it's less essential: -https://github.com/vyos/ppp-debian/commit/dd2ebd5cdcddb40230dc4cc43d374055ff374711 +Additionally, there's a patch for reopening the log file to better support +logging to files, even though it's less essential: +https://github.com/vyos/ppp-debian/commit/dd2ebd5cdcddb40230dc4cc43d374055f The patches were written by Stephen Hemminger back in the Vyatta times. mdns-repeater ------------- -This package doesn't exist in Debian. A debianized fork is kept at https://github.com/vyos/mdns-repeater +This package doesn't exist in Debian. A debianized fork is kept at +https://github.com/vyos/mdns-repeater No special build procedure is required. udp-broadcast-relay ------------------- -This package doesn't exist in Debian. A debianized fork is kept at https://github.com/vyos/udp-broadcast-relay +This package doesn't exist in Debian. A debianized fork is kept at +https://github.com/vyos/udp-broadcast-relay No special build procedure is required. @@ -100,7 +108,8 @@ TBD accel-ppp --------- -accel-ppp has been packaged for the use with vyos, due to the kernel dependencies for its modules. +accel-ppp has been packaged for the use with vyos, due to the kernel +dependencies for its modules. * https://github.com/vyos/vyos-accel-ppp @@ -113,10 +122,11 @@ A fork with packaging changes for VyOS is kept at https://github.com/vyos/hvinfo The original repo is at https://github.com/dmbaturin/hvinfo -It's an Ada program and requires GNAT and gprbuild for building, dependencies are properly specified -so just follow debuild's suggestions. +It's an Ada program and requires GNAT and gprbuild for building, dependencies +are properly specified so just follow debuild's suggestions. Per-file modifications ------------------------ -vyos-replace package replaces the upstream dhclient-script with a modified version that is aware of the VyOS config. +vyos-replace package replaces the upstream dhclient-script with a modified +version that is aware of the VyOS config. diff --git a/docs/contributing/vyos_cli.rst b/docs/contributing/vyos_cli.rst index 49f9a230..322b0be6 100644 --- a/docs/contributing/vyos_cli.rst +++ b/docs/contributing/vyos_cli.rst @@ -1,12 +1,14 @@ .. _vyos_cli: -VyOS CLI -======== +The 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. Before VyOS 1.2.x this files were created -by hand. After a complex redesign process_ the new style template are in XML. +The bash (or better vbash) completion in VyOS is defined in *templates*. +Templates are text files (called ``node.def``) stored in a directory tree. The +directory names define the command names, and template files define the command +behaviour. Before VyOS 1.2 (crux) this files were created by hand. After a +complex redesign process_ the new style template are automatically generated +from a XML input file. 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_ @@ -113,15 +115,15 @@ 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. +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. +To ensure uniform look and feel, and improve readability, we should follow a +set of guidelines consistently. Capitalization and punctuation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -134,10 +136,10 @@ a good aesthetic compromise. Examples: - * Good: "Frobnication algorithm" - * Bad: "frobnication algorithm" - * Bad: "Frobnication algorithm." - * Horrible: "frobnication algorithm." +* Good: "Frobnication algorithm" +* Bad: "frobnication algorithm" +* Bad: "Frobnication algorithm." +* Horrible: "frobnication algorithm." Use of abbreviations and acronyms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -146,29 +148,29 @@ Abbreviations and acronyms **must** be capitalized. Examples: - * Good: "TCP connection timeout" - * Bad: "tcp connection timeout" - * Horrible: "Tcp connectin timeout" +* 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) +* 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. +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 +* Good: PPPoE, IPsec +* Bad: PPPOE, IPSEC +* Bad: pppoe, ipsec Use of verbs ^^^^^^^^^^^^ @@ -177,12 +179,12 @@ Verbs **should** be avoided. If a verb can be omitted, omit it. Examples: - * Good: "TCP connection timeout" - * Bad: "Set TCP connection timeout" +* 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. +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 ^^^^^^^^^^^^^^^^^^ @@ -191,8 +193,8 @@ Verbs, when they are necessary, **should** be in their infinitive form. Examples: - * Good: "Disable IPv6 forwarding" - * Bad: "Disables IPv6 forwarding" +* Good: "Disable IPv6 forwarding" +* Bad: "Disables IPv6 forwarding" Mapping old node.def style to new XML definitions ------------------------------------------------- @@ -261,4 +263,3 @@ Mapping old node.def style to new XML definitions .. _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 - |