5 * Integrated configuration mode::
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}.
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.
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
25 @section Permissions and setup requirements
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
33 To restrict access to Frr configuration, make sure no unauthorized users
34 are members of the @emph{@value{INSTALL_VTY_GROUP}} group.
36 @subsection PAM support (experimental)
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
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}.
51 @deffn {Command} {username @var{username} nopassword} {}
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
60 @node Integrated configuration mode
61 @section Integrated configuration mode
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}.
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.
74 @command{vtysh -b} must also be executed after restarting any daemon.
77 @subsection Configuration saving, file ownership and permissions
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.
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.
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}.
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.
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.
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.
110 @deffn {Command} {service integrated-vtysh-config} {}
111 @deffnx {Command} {no service integrated-vtysh-config} {}
113 Control whether integrated @file{Frr.conf} file is written when
114 'write file' is issued.
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.
120 This command has 3 states:
123 @command{service integrated-vtysh-config}
125 @command{vtysh} will always write @file{Frr.conf}.
128 @command{no service integrated-vtysh-config}
130 @command{vtysh} will never write @file{Frr.conf}; instead it will ask
131 daemons to write their individual configuration files.
134 Neither option present (default)
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.
141 This command is primarily intended for packaging/distribution purposes, to
142 preset one of the two operating modes and ensure consistent operation across
146 @deffn {Command} {write integrated} {}
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
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.