]>
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 | ||
bec667a6 DL |
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 | ||
afec8750 DL |
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 | ||
03750f1e | 78 | .. clicmd:: terminal paginate |
afec8750 DL |
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 | ||
42fc5d26 QY |
86 | Permissions and setup requirements |
87 | ================================== | |
88 | ||
89 | *vtysh* connects to running daemons through Unix sockets located in | |
c1a54c05 QY |
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). | |
42fc5d26 | 93 | |
c1a54c05 QY |
94 | To restrict access to FRR configuration, make sure no unauthorized users are |
95 | members of the |INSTALL_VTY_GROUP| group. | |
42fc5d26 | 96 | |
a3ff0311 QY |
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 | ||
42fc5d26 QY |
107 | PAM support (experimental) |
108 | -------------------------- | |
109 | ||
c1a54c05 QY |
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. | |
42fc5d26 | 123 | |
42fc5d26 | 124 | |
c1a54c05 | 125 | .. clicmd:: username USERNAME nopassword |
42fc5d26 | 126 | |
42fc5d26 | 127 | If PAM support is enabled at build-time, this command allows disabling the |
c1a54c05 | 128 | use of PAM on a per-user basis. If vtysh finds that an user is trying to |
42fc5d26 QY |
129 | use vtysh and a "nopassword" entry is found, no calls to PAM will be made |
130 | at all. | |
131 | ||
132 | ||
0efdf0fe | 133 | .. _integrated-configuration-mode: |
42fc5d26 QY |
134 | |
135 | Integrated configuration mode | |
136 | ============================= | |
137 | ||
138 | Integrated configuration mode uses a single configuration file, | |
c1a54c05 | 139 | :file:`frr.conf`, for all daemons. This replaces the individual files like |
42fc5d26 QY |
140 | :file:`zebra.conf` or :file:`bgpd.conf`. |
141 | ||
c1a54c05 QY |
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. | |
42fc5d26 | 150 | |
42fc5d26 QY |
151 | |
152 | Configuration saving, file ownership and permissions | |
153 | ---------------------------------------------------- | |
154 | ||
c1a54c05 | 155 | The :file:`frr.conf` file is not written by any of the daemons; instead *vtysh* |
d1e7591e | 156 | contains the necessary logic to collect configuration from all of the daemons, |
c1a54c05 | 157 | combine it and write it out. |
42fc5d26 | 158 | |
c1a54c05 | 159 | .. warning:: |
42fc5d26 | 160 | |
c1a54c05 QY |
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. | |
42fc5d26 | 164 | |
c1a54c05 QY |
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`. | |
42fc5d26 | 170 | |
c1a54c05 QY |
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. | |
42fc5d26 | 175 | |
c1a54c05 QY |
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. | |
42fc5d26 | 179 | |
9b953119 | 180 | We recommend you do not mix the use of the two types of files. |
42fc5d26 | 181 | |
c1a54c05 | 182 | .. clicmd:: service integrated-vtysh-config |
42fc5d26 | 183 | |
42fc5d26 | 184 | |
c1a54c05 QY |
185 | Control whether integrated :file:`frr.conf` file is written when |
186 | 'write file' is issued. | |
42fc5d26 | 187 | |
c1a54c05 QY |
188 | These commands need to be placed in :file:`vtysh.conf` to have any effect. |
189 | Note that since :file:`vtysh.conf` is not written by FRR itself, they | |
190 | therefore need to be manually placed in that file. | |
42fc5d26 | 191 | |
c1a54c05 | 192 | This command has 3 states: |
42fc5d26 | 193 | |
42fc5d26 | 194 | |
c1a54c05 | 195 | service integrated-vtysh-config |
42fc5d26 QY |
196 | *vtysh* will always write :file:`frr.conf`. |
197 | ||
198 | ||
c1a54c05 | 199 | no service integrated-vtysh-config |
42fc5d26 QY |
200 | *vtysh* will never write :file:`frr.conf`; instead it will ask |
201 | daemons to write their individual configuration files. | |
202 | ||
c1a54c05 QY |
203 | Neither option present (default) |
204 | *vtysh* will check whether :file:`frr.conf` exists. If it does, | |
205 | configuration writes will update that file. Otherwise, writes are performed | |
42fc5d26 QY |
206 | through the individual daemons. |
207 | ||
c1a54c05 QY |
208 | This command is primarily intended for packaging/distribution purposes, to |
209 | preset one of the two operating modes and ensure consistent operation across | |
210 | installations. | |
42fc5d26 | 211 | |
c1a54c05 | 212 | .. clicmd:: write integrated |
42fc5d26 | 213 | |
c1a54c05 QY |
214 | Unconditionally (regardless of ``service integrated-vtysh-config`` setting) |
215 | write out integrated :file:`frr.conf` file through *watchfrr*. If *watchfrr* | |
216 | is not running, this command is unavailable. | |
42fc5d26 | 217 | |
c1a54c05 | 218 | .. warning:: |
42fc5d26 | 219 | |
c1a54c05 QY |
220 | Configuration changes made while some daemon is not running will be |
221 | invisible to that daemon. The daemon will start up with its saved | |
222 | configuration (either in its individual configuration file, or in | |
223 | :file:`frr.conf`). This is particularly troublesome for route-maps and | |
224 | prefix lists, which would otherwise be synchronized between daemons. | |
76bd1499 | 225 |