doc/vtysh.texi

   1 @node VTY shell
   2 @chapter VTY shell
   3
   4 @menu
   5 * Integrated configuration mode::
   6 @end menu
   7
   8 @command{vtysh} provides a combined frontend to all Frr daemons in a
   9 single combined session.  It is enabled by default at build time, but can
  10 be disabled through the @option{--disable-vtysh} option to
  11 @command{./configure}.
  12
  13 @command{vtysh} has a configuration file, @file{vtysh.conf}.  The location
  14 of that file cannot be changed from @file{@value{INSTALL_PREFIX_ETC}} since
  15 it contains options controlling authentication behavior.  This file will
  16 also not be written by configuration-save commands, it is intended to be
  17 updated manually by an administrator with an external editor.
  18
  19 @quotation Warning
  20 This also means the @command{hostname} and @command{banner motd} commands
  21 (which both do have effect for vtysh) need to be manually updated in
  22 @file{vtysh.conf}.
  23 @end quotation
  24
  25 @section Permissions and setup requirements
  26
  27 @command{vtysh} connects to running daemons through Unix sockets located in
  28 @file{@value{INSTALL_PREFIX_STATE}}.  Running vtysh thus requires access to
  29 that directory, plus membership in the @emph{@value{INSTALL_VTY_GROUP}}
  30 group (which is the group that the daemons will change ownership of their
  31 sockets to).
  32
  33 To restrict access to Frr configuration, make sure no unauthorized users
  34 are members of the @emph{@value{INSTALL_VTY_GROUP}} group.
  35
  36 @subsection PAM support (experimental)
  37
  38 vtysh has working (but rather useless) PAM support.  It will perform
  39 an "authenticate" PAM call using @emph{@value{PACKAGE_NAME}} as service
  40 name. No other (accounting, session, password change) calls will be
  41 performed by vtysh.
  42
  43 Users using vtysh still need to have appropriate access to the daemons'
  44 VTY sockets, usually by being member of the @emph{@value{INSTALL_VTY_GROUP}}
  45 group.  If they have this membership, PAM support is useless since they can
  46 connect to daemons and issue commands using some other tool.  Alternatively,
  47 the @command{vtysh} binary could be made SGID (set group ID) to the
  48 @emph{@value{INSTALL_VTY_GROUP}} group.  @strong{No security guarantees are
  49 made for this configuration}.
  50
  51 @deffn {Command} {username @var{username} nopassword} {}
  52
  53 If PAM support is enabled at build-time, this command allows disabling the
  54 use of PAM on a per-user basis.  If vtysh finds that an user is trying to
  55 use vtysh and a "nopassword" entry is found, no calls to PAM will be made
  56 at all.
  57
  58 @end deffn
  59
  60 @node Integrated configuration mode
  61 @section Integrated configuration mode
  62
  63 Integrated configuration mode uses a single configuration file,
  64 @file{frr.conf}, for all daemons.  This replaces the individual files like
  65 @file{zebra.conf} or @file{bgpd.conf}.
  66
  67 @file{frr.conf} is located in @file{@value{INSTALL_PREFIX_ETC}}.  All
  68 daemons check for the existence of this file at startup, and if it exists
  69 will not load their individual configuration files.  Instead,
  70 @command{vtysh -b} must be invoked to process @file{frr.conf} and apply
  71 its settings to the individual daemons.
  72
  73 @quotation Warning
  74 @command{vtysh -b} must also be executed after restarting any daemon.
  75 @end quotation
  76
  77 @subsection Configuration saving, file ownership and permissions
  78
  79 The @file{frr.conf} file is not written by any of the daemons; instead
  80 @command{vtysh} contains the neccessary logic to collect configuration from
  81 all of the daemons, combine it and write it out.
  82
  83 @quotation Warning
  84 Daemons must be running for @command{vtysh} to be able to collect their
  85 configuration.  Any configuration from non-running daemons is permanently
  86 lost after doing a configuration save.
  87 @end quotation
  88
  89 Since the @command{vtysh} command may be running as ordinary user on the
  90 system, configuration writes will be tried through @command{watchfrr},
  91 using the @command{write integrated} command internally.  Since
  92 @command{watchfrr} is running as superuser, @command{vtysh} is able to
  93 ensure correct ownership and permissions on @file{frr.conf}.
  94
  95 If @command{watchfrr} is not running or the configuration write fails,
  96 @command{vtysh} will attempt to directly write to the file.  This is likely
  97 to fail if running as unprivileged user;  alternatively it may leave the
  98 file with incorrect owner or permissions.
  99
 100 Writing the configuration can be triggered directly by invoking
 101 @command{vtysh -w}.  This may be useful for scripting.  Note this command
 102 should be run as either the superuser or the Frr user.
 103
 104 We recommend you do not mix the use of the two types of files. Further, it
 105 is better not to use the integrated frr.conf file, as any syntax error in
 106 it can lead to /all/ of your daemons being unable to start up. Per daemon
 107 files are more robust as impact of errors in configuration are limited to
 108 the daemon in whose file the error is made.
 109
 110 @deffn {Command} {service integrated-vtysh-config} {}
 111 @deffnx {Command} {no service integrated-vtysh-config} {}
 112
 113 Control whether integrated @file{frr.conf} file is written when
 114 'write file' is issued.
 115
 116 These commands need to be placed in @file{vtysh.conf} to have any effect.
 117 Note that since @file{vtysh.conf} is not written by Frr itself, they
 118 therefore need to be manually placed in that file.
 119
 120 This command has 3 states:
 121 @itemize @bullet
 122 @item
 123 @command{service integrated-vtysh-config}
 124
 125 @command{vtysh} will always write @file{frr.conf}.
 126
 127 @item
 128 @command{no service integrated-vtysh-config}
 129
 130 @command{vtysh} will never write @file{frr.conf}; instead it will ask
 131 daemons to write their individual configuration files.
 132
 133 @item
 134 Neither option present (default)
 135
 136 @command{vtysh} will check whether @file{frr.conf} exists.  If it does,
 137 configuration writes will update that file.  Otherwise, writes are performed
 138 through the individual daemons.
 139 @end itemize
 140
 141 This command is primarily intended for packaging/distribution purposes, to
 142 preset one of the two operating modes and ensure consistent operation across
 143 installations.
 144 @end deffn
 145
 146 @deffn {Command} {write integrated} {}
 147
 148 Unconditionally (regardless of @command{service integrated-vtysh-config}
 149 setting) write out integrated @file{frr.conf} file through
 150 @command{watchfrr}.  If @command{watchfrr} is not running, this command
 151 is unavailable.
 152
 153 @end deffn
 154
 155 @section Caveats
 156
 157 Configuration changes made while some daemon is not running will be invisible
 158 to that daemon.  The daemon will start up with its saved configuration
 159 (either in its individual configuration file, or in @file{frr.conf}).
 160 This is particularly troublesome for route-maps and prefix lists, which would
 161 otherwise be synchronized between daemons.