proxmox-mirrors/mirror_frr
1
0
Fork 0
mirror of https://git.proxmox.com/git/mirror_frr synced 2025-08-03 11:01:48 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Merge pull request #2200 from qlyoung/docuser-gettingstarted

Browse Source 
doc: add "Getting Started" section
This commit is contained in:
Rafael Zalamena 2018-05-16 18:24:36 -03:00 committed by GitHub
commit 7bed0c42d5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 259 additions and 148 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
Makefile.am
View File

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

24
SERVICES
View File

@ -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

2
doc/Makefile.am
View File

@ -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 \

9
doc/user/getting-started.rst Normal file
View File

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

2
doc/user/index.rst
View File

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

207
doc/user/installation.rst
View File

@ -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
repositories to find out if a suitable version is available.
This section covers the basics of building, installing and setting up FRR.
FRR depends on various libraries depending on your operating system.
From Packages
-------------
After installing these dependencies, change to the frr source directory and
issue the following commands:
The project publishes packages for Red Hat, Centos, Debian and Ubuntu on the
`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
$ ./configure
$ make
$ make install
In addition to traditional packages the project also builds and publishes
universal Snap images, available at https://snapcraft.io/frr.
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
host configurations. There are several additional configure options to
customize the build to include or exclude specific features and dependencies.
FRR has an excellent configure script which automatically detects most host
configurations. There are several additional configure options to customize the
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 [#]_.
If you use GNU/Linux, make sure that the current kernel configuration is what
you want. FRR will run with any kernel configuration but some recommendations
do exist.
There are several options available only to GNU/Linux systems. If you use
GNU/Linux, make sure that the current kernel configuration is what you want.
FRR will run with any kernel configuration but some recommendations 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`
Kernel/User Netlink socket. This is a brand new feature which enables an
advanced interface between the Linux kernel and zebra (:ref:`kernel-interface`).
- :makevar:`CONFIG_RTNETLINK`
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.
:makevar:`CONFIG_RTNETLINK`
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`).
IPv6 support has been added in GNU/Linux kernel version 2.2. If you
try to use the FRR IPv6 feature on a GNU/Linux kernel, please
make sure the following libraries have been installed. Please note that
these libraries will not be needed when you uses GNU C library 2.1
or upper.
:makevar:`CONFIG_IP_MULTICAST`
This option enables IP multicast and should be specified when you use *ripd*
(:ref:`rip`) or *ospfd* (:ref:`ospfv2`) because these protocols use
multicast.
- inet6-apps
Building
^^^^^^^^
The `inet6-apps` package includes basic IPv6 related libraries such
as `inet_ntop` and `inet_pton`. Some basic IPv6 programs such
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/>`_.
Once you have chosen your configure options, run the configure script and pass
the options you chose:
- net-tools
.. code-block:: shell
The `net-tools` package provides an IPv6 enabled interface and routing
utility. It contains *ifconfig*, *route*, *netstat*, and other tools.
`net-tools` may be found at http://www.tazenda.demon.co.uk/phil/net-tools/.
./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 \
...
.. _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.
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`.
make && sudo make install
::
$ ./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.
If everything finishes successfully, FRR should be installed. You should now
skip to the section on :ref:`basic-setup`.

5
doc/user/overview.rst
View File

@ -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
=============

155
doc/user/setup.rst Normal file
View File

@ -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.

2
redhat/frr.spec.in
View File

@ -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