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 Permissions and setup requirements
  26 ==================================
  27
  28 *vtysh* connects to running daemons through Unix sockets located in
  29 |INSTALL_PREFIX_STATE|. Running vtysh thus requires access to that directory,
  30 plus membership in the |INSTALL_VTY_GROUP| group (which is the group that the
  31 daemons will change ownership of their sockets to).
  32
  33 To restrict access to FRR configuration, make sure no unauthorized users are
  34 members of the |INSTALL_VTY_GROUP| group.
  35
  36 .. warning::
  37
  38    VTYSH implements a CLI option ``-u, --user`` that disallows entering the
  39    characters "en" on the command line, which ideally restricts access to
  40    configuration commands. However, VTYSH was never designed to be a privilege
  41    broker and is not built using secure coding practices. No guarantees of
  42    security are provided for this option and under no circumstances should this
  43    option be used to provide any semblance of security or read-only access to
  44    FRR.
  45
  46 PAM support (experimental)
  47 --------------------------
  48
  49 vtysh has working (but rather useless) PAM support. It will perform an
  50 "authenticate" PAM call using |PACKAGE_NAME| as service name. No other
  51 (accounting, session, password change) calls will be performed by vtysh.
  52
  53 Users using vtysh still need to have appropriate access to the daemons' VTY
  54 sockets, usually by being member of the |INSTALL_VTY_GROUP| group. If they
  55 have this membership, PAM support is useless since they can connect to daemons
  56 and issue commands using some other tool. Alternatively, the *vtysh* binary
  57 could be made SGID (set group ID) to the |INSTALL_VTY_GROUP| group.
  58
  59 .. warning::
  60
  61    No security guarantees are made for this configuration.
  62
  63
  64 .. index:: username USERNAME nopassword
  65 .. clicmd:: username USERNAME nopassword
  66
  67   If PAM support is enabled at build-time, this command allows disabling the
  68   use of PAM on a per-user basis. If vtysh finds that an user is trying to
  69   use vtysh and a "nopassword" entry is found, no calls to PAM will be made
  70   at all.
  71
  72
  73 .. _integrated-configuration-mode:
  74
  75 Integrated configuration mode
  76 =============================
  77
  78 Integrated configuration mode uses a single configuration file,
  79 :file:`frr.conf`, for all daemons. This replaces the individual files like
  80 :file:`zebra.conf` or :file:`bgpd.conf`.
  81
  82 :file:`frr.conf` is located in |INSTALL_PREFIX_ETC|. All daemons check for the
  83 existence of this file at startup, and if it exists will not load their
  84 individual configuration files. Instead, ``vtysh -b`` must be invoked to
  85 process :file:`frr.conf` and apply its settings to the individual daemons.
  86
  87 .. warning::
  88
  89    *vtysh -b* must also be executed after restarting any daemon.
  90
  91
  92 Configuration saving, file ownership and permissions
  93 ----------------------------------------------------
  94
  95 The :file:`frr.conf` file is not written by any of the daemons; instead *vtysh*
  96 contains the neccessary logic to collect configuration from all of the daemons,
  97 combine it and write it out.
  98
  99 .. warning::
 100
 101    Daemons must be running for *vtysh* to be able to collect their
 102    configuration. Any configuration from non-running daemons is permanently
 103    lost after doing a configuration save.
 104
 105 Since the *vtysh* command may be running as ordinary user on the system,
 106 configuration writes will be tried through *watchfrr*, using the ``write
 107 integrated`` command internally. Since *watchfrr* is running as superuser,
 108 *vtysh* is able to ensure correct ownership and permissions on
 109 :file:`frr.conf`.
 110
 111 If *watchfrr* is not running or the configuration write fails, *vtysh* will
 112 attempt to directly write to the file. This is likely to fail if running as
 113 unprivileged user; alternatively it may leave the file with incorrect owner or
 114 permissions.
 115
 116 Writing the configuration can be triggered directly by invoking *vtysh -w*.
 117 This may be useful for scripting. Note this command should be run as either the
 118 superuser or the FRR user.
 119
 120 We recommend you do not mix the use of the two types of files. Further, it is
 121 better not to use the integrated :file:`frr.conf` file, as any syntax error in
 122 it can lead to /all/ of your daemons being unable to start up. Per daemon files
 123 are more robust as impact of errors in configuration are limited to the daemon
 124 in whose file the error is made.
 125
 126 .. index:: service integrated-vtysh-config
 127 .. clicmd:: service integrated-vtysh-config
 128
 129 .. index:: no service integrated-vtysh-config
 130 .. clicmd:: no service integrated-vtysh-config
 131
 132    Control whether integrated :file:`frr.conf` file is written when
 133    'write file' is issued.
 134
 135    These commands need to be placed in :file:`vtysh.conf` to have any effect.
 136    Note that since :file:`vtysh.conf` is not written by FRR itself, they
 137    therefore need to be manually placed in that file.
 138
 139    This command has 3 states:
 140
 141
 142    service integrated-vtysh-config
 143       *vtysh* will always write :file:`frr.conf`.
 144
 145
 146    no service integrated-vtysh-config
 147       *vtysh* will never write :file:`frr.conf`; instead it will ask
 148       daemons to write their individual configuration files.
 149
 150    Neither option present (default)
 151       *vtysh* will check whether :file:`frr.conf` exists. If it does,
 152       configuration writes will update that file. Otherwise, writes are performed
 153       through the individual daemons.
 154
 155    This command is primarily intended for packaging/distribution purposes, to
 156    preset one of the two operating modes and ensure consistent operation across
 157    installations.
 158
 159 .. index:: write integrated
 160 .. clicmd:: write integrated
 161
 162    Unconditionally (regardless of ``service integrated-vtysh-config`` setting)
 163    write out integrated :file:`frr.conf` file through *watchfrr*. If *watchfrr*
 164    is not running, this command is unavailable.
 165
 166 .. warning::
 167
 168    Configuration changes made while some daemon is not running will be
 169    invisible to that daemon. The daemon will start up with its saved
 170    configuration (either in its individual configuration file, or in
 171    :file:`frr.conf`).  This is particularly troublesome for route-maps and
 172    prefix lists, which would otherwise be synchronized between daemons.
 173