Merge pull request #2200 from qlyoung/docuser-gettingstarted

doc: add "Getting Started" section

Makefile.am

@@ -83,7 +83,6 @@ rc_SCRIPTS = \
 endif
 
 EXTRA_DIST += \
-	SERVICES \
 	aclocal.m4 \
 	update-autotools \
 	m4/README.txt \

SERVICES

@@ -1,24 +0,0 @@
-# As long as this software is in alpha testing it is not yet included
-# in /etc/services files. This means that you may need to add the following
-# lines into your /etc/services file on your hosts.
-# 
-# --- Please add this to your /etc/services ---
-
-#
-# GNU Zebra services
-#
-
-zebrasrv	2600/tcp
-zebra		2601/tcp
-ripd		2602/tcp
-ripng		2603/tcp
-ospfd		2604/tcp
-bgpd		2605/tcp
-ospf6d		2606/tcp
-ospfapi		2607/tcp
-isisd		2608/tcp
-babeld		2609/tcp
-nhrpd		2610/tcp
-pimd		2611/tcp
-ldpd		2612/tcp
-eigrpd		2613/tcp

doc/Makefile.am

@@ -198,6 +198,7 @@ EXTRA_DIST = frr-sphinx.mk \
 	user/conf.py \
 	user/eigrpd.rst \
 	user/filter.rst \
+	user/getting-started.rst \
 	user/glossary.rst \
 	user/index.rst \
 	user/installation.rst \
@@ -217,6 +218,7 @@ EXTRA_DIST = frr-sphinx.mk \
 	user/routemap.rst \
 	user/routeserver.rst \
 	user/rpki.rst \
+	user/setup.rst \
 	user/sharp.rst \
 	user/snmp.rst \
 	user/snmptrap.rst \

doc/user/getting-started.rst

@@ -0,0 +1,9 @@
+***************
+Getting Started
+***************
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   setup

doc/user/index.rst

@@ -5,7 +5,7 @@ FRRouting User Guide
    :maxdepth: 2
 
    overview
-   installation
+   getting-started
    basic
    vtysh
    filter

doc/user/installation.rst

@@ -1,8 +1,7 @@
 .. _installation:
 
-************
 Installation
-************
+============
 
 .. index:: How to install FRR
 .. index:: Installation
@@ -10,46 +9,73 @@ Installation
 .. index:: Building the system
 .. index:: Making FRR
 
-Several distributions provide packages for FRR. Check your distribution's
+This section covers the basics of building, installing and setting up FRR.
-repositories to find out if a suitable version is available.
 
-FRR depends on various libraries depending on your operating system.
+From Packages
+-------------
 
-After installing these dependencies, change to the frr source directory and
+The project publishes packages for Red Hat, Centos, Debian and Ubuntu on the
-issue the following commands:
+`GitHub releases <https://github.com/FRRouting/frr/releases>`_. page. External
+contributors offer packages for many other platforms including \*BSD, Alpine,
+Gentoo, Docker, and others. There is currently no documentation on how to use
+those but we hope to add it soon.
 
-::
+From Snapcraft
+--------------
 
-  $ ./bootstrap.sh
+In addition to traditional packages the project also builds and publishes
-  $ ./configure
+universal Snap images, available at https://snapcraft.io/frr.
-  $ make
-  $ make install
 
+From Source
+-----------
 
-.. _configure-the-software:
+Building FRR from source is the best way to ensure you have the latest features
+and bug fixes. Details for each supported platform, including dependency
+package listings, permissions, and other gotchas, are in the developer's
+documentation. This section provides a brief overview on the process.
 
-Configure the Software
+Getting the Source
-======================
+^^^^^^^^^^^^^^^^^^
 
+FRR's source is available on the project
+`GitHub page <https://github.com/FRRouting/frr>`_.
 
-.. _the-configure-script:
+.. code-block:: shell
 
-The Configure Script
+   git clone https://github.com/FRRouting/frr.git
---------------------
+
+When building from Git there are several branches to choose from. The
+``master`` branch is the primary development branch. It should be considered
+unstable. Each release has its own branch named ``stable/X.X``, where ``X.X``
+is the release version.
+
+In addition, release tarballs are published on the GitHub releases page
+`here <https://github.com/FRRouting/frr/releases>`_.
+
+Configuration
+^^^^^^^^^^^^^
 
 .. index:: Configuration options
-
 .. index:: Options for configuring
-
 .. index:: Build options
-
 .. index:: Distribution configuration
-
 .. index:: Options to `./configure`
 
-FRR has an excellent configure script which automatically detects most
+FRR has an excellent configure script which automatically detects most host
-host configurations.  There are several additional configure options to
+configurations. There are several additional configure options to customize the
-customize the build to include or exclude specific features and dependencies.
+build to include or exclude specific features and dependencies.
+
+First, update the build system. Change into your FRR source directory and issue:
+
+.. code-block:: shell
+
+   ./bootstrap.sh
+
+This will install any missing build scripts and update the Autotools
+configuration. Once this is done you can move on to choosing your configuration
+options from the list below.
+
+.. _frr-configuration:
 
 .. program:: configure
 
@@ -202,10 +228,9 @@ options to the configuration script.
 .. _least-privilege-support:
 
 Least-Privilege Support
------------------------
+"""""""""""""""""""""""
 
 .. index:: FRR Least-Privileges
-
 .. index:: FRR Privileges
 
 Additionally, you may configure zebra to drop its elevated privileges
@@ -240,112 +265,54 @@ only Linux), FRR will retain only minimal capabilities required and will only
 raise these capabilities for brief periods. On systems without libcap, FRR will
 run as the user specified and only raise its UID to 0 for brief periods.
 
-.. _linux-notes:
-
 Linux Notes
------------
+"""""""""""
-
-.. index:: Configuring FRR
 
 .. index:: Building on Linux boxes
-
 .. index:: Linux configurations
 
-There are several options available only to GNU/Linux systems [#]_.
+There are several options available only to GNU/Linux systems.  If you use
-If you use GNU/Linux, make sure that the current kernel configuration is what
+GNU/Linux, make sure that the current kernel configuration is what you want.
-you want.  FRR will run with any kernel configuration but some recommendations
+FRR will run with any kernel configuration but some recommendations do exist.
-do exist.
 
+:makevar:`CONFIG_NETLINK`
+   Kernel/User Netlink socket. This is a enables an advanced interface between
+   the Linux kernel and *zebra* (:ref:`kernel-interface`).
 
-- :makevar:`CONFIG_NETLINK`
+:makevar:`CONFIG_RTNETLINK`
-  Kernel/User Netlink socket. This is a brand new feature which enables an
+   This makes it possible to receive Netlink routing messages.  If you specify
-  advanced interface between the Linux kernel and zebra (:ref:`kernel-interface`).
+   this option, *zebra* can detect routing information updates directly from
-- :makevar:`CONFIG_RTNETLINK`
+   the kernel (:ref:`kernel-interface`).
-  Routing messages.
-  This makes it possible to receive Netlink routing messages.  If you
-  specify this option, *zebra* can detect routing information
-  updates directly from the kernel (:ref:`kernel-interface`).
-- :makevar:`CONFIG_IP_MULTICAST`
-  IP: multicasting.
-  This option should be specified when you use *ripd* (:ref:`rip`) or
-  *ospfd* (:ref:`ospfv2`) because these protocols use multicast.
 
-IPv6 support has been added in GNU/Linux kernel version 2.2.  If you
+:makevar:`CONFIG_IP_MULTICAST`
-try to use the FRR IPv6 feature on a GNU/Linux kernel, please
+   This option enables IP multicast and should be specified when you use *ripd*
-make sure the following libraries have been installed.  Please note that
+   (:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
-these libraries will not be needed when you uses GNU C library 2.1
+   multicast.
-or upper.
 
-- inet6-apps
+Building
+^^^^^^^^
 
-  The `inet6-apps` package includes basic IPv6 related libraries such
+Once you have chosen your configure options, run the configure script and pass
-  as `inet_ntop` and `inet_pton`.  Some basic IPv6 programs such
+the options you chose:
-  as *ping*, *ftp*, and *inetd* are also
-  included. The `inet-apps` can be found at
-  `ftp://ftp.inner.net/pub/ipv6/ <ftp://ftp.inner.net/pub/ipv6/>`_.
 
-- net-tools
+.. code-block:: shell
 
-  The `net-tools` package provides an IPv6 enabled interface and routing
+   ./configure \
-  utility.  It contains *ifconfig*, *route*, *netstat*, and other tools.
+       --prefix=/usr \
-  `net-tools` may be found at http://www.tazenda.demon.co.uk/phil/net-tools/.
+       --enable-exampledir=/usr/share/doc/frr/examples/ \
+       --localstatedir=/var/run/frr \
+       --sbindir=/usr/lib/frr \
+       --sysconfdir=/etc/frr \
+       --enable-pimd \
+       --enable-watchfrr \
+       ...
 
-.. _build-the-software:
+After configuring the software, you are ready to build and install it for your
+system.
 
-Build the Software
+.. code-block:: shell
-==================
 
-After configuring the software, you will need to compile it for your system.
+   make && sudo make install
-Simply issue the command *make* in the root of the source directory and the
-software will be compiled. Cliff Notes versions of different compilation
-examples can be found in the Developer's Manual Appendix.  If you have *any*
-problems at this stage, please send a bug report :ref:`bug-reports`.
 
-::
+If everything finishes successfully, FRR should be installed. You should now
-
+skip to the section on :ref:`basic-setup`.
-  $ ./bootstrap.sh
-  $ ./configure <appropriate to your system>
-  $ make
-
-
-Install the Software
-====================
-
-Installing the software to your system consists of copying the compiled
-programs and supporting files to a standard location. After the
-installation process has completed, these files have been copied
-from your work directory to :file:`/usr/local/bin`, and :file:`/usr/local/etc`.
-
-To install the FRR suite, issue the following command at your shell
-prompt:::
-
-  $ make install
-
-FRR daemons have their own terminal interface or VTY.  After
-installation, you have to setup each beast's port number to connect to
-them. Please add the following entries to :file:`/etc/services`.
-
-::
-
-  zebrasrv      2600/tcp		  # zebra service
-  zebra         2601/tcp		  # zebra vty
-  ripd          2602/tcp		  # RIPd vty
-  ripngd        2603/tcp		  # RIPngd vty
-  ospfd         2604/tcp		  # OSPFd vty
-  bgpd          2605/tcp		  # BGPd vty
-  ospf6d        2606/tcp		  # OSPF6d vty
-  ospfapi       2607/tcp		  # ospfapi
-  isisd         2608/tcp		  # ISISd vty
-  nhrpd         2610/tcp		  # nhrpd vty
-  pimd          2611/tcp		  # PIMd vty
-
-
-If you use a FreeBSD newer than 2.2.8, the above entries are already
-added to :file:`/etc/services` so there is no need to add it. If you
-specify a port number when starting the daemon, these entries may not be
-needed.
-
-You may need to make changes to the config files in
-|INSTALL_PREFIX_ETC|. :ref:`config-commands`.
-
-.. [#] GNU/Linux has very flexible kernel configuration features.

doc/user/overview.rst

@@ -20,6 +20,8 @@ can use FRR library as your program's client user interface.
 
 FRR is distributed under the GNU General Public License.
 
+FRR is a fork of `Quagga <http://www.quagga.net/>`_.
+
 .. _about-frr:
 
 About FRR
@@ -235,7 +237,8 @@ How to get FRR
 The official FRR website is located at |PACKAGE_URL| and contains further
 information, as well as links to additional resources.
 
-FRR is a fork of `Quagga <http://www.quagga.net/>`_.
+Several distributions provide packages for FRR. Check your distribution's
+repositories to find out if a suitable version is available.
 
 Mailing Lists
 =============

doc/user/setup.rst

@@ -0,0 +1,155 @@
+.. _basic-setup:
+
+Basic Setup
+============
+
+After installing FRR, some basic configuration must be completed before it is
+ready to use.
+
+Daemons File
+------------
+After a fresh install, starting FRR will do nothing. This is because daemons
+must be explicitly enabled by editing a file in your configuration directory.
+This file is usually located at :file:`/etc/frr/daemons` and determines which
+daemons are activated when issuing a service start / stop command via init or
+systemd. The file initially looks like this:
+
+::
+
+   zebra=no
+   bgpd=no
+   ospfd=no
+   ospf6d=no
+   ripd=no
+   ripngd=no
+   isisd=no
+   pimd=no
+   ldpd=no
+   nhrpd=no
+   eigrpd=no
+   babeld=no
+   sharpd=no
+   pbrd=no
+
+To enable a particular daemon, simply change the corresponding 'no' to 'yes'.
+Subsequent service restarts should start the daemon.
+
+Daemons Configuration File
+--------------------------
+There is another file that controls the default options passed to daemons when
+starting FRR as a service. This file is located in your configuration
+directory, usually at :file:`/etc/frr/daemons.conf`.
+
+This file has several parts. Here is an example:
+
+::
+
+   #
+   # If this option is set the /etc/init.d/frr script automatically loads
+   # the config via "vtysh -b" when the servers are started.
+   # Check /etc/pam.d/frr if you intend to use "vtysh"!
+   #
+   vtysh_enable=yes
+   zebra_options=" -r -s 90000000 --daemon -A 127.0.0.1"
+   bgpd_options="   --daemon -A 127.0.0.1"
+   ospfd_options="  --daemon -A 127.0.0.1"
+   ospf6d_options=" --daemon -A ::1"
+   ripd_options="   --daemon -A 127.0.0.1"
+   ripngd_options=" --daemon -A ::1"
+   isisd_options="  --daemon -A 127.0.0.1"
+   pimd_options="  --daemon -A 127.0.0.1"
+   ldpd_options="  --daemon -A 127.0.0.1"
+   nhrpd_options="  --daemon -A 127.0.0.1"
+   eigrpd_options="  --daemon -A 127.0.0.1"
+   babeld_options="  --daemon -A 127.0.0.1"
+   sharpd_options="  --daemon -A 127.0.0.1"
+   pbrd_options="  --daemon -A 127.0.0.1"
+
+   # The list of daemons to watch is automatically generated by the init script.
+   watchfrr_enable=yes
+   watchfrr_options=(-d -r /usr/sbin/servicebBfrrbBrestartbB%s -s /usr/sbin/servicebBfrrbBstartbB%s -k /usr/sbin/servicebBfrrbBstopbB%s -b bB)
+
+   # If valgrind_enable is 'yes' the frr daemons will be started via valgrind.
+   # The use case for doing so is tracking down memory leaks, etc in frr.
+   valgrind_enable=no
+   valgrind=/usr/bin/valgrind
+
+Breaking this file down:
+
+::
+
+   vtysh_enable=yes
+
+As the comment says, this causes :ref:`VTYSH <vty-shell>` to apply
+configuration when starting the daemons. This is useful for a variety of
+reasons touched on in the VTYSH documentation and should generally be enabled.
+
+::
+
+   zebra_options=" -r -s 90000000 --daemon -A 127.0.0.1"
+   bgpd_options="   --daemon -A 127.0.0.1"
+   ...
+
+The next set of lines controls what options are passed to daemons when started
+from the service script. Usually daemons will have ``--daemon`` and ``-A
+<address>`` specified in order to daemonize and listen for VTY commands on a
+particular address.
+
+::
+
+   # The list of daemons to watch is automatically generated by the init script.
+   watchfrr_enable=yes
+   watchfrr_options=(-d -r /usr/sbin/servicebBfrrbBrestartbB%s -s /usr/sbin/servicebBfrrbBstartbB%s -k /usr/sbin/servicebBfrrbBstopbB%s -b bB)
+
+Options for the ``watchfrr``, the watchdog daemon.
+
+::
+
+   valgrind_enable=no
+   valgrind=/usr/bin/valgrind
+
+Whether or not to start FRR daemons under Valgrind. This is primarily useful
+for gathering information for bug reports and for developers.
+``valgrind_enable`` should be ``no`` for production use.
+
+Services
+--------
+FRR daemons have their own terminal interface or VTY.  After installation, it's
+a good idea to setup each daemon's port number to connect to them. To do this
+add the following entries to :file:`/etc/services`.
+
+::
+
+   zebrasrv      2600/tcp		  # zebra service
+   zebra         2601/tcp		  # zebra vty
+   ripd          2602/tcp		  # RIPd vty
+   ripngd        2603/tcp		  # RIPngd vty
+   ospfd         2604/tcp		  # OSPFd vty
+   bgpd          2605/tcp		  # BGPd vty
+   ospf6d        2606/tcp		  # OSPF6d vty
+   ospfapi       2607/tcp		  # ospfapi
+   isisd         2608/tcp		  # ISISd vty
+   babeld        2609/tcp                 # BABELd vty
+   nhrpd         2610/tcp		  # nhrpd vty
+   pimd          2611/tcp		  # PIMd vty
+   ldpd          2612/tcp                 # LDPd vty
+   eigprd        2613/tcp                 # EIGRPd vty
+
+
+If you use a FreeBSD newer than 2.2.8, the above entries are already added to
+:file:`/etc/services` so there is no need to add it. If you specify a port
+number when starting the daemon, these entries may not be needed.
+
+You may need to make changes to the config files in |INSTALL_PREFIX_ETC|.
+
+systemd
+-------
+Although not installed when installing from source, FRR provides a service file
+for use with ``systemd``. It is located in :file:`tools/frr.service` in the Git
+repository. If ``systemctl status frr.service`` indicates that the FRR service
+is not found, copy the service file from the Git repository into your preferred
+location. A good place is usually ``/etc/systemd/system/``.
+
+After issuing a ``systemctl daemon-reload``, you should be able to start the
+FRR service via ``systemctl start frr``. If this fails, or no daemons are
+started. check the ``journalctl`` logs for an indication of what went wrong.

redhat/frr.spec.in

@@ -534,7 +534,7 @@ rm -rf %{buildroot}
 %defattr(-,root,root)
 %doc */*.sample* AUTHORS COPYING
 %doc doc/mpls
-%doc ChangeLog NEWS README SERVICES
+%doc ChangeLog NEWS README
 %if 0%{?frr_user:1}
 %dir %attr(751,%frr_user,%frr_user) %{_sysconfdir}
 %dir %attr(750,%frr_user,%frr_user) /var/log/frr