monmux.8 7.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247
  1. .\" -*- nroff -*-
  2. .\"
  3. .\" Copyright (c) 2001-2002 Willem Dijkstra
  4. .\" All rights reserved.
  5. .\"
  6. .\" Redistribution and use in source and binary forms, with or without
  7. .\" modification, are permitted provided that the following conditions
  8. .\" are met:
  9. .\"
  10. .\" - Redistributions of source code must retain the above copyright
  11. .\" notice, this list of conditions and the following disclaimer.
  12. .\" - Redistributions in binary form must reproduce the above
  13. .\" copyright notice, this list of conditions and the following
  14. .\" disclaimer in the documentation and/or other materials provided
  15. .\" with the distribution.
  16. .\"
  17. .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18. .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19. .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  20. .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
  21. .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  22. .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  23. .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  24. .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  25. .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
  27. .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28. .\" POSSIBILITY OF SUCH DAMAGE.
  29. .\"
  30. .Dd April 5, 2002
  31. .Dt MONMUX 8
  32. .Os
  33. .Sh NAME
  34. .Nm monmux
  35. .Nd mon stream multiplexer
  36. .Sh SYNOPSIS
  37. .Nm
  38. .Op Fl vd
  39. .Op Fl f Ar filename
  40. .Pp
  41. .Sh DESCRIPTION
  42. .Xr mon 8
  43. is a lightweight system monitor that measures cpu, memory, interface and disk
  44. statistics every 5 seconds. This information is then spooled to
  45. .Nm
  46. for further processing.
  47. .Pp
  48. .Xr mon 8
  49. has been designed to inflict minimal performance and security impact on the
  50. system it monitors.
  51. .Nm
  52. has performance impact proportional to the amount of streams it needs to
  53. manage. Ideally
  54. .Nm
  55. should live on a different system and collect data from several
  56. .Xr mon 8
  57. instances in a LAN.
  58. .Nm
  59. stores the incoming streams in .rrd files and distributes the information to
  60. connected listeners. Listeners can connect to
  61. .Nm
  62. on a tcp port and receive incoming
  63. .Xr mon 8
  64. transmissions decoded into ascii.
  65. .Lp
  66. .Nm
  67. needs no specific priviledges besides being able to open it's ports and the rrd files. It should be run as
  68. .Ar "nobody" .
  69. .Lp
  70. The options:
  71. .Bl -tag -width Ds
  72. .It Fl v
  73. Show version information.
  74. .It Fl d
  75. Stop
  76. .Nm
  77. from becoming a daemon and show debug information on stdout.
  78. .It Fl f Ar filename
  79. Read configuration from
  80. .Ar filename
  81. instead of
  82. .Pa /etc/monmux.conf .
  83. .Sh CONFIGURATION
  84. .Nm
  85. obtains configuration data from
  86. .Pa /etc/monmux.conf .
  87. The configuration file contains one mux stanza that defines on what interface and port
  88. .Nm
  89. should listen to for incoming monitored data. There is a source section for
  90. every host that is to be monitored. The source section defines what data to
  91. accept and where to write that data to. Whitespace, newlines and text behind '#' are ignored. The format in BNF:
  92. .Pp
  93. .nf
  94. stmt = mux-stmt | source-stmt
  95. mux-stmt = "mux" host [ port ]
  96. host = ip4addr | hostname
  97. port = [ "port" | ":" | "," ] portnumber
  98. source-stmt = "source" host "{" accept-stmts write-stmts "}"
  99. accept-stmts = accept-stmt [accept-stmts]
  100. accept-stmt = "accept" "{" resources "}"
  101. resources = resource ["(" argument ")"] [ ","|" " resources ]
  102. resource = "cpu" | "mem" | "if" | "io"
  103. argument = number | interfacename | diskname
  104. write-stmts = write-stmt [write-stmts]
  105. write-stmt = "write" resource "in" filename
  106. .fi
  107. .Pp
  108. Note that
  109. .Va port
  110. in the
  111. .Va mux-stmt
  112. specifies the port-number for both the udp port (incoming
  113. .Xr mon 8
  114. traffic) and the tcp port for incoming listeners.
  115. .Sh EXAMPLE
  116. Here is an example
  117. .Ar monmux.conf
  118. that listens to udp port 2100 on lo0, and accepts cpu, memory, interfaces
  119. xl0/de0/lo0/wi0, disks wd[0-3]/cd[0-1] streams from a
  120. .Xr mon 8
  121. on localhost.
  122. .Nm
  123. will also listen on tcp port 2100 for incoming listeners.
  124. .Pp
  125. .nf
  126. mux 127.0.0.1:2100
  127. source 127.0.0.1 {
  128. accept { cpu(0), mem,
  129. if(xl0), if(de0),
  130. if(lo0), if(wi0),
  131. io(wd0), io(wd1), io(wd2),
  132. io(wd3), io(cd0), io(cd1) }
  133. write cpu(0) in "/export/mon/localhost/cpu0.rrd"
  134. write mem in "/export/mon/localhost/mem.rrd"
  135. write if(xl0) in "/export/mon/localhost/if_xl0.rrd"
  136. write if(de0) in "/export/mon/localhost/if_de0.rrd"
  137. write if(lo0) in "/export/mon/localhost/if_lo0.rrd"
  138. write if(wi0) in "/export/mon/localhost/if_wi0.rrd"
  139. write io(wd0) in "/export/mon/localhost/io_wd0.rrd"
  140. write io(wd1) in "/export/mon/localhost/io_wd1.rrd"
  141. write io(wd2) in "/export/mon/localhost/io_wd2.rrd"
  142. write io(wd3) in "/export/mon/localhost/io_wd3.rrd"
  143. write io(cd0) in "/export/mon/localhost/io_cd0.rrd"
  144. write io(cd1) in "/export/mon/localhost/io_cd1.rrd"
  145. }
  146. .fi
  147. .Sh LISTENERS
  148. .Nm
  149. offers received
  150. .Xr mon 8
  151. data to other programs via tcp. An example of a listener session:
  152. .Pp
  153. .nf
  154. hoard:~/project/mon$ telnet 127.0.0.1 2100
  155. Trying 127.0.0.1...
  156. Connected to 127.0.0.1.
  157. Escape character is '^]'.
  158. 127.0.0.1;io:cd1:1027452867:262:308:536576;io:cd0:1027452867
  159. :0:0:0;io:wd3:1027452867:249140:249140:11797277696;io:wd2:10
  160. 27452867:4074001:4074001:64923271168;io:wd1:1027452867:43183
  161. 9:431839:11880622080;io:wd0:1027452867:10890717:10890717:125
  162. 382360064;if:lo0:1027452867:86952111:86952111:1164079422:116
  163. 4079422:0:0:0:0:0:0;if:de0:1027452867:117562055:90333984:405
  164. 8603563:1844391820:2588654:1:0:0:4013757:0;if:xl0:1027452867
  165. :149845272:187785769:2494862812:739916810:43291:1:3:0:318440
  166. 7:0;mem::1027452867:26566656:68579328:323141632:3571712:1047
  167. 67488;cpu:0:1027452867:0.00:0.00:0.00:0.00:99.00;
  168. ^]
  169. telnet> close
  170. Connection closed.
  171. .fi
  172. .Lp
  173. The format is
  174. .Va mon-version
  175. :
  176. .Va mon-host-ip
  177. :
  178. .Va io|if|cpu|mem
  179. :
  180. .Va stream-argument
  181. :
  182. .Va timestamp
  183. :
  184. .Va data
  185. .Lp
  186. Data formats:
  187. .Bl -tag -width Ds
  188. .It cpu
  189. Time spent in (user, nice, system, interrupt, idle). Total time is 100, data is
  190. offered with precision 2.
  191. .It mem
  192. Memory in (real active, real total, free, swap used, swap total). All values
  193. are in bytes rounded of to page boundaries. Values are 32 bit unsigned integers
  194. internally.
  195. .It if
  196. Interface counters (packets in, packets out, bytes in, bytes out, multicasts
  197. in, multicasts out, errors in, errors out, collisions, drops). Values are 32
  198. bit unsigned integers internally.
  199. .It io
  200. Io/disk counters (total transfers, total seeks, total bytes). Values are 64 bit
  201. unsigned integers internally.
  202. .El
  203. .Sh SIGNALS
  204. .Bl -tag -width Ds
  205. .It SIGHUP
  206. Causes
  207. .Nm
  208. to read
  209. .Pa /etc/monmux.conf
  210. or the file specified by the
  211. .Fl f
  212. flag.
  213. .Nm
  214. will keep the old configuration if errors occured during parsing of the
  215. configuration file.
  216. .El
  217. .Sh FILES
  218. .Bl -tag -width Ds
  219. .It Pa /var/run/monmux.pid
  220. Contains the program id of the
  221. .Nm
  222. daemon.
  223. .It Pa /etc/monmux.conf
  224. .Nm
  225. system wide configuration file.
  226. .El
  227. .Sh BUGS
  228. .Nm
  229. writes incoming data to rrd files "in process". An rrdupdate on a somewhat
  230. stale rrdfile -- with the last data from quite some time in the past -- is a
  231. very expensive operation. This can cause
  232. .Nm
  233. to lockup while rrdupdate is updating the rrd file.
  234. .Nm
  235. will be unresponsive during this process.
  236. .Sh AUTHOR
  237. Willem Dijkstra <wpd@xs4all.nl>
  238. .Sh SEE ALSO
  239. .Xr mon 8