doc: vtysh doc updates

2 files changed, 138 insertions, 37 deletions

diff --git a/doc/defines.texi.in b/doc/defines.texi.in
index a4badef0e..5436f20c3 100644
--- a/doc/defines.texi.in
+++ b/doc/defines.texi.in
@@ -13,3 +13,4 @@
 @set INSTALL_PREFIX_ETC /etc/quagga
 @set INSTALL_PREFIX_SBIN /usr/sbin
 @set INSTALL_PREFIX_STATE /var/run/quagga
+@set INSTALL_VTY_GROUP @enable_vty_group@
diff --git a/doc/vtysh.texi b/doc/vtysh.texi
index 66562a96c..69b7acd3b 100644
--- a/doc/vtysh.texi
+++ b/doc/vtysh.texi
@@ -1,56 +1,105 @@
 @node VTY shell
 @chapter VTY shell
 
-@command{vtysh} is integrated shell of Quagga software.
+@menu
+* Integrated configuration mode::
+@end menu
 
-To use vtysh please specify ---enable-vtysh to configure script.  To use
-PAM for authentication use ---with-libpam option to configure script.
+@command{vtysh} provides a combined frontend to all Quagga daemons in a
+single combined session.  It is enabled by default at build time, but can
+be disabled through the @option{--disable-vtysh} option to
+@command{./configure}.
+
+@command{vtysh} has a configuration file, @file{vtysh.conf}.  The location
+of that file cannot be changed from @file{@value{INSTALL_PREFIX_ETC}} since
+it contains options controlling authentication behavior.  This file will
+also not be written by configuration-save commands, it is intended to be
+updated manually by an administrator with an external editor.
+
+@quotation Warning
+This also means the @command{hostname} and @command{banner motd} commands
+(which both do have effect for vtysh) need to be manually updated in
+@file{vtysh.conf}.
+@end quotation
+
+@section Permissions and setup requirements
+
+@command{vtysh} connects to running daemons through Unix sockets located in
+@file{@value{INSTALL_PREFIX_STATE}}.  Running vtysh thus requires access to
+that directory, plus membership in the @emph{@value{INSTALL_VTY_GROUP}}
+group (which is the group that the daemons will change ownership of their
+sockets to).
+
+To restrict access to Quagga configuration, make sure no unauthorized users
+are members of the @emph{@value{INSTALL_VTY_GROUP}} group.
+
+@subsection PAM support (experimental)
+
+vtysh has working (but rather useless) PAM support.  It will perform
+an "authenticate" PAM call using @emph{@value{PACKAGE_NAME}} as service
+name. No other (accounting, session, password change) calls will be
+performed by vtysh.
+
+Users using vtysh still need to have appropriate access to the daemons'
+VTY sockets, usually by being member of the @emph{@value{INSTALL_VTY_GROUP}}
+group.  If they have this membership, PAM support is useless since they can
+connect to daemons and issue commands using some other tool.  Alternatively,
+the @command{vtysh} binary could be made SGID (set group ID) to the
+@emph{@value{INSTALL_VTY_GROUP}} group.  @strong{No security guarantees are
+made for this configuration}.
 
-vtysh only searches @value{INSTALL_PREFIX_ETC} path for vtysh.conf which
-is the vtysh configuration file.  Vtysh does not search current
-directory for configuration file because the file includes user
-authentication settings.
+@deffn {Command} {username @var{username} nopassword} {}
 
-Currently, vtysh.conf has only two commands.
+If PAM support is enabled at build-time, this command allows disabling the
+use of PAM on a per-user basis.  If vtysh finds that an user is trying to
+use vtysh and a "nopassword" entry is found, no calls to PAM will be made
+at all.
 
-@menu
-* VTY shell username::
-* VTY shell integrated configuration::
-@end menu
+@end deffn
 
-@node VTY shell username
-@section VTY shell username
+@node Integrated configuration mode
+@section Integrated configuration mode
 
-@deffn {Command} {username @var{username} nopassword} {}
+Integrated configuration mode uses a single configuration file,
+@file{Quagga.conf}, for all daemons.  This replaces the individual files like
+@file{zebra.conf} or @file{bgpd.conf}.
 
-With this set, user foo does not need password authentication for user vtysh.
-With PAM vtysh uses PAM authentication mechanism.
+@file{Quagga.conf} is located in @file{@value{INSTALL_PREFIX_ETC}}.  All
+daemons check for the existence of this file at startup, and if it exists
+will not load their individual configuration files.  Instead,
+@command{vtysh -b} must be invoked to process @file{Quagga.conf} and apply
+its settings to the individual daemons.
 
-If vtysh is compiled without PAM authentication, every user can use vtysh
-without authentication. vtysh requires read/write permission
-to the various daemons vty sockets, this can be accomplished through use
-of unix groups and the --enable-vty-group configure option.
+@quotation Warning
+@command{vtysh -b} must also be executed after restarting any daemon.
+@end quotation
 
-@end deffn
+@subsection Configuration saving, file ownership and permissions
 
-@node VTY shell integrated configuration
-@section VTY shell integrated configuration
+The @file{Quagga.conf} file is not written by any of the daemons; instead
+@command{vtysh} contains the neccessary logic to collect configuration from
+all of the daemons, combine it and write it out.
 
-@deffn {Command} {service integrated-vtysh-config} {}
-Write out integrated Quagga.conf file when 'write file' is issued.
+@quotation Warning
+Daemons must be running for @command{vtysh} to be able to collect their
+configuration.  Any configuration from non-running daemons is permanently
+lost after doing a configuration save.
+@end quotation
+
+Since the @command{vtysh} command may be running as ordinary user on the
+system, configuration writes will be tried through @command{watchquagga},
+using the @command{write integrated} command internally.  Since
+@command{watchquagga} is running as superuser, @command{vtysh} is able to
+ensure correct ownership and permissions on @file{Quagga.conf}.
 
-This command controls the behaviour of vtysh when it is told to write out
-the configuration.  Per default, vtysh will instruct each daemon to write
-out their own config files when @command{write file} is issued.  However, if
-@command{service integrated-vtysh-config} is set, when @command{write file}
-is issued, vtysh will instruct the daemons will write out a Quagga.conf with
-all daemons' commands integrated into it. 
+If @command{watchquagga} is not running or the configuration write fails,
+@command{vtysh} will attempt to directly write to the file.  This is likely
+to fail if running as unprivileged user;  alternatively it may leave the
+file with incorrect owner or permissions.
 
-Vtysh per default behaves as if @command{write-conf daemon} is set. Note
-that both may be set at same time if one wishes to have both Quagga.conf and
-daemon specific files written out. Further, note that the daemons are
-hard-coded to first look for the integrated Quagga.conf file before looking
-for their own file.
+Writing the configuration can be triggered directly by invoking
+@command{vtysh -w}.  This may be useful for scripting.  Note this command
+should be run as either the superuser or the Quagga user.
 
 We recommend you do not mix the use of the two types of files. Further, it
 is better not to use the integrated Quagga.conf file, as any syntax error in
@@ -58,4 +107,55 @@ it can lead to /all/ of your daemons being unable to start up. Per daemon
 files are more robust as impact of errors in configuration are limited to
 the daemon in whose file the error is made.
 
+@deffn {Command} {service integrated-vtysh-config} {}
+@deffnx {Command} {no service integrated-vtysh-config} {}
+
+Control whether integrated @file{Quagga.conf} file is written when
+'write file' is issued.
+
+These commands need to be placed in @file{vtysh.conf} to have any effect.
+Note that since @file{vtysh.conf} is not written by Quagga itself, they
+therefore need to be manually placed in that file.
+
+This command has 3 states:
+@itemize @bullet
+@item
+@command{service integrated-vtysh-config}
+
+@command{vtysh} will always write @file{Quagga.conf}.
+
+@item
+@command{no service integrated-vtysh-config}
+
+@command{vtysh} will never write @file{Quagga.conf}; instead it will ask
+daemons to write their individual configuration files.
+
+@item
+Neither option present (default)
+
+@command{vtysh} will check whether @file{Quagga.conf} exists.  If it does,
+configuration writes will update that file.  Otherwise, writes are performed
+through the individual daemons.
+@end itemize
+
+This command is primarily intended for packaging/distribution purposes, to
+preset one of the two operating modes and ensure consistent operation across
+installations.
 @end deffn
+
+@deffn {Command} {write integrated} {}
+
+Unconditionally (regardless of @command{service integrated-vtysh-config}
+setting) write out integrated @file{Quagga.conf} file through
+@command{watchquagga}.  If @command{watchquagga} is not running, this command
+is unavailable.
+
+@end deffn
+
+@section Caveats
+
+Configuration changes made while some daemon is not running will be invisible
+to that daemon.  The daemon will start up with its saved configuration
+(either in its individual configuration file, or in @file{Quagga.conf}).
+This is particularly troublesome for route-maps and prefix lists, which would
+otherwise be synchronized between daemons.