doc: manually finish conversion

Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>

1 files changed, 101 insertions, 109 deletions

diff --git a/doc/user/vtysh.rst b/doc/user/vtysh.rst
index d94eba110..eeb856cbd 100644
--- a/doc/user/vtysh.rst
+++ b/doc/user/vtysh.rst
@@ -4,56 +4,58 @@
 VTY shell
 *********
 
-*vtysh* provides a combined frontend to all FRR daemons in a
-single combined session.  It is enabled by default at build time, but can
-be disabled through the *--disable-vtysh* option to
-*./configure*.
-
-*vtysh* has a configuration file, :file:`vtysh.conf`.  The location
-of that file cannot be changed from :file:`|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 *hostname* and *banner motd* commands
-(which both do have effect for vtysh) need to be manually updated in
-:file:`vtysh.conf`.
-@end quotation
+.. program:: configure
+
+*vtysh* provides a combined frontend to all FRR 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 the configure script.
+
+*vtysh* has a configuration file, :file:`vtysh.conf`. The location of that
+file cannot be changed from |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.
+
+.. warning::
+
+   This also means the ``hostname`` and ``banner motd`` commands (which both do
+   have effect for vtysh) need to be manually updated in :file:`vtysh.conf`.
+
 
 Permissions and setup requirements
 ==================================
 
 *vtysh* connects to running daemons through Unix sockets located in
-:file:`|INSTALL_PREFIX_STATE|`.  Running vtysh thus requires access to
-that directory, plus membership in the *|INSTALL_VTY_GROUP|*
-group (which is the group that the daemons will change ownership of their
-sockets to).
+|INSTALL_PREFIX_STATE|. Running vtysh thus requires access to that directory,
+plus membership in the |INSTALL_VTY_GROUP| group (which is the group that the
+daemons will change ownership of their sockets to).
 
-To restrict access to FRR configuration, make sure no unauthorized users
-are members of the *|INSTALL_VTY_GROUP|* group.
+To restrict access to FRR configuration, make sure no unauthorized users are
+members of the |INSTALL_VTY_GROUP| group.
 
 PAM support (experimental)
 --------------------------
 
-vtysh has working (but rather useless) PAM support.  It will perform
-an "authenticate" PAM call using *|PACKAGE_NAME|* as service
-name. No other (accounting, session, password change) calls will be
-performed by vtysh.
+vtysh has working (but rather useless) PAM support. It will perform an
+"authenticate" PAM call using |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 |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 *vtysh* binary
+could be made SGID (set group ID) to the |INSTALL_VTY_GROUP| group.
+
+.. warning::
+
+   No security guarantees are made for this configuration.
 
-Users using vtysh still need to have appropriate access to the daemons'
-VTY sockets, usually by being member of the *|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 *vtysh* binary could be made SGID (set group ID) to the
-*|INSTALL_VTY_GROUP|* group.  @strong{No security guarantees are
-made for this configuration}.
 
-.. index:: {Command} {username `username` nopassword} {}
+.. index:: username USERNAME nopassword
+.. clicmd:: username USERNAME nopassword
 
-{Command} {username `username` nopassword} {}
   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 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.
 
@@ -64,108 +66,98 @@ Integrated configuration mode
 =============================
 
 Integrated configuration mode uses a single configuration file,
-:file:`frr.conf`, for all daemons.  This replaces the individual files like
+:file:`frr.conf`, for all daemons. This replaces the individual files like
 :file:`zebra.conf` or :file:`bgpd.conf`.
 
-:file:`frr.conf` is located in :file:`|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,
-*vtysh -b* must be invoked to process :file:`frr.conf` and apply
-its settings to the individual daemons.
+:file:`frr.conf` is located in |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, ``vtysh -b`` must be invoked to
+process :file:`frr.conf` and apply its settings to the individual daemons.
+
+.. warning::
+
+   *vtysh -b* must also be executed after restarting any daemon.
 
-@quotation Warning
-*vtysh -b* must also be executed after restarting any daemon.
-@end quotation
 
 Configuration saving, file ownership and permissions
 ----------------------------------------------------
 
-The :file:`frr.conf` file is not written by any of the daemons; instead
-*vtysh* contains the neccessary logic to collect configuration from
-all of the daemons, combine it and write it out.
+The :file:`frr.conf` file is not written by any of the daemons; instead *vtysh*
+contains the neccessary logic to collect configuration from all of the daemons,
+combine it and write it out.
 
-@quotation Warning
-Daemons must be running for *vtysh* to be able to collect their
-configuration.  Any configuration from non-running daemons is permanently
-lost after doing a configuration save.
-@end quotation
+.. warning::
 
-Since the *vtysh* command may be running as ordinary user on the
-system, configuration writes will be tried through *watchfrr*,
-using the *write integrated* command internally.  Since
-*watchfrr* is running as superuser, *vtysh* is able to
-ensure correct ownership and permissions on :file:`frr.conf`.
+   Daemons must be running for *vtysh* to be able to collect their
+   configuration. Any configuration from non-running daemons is permanently
+   lost after doing a configuration save.
 
-If *watchfrr* is not running or the configuration write fails,
-*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.
+Since the *vtysh* command may be running as ordinary user on the system,
+configuration writes will be tried through *watchfrr*, using the ``write
+integrated`` command internally. Since *watchfrr* is running as superuser,
+*vtysh* is able to ensure correct ownership and permissions on
+:file:`frr.conf`.
 
-Writing the configuration can be triggered directly by invoking
-*vtysh -w*.  This may be useful for scripting.  Note this command
-should be run as either the superuser or the FRR user.
+If *watchfrr* is not running or the configuration write fails, *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.
 
-We recommend you do not mix the use of the two types of files. Further, it
-is better not to use the integrated frr.conf file, as any syntax error in
-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.
+Writing the configuration can be triggered directly by invoking *vtysh -w*.
+This may be useful for scripting. Note this command should be run as either the
+superuser or the FRR user.
 
-.. index:: {Command} {service integrated-vtysh-config} {}
+We recommend you do not mix the use of the two types of files. Further, it is
+better not to use the integrated :file:`frr.conf` file, as any syntax error in
+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.
 
-{Command} {service integrated-vtysh-config} {}
-.. index:: {Command} {no service integrated-vtysh-config} {}
+.. index:: service integrated-vtysh-config
+.. clicmd:: service integrated-vtysh-config
 
-{Command} {no service integrated-vtysh-config} {}
-    Control whether integrated :file:`frr.conf` file is written when
-    'write file' is issued.
+.. index:: no service integrated-vtysh-config
+.. clicmd:: no service integrated-vtysh-config
 
-    These commands need to be placed in :file:`vtysh.conf` to have any effect.
-    Note that since :file:`vtysh.conf` is not written by FRR itself, they
-    therefore need to be manually placed in that file.
+   Control whether integrated :file:`frr.conf` file is written when
+   'write file' is issued.
 
-    This command has 3 states:
+   These commands need to be placed in :file:`vtysh.conf` to have any effect.
+   Note that since :file:`vtysh.conf` is not written by FRR itself, they
+   therefore need to be manually placed in that file.
 
+   This command has 3 states:
 
-``
-      *service integrated-vtysh-config*
 
+   service integrated-vtysh-config
       *vtysh* will always write :file:`frr.conf`.
 
 
-``
-      *no service integrated-vtysh-config*
-
+   no service integrated-vtysh-config
       *vtysh* will never write :file:`frr.conf`; instead it will ask
       daemons to write their individual configuration files.
 
-
-``
-      Neither option present (default)
-
-      *vtysh* will check whether :file:`frr.conf` exists.  If it does,
-      configuration writes will update that file.  Otherwise, writes are performed
+   Neither option present (default)
+      *vtysh* will check whether :file:`frr.conf` exists. If it does,
+      configuration writes will update that file. Otherwise, writes are performed
       through the individual daemons.
 
-    This command is primarily intended for packaging/distribution purposes, to
-    preset one of the two operating modes and ensure consistent operation across
-    installations.
-
-.. index:: {Command} {write integrated} {}
-
-{Command} {write integrated} {}
-    Unconditionally (regardless of *service integrated-vtysh-config*
-    setting) write out integrated :file:`frr.conf` file through
-    *watchfrr*.  If *watchfrr* is not running, this command
-    is unavailable.
+   This command is primarily intended for packaging/distribution purposes, to
+   preset one of the two operating modes and ensure consistent operation across
+   installations.
 
+.. index:: write integrated
+.. clicmd:: write integrated
 
-Caveats
-=======
+   Unconditionally (regardless of ``service integrated-vtysh-config`` setting)
+   write out integrated :file:`frr.conf` file through *watchfrr*. If *watchfrr*
+   is not running, this command is unavailable.
 
-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:`frr.conf`).
-This is particularly troublesome for route-maps and prefix lists, which would
-otherwise be synchronized between daemons.
+.. warning::
 
+   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:`frr.conf`).  This is particularly troublesome for route-maps and
+   prefix lists, which would otherwise be synchronized between daemons.
+