Submitted by:
Colin Hudler
Description:
This ZenPack contains only a zendaemon which uses twisted.jabber to connect to a jabber server and expose certain Zenoss utilities, as well as send alerts to subscribed and authorized users.
Screenshots:
REQUIREMENTS:
Zenoss Version: It is known to work in Zenoss 2.4.1, 2.4.5, and 2.5 (Core and Enterpise) with py2.4 file. For Zenoss 3.0 use the py2.6 file. The bot was tested with OpenFire and Google Talk.
ZenPack Dependencies: none
External Dependencies:
Installation:
- Install the ZenPack using the usual method. (webui, or zenpack --install)
- Open for edit the file $ZENHOME/etc/xmppBot.conf. You need to set some things for the bot to connect successfully. The minimum settings required are
- jabber_pass: the password the bot should use to connect
- jabber_user: the user the bot should connect as. Should only include the username, not the host. That is only the name, not the JID (i.e. zenbot, not zenbot@talk.google.com
- jabber_host: the jabber server.
- first_user: this is optional, but you will not be able to chat with the bot if you do not set this. More details on this and other options are below.
- Once you have the configuration set, restart zenoss. The bot will be started along with the other daemons. It logs to $ZENHOME/logs/xmppBot.log
- These are details of the xmpp specific options supported in this version.
- jabber_host: This is the address of the jabber server. It will be used to build the remainder of the jabber ID when the bot communicates, so it must be the actual name of the server. If this is not feasible (stunnel is used, or DNS is not used), use the im_host option to set the real server identity.
- jabber_port: Default jabber port is 5222. NOTE WELL: Twisted 8.1 that zenoss bundles has a bug which prevents TLS from working with OpenFire and Gtalk jabber servers (probably others, also). This bot will not do TLS over port 5222. If you need SSL, use 5223 and the "ssl" option, or use stunnel, like I do. (See Known Issues below, for more information on SSL)
- first_user: Because incoming jabber messages will come from unknown persons, the bot needs a way to map the messages to Zenoss users. This is done with a Zope property "JabberId" on the user object. The mappings are managed with the bot command "mapuser". Since the bot will start without any mappings, we need at least one user to Bootstrap the others. That is what this option does. Specify the first user mapping like this: zenusername,jabberuser@example.com.
- im_host: This option is normally not needed. Use it to set the REAL im server which appears after th e "@" in your JID strings. Use this when you want to connect to an IP address, or through a proxy like stunnel. By default the bot will use jabber_host for this value.
- ssl: Set this value to anything and the bot will attempt to use SSL when communicating with the server. TLS is NOT supported, and typically the port is changed to 5223, although the bot will not do this for you. (See Known Issues below, for more information)
- group_server: If the bot is going to participate in groupchat, it needs to know the groupchat server (conference server). The default is to prepend "conference" to jabber_host, which will probably not work for you.
- chatroom: If the bot should join a room when it connects, specify it here. It can be the entire room 'bot-room@im.example.com' or simply bot-room, if the group_server has been specified above. The bot will also respond to invites.
Features/Synopsis
The bot has a simple plugin system, so it is easy to add functionality. It comes with 6 command plugins, and one Access Control plugin.- Command Plugins
- users (simply lists zenoss users and what the bot thinks their jabberId is).
- model (model a device)
- mapuser (manage the jabberId of Zenoss users; authorize them to communicate with the bot)
- ack (acknowledge alerts)
- data (pull data from zenoss (any datapoint on any device/component))
- events (query for events/status)
- Access Control
Most jabber servers are on an open federation. This means any user can message any other. The bot must know that the user is part of it's local zenoss installation before it processes the message. The zenuser jabberId property must be set to the same as the incoming message. Access control is disabled for groupchat, because users can set their own aliases. Chatroom members in the room with the bot must be trusted by you. - Alerting
The bot adds a new alert Action, which you will find beneath the ordinary Zenoss actions "page" and "email". When this action is set, the bot handles the alert rule exactly as Zenoss itself. Just like zenactions, it respects the same rules, schedule, repeat, etc. If you want messages to go to a chatroom, create a normal alert rule, but set "Address" to someroom@conference.example.com/groupchat. When the bot sees the /groupchat resource, it will know to address the room. Aside from that exception, the Address field works the same as other alerting rules. You may leave it blank and the bot will use the aforementioned JabberId property, if it is set. - Mute/Unmute
If an authorized user issues the "mute" command, the bot will cease *all* outgoing xmpp messaging activity until "unmute" is issued. - help
A global "help" command will list available commands. If the commands support help they can be seen with "someCmd -h"
(16:31:05) zenbot10 has signed on.
(16:31:09) chudler: help
(16:31:09) zenbot10: In a groupchat, all commands start with "zenbot10:" or "!."
In private chat, simply type the command.
These are the commands available. For help on a command, try -h
model
users
ack
mapuser
data
events
(16:31:41) chudler: data -h
(16:31:41) zenbot10: option -h: usage: ack [options]
Retrieve latest value read from the device for datapoint. Simple example:
data -d 10.1.1.1 -p laLoadInt1
options:
-h, --help show this help message and exit
-d DEVICENAME, --device=DEVICENAME
Device name, IP or MAC.
-p DATAPOINTNAME, --point=DATAPOINTNAME
Acknowledge all events. If -e is also specified, it
will still acknowledge every event.
-l, --list Only list datapoints for the device and/or component.
-s SUBCOMPONENT, --subcomponent=SUBCOMPONENT
Optional subcomponent name, if the datapoint does not
reside directly on the device. You will probably have
to specify this. Here are two usage example: data
-d buffalo.example.com -p usedBlocks -s filesystems
data -10.1.1.1 -p ifInErrors -s interfaces
(16:32:10) chudler: data -d viclus -l
(16:32:11) zenbot10: Valid datapoints:
ssCpuRawIdle (Devices_Server_Templates_Device_ssCpuRawIdle_ssCpuRawIdle)
loss (Devices_Templates_b_fping_fping_loss)
memBuffer (Devices_Server_Templates_Device_memBuffer_memBuffer)
(16:32:35) chudler: data -d viclus -p ssCpuRawIdle
(16:32:36) zenbot10: viclus.example.com: 88.87
(16:33:25) chudler: events -d vi00
(16:33:25) zenbot10: Current Events
viclus.example.com: threshold of CPU Utilization not met: current value 0.00 (id:eb1ccd35-d2e6-483f-b0b9-a973ccad99c0)
(16:34:47) chudler: ack -e ad99c0 -t
(16:34:48) zenbot10: Test mode: 1 WOULD have been acknowledged.
(16:35:18) chudler: ack -e 973ccad99c0
(16:35:18) zenbot10: Acknowledged 1
Source: http://zenpacks.zenoss.org/trac-zenpacks/browser/zenpacks/ZenPacks.chudler.xmppBot
Tagged Releases:
- http://zenpacks.zenoss.org/trac-zenpacks/browser/tags/xmppbot-1.0
- http://zenpacks.zenoss.org/trac-zenpacks/browser/tags/xmppbot-1.1
Change History:
- 1.1 http://zenpacks.zenoss.org/trac-zenpacks/changeset/401 based on xmppBot in 2.5 thread
Trac tickets: http://zenpacks.zenoss.org/trac-zenpacks/report/1
Known issues:
- The bot will respond to anyone in groupchat. Keep the chatroom clear of untrusted people.
- If the "ssl" option is used (likely), pyopenssl must be installed. This is a requirement of the "twisted.jabber" framework. For more information, see this howto
- If you use Granular access control (Enterprise), the bot will bypass it for the users. I.e. it does not respect Zenoss access control.
- Zenactions will periodically complain that it cannot process the sendXmpp event for any user that has a xmpp rule Action defined. This will look in the logs like this:
Traceback (most recent call last):It can be ignored because the bot starts after zenactions has already been built, and it handles these event rules.
File "/opt/zenoss/Products/ZenEvents/zenactions.py", line 236, in processRules
actfunc = getattr(self, "send"+ar.action.title())
AttributeError: ZenActions instance has no attribute 'sendXmpp' - The bot might log an error when it first starts. It has to do with sending alerts before the im session is open.
- when using the "model" command, it will block the bot from responding to other requests until the model is finished. Also, it does not provide good feedback on the model (no logs, no success/error).
- Untested in distributed environment (it should work)
- The bot will accept roster requests from authorized users. It will also join rooms it has been invited to by authorized users. More xmppBot plugins are planned, and ideas are welcome.
