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