[mirror_frr.git] / doc / user / setup.rst

.. _basic-setup:

Basic Setup
============

After installing FRR, some basic configuration must be completed before it is
ready to use.

Crash logs
----------

If any daemon should crash for some reason (segmentation fault, assertion
failure, etc.), it will attempt to write a backtrace to a file located in
:file:`/var/tmp/frr/<daemon>[-<instance>].<pid>/crashlog`.  This feature is
not affected by any configuration options.

The crashlog file's directory also contains files corresponding to per-thread
message buffers in files named
:file:`/var/tmp/frr/<daemon>[-<instance>].<pid>/logbuf.<tid>`.  In case of a
crash, these may contain unwritten buffered log messages.  To show the contents
of these buffers, pipe their contents through ``tr '\0' '\n'``.  A blank line
marks the end of valid unwritten data (it will generally be followed by
garbled, older log messages since the buffer is not cleared.)

.. _daemons-configuration-file:

Daemons Configuration 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
   staticd=no
   pbrd=no
   bfdd=no
   fabricd=no

   #
   # 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=" -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"
   staticd_options="  --daemon -A 127.0.0.1"
   pbrd_options="  --daemon -A 127.0.0.1"
   bfdd_options="  --daemon -A 127.0.0.1"
   fabricd_options="  --daemon -A 127.0.0.1"

   #MAX_FDS=1024
   # The list of daemons to watch is automatically generated by the init script.
   #watchfrr_options=""

   # for debugging purposes, you can specify a "wrap" command to start instead
   # of starting the daemon directly, e.g. to use valgrind on ospfd:
   #   ospfd_wrap="/usr/bin/valgrind"
   # or you can use "all_wrap" for all daemons, e.g. to use perf record:
   #   all_wrap="/usr/bin/perf record --call-graph -"
   # the normal daemon command is added to this at the end.

Breaking this file down:

::

   bgpd=yes

To enable a particular daemon, simply change the corresponding 'no' to 'yes'.
Subsequent service restarts should start the daemon.

::

   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.

::

   MAX_FDS=1024

This allows the operator to control the number of open file descriptors
each daemon is allowed to start with.  The current assumed value on
most operating systems is 1024.  If the operator plans to run bgp with
several thousands of peers then this is where we would modify FRR to
allow this to happen.

::

  FRR_NO_ROOT="yes"

This option allows you to run FRR as a non-root user. Use this option
only when you know what you are doing since most of the daemons
in FRR will not be able to run under a regular user. This option
is useful for example when you run FRR in a container with a designated
user instead of root.

::

   zebra_options=" -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 remaining file content regarding `watchfrr_options` and `*_wrap` settings
should not normally be needed;  refer to the comments in case they are.

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
   bfdd          2617/tcp                 # bfdd vty
   fabricd       2618/tcp                 # fabricd vty
   vrrpd         2619/tcp                 # vrrpd 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.

Operations
----------

This section covers a few common operational tasks and how to perform them.

Interactive Shell
^^^^^^^^^^^^^^^^^
FRR offers an IOS-like interactive shell called ``vtysh`` where a user can run
individual configuration or show commands. To get into this shell, issue the
``vtysh`` command from either a privilege user (root, or with sudo) or a user
account that is part of the ``frrvty`` group.
e.g.

.. code-block:: console

   root@ub18:~# vtysh

   Hello, this is FRRouting (version 8.1-dev).
   Copyright 1996-2005 Kunihiro Ishiguro, et al.

   ub18#

.. note::
   The default install location for vtysh is /usr/bin/vtysh


Restarting
^^^^^^^^^^

Restarting kills all running FRR daemons and starts them again. Any unsaved
configuration will be lost.

.. code-block:: console

   service frr restart

.. note::

   Alternatively, you can invoke the init script directly::

      /etc/init.d/frr restart

   Or, if using systemd::

      systemctl restart frr

Reloading
^^^^^^^^^

Reloading applies the differential between on-disk configuration and the
current effective configuration of running FRR processes. This includes
starting daemons that were previously stopped and any changes made to
individual or unified daemon configuration files.

.. code-block:: console

   service frr reload

.. note::

   Alternatively, you can invoke the init script directly::

      /etc/init.d/frr reload

   Or, if using systemd::

      systemctl reload frr

See :ref:`FRR-RELOAD <frr-reload>` for more about the `frr-reload.py` script.


Starting a new daemon
^^^^^^^^^^^^^^^^^^^^^

Suppose *bgpd* and *zebra* are running, and you wish to start *pimd*. In
``/etc/frr/daemons`` make the following change:

.. code-block:: diff

   - pimd=no
   + pimd=yes

Then perform a reload.

Currently there is no way to stop or restart an individual daemon. This is
because FRR's monitoring program cannot currently distinguish between a crashed
/ killed daemon versus one that has been intentionally stopped or restarted.
The closest that can be achieved is to remove all configuration for the daemon,
and set its line in ``/etc/frr/daemons`` to ``=no``. Once this is done, the
daemon will be stopped the next time FRR is restarted.


Network Namespaces
^^^^^^^^^^^^^^^^^^

It is possible to run FRR in different network namespaces so it can be
further compartmentalized (e.g. confining to a smaller subset network).
The network namespace configuration can be used in the default FRR
configuration pathspace or it can be used in a different pathspace
(`-N/--pathspace`).

To use FRR network namespace in the default pathspace you should add
or uncomment the ``watchfrr_options`` line in ``/etc/frr/daemons``:

.. code-block:: diff

   - #watchfrr_options="--netns"
   + watchfrr_options="--netns=<network-namespace-name>"

If you want to use a different pathspace with the network namespace
(the recommended way) you should add/uncomment the ``watchfrr_options``
line in ``/etc/frr/<namespace>/daemons``:

.. code-block:: diff

   - #watchfrr_options="--netns"
   + #watchfrr_options="--netns=<network-namespace-name>"
   +
   + # `--netns` argument is optional and if not provided it will
   + # default to the pathspace name.
   + watchfrr_options="--netns"

To start FRR in the new pathspace+network namespace the initialization script
should be called with an extra parameter:


.. code::

   /etc/init.d/frr start <pathspace-name>


.. note::

   Some Linux distributions might not use the default init script
   shipped with FRR, in that case you might want to try running the
   bundled script in ``/usr/lib/frr/frrinit.sh``.

   On systemd you might create different units or parameterize the
   existing one. See the man page:
   https://www.freedesktop.org/software/systemd/man/systemd.unit.html
Commit	Line	Data
717b4866 QY	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
0eb5f938 DL	9	Crash logs
	10	----------
	11
	12	If any daemon should crash for some reason (segmentation fault, assertion
	13	failure, etc.), it will attempt to write a backtrace to a file located in
	14	:file:`/var/tmp/frr/<daemon>[-<instance>].<pid>/crashlog`. This feature is
	15	not affected by any configuration options.
	16
	17	The crashlog file's directory also contains files corresponding to per-thread
	18	message buffers in files named
	19	:file:`/var/tmp/frr/<daemon>[-<instance>].<pid>/logbuf.<tid>`. In case of a
	20	crash, these may contain unwritten buffered log messages. To show the contents
	21	of these buffers, pipe their contents through ``tr '\0' '\n'``. A blank line
	22	marks the end of valid unwritten data (it will generally be followed by
	23	garbled, older log messages since the buffer is not cleared.)
	24
ac2cb9bf IR	25	.. _daemons-configuration-file:
ac2cb9bf IR	26
610b5328 DS	27	Daemons Configuration File
610b5328 DS	28	--------------------------
717b4866 QY	29	After a fresh install, starting FRR will do nothing. This is because daemons
	30	must be explicitly enabled by editing a file in your configuration directory.
	31	This file is usually located at :file:`/etc/frr/daemons` and determines which
	32	daemons are activated when issuing a service start / stop command via init or
	33	systemd. The file initially looks like this:
	34
	35	::
	36
	37	zebra=no
	38	bgpd=no
	39	ospfd=no
	40	ospf6d=no
	41	ripd=no
	42	ripngd=no
	43	isisd=no
	44	pimd=no
	45	ldpd=no
	46	nhrpd=no
	47	eigrpd=no
	48	babeld=no
	49	sharpd=no
614aa5c1	50	staticd=no
717b4866	51	pbrd=no
c44032c1	52	bfdd=no
f3c7b99d	53	fabricd=no
717b4866	54
717b4866 QY	55	#
	56	# If this option is set the /etc/init.d/frr script automatically loads
	57	# the config via "vtysh -b" when the servers are started.
	58	# Check /etc/pam.d/frr if you intend to use "vtysh"!
	59	#
	60	vtysh_enable=yes
da7e1a92	61	zebra_options=" -s 90000000 --daemon -A 127.0.0.1"
717b4866 QY	62	bgpd_options=" --daemon -A 127.0.0.1"
	63	ospfd_options=" --daemon -A 127.0.0.1"
	64	ospf6d_options=" --daemon -A ::1"
	65	ripd_options=" --daemon -A 127.0.0.1"
	66	ripngd_options=" --daemon -A ::1"
	67	isisd_options=" --daemon -A 127.0.0.1"
	68	pimd_options=" --daemon -A 127.0.0.1"
	69	ldpd_options=" --daemon -A 127.0.0.1"
	70	nhrpd_options=" --daemon -A 127.0.0.1"
	71	eigrpd_options=" --daemon -A 127.0.0.1"
	72	babeld_options=" --daemon -A 127.0.0.1"
	73	sharpd_options=" --daemon -A 127.0.0.1"
614aa5c1	74	staticd_options=" --daemon -A 127.0.0.1"
717b4866	75	pbrd_options=" --daemon -A 127.0.0.1"
c44032c1	76	bfdd_options=" --daemon -A 127.0.0.1"
f3c7b99d	77	fabricd_options=" --daemon -A 127.0.0.1"
717b4866	78
610b5328	79	#MAX_FDS=1024
717b4866	80	# The list of daemons to watch is automatically generated by the init script.
bd2893d5	81	#watchfrr_options=""
717b4866	82
bd2893d5 DL	83	# for debugging purposes, you can specify a "wrap" command to start instead
	84	# of starting the daemon directly, e.g. to use valgrind on ospfd:
	85	# ospfd_wrap="/usr/bin/valgrind"
	86	# or you can use "all_wrap" for all daemons, e.g. to use perf record:
	87	# all_wrap="/usr/bin/perf record --call-graph -"
	88	# the normal daemon command is added to this at the end.
717b4866 QY	89
	90	Breaking this file down:
	91
610b5328 DS	92	::
610b5328 DS	93
4b031e20	94	bgpd=yes
610b5328 DS	95
	96	To enable a particular daemon, simply change the corresponding 'no' to 'yes'.
	97	Subsequent service restarts should start the daemon.
	98
717b4866 QY	99	::
	100
	101	vtysh_enable=yes
	102
	103	As the comment says, this causes :ref:`VTYSH <vty-shell>` to apply
	104	configuration when starting the daemons. This is useful for a variety of
	105	reasons touched on in the VTYSH documentation and should generally be enabled.
	106
610b5328 DS	107	::
	108
	109	MAX_FDS=1024
	110
	111	This allows the operator to control the number of open file descriptors
	112	each daemon is allowed to start with. The current assumed value on
	113	most operating systems is 1024. If the operator plans to run bgp with
8de0f66a	114	several thousands of peers then this is where we would modify FRR to
610b5328 DS	115	allow this to happen.
610b5328 DS	116
d8743c28 MR	117	::
	118
	119	FRR_NO_ROOT="yes"
	120
	121	This option allows you to run FRR as a non-root user. Use this option
	122	only when you know what you are doing since most of the daemons
	123	in FRR will not be able to run under a regular user. This option
	124	is useful for example when you run FRR in a container with a designated
	125	user instead of root.
	126
717b4866 QY	127	::
717b4866 QY	128
da7e1a92	129	zebra_options=" -s 90000000 --daemon -A 127.0.0.1"
717b4866 QY	130	bgpd_options=" --daemon -A 127.0.0.1"
	131	...
	132
	133	The next set of lines controls what options are passed to daemons when started
	134	from the service script. Usually daemons will have ``--daemon`` and ``-A
	135	<address>`` specified in order to daemonize and listen for VTY commands on a
	136	particular address.
	137
bd2893d5 DL	138	The remaining file content regarding `watchfrr_options` and `*_wrap` settings
bd2893d5 DL	139	should not normally be needed; refer to the comments in case they are.
717b4866 QY	140
	141	Services
	142	--------
	143	FRR daemons have their own terminal interface or VTY. After installation, it's
	144	a good idea to setup each daemon's port number to connect to them. To do this
	145	add the following entries to :file:`/etc/services`.
	146
	147	::
	148
	149	zebrasrv 2600/tcp # zebra service
	150	zebra 2601/tcp # zebra vty
	151	ripd 2602/tcp # RIPd vty
	152	ripngd 2603/tcp # RIPngd vty
	153	ospfd 2604/tcp # OSPFd vty
	154	bgpd 2605/tcp # BGPd vty
	155	ospf6d 2606/tcp # OSPF6d vty
	156	ospfapi 2607/tcp # ospfapi
	157	isisd 2608/tcp # ISISd vty
	158	babeld 2609/tcp # BABELd vty
	159	nhrpd 2610/tcp # nhrpd vty
	160	pimd 2611/tcp # PIMd vty
	161	ldpd 2612/tcp # LDPd vty
	162	eigprd 2613/tcp # EIGRPd vty
c44032c1	163	bfdd 2617/tcp # bfdd vty
f3c7b99d	164	fabricd 2618/tcp # fabricd vty
df6f6055	165	vrrpd 2619/tcp # vrrpd vty
717b4866 QY	166
	167
	168	If you use a FreeBSD newer than 2.2.8, the above entries are already added to
	169	:file:`/etc/services` so there is no need to add it. If you specify a port
	170	number when starting the daemon, these entries may not be needed.
	171
	172	You may need to make changes to the config files in \|INSTALL_PREFIX_ETC\|.
	173
5b8235aa	174	Systemd
717b4866 QY	175	-------
	176	Although not installed when installing from source, FRR provides a service file
	177	for use with ``systemd``. It is located in :file:`tools/frr.service` in the Git
	178	repository. If ``systemctl status frr.service`` indicates that the FRR service
	179	is not found, copy the service file from the Git repository into your preferred
	180	location. A good place is usually ``/etc/systemd/system/``.
	181
	182	After issuing a ``systemctl daemon-reload``, you should be able to start the
	183	FRR service via ``systemctl start frr``. If this fails, or no daemons are
	184	started. check the ``journalctl`` logs for an indication of what went wrong.
5b8235aa QY	185
	186	Operations
	187	----------
	188
	189	This section covers a few common operational tasks and how to perform them.
	190
bca2d9bc TA	191	Interactive Shell
	192	^^^^^^^^^^^^^^^^^
	193	FRR offers an IOS-like interactive shell called ``vtysh`` where a user can run
	194	individual configuration or show commands. To get into this shell, issue the
	195	``vtysh`` command from either a privilege user (root, or with sudo) or a user
	196	account that is part of the ``frrvty`` group.
	197	e.g.
	198
	199	.. code-block:: console
	200
	201	root@ub18:~# vtysh
	202
	203	Hello, this is FRRouting (version 8.1-dev).
	204	Copyright 1996-2005 Kunihiro Ishiguro, et al.
	205
	206	ub18#
	207
	208	.. note::
	209	The default install location for vtysh is /usr/bin/vtysh
	210
	211
5b8235aa QY	212	Restarting
	213	^^^^^^^^^^
	214
	215	Restarting kills all running FRR daemons and starts them again. Any unsaved
	216	configuration will be lost.
	217
	218	.. code-block:: console
	219
	220	service frr restart
	221
	222	.. note::
	223
	224	Alternatively, you can invoke the init script directly::
	225
	226	/etc/init.d/frr restart
	227
	228	Or, if using systemd::
	229
	230	systemctl restart frr
	231
	232	Reloading
	233	^^^^^^^^^
	234
	235	Reloading applies the differential between on-disk configuration and the
	236	current effective configuration of running FRR processes. This includes
	237	starting daemons that were previously stopped and any changes made to
	238	individual or unified daemon configuration files.
	239
	240	.. code-block:: console
	241
	242	service frr reload
	243
	244	.. note::
	245
	246	Alternatively, you can invoke the init script directly::
	247
	248	/etc/init.d/frr reload
	249
	250	Or, if using systemd::
	251
	252	systemctl reload frr
	253
cff40472 MS	254	See :ref:`FRR-RELOAD <frr-reload>` for more about the `frr-reload.py` script.
cff40472 MS	255
431dd37e	256
5b8235aa QY	257	Starting a new daemon
	258	^^^^^^^^^^^^^^^^^^^^^
	259
	260	Suppose bgpd and zebra are running, and you wish to start pimd. In
	261	``/etc/frr/daemons`` make the following change:
	262
	263	.. code-block:: diff
	264
	265	- pimd=no
	266	+ pimd=yes
	267
	268	Then perform a reload.
	269
	270	Currently there is no way to stop or restart an individual daemon. This is
	271	because FRR's monitoring program cannot currently distinguish between a crashed
	272	/ killed daemon versus one that has been intentionally stopped or restarted.
	273	The closest that can be achieved is to remove all configuration for the daemon,
	274	and set its line in ``/etc/frr/daemons`` to ``=no``. Once this is done, the
	275	daemon will be stopped the next time FRR is restarted.
074286ed RZ	276
	277
	278	Network Namespaces
	279	^^^^^^^^^^^^^^^^^^
	280
	281	It is possible to run FRR in different network namespaces so it can be
	282	further compartmentalized (e.g. confining to a smaller subset network).
	283	The network namespace configuration can be used in the default FRR
	284	configuration pathspace or it can be used in a different pathspace
	285	(`-N/--pathspace`).
	286
	287	To use FRR network namespace in the default pathspace you should add
	288	or uncomment the ``watchfrr_options`` line in ``/etc/frr/daemons``:
	289
	290	.. code-block:: diff
	291
	292	- #watchfrr_options="--netns"
	293	+ watchfrr_options="--netns=<network-namespace-name>"
	294
	295	If you want to use a different pathspace with the network namespace
	296	(the recommended way) you should add/uncomment the ``watchfrr_options``
	297	line in ``/etc/frr/<namespace>/daemons``:
	298
	299	.. code-block:: diff
	300
	301	- #watchfrr_options="--netns"
	302	+ #watchfrr_options="--netns=<network-namespace-name>"
	303	+
	304	+ # `--netns` argument is optional and if not provided it will
	305	+ # default to the pathspace name.
	306	+ watchfrr_options="--netns"
	307
	308	To start FRR in the new pathspace+network namespace the initialization script
	309	should be called with an extra parameter:
	310
	311
	312	.. code::
	313
	314	/etc/init.d/frr start <pathspace-name>
	315
	316
	317	.. note::
	318
	319	Some Linux distributions might not use the default init script
	320	shipped with FRR, in that case you might want to try running the
	321	bundled script in ``/usr/lib/frr/frrinit.sh``.
	322
	323	On systemd you might create different units or parameterize the
	324	existing one. See the man page:
	325	https://www.freedesktop.org/software/systemd/man/systemd.unit.html