summaryrefslogtreecommitdiffstats
path: root/doc/user/basic.rst
blob: 5fdd1887fa32bf44adf487c8df2a5ade0bb4dbc3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
.. _basic-commands:

**************
Basic Commands
**************

The following sections discuss commands common to all the routing daemons.

.. _config-commands:

Config Commands
===============

In the config file, you can write the debugging options, a vty's password,
routing daemon configurations, a log file name, and so forth. This information
forms the initial command set for a routing beast as it is starting.

.. _config-file:

Integrated Config File
----------------------

FRR uses a single configuration file located in |INSTALL_PREFIX_ETC|/frr.conf.
When FRR is started using an init script or ``systemd``, ``vtysh`` is invoked to
read the config file and send the appropriate portions to only the daemons
interested in them. Running configuration updates are persisted back to this
single file using ``vtysh`` as well.

.. include:: prior-config-files.rst

.. _basic-config-commands:

Basic Config Commands
---------------------

.. clicmd:: hostname HOSTNAME

   Set hostname of the router. It is only for current ``vtysh``, it will not be
   saved to any configuration file even with ``write file``.

.. clicmd:: domainname DOMAINNAME

   Set domainname of the router. It is only for current ``vtysh``, it will not
   be saved to any configuration file even with ``write file``.

.. clicmd:: password PASSWORD

   Set password for vty interface. The ``no`` form of the command deletes the
   password. If there is no password, a vty won't accept connections.

.. clicmd:: enable password PASSWORD

   Set enable password. The ``no`` form of the command deletes the enable
   password.

.. clicmd:: service cputime-stats

   Collect CPU usage statistics for individual FRR event handlers and CLI
   commands.  This is enabled by default and can be disabled if the extra
   overhead causes a noticeable slowdown on your system.

   Disabling these statistics will also make the
   :clicmd:`service cputime-warning (1-4294967295)` limit non-functional.

.. clicmd:: service cputime-warning (1-4294967295)

   Warn if the CPU usage of an event handler or CLI command exceeds the
   specified limit (in milliseconds.)  Such warnings are generally indicative
   of some routine in FRR mistakenly blocking/hogging the processing loop and
   should be reported as a FRR bug.

   This command has no effect if :clicmd:`service cputime-stats` is disabled.

.. clicmd:: service walltime-warning (1-4294967295)

   Warn if the total wallclock time spent handling an event or executing a CLI
   command exceeds the specified limit (in milliseconds.)  This includes time
   spent waiting for I/O or other tasks executing and may produce excessive
   warnings if the system is overloaded.  (This may still be useful to
   provide an immediate sign that FRR is not operating correctly due to
   externally caused starvation.)

.. clicmd:: log trap LEVEL

   These commands are deprecated and are present only for historical
   compatibility. The log trap command sets the current logging level for all
   enabled logging destinations, and it sets the default for all future logging
   commands that do not specify a level. The normal default logging level is
   debugging. The ``no`` form of the command resets the default level for
   future logging commands to debugging, but it does not change the logging
   level of existing logging destinations.


.. clicmd:: log stdout LEVEL

   Enable logging output to stdout. If the optional second argument specifying
   the logging level is not present, the default logging level (typically
   debugging) will be used. The ``no`` form of the command disables logging to
   stdout. The ``LEVEL`` argument must have one of these values: emergencies,
   alerts, critical, errors, warnings, notifications, informational, or
   debugging. Note that the existing code logs its most important messages with
   severity ``errors``.

   .. note::

      If ``systemd`` is in use and stdout is connected to systemd, FRR will
      automatically switch to ``journald`` extended logging for this target.

   .. warning::

      FRRouting uses the ``writev()`` system call to write log messages.  This
      call is supposed to be atomic, but in reality this does not hold for
      pipes or terminals, only regular files.  This means that in rare cases,
      concurrent log messages from distinct threads may get jumbled in
      terminal output.  Use a log file and ``tail -f`` if this rare chance is
      inacceptable to your setup.

.. clicmd:: log file [FILENAME [LEVEL]]

   If you want to log into a file, please specify ``filename`` as
   in this example:

   ::

      log file /var/log/frr/bgpd.log informational

   If the optional second argument specifying the logging level is not present,
   the default logging level (typically debugging, but can be changed using the
   deprecated ``log trap`` command) will be used. The ``no`` form of the command
   disables logging to a file.

.. clicmd:: log daemon DAEMON file [FILENAME [LEVEL]]

   Configure file logging for a single FRR daemon. If you want to log
   into a file, please specify ``filename`` as in this example:

   ::

      log daemon bgpd file /var/log/frr/bgpd.log informational

   If the optional second argument specifying the logging level is not present,
   the default logging level (typically debugging, but can be changed using the
   deprecated ``log trap`` command) will be used. The ``no`` form of the command
   disables logging to a file for a single FRR daemon.

.. clicmd:: log syslog [LEVEL]

   Enable logging output to syslog. If the optional second argument specifying
   the logging level is not present, the default logging level (typically
   debugging, but can be changed using the deprecated ``log trap`` command) will
   be used. The ``no`` form of the command disables logging to syslog.

   .. note::

      This uses the system's ``syslog()`` API, which does not support message
      batching or structured key/value data pairs.  If possible, use
      :clicmd:`log extended EXTLOGNAME` with
      :clicmd:`destination syslog [supports-rfc5424]` instead of this.

.. clicmd:: log extended EXTLOGNAME

   Create an extended logging target with the specified name.  The name has
   no further meaning and is only used to identify the target.  Multiple
   targets can be created and deleted with the ``no`` form.

   Refer to :ref:`ext-log-target` for further details and suboptions.

.. clicmd:: log monitor [LEVEL]

   This command is deprecated and does nothing.

.. clicmd:: log facility [FACILITY]

   This command changes the facility used in syslog messages. The default
   facility is ``daemon``. The ``no`` form of the command resets the facility
   to the default ``daemon`` facility.

.. clicmd:: log record-priority

   To include the severity in all messages logged to a file, to stdout, or to
   a terminal monitor (i.e. anything except syslog),
   use the ``log record-priority`` global configuration command.
   To disable this option, use the ``no`` form of the command. By default,
   the severity level is not included in logged messages. Note: some
   versions of syslogd can be configured to include the facility and
   level in the messages emitted.

.. clicmd:: log timestamp precision [(0-6)]

   This command sets the precision of log message timestamps to the given
   number of digits after the decimal point. Currently, the value must be in
   the range 0 to 6 (i.e. the maximum precision is microseconds). To restore
   the default behavior (1-second accuracy), use the ``no`` form of the
   command, or set the precision explicitly to 0.

   ::

      log timestamp precision 3

   In this example, the precision is set to provide timestamps with
   millisecond accuracy.

.. clicmd:: log commands

   This command enables the logging of all commands typed by a user to all
   enabled log destinations. The note that logging includes full command lines,
   including passwords. If the daemon startup option `--command-log-always`
   is used to start the daemon then this command is turned on by default
   and cannot be turned off and the [no] form of the command is disallowed.

.. clicmd:: log filtered-file [FILENAME [LEVEL]]

   Configure a destination file for filtered logs with the
   :clicmd:`log filter-text WORD` command.

.. clicmd:: log filter-text WORD

   This command forces logs to be filtered on a specific string. A log message
   will only be printed if it matches on one of the filters in the log-filter
   table.  The filter only applies to file logging targets configured with
   :clicmd:`log filtered-file [FILENAME [LEVEL]]`.

   .. note::

      Log filters help when you need to turn on debugs that cause significant
      load on the system (enabling certain debugs can bring FRR to a halt).
      Log filters prevent this but you should still expect a small performance
      hit due to filtering each of all those logs.

   .. note::

      This setting is not saved to ``frr.conf`` and not shown in
      :clicmd:`show running-config`.  It is intended for ephemeral debugging
      purposes only.

.. clicmd:: clear log filter-text

   This command clears all current filters in the log-filter table.


.. clicmd:: log immediate-mode

   Use unbuffered output for log and debug messages; normally there is
   some internal buffering.

.. clicmd:: log unique-id

   Include ``[XXXXX-XXXXX]`` log message unique identifier in the textual part
   of log messages.  This is enabled by default, but can be disabled with
   ``no log unique-id``.  Please make sure the IDs are enabled when including
   logs for FRR bug reports.

   The unique identifiers are automatically generated based on source code
   file name, format string (before filling out) and severity.  They do not
   change "randomly", but some cleanup work may cause large chunks of ID
   changes between releases.  The IDs always start with a letter, consist of
   letters and numbers (and a dash for readability), are case insensitive, and
   ``I``, ``L``, ``O`` & ``U`` are excluded.

   This option will not affect future logging targets which allow putting the
   unique identifier in auxiliary metadata outside the log message text
   content.  (No such logging target exists currently, but RFC5424 syslog and
   systemd's journald both support it.)

.. clicmd:: debug unique-id XXXXX-XXXXX backtrace

   Print backtraces (call stack) for specific log messages, identified by
   their unique ID (see above.)  Includes source code location and current
   event handler being executed.  On some systems you may need to install a
   `debug symbols` package to get proper function names rather than raw code
   pointers.

   This command can be issued inside and outside configuration mode, and is
   saved to configuration only if it was given in configuration mode.

   .. warning::

      Printing backtraces can significantly slow down logging calls and cause
      log files to quickly balloon in size.  Remember to disable backtraces
      when they're no longer needed.

.. clicmd:: debug routemap [detail]

   This command turns on debugging of routemaps.  When detail is specified
   more data is provided to the operator about the reasoning about what
   is going on in the routemap code.

.. clicmd:: service password-encryption

   Encrypt password.

.. clicmd:: service advanced-vty

   Enable advanced mode VTY.

.. clicmd:: service terminal-length (0-512)

   Set system wide line configuration. This configuration command applies to
   all VTY interfaces.

.. clicmd:: line vty

   Enter vty configuration mode.

.. clicmd:: banner motd default

   Set default motd string.

.. clicmd:: banner motd file FILE

   Set motd string from file. The file must be in directory specified
   under ``--sysconfdir``.

.. clicmd:: banner motd line LINE

   Set motd string from an input.

.. clicmd:: exec-timeout MINUTE [SECOND]

   Set VTY connection timeout value. When only one argument is specified
   it is used for timeout value in minutes. Optional second argument is
   used for timeout value in seconds. Default timeout value is 10 minutes.
   When timeout value is zero, it means no timeout.

   Not setting this, or setting the values to 0 0, means a timeout will not be
   enabled.

.. clicmd:: access-class ACCESS-LIST

   Restrict vty connections with an access list.

.. clicmd:: allow-reserved-ranges

   Allow using IPv4 reserved (Class E) IP ranges for daemons. E.g.: setting
   IPv4 addresses for interfaces or allowing reserved ranges in BGP next-hops.

   If you need multiple FRR instances (or FRR + any other daemon) running in a
   single router and peering via 127.0.0.0/8, it's also possible to use this
   knob if turned on.

   Default: off.

.. _sample-config-file:

Sample Config File
------------------

Below is a sample configuration file for the zebra daemon.

.. code-block:: frr

   !
   ! Zebra configuration file
   !
   frr version 6.0
   frr defaults traditional
   !
   hostname Router
   password zebra
   enable password zebra
   !
   log stdout
   !
   !


``!`` and ``#`` are comment characters. If the first character of the word is
one of the comment characters then from the rest of the line forward will be
ignored as a comment.

.. code-block:: frr

   password zebra!password

If a comment character is not the first character of the word, it's a normal
character. So in the above example ``!`` will not be regarded as a comment and
the password is set to ``zebra!password``.


Configuration versioning, profiles and upgrade behavior
-------------------------------------------------------

All |PACKAGE_NAME| daemons share a mechanism to specify a configuration profile
and version for loading and saving configuration.  Specific configuration
settings take different default values depending on the selected profile and
version.

While the profile can be selected by user configuration and will remain over
upgrades, |PACKAGE_NAME| will always write configurations using its current
version.  This means that, after upgrading, a ``write file`` may write out a
slightly different configuration than what was read in.

Since the previous configuration is loaded with its version's defaults, but
the new configuration is written with the new defaults, any default that
changed between versions will result in an appropriate configuration entry
being written out.  **FRRouting configuration is sticky, staying consistent
over upgrades.**  Changed defaults will only affect new configuration.

Note that the loaded version persists into interactive configuration
sessions.  Commands executed in an interactive configuration session are
no different from configuration loaded at startup.  This means that when,
say, you configure a new BGP peer, the defaults used for configuration
are the ones selected by the last ``frr version`` command.

.. warning::

   Saving the configuration does not bump the daemons forward to use the new
   version for their defaults, but restarting them will, since they will then
   apply the new ``frr version`` command that was written out.  Manually
   execute the ``frr version`` command in ``show running-config`` to avoid
   this intermediate state.

This is visible in ``show running-config``:

.. code-block:: frr

   Current configuration:
   !
   ! loaded from 6.0
   frr version 6.1-dev
   frr defaults traditional
   !

If you save and then restart with this configuration, the old defaults will
no longer apply.  Similarly, you could execute ``frr version 6.1-dev``, causing
the new defaults to apply and the ``loaded from 6.0`` comment to disappear.


Profiles
^^^^^^^^

|PACKAGE_NAME| provides configuration profiles to adapt its default settings
to various usage scenarios.  Currently, the following profiles are
implemented:

* ``traditional`` - reflects defaults adhering mostly to IETF standards or
  common practices in wide-area internet routing.
* ``datacenter`` - reflects a single administrative domain with intradomain
  links using aggressive timers.

Your distribution/installation may pre-set a profile through the ``-F`` command
line option on all daemons.  All daemons must be configured for the same
profile.  The value specified on the command line is only a pre-set and any
``frr defaults`` statement in the configuration will take precedence.

.. note::

   The profile must be the same across all daemons.  Mismatches may result
   in undefined behavior.

You can freely switch between profiles without causing any interruption or
configuration changes.  All settings remain at their previous values, and
``show running-configuration`` output will have new output listing the previous
default values as explicit configuration.  New configuration, e.g. adding a
BGP peer, will use the new defaults.  To apply the new defaults for existing
configuration, the previously-invisible old defaults that are now shown must
be removed from the configuration.


Upgrade practices for interactive configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you configure |PACKAGE_NAME| interactively and use the configuration
writing functionality to make changes persistent, the following
recommendations apply in regards to upgrades:

1. Skipping major versions should generally work but is still inadvisable.
   To avoid unneeded issue, upgrade one major version at a time and write
   out the configuration after each update.

2. After installing a new |PACKAGE_NAME| version, check the configuration
   for differences against your old configuration.  If any defaults changed
   that affect your setup, lines may appear or disappear.  If a new line
   appears, it was previously the default (or not supported) and is now
   necessary to retain previous behavior.  If a line disappears, it
   previously wasn't the default, but now is, so it is no longer necessary.

3. Check the log files for deprecation warnings by using ``grep -i deprecat``.

4. After completing each upgrade, save the configuration and either restart
   |PACKAGE_NAME| or execute ``frr version <CURRENT>`` to ensure defaults of
   the new version are fully applied.


Upgrade practices for autogenerated configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When using |PACKAGE_NAME| with generated configurations (e.g. Ansible,
Puppet, etc.), upgrade considerations differ somewhat:

1. Always write out a ``frr version`` statement in the configurations you
   generate.  This ensures that defaults are applied consistently.

2. Try to not run more distinct versions of |PACKAGE_NAME| than necessary.
   Each version may need to be checked individually.  If running a mix of
   older and newer installations, use the oldest version for the
   ``frr version`` statement.

3. When rolling out upgrades, generate a configuration as usual with the old
   version identifier and load it.  Check for any differences or deprecation
   warnings.  If there are differences in the configuration, propagate these
   back to the configuration generator to minimize relying on actual default
   values.

4. After the last installation of an old version is removed, change the
   configuration generation to a newer ``frr version`` as appropriate.  Perform
   the same checks as when rolling out upgrades.


.. _terminal-mode-commands:

Terminal Mode Commands
======================

.. clicmd:: write terminal

   Displays the current configuration to the vty interface.

.. clicmd:: write file

   Write current configuration to configuration file.

.. clicmd:: configure [terminal]

   Change to configuration mode. This command is the first step to
   configuration.

.. clicmd:: terminal length (0-512)

   Set terminal display length to ``(0-512)``. If length is 0, no display
   control is performed.

.. clicmd:: who

   Show a list of currently connected vty sessions.

.. clicmd:: list

   List all available commands.

.. clicmd:: show version

   Show the current version of |PACKAGE_NAME| and its build host information.

.. clicmd:: show logging

   Shows the current configuration of the logging system. This includes the
   status of all logging destinations.

.. clicmd:: show log-filter

   Shows the current log filters applied to each daemon.

.. clicmd:: show memory [DAEMON]

   Show information on how much memory is used for which specific things in
   |PACKAGE_NAME|.  Output may vary depending on system capabilities but will
   generally look something like this:

   ::

      frr# show memory
      System allocator statistics:
        Total heap allocated:  1584 KiB
        Holding block headers: 0 bytes
        Used small blocks:     0 bytes
        Used ordinary blocks:  1484 KiB
        Free small blocks:     2096 bytes
        Free ordinary blocks:  100 KiB
        Ordinary blocks:       2
        Small blocks:          60
        Holding blocks:        0
      (see system documentation for 'mallinfo' for meaning)
      --- qmem libfrr ---
      Buffer                        :          3      24                  72
      Buffer data                   :          1    4120                4120
      Host config                   :          3  (variably sized)        72
      Command Tokens                :       3427      72              247160
      Command Token Text            :       2555  (variably sized)     83720
      Command Token Help            :       2555  (variably sized)     61720
      Command Argument              :          2  (variably sized)        48
      Command Argument Name         :        641  (variably sized)     15672
      [...]
      --- qmem Label Manager ---
      --- qmem zebra ---
      ZEBRA VRF                     :          1     912                 920
      Route Entry                   :         11      80                 968
      Static route                  :          1     192                 200
      RIB destination               :          8      48                 448
      RIB table info                :          4      16                  96
      Nexthop tracking object       :          1     200                 200
      Zebra Name Space              :          1     312                 312
      --- qmem Table Manager ---

   To understand system allocator statistics, refer to your system's
   :manpage:`mallinfo(3)` man page.

   Below these statistics, statistics on individual memory allocation types
   in |PACKAGE_NAME| (so-called `MTYPEs`) is printed:

   * the first column of numbers is the current count of allocations made for
     the type (the number decreases when items are freed.)
   * the second column is the size of each item.  This is only available if
     allocations on a type are always made with the same size.
   * the third column is the total amount of memory allocated for the
     particular type, including padding applied by malloc.  This means that
     the number may be larger than the first column multiplied by the second.
     Overhead incurred by malloc's bookkeeping is not included in this, and
     the column may be missing if system support is not available.

   When executing this command from ``vtysh``, each of the daemons' memory
   usage is printed sequentially. You can specify the daemon's name to print
   only its memory usage.

.. clicmd:: show motd

   Show current motd banner.

.. clicmd:: show history

   Dump the vtysh cli history.

.. clicmd:: logmsg LEVEL MESSAGE

   Send a message to all logging destinations that are enabled for messages of
   the given severity.

.. clicmd:: find REGEX...

   This command performs a regex search across all defined commands in all
   modes. As an example, suppose you're in enable mode and can't remember where
   the command to turn OSPF segment routing on is:

   ::

      frr# find segment-routing on
        (ospf)  segment-routing on
        (isis)  segment-routing on


   The CLI mode is displayed next to each command. In this example,
   :clicmd:`segment-routing on` is under the `router ospf` mode.

   Similarly, suppose you want a listing of all commands that contain "l2vpn"
   and "neighbor":

   ::

      frr# find l2vpn.*neighbor
        (view)  show [ip] bgp l2vpn evpn neighbors <A.B.C.D|X:X::X:X|WORD> advertised-routes [json]
        (view)  show [ip] bgp l2vpn evpn neighbors <A.B.C.D|X:X::X:X|WORD> routes [json]
        (view)  show [ip] bgp l2vpn evpn rd ASN:NN_OR_IP-ADDRESS:NN neighbors <A.B.C.D|X:X::X:X|WORD> advertised-routes [json]
        (view)  show [ip] bgp l2vpn evpn rd ASN:NN_OR_IP-ADDRESS:NN neighbors <A.B.C.D|X:X::X:X|WORD> routes [json]
        ...


   Note that when entering spaces as part of a regex specification, repeated
   spaces will be compressed into a single space for matching purposes. This is
   a consequence of spaces being used to delimit CLI tokens. If you need to
   match more than one space, use the ``\s`` escape.

   POSIX Extended Regular Expressions are supported.


.. _common-show-commands:

.. clicmd:: show event cpu [r|w|t|e|x]

   This command displays system run statistics for all the different event
   types. If no options is specified all different run types are displayed
   together.  Additionally you can ask to look at (r)ead, (w)rite, (t)imer,
   (e)vent and e(x)ecute thread event types.

.. clicmd:: show event poll

   This command displays FRR's poll data.  It allows a glimpse into how
   we are setting each individual fd for the poll command at that point
   in time.

.. clicmd:: show event timers

   This command displays FRR's timer data for timers that will pop in
   the future.

.. clicmd:: show configuration running [<json|xml> [translate WORD]] [with-defaults] DAEMON

   This command displays the northbound/YANG configuration data for a
   daemon in text/vty, json, or xml format.

.. clicmd:: show yang operational-data XPATH [{format <json|xml>|translate TRANSLATOR|with-config}] DAEMON

   Display the YANG operational data starting from XPATH. The default
   format is JSON, but can be displayed in XML as well.

   Normally YANG operational data are located inside containers marked
   as `read-only`.

   Optionally it is also possible to display configuration leaves in
   addition to operational data with the option `with-config`. This
   option enables the display of configuration leaves with their
   currently configured value (if the leaf is optional it will only show
   if it was created or has a default value).

.. _common-invocation-options:

Common Invocation Options
=========================

These options apply to all |PACKAGE_NAME| daemons.


.. option:: -d, --daemon

   Run in daemon mode.

.. option:: -f, --config_file <file>

   Set configuration file name.

.. option:: -h, --help

   Display this help and exit.

.. option:: -i, --pid_file <file>

   Upon startup the process identifier of the daemon is written to a file,
   typically in :file:`/var/run`. This file can be used by the init system
   to implement commands such as ``.../init.d/zebra status``,
   ``.../init.d/zebra restart`` or ``.../init.d/zebra stop``.

   The file name is an run-time option rather than a configure-time option so
   that multiple routing daemons can be run simultaneously. This is useful when
   using |PACKAGE_NAME| to implement a routing looking glass. One machine can
   be used to collect differing routing views from differing points in the
   network.

.. option:: -A, --vty_addr <address>

   Set the VTY local address to bind to. If set, the VTY socket will only be
   bound to this address.

.. option:: -P, --vty_port <port>

   Set the VTY TCP port number. If set to 0 then the TCP VTY sockets will not
   be opened.

.. option:: -u <user>

   Set the user and group to run as.

.. option:: -N <namespace>

   Set the namespace that the daemon will run in.  A "/<namespace>" will
   be added to all files that use the statedir.  If you have "/var/run/frr"
   as the default statedir then it will become "/var/run/frr/<namespace>".

.. option:: -o, --vrfdefaultname <name>

   Set the name used for the *Default VRF* in CLI commands and YANG models.
   This option must be the same for all running daemons. By default, the name
   is "default".

   .. seealso:: :ref:`zebra-vrf`

.. option:: -v, --version

   Print program version.

.. option:: --command-log-always

   Cause the daemon to always log commands entered to the specified log file.
   This also makes the `no log commands` command disallowed. Enabling this
   is suggested if you have need to track what the operator is doing on
   this router.

.. option:: --log <stdout|syslog|file:/path/to/log/file>

   When initializing the daemon, setup the log to go to either stdout,
   syslog or to a file.  These values will be displayed as part of
   a show run.  Additionally they can be overridden at runtime if
   desired via the normal log commands.

.. option:: --log-level <emergencies|alerts|critical|errors|warnings|notifications|informational|debugging>

   When initializing the daemon, allow the specification of a default
   log level at startup from one of the specified levels.

.. option:: --tcli

   Enable the transactional CLI mode.

.. option:: --limit-fds <number>

   Limit the number of file descriptors that will be used internally
   by the FRR daemons. By default, the daemons use the system ulimit
   value.

.. _loadable-module-support:

Loadable Module Support
=======================

FRR supports loading extension modules at startup. Loading, reloading or
unloading modules at runtime is not supported (yet). To load a module, use
the following command line option at daemon startup:


.. option:: -M, --module <module:options>

   Load the specified module, optionally passing options to it. If the module
   name contains a slash (/), it is assumed to be a full pathname to a file to
   be loaded. If it does not contain a slash, the |INSTALL_PREFIX_MODULES|
   directory is searched for a module of the given name; first with the daemon
   name prepended (e.g. ``zebra_mod`` for ``mod``), then without the daemon
   name prepended.

   This option is available on all daemons, though some daemons may not have
   any modules available to be loaded.


The SNMP Module
---------------

If SNMP is enabled during compile-time and installed as part of the package,
the ``snmp`` module can be loaded for the *Zebra*, *bgpd*, *ospfd*, *ospf6d*
and *ripd* daemons.

The module ignores any options passed to it. Refer to :ref:`snmp-support` for
information on its usage.


The FPM Module
--------------

If FPM is enabled during compile-time and installed as part of the package, the
``fpm`` module can be loaded for the *zebra* daemon. This provides the
Forwarding Plane Manager ("FPM") API.

The module expects its argument to be either ``Netlink`` or ``protobuf``,
specifying the encapsulation to use. ``Netlink`` is the default, and
``protobuf`` may not be available if the module was built without protobuf
support. Refer to :ref:`zebra-fib-push-interface` for more information.


.. _virtual-terminal-interfaces:

Virtual Terminal Interfaces
===========================

VTY -- Virtual Terminal [aka TeletYpe] Interface is a command line
interface (CLI) for user interaction with the routing daemon.


.. _vty-overview:

VTY Overview
------------

VTY stands for Virtual TeletYpe interface. It means you can connect to
the daemon via the telnet protocol.

To enable a VTY interface, you have to setup a VTY password. If there
is no VTY password, one cannot connect to the VTY interface at all.

::

   % telnet localhost 2601
   Trying 127.0.0.1...
   Connected to localhost.
   Escape character is '^]'.

   Hello, this is |PACKAGE_NAME| (version |PACKAGE_VERSION|)
   |COPYRIGHT_STR|

   User Access Verification

   Password: XXXXX
   Router> ?
     enable .  .  .  Turn on privileged commands
     exit   .  .  .  Exit current mode and down to previous mode
     help   .  .  .  Description of the interactive help system
     list   .  .  .  Print command list
     show   .  .  .  Show system inform

     wh. . .  Display who is on a vty
   Router> enable
   Password: XXXXX
   Router# configure terminal
   Router(config)# interface eth0
   Router(config-if)# ip address 10.0.0.1/8
   Router(config-if)# ^Z
   Router#


.. _vty-modes:

VTY Modes
---------

There are three basic VTY modes:

There are commands that may be restricted to specific VTY modes.

.. _vty-view-mode:

VTY View Mode
^^^^^^^^^^^^^

This mode is for read-only access to the CLI. One may exit the mode by
leaving the system, or by entering `enable` mode.

.. _vty-enable-mode:

VTY Enable Mode
^^^^^^^^^^^^^^^

This mode is for read-write access to the CLI. One may exit the mode by
leaving the system, or by escaping to view mode.

.. _vty-other-modes:

VTY Other Modes
^^^^^^^^^^^^^^^

This page is for describing other modes.

.. _vty-cli-commands:

VTY CLI Commands
----------------

Commands that you may use at the command-line are described in the following
three subsubsections.

.. _cli-movement-commands:

CLI Movement Commands
^^^^^^^^^^^^^^^^^^^^^

These commands are used for moving the CLI cursor. The :kbd:`C` character
means press the Control Key.

:kbd:`C-f` / :kbd:`LEFT`
   Move forward one character.

:kbd:`C-b` / :kbd:`RIGHT`
   Move backward one character.

:kbd:`M-f`
   Move forward one word.

:kbd:`M-b`
   Move backward one word.

:kbd:`C-a`
   Move to the beginning of the line.

:kbd:`C-e`
   Move to the end of the line.


.. _cli-editing-commands:

CLI Editing Commands
^^^^^^^^^^^^^^^^^^^^

These commands are used for editing text on a line. The :kbd:`C`
character means press the Control Key.


:kbd:`C-h` / :kbd:`DEL`
   Delete the character before point.


:kbd:`C-d`
   Delete the character after point.


:kbd:`M-d`
   Forward kill word.


:kbd:`C-w`
   Backward kill word.


:kbd:`C-k`
   Kill to the end of the line.


:kbd:`C-u`
   Kill line from the beginning, erasing input.


:kbd:`C-t`
   Transpose character.


CLI Advanced Commands
^^^^^^^^^^^^^^^^^^^^^

There are several additional CLI commands for command line completions,
insta-help, and VTY session management.


:kbd:`C-c`
   Interrupt current input and moves to the next line.


:kbd:`C-z`
   End current configuration session and move to top node.


:kbd:`C-n` / :kbd:`DOWN`
   Move down to next line in the history buffer.


:kbd:`C-p` / :kbd:`UP`
   Move up to previous line in the history buffer.


:kbd:`TAB`
   Use command line completion by typing :kbd:`TAB`.


:kbd:`?`
   You can use command line help by typing ``help`` at the beginning of the
   line.  Typing :kbd:`?` at any point in the line will show possible
   completions.

Pipe Actions
^^^^^^^^^^^^

VTY supports optional modifiers at the end of commands that perform
postprocessing on command output or modify the action of commands. These do not
show up in the :kbd:`?` or :kbd:`TAB` suggestion lists.

``... | include REGEX``
   Filters the output of the preceding command, including only lines which
   match the POSIX Extended Regular Expression ``REGEX``. Do not put the regex
   in quotes.

   Examples:

   ::

      frr# show ip bgp sum json | include remoteAs
            "remoteAs":0,
            "remoteAs":455,
            "remoteAs":99,

   ::

      frr# show run | include neigh.*[0-9]{2}\.0\.[2-4]\.[0-9]*
       neighbor 10.0.2.106 remote-as 99
       neighbor 10.0.2.107 remote-as 99
       neighbor 10.0.2.108 remote-as 99
       neighbor 10.0.2.109 remote-as 99
       neighbor 10.0.2.110 remote-as 99
       neighbor 10.0.3.111 remote-as 111