Import Upstream version 1.2.2

[quagga-debian.git] / doc / basic.texi

@node Basic commands
@chapter Basic commands

There are five routing daemons in use, and there is one manager daemon.
These daemons may be located on separate machines from the manager
daemon.  Each of these daemons will listen on a particular port for
incoming VTY connections.  The routing daemons are:

@itemize @bullet
@item @command{ripd}, @command{ripngd}, @command{ospfd}, @command{ospf6d}, @command{bgpd}
@item @command{zebra}
@end itemize

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

@menu
* Config Commands::             Commands used in config files
* Terminal Mode Commands::      Common commands used in a VTY
* Common Invocation Options::   Starting the daemons
* Virtual Terminal Interfaces:: Interacting with the daemons
@end menu



@node Config Commands
@section Config Commands

@cindex Configuration files for running the software
@c A -not configuration files for installing the software
@cindex Files for running configurations
@cindex Modifying the herd's behavior
@cindex Getting the herd running


@menu
* Basic Config Commands::       Some of the generic config commands
* Sample Config File::          An example config file
@end menu


In a 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 files are generally found in:

@itemize @w{}
@item @file{@value{INSTALL_PREFIX_ETC}/*.conf}
@end itemize

Each of the daemons has its own
config file.  For example, zebra's default config file name is:

@itemize @w{}
@item @file{@value{INSTALL_PREFIX_ETC}/zebra.conf}
@end itemize

The daemon name plus @file{.conf} is the default config file name. You
can specify a config file using the @kbd{-f} or @kbd{--config-file}
options when starting the daemon.



@node Basic Config Commands
@subsection Basic Config Commands

@deffn Command {hostname @var{hostname}} {}
Set hostname of the router.
@end deffn

@deffn Command {password @var{password}} {}
Set password for vty interface.  If there is no password, a vty won't
accept connections.
@end deffn

@deffn Command {enable password @var{password}} {}
Set enable password.
@end deffn

@deffn Command {log trap @var{level}} {}
@deffnx Command {no log trap} {}
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 @code{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.
@end deffn


@deffn Command {log stdout} {}
@deffnx Command {log stdout @var{level}} {}
@deffnx Command {no log stdout} {}
Enable logging output to stdout. 
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 @code{log trap} command) will be used.
The @code{no} form of the command disables logging to stdout.
The @code{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 @code{errors}.
@end deffn

@deffn Command {log file @var{filename}} {}
@deffnx Command {log file @var{filename} @var{level}} {}
@deffnx Command {no log file} {}
If you want to log into a file, please specify @code{filename} as
in this example:
@example
log file /var/log/quagga/bgpd.log informational
@end example
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 @code{log trap} command) will be used.
The @code{no} form of the command disables logging to a file.

Note: if you do not configure any file logging, and a daemon crashes due
to a signal or an assertion failure, it will attempt to save the crash
information in a file named /var/tmp/quagga.<daemon name>.crashlog.
For security reasons, this will not happen if the file exists already, so
it is important to delete the file after reporting the crash information.
@end deffn

@deffn Command {log syslog} {}
@deffnx Command {log syslog @var{level}} {}
@deffnx Command {no log syslog} {}
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 @code{log trap} command) will be used.
The @code{no} form of the command disables logging to syslog.
@end deffn

@deffn Command {log monitor} {}
@deffnx Command {log monitor @var{level}} {}
@deffnx Command {no log monitor} {}
Enable logging output to vty terminals that have enabled logging
using the @code{terminal monitor} command.
By default, monitor logging is enabled at the debugging level, but this
command (or the deprecated @code{log trap} command) can be used to change 
the monitor logging level.
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 @code{log trap} command) will be used.
The @code{no} form of the command disables logging to terminal monitors.
@end deffn

@deffn Command {log facility @var{facility}} {}
@deffnx Command {no log facility} {}
This command changes the facility used in syslog messages.  The default
facility is @code{daemon}.  The @code{no} form of the command resets
the facility to the default @code{daemon} facility.
@end deffn

@deffn Command {log record-priority} {}
@deffnx Command {no 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 @code{log record-priority} global configuration command.
To disable this option, use the @code{no} form of the command.  By default,
the severity level is not included in logged messages.  Note: some
versions of syslogd (including Solaris) can be configured to include
the facility and level in the messages emitted.
@end deffn

@deffn Command {log timestamp precision @var{<0-6>}} {}
@deffnx Command {no log timestamp precision} {}
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
@code{no} form of the command, or set the precision explicitly to 0.

@example
@group
log timestamp precision 3
@end group
@end example

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

@deffn Command {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.  Once set, command logging can only
be turned off by restarting the daemon.
@end deffn  

@deffn Command {service password-encryption} {}
Encrypt password.
@end deffn

@deffn Command {service advanced-vty} {}
Enable advanced mode VTY.
@end deffn

@deffn Command {service terminal-length @var{<0-512>}} {}
Set system wide line configuration.  This configuration command applies
to all VTY interfaces.
@end deffn

@deffn Command {line vty} {}
Enter vty configuration mode.
@end deffn

@deffn Command {banner motd default} {}
Set default motd string.
@end deffn

@deffn Command {no banner motd} {}
No motd banner string will be printed.
@end deffn

@deffn {Line Command} {exec-timeout @var{minute}} {}
@deffnx {Line Command} {exec-timeout @var{minute} @var{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.
@end deffn

@deffn {Line Command} {no exec-timeout} {}
Do not perform timeout at all.  This command is as same as
@command{exec-timeout 0 0}.
@end deffn

@deffn {Line Command} {access-class @var{access-list}} {}
Restrict vty connections with an access list.
@end deffn

@node Sample Config File
@subsection Sample Config File


Below is a sample configuration file for the zebra daemon.

@example
@group
!
! Zebra configuration file
!
hostname Router
password zebra
enable password zebra
!
log stdout
!
!
@end group
@end example

'!' 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.

@example
password zebra!password
@end example

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'.



@node Terminal Mode Commands
@section Terminal Mode Commands

@deffn Command {write terminal} {}
Displays the current configuration to the vty interface.
@end deffn

@deffn Command {write file} {}
Write current configuration to configuration file.
@end deffn

@deffn Command {configure terminal} {}
Change to configuration mode.  This command is the first step to
configuration.
@end deffn

@deffn Command {terminal length @var{<0-512>}} {}
Set terminal display length to @var{<0-512>}.  If length is 0, no
display control is performed.
@end deffn

@deffn Command {who} {}
Show a list of currently connected vty sessions.
@end deffn

@deffn Command {list} {}
List all available commands.
@end deffn

@deffn Command {show version} {}
Show the current version of @value{PACKAGE_NAME} and its build host information.
@end deffn

@deffn Command {show logging} {}
Shows the current configuration of the logging system.  This includes
the status of all logging destinations.
@end deffn

@deffn Command {logmsg @var{level} @var{message}} {}
Send a message to all logging destinations that are enabled for messages
of the given severity.
@end deffn




@node Common Invocation Options
@section Common Invocation Options
@c COMMON_OPTIONS
@c OPTIONS section of the man page

These options apply to all @value{PACKAGE_NAME} daemons.

@table @samp

@item -d
@itemx --daemon
Runs in daemon mode.

@item -f @var{file}
@itemx --config_file=@var{file}
Set configuration file name.

@item -h
@itemx --help
Display this help and exit.

@item -i @var{file}
@itemx --pid_file=@var{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 @command{@dots{}/init.d/zebra status},
@command{@dots{}/init.d/zebra restart} or @command{@dots{}/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 @value{PACKAGE_NAME} to implement a routing looking glass.  One
machine can be used to collect differing routing views from differing
points in the network.

@item -A @var{address}
@itemx --vty_addr=@var{address}
Set the VTY local address to bind to. If set, the VTY socket will only
be bound to this address. 

@item -P @var{port}
@itemx --vty_port=@var{port}
Set the VTY TCP port number. If set to 0 then the TCP VTY sockets will not
be opened.

@item -u @var{user}
@itemx --vty_addr=@var{user}
Set the user and group to run as.

@item -v
@itemx --version
Print program version.

@end table



@node Virtual Terminal Interfaces
@section Virtual Terminal Interfaces

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

@menu
* VTY Overview::                Basics about VTYs                
* VTY Modes::                   View, Enable, and Other VTY modes
* VTY CLI Commands::            Commands for movement, edition, and management
@end menu



@node VTY Overview
@subsection 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.

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

Hello, this is @value{PACKAGE_NAME} (version @value{VERSION})
@value{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 running system information
  who               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#
@end group
@end example

'?' is very useful for looking up commands.

@node VTY Modes
@subsection VTY Modes

There are three basic VTY modes:

@menu
* VTY View Mode::               Mode for read-only interaction               
* VTY Enable Mode::             Mode for read-write interaction
* VTY Other Modes::             Special modes (tftp, etc)
@end menu

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

@node VTY View Mode
@subsubsection VTY View Mode
@c to be written (gpoul)


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

@node VTY Enable Mode
@subsubsection VTY Enable Mode

@c to be written (gpoul)
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.

@node VTY Other Modes
@subsubsection VTY Other Modes


@c to be written (gpoul)
This page is for describing other modes.

@node VTY CLI Commands
@subsection VTY CLI Commands

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

@menu
* CLI Movement Commands::       Commands for moving the cursor about
* CLI Editing Commands::        Commands for changing text
* CLI Advanced Commands::       Other commands, session management and so on
@end menu

@node CLI Movement Commands
@subsubsection CLI Movement Commands

These commands are used for moving the CLI cursor. The @key{C} character
means press the Control Key.

@table @kbd

@item C-f
@itemx @key{RIGHT}
@kindex C-f
@kindex @key{RIGHT}
Move forward one character.

@item C-b
@itemx @key{LEFT}
@kindex C-b
@kindex @key{LEFT}
Move backward one character.

@item M-f
@kindex M-f
Move forward one word.

@item M-b
@kindex M-b
Move backward one word.

@item C-a
@kindex C-a
Move to the beginning of the line.

@item C-e
@kindex C-e
Move to the end of the line.

@end table

@node CLI Editing Commands
@subsubsection CLI Editing Commands

These commands are used for editing text on a line. The @key{C}
character means press the Control Key.

@table @kbd

@item C-h
@itemx @key{DEL}
@kindex C-h
@kindex @key{DEL}
Delete the character before point.

@item C-d
@kindex C-d
Delete the character after point.

@item M-d
@kindex M-d
Forward kill word.

@item C-w
@kindex C-w
Backward kill word.

@item C-k
@kindex C-k
Kill to the end of the line.

@item C-u
@kindex C-u
Kill line from the beginning, erasing input.

@item C-t
@kindex C-t
Transpose character.

@item C-v
@kindex C-v
Interpret following character literally. Do not treat it specially.
This can be used to, e.g., type in a literal @kbd{?} rather than do
help completion.

@end table

@node CLI Advanced Commands
@subsubsection CLI Advanced Commands

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

@table @kbd

@item C-c
@kindex C-c
Interrupt current input and moves to the next line.

@item C-z
@kindex C-z
End current configuration session and move to top node.


@item C-n
@itemx @key{DOWN}
@kindex C-n
@kindex @key{DOWN}
Move down to next line in the history buffer.

@item C-p
@itemx @key{UP}
@kindex C-p
@kindex @key{UP}
Move up to previous line in the history buffer.

@item TAB
@kindex @key{TAB}
Use command line completion by typing @key{TAB}.

@item ?
@kindex @key{?}
You can use command line help by typing @code{help} at the beginning of
the line.  Typing @kbd{?} at any point in the line will show possible
completions.

To enter an actual @kbd{?} character rather show completions, e.g. to
enter into a regexp, use @kbd{@key{C}-v ?}.

@end table