diff options
Diffstat (limited to 'doc/user/vtysh.rst')
| -rw-r--r-- | doc/user/vtysh.rst | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/doc/user/vtysh.rst b/doc/user/vtysh.rst new file mode 100644 index 0000000..adbdf34 --- /dev/null +++ b/doc/user/vtysh.rst @@ -0,0 +1,226 @@ +.. _vty-shell: + +********* +VTY shell +********* + +.. program:: configure + +*vtysh* provides a combined frontend to all FRR daemons in a single combined +session. It is enabled by default at build time, but can be disabled through +the :option:`--disable-vtysh` option to the configure script. + +*vtysh* has a configuration file, :file:`vtysh.conf`. The location of that +file cannot be changed from |INSTALL_PREFIX_ETC| since it contains options +controlling authentication behavior. This file will also not be written by +configuration-save commands, it is intended to be updated manually by an +administrator with an external editor. + +.. warning:: + + This also means the ``hostname``, ``domainname``, and ``banner motd`` commands + (which do have effect for vtysh) need to be manually updated + in :file:`vtysh.conf`. + + +.. clicmd:: copy FILENAME running-config + + Process and load a configuration file manually; each line in the + file is read and processed as if it were being typed (or piped) to + vtysh. + + +Live logs +========= + +.. clicmd:: terminal monitor [DAEMON] + + Receive and display log messages. + + It is not currently possible to change the minimum message priority (fixed + to debug) or output formatting. These will likely be made configurable in + the future. + + Log messages are received asynchronously and may be printed both during + command execution as well as while on the prompt. They are printed to + stderr, unlike regular CLI output which is printed to stdout. The intent is + that stdin/stdout might be driven by some script while log messages are + visible on stderr. If stdout and stderr are the same file, the prompt and + pending input will be cleared and reprinted appropriately. + + .. note:: + + If ``vtysh`` cannot keep up, some log messages may be lost. The daemons + do **not** wait for, get blocked by, or buffer messages for ``vtysh``. + + +Pager usage +=========== + +*vtysh* can call an external paging program (e.g. *more* or *less*) to +paginate long output from commands. This feature used to be enabled by +default but is now controlled by the ``VTYSH_PAGER`` environment variable +and the :clicmd:`terminal paginate` command: + +.. envvar:: VTYSH_PAGER + + If set, the ``VTYSH_PAGER`` environment variable causes *vtysh* to pipe + output from commands through the given command. Note that this happens + regardless of the length of the output. As such, standard pager behavior + (particularly waiting at the end of output) tends to be annoying to the + user. Using ``less -EFX`` is recommended for a better user experience. + + If this environment variable is unset, *vtysh* defaults to not using any + pager. + + This variable should be set by the user according to their preferences, + in their :file:`~/.profile` file. + +.. clicmd:: terminal paginate + + Enables/disables vtysh output pagination. This command is intended to + be placed in :file:`vtysh.conf` to set a system-wide default. If this + is enabled but ``VTYSH_PAGER`` is not set, the system default pager + (likely ``more`` or ``/usr/bin/pager``) will be used. + + +Permissions and setup requirements +================================== + +*vtysh* connects to running daemons through Unix sockets located in +|INSTALL_PREFIX_STATE|. Running vtysh thus requires access to that directory, +plus membership in the |INSTALL_VTY_GROUP| group (which is the group that the +daemons will change ownership of their sockets to). + +To restrict access to FRR configuration, make sure no unauthorized users are +members of the |INSTALL_VTY_GROUP| group. + +.. warning:: + + VTYSH implements a CLI option ``-u, --user`` that disallows entering the + characters "en" on the command line, which ideally restricts access to + configuration commands. However, VTYSH was never designed to be a privilege + broker and is not built using secure coding practices. No guarantees of + security are provided for this option and under no circumstances should this + option be used to provide any semblance of security or read-only access to + FRR. + +PAM support (experimental) +-------------------------- + +vtysh has working (but rather useless) PAM support. It will perform an +"authenticate" PAM call using |PACKAGE_NAME| as service name. No other +(accounting, session, password change) calls will be performed by vtysh. + +Users using vtysh still need to have appropriate access to the daemons' VTY +sockets, usually by being member of the |INSTALL_VTY_GROUP| group. If they +have this membership, PAM support is useless since they can connect to daemons +and issue commands using some other tool. Alternatively, the *vtysh* binary +could be made SGID (set group ID) to the |INSTALL_VTY_GROUP| group. + +.. warning:: + + No security guarantees are made for this configuration. + + +.. clicmd:: username USERNAME nopassword + + If PAM support is enabled at build-time, this command allows disabling the + use of PAM on a per-user basis. If vtysh finds that an user is trying to + use vtysh and a "nopassword" entry is found, no calls to PAM will be made + at all. + + +.. _integrated-configuration-mode: + +Integrated configuration mode +============================= + +Integrated configuration mode uses a single configuration file, +:file:`frr.conf`, for all daemons. This replaces the individual files like +:file:`zebra.conf` or :file:`bgpd.conf`. + +:file:`frr.conf` is located in |INSTALL_PREFIX_ETC|. All daemons check for the +existence of this file at startup, and if it exists will not load their +individual configuration files. Instead, ``vtysh -b`` must be invoked to +process :file:`frr.conf` and apply its settings to the individual daemons. + +.. warning:: + + *vtysh -b* must also be executed after restarting any daemon. + + +Configuration saving, file ownership and permissions +---------------------------------------------------- + +The :file:`frr.conf` file is not written by any of the daemons; instead *vtysh* +contains the necessary logic to collect configuration from all of the daemons, +combine it and write it out. + +.. warning:: + + Daemons must be running for *vtysh* to be able to collect their + configuration. Any configuration from non-running daemons is permanently + lost after doing a configuration save. + +Since the *vtysh* command may be running as ordinary user on the system, +configuration writes will be tried through *watchfrr*, using the ``write +integrated`` command internally. Since *watchfrr* is running as superuser, +*vtysh* is able to ensure correct ownership and permissions on +:file:`frr.conf`. + +If *watchfrr* is not running or the configuration write fails, *vtysh* will +attempt to directly write to the file. This is likely to fail if running as +unprivileged user; alternatively it may leave the file with incorrect owner or +permissions. + +Writing the configuration can be triggered directly by invoking *vtysh -w*. +This may be useful for scripting. Note this command should be run as either the +superuser or the FRR user. + +We recommend you do not mix the use of the two types of files. + +.. clicmd:: service integrated-vtysh-config + + + Control whether integrated :file:`frr.conf` file is written when + 'write file' is issued. + + These commands need to be placed in :file:`vtysh.conf` to have any effect. + Note that since :file:`vtysh.conf` is not written by FRR itself, they + therefore need to be manually placed in that file. + + This command has 3 states: + + + service integrated-vtysh-config + *vtysh* will always write :file:`frr.conf`. + + + no service integrated-vtysh-config + *vtysh* will never write :file:`frr.conf`; instead it will ask + daemons to write their individual configuration files. + + Neither option present (default) + *vtysh* will check whether :file:`frr.conf` exists. If it does, + configuration writes will update that file. Otherwise, writes are performed + through the individual daemons. + + This command is primarily intended for packaging/distribution purposes, to + preset one of the two operating modes and ensure consistent operation across + installations. + +.. clicmd:: write integrated + + Unconditionally (regardless of ``service integrated-vtysh-config`` setting) + write out integrated :file:`frr.conf` file through *watchfrr*. If *watchfrr* + is not running, this command is unavailable. + +.. warning:: + + Configuration changes made while some daemon is not running will be + invisible to that daemon. The daemon will start up with its saved + configuration (either in its individual configuration file, or in + :file:`frr.conf`). This is particularly troublesome for route-maps and + prefix lists, which would otherwise be synchronized between daemons. + |