diff options
Diffstat (limited to 'doc/developer')
| -rw-r--r-- | doc/developer/building-frr-on-lede-openwrt.rst | 10 | ||||
| -rw-r--r-- | doc/developer/building-frr-on-ubuntu1204.rst | 187 | ||||
| -rw-r--r-- | doc/developer/building.rst | 1 | ||||
| -rw-r--r-- | doc/developer/maintainer-release-build.rst | 2 | ||||
| -rw-r--r-- | doc/developer/packaging-debian.rst | 233 | ||||
| -rw-r--r-- | doc/developer/subdir.am | 3 |
6 files changed, 114 insertions, 322 deletions
diff --git a/doc/developer/building-frr-on-lede-openwrt.rst b/doc/developer/building-frr-on-lede-openwrt.rst index d14754b37f..039351c7f9 100644 --- a/doc/developer/building-frr-on-lede-openwrt.rst +++ b/doc/developer/building-frr-on-lede-openwrt.rst @@ -13,15 +13,7 @@ https://lede-project.org/docs/guide-developer/install-buildsystem for -Ubuntu 12.04LTS: - -:: - - sudo apt-get install build-essential subversion git-core \ - libncurses5-dev zlib1g-dev gawk flex quilt libssl-dev xsltproc \ - libxml-parser-perl mercurial bzr ecj cvs unzip python3-sphinx - -Ubuntu 64bit: +Ubuntu: :: diff --git a/doc/developer/building-frr-on-ubuntu1204.rst b/doc/developer/building-frr-on-ubuntu1204.rst deleted file mode 100644 index dad115acd8..0000000000 --- a/doc/developer/building-frr-on-ubuntu1204.rst +++ /dev/null @@ -1,187 +0,0 @@ -Ubuntu 12.04LTS -=============================================== - -- MPLS is not supported on ``Ubuntu 12.04`` with default kernel. MPLS - requires Linux Kernel 4.5 or higher (LDP can be built, but may have - limited use without MPLS) For an updated Ubuntu Kernel, see - http://kernel.ubuntu.com/~kernel-ppa/mainline/ - -Install required packages -------------------------- - -Add packages: - -:: - - apt-get install \ - git autoconf automake libtool make gawk libreadline-dev texinfo \ - dejagnu pkg-config libpam0g-dev libjson0-dev flex python-pip \ - libc-ares-dev python3-dev python3-sphinx install-info - -Install newer bison from 14.04 package source (Ubuntu 12.04 package -source is too old) - -:: - - mkdir builddir - cd builddir - wget http://archive.ubuntu.com/ubuntu/pool/main/b/bison/bison_3.0.2.dfsg-2.dsc - wget http://archive.ubuntu.com/ubuntu/pool/main/b/bison/bison_3.0.2.dfsg.orig.tar.bz2 - wget http://archive.ubuntu.com/ubuntu/pool/main/b/bison/bison_3.0.2.dfsg-2.debian.tar.gz - tar -jxvf bison_3.0.2.dfsg.orig.tar.bz2 - cd bison-3.0.2.dfsg/ - tar xzf ../bison_3.0.2.dfsg-2.debian.tar.gz - sudo apt-get build-dep bison - debuild -b -uc -us - cd .. - sudo dpkg -i ./libbison-dev_3.0.2.dfsg-2_amd64.deb ./bison_3.0.2.dfsg-2_amd64.deb - cd .. - rm -rf builddir - -Install newer version of autoconf and automake: - -:: - - wget http://ftp.gnu.org/gnu/autoconf/autoconf-2.69.tar.gz - tar xvf autoconf-2.69.tar.gz - cd autoconf-2.69 - ./configure --prefix=/usr - make - sudo make install - cd .. - - wget http://ftp.gnu.org/gnu/automake/automake-1.15.tar.gz - tar xvf automake-1.15.tar.gz - cd automake-1.15 - ./configure --prefix=/usr - make - sudo make install - cd .. - -Install pytest: - -:: - - pip install pytest - -Get FRR, compile it and install it (from Git) ---------------------------------------------- - -**This assumes you want to build and install FRR from source and not -using any packages** - -Add frr groups and user -^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - sudo groupadd -r -g 92 frr - sudo groupadd -r -g 85 frrvty - sudo adduser --system --ingroup frr --home /var/run/frr/ \ - --gecos "FRR suite" --shell /sbin/nologin frr - sudo usermod -a -G frrvty frr - -Download Source, configure and compile it -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -(You may prefer different options on configure statement. These are just -an example.) - -:: - - git clone https://github.com/frrouting/frr.git frr - cd frr - ./bootstrap.sh - ./configure \ - --prefix=/usr \ - --enable-exampledir=/usr/share/doc/frr/examples/ \ - --localstatedir=/var/run/frr \ - --sbindir=/usr/lib/frr \ - --sysconfdir=/etc/frr \ - --enable-pimd \ - --enable-watchfrr \ - --enable-ospfclient=yes \ - --enable-ospfapi=yes \ - --enable-multipath=64 \ - --enable-user=frr \ - --enable-group=frr \ - --enable-vty-group=frrvty \ - --enable-configfile-mask=0640 \ - --enable-logfile-mask=0640 \ - --enable-rtadv \ - --enable-fpm \ - --with-pkg-git-version \ - --with-pkg-extra-version=-MyOwnFRRVersion - make - make check - sudo make install - -Create empty FRR configuration files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - sudo install -m 755 -o frr -g frr -d /var/log/frr - sudo install -m 775 -o frr -g frrvty -d /etc/frr - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/zebra.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/bgpd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ospfd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ospf6d.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/isisd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ripd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ripngd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/pimd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/ldpd.conf - sudo install -m 640 -o frr -g frr /dev/null /etc/frr/nhrpd.conf - sudo install -m 640 -o frr -g frrvty /dev/null /etc/frr/vtysh.conf - -Enable IP & IPv6 forwarding -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Edit ``/etc/sysctl.conf`` and uncomment the following values (ignore the -other settings) - -:: - - # Uncomment the next line to enable packet forwarding for IPv4 - net.ipv4.ip_forward=1 - - # Uncomment the next line to enable packet forwarding for IPv6 - # Enabling this option disables Stateless Address Autoconfiguration - # based on Router Advertisements for this host - net.ipv6.conf.all.forwarding=1 - -**Reboot** or use ``sysctl -p`` to apply the same config to the running -system - -Install the init.d service -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -:: - - sudo install -m 755 tools/frr /etc/init.d/frr - sudo install -m 644 tools/etc/frr/daemons /etc/frr/daemons - sudo install -m 644 -o frr -g frr tools/etc/frr/vtysh.conf /etc/frr/vtysh.conf - -Enable daemons -^^^^^^^^^^^^^^ - -| Edit ``/etc/frr/daemons`` and change the value from "no" to "yes" for - those daemons you want to start by systemd. -| For example. - -:: - - zebra=yes - bgpd=yes - ospfd=yes - ospf6d=yes - ripd=yes - ripngd=yes - isisd=yes - -Start the init.d service -^^^^^^^^^^^^^^^^^^^^^^^^ - -- /etc/init.d/frr start -- use ``/etc/init.d/frr status`` to check its status. diff --git a/doc/developer/building.rst b/doc/developer/building.rst index 051611a65d..c94b2a67aa 100644 --- a/doc/developer/building.rst +++ b/doc/developer/building.rst @@ -21,7 +21,6 @@ Building FRR building-frr-on-netbsd7 building-frr-on-omnios building-frr-on-openbsd6 - building-frr-on-ubuntu1204 building-frr-on-ubuntu1404 building-frr-on-ubuntu1604 building-frr-on-ubuntu1804 diff --git a/doc/developer/maintainer-release-build.rst b/doc/developer/maintainer-release-build.rst index 907bd14ee6..1925ae5d4b 100644 --- a/doc/developer/maintainer-release-build.rst +++ b/doc/developer/maintainer-release-build.rst @@ -37,7 +37,7 @@ Release Build Procedure for FRR maintainers 4. Update Changelog for Debian Packages: - Edit :file:`debianpkg/changelog.in`: + Edit :file:`debian/changelog-auto.in`: - Change last (top of list) entry from ``@VERSION@`` to previous fixed version number, i.e.:: diff --git a/doc/developer/packaging-debian.rst b/doc/developer/packaging-debian.rst index 4ea784c0fc..55e35c332f 100644 --- a/doc/developer/packaging-debian.rst +++ b/doc/developer/packaging-debian.rst @@ -1,31 +1,26 @@ Debian ====== -(Tested on Ubuntu 12.04, 14.04, 16.04, 17.10, 18.04, Debian 8 and 9) +(Tested on Ubuntu 14.04, 16.04, 17.10, 18.04, Debian jessie, stretch and +buster.) -.. note:: - - If you try to build for a different distro, then it will most likely fail - because of the missing backport. See :ref:`deb-backports` about adding a new - backport. - -1. Install build dependencies for your platform as outlined in :ref:`building`. - -2. Install the following additional packages: - - - on Ubuntu 12.04, 14.04, 16.04, 17.10, Debian 8 and 9: +1. Install the Debian packaging tools: .. code-block:: shell - apt-get install realpath equivs groff fakeroot debhelper devscripts + sudo apt install fakeroot debhelper devscripts - - on Ubuntu 18.04: (realpath is now part of preinstalled by coreutils) +2. Install build dependencies using the `mk-build-deps` tool from the + `devscripts` package: .. code-block:: shell - apt-get install equivs groff fakeroot debhelper devscripts + sudo mk-build-deps --install debianpkg/control + + Alternatively, you can manually install build dependencies for your + platform as outlined in :ref:`building`. -3. Checkout FRR under a **unprivileged** user account: +3. Checkout FRR under an **unprivileged** user account: .. code-block:: shell @@ -38,143 +33,135 @@ Debian git checkout <branch> -4. Run ``bootstrap.sh`` and make a dist tarball: +4. Run ``tools/tarsource.sh -V``: .. code-block:: shell - ./bootstrap.sh - ./configure --with-pkg-extra-version=-MyDebPkgVersion - make dist - - .. note:: - - Configure parameters are not important for the Debian Package building - - except the `with-pkg-extra-version` if you want to give the Debian - package a specific name to mark your own unoffical build. + ./tools/tarsource.sh -V -5. Edit :file:`debianpkg/rules` and set the configuration as needed. + This script sets up the ``debian/changelog-auto`` file with proper version + information. - Look for section ``dh_auto_configure`` to modify the configure options as - needed. Options might be different between the top-level ``rules``` and - :file:`backports/XXXX/debian/rules`. Please adjust as needed on all files. +5. (optional) Append a distribution identifier if needed (see below under + :ref:`multi-dist`.) -6. Create backports debian sources - - Rename the :file:`debianpkg` directory to :file:`debian` and create the - backports (Debian requires to not ship a :file:`debian` directory inside the - source directory to avoid build conflicts with the reserved ``debian`` - subdirectory name during the build): +6. Build Debian Package: .. code-block:: shell - mv debianpkg debian - make -f debian/rules backports - - This will create a :file:`frr_*.orig.tar.gz` with the source (same as the - dist tarball), as well as multiple :file:`frr_*.debian.tar.xz` and - :file:`frr_*.dsc` corresponding to each distribution for which a backport is - available. - -7. Create a new directory to build the package and populate with package - source. - - .. code-block:: shell + dpkg-buildpackage $options - mkdir frrpkg - cd frrpkg - tar xf ~/frr/frr_*.orig.tar.gz - cd frr* - . /etc/os-release - tar xf ~/frr/frr_*${ID}${VERSION_ID}*.debian.tar.xz + Where `$options` may contain any or all of the following items: -8. Build Debian package dependencies and install them as needed. + * build profiles specified with ``-P``, e.g. + ``-Ppkg.frr.nortrlib,pkg.frr.nosystemd``. + Multiple values are separated by commas and there must not be a space + after the ``-P``. - .. code-block:: shell + The following build profiles are currently available: - sudo mk-build-deps --install debian/control + +----------------+-------------------+-----------------------------------------+ + | Profile | Negation | Effect | + +================+===================+=========================================+ + | pkg.frr.rtrlib | pkg.frr.nortrlib | builds frr-rpki-rtrlib package (or not) | + +----------------+-------------------+-----------------------------------------+ + | n/a | pkg.frr.nosystemd | removes libsystemd dependency and | + | | | disables unit file installation | + +----------------+-------------------+-----------------------------------------+ -9. Build Debian Package + .. note:: - Building with standard options: + The ``pkg.frr.nosystemd`` option is only intended to support Ubuntu + 14.04 (and should be enabled when building for that.) - .. code-block:: shell + * the ``-uc -us`` options to disable signing the packages with your GPG key - debuild -b -uc -us + (git builds of the `master` or `stable/X.X` branches won't be signed by + default since their target release is set to ``UNRELEASED``.) - Or change some options (see `rules` file for available options): +7. Done! - .. code-block:: shell + If all worked correctly, then you should end up with the Debian packages in + the parent directory of where `debuild` ran. If distributed, please make sure + you distribute it together with the sources (``frr_*.orig.tar.xz``, + ``frr_*.debian.tar.xz`` and ``frr_*.dsc``) - debuild --set-envvar=WANT_BGP_VNC=1 --set-envvar=WANT_CUMULUS_MODE=1 -b -uc -us - - To build with RPKI: - - - Download the librtr packages from - https://ci1.netdef.org/browse/RPKI-RTRLIB/latestSuccessful/artifact - - - install librtr-dev on the build server - - Then build with: +.. note:: - .. code-block:: shell + A package created from `master` or `stable/X.X` is slightly different from + a package created from the `debian` branch. The changelog for the former + is autogenerated and sets the Debian revision to ``-0``, which causes an + intentional lintian warning. The `debian` branch on the other hand has + a manually maintained changelog that contains proper Debian release + versioning. - debuild --set-envvar=WANT_RPKI=1 -b -uc -us + Furthermore, official Debian packages are built in ``3.0 (quilt)`` format + with an "orig" tarball and a "debian" tarball. These tarballs are created + by the ``tarsource.sh`` tool on any branch. The git repository however + contains a ``3.0 (git)`` source format specifier to easily allow direct + git builds. - RPKI packages have an additonal dependency of ``librtr0`` which can be found - at the same URL. -10. Done! +.. _multi-dist: -If all worked correctly, then you should end up with the Debian packages under -:file:`frrpkg`. If distributed, please make sure you distribute it together -with the sources (``frr_*.orig.tar.gz``, ``frr_*.debian.tar.xz`` and -``frr_*.dsc``) +Multi-Distribution builds +========================= -The build procedure can also be executed automatically using the ``tools/build-debian-package.sh`` -script. For example: +You can optionally append a distribution identifier in case you want to +make multiple versions of the package available in the same repository. +Do the following after creating the changelog with `tarsource.sh`: .. code-block:: shell - EXTRA_VERSION="-myversion" WANT_SNMP=1 WANT_CUMULUS_MODE=1 tools/build-debian-package.sh - -.. _deb-backports: - -Debian Backports ----------------- + dch -l '~deb8u' 'build for Debian 8 (jessie)' + dch -l '~deb9u' 'build for Debian 9 (stretch)' + dch -l '~ubuntu14.04.' 'build for Ubuntu 14.04 (trusty)' + dch -l '~ubuntu16.04.' 'build for Ubuntu 16.04 (xenial)' + dch -l '~ubuntu18.04.' 'build for Ubuntu 18.04 (bionic)' + +Between building packages for specific distributions, the only difference +in the package itself lies in the automatically generated shared library +dependencies, e.g. libjson-c2 or libjson-c3. This means that the +architecture independent packages should **not** have a suffix appended. +Also, the current Debian testing/unstable releases should not have any suffix +appended. + +For example, at the end of 2018 (i.e. ``buster``/Debian 10 is the current +"testing" release), the following is a complete list of `.deb` files for +Debian 8, 9 and 10 packages for FRR 6.0.1-1 with RPKI support:: + + frr_6.0.1-1_amd64.deb + frr_6.0.1-1~deb8u1_amd64.deb + frr_6.0.1-1~deb9u1_amd64.deb + frr-dbg_6.0.1-1_amd64.deb + frr-dbg_6.0.1-1~deb8u1_amd64.deb + frr-dbg_6.0.1-1~deb9u1_amd64.deb + frr-rpki-rtrlib_6.0.1-1_amd64.deb + frr-rpki-rtrlib_6.0.1-1~deb8u1_amd64.deb + frr-rpki-rtrlib_6.0.1-1~deb9u1_amd64.deb + frr-doc_6.0.1-1_all.deb + frr-pythontools_6.0.1-1_all.deb + +Note that there are no extra versions of the `frr-doc` and `frr-pythontools` +packages (because they are for architecture ``all``, not ``amd64``), and the +version for Debian 10 does **not** have a ``~deb10u1`` suffix. + +.. warning:: + + Do not use the ``-`` character in the version suffix. The last ``-`` in + the version number is the separator between upstream version and Debian + version. ``6.0.1-1~foobar-2`` means upstream version ``6.0.1-1~foobar``, + Debian version ``2``. This is not what you want. + + The only allowed characters in the Debian version are ``0-9 A-Z a-z + . ~`` -The :file:`debianpkg/backports` directory contains the Debian directories for -backports to other Debian platforms. These are built via the ``3.0 (custom)`` -source format, which allows one to build a source package directly out of -tarballs (e.g. an orig.tar.gz tarball and a debian.tar.gz file), at which point -the format can be changed to a real format (e.g. ``3.0 (quilt)``). - -Source packages are assembled via targets of the same name as the system to -which the backport is done (e.g. ``precise``), included in :file:`debian/rules`. - -To create a new Debian backport: - -- Add its name to ``KNOWN_BACKPORTS``, defined in :file:`debian/rules`. -- Create a directory of the same name in :file:`debian/backports`. -- Add the files ``exclude``, ``versionext``, and ``debian/source/format`` under - this directory. - -For the last point, these files should contain the following: - -``exclude`` - Contains whitespace-separated paths (relative to the root of the source dir) - that should be excluded from the source package (e.g. - :file:`debian/patches`). - -``versionext`` - Contains the suffix added to the version number for this backport's build. - Distributions often have guidelines for what this should be. If left empty, - no new :file:`debian/changelog` entry is created. +.. note:: -``debian/source/format`` - Contains the source format of the resulting source package. As of of the - writing of this document the only supported format is ``3.0 (quilt)``. + The separating character for the suffix **must** be the tilde (``~``) + because the tilde is ordered in version-comparison before the empty + string. That means the order of the above packages is the following: -- Add appropriate files under the :file:`debian/` subdirectory. These will be - included in the source package, overriding any top-level :file:`debian/` - files with equivalent paths. + ``6.0.1-1`` newer than ``6.0.1-1~deb9u1`` newer than ``6.0.1-1~deb8u1`` + If you use another character (e.g. ``+``), the untagged version will be + regarded as the "oldest"! diff --git a/doc/developer/subdir.am b/doc/developer/subdir.am index f06451f4cc..b9fcf9e0a5 100644 --- a/doc/developer/subdir.am +++ b/doc/developer/subdir.am @@ -19,7 +19,6 @@ dev_RSTFILES = \ doc/developer/building-frr-on-netbsd7.rst \ doc/developer/building-frr-on-omnios.rst \ doc/developer/building-frr-on-openbsd6.rst \ - doc/developer/building-frr-on-ubuntu1204.rst \ doc/developer/building-frr-on-ubuntu1404.rst \ doc/developer/building-frr-on-ubuntu1604.rst \ doc/developer/building-frr-on-ubuntu1804.rst \ @@ -37,6 +36,8 @@ dev_RSTFILES = \ doc/developer/ospf-api.rst \ doc/developer/ospf-sr.rst \ doc/developer/ospf.rst \ + doc/developer/packaging.rst \ + doc/developer/packaging-debian.rst \ doc/developer/workflow.rst \ doc/developer/zebra.rst \ # end |