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