doc/user/setup.rst

   1 .. _basic-setup:
   2
   3 Basic Setup
   4 ============
   5
   6 After installing FRR, some basic configuration must be completed before it is
   7 ready to use.
   8
   9 Daemons File
  10 ------------
  11 After a fresh install, starting FRR will do nothing. This is because daemons
  12 must be explicitly enabled by editing a file in your configuration directory.
  13 This file is usually located at :file:`/etc/frr/daemons` and determines which
  14 daemons are activated when issuing a service start / stop command via init or
  15 systemd. The file initially looks like this:
  16
  17 ::
  18
  19    zebra=no
  20    bgpd=no
  21    ospfd=no
  22    ospf6d=no
  23    ripd=no
  24    ripngd=no
  25    isisd=no
  26    pimd=no
  27    ldpd=no
  28    nhrpd=no
  29    eigrpd=no
  30    babeld=no
  31    sharpd=no
  32    staticd=no
  33    pbrd=no
  34    bfdd=no
  35    fabricd=no
  36
  37 To enable a particular daemon, simply change the corresponding 'no' to 'yes'.
  38 Subsequent service restarts should start the daemon.
  39
  40 Daemons Configuration File
  41 --------------------------
  42 There is another file that controls the default options passed to daemons when
  43 starting FRR as a service. This file is located in your configuration
  44 directory, usually at :file:`/etc/frr/daemons`.
  45
  46 This file has several parts. Here is an example:
  47
  48 ::
  49
  50    #
  51    # If this option is set the /etc/init.d/frr script automatically loads
  52    # the config via "vtysh -b" when the servers are started.
  53    # Check /etc/pam.d/frr if you intend to use "vtysh"!
  54    #
  55    vtysh_enable=yes
  56    zebra_options=" -s 90000000 --daemon -A 127.0.0.1"
  57    bgpd_options="   --daemon -A 127.0.0.1"
  58    ospfd_options="  --daemon -A 127.0.0.1"
  59    ospf6d_options=" --daemon -A ::1"
  60    ripd_options="   --daemon -A 127.0.0.1"
  61    ripngd_options=" --daemon -A ::1"
  62    isisd_options="  --daemon -A 127.0.0.1"
  63    pimd_options="  --daemon -A 127.0.0.1"
  64    ldpd_options="  --daemon -A 127.0.0.1"
  65    nhrpd_options="  --daemon -A 127.0.0.1"
  66    eigrpd_options="  --daemon -A 127.0.0.1"
  67    babeld_options="  --daemon -A 127.0.0.1"
  68    sharpd_options="  --daemon -A 127.0.0.1"
  69    staticd_options="  --daemon -A 127.0.0.1"
  70    pbrd_options="  --daemon -A 127.0.0.1"
  71    bfdd_options="  --daemon -A 127.0.0.1"
  72    fabricd_options="  --daemon -A 127.0.0.1"
  73
  74    # The list of daemons to watch is automatically generated by the init script.
  75    watchfrr_enable=yes
  76    watchfrr_options=(-d -r /usr/sbin/servicebBfrrbBrestartbB%s -s /usr/sbin/servicebBfrrbBstartbB%s -k /usr/sbin/servicebBfrrbBstopbB%s -b bB)
  77
  78    # If valgrind_enable is 'yes' the frr daemons will be started via valgrind.
  79    # The use case for doing so is tracking down memory leaks, etc in frr.
  80    valgrind_enable=no
  81    valgrind=/usr/bin/valgrind
  82
  83 Breaking this file down:
  84
  85 ::
  86
  87    vtysh_enable=yes
  88
  89 As the comment says, this causes :ref:`VTYSH <vty-shell>` to apply
  90 configuration when starting the daemons. This is useful for a variety of
  91 reasons touched on in the VTYSH documentation and should generally be enabled.
  92
  93 ::
  94
  95    zebra_options=" -s 90000000 --daemon -A 127.0.0.1"
  96    bgpd_options="   --daemon -A 127.0.0.1"
  97    ...
  98
  99 The next set of lines controls what options are passed to daemons when started
 100 from the service script. Usually daemons will have ``--daemon`` and ``-A
 101 <address>`` specified in order to daemonize and listen for VTY commands on a
 102 particular address.
 103
 104 ::
 105
 106    # The list of daemons to watch is automatically generated by the init script.
 107    watchfrr_enable=yes
 108    watchfrr_options=(-d -r /usr/sbin/servicebBfrrbBrestartbB%s -s /usr/sbin/servicebBfrrbBstartbB%s -k /usr/sbin/servicebBfrrbBstopbB%s -b bB)
 109
 110 Options for the ``watchfrr``, the watchdog daemon.
 111
 112 ::
 113
 114    valgrind_enable=no
 115    valgrind=/usr/bin/valgrind
 116
 117 Whether or not to start FRR daemons under Valgrind. This is primarily useful
 118 for gathering information for bug reports and for developers.
 119 ``valgrind_enable`` should be ``no`` for production use.
 120
 121 Services
 122 --------
 123 FRR daemons have their own terminal interface or VTY.  After installation, it's
 124 a good idea to setup each daemon's port number to connect to them. To do this
 125 add the following entries to :file:`/etc/services`.
 126
 127 ::
 128
 129    zebrasrv      2600/tcp                 # zebra service
 130    zebra         2601/tcp                 # zebra vty
 131    ripd          2602/tcp                 # RIPd vty
 132    ripngd        2603/tcp                 # RIPngd vty
 133    ospfd         2604/tcp                 # OSPFd vty
 134    bgpd          2605/tcp                 # BGPd vty
 135    ospf6d        2606/tcp                 # OSPF6d vty
 136    ospfapi       2607/tcp                 # ospfapi
 137    isisd         2608/tcp                 # ISISd vty
 138    babeld        2609/tcp                 # BABELd vty
 139    nhrpd         2610/tcp                 # nhrpd vty
 140    pimd          2611/tcp                 # PIMd vty
 141    ldpd          2612/tcp                 # LDPd vty
 142    eigprd        2613/tcp                 # EIGRPd vty
 143    bfdd          2617/tcp                 # bfdd vty
 144    fabricd       2618/tcp                 # fabricd vty
 145
 146
 147 If you use a FreeBSD newer than 2.2.8, the above entries are already added to
 148 :file:`/etc/services` so there is no need to add it. If you specify a port
 149 number when starting the daemon, these entries may not be needed.
 150
 151 You may need to make changes to the config files in |INSTALL_PREFIX_ETC|.
 152
 153 systemd
 154 -------
 155 Although not installed when installing from source, FRR provides a service file
 156 for use with ``systemd``. It is located in :file:`tools/frr.service` in the Git
 157 repository. If ``systemctl status frr.service`` indicates that the FRR service
 158 is not found, copy the service file from the Git repository into your preferred
 159 location. A good place is usually ``/etc/systemd/system/``.
 160
 161 After issuing a ``systemctl daemon-reload``, you should be able to start the
 162 FRR service via ``systemctl start frr``. If this fails, or no daemons are
 163 started. check the ``journalctl`` logs for an indication of what went wrong.