README.md
1# sqtop
2Console applicaton to display information about currently active client connections for a Squid proxy in a convenient way.
3
4 - [Installing](README.md#installing)
5 - [Configuring](README.md#configuring)
6 - [Mac OS X](README.md#mac-os-x)
7 - [Debug version](README.md#debug-version)
8 - [Building/Installing](README.md#buildinginstalling)
9 - [Post-installation](README.md#post-installation)
10 - [Uninstallation](README.md#uninstallation)
11 - [Binaries](README.md#how-to-install-sqtop-from-binaries)
12 - [Debian/Ubuntu](README.md#debianubuntu)
13 - [FreeBSD](README.md#freebsd)
14 - [Configuration](README.md#configuration)
15 - [Squid server configuration](README.md#squid-server-configuration)
16 - [Command line arguments](README.md#command-line-arguments)
17 - [Usage](README.md#usage)
18 - [Interactive mode](README.md#interactive-mode)
19 - [Examples](README.md#examples)
20 - [Diagnostic](README.md#diagnostic)
21
22## Installing
23
24### Configuring
25
26sqtop uses GNU autotools to automatically configure software source code.
27
28By default:
29 - sqtop builds with user interface. This adds dependency on [posix threads](http://en.wikipedia.org/wiki/POSIX_Threads) and [ncurses](http://www.gnu.org/software/ncurses/). You can use **--disable-ui** to build sqtop without user interface (as well as without this dependencies).
30 - sqtop builds with resolver. This adds dependency on [posix threads](http://en.wikipedia.org/wiki/POSIX_Threads). You can use **--without-resolver** to build sqtop without resolver (as well as without this dependency).
31 - installation prefix is `/usr/local/bin'. You can use standard autotools variables to change this.
32
33```
34 $ ./configure
35or
36 $ ./configure --disable-ui --program-prefix=/opt/local
37```
38
39Note: to build with gcc-2.9x, you should export CXXFLAGS=-D_GNU_SOURCE before ./configure
40
41#### Mac OS X
42
43Snow Leopard 10.6.3 are know to have broken ncurses library - functional keys are not working (bug id #7812932). To use sqtop under 10.6.3 you can:
44 - copy */usr/lib/libncurses.5.4.dylib* and */usr/lib/libncurses.5.dylib* from a 10.6.2 system to a 10.6.3 system. Do not forget to update dyld cache:
45```
46 $ sudo update_dyld_shared_cache
47```
48 - build sqtop agains ncurses from [macports](http://macports.org). Of couse you should have install ncurses from macports first
49```
50 $ export LDFLAGS=-L/opt/local/lib; ./configure
51```
52
53#### Debug version
54
55To obtain version of sqtop with debugging symbols, do:
56```
57 $ export CXXFLAGS="-g -O0"; ./configure
58```
59Note: **make install** installs stripped version of binary, so if you want to use binary with debugging symbols use one in **src** subdir, or install it manualy with **cp(1)**.
60
61----
62### Building/Installing
63
64As trivial as
65```
66 $ make
67 $ sudo make install
68```
69
70It installs two files:
71 - sqtop binary
72 - man page
73
74----
75### Post-installation
76
77If sqtop was built with user interface you can make following aliases for command to just print statistics once (without entering UI mode) like old good squidstat.
78
79For [BASH](http://www.gnu.org/software/bash/):
80```
81 $ echo 'alias squidstat="sqtop -o"' >> ~/.bashrc
82```
83
84For [tcsh](http://www.tcsh.org/):
85```
86 $ echo 'alias squidstat "sqtop -o"' >> ~/.cshrc
87```
88
89----
90### Uninstallation
91
92From directory where sqtop was built:
93```
94 $ sudo make uninstall
95```
96## How-to install sqtop from binaries
97
98### Debian/Ubuntu
99
100[Download](http://code.google.com/p/sqtop/downloads/list) appropriate deb package and install it with **dpkg**.
101
102### FreeBSD
103
104```
105 cd /usr/ports/net/sqtop/ && make install
106```
107## Configuration
108
109sqtop itself does not require any configuration. All configuration parameters can be passed while invoking sqtop, for details see [Usage](README.md#Usage)
110
111### Squid server configuration
112
113Edit your squid.conf to allow cachemgr protocol:
114
115```
116acl manager proto cache_object
117# replace x.x.x.x with admin ip address
118acl admin src x.x.x.x/255.255.255.255
119http_access allow manager admin
120http_access deny manager
121```
122
123
124Note: if you use any type of authentification (ntlm, basic, etc) above mentioned lines sould be written before any http_access with authentification.# how-to use sqtop
125
126### Command line arguments
127
128```
129 --host host (-h host)
130 Squid proxy host. Defaults to 127.0.0.1.
131
132 --port port (-p port)
133 Squid proxy port. Defaults to 3128.
134
135 --pass password (-P password)
136 Squid proxy cachemgr_passwd.
137
138 --hosts hostlist (-H hostlist)
139 Comma-separated list of client IP addresses (CIDR notation is supported) to query the Squid proxy for. Hostnames are
140 silently ignored.
141
142 --users userlist (-u userlist)
143 Comma-separated list of Squid usernames to list active connections for.
144
145 --brief (-b)
146 Display brief per-connection information, omits URLs.
147
148 --detail (-d)
149 Display detailed information (size, username and average speed) for each URL in each connection.
150
151 --full (-f)
152 Display full details (size, username, average speed, delay pool and elapsed time) for each URL in each connection.
153
154 --zero (-z)
155 Display zero values instead of silently omitting them.
156
157 --once (-o)
158 Disable interactive mode, just print statistics once to stdout.
159
160 --refreshinterval seconds (-r seconds)
161 Set the refresh-interval for interactive mode.
162
163 -c
164 Do not compact the display of multiple occurrences of the same URL in a single connection.
165
166 -n
167 Do not do hostname lookups.
168
169 -S
170 Do not strip domain part of hostname.
171
172 --help Display a brief help text.
173```
174
175Note: without options, sqtop tries to connect to a Squid proxy listening at 127.0.0.1 using port 3128.
176
177## Usage
178
179### Interactive mode
180
181If built with support for ncurses(3), sqtop defaults to running in interactive mode, occupying the whole screen, unless the --once option was specified on the command line.
182
183Information about the Squid server currently connected to, the version of sqtop used, as well as eventual error messages are shown at the top of the display.
184
185The bottom of the display keeps various aggregates, including current and average speed, the total number of IPs connected and the total number of connections.
186
187Any option given on the command line can be changed from within interactive mode by pressing the key corresponding to its respective short option character.
188
189In addition to the options given on the command line, sqtop recognizes the following keys when in interactive mode:
190
191```
192/ Search for literal substrings in IPs, usernames or URLs. Regular expressions are not parsed, currently.
193
194SPACE Stop refreshing.
195
196UP/DOWN, PGUP/PGDN, HOME/END
197 Scroll display.
198
199ENTER Toggle displayed level of detail for the currently selected entry.
200
201? Display the help screen, including current settings for options, where applicable.
202
203C Compact long urls to fit them on one line.
204
205s Toggle mode of display for speed detail between current and average, current only and average only.
206
207o Toggle connection sort order between size, current speed, average speed and max time.
208
209R Toggle hosts showing mode between host name only, host ip only, both ip and host name.
210
211q Quit sqtop
212```
213
214### Examples
215
216List all currently active connections in interacive mode from 192.168.2.0/24 and 172.18.118.10 to a Squid proxy running at mysquid.example.com, port 8080 using ZePasswd as cachemgr_passwd:
217```
218 $ sqtop -h mysquid.example.com -port 8080 -p ZePasswd -H 192.168.2.0/24,172.18.118.10
219```
220
221### Diagnostic
222
223The sqtop utility exits 0 on success, and >0 if an error occurs.
224