From b7866e519f27c960e1ce6ef2a8e34285711ea67d Mon Sep 17 00:00:00 2001 From: Tobias Klausmann Date: Sat, 27 Aug 2016 15:04:33 +0200 Subject: [PATCH] Minor README formatting fixes --- README.md | 64 +++++++++++++++++++++++++++---------------------------- 1 file changed, 31 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 7d921a7..06fc66f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ -Transonic -========= +# Transonic Transonic is a simple script that lets you run ping(1) in a massively parallel manner. The only limits are your bandwidth and the performance of the computer @@ -19,50 +18,54 @@ transonic only depends on having ping(1) available. Finally, transonic is written as simple as possible and thus is easier to adapt and extend according to your taste than nmap or fping (and most other tools). -Output modes ------------- +## Output modes -Currently, Transonic supports four output modes: cell, ccell, updl and list, -defaulting to "list". +Currently, Transonic supports four output modes: `cell`, `ccell`, `updl` and +`list`, defaulting to `list`. Here's an example of list output: +``` $ transonic.py localhost fw host.doesnotexist.invalid Pinging 3 machines with 3 workers; 5 pings per host localhost S5/R5, maMD: 0.018/0.026/0.030/0.007 fw S5/R5, maMD: 28.525/36.897/48.839/8.450 host.doesnotexist.invalid S?/R?, maMD: ?/?/?/? Time taken: 4.107 seconds (1.369 per host) +``` Transonic shows one line per host pinged, plus a header line and a summary. Every per-host line consist of the following: -hostname, S/S, maMD: +`hostname, S/S, maMD: ` -s and r are the number of packets sent and received, respectively. The numbers +`s` and `r` are the number of packets sent and received, respectively. The numbers at the end of the line are the min, average, max round-trip time plus the standard deviation of all the RTTs. All of these numbers are calculated by -ping(1) itself, so its documentation (and source) should be consulted if +`ping(1)` itself, so its documentation (and source) should be consulted if details are needed. -The cell and ccell modes are very similar, here's an example of "cell": +The `cell` and `ccell` modes are very similar, here's an example of `cell`: +``` Pinging 3 machines with 3 workers; 5 pings per host localhost fw.i-no.de host.doesnotexist.invalid 2 up, 1 down Time taken: 4.050 seconds (1.350 per host) +``` Where "host.doesnotexist.invalid" is in reverse video (not easily reproducible in this text file). This takes up less screen space than the per-line mode, especially if the host names used are short. It will still tell you _which_ hosts are up/down. -The ccell ("condensed cell") mode forgoes telling you which hosts are up/down +The `ccell` ("condensed cell") mode forgoes telling you which hosts are up/down in favour of displaying state of more hosts in the same amount of screen space. It is most useful when pinging tens or even hundreds of hosts and getting a quick view of the shape of things. Here's an example, also -demonstrating the -c and -n commandline options (output has been trimmed): +demonstrating the `-c` and `-n` commandline options (output has been trimmed): +``` $ transonic.py -m ccell -c2 -n500 $IPS Warning: Expected reply count is larger than number of requests sent (4 > 2). Adjusting expected reply count to 2 @@ -76,26 +79,26 @@ Pinging 2816 machines with 500 workers; 2 pings per host !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! 85 up, 2731 down Time taken: 66.269 seconds (0.024 per host) +``` -Every host that is up is denoted by a "." and every down host is denoted with -a "!". Due to the way Transonic works, the order of hosts in the output is +Every host that is up is denoted by a `.` and every down host is denoted with +a `!`. Due to the way Transonic works, the order of hosts in the output is basically random. Also note how Transonic will adjust the expected reply count for you when it makes sense. This behaviour can be controlled using the --a commandline flag. +`-a` commandline flag. -The updl formatter will give you three lines, one with UP: and the hostnames -that are up; one with DOWN:, for down hosts and a summary line prefixed with -TOTALS:. +The `updl` formatter will give you three lines, one with `UP:` and the hostnames +that are up; one with `DOWN:`, for down hosts and a summary line prefixed with +`TOTALS:`. Writing your own output formatter is relatively easy if you know Python. Since -the Pinger function does all the ping(1) output parsing for you, all you need +the Pinger function does all the `ping(1)` output parsing for you, all you need to know is how to handle the Pingresult objects. If you come up with a smashing new output formatter that is of general use, feel free to send me a patch (note: Transonic is GPL-2), but note the comment about 2.x/3.x compatibility below. -Performance ------------ +## Performance Transonic is quite fast, as you can see from the example above. If you limit the count of pings to 1 and crank up the count of workers (a modern machine @@ -112,28 +115,23 @@ you provide. Also, Transonic has the potential to quickly fill your network connection. A corollary to that is that the admin of the net you're pinging might be very unhappy with the amount of traffic you cause. Since Transonic won't (and -can't) mask the fact that *you* cause the traffic, said Admin might take +can't) mask the fact that _you_ cause the traffic, said Admin might take (possibly legal) action against you. Don't do anything stupid, alright? -Dependencies ------------- +## Dependencies -Transonic currently assumes that ping(1) has the same output format that ping +Transonic currently assumes that `ping(1)` has the same output format that ping from Linux' iputils has. If you have reasonably modern Linux installation, this should be enough. If you run BSD or another shape of Unix, adjustments to the Pinger function in Transonic may be necessary. Autodetection of what your ping flavour is is _not_ planned. -Python 2.x and 3.x ------------------- +## Python 2.x and 3.x Transonic comes in two variants: one for Python 2.x with x>=6, named -transonic2.py in the distribution and one for Python 3.x with x>=2, named -transonic.py. Principal development is done using the version for 3.x, with +`transonic2.py` in the distribution and one for Python 3.x with x>=2, named +`transonic.py`. Principal development is done using the version for 3.x, with changes backported to the 2.x whenever feasible. So far, they are functionally -identical. if you send patches for Transonic, please make a reasonable effort +identical. If you send patches for Transonic, please make a reasonable effort to write code that works with both versions with as little (read: no) editing as possible. - -vim: tw=78 -