XYMONPROXY(8)

💖 XYMONPROXY 💖

okay bestie, so this is xymonproxy, straight outta the System Manager's Manual, section 8. lowkey one of the most useful little gremlins in the whole Xymon family. let's get into it 🫶

---

✨ NAME ✨

xymonproxy — the Xymon message proxy 💅

---

🦋 SYNOPSIS 🦋

xymonproxy [options] --server=$XYMSRV

---

🌸 DESCRIPTION 🌸

okay so xymonproxy(8) is a proxy that forwards Xymon messages from one server to another. when do you even need it? classic scenario: your clients are sitting behind a firewall and literally cannot send their status messages to the Xymon server directly. that's the vibe, and this is the fix. 🧱

and ngl, xymonproxy serves three purposes, and it's giving main character energy on all three:

1. it's a regular proxy server. clients that can't connect directly to the Xymon servers can still send their data through it. and yes, it's optimized for handling status messages, but bestie it will forward all types of messages — including notes- and data-messages. no gatekeeping here 💖
2. it's a buffer. if a ton of clients all try to send status messages simultaneously (peak load chaos 😭), xymonproxy smooths that out. it can absorb messages very quickly, but it queues them up internally and forwards them to the Xymon server at a reasonable pace. queen of time management, fr fr ✨
3. it merges messages. small "status" messages get merged into bigger "combo" messages. this can dramatically decrease the number of connections that need to go from xymonproxy to the Xymon server. but heads up 🫣 — the merging of messages causes "status" messages to be delayed for up to 0.25 seconds before being sent off to the Xymon server. tiny price, huge payoff.

---

🎀 OPTIONS 🎀

• --server=SERVERIP[:PORT][,SERVER2IP[:PORT]] — tells it the IP-address and optional portnumber where incoming messages are forwarded to. the default portnumber is 1984, the standard Xymon port number. if you've set up the normal Xymon environment, you can just use --server=$XYMSRV. up to 3 servers can be specified, and incoming messages are sent to all of them — except "config", "query" and "download" messages, which go to the LAST server only. and if you have Xymon clients sending their data via this proxy, note that the clients will receive their configuration data from the LAST of the servers listed here. 👀 this option is required.
• --listen=LOCALIP[:PORT] — specifies the IP-adress where xymonproxy listens for incoming connections. by default, xymonproxy listens on all IP-addresses assigned to the host. if no portnumber is given, port 1984 will be used. 💫
• --timeout=N — the number of seconds after which a connection is aborted due to a timeout. default: 10 seconds. ⏰
• --report=[PROXYHOSTNAME.]SERVICE — if given, this option causes xymonproxy to send a status report every 5 minutes to the Xymon server about itself (yes, self-reporting, we love an introspective icon ✨). if you've set the standard Xymon environment, you can use --report=xymonproxy to have xymonproxy report its status to a "xymonproxy" column in Xymon. the default for PROXYHOSTNAME is the $MACHINE environment variable, i.e. the hostname of the server running xymonproxy. scroll to REPORT OUTPUT below for what's actually in that report 🫶
• --lqueue=N — the size of the listen-queue, aka where incoming connections can queue up before being processed. this should be large to accommodate bursts of activity from clients. default: 512. 📚
• --daemon — run in daemon mode, i.e. detach and run as a background process. this is the default. ✨
• --no-daemon — runs xymonproxy as a foreground process. 🧍
• --pidfile=FILENAME — the location of a file containing the process-ID of the xymonproxy daemon process. default: /var/run/xymonproxy.pid.
• --logfile=FILENAME — sends all logging output to the specified file instead of stderr.
• --log-details — logs details (IP-address, message type and hostname) to the logfile. this can also be enabled and disabled at run-time by sending the xymonproxy process a SIGUSR1 signal. 🔍
• --debug — enable debugging output. 🐛

---

📊 REPORT OUTPUT 📊

if enabled via the --report option, xymonproxy will send a status message about itself to the Xymon server once every 5 minutes.

the status message includes the following information:

• Incoming messages — the total number of connections accepted from clients since the proxy started. the "(N msgs/second)" is the average number of messages per second over the past 5 minutes.
• Outbound messages — the total number of messages sent to the Xymon server. note that this is probably smaller than the number of incoming messages, since xymonproxy merges messages before sending them. ✂️
• Incoming - Combo messages — the number of "combo" messages received from a client.
• Incoming - Status messages — the number of "status" messages received from a client. xymonproxy attempts to merge these into "combo" messages. the "Messages merged" is the number of "status" messages that were merged into a combo message, and the "Resulting combos" is the number of "combo" messages that resulted from the merging. 🧬
• Incoming - Other messages — the number of other messages (data, notes, ack, query, ...) messages received from a client.
• Proxy resources - Connection table size — the number of connection table slots in the proxy. this measures the number of simultaneously active requests that the proxy has handled, so it gives you an idea about the peak number of clients that the proxy has handled simultaneously. 📈
• Proxy resources - Buffer space — the number of KB memory allocated for network buffers.
• Timeout details - reading from client — the number of messages dropped because reading the message from the client timed out. 💀
• Timeout details - connecting to server — the number of messages dropped, because a connection to the Xymon server could not be established.
• Timeout details - sending to server — the number of messages dropped because the communication to the Xymon server timed out after a connection was established.
• Timeout details - recovered — when a timeout happens while sending the status message to the server, xymonproxy will attempt to recover the message and retry sending it to the server after waiting a few seconds. this number is the number of messages that were recovered, and so were not lost. 🩹
• Timeout details - reading from server — the number of response messages that timed out while attempting to read them from the server. note that this applies to the "config" and "query" messages only, since all other message types do not get any response from the servers.
• Timeout details - sending to client — the number of response messages that timed out while attempting to send them to the client. note that this applies to the "config" and "query" messages only, since all other message types do not get any response from the servers.
• Average queue time — the average time it took the proxy to process a message, calculated from the messages that have passed through the proxy during the past 5 minutes. this number is computed from the messages that actually end up establishing a connection to the Xymon server, i.e. status messages that were combined into combo-messages do not go into the calculation — because if they did, it would reduce the average time, since it's faster to merge messages than send them out over the network. 🤓

---

if you think the numbers do not add up, here is how they relate. 🧮

the "Incoming messages" should be equal to the sum of the "Incoming Combo/Status/Page/Other messages", or slightly more because messages in transit are not included in the per-type message counts. 🚧

the "Outbound messages" should be equal to the sum of the "Incoming Combo/Page/Other messages", plus the "Resulting combos" count, plus "Incoming Status messages" minus "Messages merged" (this latter number is the number of status messages that were NOT merged into combos, but sent directly). the "Outbound messages" may be slightly lower than that, because messages in transit are not included in the "Outbound messages" count until they have been fully sent. 💌

---

🚨 SIGNALS 🚨

• SIGHUP — re-opens the logfile, e.g. after it has been rotated. 🔄
• SIGTERM — shut down the proxy. ✌️
• SIGUSR1 — toggles logging of individual messages. 🔀

---

👀 SEE ALSO 👀

xymon(1), xymond(1), xymon(7)

---

and that's the whole page, bestie 💖 this one's from Xymon Version 4.3.30, dated 4 Sep 2019. go forth and proxy, you've absolutely got this 🫶✨