doc/user/vtysh.rst

   1 .. _vty-shell:
   2
   3 *********
   4 VTY shell
   5 *********
   6
   7 .. program:: configure
   8
   9 *vtysh* provides a combined frontend to all FRR daemons in a single combined
  10 session. It is enabled by default at build time, but can be disabled through
  11 the :option:`--disable-vtysh` option to the configure script.
  12
  13 *vtysh* has a configuration file, :file:`vtysh.conf`. The location of that
  14 file cannot be changed from |INSTALL_PREFIX_ETC| since it contains options
  15 controlling authentication behavior. This file will also not be written by
  16 configuration-save commands, it is intended to be updated manually by an
  17 administrator with an external editor.
  18
  19 .. warning::
  20
  21    This also means the ``hostname`` and ``banner motd`` commands (which both do
  22    have effect for vtysh) need to be manually updated in :file:`vtysh.conf`.
  23
  24
  25 .. index:: copy FILENAME running-config
  26 .. clicmd:: copy FILENAME running-config
  27
  28    Process and load a configuration file manually; each line in the
  29    file is read and processed as if it were being typed (or piped) to
  30    vtysh.
  31
  32
  33 Pager usage
  34 ===========
  35
  36 *vtysh* can call an external paging program (e.g. *more* or *less*) to
  37 paginate long output from commands.  This feature used to be enabled by
  38 default but is now controlled by the ``VTYSH_PAGER`` environment variable
  39 and the :clicmd:`terminal paginate` command:
  40
  41 .. envvar:: VTYSH_PAGER
  42
  43    If set, the ``VTYSH_PAGER`` environment variable causes *vtysh* to pipe
  44    output from commands through the given command.  Note that this happens
  45    regardless of the length of the output.  As such, standard pager behavior
  46    (particularly waiting at the end of output) tends to be annoying to the
  47    user.  Using ``less -EFX`` is recommended for a better user experience.
  48
  49    If this environment variable is unset, *vtysh* defaults to not using any
  50    pager.
  51
  52    This variable should be set by the user according to their preferences,
  53    in their :file:`~/.profile` file.
  54
  55 .. index:: [no] terminal paginate
  56 .. clicmd:: [no] terminal paginate
  57
  58    Enables/disables vtysh output pagination.  This command is intended to
  59    be placed in :file:`vtysh.conf` to set a system-wide default.  If this
  60    is enabled but ``VTYSH_PAGER`` is not set, the system default pager
  61    (likely ``more`` or ``/usr/bin/pager``) will be used.
  62
  63
  64 Permissions and setup requirements
  65 ==================================
  66
  67 *vtysh* connects to running daemons through Unix sockets located in
  68 |INSTALL_PREFIX_STATE|. Running vtysh thus requires access to that directory,
  69 plus membership in the |INSTALL_VTY_GROUP| group (which is the group that the
  70 daemons will change ownership of their sockets to).
  71
  72 To restrict access to FRR configuration, make sure no unauthorized users are
  73 members of the |INSTALL_VTY_GROUP| group.
  74
  75 .. warning::
  76
  77    VTYSH implements a CLI option ``-u, --user`` that disallows entering the
  78    characters "en" on the command line, which ideally restricts access to
  79    configuration commands. However, VTYSH was never designed to be a privilege
  80    broker and is not built using secure coding practices. No guarantees of
  81    security are provided for this option and under no circumstances should this
  82    option be used to provide any semblance of security or read-only access to
  83    FRR.
  84
  85 PAM support (experimental)
  86 --------------------------
  87
  88 vtysh has working (but rather useless) PAM support. It will perform an
  89 "authenticate" PAM call using |PACKAGE_NAME| as service name. No other
  90 (accounting, session, password change) calls will be performed by vtysh.
  91
  92 Users using vtysh still need to have appropriate access to the daemons' VTY
  93 sockets, usually by being member of the |INSTALL_VTY_GROUP| group. If they
  94 have this membership, PAM support is useless since they can connect to daemons
  95 and issue commands using some other tool. Alternatively, the *vtysh* binary
  96 could be made SGID (set group ID) to the |INSTALL_VTY_GROUP| group.
  97
  98 .. warning::
  99
 100    No security guarantees are made for this configuration.
 101
 102
 103 .. index:: username USERNAME nopassword
 104 .. clicmd:: username USERNAME nopassword
 105
 106   If PAM support is enabled at build-time, this command allows disabling the
 107   use of PAM on a per-user basis. If vtysh finds that an user is trying to
 108   use vtysh and a "nopassword" entry is found, no calls to PAM will be made
 109   at all.
 110
 111
 112 .. _integrated-configuration-mode:
 113
 114 Integrated configuration mode
 115 =============================
 116
 117 Integrated configuration mode uses a single configuration file,
 118 :file:`frr.conf`, for all daemons. This replaces the individual files like
 119 :file:`zebra.conf` or :file:`bgpd.conf`.
 120
 121 :file:`frr.conf` is located in |INSTALL_PREFIX_ETC|. All daemons check for the
 122 existence of this file at startup, and if it exists will not load their
 123 individual configuration files. Instead, ``vtysh -b`` must be invoked to
 124 process :file:`frr.conf` and apply its settings to the individual daemons.
 125
 126 .. warning::
 127
 128    *vtysh -b* must also be executed after restarting any daemon.
 129
 130
 131 Configuration saving, file ownership and permissions
 132 ----------------------------------------------------
 133
 134 The :file:`frr.conf` file is not written by any of the daemons; instead *vtysh*
 135 contains the necessary logic to collect configuration from all of the daemons,
 136 combine it and write it out.
 137
 138 .. warning::
 139
 140    Daemons must be running for *vtysh* to be able to collect their
 141    configuration. Any configuration from non-running daemons is permanently
 142    lost after doing a configuration save.
 143
 144 Since the *vtysh* command may be running as ordinary user on the system,
 145 configuration writes will be tried through *watchfrr*, using the ``write
 146 integrated`` command internally. Since *watchfrr* is running as superuser,
 147 *vtysh* is able to ensure correct ownership and permissions on
 148 :file:`frr.conf`.
 149
 150 If *watchfrr* is not running or the configuration write fails, *vtysh* will
 151 attempt to directly write to the file. This is likely to fail if running as
 152 unprivileged user; alternatively it may leave the file with incorrect owner or
 153 permissions.
 154
 155 Writing the configuration can be triggered directly by invoking *vtysh -w*.
 156 This may be useful for scripting. Note this command should be run as either the
 157 superuser or the FRR user.
 158
 159 We recommend you do not mix the use of the two types of files. Further, it is
 160 better not to use the integrated :file:`frr.conf` file, as any syntax error in
 161 it can lead to /all/ of your daemons being unable to start up. Per daemon files
 162 are more robust as impact of errors in configuration are limited to the daemon
 163 in whose file the error is made.
 164
 165 .. index:: service integrated-vtysh-config
 166 .. clicmd:: service integrated-vtysh-config
 167
 168 .. index:: no service integrated-vtysh-config
 169 .. clicmd:: no service integrated-vtysh-config
 170
 171    Control whether integrated :file:`frr.conf` file is written when
 172    'write file' is issued.
 173
 174    These commands need to be placed in :file:`vtysh.conf` to have any effect.
 175    Note that since :file:`vtysh.conf` is not written by FRR itself, they
 176    therefore need to be manually placed in that file.
 177
 178    This command has 3 states:
 179
 180
 181    service integrated-vtysh-config
 182       *vtysh* will always write :file:`frr.conf`.
 183
 184
 185    no service integrated-vtysh-config
 186       *vtysh* will never write :file:`frr.conf`; instead it will ask
 187       daemons to write their individual configuration files.
 188
 189    Neither option present (default)
 190       *vtysh* will check whether :file:`frr.conf` exists. If it does,
 191       configuration writes will update that file. Otherwise, writes are performed
 192       through the individual daemons.
 193
 194    This command is primarily intended for packaging/distribution purposes, to
 195    preset one of the two operating modes and ensure consistent operation across
 196    installations.
 197
 198 .. index:: write integrated
 199 .. clicmd:: write integrated
 200
 201    Unconditionally (regardless of ``service integrated-vtysh-config`` setting)
 202    write out integrated :file:`frr.conf` file through *watchfrr*. If *watchfrr*
 203    is not running, this command is unavailable.
 204
 205 .. warning::
 206
 207    Configuration changes made while some daemon is not running will be
 208    invisible to that daemon. The daemon will start up with its saved
 209    configuration (either in its individual configuration file, or in
 210    :file:`frr.conf`).  This is particularly troublesome for route-maps and
 211    prefix lists, which would otherwise be synchronized between daemons.
 212