From 32652cce15d200363c0dbaf5d2c6c41621f51e73 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 21 Dec 2019 18:03:01 +0100 Subject: install: overall chapter improvement --- docs/contributing/issues-features.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs/contributing') diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 3a1738d7..04efbd22 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -3,6 +3,8 @@ Issues/Feature requests ======================= +.. _bug_report: + Bug Report/Issue ---------------- Issues or bugs are found in any software project. VyOS is not an exception. -- cgit v1.2.3 From fe343f5a824dc663896fb63af33e201cc2146b68 Mon Sep 17 00:00:00 2001 From: Jernej Jakob Date: Sat, 21 Dec 2019 15:45:22 +0100 Subject: contribution: build: add section about building packages This is copied from the vyos-build README.md with some changes and updates. --- docs/contributing/build-vyos.rst | 102 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) (limited to 'docs/contributing') diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index bc113750..d158594e 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -121,6 +121,108 @@ Good luck! or ``rolling`` image. Make sure to choose the matching container for the version of VyOS that is being built. +.. _build_packages: + +Build packages +-------------- + +VyOS requires a bunch of packages which are VyOS specific and thus can not be +found in any Debian Upstream mirrror. Those packages can be found at the VyOS +GitHub project (https://github.com/vyos) and there is a nice helper script +available to build and list those individual packages. + +`scripts/build-packages` provides an easy interface to automate the process +of building all VyOS related packages that are not part of the upstream Debian +version. Execute it in the root of the `vyos-build` directory to start +compilation. + +.. code-block:: none + + $ scripts/build-packages -h + usage: build-packages [-h] [-c | -k | -f] [-v] [-l] [-b BUILD [BUILD ...]] + [-p] [--blacklist BLACKLIST [BLACKLIST ...]] + + optional arguments: + -h, --help show this help message and exit + -c, --clean Re-clone required Git repositories + -k, --keep Keep modified Git repositories + -f, --fetch Fetch sources only, no build + -v, --verbose Increase logging verbosity for each occurance + -l, --list-packages List all packages to build + -b BUILD [BUILD ...], --build BUILD [BUILD ...] + Whitespace separated list of packages to build + -p, --parallel Build on all CPUs + --blacklist BLACKLIST [BLACKLIST ...] + Do not build/report packages when calling --list + +Git repositoriers are automatically fetched and build on demand. If you want to +work offline you can fetch all source code first with the `-f` option. + +The easiest way to compile is with the above mentioned Docker +container, it includes all dependencies for compiling supported packages. + +.. code-block:: none + + $ docker run --rm -it -v $(pwd):/vyos -w /vyos \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages + +.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is required to build the + `vyos-strongswan` package + +.. note:: Prior to executing this script you need to create or build the Docker + container and checkout all packages you want to compile. + +Building single package(s) +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To build a single package use the same script as above but specify packages with +`-b`: + +Executed from the root of `vyos-build` + +.. code-block:: none + + $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages -b + +.. note:: `--sysctl net.ipv6.conf.lo.disable_ipv6=0` is only needed when + building `vyos-strongswan` and can be ignored on other packages. + +.. note:: `vyos-strongswan` will only compile on a Linux system, running on + macOS or Windows might result in a unittest deadlock (it never exits). + +Building single packages from your own repositories +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can also build packages that are not from the default git repositories, +for example from your own forks of the official vyos repositories. + +First create a directory "packages" at the top level of the vyos-build +repository and clone your package into it (creating a subdirectory with the +package contents). Then checkout the correct branch or commit you want to build +before building the package. + +Example using `git@github.com:myname/vyos-1x.git` repository to build vyos-1x: + +.. code-block:: none + + $ mkdir packages + $ cd packages + $ git clone git@github.com:myname/vyos-1x.git + $ cd .. + $ docker run --rm -it -v $(pwd):/vyos -w /vyos/packages/PACKAGENAME \ + --sysctl net.ipv6.conf.lo.disable_ipv6=0 \ + vyos-builder scripts/build-packages -b vyos-1x + +.. note:: You need to git pull manually after you commit to the remote and + before rebuilding, the local repository won't be updated automatically. + +.. warning:: Any packages in the packages directory will be added to the iso + during build, replacing the upstream ones. Make sure you delete them (both + the source directories and built deb packages) if you want to build an iso + from purely upstream packages. .. _upstream_packages: -- cgit v1.2.3 From 3918aefbeeeac4ab9844e3528995ae689a9bd952 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 10:41:33 +0100 Subject: vytask: migrate all task references to new command --- docs/appendix/vyos-on-baremetal.rst | 6 ++---- docs/contributing/development.rst | 3 +-- docs/routing/ospf.rst | 4 +--- 3 files changed, 4 insertions(+), 9 deletions(-) (limited to 'docs/contributing') diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst index 76b5e210..5f20a03f 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/appendix/vyos-on-baremetal.rst @@ -107,7 +107,7 @@ VyOS 1.2 (crux) --------------- Depending on the VyOS versions you intend to install there is a difference in -the serial port settings (T1327_). +the serial port settings (:vytask:`T1327`). Create a bootable USB pendrive using e.g. Rufus_ on a Windows machine. @@ -190,7 +190,7 @@ VyOS 1.2 (rolling) ------------------ Installing the rolling release on an APU2 board does not require any change -on the serial console from your host side as T1327_ was successfully +on the serial console from your host side as :vytask:`T1327` was successfully implemented. Simply proceed with a regular image installation as described in @@ -246,8 +246,6 @@ Desktop :alt: APU4C4 desktop back .. _Rufus: https://rufus.ie/ -.. _T1327: https://phabricator.vyos.net/T1327 - Qotom Q355G4 ************ diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 1c257772..35b9e17a 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -486,7 +486,7 @@ GNU Preprocessor ---------------- XML interface definition files use the `xml.in` file extension which was -implemented in T1843_. XML interface definitions tend to have a lot of +implemented in :vytask:`T1843`. XML interface definitions tend to have a lot of duplicated code in areas such as: * VIF (incl. VIF-S/VIF-C) @@ -698,7 +698,6 @@ http://dev.packages.vyos.net/repositories/. .. _Phabricator: https://phabricator.vyos.net/ .. _Jenkins: https://jenkins.io/ .. _Dockerhub: https://hub.docker.com/u/vyos/ -.. _T1843: https://phabricator.vyos.net/T1843 .. _`IPv4, IPv6 and DHCP(v6)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6-dhcp.xml.i .. _`IPv4, IPv6`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6.xml.i .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i diff --git a/docs/routing/ospf.rst b/docs/routing/ospf.rst index bee70895..acffb7b3 100644 --- a/docs/routing/ospf.rst +++ b/docs/routing/ospf.rst @@ -90,7 +90,7 @@ A typical configuration using 2 nodes. .. note:: You can not easily redistribute IPv6 routes via OSPFv3 on a WireGuard interface link. This requires you to configure link-local addresses manually - on the WireGuard interfaces, see Phabricator task T1483_. + on the WireGuard interfaces, see :vytask:`T1483`. Example configuration for WireGuard interfaces: @@ -136,5 +136,3 @@ Example configuration for WireGuard interfaces: Neighbor ID Pri DeadTime State/IfState Duration I/F[State] 192.168.0.1 1 00:00:39 Full/PointToPoint 00:19:44 wg01[PointToPoint] -.. _T1483: https://phabricator.vyos.net/T1483 - -- cgit v1.2.3 From 1499918804a16051c44d2ee248c067f25e617185 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 11:07:22 +0100 Subject: common-references: migrate all VyOS Phabricator references --- docs/common-references.rst | 1 + docs/contributing/development.rst | 3 ++- docs/contributing/documentation.rst | 3 ++- docs/contributing/issues-features.rst | 10 ++++++---- docs/vpn/openvpn.rst | 6 ++++-- 5 files changed, 15 insertions(+), 8 deletions(-) (limited to 'docs/contributing') diff --git a/docs/common-references.rst b/docs/common-references.rst index 9f0b9b84..d7e376eb 100644 --- a/docs/common-references.rst +++ b/docs/common-references.rst @@ -1,2 +1,3 @@ .. _`accel-ppp`: https://accel-ppp.org/ .. _`Secure Socket Tunneling Protocol`: https://en.wikipedia.org/wiki/Secure_Socket_Tunneling_Protocol +.. _Phabricator: https://phabricator.vyos.net/ diff --git a/docs/contributing/development.rst b/docs/contributing/development.rst index 35b9e17a..fed06e6f 100644 --- a/docs/contributing/development.rst +++ b/docs/contributing/development.rst @@ -695,10 +695,11 @@ http://dev.packages.vyos.net/repositories/. .. _VyConf: https://github.com/vyos/vyconf/tree/master/data/schemata .. _vyos-1x: https://github.com/vyos/vyos-1x/tree/current/schema .. _Jinja2: https://jinja.palletsprojects.com/ -.. _Phabricator: https://phabricator.vyos.net/ .. _Jenkins: https://jenkins.io/ .. _Dockerhub: https://hub.docker.com/u/vyos/ .. _`IPv4, IPv6 and DHCP(v6)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6-dhcp.xml.i .. _`IPv4, IPv6`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/address-ipv4-ipv6.xml.i .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i + +.. include:: ../common-references.rst diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 48cc063b..c639651b 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -171,5 +171,6 @@ be added below this statement. .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -.. _Phabricator: https://phabricator.vyos.net .. _README.md: https://github.com/vyos/vyos-documentation/blob/master/README.md + +.. include:: ../common-references.rst diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 04efbd22..e208a3e6 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -51,9 +51,10 @@ also contain information that is helpful for the development team. Report a Bug ************ -Create an account on VyOS Phabricator_. Phabricator_ is located at -https://phabricator.vyos.net. To create a bug-report use the quick link in the -left side under the specific project. +In order to open up a bug-report/feature request you need to create yourself +an account on VyOS Phabricator_. On the left side of the specific project (VyOS +1.2 or VyOS 1.3) you will find quick-links for opening a bug-report/feature +request. * Provide as much information as you can * Which version of VyOS are you using? ``run show version`` @@ -71,4 +72,5 @@ the left side under the specific project. .. _documentation: https://docs.vyos.io .. _Slack: https://slack.vyos.io .. _Forum: https://forum.vyos.io -.. _Phabricator: https://phabricator.vyos.net \ No newline at end of file + +.. include:: ../common-references.rst \ No newline at end of file diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index 69961f0c..cbb89fbe 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -441,8 +441,8 @@ Options ======= We do not have CLI nodes for every single OpenVPN options. If an option is -missing, a feature request should be opened at https://phabricator.vyos.net so -all users can benefit from it. +missing, a feature request should be opened at Phabricator_ so all users can +benefit from it (see :ref:`issues_features`). If you are a hacker or want to try on your own we support passing raw OpenVPN options to OpenVPN. @@ -460,3 +460,5 @@ Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. .. note:: Sometimes option lines in the generated OpenVPN configurarion require quotes. This is done through a hack on our config generator. You can pass quotes using the ``"`` statement. + +.. include:: ../common-references.rst -- cgit v1.2.3 From ed82d6b00e6ed32b3d056f0623822d61c6c599f6 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 11:10:38 +0100 Subject: issue-feature: use documented section style guide --- docs/contributing/issues-features.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) (limited to 'docs/contributing') diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index e208a3e6..553522a1 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -1,12 +1,14 @@ .. _issues_features: +####################### Issues/Feature requests ======================= .. _bug_report: Bug Report/Issue ----------------- +================ + Issues or bugs are found in any software project. VyOS is not an exception. All issues should be reported to the developers. This lets the developers know @@ -14,7 +16,7 @@ what is not working properly. Without this sort of feedback every developer will believe that everything is working correctly. I have found a bug, what should I do? -************************************* +------------------------------------- When you believe you have found a bug, it is always a good idea to verify the issue prior to opening a bug request. @@ -24,7 +26,7 @@ issue prior to opening a bug request. * Get community support via Slack_ or our Forum_ Ensure the problem is reproducible -********************************** +---------------------------------- When you are able to verify that it is actually a bug, spend some time to document how to reproduce the issue. This documentation can be invaluable. @@ -40,7 +42,7 @@ information can be very useful. * What commands did you use? Use e.g. ``run show configuration commands`` Include output -************** +-------------- The output you get when you find a bug can provide lots of information. If you get an error message on the screen, copy it exactly. Having the exact message @@ -49,7 +51,7 @@ messages that also are from the time of the issue, include those. They may also contain information that is helpful for the development team. Report a Bug -************ +------------ In order to open up a bug-report/feature request you need to create yourself an account on VyOS Phabricator_. On the left side of the specific project (VyOS @@ -60,8 +62,10 @@ request. * Which version of VyOS are you using? ``run show version`` * How can we reproduce this Bug? +.. _feature_request: + Feature Request ---------------- +=============== You have an idea of how to make VyOS better or you are in need of a specific feature which all users of VyOS would benefit from? To send a feature request -- cgit v1.2.3 From 63d79bfbc887f306bca842986b823a1ee38ace13 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sun, 29 Dec 2019 17:13:44 +0100 Subject: issue-feature: fix title overline & underline mismatch --- docs/contributing/issues-features.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/contributing') diff --git a/docs/contributing/issues-features.rst b/docs/contributing/issues-features.rst index 553522a1..1c6563b9 100644 --- a/docs/contributing/issues-features.rst +++ b/docs/contributing/issues-features.rst @@ -2,7 +2,7 @@ ####################### Issues/Feature requests -======================= +####################### .. _bug_report: -- cgit v1.2.3 From 3a8e3b1e9c392b37eebbf1d3927965c4e4e2aa72 Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 13:36:42 +0100 Subject: documentation: split cfgcmd/opcmd description --- docs/contributing/documentation.rst | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) (limited to 'docs/contributing') diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index c639651b..1cf93313 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -147,16 +147,38 @@ system numbers for the documentation: Please don't use other public address space. - Custom Sphinx-doc Markup ^^^^^^^^^^^^^^^^^^^^^^^^ +When writing the cducmentation custom commands have been developed. Please +make yourself comfortable with those commands as this eases the way how we +can render the ducumentation. + +cfgcmd +"""""" + When documenting CLI commands use the ``.. cfgcmd::`` directive for all -configuration mode commands. When documenting operational level command use -the ``.. opcmd::`` directive. An explanation of the described command should -be added below this statement. +configuration mode commands. 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 + + .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa -**Example** + This will configure a static ARP entry always resolving `192.0.2.100` to + `00:53:27:de:23:aa`. + +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 @@ -164,10 +186,7 @@ be added below this statement. Display all known ARP table entries spanning accross all interfaces - .. cfgcmd:: set protocols static arp 192.0.2.100 hwaddr 00:53:27:de:23:aa - This will configure a static ARP entry always resolving `192.0.2.100` to - `00:53:27:de:23:aa`. .. _Sphinx-doc: https://www.sphinx-doc.org .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html -- cgit v1.2.3 From 0567858714bc3306ac09aba2c167268a30e29d2b Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Mon, 30 Dec 2019 13:36:56 +0100 Subject: documentation: add new custom command: vytask --- docs/contributing/documentation.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs/contributing') diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 1cf93313..5714fb00 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -186,6 +186,17 @@ descriptive way in the resulting HTML/PDF manual. Display all known ARP table entries spanning accross all interfaces +vytask +"""""" + +When referencing to VyOS Phabricator Tasks, there is a custom Spinx Markup +command called ``vytask`` which automatically reners 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 .. _Sphinx-doc: https://www.sphinx-doc.org -- cgit v1.2.3 From bd7a52fbcc98ae06568baf1795cd2b7f6ec950a9 Mon Sep 17 00:00:00 2001 From: Ali Date: Tue, 31 Dec 2019 02:18:23 +0330 Subject: documentation: fix contribution guideline typos --- docs/contributing/documentation.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) (limited to 'docs/contributing') diff --git a/docs/contributing/documentation.rst b/docs/contributing/documentation.rst index 5714fb00..2d9f14d1 100644 --- a/docs/contributing/documentation.rst +++ b/docs/contributing/documentation.rst @@ -5,12 +5,12 @@ 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 -benefical four you (when reading something up) but also for the whole world. +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 definate -guid how to do so. +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 +.. 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. @@ -150,9 +150,9 @@ Please don't use other public address space. Custom Sphinx-doc Markup ^^^^^^^^^^^^^^^^^^^^^^^^ -When writing the cducmentation custom commands have been developed. Please -make yourself comfortable with those commands as this eases the way how we -can render the ducumentation. +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 """""" @@ -184,13 +184,13 @@ descriptive way in the resulting HTML/PDF manual. .. opcmd:: show protocols static arp - Display all known ARP table entries spanning accross all interfaces + Display all known ARP table entries spanning across all interfaces vytask """""" When referencing to VyOS Phabricator Tasks, there is a custom Spinx Markup -command called ``vytask`` which automatically reners to a proper Phabricator +command called ``vytask`` which automatically renders to a proper Phabricator URL. This is heavily used in the :ref:`release-notes` section. .. code-block:: none -- cgit v1.2.3