]> git.proxmox.com Git - mirror_frr.git/blame - doc/user/basic.rst
doc: cleanup kernel.rst
[mirror_frr.git] / doc / user / basic.rst
CommitLineData
42fc5d26
QY
1.. _Basic_commands:
2
3**************
4Basic commands
5**************
6
7There are five routing daemons in use, and there is one manager daemon.
8These daemons may be located on separate machines from the manager
8d209861
QY
9daemon. Each of these daemons will listen on a particular port for
10incoming VTY connections. The routing daemons are:
42fc5d26 11
8d209861
QY
12- *ripd*
13- *ripngd*
14- *ospfd*
15- *ospf6d*
16- *bgpd*
17- *zebra*
42fc5d26
QY
18
19The following sections discuss commands common to all the routing
20daemons.
21
22.. _Config_Commands:
23
24Config Commands
25===============
26
27.. index:: Configuration files for running the software
28
29.. index:: Files for running configurations
30
31.. index:: Modifying the herd's behavior
32
33.. index:: Getting the herd running
34
35In a config file, you can write the debugging options, a vty's password,
36routing daemon configurations, a log file name, and so forth. This
37information forms the initial command set for a routing beast as it is
38starting.
39
dc5564c7 40Config files are generally found in |INSTALL_PREFIX_ETC|.
42fc5d26
QY
41
42Each of the daemons has its own
dc5564c7 43config file. For example, zebra's default config file name is *zebra.conf*.
42fc5d26 44
dc5564c7 45The daemon name plus `.conf` is the default config file name. You
8d209861 46can specify a config file using the :kbd:`-f` or :kbd:`--config-file`
42fc5d26
QY
47options when starting the daemon.
48
49.. _Basic_Config_Commands:
50
51Basic Config Commands
52---------------------
53
8d209861 54.. index:: hostname HOSTNAME
42fc5d26 55
29adcd50
QY
56.. clicmd:: hostname HOSTNAME
57
58 Set hostname of the router.
42fc5d26 59
8d209861 60.. index:: password PASSWORD
42fc5d26 61
29adcd50
QY
62.. clicmd:: password PASSWORD
63
64 Set password for vty interface. If there is no password, a vty won't
65 accept connections.
42fc5d26 66
8d209861 67.. index:: enable password PASSWORD
42fc5d26 68
29adcd50
QY
69.. clicmd:: enable password PASSWORD
70
71 Set enable password.
42fc5d26 72
8d209861 73.. index::
29adcd50
QY
74 single: no log trap [LEVEL]
75 single: log trap LEVEL
76
77.. clicmd:: [no] log trap LEVEL
78
79 These commands are deprecated and are present only for historical
80 compatibility. The log trap command sets the current logging level for all
81 enabled logging destinations, and it sets the default for all future logging
82 commands that do not specify a level. The normal default logging level is
83 debugging. The ``no`` form of the command resets the default level for future
84 logging commands to debugging, but it does not change the logging level of
85 existing logging destinations.
8d209861
QY
86
87.. index::
29adcd50
QY
88 single: no log stdout [LEVEL]
89 single: log stdout [LEVEL]
90
91.. clicmd:: [no] log stdout LEVEL
92
93 Enable logging output to stdout. If the optional second argument specifying
94 the logging level is not present, the default logging level (typically
95 debugging, but can be changed using the deprecated ``log trap`` command) will
96 be used. The ``no`` form of the command disables logging to stdout. The
97 ``LEVEL`` argument must have one of these values: emergencies, alerts,
98 critical, errors, warnings, notifications, informational, or debugging. Note
99 that the existing code logs its most important messages with severity
100 ``errors``.
8d209861
QY
101
102.. index::
29adcd50
QY
103 single: no log file [FILENAME [LEVEL]]
104 single: log file FILENAME [LEVEL]
105
106.. clicmd:: [no] log file [FILENAME [LEVEL]]
8d209861 107
29adcd50
QY
108 If you want to log into a file, please specify ``filename`` as
109 in this example: ::
8d209861 110
29adcd50 111 log file /var/log/frr/bgpd.log informational
8d209861 112
29adcd50
QY
113 If the optional second argument specifying the logging level is not present,
114 the default logging level (typically debugging, but can be changed using the
115 deprecated ``log trap`` command) will be used. The ``no`` form of the command
116 disables logging to a file. *Note:* if you do not configure any file logging,
117 and a daemon crashes due to a signal or an assertion failure, it will attempt
118 to save the crash information in a file named /var/tmp/frr.<daemon
119 name>.crashlog. For security reasons, this will not happen if the file exists
120 already, so it is important to delete the file after reporting the crash
121 information.
8d209861
QY
122
123.. index::
29adcd50
QY
124 single: no log syslog [LEVEL]
125 single: log syslog [LEVEL]
126
127.. clicmd:: [no] log syslog [LEVEL]
8d209861 128
29adcd50
QY
129 Enable logging output to syslog. If the optional second argument specifying
130 the logging level is not present, the default logging level (typically
131 debugging, but can be changed using the deprecated ``log trap`` command) will
132 be used. The ``no`` form of the command disables logging to syslog.
8d209861
QY
133
134.. index::
29adcd50
QY
135 single: no log monitor [LEVEL]
136 single: log monitor [LEVEL]
137
138.. clicmd:: [no] log monitor [LEVEL]
139
140 Enable logging output to vty terminals that have enabled logging using the
141 ``terminal monitor`` command. By default, monitor logging is enabled at the
142 debugging level, but this command (or the deprecated ``log trap`` command) can
143 be used to change the monitor logging level. If the optional second argument
144 specifying the logging level is not present, the default logging level
145 (typically debugging, but can be changed using the deprecated ``log trap``
146 command) will be used. The ``no`` form of the command disables logging to
147 terminal monitors.
8d209861
QY
148
149.. index::
29adcd50
QY
150 single: no log facility [FACILITY]
151 single: log facility [FACILITY]
8d209861 152
29adcd50
QY
153.. clicmd:: [no] log facility [FACILITY]
154
155 This command changes the facility used in syslog messages. The default
156 facility is ``daemon``. The ``no`` form of the command resets
157 the facility to the default ``daemon`` facility.
8d209861
QY
158
159.. index::
29adcd50
QY
160 single: no log record-priority
161 single: log record-priority
162
163.. clicmd:: [no] log record-priority
164
165 To include the severity in all messages logged to a file, to stdout, or to
166 a terminal monitor (i.e. anything except syslog),
167 use the ``log record-priority`` global configuration command.
168 To disable this option, use the ``no`` form of the command. By default,
169 the severity level is not included in logged messages. Note: some
170 versions of syslogd (including Solaris) can be configured to include
171 the facility and level in the messages emitted.
8d209861
QY
172
173.. index::
29adcd50
QY
174 single: log timestamp precision (0-6)
175 single: [no] log timestamp precision (0-6)
8d209861 176
29adcd50
QY
177.. clicmd:: [no] log timestamp precision [(0-6)]
178
179 This command sets the precision of log message timestamps to the given number
180 of digits after the decimal point. Currently, the value must be in the range
181 0 to 6 (i.e. the maximum precision is microseconds). To restore the default
182 behavior (1-second accuracy), use the ``no`` form of the command, or set the
183 precision explicitly to 0.
42fc5d26
QY
184
185::
186
29adcd50 187 log timestamp precision 3
42fc5d26 188
29adcd50
QY
189 In this example, the precision is set to provide timestamps with
190 millisecond accuracy.
42fc5d26 191
8d209861 192.. index:: log commands
42fc5d26 193
29adcd50
QY
194.. clicmd:: log commands
195
196 This command enables the logging of all commands typed by a user to
197 all enabled log destinations. The note that logging includes full
198 command lines, including passwords. Once set, command logging can only
199 be turned off by restarting the daemon.
42fc5d26 200
8d209861 201.. index:: service password-encryption
42fc5d26 202
29adcd50
QY
203.. clicmd:: service password-encryption
204
205 Encrypt password.
42fc5d26 206
8d209861 207.. index:: service advanced-vty
42fc5d26 208
29adcd50 209.. clicmd:: service advanced-vty
42fc5d26 210
29adcd50 211 Enable advanced mode VTY.
42fc5d26 212
29adcd50
QY
213.. index:: service terminal-length (0-512)
214
215.. clicmd:: service terminal-length (0-512)
216
217 Set system wide line configuration. This configuration command applies
218 to all VTY interfaces.
42fc5d26 219
8d209861 220.. index:: line vty
42fc5d26 221
29adcd50
QY
222.. clicmd:: line vty
223
224 Enter vty configuration mode.
42fc5d26 225
8d209861 226.. index:: banner motd default
42fc5d26 227
29adcd50
QY
228.. clicmd:: banner motd default
229
230 Set default motd string.
42fc5d26 231
8d209861 232.. index:: no banner motd
42fc5d26 233
29adcd50
QY
234.. clicmd:: no banner motd
235
236 No motd banner string will be printed.
42fc5d26 237
8d209861 238.. index:: exec-timeout MINUTE [SECOND]
42fc5d26 239
29adcd50
QY
240.. clicmd:: exec-timeout MINUTE [SECOND]
241
242 Set VTY connection timeout value. When only one argument is specified
243 it is used for timeout value in minutes. Optional second argument is
244 used for timeout value in seconds. Default timeout value is 10 minutes.
245 When timeout value is zero, it means no timeout.
42fc5d26 246
8d209861 247.. index:: no exec-timeout
42fc5d26 248
29adcd50
QY
249.. clicmd:: no exec-timeout
250
251 Do not perform timeout at all. This command is as same as *exec-timeout 0 0*.
42fc5d26 252
8d209861 253.. index:: access-class ACCESS-LIST
42fc5d26 254
29adcd50
QY
255.. clicmd:: access-class ACCESS-LIST
256
257 Restrict vty connections with an access list.
42fc5d26
QY
258
259.. _Sample_Config_File:
260
261Sample Config File
262------------------
263
264Below is a sample configuration file for the zebra daemon.
265
266::
267
42fc5d26
QY
268 !
269 ! Zebra configuration file
270 !
271 hostname Router
272 password zebra
273 enable password zebra
274 !
275 log stdout
276 !
277 !
42fc5d26 278
8d209861
QY
279
280'!' and '#' are comment characters. If the first character of the word
42fc5d26
QY
281is one of the comment characters then from the rest of the line forward
282will be ignored as a comment.
283
284::
285
286 password zebra!password
42fc5d26
QY
287
288If a comment character is not the first character of the word, it's a
289normal character. So in the above example '!' will not be regarded as a
290comment and the password is set to 'zebra!password'.
291
292.. _Terminal_Mode_Commands:
293
294Terminal Mode Commands
295======================
296
8d209861 297.. index:: write terminal
42fc5d26 298
29adcd50
QY
299.. clicmd:: write terminal
300
42fc5d26
QY
301 Displays the current configuration to the vty interface.
302
8d209861 303.. index:: write file
42fc5d26 304
29adcd50
QY
305.. clicmd:: write file
306
42fc5d26
QY
307 Write current configuration to configuration file.
308
8d209861 309.. index:: configure terminal
42fc5d26 310
29adcd50
QY
311.. clicmd:: configure terminal
312
8d209861 313 Change to configuration mode. This command is the first step to
42fc5d26
QY
314 configuration.
315
29adcd50 316.. index:: terminal length (0-512)
42fc5d26 317
29adcd50
QY
318.. clicmd:: terminal length (0-512)
319
320 Set terminal display length to ``(0-512)``. If length is 0, no
42fc5d26
QY
321 display control is performed.
322
8d209861 323.. index:: who
42fc5d26 324
29adcd50
QY
325.. clicmd:: who
326
42fc5d26
QY
327 Show a list of currently connected vty sessions.
328
8d209861 329.. index:: list
42fc5d26 330
29adcd50
QY
331.. clicmd:: list
332
42fc5d26
QY
333 List all available commands.
334
8d209861 335.. index:: show version
42fc5d26 336
29adcd50
QY
337.. clicmd:: show version
338
be46d288 339 Show the current version of |PACKAGE_NAME| and its build host information.
42fc5d26 340
8d209861 341.. index:: show logging
42fc5d26 342
29adcd50
QY
343.. clicmd:: show logging
344
8d209861 345 Shows the current configuration of the logging system. This includes
42fc5d26
QY
346 the status of all logging destinations.
347
8d209861 348.. index:: logmsg LEVEL MESSAGE
42fc5d26 349
29adcd50
QY
350.. clicmd:: logmsg LEVEL MESSAGE
351
42fc5d26
QY
352 Send a message to all logging destinations that are enabled for messages
353 of the given severity.
354
355.. _Common_Invocation_Options:
356
357Common Invocation Options
358=========================
359
be46d288 360These options apply to all |PACKAGE_NAME| daemons.
42fc5d26
QY
361
362
29adcd50
QY
363.. clicmd:: -d, --daemon
364
42fc5d26
QY
365 Runs in daemon mode.
366
367
29adcd50
QY
368.. clicmd:: -f file, --config_file=FILE
369
42fc5d26
QY
370 Set configuration file name.
371
372
29adcd50
QY
373.. clicmd:: -h, --help
374
42fc5d26
QY
375 Display this help and exit.
376
377
29adcd50
QY
378.. clicmd:: -i file, --pid_file=file
379
42fc5d26 380 Upon startup the process identifier of the daemon is written to a file,
8d209861
QY
381 typically in :file:`/var/run`. This file can be used by the init system
382 to implement commands such as ``.../init.d/zebra status``,
383 ``.../init.d/zebra restart`` or ``.../init.d/zebra stop``.
42fc5d26
QY
384
385 The file name is an run-time option rather than a configure-time option
8d209861 386 so that multiple routing daemons can be run simultaneously. This is
be46d288 387 useful when using |PACKAGE_NAME| to implement a routing looking glass. One
42fc5d26
QY
388 machine can be used to collect differing routing views from differing
389 points in the network.
390
391
29adcd50
QY
392.. clicmd:: -A address, --vty_addr=address
393
42fc5d26 394 Set the VTY local address to bind to. If set, the VTY socket will only
8d209861 395 be bound to this address.
42fc5d26
QY
396
397
29adcd50
QY
398.. clicmd:: -P port, --vty_port=port
399
42fc5d26
QY
400 Set the VTY TCP port number. If set to 0 then the TCP VTY sockets will not
401 be opened.
402
403
29adcd50
QY
404.. clicmd:: -u user, --vty_addr=user
405
42fc5d26
QY
406 Set the user and group to run as.
407
408
29adcd50
QY
409.. clicmd:: -v, --version
410
42fc5d26
QY
411 Print program version.
412
413
414.. _Loadable_Module_Support:
415
416Loadable Module Support
417=======================
418
8d209861
QY
419FRR supports loading extension modules at startup. Loading, reloading or
420unloading modules at runtime is not supported (yet). To load a module, use
42fc5d26
QY
421the following command line option at daemon startup:
422
423
29adcd50
QY
424.. clicmd:: -M module:options, --module module:options
425
8d209861 426 Load the specified module, optionally passing options to it. If the module
42fc5d26 427 name contains a slash (/), it is assumed to be a full pathname to a file to
8d209861 428 be loaded. If it does not contain a slash, the
be46d288 429 `INSTALL_PREFIX_MODULES` directory is searched for a module of
8d209861
QY
430 the given name; first with the daemon name prepended (e.g. ``zebra_mod``
431 for ``mod``), then without the daemon name prepended.
42fc5d26
QY
432
433 This option is available on all daemons, though some daemons may not have
434 any modules available to be loaded.
435
436The SNMP Module
437---------------
438
439If SNMP is enabled during compile-time and installed as part of the package,
8d209861
QY
440the ``snmp`` module can be loaded for the *zebra*, *bgpd*, *ospfd*, *ospf6d*
441and *ripd* daemons.
42fc5d26 442
8d209861 443The module ignores any options passed to it. Refer to :ref:`SNMP_Support`
42fc5d26
QY
444for information on its usage.
445
446The FPM Module
447--------------
448
449If FPM is enabled during compile-time and installed as part of the package,
8d209861 450the ``fpm`` module can be loaded for the *zebra* daemon. This
42fc5d26
QY
451provides the Forwarding Plane Manager ("FPM") API.
452
8d209861 453The module expects its argument to be either ``netlink`` or
29adcd50 454.. clicmd:: protobuf, specifying the encapsulation to use. `netlink` is the
42fc5d26 455default, and `protobuf` may not be available if the module was built
8d209861 456without protobuf support. Refer to :ref:`zebra_FIB_push_interface` for more
42fc5d26
QY
457information.
458
459.. _Virtual_Terminal_Interfaces:
460
461Virtual Terminal Interfaces
462===========================
463
464VTY -- Virtual Terminal [aka TeletYpe] Interface is a command line
465interface (CLI) for user interaction with the routing daemon.
466
467.. _VTY_Overview:
468
469VTY Overview
470------------
471
8d209861 472VTY stands for Virtual TeletYpe interface. It means you can connect to
42fc5d26
QY
473the daemon via the telnet protocol.
474
8d209861 475To enable a VTY interface, you have to setup a VTY password. If there
42fc5d26
QY
476is no VTY password, one cannot connect to the VTY interface at all.
477
478::
479
42fc5d26
QY
480 % telnet localhost 2601
481 Trying 127.0.0.1...
482 Connected to localhost.
483 Escape character is '^]'.
484
be46d288
QY
485 Hello, this is |PACKAGE_NAME| (version |PACKAGE_VERSION|)
486 |COPYRIGHT_STR|
42fc5d26
QY
487
488 User Access Verification
489
490 Password: XXXXX
491 Router> ?
8d209861
QY
492 enable . . . Turn on privileged commands
493 exit . . . Exit current mode and down to previous mode
494 help . . . Description of the interactive help system
495 list . . . Print command list
496 show . . . Show system inform
497
498 wh. . . Display who is on a vty
42fc5d26
QY
499 Router> enable
500 Password: XXXXX
501 Router# configure terminal
502 Router(config)# interface eth0
503 Router(config-if)# ip address 10.0.0.1/8
504 Router(config-if)# ^Z
505 Router#
42fc5d26 506
8d209861
QY
507
508:kbd:`?` is very useful for looking up commands.
42fc5d26
QY
509
510.. _VTY_Modes:
511
512VTY Modes
513---------
514
515There are three basic VTY modes:
516
517There are commands that may be restricted to specific VTY modes.
518
519.. _VTY_View_Mode:
520
521VTY View Mode
522^^^^^^^^^^^^^
523
524This mode is for read-only access to the CLI. One may exit the mode by
525leaving the system, or by entering `enable` mode.
526
527.. _VTY_Enable_Mode:
528
529VTY Enable Mode
530^^^^^^^^^^^^^^^
531
532This mode is for read-write access to the CLI. One may exit the mode by
533leaving the system, or by escaping to view mode.
534
535.. _VTY_Other_Modes:
536
537VTY Other Modes
538^^^^^^^^^^^^^^^
539
540This page is for describing other modes.
541
542.. _VTY_CLI_Commands:
543
544VTY CLI Commands
545----------------
546
547Commands that you may use at the command-line are described in the following
548three subsubsections.
549
550.. _CLI_Movement_Commands:
551
552CLI Movement Commands
553^^^^^^^^^^^^^^^^^^^^^
554
555These commands are used for moving the CLI cursor. The :kbd:`C` character
556means press the Control Key.
557
8d209861 558:kbd:`C-f` / :kbd:`LEFT`
42fc5d26
QY
559 Move forward one character.
560
8d209861 561:kbd:`C-b` / :kbd:`RIGHT`
42fc5d26
QY
562 Move backward one character.
563
8d209861 564:kbd:`M-f`
42fc5d26
QY
565 Move forward one word.
566
8d209861 567:kbd:`M-b`
42fc5d26
QY
568 Move backward one word.
569
8d209861 570:kbd:`C-a`
42fc5d26
QY
571 Move to the beginning of the line.
572
8d209861 573:kbd:`C-e`
42fc5d26
QY
574 Move to the end of the line.
575
576
577.. _CLI_Editing_Commands:
578
579CLI Editing Commands
580^^^^^^^^^^^^^^^^^^^^
581
582These commands are used for editing text on a line. The :kbd:`C`
583character means press the Control Key.
584
585
8d209861 586:kbd:`C-h` / :kbd:`DEL`
42fc5d26
QY
587 Delete the character before point.
588
589
8d209861 590:kbd:`C-d`
42fc5d26
QY
591 Delete the character after point.
592
593
8d209861 594:kbd:`M-d`
42fc5d26
QY
595 Forward kill word.
596
597
8d209861 598:kbd:`C-w`
42fc5d26
QY
599 Backward kill word.
600
601
8d209861 602:kbd:`C-k`
42fc5d26
QY
603 Kill to the end of the line.
604
605
8d209861 606:kbd:`C-u`
42fc5d26
QY
607 Kill line from the beginning, erasing input.
608
609
8d209861 610:kbd:`C-t`
42fc5d26
QY
611 Transpose character.
612
613
614CLI Advanced Commands
615^^^^^^^^^^^^^^^^^^^^^
616
617There are several additional CLI commands for command line completions,
618insta-help, and VTY session management.
619
620
8d209861 621:kbd:`C-c`
42fc5d26
QY
622 Interrupt current input and moves to the next line.
623
624
8d209861 625:kbd:`C-z`
42fc5d26
QY
626 End current configuration session and move to top node.
627
628
8d209861 629:kbd:`C-n` / :kbd:`DOWN`
42fc5d26
QY
630 Move down to next line in the history buffer.
631
632
8d209861 633:kbd:`C-p` / :kbd:`UP`
42fc5d26
QY
634 Move up to previous line in the history buffer.
635
636
8d209861 637:kbd:`TAB`
42fc5d26
QY
638 Use command line completion by typing :kbd:`TAB`.
639
640
8d209861 641:kbd:`?`
42fc5d26 642 You can use command line help by typing `help` at the beginning of
8d209861 643 the line. Typing :kbd:`?` at any point in the line will show possible
42fc5d26
QY
644 completions.
645