]>
Commit | Line | Data |
---|---|---|
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 necessary 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 |