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