basic.texi 16 KB

  1. @node Basic commands
  2. @chapter Basic commands
  3. There are five routing daemons in use, and there is one manager daemon.
  4. These daemons may be located on separate machines from the manager
  5. daemon. Each of these daemons will listen on a particular port for
  6. incoming VTY connections. The routing daemons are:
  7. @itemize @bullet
  8. @item @command{ripd}, @command{ripngd}, @command{ospfd}, @command{ospf6d}, @command{bgpd}
  9. @item @command{zebra}
  10. @end itemize
  11. The following sections discuss commands common to all the routing
  12. daemons.
  13. @menu
  14. * Config Commands:: Commands used in config files
  15. * Terminal Mode Commands:: Common commands used in a VTY
  16. * Common Invocation Options:: Starting the daemons
  17. * Virtual Terminal Interfaces:: Interacting with the daemons
  18. @end menu
  19. @node Config Commands
  20. @section Config Commands
  21. @cindex Configuration files for running the software
  22. @c A -not configuration files for installing the software
  23. @cindex Files for running configurations
  24. @cindex Modifying the herd's behavior
  25. @cindex Getting the herd running
  26. @menu
  27. * Basic Config Commands:: Some of the generic config commands
  28. * Sample Config File:: An example config file
  29. @end menu
  30. In a config file, you can write the debugging options, a vty's password,
  31. routing daemon configurations, a log file name, and so forth. This
  32. information forms the initial command set for a routing beast as it is
  33. starting.
  34. Config files are generally found in:
  35. @itemize @w{}
  36. @item @file{@value{INSTALL_PREFIX_ETC}/*.conf}
  37. @end itemize
  38. Each of the daemons has its own
  39. config file. For example, zebra's default config file name is:
  40. @itemize @w{}
  41. @item @file{@value{INSTALL_PREFIX_ETC}/zebra.conf}
  42. @end itemize
  43. The daemon name plus @file{.conf} is the default config file name. You
  44. can specify a config file using the @kbd{-f} or @kbd{--config-file}
  45. options when starting the daemon.
  46. @node Basic Config Commands
  47. @subsection Basic Config Commands
  48. @deffn Command {hostname @var{hostname}} {}
  49. Set hostname of the router.
  50. @end deffn
  51. @deffn Command {password @var{password}} {}
  52. Set password for vty interface. If there is no password, a vty won't
  53. accept connections.
  54. @end deffn
  55. @deffn Command {enable password @var{password}} {}
  56. Set enable password.
  57. @end deffn
  58. @deffn Command {log trap @var{level}} {}
  59. @deffnx Command {no log trap} {}
  60. These commands are deprecated and are present only for historical compatibility.
  61. The log trap command sets the current logging level for all enabled
  62. logging destinations, and it sets the default for all future logging commands
  63. that do not specify a level. The normal default
  64. logging level is debugging. The @code{no} form of the command resets
  65. the default level for future logging commands to debugging, but it does
  66. not change the logging level of existing logging destinations.
  67. @end deffn
  68. @deffn Command {log stdout} {}
  69. @deffnx Command {log stdout @var{level}} {}
  70. @deffnx Command {no log stdout} {}
  71. Enable logging output to stdout.
  72. If the optional second argument specifying the
  73. logging level is not present, the default logging level (typically debugging,
  74. but can be changed using the deprecated @code{log trap} command) will be used.
  75. The @code{no} form of the command disables logging to stdout.
  76. The @code{level} argument must have one of these values:
  77. emergencies, alerts, critical, errors, warnings, notifications, informational, or debugging. Note that the existing code logs its most important messages
  78. with severity @code{errors}.
  79. @end deffn
  80. @deffn Command {log file @var{filename}} {}
  81. @deffnx Command {log file @var{filename} @var{level}} {}
  82. @deffnx Command {no log file} {}
  83. If you want to log into a file, please specify @code{filename} as
  84. in this example:
  85. @example
  86. log file /var/log/quagga/bgpd.log informational
  87. @end example
  88. If the optional second argument specifying the
  89. logging level is not present, the default logging level (typically debugging,
  90. but can be changed using the deprecated @code{log trap} command) will be used.
  91. The @code{no} form of the command disables logging to a file.
  92. Note: if you do not configure any file logging, and a daemon crashes due
  93. to a signal or an assertion failure, it will attempt to save the crash
  94. information in a file named /var/tmp/quagga.<daemon name>.crashlog.
  95. For security reasons, this will not happen if the file exists already, so
  96. it is important to delete the file after reporting the crash information.
  97. @end deffn
  98. @deffn Command {log syslog} {}
  99. @deffnx Command {log syslog @var{level}} {}
  100. @deffnx Command {no log syslog} {}
  101. Enable logging output to syslog.
  102. If the optional second argument specifying the
  103. logging level is not present, the default logging level (typically debugging,
  104. but can be changed using the deprecated @code{log trap} command) will be used.
  105. The @code{no} form of the command disables logging to syslog.
  106. @end deffn
  107. @deffn Command {log monitor} {}
  108. @deffnx Command {log monitor @var{level}} {}
  109. @deffnx Command {no log monitor} {}
  110. Enable logging output to vty terminals that have enabled logging
  111. using the @code{terminal monitor} command.
  112. By default, monitor logging is enabled at the debugging level, but this
  113. command (or the deprecated @code{log trap} command) can be used to change
  114. the monitor logging level.
  115. If the optional second argument specifying the
  116. logging level is not present, the default logging level (typically debugging,
  117. but can be changed using the deprecated @code{log trap} command) will be used.
  118. The @code{no} form of the command disables logging to terminal monitors.
  119. @end deffn
  120. @deffn Command {log facility @var{facility}} {}
  121. @deffnx Command {no log facility} {}
  122. This command changes the facility used in syslog messages. The default
  123. facility is @code{daemon}. The @code{no} form of the command resets
  124. the facility to the default @code{daemon} facility.
  125. @end deffn
  126. @deffn Command {log record-priority} {}
  127. @deffnx Command {no log record-priority} {}
  128. To include the severity in all messages logged to a file, to stdout, or to
  129. a terminal monitor (i.e. anything except syslog),
  130. use the @code{log record-priority} global configuration command.
  131. To disable this option, use the @code{no} form of the command. By default,
  132. the severity level is not included in logged messages. Note: some
  133. versions of syslogd (including Solaris) can be configured to include
  134. the facility and level in the messages emitted.
  135. @end deffn
  136. @deffn Command {log timestamp precision @var{<0-6>}} {}
  137. @deffnx Command {no log timestamp precision} {}
  138. This command sets the precision of log message timestamps to the
  139. given number of digits after the decimal point. Currently,
  140. the value must be in the range 0 to 6 (i.e. the maximum precision
  141. is microseconds).
  142. To restore the default behavior (1-second accuracy), use the
  143. @code{no} form of the command, or set the precision explicitly to 0.
  144. @example
  145. @group
  146. log timestamp precision 3
  147. @end group
  148. @end example
  149. In this example, the precision is set to provide timestamps with
  150. millisecond accuracy.
  151. @end deffn
  152. @deffn Command {log commands} {}
  153. This command enables the logging of all commands typed by a user to
  154. all enabled log destinations. The note that logging includes full
  155. command lines, including passwords. Once set, command logging can only
  156. be turned off by restarting the daemon.
  157. @end deffn
  158. @deffn Command {service password-encryption} {}
  159. Encrypt password.
  160. @end deffn
  161. @deffn Command {service advanced-vty} {}
  162. Enable advanced mode VTY.
  163. @end deffn
  164. @deffn Command {service terminal-length @var{<0-512>}} {}
  165. Set system wide line configuration. This configuration command applies
  166. to all VTY interfaces.
  167. @end deffn
  168. @deffn Command {line vty} {}
  169. Enter vty configuration mode.
  170. @end deffn
  171. @deffn Command {banner motd default} {}
  172. Set default motd string.
  173. @end deffn
  174. @deffn Command {no banner motd} {}
  175. No motd banner string will be printed.
  176. @end deffn
  177. @deffn {Line Command} {exec-timeout @var{minute}} {}
  178. @deffnx {Line Command} {exec-timeout @var{minute} @var{second}} {}
  179. Set VTY connection timeout value. When only one argument is specified
  180. it is used for timeout value in minutes. Optional second argument is
  181. used for timeout value in seconds. Default timeout value is 10 minutes.
  182. When timeout value is zero, it means no timeout.
  183. @end deffn
  184. @deffn {Line Command} {no exec-timeout} {}
  185. Do not perform timeout at all. This command is as same as
  186. @command{exec-timeout 0 0}.
  187. @end deffn
  188. @deffn {Line Command} {access-class @var{access-list}} {}
  189. Restrict vty connections with an access list.
  190. @end deffn
  191. @node Sample Config File
  192. @subsection Sample Config File
  193. Below is a sample configuration file for the zebra daemon.
  194. @example
  195. @group
  196. !
  197. ! Zebra configuration file
  198. !
  199. hostname Router
  200. password zebra
  201. enable password zebra
  202. !
  203. log stdout
  204. !
  205. !
  206. @end group
  207. @end example
  208. '!' and '#' are comment characters. If the first character of the word
  209. is one of the comment characters then from the rest of the line forward
  210. will be ignored as a comment.
  211. @example
  212. password zebra!password
  213. @end example
  214. If a comment character is not the first character of the word, it's a
  215. normal character. So in the above example '!' will not be regarded as a
  216. comment and the password is set to 'zebra!password'.
  217. @node Terminal Mode Commands
  218. @section Terminal Mode Commands
  219. @deffn Command {write terminal} {}
  220. Displays the current configuration to the vty interface.
  221. @end deffn
  222. @deffn Command {write file} {}
  223. Write current configuration to configuration file.
  224. @end deffn
  225. @deffn Command {configure terminal} {}
  226. Change to configuration mode. This command is the first step to
  227. configuration.
  228. @end deffn
  229. @deffn Command {terminal length @var{<0-512>}} {}
  230. Set terminal display length to @var{<0-512>}. If length is 0, no
  231. display control is performed.
  232. @end deffn
  233. @deffn Command {who} {}
  234. Show a list of currently connected vty sessions.
  235. @end deffn
  236. @deffn Command {list} {}
  237. List all available commands.
  238. @end deffn
  239. @deffn Command {show version} {}
  240. Show the current version of @value{PACKAGE_NAME} and its build host information.
  241. @end deffn
  242. @deffn Command {show logging} {}
  243. Shows the current configuration of the logging system. This includes
  244. the status of all logging destinations.
  245. @end deffn
  246. @deffn Command {logmsg @var{level} @var{message}} {}
  247. Send a message to all logging destinations that are enabled for messages
  248. of the given severity.
  249. @end deffn
  250. @node Common Invocation Options
  251. @section Common Invocation Options
  253. @c OPTIONS section of the man page
  254. These options apply to all @value{PACKAGE_NAME} daemons.
  255. @table @samp
  256. @item -d
  257. @itemx --daemon
  258. Runs in daemon mode.
  259. @item -f @var{file}
  260. @itemx --config_file=@var{file}
  261. Set configuration file name.
  262. @item -h
  263. @itemx --help
  264. Display this help and exit.
  265. @item -i @var{file}
  266. @itemx --pid_file=@var{file}
  267. Upon startup the process identifier of the daemon is written to a file,
  268. typically in @file{/var/run}. This file can be used by the init system
  269. to implement commands such as @command{@dots{}/init.d/zebra status},
  270. @command{@dots{}/init.d/zebra restart} or @command{@dots{}/init.d/zebra
  271. stop}.
  272. The file name is an run-time option rather than a configure-time option
  273. so that multiple routing daemons can be run simultaneously. This is
  274. useful when using @value{PACKAGE_NAME} to implement a routing looking glass. One
  275. machine can be used to collect differing routing views from differing
  276. points in the network.
  277. @item -A @var{address}
  278. @itemx --vty_addr=@var{address}
  279. Set the VTY local address to bind to. If set, the VTY socket will only
  280. be bound to this address.
  281. @item -P @var{port}
  282. @itemx --vty_port=@var{port}
  283. Set the VTY TCP port number. If set to 0 then the TCP VTY sockets will not
  284. be opened.
  285. @item -u @var{user}
  286. @itemx --vty_addr=@var{user}
  287. Set the user and group to run as.
  288. @item -v
  289. @itemx --version
  290. Print program version.
  291. @end table
  292. @node Virtual Terminal Interfaces
  293. @section Virtual Terminal Interfaces
  294. VTY -- Virtual Terminal [aka TeletYpe] Interface is a command line
  295. interface (CLI) for user interaction with the routing daemon.
  296. @menu
  297. * VTY Overview:: Basics about VTYs
  298. * VTY Modes:: View, Enable, and Other VTY modes
  299. * VTY CLI Commands:: Commands for movement, edition, and management
  300. @end menu
  301. @node VTY Overview
  302. @subsection VTY Overview
  303. VTY stands for Virtual TeletYpe interface. It means you can connect to
  304. the daemon via the telnet protocol.
  305. To enable a VTY interface, you have to setup a VTY password. If there
  306. is no VTY password, one cannot connect to the VTY interface at all.
  307. @example
  308. @group
  309. % telnet localhost 2601
  310. Trying
  311. Connected to localhost.
  312. Escape character is '^]'.
  313. Hello, this is @value{PACKAGE_NAME} (version @value{VERSION})
  314. @value{COPYRIGHT_STR}
  315. User Access Verification
  316. Password: XXXXX
  317. Router> ?
  318. enable Turn on privileged commands
  319. exit Exit current mode and down to previous mode
  320. help Description of the interactive help system
  321. list Print command list
  322. show Show running system information
  323. who Display who is on a vty
  324. Router> enable
  325. Password: XXXXX
  326. Router# configure terminal
  327. Router(config)# interface eth0
  328. Router(config-if)# ip address
  329. Router(config-if)# ^Z
  330. Router#
  331. @end group
  332. @end example
  333. '?' is very useful for looking up commands.
  334. @node VTY Modes
  335. @subsection VTY Modes
  336. There are three basic VTY modes:
  337. @menu
  338. * VTY View Mode:: Mode for read-only interaction
  339. * VTY Enable Mode:: Mode for read-write interaction
  340. * VTY Other Modes:: Special modes (tftp, etc)
  341. @end menu
  342. There are commands that may be restricted to specific VTY modes.
  343. @node VTY View Mode
  344. @subsubsection VTY View Mode
  345. @c to be written (gpoul)
  346. This mode is for read-only access to the CLI. One may exit the mode by
  347. leaving the system, or by entering @code{enable} mode.
  348. @node VTY Enable Mode
  349. @subsubsection VTY Enable Mode
  350. @c to be written (gpoul)
  351. This mode is for read-write access to the CLI. One may exit the mode by
  352. leaving the system, or by escaping to view mode.
  353. @node VTY Other Modes
  354. @subsubsection VTY Other Modes
  355. @c to be written (gpoul)
  356. This page is for describing other modes.
  357. @node VTY CLI Commands
  358. @subsection VTY CLI Commands
  359. Commands that you may use at the command-line are described in the following
  360. three subsubsections.
  361. @menu
  362. * CLI Movement Commands:: Commands for moving the cursor about
  363. * CLI Editing Commands:: Commands for changing text
  364. * CLI Advanced Commands:: Other commands, session management and so on
  365. @end menu
  366. @node CLI Movement Commands
  367. @subsubsection CLI Movement Commands
  368. These commands are used for moving the CLI cursor. The @key{C} character
  369. means press the Control Key.
  370. @table @kbd
  371. @item C-f
  372. @itemx @key{RIGHT}
  373. @kindex C-f
  374. @kindex @key{RIGHT}
  375. Move forward one character.
  376. @item C-b
  377. @itemx @key{LEFT}
  378. @kindex C-b
  379. @kindex @key{LEFT}
  380. Move backward one character.
  381. @item M-f
  382. @kindex M-f
  383. Move forward one word.
  384. @item M-b
  385. @kindex M-b
  386. Move backward one word.
  387. @item C-a
  388. @kindex C-a
  389. Move to the beginning of the line.
  390. @item C-e
  391. @kindex C-e
  392. Move to the end of the line.
  393. @end table
  394. @node CLI Editing Commands
  395. @subsubsection CLI Editing Commands
  396. These commands are used for editing text on a line. The @key{C}
  397. character means press the Control Key.
  398. @table @kbd
  399. @item C-h
  400. @itemx @key{DEL}
  401. @kindex C-h
  402. @kindex @key{DEL}
  403. Delete the character before point.
  404. @item C-d
  405. @kindex C-d
  406. Delete the character after point.
  407. @item M-d
  408. @kindex M-d
  409. Forward kill word.
  410. @item C-w
  411. @kindex C-w
  412. Backward kill word.
  413. @item C-k
  414. @kindex C-k
  415. Kill to the end of the line.
  416. @item C-u
  417. @kindex C-u
  418. Kill line from the beginning, erasing input.
  419. @item C-t
  420. @kindex C-t
  421. Transpose character.
  422. @item C-v
  423. @kindex C-v
  424. Interpret following character literally. Do not treat it specially.
  425. This can be used to, e.g., type in a literal @kbd{?} rather than do
  426. help completion.
  427. @end table
  428. @node CLI Advanced Commands
  429. @subsubsection CLI Advanced Commands
  430. There are several additional CLI commands for command line completions,
  431. insta-help, and VTY session management.
  432. @table @kbd
  433. @item C-c
  434. @kindex C-c
  435. Interrupt current input and moves to the next line.
  436. @item C-z
  437. @kindex C-z
  438. End current configuration session and move to top node.
  439. @item C-n
  440. @itemx @key{DOWN}
  441. @kindex C-n
  442. @kindex @key{DOWN}
  443. Move down to next line in the history buffer.
  444. @item C-p
  445. @itemx @key{UP}
  446. @kindex C-p
  447. @kindex @key{UP}
  448. Move up to previous line in the history buffer.
  449. @item TAB
  450. @kindex @key{TAB}
  451. Use command line completion by typing @key{TAB}.
  452. @item ?
  453. @kindex @key{?}
  454. You can use command line help by typing @code{help} at the beginning of
  455. the line. Typing @kbd{?} at any point in the line will show possible
  456. completions.
  457. To enter an actual @kbd{?} character rather show completions, e.g. to
  458. enter into a regexp, use @kbd{@key{C}-v ?}.
  459. @end table