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