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