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

     This also means the hostname and banner motd commands (which both do have effect for vtysh) need to be manually updated in vtysh.conf.

Permissions and setup requirements
==================================

vtysh connects to running daemons through Unix sockets located in 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.

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.

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.  No security guarantees are
made for this configuration.

 -- 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 vtysh and a "nopassword" entry is found, no calls to PAM will be made at all.

Integrated configuration mode
=============================

Integrated configuration mode uses a single configuration file, frr.conf, for all daemons.  This replaces the individual files like zebra.conf or bgpd.conf.

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 frr.conf and apply its settings to the individual daemons.

     vtysh -b must also be executed after restarting any daemon.

Configuration saving, file ownership and permissions
----------------------------------------------------

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

     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.

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 frr.conf.

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.

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.

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.

 -- Command: service integrated-vtysh-config
 -- Command: no service integrated-vtysh-config

     Control whether integrated frr.conf file is written when 'write file' is issued.

     These commands need to be placed in vtysh.conf to have any effect. Note that since 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

          vtysh will always write frr.conf.

       * no service integrated-vtysh-config

          vtysh will never write frr.conf; instead it will ask daemons to write their individual configuration files.

       * Neither option present (default)

          vtysh will check whether 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.

 -- Command: write integrated

     Unconditionally (regardless of service integrated-vtysh-config setting) write out integrated frr.conf file through watchfrr.  If watchfrr is not running, this command is unavailable.

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 frr.conf). This is particularly troublesome for route-maps and prefix lists, which would otherwise be synchronized between daemons.