To create new wiki account, please join us on #znc at Libera.Chat and ask admins to create a wiki account for you. You can say thanks to spambots for this inconvenience.

Modules: Difference between revisions

From ZNC
Jump to navigation Jump to search
>Domin
m →‎User Modules: Add awaystore to user modules list
>Domin
m →‎User Modules: add block_motd to user section
Line 36: Line 36:
; [[autovoice]]: Autovoices everyone who joins some channel.
; [[autovoice]]: Autovoices everyone who joins some channel.
; [[awaynick]] : Change your nick while you are away.
; [[awaynick]] : Change your nick while you are away.
; [[Awaystore]] : When you are set away or detached, this module will save all private messages for you. The messages can be read until you delete them. Messages are stored in an encrypted file on your shell (based on the <password> you set, if set). That way everyone who has access to this shell still cannot read your messages. This module will also set you away when you are idle some time (see timer/settimer).  
; [[awaystore]] : When you are set away or detached, this module will save all private messages for you. The messages can be read until you delete them. Messages are stored in an encrypted file on your shell (based on the <password> you set, if set). That way everyone who has access to this shell still cannot read your messages. This module will also set you away when you are idle some time (see timer/settimer).
; [[block_motd]] : This module blocks the server's Message of the Day.  
; [[buffextras]] : Add nick changes, joins, parts, topic changes etc. to your playback buffer.
; [[buffextras]] : Add nick changes, joins, parts, topic changes etc. to your playback buffer.
; [[chansaver]] : Keeping config up to date when user joins and parts.
; [[chansaver]] : Keeping config up to date when user joins and parts.

Revision as of 11:17, 24 November 2012

Overview

Modules are most commonly interfaced with by messaging a special user on irc. For example, to view the highlight keywords in your watch list, you'd send /msg *watch list. When znc sees that the nick you're msging starts with an asterisk, it doesn't forward the message to the ircd but instead sends it to the proper module for processing. In this case, the watch module will get the message and reply to you with a listing of your keywords. This makes for a very convenient and standard way of configuring or otherwise communicating with your loaded modules as well as a common and standard way for your loaded modules to display status or other information back to you. Notice that we said "loaded modules" which brings up the point that you first have to /znc loadmod watch before you can interface with the watch module. Most modules will reply to /msg *module help with a listing of commands.

ZNC modules are loaded either globally or on a per-user basis. Each module itself defines whether it is global or user specific. User level modules can do things ranging from manipulating the incoming/outgoing messages to implementing a full blown twitter client. They can also do more traditional irc tasks such as challenge based auto-op, setting you away, or logging to disk. Each user gets to load and configure their own set of modules to customize their experience to suit their preference.

Global modules are loadable by admins and provide functionality or change behavior for all users. For example, the partyline module has to be global since it provides functionality for all users on a given znc instance to be able to communicate with each other from within znc itself. Global modules can do everything that user level modules can do as well as a few extras. They can replace ZNC's authentication system, modify the config writing process, deal with CAP, etc.

Both global and user level modules can also hook into znc's web interface and provide web content. The most common web module is webadmin which allows admins to add/remove users and allows users to configure their settings from a browser. The web hooks are a fairly new feature available to znc module authors, so stay tuned for some amazing features to come.

Developers

ZNC modules are written in C++ natively. There are also a couple of modules that embed an interpreter to allow you to load perl, python or tcl modules. To learn more about creation of modules you should read Perl Modules, Python Modules or C++ Modules. Feel free to create wikipages about modules you created, but don't forget to add a download link, contact information and use the same layout as the rest of the modules. Contributions are always much appreciated.

Module List

Global Modules

adminlog
Log user connects and disconnects and failed logins to file or syslog.
blockuser
Blocks certain users from using ZNC saying their account was disabled.
connect_throttle
Limit the number of login attempts a user can make per time
fail2ban
Block IPs for some time after a failed login.
imapauth
Allow users to authenticate via IMAP.
lastseen
Logs when a user last logged in to ZNC.
modperl
Loads perl scripts as ZNC modules.
modtcl
Allows you to run tcl scripts in ZNC, including some eggdrop.
partyline
Allows ZNC users to join internal channels and query other ZNC users on the same ZNC.
saslauth
Allow users to authenticate via SASL.
webadmin
Allows you to add/remove/edit users and settings on the fly via a web browser.
notify_connect
Sends a notice to all admins when a user logs in or out.

User Modules

admin
Allows you to add/remove/edit users and settings on the fly via IRC messages.
autoattach
Autoattach watches your detached channels and reattaches you automatically when there is activity in a channel you added to your autoattach list. Read the page about detaching to learn about detached channels.
autocycle
Cycles a channel when you are the only one in there and you don't have op.
autoop
Auto op the good guys.
autoreply
Gives a automatic reply if someone messages you if you are away.
autovoice
Autovoices everyone who joins some channel.
awaynick
Change your nick while you are away.
awaystore
When you are set away or detached, this module will save all private messages for you. The messages can be read until you delete them. Messages are stored in an encrypted file on your shell (based on the <password> you set, if set). That way everyone who has access to this shell still cannot read your messages. This module will also set you away when you are idle some time (see timer/settimer).
block_motd
This module blocks the server's Message of the Day.
buffextras
Add nick changes, joins, parts, topic changes etc. to your playback buffer.
chansaver
Keeping config up to date when user joins and parts.
crypt
Encryption for channel/private messages.
keepnick
Tries to get you your primary nick.
kickrejoin
Implements auto-rejoin-on-kick.
log
Log conversations to file.
nickserv
Auths you with NickServ.
perform
Performs commands on connect.
q
Auths you with Q (and a little more).
raw
View all of the raw traffic.
route_replies
Routes back answers to the right client when connected with multiple clients.
sample
This is an example for writing modules to do whatever you want.
savebuff
Saves your channel buffers into an encrypted file so they can survive restarts and reboots.
schat
SSL (encrypted) DCC chats.
send_raw
Allows you to send raw traffic to IRC from other users.
shell
Have your unix shell in a query window right inside of your IRC client.
simple_away
Automatically set you away on IRC when disconnected from the bouncer.
stickychan
Keeps you sticked to specific channels.
watch
Monitor activity for specific text patterns from specific users and have the text sent to a special query window.

More Modules

For more modules, see Category:Modules.

Managing Modules

Modules can be added or removed easily. Modules can be stored in ~/.znc/modules and /usr/local/lib/znc by default. ZNC installs its modules to that second directory, which in fact is ${prefix}/lib/znc, but this can be changed with ./configure --module-prefix=DIR before compiling.

ZNC will first look in the local sub-directory modules when searching for modules. Only files that end with ".so" will be seen as a module. To remove modules you can simply delete them from the folder. No other configuration changes or restarts are necessary. To remove, but also keep a module for later use you can also change the name, like: mv sample.so sample.so_.

To compile a new module you must first save the source as a ".cpp" file. Compiling modules describes the process in detail.

(Un)Loading Modules

Both global and user modules can be (un)loaded from webadmin or via the *status query window, like:

/msg *status loadmod <module> <parameters>
/msg *status unloadmod <module>
  • * is the StatusPrefix set in your configuration. Usually it's just an asterisk ("*").
  • <module> is based on the modules file name excluding ".so".
  • <parameters> are specific for each module and not required.

Alternatively, global modules can be loaded by adding them to your config file (znc.conf) right before the user definitions, like:

LoadModule = <module> <parameters>
<User foo>

If you want to load user modules by editing config, they have to be added within a specific user, like:

<User foo>
  ...
  LoadModule = <module> <parameters>
  ...
</User>

Please keep in mind, that a user is not able to load a module, if the directive "DenyLoadMod" is set to true. Trying to load a module will fail with "Unable to load [<module>] Access Denied.".

Using modules

It is recommended to read the module's wikipage if you want to find out how a module works. Alternatively the following command can be used to get a command list:

/msg *<module> help
  • * is the StatusPrefix set in your config file.

External modules

droproot
Allows ZNC to drop root privileges on systems that implement POSIX setuid/setgid.
motdfile
Reads a MOTD from a file and displays it to users when they login.
notify
Notifies all ZNC users when a client attaches/detaches.
amsgfilter
Filters amsgs from specified channels.
antiidle
Hides your idle time.
autoattach
Reattaches you to channels on activity.
colloquy
Push private messages and highlights to your iPhone/iPod Touch via Colloquy Mobile.
email
Monitors email activity on local disk /var/mail/user.
fish
FiSH encryption for channel/private messages.
fixfreenode
This module blocks some freenode-specific feature which results in plus (+) and minus (-) signs being displayed in front of every message from a client.
fakeonline
Fakes online status of ZNC *-users, to fix some clients.
notifo
Send private messages and highlights to your mobile devices using Notifo. Includes a highly configurable set of conditions to control how and when notifications get sent.
twitter
Implements a Twitter client. It can post new tweets and monitor searches, users, timeline and @mentions.

See this page for a list of external modules http://wiki.znc.in/Category:External_Modules