Commit 9b3e6783 authored by Adam Wujek's avatar Adam Wujek

doc: add description of wrs_dump.sh

Signed-off-by: 's avatarAdam Wujek <dev_public@wujek.eu>
parent 2827304d
Pipeline #4130 failed with stage
in 8 seconds
......@@ -3169,6 +3169,118 @@ We are collecting all those issues in our project pages. Please visit:
If you have any problem with this firmware and you don't find help in the above links,
feel free to reach us on the @i{white-rabbit-dev} mailing list.
@c ==========================================================================
@node Dumping WRS state (wrs_dump)
@section Dumping WRS state (wrs_dump)
The @t{wrs_dump.sh} can dump the current state of a switch. Its use can be
helpful when reporting a bug or saving a switch's state for later analysis.
The tool can be found in WRS software repository (or accessed directly via
weblink @url{https://ohwr.org/project/wr-switch-sw/blob/master/userspace/host_tools/wrs_dump.sh}).
The @t{wrs_dump.sh} is independent from the WR software, it can be used on
different versions of firmware.
It can be run from a host computer or even WR switch
(however, @t{wrs_dump.sh} is not included in the firmware).
It connects form a host machine via @t{ssh} to a switch and gets the following
information in the order:
@itemize
@item firmware version information (output of @t{wrs_version})
@item logged users and uptime (output of @t{w} command)
@item process list (output of @t{ps} command)
@item dump of shared memory of WR specific daemons (output of @t{wrs_dump_shmem})
@item detailed port statistics (output of @t{wrs_pstats})
@item timing status and configuration (output of @t{wr_mon})
@item local disk usage (output of @t{df})
@item information about free memory (output of @t{free})
@item detailed information about memory usage (output of @t{/proc/meminfo})
@item information about network interfaces (output of @t{ifconfig})
@item traffic on working WR ports; using @t{tcpdump} of up ports (or on
specified ports depending on the parameter)
@item output of PPSI's verbose messages (if selected by the parameter);
it may affect synchronization (not seen in practice)
@item output of @t{dmesg}
@item information about VLAN configuration (output of @t{wrs_vlans --list}
and @t{wrs_vlans --plist})
@item information about routing (switching) rules (output of @t{rtu_stat})
@item SFP information (output of @t{wrs_sfp_dump -L -d -x})
@item copy of dot-config
@item copy of shared memory files of WR specific daemons
@item copy content of /tmp
@end itemize
During the run of this tool many parameters could have changed their values.
Such information might be important during further investigation. For this
reason the tool reads once more some information:
@itemize
@item process list (output of @t{ps} command)
@item dump of shared memory of WR specific daemons (output of @t{wrs_dump_shmem})
@item detailed port statistics (output of @t{wrs_pstats})
@item timing status and configuration (output of @t{wr_mon})
@item local disk usage (output of @t{df})
@item information about free memory (output of @t{free})
@item detailed information about memory usage (output of @t{/proc/meminfo})
@item information about network interfaces (output of @t{ifconfig})
@end itemize
By default, the gathered information is stored in the directory
@t{wrs_dump-<hostname>-<date>}. If needed the output directory can be changed
with @t{--output} parameter.
It is possible to define the list of ports that @t{tcpdump} shall be run on.
The verbosity of PPSi can be set to the predefined value
(@t{--ppsi-verbose <verbose_mode>}) or set to dump all messages
(@t{--ppsi-verbose-all}) for 60 seconds.
If for some reason it is not possible to use password or ssh-keys for
authentication to login to the switch, the user can store the password in
host's @t{WRS_PSWD} environment variable.
The content of this environment variable will be passed to the @t{sshpass}
command instead.
Example run of @t{wrs_dump.sh}:
@smallexample
$ ./wrs_dump.sh root@@wrs
Example printout:
root@@wrs ppsi_verbose_mode=
Open ssh connection...
Provide password
Password:
ssh connection established
Store data in the directory wrs_dump-wrs-2022-08-28_04-46-52
Get version... Done
Get w (logged users and uptime)... Done
Get process list... Done
Get output of wrs_dump_shmem... Done
Get output of wrs_pstats... Done
Get output of wr_mon... Done
Get output of df... Done
Get output of free... Done
Get output of /proc/meminfo... Done
Get output of ifconfig... Done
Get tcpdump for up ports: wri1 wri4 wri15
Get output of tcpdump wri1... Done
Get output of tcpdump wri4... Done
Get output of tcpdump wri15... Done
Get output of dmesg... Done
Get output of wrs_vlans --list... Done
Get output of wrs_vlans --plist... Done
Get output of rtu_stat... Done
Get output of wrs_sfp_dump -L -d -x... Done
Copy dot-config... Done
Copy shmem... Done
Copy /tmp... Done
Get again process list... Done
Get again output of wrs_dump_shmem... Done
Get again output of wrs_pstats... Done
Get again output of wr_mon... Done
Get again output of df... Done
Get again output of free... Done
Get again output of /proc/meminfo... Done
Get again output of ifconfig... Done
Closing ssh connection... Done
@end smallexample
@c ##########################################################################
@bye
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment