An OpenSource VooDoo cIRCle version 1.0.53 - documentation for users

logo

Table of contents

  1. Developers
  2. Purpose
  3. Change log
  4. Configuration - file logic.txt
    1. Basic configuration knowledge
    2. Structure of logic.txt file
    3. Other access flags has little bit similar meaning
    4. List of events that can be assigned to user on channel
    5. List of flood limits assigned to specific user on channel
    6. Channel definitions
    7. Events on channel definition
    8. Private definitions
    9. Procedure commands and syntax
    10. "op" command
    11. "deop" command
    12. "voice" command
    13. "devoice" command
    14. "kick" command
    15. "msg" command
    16. "msgq" command
    17. "if_match" command
    18. "!if_match" command
    19. "if_match_case_insensitive" command
    20. "!if_match_case_insensitive" command
    21. "if_in" command
    22. "!if_in" command
    23. "if_group" command
    24. "!if_group" command
    25. "return" command
    26. "timer_once" command
    27. "timer_every" command
    28. "execute" command
    29. "SMTP" command
    30. "NET_SEND" command
    31. "LOG" command
    32. "join" command
    33. "part" command
    34. "disconnect" command
    35. "irc_server" command
    36. "try_connect" and "if_error" command sequence
    37. "bot_nick" command
    38. "bot_ident" command
    39. "bot_ident_ipv6" command
    40. "bot_fullname" command
    41. "bot_auth" command
    42. "allow_redirect" command
    43. "sleep" command
    44. "restart" command
    45. "notice" command
    46. "noticeq" command
    47. "unban_mask" command
    48. "ban_mask" command
    49. "dcc_server" command
    50. "dcc_server_ipv6" command
    51. "label" command
    52. "goto" command
    53. "ident" command
    54. "host" command
    55. "SCRIPT" command
    56. "telnet_server" command
    57. "telnet_server_ipv6" command
    58. "link" command
    59. "work" command
    60. "chan_mode" command
    61. "change_nick" command
    62. "kill_timers" command
    63. "get_chan_mode" command
    64. "get_chan_topic" command
    65. "topic" command
    66. "check_dynamic_bans" command
    67. "dynamic_ban" command
    68. "process_on_banned" command
    69. "raw" command
    70. "remote_execute" command
    71. "delete_irc_servers" command
    72. "delete_nicks" command
    73. "admin_msg" command
  5. Configuration - file "conf.txt"
    1. botname
    2. admin - your e-mail
    3. botnet_penalty
    4. log_echo_debug
    5. log_echo_irc
    6. log_echo_socket
    7. log_echo_bot
    8. log_echo_identd
    9. log_echo_botnet
    10. log_echo_botnet_debug
    11. log_debug
    12. log_irc
    13. log_socket
    14. log_bot
    15. log_identd
    16. log_botnet
    17. log_botnet_debug
    18. php_processor
    19. php_script_dir
    20. php_1
    21. php_2
    22. php_2_1
    23. dcc_bind_ip
    24. dcc_bind_ip6
    25. notify_interval
    26. dcc_max_transfers
    27. ctcp_lag_user_msgs
    28. ctcp_lag_user_seconds
    29. dcc_send_timeout
    30. irc_bot_flood_bytes
    31. irc_bot_flood_seconds
    32. irc_bot_flood_lines
    33. 127.0.0.1_dcc_user
    34. msg_force_secure_lines
    35. irc_bot_flood_other_seconds
    36. try_reverse_lookup
    37. important_ident_daemon
    38. compress_mode_wait
    39. smart_mode
    40. send_+R
    41. dcc_chat_ping_interval
    42. lockout_duration
    43. lockout_count
    44. dcc_max_message_size
    45. dcc_max_sessions_per_ip
    46. auto_backup_interval
    47. disable_ident_daemon
    48. dcc_always_want_nick
  6. Quick start
  7. Botnet and replication
  8. PHP scripting (old method)
  9. PHP scripting ("php_2" method)
  10. DCC / telnet commands
    1. .help
    2. .whois <name>
    3. .+user
    4. .edituser
    5. .+proc
    6. .editproc
    7. .editchan
    8. .+chan
    9. .quit
    10. .backup
    11. .rehash
    12. .filesystem
    13. .msg
    14. .getfile <filename> <optional_dcc_group>
    15. .partyline <partyline_channel_(optional)>
    16. .leave
    17. .restart
    18. .die
    19. .+group <groupname>
    20. .private
    21. .replication
    22. .terminator
    23. .lang
    24. .part
    25. .join
    26. .rproc
    27. .upgrade
    28. .chpass
    29. .showbots
    30. .broadcastping
    31. .execute
    32. .apply
  11. Filesystem
  12. VooDoo cIRCle service (Windows(TM) only)
    1. Installation of service
    2. Configuration of service
    3. Contents of this file
    4. Example
  13. SSL
  14. MOTD - Message Of The Day file
  15. CLI - command line interface
  16. Good tips
  17. FAQ's
    1. How can I delete user?
    2. Which host masks/wildcards are supported?
    3. Does IPv6 host masks for IPv6 IRC users work even bot is not compiled with IPv6 support?
    4. How could I compile bot with IPv6 support?
    5. There is feature that supports recognition also by their "full name mask". Can I turn it off?
    6. How can I compile this bot?
  18. Additional information
  19. Credits
  20. License

Developing of this software:
VooDoo cIRCle Copyright (C) 2004-2005 by Marian VooDooMan Meravy (ghostvoodooman [NOSPAM] (at) [NOSPAM] users (dot) [NOSPAM!] sourceforge (dot) net)
 
VooDoo cIRCle comes with ABSOLUTELY NO WARRANTY; for details see `license.html'. This is free software, and you are welcome to redistribute it under certain conditions; see the license for details. This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)
 
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).

Purpose

VooDoo cIRCle is an IRC (ro)bot.


Changes

(skip ChangeLog)

Release version 1.0.53
Date: 2005-07-10
Bug fix: Stuck in the loop while "ERROR" response from IRC server while in authentication state.
Bug fix: *NIX: Registration timeouts.
Bug fix: *NIX: Strange message "513 nick :Your client may not be compatible with this server." from some exotic IRC servers, while bot on *NIX, but not on Win32. Thanks to Varun for reporting this.
Bug fix: Possibility of infinite loop ending with stack overflow in "on_internal_event" event procedure, when a C++ exception is thrown due to ".rehash".
Improvement: Win32: Binary distribution: Upgraded .dll's to OpenSSL-0.9.8 (major release from 2005-07-05) - see http://www.openssl.org/ .

Release version 1.0.52
Date: 2005-07-09
Bug fix: Non-critical bug, where user on DCC/telnet connection in some conditions stopped receiving PING? messages according to enabled "dcc_chat_ping_interval=xxx" ping period.
Bug fix: There was missing EOL sequence (\r\n on telnet, \n on DCC) connection while ".getfile <name_of_file>" failed due to reasons like "No such file", "Access denied", and "I/O error".
Bug fix: In certain conditions, if user is downloading file from filesystem, and issuing next ".getfile" command, s/he could get greeting as on DCC chat/telnet connection, instead of real file. Now fixed.
Bug fix: On DCC CHAT connection, there were \0x08 characters after password supplied, which should be only on telnet connection. Now fixed.
Bug fix: Forgotten to close file "logic.txt" after unsuccessful ".rehash", so roll-back to old configuration was malfunctioning.
Semi-bug fix: On DCC/telnet connection, there was in ".filesystem" -> ".editfile <name_of_file>" -> ".attr" nothing displayed if user wrote bad command, so it was confusing. Now displays list of available commands in this case.
Semi-bug fix: Errors reported in file "logic.txt": Now we are counting lines from one - not zero-based from now on. I've decided to do so, because many text editors count them from one.
Improvement: Added "on_internal_event" event, for better monitoring of your bot. See documentation.
Improvement: PING? message on DCC/telnet connection is now timestamped, and shows your idle time.
Improvement: Changed format of channel logs to much clever messages (believe me or not). Now shows actual mode of user (op, voice,...) for better orientation in logs.
Improvement: Channel logs now contains entries if an IRC operator is detected on channel by WHOIS on their JOIN, or bot's JOIN followed by WHOIS burst, and also if an IRC operator QUITs/PARTs/gets-KICKed.
Improvement: Added "dcc_always_want_nick" attribute to "conf.txt" file. See documentation.
Improvement: Bot now silently ignores user name and password on DCC/telnet connections that matches mask "### *" ('#' stands for one numeric character) for better compatibility with "/dcc chat 127.0.0.1:2010" command while using mIRC.

Release version 1.0.51
Date: 2005-07-01
Bug fix: If procedure in "logic.txt" for on_kick event of user with "host_bot" flag (the bot itself) contained command "join" to re-join channel, the command weren't performed.

Release version 1.0.50
Date: 2005-06-29
Bug fix: Forgot to close filesystem file after it has been sent to client. (Saving resources)
Bug fix: Forgot to close file "pass.txt" in certain conditions. (Saving resources)
Bug fix: PONG response to server's PING: forgotten colon separator between command and "comment" (PONG argument).
Bug fix: DCC invitation was not working if supplied address was compressed IPv6 address (containing "::" sequence).
Semi-bug fix: Fixed annoying PING? message on DCC/telnet connection that wasn't in order of "dcc_chat_ping_interval" interval.
Semi-bug fix: Less doubled messages on ".broadcastping" command (pinging all bots on BOTNET).
Improvement: Bot now detects DCC invitation IP address spoofing. Until now, it accepted any address passed to CTCP DCC invitation, now accepts only IP address that coresponds (afte DNS resolution) to user's host (nick!ident@HOST).
Improvement: If CPU load were *really* high, bot didn't get response to each 60 seconds' "keep-alive" WHOIS to itself in 120 seconds, you've seen quitting it by EOF from client and reconnect. Now timeout to receive response is 3 minutes, sending PING to server as "keep-alive" (WHOIS could be penalised!) each 30 seconds. Hope this will help.
Improvement: ".broadcastping" now receives also version of remote connected bot(s) - but only if both sides are version >= 1.0.50.
Improvement: Added "admin_msg" command to "logic.txt". See documentation.

Release version 1.0.49
Date: 2005-06-15
Bug fix: Bot could crash if there was attemp to run script which andiminstrator forgot to create (.php file).
Bug fix: Resolved problem while using ".getfile" command issued on private query when user's host wasn't numeric IP address, but DNS name.
Bug fix: There was incorrect timestamp reported when user read message/downloaded file.

Release version 1.0.48
Date: 2005-06-13
Bug fix: Old-style php scripting: user's mode had nick, not mode string.

Release version 1.0.47
Date: 2005-06-13
Improvement: Added list of groups for users to PHP scripting facility.
Improvement: Now bot logs a record to debug log if there are incorrect lines inside magic command section of script's output.

Release version 1.0.46
Date: 2005-06-10
Bug fix: Win32: Service didn't start up the bot if defined pre-startup idle was non-zero.

Release version 1.0.45
Date: 2005-06-09
Bug fix: On telnet connection, there was \n character instead of \r\n sequence while setting expiration on new FileSystem object.
Bug fix: Linker error unresolved external logic_on_flood() while using Dev-C++. (Still it should use implicit typecast while having "time_t" in header file and "int" in source file, like other compilers do.)
Bug fix: Now using ident username as argument to "USER" command, not nick.
Bug fix: If there was no access to log files (permission denied) there wasn't also write to console (if enabled).
Improvement: Made "library_php_2.inc.php" needed for "php_2" method scripting compatible also for earlier versions of php (<5).
(see documentation here, here and here)

Release version 1.0.44
Date: 2005-06-06
Semi-bug fix: PHP preprocessor sometimes returns error code 255, when there is parse error in the script, but it is also handled by set_error_handler(). Bot ignored output of script with return codes not equal to zero. Now accepts *everyting*, continues to seek for magick commands in the output.
Improvement: Less warnings on compile.

Release version 1.0.43
Date: 2005-06-05
Bug fix: When script runs longer than 10 minuters, the bot crashed.
Semi-bug fix: No message after ".filesystem" command, now tells to use ".help" to get available commands.

Release version 1.0.42
Date: 2005-06-04
Bug fix: PHP scripting: There was incorrect UserNotified value taken from OwnerNotified.
Bug fix: Fixed DCC SEND problem when someone requested file via ".getfile" as private query.
Bug fix: Bot wasn't remembering +b bans and +e exceptions when someone set it, while bot was already on channel.
Semi-bug fix: Added check whether the procedure is already defined (no overloading support!).
Improvement: Added "php_2" method for PHP scripting. See documentation.
Improvement: Added modes and topics of channel to PHP scripting support.
Improvement: When channel is +k (key-protected), and bot has tried all keys in history of keys listing, it schedules JOIN to 15 secods later (if someone removes key, or set key to one from the history of keys listing).

Release version 1.0.41
Date: 2005-05-30
Bug fix: Removed forgotten write (printf()) of debug string to console.
Bug fix: Win32: Turned off handle inheritance while spawning new instance by ".upgrade" and ".restart" commands causing not to close some handles.
Bug fix: Fixed missing string in file "lang01.txt" causing display of incorrect string when user with no password yet set logs-in to telnet connection. However, user logging in for the first time still needs to use DCC CHAT, not telnet for security reasons, or admin of bot should set them password.
Improvement: Better logging and copying log to console while ".restart" command. Now notifies in case of error spawning new instance, and writes real error code, in this case it is 2, in case of success it is 0.
Improvement: Win32: Service application ("vdcsvc.exe") gets now control over ".restart" command, so if it is used, bot on ".restart" command leaves respawning on it. This fixes problem after two ".restart" commands.

Release version 1.0.40
Date: 2005-05-25
Bug fix: No longer setting "internal mode" status on op/deop/voice/devoice, but when we do so, we wait for acknowledgement from IRC server (response). There was problem when bot was deopped and script told to op other users, bot thought that it has op (seen in ".stat" status). Occured sometimes on mass deopping (-ooo).
Bug fix: Don't send JOIN on "join" command if we are already on channel, don't send PART on "part" command if we are not on channel.
Bug fix: Win32: "NET_SEND" command was not working.
Semi-bug fix: We are not waiting now for response to MODE +b mask and KICK nick (commands "ban_mask" and "kick"), because these commands should be posted as soon as possible (takeover hot while).

Release version 1.0.39
Date: 2005-05-24
Bug fix: Automatic backup was invoked on also startup, now really after elapsing time period.
Bug fix: There was 20 seconds wait after KICK command, response from IRC server was ignored in error (in order to kill 20 seconds wait before next command).

Release version 1.0.38
Date: 2005-05-23
Improvement: Added ".apply" command, "access_to_apply", "access_grant_apply" rights. See docuemntation.
Improvement: Added "auto_backup_interval" attribute to "conf.txt" file. See documentation.
Improvement: Bot automatically backs-up configuration ("logic.txt") on die/restart/upgrade.

Release version 1.0.37
Date: 2005-05-22
Improvement/semi-bug fix: Now bot is doing "synchronous communication" with IRC server - always waits for response from IRC server after message, then sends next message (no WHOIS flood on startup!).
Improvement: Now using "MODES" parameter from 005 ISUPPORT message to find out how many modes can be used in "compressed mode" (for "MODES=3": MODE +ooo nick1 nick2 nick3), till now it was fixed to 3.
Improvement/semi-bug fix: Now after ".upgrade" command bot copies itself from "upgrade" dir to one level upper ("..") only once, not every while.

Release version 1.0.36
Date: 2005-05-17
Bug fix: Win32: Forgot to close unused handles for sub-processes, such as PHP script and sendmail after they exits, which consumed resources under Win32.
Improvement: Now we are accepting also PHP preprocessor in the SPACE character in path.
Bug fix: Linux/BSD: Fixed errors while trying to compile (depfiles problem).

Release version 1.0.35
Date: 2005-05-11
Improvement: Fixed *NIX build problems, updated documentation.

Release version 1.0.34
Date: 2005-04-27
Bug fix: Not correctly set argument to memset() as size of buffer in module botnet.cpp at various places (set 4 bytes instead of much more) causing on remote side of BOTNET connection possibility of false positive buffer overflow detected and closing connection while replication of "private definitions" section of logic.txt configuration file.
Bug fix: Forgotten debug string in win_sock.cpp/sock_connect() for my internal purposes to comment out.
Improvement: BOTNET packet receive code botnet.cpp/botnet_receive() completely recoded to be much clear code to understand.
Improvement: Buffer overflow detection routine recoded to be much clear code to understand.
Improvement: botnet.cpp module clean up of old commented out code.

Release version 1.0.33
Date: 2005-04-26
Bug fix: No more responses to CTCP quoted NOTICE's (RFC is saying strictly that there MUST NOT be automatic reply to NOTICE). However, CTCP request is only PRIVMSG, not NOTICE.
Bug fix: ...many forgotten bug fixes related to CTCP messages handling.
Bug fix: Packets received on BOTNET with commands from protocol BOTNET 5 and later were not fully functioning.
Security minor bug fix: There was possibility of buffer overflow while receiving specially crafted packet on BOTNET connection which could crash bot. Since the length of buffer was not tested inside the packet frame, but packet as whole was tested, there is not possibility of disclosure of sensitive information, nor execution of arbitrary code. However, it is still needed for intruder to know password of remote bot, and, if SSL connection is only allowed for remote bot, it needs correct client's certificate to process these crafted packets; without previous successful authentication it is not possible. (affected versions: from 1.0.20 to 1.0.32 inclusive)
Semi-bug fix: Fixed unknown mode +i panic warning in debug log on UnrealIRCd.
Improvement: Added on_broadcast event to catch IRC operators' PRIVMSG's and NOTICE's separately from other messages so far passed to private definitions section's on_privmsg and on_notice events - from now not.
Improvement: Added on_server_msg event to channel definition and private definition.
Improvement: Added informations about current IRC server host/port to PHP script.
Improvement: From now on, using YYYY-MM-DD style of timestamp in ChangeLog, as recommended international format of date, instead of YYYY/MM/DD :-)

Release version 1.0.32
Date: 2005/04/16
This release is to support developers and to support FreeBSD builing.
Semi-bug fix: If domain part of user's host mask contains "#" (hash) symbol, it is not passed to DNS resolver while compiling "logic.txt" (chacheing DNS names).
Bug fix: Segmentation fault on FreeBSD while unsuccessful DNS resolve.
Improvement: Now compilable and working well on FreeBSD.

Release version 1.0.31
Date: 2005/04/13
Bug fix: on_join event for user "unknown" was called twice.

Release version 1.0.30
Date: 2005/04/09
This release is to support developers and to support Linux builing.
Added: Documentation how to build using MSVC 7, Dev-C++ 4.9.9.1, GCC 3.3.2, KDevelop 3.
Updated: Project files.

Release version 1.0.29
Date: 2005/04/05
Bug fix: Attribute last_changed in various DCC/telnet administration routines was not properly updated.
Bug fix: .private command on DCC/telnet connection was not properly working.
Improvement: Now MD5-encoded (hashed) "passwords" in file "pass.txt" are compared case-insensitive.

Release version 1.0.28
Date: 2005/04/04
Bug fix: Deadlock in new user's .pl command (access to partyline number of lines/seconds to limit the flood).
Improvement: PHP scripts can now modify filesystem. See documentation.
Improvement: Added on_fnc event. See documentation.

Release version 1.0.27
Date: 2005/03/23
Bug fix: Corrected telnet EOL sequence on telnet connection while displaying message from filesystem (telnet uses \r\n, not just \n!).
Bug fix: Problem with accepting TCP connections on listening socket on Linux.
Semi-bug fix: Corrected message from filesystem splitting into multiple PRIVMSG's when sending as private query, it was splitted into multiple lines every 128 characters in filesys.cpp while reading the file + new line character (\n), which was ignored while counting; now it is correctly splitted in irc.cpp every 256 characters, or on new line character (\n), whichever comes first. So now we will have less number of PRIVMSG's.
Semi-bug fix: Fixed incompatibility while compiling with GCC.
Improvement: Now messages from filesystem (such as "Subject:", "Message from owner:", hints how to download file with DCC) can be also localized to more native languages (file "lang/lang01.txt").

Release version 1.0.26
Date: 2005/03/17
Improvement: Security: Remote bot on BOTNET need to have access_usage_procedure on event's procedure to change existing user's on_XXX events.
Improvement: Security: Remote bot on BOTNET need to have access_usage_procedure on event's procedure to set existing user's on_XXX events.
Improvement: Security: Remote bot on BOTNET need to have access_grant_can_send_unknown_users right to change or set user's can_send_unknown_users flag.
Improvement: Security: Procedures are replicated first, users then.
Improvement: BotNet: After pulling of new procedure, bot sets access_usage_procedure right to remote bot on that procedure.
Improvement: Flags access_usage_procedure can now contain string "*" (without quotes) indicating all procedures.

Release version 1.0.25
Date: 2005/03/16
Bug fix: Problem with socket communication - previous release is unstable.

Release version 1.0.24
Date: 2005/03/16
Bug fix: I/O error on socket was not reported to upper application layer.
Bug fix: "Address already in use" error on Win32 was not reported (SO_REUSEADDR bug in Win32).
Improvement: Added commands "delete_irc_servers" and "delete_nicks", so BOTNET protocol increased to 6 (while keeping backward compatibility). See documentation.

Release version 1.0.23
Date: 2005/03/12
Bug fix: If remote connection was closed, some data received before connection close may be lost (e.g. IRC server has closed connection due to restart, or on BOTNET remote bot closed connection,...).
Improvement: Fixed potential incompatibilities on BOTNET between bots compiled on different compilers (GCC / MSVC). On other compilers ensure no alignment is used on structures s_bot_control and s_bot_command; and uint32 must be always 32 bit long; in file botnet.cpp.
Improvement: Added .execute command. See documentation.

Release version 1.0.22
Date: 2005/02/13
Bug fix: .stats always enclosed host name of IRC server in "[]" (typo), now only for IPv6 addresses.
Bug fix: There could be conflict in writting of files "logic.txt", "pass.txt", and "filesystem/index.txt" in upgrade state of bot, if some user were changing password, or invoked .backup, or made change to filesystem in both instances of bot (now on old one, these functions are blocked).
Bug fix: Forgotten support for Botnet over IPv6 network.
Bug fix: Resolved Botnet linking problem due to dead connections.
Improvement: Added .showbots command. See documentation.
Improvement: Added .broadcastping command. See documentation.

Release version 1.0.21
Date: 2005/02/05
Improvement: Added .chpass command.

Release version 1.0.20
Date: 2005/02/02
Bug fix: Fixed strange problem related to change of one's nick.
Improvement: Added .upgrade command. See documentation. Increased BOTNET protocol version to 5.

Release version 1.0.19
Date: 2005/01/31
Improvement: Less CPU load consumption due to BOTNET connections.
Improvement: BOTNET/OpenSSL/security: Now checks incomming BOTNET via SSL client's certificate *really* against "ssl.txt"'s definition of that client's certificate (not only against trusted CA's). If this client has other client certificate, it is rejected.
Improvement: In PHP script, added +R reop hints ("reops") to array of channel dump (IrcNet).

Release version 1.0.18
Date: 2005/01/27
Bug fix: IDENT daemon emulation could be malfunctioning after redirect message from IRC server (Shutdown too soon).
Bug fix: If compiled with IPv6 support, in case of unsucessfull connect to IPv6 IRC host, there was always confusing message "Not compiled with IPv6 support" instead of real error reason (e.g. "Host not found").
Improvement: Added support for IPv6 IDENT daemon emulation. See documentation for command "bot_ident_ipv6". Increased BOTNET protocol to version 4.
Improvement: Now IPv6 address (if not given host, but numeric address) in log message "Connecting to" and "Using IRC server host/port" is enclosed in "[]"
...maybe some forgotten minor bug fixes...

Release version 1.0.17
Date: 2005/01/26
Bug fix: Security: Possible security flaw on WinNT, related to NET_SEND command.
Bug fix: Bad handling of escaped double-quote (\") in string parser for logic.txt file.

Release version 1.0.16
Date: 2005/01/19
Bug fix: On IRCnet, unique ID message has been parsed wrong way, and 043 numeric to force nick change to unique ID while in nick collision caused deadlock in infinite loop.
Bug fix: RPL_ISUPPORT (005 numeric) was parsed omitting first parameter.

Release version 1.0.15
Date: 2005/01/17
Bug fix: In the past, on_banned event could be called for some other user as well as for user who is actually banned on channel.

Release version 1.0.14
Date: 2005/01/11
Security bug fix: Lockout after numerous bad logins could had been malfunctioning, due to invalid argument to function inet_ntop().
Security bug fix: There could be attack on bot in the BOTNET without successful authentication of remote peer by sending incorrect packet sequence (but only with hacked sources, or if attacker spoofed that it is a bot).
Improvement: Now you can use in strings escaped characters like in C (\" \n \r \xAB etc...).
Improvement: PHP script can put as output "EXECUTE" command to execute procedure in file "logic.txt".
Improvement: Increased BOTNET protocol to version 3, there can be call of procedure on remote bot on BOTNET remotely. (on DCC/telnet console there is new command ".rproc").
Improvement: For security reasons and whishes to eliminate DoS attacks and to save memory resources, in the "conf.txt" file, there can be defined maximum DCC/telnet connections from one IP ("dcc_max_sessions_per_ip=3").
Bug fix: Redundant new line character in timestamp of filesystem event.

Release version 1.0.13
Date: 2005/01/10
Bug fix: In filesystem, notify messages for files: possibility of buffer overflow.
Improvement: Now the filesystem notify messagess for file are also checked for length ("msg_force_secure_lines" in "conf.txt" times 128 characters per line).
Improvement: Now bot should accept compressed IPv6 numeric notation syntax in host mask, and/or on receive it from IRC server as host for user ("123::4:5").
Improvement: In file "conf.txt" there can be now "dcc_max_message_size" set to number of maximum bytes for message - helps to control amount of memory resources.
Improvement: Now events in the filesystem are also timestamp-ed.

Release version 1.0.12
Date: 2005/01/09
Bug fix: Redirect to other server (if enabled) was malfunctioning.
Bug fix: Identd module shutdown is now on 001 numeric reply, not on any; if there was 020 (wait request) it was sutted down which could be abortive.

Release version 1.0.11
Date: 2005/01/05
Improvement: Security: Now can be specified DCC/telnet log in lockout after numerous bad login's. It is strongly recommended that you set "lockout_duration=300" and "lockout_count=5" in your "conf.txt" file! This can make intruder guessing password harder. Lockout is IP-address based, so bot remembers bad login's and records IP-addresses of origin. See documentation for users.
Bug fix: On non-Win32 platforms, there was logical error if "sock.cpp" in function "sock_async()" making all sockets blocking instead of non-blocking(!) - true / false exchange issue... (I recommend you not to drink another coffee, and go to sleep when you are overworked, or you'll make such mistakes! ;-)
Improvement: .die/.restart are now faster... removed redundant sleep()'s.
Bug fix: Sendmail: On non-Win32 platforms sendmail was not working.
Improvement: IPv6 support works also on non-Win32 platforms.
Improvement: On non-Win32 platforms added "irc_bot.lock" lock file to detect if there is not accidentally other instance running. On Win32 it was already handled in other way (try to unlink() fopen()'ed file).
...maybe some forgotten minor bug fixes...

Release version 1.0.10
Date: 2004/12/24
Improvement: Bot now parses RPL_ISUPPORT (005 numeric) message, which explains server's/network's features, such as list of modes and how to use them.
Improvement: Added command "raw" into procedure, so you can send raw data to server. Botnet protocol version 2 introduced. So if your procedure contains command "raw", this procedure will not be replicated to other bot which doesn't support Botnet protocol 2 (version <1.0.10) for compatibility reasons.
Improvement: Added file system listing to script, RPL_ISUPPORT parsed variables, and such informations.
Obsoletes: Setting "send_+R" in file "conf.txt" is now ignored for backward compatibility - now using RPL_ISUPPORT message for such informations.

Release version 1.0.9
Date: 2004/12/19
Fixed bug: Related to processing output / execution of php script on non-win32 platforms. Now 2 separate methods, one for win32, one for unix.
Improvement: Added CLI options.

Release version 1.0.8
Date: 2004/12/15
Fixed bug: Again, php script concurrency problem. Now works fine, long term various tests succeeded, it seems to be non-bugie-woogie.
Improvement: Faster filesystem operations (no more forced to save index file every moment in filesystem module, scheduled once per minute).

Release version 1.0.7
Date: 2004/12/13
Fixed bug: There was a poossiblity of crash due to bug in php script handling.
Fixed bug: Cycle channel failed if there were more than one channel to cycle.
Fixed bug: Checking of concurrency of php scripts was malfunctioning. Now really ony one php script (from same template) is executed.
Fixed bug: "link" command sometimes failed. Also botnet linking problem fixed.
Improvement: Botnet replication optimised - there is scheduling of backup + rehash now. It is done after 2 minutes from the last backup + rehash request from remote bot after object pulling, but new version of object will take effect even if backup + rehash is not executed yet.
Improvement: Bot should be compilable also under unices (tested uder i686 GCC 3.3.2 20031022 (Red Hat Linux 3.3.2-1)).
Improvement: Service (under win32) is not needed now, bot after .restart command tries to spawn itself, if succeeded returns BOT_DIE exit code, if not returns BOT_RESTART and leaves respawning on service.

Release version 1.0.6
Date: 2004/12/10
Fixed bug: Malfunctioning setting of user flags "access_to_replication" and "access_grant_replication" in DCC/telnet administration.
Fixed bug: .whois <user_name_mask> on DCC/telnet connection now gives much more (at least full basic) informations from user's definitions.
Fixed semi-bug: No more repeating groups in ".edituser"/".groups"/".add" in DCC/telnet administration. Each group is listed only once now.
Fixed semi-bug: In DCC/telnet administration ".edituser": redundant empty line.
Improvement: DIE's and RESTART's of the bot causes broadcasting kill message to all logged-in users on DCC/telnet (not BOTNET) connections ("DIE/RESTART by <user_name>").
Improvement: Rehashing of the bot (whichever is caused by user, or another bot in BOTNET) puts rehash message to all logged-in users on DCC/telnet connections.
Improvement: If .die/.restart commands has invoked user (not OS on Ctrl+C, service nor system shutdown), the same user gets full kill log with statistics to their console (DCC/telnet). That log is one that is written also to "logs/bot.log" as in previous versions.
Improvement: Added ping message on DCC/telnet (not BOTNET) connection to console to help detect if user is alive, or the connection was broken without notification from IP stack. This could prevent (in theory) hung "zombie" users on partyline. Ping message interval can be set by "dcc_chat_ping_interval=<seconds>" line in "conf.txt" file; zero for dissable.
Documentation: There was possibility of "motd.txt" file (for DCC/telnet connections) since first release; forgotten to notice it in documentation: now updated.
...maybe some forgotten minor bug fixes...

Release version 1.0.5
Date: 2004/12/09
Fixed bug: When on one channel bot got op, it thought that it is opped on every channel.
Fixed bug: Event on_other_mode was not working.

Release version 1.0.4
Date: 2004/12/08
Fixed bug: Undefined language string in file "lang01.txt" causing an empty string in DCC/telnet console.
Improvment: At BOTNET telnet/SSL connection sends at first PING, and after PONG is received sends password (this is check for SSL handshake validity).

Release version 1.0.3:
Date: 2004/11/21
Fixed bug: DCC chat login problem.
Improvement: Now DCC chat / send works over IPv6 too.

Release version 1.0.2:
Date: 2004/11/19
Fixed bug: in smart_mode enabled, there was problem when there was longer time difference between IRC server's op/voice user after net split and time when bot got the WHOIS on "new" users on channel.

Release version 1.0.1:
Date: 2004/11/17
Fixed bug related to unsuccessful reverse DNS lookup (entry wasn't inserted to resolver cache correctly).

Release version 1.0.0:
Date: 2004/11/16
Initial revision by VooDooMan.

Note: If you want to join a mailing-list to get along with new releases, please send me a mail to ghostvoodooman [NOSPAM] (at) [NOSPAM] users (dot) [NOSPAM!] sourceforge (dot) net with subject "VooDoo cIRCle" (to know that your mail is not a spam).


Basic configuration knowledge

Note, that configuration of this IRC bot is not as easy as configuration of for example IRC bot Eggdrop.

Main logic of the bot is stored in file "logic.txt". This file contains:

  1. definitions of users, which contains:
    1. name of user
    2. their host masks
    3. full name masks
    4. replication parameters used for replication of user between other bots (botnet)
    5. group membership of user
    6. access rights
    7. channel definitions for this user
  2. definitions of procedures, which can be executed in special cases
  3. definitions of channels rules
  4. definitions of private queries for the bot
  5. additionally, list of all groups (which is generated automatically, so you don't need to add them)

Access privileges are in two categories:
  1. "access_to...", this means that user has access to that feature, and cannot grant this access to other user.
  2. "access_grant...", this means that user can grant access to other user to this feature. Example: if there is a group called "my_friends_group", and user has right "access_grant_group" to this group, then user can add or exclude other users to / from this group.
  3. There is also special category applicable only to procedures, "access_usage_procedure", it means that user can assign procedures in this group to events.

Structure of logic.txt file:
 
user YOUR_BOT_NAME
{
   last_changed 0
   host_bot
   host "mybot!*mybot@host.org"
   member_of_group "bots"
}
user USER_NAME
{
   last_changed 0
   host "nick!ident@host.com"
   host "*!ident@another.host.com"
   full_name "I am an IRC user. My real name is unknown..."
   access_to_partyline 1
   replication another_bot push
   access_grant_partyline 0
   access_to_backup 0
   access_to_rehash 0
   access_grant_backup 0
   access_grant_rehash 0
   access_to_+user 0
   access_grant_+user 0
   access_to_+proc 0
   access_grant_+proc 0
   access_grant_replication 0
   meta "key" "value"
   meta "description" "this is an user!"
   channel "#your_channel"
   {
      member_of_group "your_channel_user"
      on_deop revenge2($channel,$source,$target,$source_nick,$target_nick)
      on_ban revenge2($channel,$source,$target,$source_nick,$target_nick)
      on_kick revenge2($channel,$source,$target,$source_nick,$target_nick)
      on_banned banned($channel,$user,$ban_mask)
      on_privmsg 
      msg_flood 3 10
      notice_flood 3 30
      repeat_flood 2 10
      nick_flood 3 30
      join_flood 3 60
      mode_flood 5 10
      allow_dynamic "super_users" "+@" "@"
      allow_dynamic "other_users" "+@" "+"
      dynamic1 
      dynamic2 
      can_send_unknown_users 1
   }
}
Let's go to explain what it means.

String "YOUR_BOT_NAME" should be name of your bot. Note, that this need not to be the same as Nick name of your bot.

Line beginning with "host" contains nick, ident and host name in format <nick>!<ident>@<host>. You can user wildcards, such as "?" for one character, and "*" for zero or any number of characters. You can specify more than one host masks, but at least one. Note that these host masks MUST be in double-quotes ("nick!ident@host").

Line beginning with "full_name" contains full name of user (as shown in WHOIS). You can also use wild cards as in host masks. Note that VooDoo cIRCle identifies user by host mask and full names too! Tip: if you want to disable checking to full name, just simply use this: full_name "*"

Line "last_changed 0" contains time stamp for case of replication this user. Time stamp is number of seconds since 1.1.1970 (it is UNIX standard time stamp). You can set this to zero, if you edit logic.txt file for the first time. This time stamp is used when your bot is replicating this user with another bot via "botnet". Botnet is two or more bots connected together by IP network.

Line "host_bot" means, that this user is the bot itself. Note that this line must NOT to be set to other users! When you have "host_bot" line, you need not have host masks defined for this user (for bot itself), but it is strongly recommended to add host mask for your bot, for case of broken line, when new instance of bot's connection to IRC server is made, and the other one instance falls for "ping timeout", to know that it was bot itself. (There is known problem with flood detection routine, when new instance think of old bot as user "unknown" and ban-kick itself for flood. If there is a host mask present, bot knowns, that it is it itself and applies the flood rules for itself - if there are some defined).


Let's go to next user, "USER_NAME" - this should contain user-friendly name of some user.

Line beginning with "replication" word means, that this user will be replicated to bot named "another_bot". You MUST in this case create user "another_bot". Here is example of record for "another_bot" in logic.txt:

user "another_bot"
{
   host "a_bot!ident@host.org"
   full_name "This is another bot"
   replication_partner
   access_to_+user 1
}


There must be line "replication_partner" in order to link with this bot. You should also set "access_XXX" privileges, that this another bot will have access in your main bot.

Replication types can be:

1) "push" - this object (user, procedure or channel definition) will be pushed to another bot, if that bot has an older version for that object
2) "pull" - this object will be pulled from another bot, if this bot has an older version than other bot
3) "pushpull" - this object will be pushed or pulled to / from another bot, the replication will be done, if one of them has older version of object

You could ask how the remote bot knows if it has older or newer version of some object. There is "last_changed" property, which is set to current time when the object is modified. Bots also sends to each other their current system time, and computes time difference. If the object is older that 60 seconds, it will be replicated by specified replication rules.


Line "access_to_partyline 1" means, that this user has access to party line. Party line is telnet or DCC connection to bot, often used for its administration, or for chatting. If there is "0" (zero), user doesn't have access.

Line "access_grant_partyline 0" means that user cannot grant access to party line to other user. If there is "1" (one), user can.

Basic knowledge:
Flags "access_to_XXX" means, if user has access to feature "XXX",
Flags "access_grant_XXX" means, if user can grant access to feature "XXX" to other user (if can set "access_to_XXX" flag for other user.
Flags "access_to_XXX" and "access_grant_XXX" is followed by space and number of "0" (zero) or "1". "0" means no access, "1" means access is granted.

Other access flags has little bit similar meaning:

"access_to_backup": whether user can use ".backup" command at party line.
"access_to_rehash": whether user can use ".rehash" command at party line.
"access_grant_backup": whether user can grant access to usage of ".backup" command at party line.
"access_grant_rehash": whether user can grant access to usage of ".rehash" command at party line.
"access_to_+user": whether user can grant access to usage of ".+user" command at party line.
"access_grant_+user": whether user can grant access to usage of ".+user" command at party line.
"access_to_+proc": whether user can grant access to usage of ".+proc" command at party line.
"access_grant_+proc": whether user can grant access to usage of ".+proc" command at party line.
"access_grant_replication": whether user can modify replication parameters to other bots on the botnet.
"access_to_restart": whether user can use ".restart" command on DCC / telnet connection to restart the bot.
"access_grant_restart": whether user can grant to other one access to ".restart"
"access_to_die": whether user can use ".die" command on DCC / telnet connection to shutdown the bot.
"access_grant_die": whether user can grant to other one access to ".die"
"access_to_filesystem": whether user has access to filesystem, thus can upload, download files stored in local bot's filesystem directory.
"access_grant_filesystem" whether user can grant to other one access to filesystem
"access_to_private": whether user can modify "private" section of file "logic.txt"
"access_grant_private": whether user can grant "access_to_private" right to other users.
"access_to_can_send_all_users": whether user can send message / file to all users (filesystem).
"access_grant_can_send_all_users": whether user can grant privilege to other user to send message / file to all users.
"access_to_can_send_unknown_users": whether user can send message / file to unknown users (according to flag "host_unknown")
"access_grant_can_send_unknown_users": whether user can grant privilege to other user to send message / file to unknown users (according to flag "host_unknown")
"access_to_upgrade": whether user can use command ".upgrade". NOTE: You need to have at least version 1.0.20 of remote bot on the BOTNET in order to replicate this attribute to it.
"access_grant_upgrade": whether user can grant privilege to use command ".upgrade" to other user. NOTE: You need to have at least version 1.0.20 of remote bot on the BOTNET in order to replicate this attribute to it.
"access_to_apply": whether user can use ".apply" command. "access_grant_apply": whether user can grant privilege to use ".apply" command to other user.

Let's go to channel definition for our "USER_NAME" user.

There are also meta-data used for PHP scripting. It is useful for example for declension in PHP script in some human languages the bot to speak in. See PHP scripting section.

After word "channel" is name of the channel, in which user has some defined rules. Note that name of channel MUST be in double-quotes.

Line beginning with "member_of_group" contains group membership of user on this channel, in double-quotes.

Lines beginning with "on_" are events. These events contain name and declaration of procedure, which is executed on specified event. Syntax is: procedure_name($parameter1,$parameter2) and so on. Note that there must NOT be any space character!

List of events that can be assigned to user on channel:

  1. on_deop - this procedure will be called when specified user on specified channel is deopped (-o).
    Syntax of called procedure: procedure_name($channel,$source,$target,$source_nick,$target_nick).
    Parameters:
    1. $channel - contains channel name
    2. $source - contains name of user who is deopping (name of user is as specified in logic.txt as "user-friendly name")
    3. $target - contains name of user who is deopped (name of user is as specified in logic.txt as "user-friendly name")
    4. $source_nick - contains current nick of user who is deopping
    5. $target_nick - contains current nick of user who is deopped
  2. on_ban - this procedure will be called when specified user has just been banned
    Syntax of called procedure: procedure_name($channel,$source,$target,$source_nick,$target_nick,$ban_mask)
    Parameters and syntax are similar as on_deop, except of "$ban_mask" contains the mask that is set as ban.
  3. on_kick - this procedure will be called when specified user has been kicked
    Parameters and syntax are same as on_deop.
  4. on_banned - this procedure is called when your bot has just joined channel, and finds out that specified user is banned (matches the ban mask) and is not listed in exception list.
    Syntax:
    Procedure_name($channel,$user,$ban_mask)
    Parameters:
    1. $channel - contains name of channel
    2. $user - user name as specified in logic.txt
    3. $ban_mask - mask of ban that is set
  5. on_privmsg - this procedure is called when this user posts a message to the channel
    Syntax:
    Procedure_name($channel,$source,$source_nick,$msg)
    Parameters:
    1. $channel - contains channel name
    2. $source - user name as specified in "logic.txt" file
    3. $source_nick - nick name of user
    4. $msg - the message
  6. on_notice - this procedure is called when this user posts a notice to the channel
    Syntax and parameters are same as on_privmsg.
  7. on_unban - this procedure is called when this user is unbanned (-b nick!ident@host)
    Syntax:
    procedure_name($channel,$source,$target,$source_nick,$target_nick,$ban_mask)
    Parameters:
    1. $channel - name of channel
    2. $source - name of user as specified in "logic.txt" file who has unbanned someone
    3. $target - name of user who was unbanned
    4. $source_nick - nick name of user who has set -b flag
    5. $taget_nick - nick name of user who has been unbanned - empty string if user is not on channel
    6. $ban_mask - mask that has been passed as parameter to -b (-b mask)
  8. on_op - this procedure will be called if some user has been opped (+o)
    Syntax:
    procedure_name($channel,$source,$target,$source_nick,$target_nick)
    Parameters:
    (same as on_deop)
  9. on_voice - this procedure will be called if this user has been voiced (+v)
    Syntax and parameters are same as on_deop / on_op
  10. on_devoice - this procedure will be called when this user has been devoiced (-v)
    Syntax and parameters are same as on_voice
  11. on_creator - this procedure will be called if some user has been set as creator of channel (some IRC networks use it) - (+O)
    Syntax and parameters are same as on_op
  12. on_decreator - this procedure will be called if some user has been reset as creator of channel (some IRC networks use it) - (-O)
    Syntax and parameters are same as on_op
  13. on_join - this procedure will be called when this user joins the channel
    Syntax:
    join($channel,$user,$nick,$dynamic1,$dynamic2,$passive)
    Parameters
    1. $channel - name of channel
    2. $user - user name as in "logic.txt"
    3. $nick - nick name of user
    4. $dynamic1 - dynamic "plus" modes that user has been specified by others (if someone gave them +v or +o, this parameter will contains string "@" for +o, "+" for +v, or both, or an empty string)
    5. $dynamic2 - dynamic "minus" modes that user has been specified by others (if someone gave them -v or -o, this parameter will contain string "@" for -o, "+" for -v, or both, or an empty string)
    6. $passive - contains mode of user (e.g. "@" or "+",...) if this user is already on channel, after your bot has just joined the channel, or "0" (zero) if have user just joined channel. Also contains "1" (one) if it is a "passive join", which means that user is already on channel when bot has just joined (it is good case for validate of user's modes). You should use "if_in", and "!if_in" commands for comparsion.
  14. on_flood - this procedure will be called when user excess its flood limit
    Syntax:
    flood($channel,$source,$source_nick,$type,$num,$sec,$sec_of)
    Parameters:
    1. $channel - name of channel
    2. $source - name of user in "logic.txt"
    3. $source_nick - nick name of user
    4. $type - string determining type of flood, can be one of these:
      1. "message" - user posts too many messages to channel
      2. "notice" - user posts too many notices to channel
      3. "nick" - user changes their nick too many times in a shot time
      4. "mode" - user changes mode of channel too many times in a short time
      5. "join" - user joined and parted/quit channel too many times in a short time
      6. "repeat" - user posts to the channel too many same messages / notices in a short time
      7. "ctcp" - user sends CTCP (ping, version,...) requests to all users in the channel (to whole channel) too many times in a short time ("ACTION" is exception here, it is considered as "message", and against "repeat" as well
      Note: "too many xxx in a short time" means that exceeded limit defined for the user as "xxx_flood" limit property (for example "ctcp_flood")
    5. $num - number of occurences (first parameter of flood definition)
    6. $sec - number of seconds that flood took
    7. $sec_of - number of total seconds defined (second parameter of flood definition)

  15. on_except - this procedure is called when someone sets +e (exception to ban) to channel
    Syntax:
    except($channel,$source,$target,$source_nick,$target_nick,$prefix,$mask)
    Parameters are similar, but $prefix contians one-character string "+".
  16. on_unexcept - this procedure is called when someone sets -e (exception to ban) to channel
    Syntax:
    unexcept($channel,$source,$target,$source_nick,$target_nick,$prefix,$mask)
    Parameters are similar, but $prefix contians one-character string "-".
  17. on_invite - this procedure is called when someone sets +I (invite and also exception to ban) to channel
    Syntax:
    invite($channel,$source,$target,$source_nick,$target_nick,$prefix,$mask)
    Parameters are similar, but $prefix contians one-character string "+".
  18. on_uninvite - this procedure is called when someone sets -I (invite and also exception to ban) to channel
    Syntax:
    uninvite($channel,$source,$target,$source_nick,$target_nick,$prefix,$mask)
    Parameters are similar, but $prefix contians one-character string "-".
  19. on_not_invited - this procedure is called when bot joins a channel and has found that someone is not on +I invite list
    Syntax:
    not_invited($channel,$user,$mask)
  20. on_not_in_reop - this procedure is called when bot joins a channel and found that someone is not on +R reop hints (IRCnet)
    Syntax:
    not_in_reop($channel,$user,$mask)
  21. on_reop - this procedure is called when someone set / removes R mode (reop hints - IRCnet) for some user
    Syntax:
    reop($channel,$source_user,$target,$source_nick,$target_nick,$prefix,$mask)
    Where $prefix contains "+" for +R mode, or "-" for -R mode.
  22. can_send_unknown_users - this is set to one (1) if user can send message / file to unknown user if it appears on the channel (filesystem). Otherwise, it is zero (0). Note, that if there is one (1), unknown when unknown user wants to receive message / file, it must have privilege "access_to_filesystem" (consider user flagged by "host_unknown"). If message / file has attribute READ for unknown users, note, that every user can receive / download it.


List of flood limits assigned to specific user on channel:
After specified flood keyword, there is number of occurrences and number of seconds, delimited by space. For example:
msg_flood 5 10
means that when user posts 5 messages in 10 seconds, it will be considered as flood, and specified procedure is called.

  1. msg_flood - flood limit for PRIVMSG (common message).
  2. notice_flood - flood limit for NOTICE.
  3. repeat_flood - flood limit for repeating. If there is "repeat_flood 3 10", repeat flood procedure will be called when user posts 3 very same messages in 10 seconds.
  4. nick_flood - when user changes their nick many times.
  5. join_flood - when user joins and parts channel many times.
  6. mode_flood - when user changes mode of channel or user many times.
  7. ctcp_flood - when user sends to channel (=to all users) CTCP request (for example /ctcp #channel ping), thus any quoted message, except of ACTION - it is considered against repeat flood and message flood definitions.

Line beginning with "allow_dynamic" contains definitions about dynamic modes. Note that all parameters MUST be in double-quotes.
Dynamic modes are useful for "learning" your bot. For example, when someone in specified group sets +o ("@" mode) to this user, bot should automatically set to this user +o when they join. It is useful when you have on your channel another bot, from another vendor, and it is configured to give someone +o status, and that bot is in that dynamic group, your bot writes it down, and will be automatically set +o for that user. This is called "dynamic modes". Note, that this "learning" should NOT be applied on "unknown user", because that would mean that anyone who is considered as unknown will have +o status. This learning is useful only for known users in "logic.txt".
First parameter is name of group of user, from which are dynamic modes accepted.
Second parameter is which modes are accepted with "+" prefix. There is "+" for +v mode; "@" for +o mode, or "+@" for +v and +o mode;
Third parameter is similar to second one, but there are modes with "-" prefix ("+" for -v mode, "@" for -o mode and "+@" for -v and -o mode).

Finally, line "dynamic1" stores minus dynamic modes, and "dynamic2" plus dynamic modes.

Note that bot will NOT automatically give dynamic modes (+o, -o, +v, -v), unless you assign on_join event procedure, which checks for dynamic modes and does it itself, after considering suitable reason.


Channel definitions

Here is example part of logic.txt:

channel "#your_channel"
{
   last_changed 0
   member_of_group "my_channel"
   replication another_bot push
   on_mode mode($channel,$source,$source_nick,$plus_modes,$minus_modes)
   on_key key($channel,$source,$source_nick,$prefix,$key)
   on_limit limit($channel,$source,$source_nick,$prefix,$limit)
   on_ircop ircop($channel,$source,$source_nick,$on)
   on_privmsg proc_chan_msg($channel,$source,$source_nick,$msg)
   on_part part($channel,$source,$source_nick,$msg,$type)
   on_dynamic_ban dynamic_ban($channel,$source,$source_nick,$prefix,$ban_mask)
   on_ctcp ctcp($source,$source_nick,$channel,$command,$parameters)
   dynamic_ban "some!ident@host.org" "do not do a lame things!"
   partyline_dynbans_editors "super_users"
   allow_dynamic "super_users" "sp" "sp"
   dynamic1 
   dynamic2 
}
After word "channel", there should be name of your channel, in double-quotes.

"last_changed" property is relevant for replication.
"member_of_group" - contains group membership of channel.
"replication" - defines replication rules same as user object.
"on_mode" procedure will be called when someone changes mode of channel (for example +s, +nt, ...)

Events on channel definition:

  1. on_mode
    Syntax:
    proc_name($channel,$source,$source_nick,$plus_modes,$minus_modes)
    Paramters:
    1. $channel - name of channel
    2. $source - name of user who changed the mode as defined in logic.txt
    3. $source_nick - current nick name of user who changed mnode
    4. $plus_modes - contains mode character; for +n, it is "n", for +t it is "t", or can be an empty string
    5. $minus_modes - contains mode character; for -n, it is "n", for -t it is "t", or can be an empty string
  2. "on_key" procedure will be called if someone on channel sets or clears key to channel (+k)
    Syntax:
    proc_key($channel,$source,$source_nick,$prefix,$key)
    Parameters - same as on_mode, but:
    1. $prefix - contains "+" for +k, or "-" for -k
    2. $key - contains key as parameter to +/-k mode

  3. "on_limit" procedure will be called if someone on channel sets users limit (+l)
    Syntax:
    proc_limit($channel,$source,$source_nick,$prefix,$limit)
    Parameters - same as on_key, but:
    1. $limit - contains limit that has been set

    "allow_dynamic" contains rule for dynamic modes. See "allow_dynamic" for users for details. The parameters can be such as "sp" for +/-sp modes, or "i" for +i, ...
     
  4. "on_ircop" procedure will be called if on the channel is irc operator present after he joined, parted channel, or he is present on channel at bot's join
    Syntax:
    proc_ircop($channel,$source,$source_nick,$on)
    1. $channel - name of channel
    2. $source - name of user from logic.txt (if present)
    3. $source_nick - nick name of the irc op
    4. $on - contains string "1" (one) if irc op is present, or "0" (zero) if irc op has left the channel
  5. "on_privmsg" procedure will be called when anyone posts a PRIVMSG to channel

    Syntax:
    proc_chan_msg($channel,$source,$source_nick,$msg)

    1. $channel - name of channel
    2. $source - name of user from logic.txt (if present)
    3. $source_nick - nick name
    4. $msg - message content
  6. "on_notice" procedure will be called when anyone posts a NOTICE to channel
    Syntax and parameters are same as on_privmsg.
  7. "on_part" procedure will be called when someone parts channel or quits the IRC

    Syntax:
    part($channel,$source,$source_nick,$msg,$type)

    1. $channel - name of channel
    2. $source - name of user from logic.txt (if present)
    3. $source_nick - nick name
    4. $msg - reason of part / quit, or kick message when it was a kick
    5. $type - type of exit, one of following: "PART", "QUIT", "KICK"

  8. "on_dynamic_ban" procedure will be called when someone sets or removes ban (+/-b mask)

    Syntax:
    dynamic_ban($channel,$source,$source_nick,$prefix,$ban_mask)

    1. $channel - name of channel
    2. $source - name of user from logic.txt who set/removed the ban
    3. $source_nick - and his nick
    4. $prefix - contains "+" for +b and "-" for -b was set
    5. $ban_mask - mask of the set/removed ban

    Notes:
    Dynamic ban is ban, that doesn't need to be set on channel (remember that most IRC networks limits number of bans on channel to 30), so there is a list of dynamic bans, and when someone joins a channel and bot detects that there is dynamic ban entry in its configuration, it can set ban (for couple of minutes) and kick this user. In this procedure, it is useful to check if $source user is member of group who can set/remove dynamic ban. The bot doesn't remember dynamic ban, so you need to use "dynamic_ban" command to set dynamic ban. Also, bot will not automatically set channel ban and kick user that matches dynamic ban mask, you need to do it explicitly in logic.txt file in some procedure.

  9. "on_ctcp" procedure will be called if someone posts a CTCP request to channel or private query of the bot.

    Syntax:
    on_ctcp ctcp($source,$source_nick,$channel,$command,$parameters)

    Parameters

    1. $source - name of user as defined in "logic.txt"
    2. $source_nick - nick of user
    3. $channel - name of channel
    4. $command - command part of the quoted message (such as "VERSION", "DCC", "PING", "ACTION")
    5. $parameters - text after $command

    See also private definitions of "on_ctcp".

  10. "on_server_msg" will be called when message from IRC server is posted to channel.

    Syntax:
    on_server_msg server_msg($channel,$source,$type,$msg,$server,$port)

    Parameters

    1. $channel - name of channel
    2. $source - name of server which post message
    3. $type - type of message: string "PRIVMSG" or "NOTICE"
    4. $server - host of server which we are now on
    5. $port - port of server which we are now on

    See also private definitions of "on_server_msg".

  11. "allow_dynamic" contains rule for dynamic modes. See "allow_dynamic" for users for details. The parameters can be such as "sp" for +/-sp modes, or "i" for +i, ...

     

  12. "dynamic_ban" (there can be multiple lines) has first argument mask of dynamic ban, and second reason which can be used for kick reason.

  13. "partyline_dynbans_editors" (the can be multiple lines) defines which group of users that they are member of can set, or unset dynamic ban entries via DCC CHAT or telnet connection (note that the also need to have access_to_partyline privilege).

 

Private definitions - handles private queries

private
{
   last_changed 0
   on_privmsg private_msg($source,$source_nick,$msg)
   on_notice private_notice($source,$source_nick,$msg)
   on_ctcp ctcp($source,$source_nick,$channel,$command,$parameters)
   on_filesys_got_new fs_got_new($user_name,$nick,$ident,$host,$internal_name)
   on_fnc fnc($old_nick,$new_nick)
   on_broadcast bdc($source,$source_nick,$source_ident,$source_host,$bcast_mask,$type,$msg,$server,$port)
   on_server_msg smsg($channel,$source,$type,$msg,$server,$port)
   on_internal_event internal_event($type,$timestamp,$time_string,$flags1,$flags2,$flags3,$flags4,$severity_numeric,$severity_string,$msg1,$msg2,$server,$port)
}
  1. "on_privmsg" procedure will be called if someone posts a message to query of the bot

    Syntax:
    private_msg($source,$source_nick,$msg)

    Parameters

    1. $source - name of user as defined in "logic.txt"
    2. $source_nick - nick of user
    3. $msg - message

  2. "on_notice" procedure will be called if someone posts a notice to query of the bot

    Syntax and parameters are same as "on_privmsg".

  3. "on_ctcp" procedure will be called if someone posts a CTCP request to channel or private query of the bot.

    Syntax:
    on_ctcp ctcp($source,$source_nick,$channel,$command,$parameters)

    Parameters

    1. $source - name of user as defined in "logic.txt"
    2. $source_nick - nick of user
    3. $channel - name of channel or an empty string if it is a private query
    4. $command - command part of the quoted message (such as "VERSION", "DCC", "PING", "ACTION")
    5. $parameters - text after $command

    Note: This event will be triggered also when user posts a CTCP request to channel, together with channel's definition "on_ctcp" event. Your procedure will receive also "ACTION"'s.
    "DCC", "PING" and "TIME" should be ignored, because they are handled by the bot automatically. When someone posts message "\001ACTION is doing a bugie-woogie style of crashing\001", $command will contain "ACTION" and $parameters will contain string "is doing a bugie-woogie style of crashing".

  4. "on_filesys_got_new" procedure will be called if someone posts adds message or file to filesystem.

    Syntax:
    on_filesys_got_new filesys_got_new($source,$nick,$ident,$host,$internal_name)

    Parameters

    1. $source - name of user as defined in "logic.txt"
    2. $nick - nick of user (empty if user has added a message via DCC/telnet connection)
    3. $ident - ident of user (empty if user has added a message via DCC/telnet connection)
    4. $host - host of user (emptyif user has added a message via DCC/telnet connection, or "127.0.0.1"/"::1" if it was user from localhost)
    5. $ineternal_name - internal name of filesystem's object

    Note: This event will not be replicated to/from bot version < 1.0.28, that is BOTNET protocol version 7 due to compatibility reasons.

    Your procedure should look like this:

    See PHP scripting section.

  5. "on_fnc" procedure will be called if bot has been forced to change its nick (applicable only on IRCnet).

    Syntax:
    on_fnc fnc($old_nick,$new_nick)

    Parameters

    1. $old_nick - bot's old nick
    2. $new_nick - bot's new nick

    Note: This event will not be replicated to/from bot version < 1.0.28, that is BOTNET protocol version 7 due to compatibility reasons.

    Your procedure should look like this:

    This attempts to change nick after 30 minutes and 2 seconds - on IRCnet is currently the old nick temporarily unavailable for 30 minutes after nick collision.

  6. "on_broadcast" will be called when message from IRC operator is sent to all users which match specific mask.

    Syntax:
    on_broadcast bcast($source,$source_nick,$source_ident,$source_host,$bcast_mask,$type,$msg,$server,$port)

    Parameters

    1. $source - name of originating user as in "logic.txt"
    2. $source_nick - nick name of originating user who sent message (probably IRC operator)
    3. $source_ident - ident of originator
    4. $source_host - host of originator
    5. $bcast_mask - mask used to broadcast (something like "$$irc.somedomain.org")
    6. $type - string of type of message: "PRIVMSG" or "NOTICE"
    7. $msg - the whole message
    8. $server - host of server which we are now on
    9. $port - port of server which we are now on

    Note that if broadcast message is CTCP PRIVMSG, the proper event will be also called to process CTCP message.

    Note: This event will not be replicated to/from bot version < 1.0.33, that is BOTNET protocol version 8 due to compatibility reasons.

  7. "on_server_msg" will be called when message from IRC server is posted to bot as private message.

    Syntax:
    on_server_msg server_msg($source,$type,$msg,$server,$port)

    Parameters

    1. $source - name of server which post message
    2. $type - type of message: string "PRIVMSG" or "NOTICE"
    3. $server - host of server which we are now on
    4. $port - port of server which we are now on

    See also channel definitions of "on_server_msg".

    Note: This event will not be replicated to/from bot version < 1.0.33, that is BOTNET protocol version 8 due to compatibility reasons.

  8. "on_internal_event" will be called when something happen in the internals of the bot.

    Syntax:
    on_internal_event internal_event($type,$timestamp,$time_string,$flags1,$flags2,$flags3,$flags4,$severity_numeric,$severity_string,$msg1,$msg2,$server,$port)

    Parameters

    1. $type - type of event (e.g. "@rehash@", "@backup@")
    2. $timestamp - Unix timestamp (number of seconds until UNIX epoch: 1970-01-01 as number in string)
    3. $time_string - e.g. "Wed Jul 06 14:40:45 2005"
    4. $flags1 - flags #1 - type-specific as what $type contains
    5. $flags2 - flags #2 - type-specific as what $type contains
    6. $flags3 - flags #3 - type-specific as what $type contains
    7. $flags4 - flags #4 - type-specific as what $type contains
    8. $severity_numeric - severity number as string; $severity_string severity as string:
      1. $severity_numeric=="0"; $severity_string=="N/A"; This means that no severity is given. Often used for events that has no severity.
      2. $severity_numeric=="1"; $severity_string=="informational"; This event is informational.
      3. $severity_numeric=="3"; $severity_string=="warning"; This event is warning.
      4. $severity_numeric=="5"; $severity_string=="error"; This event is error.
      5. $severity_numeric=="7"; $severity_string=="critical error"; This event is critical error.
      6. $severity_numeric=="9"; $severity_string=="fatal error"; This event is fatal error.
    9. $msg1 - type-specific message #1 as what $type contains
    10. $msg2 - type-specific message #2 as what $type contains
    11. $server - host/IP of server we are connected to
    12. $port - Port of server we are connected to as string
    Note: This event will not be replicated to/from bot version < 1.0.52, that is BOTNET protocol version 11 due to compatibility reasons.

    Types of events follows:

      1. $type=="@rehash@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - string, who caused rehashing
      5. $flags2 - not used yet, should contain an empty string
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - "Trying to rehash..."
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above

      Note: Before rehash

      1. $type=="@rehash_done@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - string, who caused rehashing
      5. $flags2 - string "OK" for success; "ERROR" for error
      6. $flags3 - an empty string for success; if not, string number of error line in "logic.txt"
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1" for successful rehash; "5" for error, so roll-back to old configuration is going to be performed
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - Message "Rehashing succeeded."; in case of not success contains error string describing which line of configuration script ("logic.txt") is errorneous.
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above

      Note: After rehash

      1. $type=="@rehash_rollback_ok@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - not used yet, should contain an empty string
      5. $flags2 - not used yet, should contain an empty string
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - Message: log from roll-back engine (more informations about which file was used, from which date, and so on.
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above

      Note: After successful roll-back

      1. $type=="@rehash_rollback_error@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - not used yet, should contain an empty string
      5. $flags2 - not used yet, should contain an empty string
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "5"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - Message: "Don't have any backup files for roll-back."
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above

      Note: After unsuccessful roll-back

      1. $type=="@backup@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - string, who caused backup
      5. $flags2 - not used yet, should contain an empty string
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1" for success of backup, or "3" for ignored backup (e.g. bot is in UPGRADE state)
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - contains an empty string if $severity_numeric=="1", error message if $severity_numeric=="3"
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above
      1. $type=="@apply@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - string, who caused ".apply" command
      5. $flags2 - not used yet, should contain an empty string
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - Message of success
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above
      1. $type=="@restart@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - string, who caused ".restart" command
      5. $flags2 - not used yet, should contain an empty string
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - not used yet, should contain an empty string
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above
      1. $type=="@restart_error@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - string, who caused ".restart" command
      5. $flags2 - not used yet, should contain an empty string
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "9"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - Message why restart was not successful (e.g. "RESTART: Error spawning new instance. Something should run it.")
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above

      Note: This could occur if bot wasn't spawned by service, and ".restart" command failed to re-spawn the bot.

      1. $type=="@die@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - string, who caused ".die" command
      5. $flags2 - not used yet, should contain an empty string
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - not used yet, should contain an empty string
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above
      1. $type=="@upgrade@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - string, who caused ".die" command
      5. $flags2 - file name of new binary
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1" for ".upgrade" command; contains "5" for error while performing UPGRADE
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - if $severity_numeric=="1": an empty string (before new instance has been spawned), or contains success message (after new instance has been spawned); if $severity_numeric=="5": error message
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above
      1. $type=="@ircop@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - Nick name of IRC operator
      5. $flags2 - Full host mask of IRC operator (e.g. "nick!user@host")
      6. $flags3 - Channel name
      7. $flags4 - String "ON" if IRC operator joined channel, or is found out that they is on the channel; "OFF" if left channel
      8. $severity_numeric - contains "3"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - not used yet, should contain an empty string
      11. $msg1 - Full name / real name of IRC operator from WHOIS
      12. $server - see above
      13. $port - see above

      Note: It will be fired if an IRC operator is found on some channel.

      1. $type=="@botnet_link@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - Remote bot name (as defined in "logic.txt")
      5. $flags2 - "LINKED", "DELINKED", "BAD_PASSWORD_HERE" for bad password on our side, "BAD_PASSWORD_THERE" for bad password on the other side
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1" if remote bot has been linked; contains "3" if remote bot has been de-linked, or other error
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - There is explanation message for human
      11. $msg1 - not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above

      Note: There you can get informations about linking/delinking remote bots.

      1. $type=="@botnet_replication@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - Remote bot name (as defined in "logic.txt")
      5. $flags2 - "channel" for channel, "user" for user
      6. $flags3 - name of object
      7. $flags4 - Error reason (or "OK" for okay)
      8. $severity_numeric - contains "1" if replication was performed okay; contains "5" if there is replication error
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - There is explanation message for human
      11. $msg2 - contains "PUSH", "PULL", or "PULL_REQUEST" describing type of replication, or "REMOTE" for remote bot rejected replication, or "LOCAL" if local bot rejected replication
      12. $server - see above
      13. $port - see above

      Note: It will be fired if replication event occur on BOTNET.

      1. $type=="@log@"
      2. $timestamp==(see above)
      3. $time_string==(see above)
      4. $flags1 - Type of log message: "debug", "irc", "socket", "bot", "identd", "channel", "botnet_debug", "botnet", "ssl", "broadcast" (broadcast messages from IRC operators)
      5. $flags2 - If $flags1=="irc": "IN" for incomming message, "OUT" for outgoing message; if $flags1=="socket": OS error number as text; if $flags1=="channel": name of channel, or "status" for status messages; if $flags1=="botnet_debug": name of remote bot (from "logic.txt"); if $flags1=="botnet": name of remote bot (from "logic.txt"); if $flags1=="broadcast": Nick name of IRC operator - originator of PRIVMSG/NOTICE
      6. $flags3 - not used yet, should contain an empty string
      7. $flags4 - not used yet, should contain an empty string
      8. $severity_numeric - contains "1"
      9. $severity_string - according to $severity_numeric: see above)
      10. $msg1 - Log message; if $flags1=="socket": OS error message
      11. $msg2 - if $flags1=="socket": Human message of I/O error; else: not used yet, should contain an empty string
      12. $server - see above
      13. $port - see above

    Note: You can use "if_match" and "!if_match" on "$type" argument to filter it out, and then command "admin_msg". To send ALL events, use procedure:


Procedure commands and syntax

Basic knowledge:

You can use php-like scripting syntax. Note that scripting in logic.txt is poor, for advanced scripting you should use PHP script (see "SCRIPT" command, which executes a PHP script). There are some limitations: use only one SPACE as white-space (except of at beginning of the line), don't use semi-colon ";" at the end of the line, and beginning and end of block ("{" and "}" brackets) must be one separate line. Parsing engine should be advanced in future, it was written fast, just to fit basic syntax.

If the procedure contains in declaration, for example "$channel" and "$nick" variable, you can use this command for giving user +o status:

op HIGH $channel $nick

(see definition of "op" command)

Contatenating strings:

If you want to ban (+b) some user on specific channel, you can use this command:

ban_mask $channel "*!".$ident."@".$host

which means that ban mask will be set on channel name in variable "$channel". If we assume that "$ident" variable contains user's ident (for example "someuser") and "$host" variable contains user host (for example "user.host.org"), the ban mask will be "*!someuser@user.host.org". Note that there CANNOT be any space character between double-quote mark, dot and dollar sign.

For commands "op", "deop", "voice", "devoice", "msg", "msgq", "notice", "noticeq" and "chan_mode" there is first parameter indicating priority of action (it will be put to another buffer if "compress_mode_wait" inf conf.txt is non-zero). Commands "ban_mask", "unban_mask" and "kick" are always considered as HIGH priority. The valid priorities are:

  1. LOW
  2. HIGH
  3. CRITICAL - the message will be sent immediately to IRC server - note that here can occur excess flood! In case of 2 priority classes above, there is flood protection, as the messages are put into buffer before sending to server.

Let's go to definition and usage of commands:

  1. "op" command

    Definition:

    Gives +o flag to user

    Syntax:

    op LOW "#channel_name" "nick"

  2. "deop" command

    Definition:

    Gives -o flag to user

    Syntax:

    deop HIGH "#channel_name" "nick"

  3. "voice" command

    Definition:

    Gives +v flag to user

    Syntax:

    voice LOW "#channel_name" "nick"

  4. "devoice" command

    Gives -v flag to user

    Syntax

    devoice HIGH "#channel_name" "nick"

  5. "kick" command

    Definition:

    Kicks user away from channel

    Syntax:

    kick "#channel_name" "nick"

  6. "msg" command

    Definition:

    Sends user message as private message

    Syntax:

    msg LOW "nick" "message for you is here!"

    msg LOW "#channel" "message for the channel!"

  7. "msgq" command

    Definition:

    Sends quoted message (message will begin and end with 0x01 character)

    Syntax:

    msgq LOW "nick" "" "ACTION says hello!"

    So the result will be like:

    PRIVMSG nick :<0x01>ACTION says hello!<0x01>

    Note: If there is not an empty string for third parameter, you should add to end of second parameter a SPACE before ending quote, because second and third parameters will be concatenated together, but in between them there will be 0x01 character.

  8. "if_match" command

    Definition:

    Compares two strings or variables (case sensitive), if they are the same, executes next block in "{" brackets, if not, skips next block.

    Syntax:

    if_match $some_variable "check for this string"
    {
       msg LOW "nick" "Strings ARE the same!"
    }
  9. "!if_match" command

    Definition:

    Compares two strings or variables (case sensitive), if they are NOT the same, executes next block in "{" brackets, if yes, skips next block.

    Syntax:

    !if_match $some_variable "check for this string"
    {
       msg LOW "nick" "Strings are NOT the same!"
    }
  10. "if_match_case_insensitive" command

    Definition:

    Compares two strings or variables (case insensitive), if they are the same, executes next block in "{" brackets, if not, skips next block.

    Syntax:

    if_match_case_insensitive $some_variable "check for this string"
    {
       msg LOW "nick" "Strings ARE the same! (case insensitive comparsion)"
    }
  11. "!if_match_case_insensitive" command

    Definition:

    Compares two strings or variables (case insensitive), if they are NOT the same, executes next block in "{" brackets, if yes, skips next block.

    Syntax:

    !if_match_case_insensitive $some_variable "check for this string"
    {
       msg LOW "nick" "Strings are NOT the same! (case insensitive comparsion)"
    }
  12. "if_in" command

    Definition:

    Scans if string as second parameter is a part of string as first parameter

    Syntax:

    if_in $some_variable "some"
    {
       msg LOW "nick" "String ".$some_variable." contains string \"some\""
    }
  13. "!if_in" command

    Definition:

    Scans if string as second parameter is NOT a part of string as first parameter

    Syntax:

    !if_in $some_variable "some"
    {
       msg LOW "nick" "String ".$some_variable." does NOT contain string \"some\""
    }
  14. "if_group" command

    Definition:

    Checks if object named as first parameter is member of group specified in the second parameter.

    Syntax:

    if_group $some_user "group_of_super_users"
    {
       msg LOW "nick" $some_user." is member of group group_of_super_users!"
    }
  15. "!if_group" command

    Definition:

    Checks if object named as first parameter is NOT member of group specified in the second parameter.

    Syntax:

    !if_group $some_user "group_of_super_users"
    {
       msg LOW "nick" $some_user." is NOT member of group group_of_super_users!"
    }
  16. "return" command

    Definition:

    Returns from procedure (terminates the execution of procedure).

    Syntax:

    return
  17. "timer_once" command

    Definition:

    Sets a timer, and when specified time elapses, executes specified procedure, and then deletes a timer (executes it only once).

    Syntax:

    timer_once "name_of_timer" 0:00:05:00 unbanproc($channel,"*!".$ident."@".$host,$source_nick)

    "0:00:05:00" means that timer executes procedure "unbanproc" after 0 days, 00 hours, 05 minutes and 00 seconds.

  18. "timer_every" command

    Definition:

    Sets a timer, and when specified time elapses, executes specified procedure, and then resets time counter, and when time elapses again, it again executes a procedure. It doesn't deletes a timer.

    Syntax:

    timer_every "name_of_timer" 0:00:05:00 msg_to_user($nick,"Once again, 5 minutes has elapsed")

    "0:00:05:00" means that timer executes procedure "msg_to_proc" after 0 days, 00 hours, 05 minutes and 00 seconds.

  19. "execute" command

    Definition:

    Calls a procedure.

    Syntax:

    execute some_procedure($parameter1,"parameter #2")

  20. "SMTP" command

    Definition:

    Sends an e-mail.

    Syntax:

    SMTP
    {
        server "mail.somehost.org"
        port 25
        HELO "somehost.org"
        MAIL_FROM "MyBot@somehost.org"
        RCPT_TO "your_eamil@somehost.org"
        DATA
        From: My Bot <MyBot@somehost.org>
        To: VooDoo cIRCle administrator <your_email@somehost.org>
        Subject: WARNING!
        -
        $nick has de-opped me on channel $channel !!!
        .
    }
    
  21. "NET_SEND" command (Windows NT only!)

    Definition:

    Sends an administrator message.

    Syntax:

    NET_SEND "127.0.0.1" "BOT WARNING! Check your e-mail messages!"

    or:

    NET_SEND "your_computer_name" "BOT WARNING! Check your e-mail messages!"
    

  22. "LOG" command

    Definition:

    Writes a message to the log (file "logs/bot.log")

    Syntax:

    LOG "There is a log message"
  23. "join" command

    Definition:

    Joins a channel.

    Syntax:

    join "#your_channel"
    join "#your_channel" "key"
  24. "part" command

    Definition:

    Parts a channel.

    Syntax:

    part $channel_name
  25. "disconnect" command

    Definition:

    Disconnects from IRC server (should be called before connection commands)

    Syntax:

    disconnect
  26. "irc_server" command
    Definition:

    Adds a server and port for later "try_connect" command

    Syntax:

    irc_server "irc.host.org" 6667
    irc_server "irc2.host.org" 6667

    Note: You can specify here also IPv6 host or address; on Win32 works only if bot was compiled with IPv6 support, on non-Win32 works even not - but some features will fail.

  27. "try_connect" and "if_error" command sequence
    Definition:

    Tries to connect to IRC server, with values and order given by "irc_server" command, and moves server list iterator to the next server / port.

    Syntax:

    label again
    try_connect
    if_error
    {
       sleep 10
       goto again
    }
    Notes: this sequence tries to connect to IRC server, if an error occured, it waits 10 seconds and jumps to label again (see "goto" and "label" commands)

  28. "bot_nick" command

    Definition:

    Sets the nick name of bot (you can define multiple nicks, for case that nick is taken over)

    Syntax:

    bot_nick "MyBot"
    bot_nick "MyBot2"
  29. "bot_ident" command

    Definition:

    Sets the bot's ident name. When the bot is connecting to IRC server, it enables the IDENT server (for IPv4 network), and after successful reply to ident request it shuts it down. Should be omited if OS has its own IDENT daemon.

    Syntax:

    bot_ident "MyBotRulez"
    Note:
    You should use this command to make bot know what to say to IRC server in USER command, even if your ISP or system is already running IDENT daemon. To disable internal ident daemon emulation use parameter "disable_ident_daemon" in file conf.txt. If this command is not present, bot takes current nick, converts it to lowercase and removes non-alphabet characters.
  30. "bot_ident_ipv6" command

    Definition:

    Sets the bot's ident name. When the bot is connecting to IRC server, it enables the IDENT server (for IPv6 network), and after successful reply to ident request it shuts it down. Should be omited if OS has its own IDENT daemon.

    Syntax:

    bot_ident_ipv6 "MyBotRulez"
    Note:
    If your procedure contains this command, the whole procedure will not be replicated to bot of version <1.0.18, that is BOTNET protocol <4, for compatibility reasons, since this command was introduced in version 1.0.18.
    Note:
    You should use this command to make bot know what to say to IRC server in USER command, even if your ISP or system is already running IDENT daemon. To disable internal ident daemon emulation use parameter "disable_ident_daemon" in file conf.txt. If this command is not present, bot takes current nick, converts it to lowercase and removes non-alphabet characters.
  31. "bot_fullname" command

    Definition:

    Sets the full name of the bot.

    Syntax:

    bot_fullname "This is a VooDoo cIRCle bot! GNU rulez!"
  32. "bot_auth" command

    Definition:

    Sends authentication to IRC server.

    Syntax:

    label again
    disconnect
    bot_nick "MyBot"
    bot_nick "MyBot2"
    bot_ident "MyBotRulez"
    bot_fullname "This is a VooDoo cIRCle bot! GNU rulez!"
    bot_auth
    wait_if_error
    {
       disconnect
       sleep 60
       goto again
    }
    
  33. "allow_redirect" command

    Definition:

    Allows bot to use different server, if the IRC server is overloaded and sends on connect message saying "I am overloaded, so use this server/port instead"

    Syntax:

    allow_redirect 1
  34. "sleep" command

    Definition:

    Waits (do nothing) for specified time

    Syntax:

    sleep 30

    Note: this exaple waits 30 seconds

  35. "restart" command

    Definition:

    Bot exites with return code 2 (two), which means for parent process that bot wants to restart itself.

    Syntax:

    restart
  36. "notice" command

    Definition:

    Send a notice message to specified nick

    Syntax:

    notice LOW "nick" "This is a notice!"
  37. "noticeq" command

    Definition:

    Sends quoted notice (message will begin and end with 0x01 character)

    Syntax:

    noitceq LOW "nick" "" "VERSION VooDoo_cIRCle"

    So the result will be like:

    NOTICE nick :<0x01>VERSION VooDoo_cIRCle<0x01>

    Note: If there is not an empty string for second parameter, you should add to end of second parameter a SPACE before ending quote, because second and third parameters will be concatenated together, but in between them there will be 0x01 character.

  38. "unban_mask" command

    Definition:

    Removes a ban mask (-b)

    Syntax:

    unban_mask $channel "*!*@*.org"
  39. "ban_mask" command

    Definition:

    Sets a ban mask (+b)

    Syntax:

    ban_mask $channel "*!*@*.org"
  40. "dcc_server" command

    Definition:

    Binds to specified IPv4 address and port, and listens on that port for DCC clients

    Syntax:

    dcc_server 0 "10.0.0.1" 2010 type

    Notes: the first parameter (here is it zero) means that this is DCC server group zero. If it is zero, the dcc connection to bot can be established by sending "dcc" or "dcc 0" message to query of the bot. If it is, for example "1" (one), this DCC server will be accessible by sending "dcc 1" to query of the bot. You can specify more than one DCC server (each with different group number). For example one for WAN clients, and one for LAN clients, which resolves some proxy/firewall limitation issues.

    "type" means type of DCC server. This parameter is optional. It can have values "chat" or "send". If it is a "chat", this DCC server is for chatting with bot, or when it is "send", it is for sending files. This is support for mIRC protocol, for commands /dcc chat IP_address:port

    Example:

    dcc_server 0 "10.0.0.1" 2010
    dcc_server 1 "127.0.0.1" 2011 chat
    dcc_server 2 "127.0.0.1" 2012 send
     

    For some firewall issues, you can use this configuration, and connect to DCC CHAT or DCC SEND with mIRC by these commands:

    /dcc chat 127.0.0.1:2011

    /dcc send 127.0.0.1:2012

    Note, that you need to set property key "127.0.0.1_dcc_user" in file "conf.txt", thus bot knows who is the one who connecting with loop-back IP address.

  41. "dcc_server_ipv6" command

    Definition:

    Binds to specified IPv6 address and port, and listens on that port for DCC clients

    Syntax:

    dcc_server_ipv6 0 "fe80::210:a7ff:fe28:8b4d%5" 2013 type

  42. "if_error" command

    (see "try_connect" command)

  43. "label" command

    Definition:

    Label checkpoint for "goto" command. Must be written BEFORE "goto" command.

    Syntax:

    label jump_here
  44. "goto" command

    Definition:

    Jumps to specified "label". Must be AFTER "label" command.

    Syntax:

    label jump_here
    ...
    goto jump_here
  45. "ident" command

    Definition:

    Returns ident name of specified nick

    Syntax:

    $ident=ident $source_nick
    Note: this command sets variable "$ident" to ident name of nick in "$source_nick" variable

  46. "host" command

    Definition:

    Returns host name of specified nick

    Syntax:

    $host=host $source_nick

    Note: this command sets variable "$host" to host name of nick in "$source_nick" variable

  47. "SCRIPT" command

    Definition:

    Executes an external script. Currently is supported only PHP.

    Syntax:

    SCRIPT "php" 1 $channel ($source_nick,$msg)

    Note: The first parameter is type of script (must be always "php"). Second parameter is number of script in "conf.txt" file. Third parameter is name of channel to pass to script, and rest are parameters for that script.

  48. "telnet_server" command

    Definition:

    Binds to specified IPv4 address and port, to listen for telnet users and other bots in the botnet.

    Syntax:

    telnet_server "10.0.0.1" 4444
  49. "telnet_server_ipv6" command

    Definition:

    Binds to specified IPv6 address and port, to listen for telnet users and other bots in the botnet.

    Syntax:

    telnet_server_ipv6 "::1" 4444
  50. "link" command

    Definition:

    Links to another bot on the botnet.

    Syntax:

    link telnet "other_bot" "0.0.0.0" "10.0.0.1" 6666 bot_unlinked("other_bot")
    link telnet_ssl "other_bot" "0.0.0.0" "10.0.0.1" 6666 bot_unlinked("other_bot")

    Note: The first parameter is type of connection (currently only "telnet" and "telnet_ssl" connection are supported) describes if to use plain binary telnet connection, or encapsulated in SSL tunnel. Note that for SSL connection, the other bot should have properly configured the certificate chain to use (see "ssl.txt"). Second parameter is name of remote bot (as in "logic.txt"). The third parameter is local IPv4 address to bind to. Fourth parameter is remote address for other bot. Fifth parameter is remote port. And last parameter is function to call when bot connection will be broken (this is useful to call "link" command in this procedure)

  51. "work" command

    Definition:

    After successful connect and authentication on IRC server, you should use this command. When connection to IRC server will be broken, bot will continue execution after this command.

    Syntax:

    work
  52. "chan_mode" command

    Definition:

    Changes the mode of channel.

    Syntax:

    chan_mode LOW "#your_channel" "+tn"
  53. "change_nick" command

    Definition:

    Changes the nick of the bot.

    Syntax:

    change_nick "MyBot"
    change_nick $nick
  54. "kill_timers" command

    Definition:

    Kills all timers that matches the mask by their name, so they won't be called anymore, until they are defined again.

    Syntax:

    kill_timers "timer_*"
    kill_timers "timer_1"
  55. "get_chan_mode" command

    Definition:

    Returns channel mode of specified channel

    Syntax:

    $mode=get_chan_mode $channel

    Note: this command sets variable "$mode" to channel mode of channel in "$channel" variable (e.g. "nt",...)

  56. "get_chan_topic" command

    Definition:

    Returns channel topic of specified channel

    Syntax:

    $topic=get_chan_topic $channel

    Note: this command sets variable "$topic" to channel topic of channel in "$channel" variable (e.g. "There is a topic!", or an empty string for no topic)

  57. "topic" command

    Definition:

    Sets a new topic for channel

    Syntax:

    topic $channel "A new topic!"
  58. "check_dynamic_bans" command

    Definition:

    Checks if there's an entry for dynamic ban

    Syntax:

    $match=check_dynamic_bans $channel $nick $reason

    Notes:

    Above command checks for dynamic ban entry on given channel and user on that channel with given nick, if there's an entry, it sets $match variable to "1", if not to "0". Also if there's a match, it sets variable $reason to dynamic ban's reason.

    Future compatibility note:

    For testing return value ($match here), use:

    if_in $match "1"

  59. "dynamic_ban" command

    Definiton:

    Sets a dynamic ban entry

    Syntax:

    dynamic_ban $channel $prefix $ban_mask $reason

  60. "process_on_banned" command

    Definition:

    Forces bot to process "on_banned" events if it finds out that some user(s) is banned. Useful to call after "ban_mask" command (see notes below).

    Syntax:

    process_on_banned $channel $nick."!".$ident."@".$host

    Notes:

    Do not call this command directly after "ban_mask" command, because bot has queue for commands to IRC server. Every command is placed there, and it waits for incoming "MODE" command from server as confirmation that ban was set. It can be useful call a procedure with this command approximately 5 seconds after command "ban_mask":

    procedure process_banned($channel,$mask)
    {
        process_on_banned $channel $mask
    }
    
    
    ...
    
    
        $ident=ident $nick
        $host=host $nick
        ban_mask $channel $nick."!".$ident."@".$host
        kick $channel $nick $reason
    timer_once "process_banned" 0:00:00:10 process_banned($channel,$nick."!".$ident."@".$host)
  61. "raw" command

    Definition:

    Send raw command to IRC server.

    Syntax:

    raw HIGH "MODE ".$channel." +h someone"
    raw LOW "PRIVMSG ".$channel." :I have set mode +h to someone!"
    raw CRITICAL "KICK ".$channel." ".$nick." :Go away!"
    

    Notes:

    If your procedure contains this command, the whole procedure will not be replicated to bot of version <1.0.10, that is BOTNET protocol <2, for compatibility reasons, since this command was introduced in version 1.0.10.

    Use "CRITICAL" priority at your own risk, because message with this priority class is sent immediatelly, thus there is no flood protection/check, and your bot could possibly end up with server's KILL (excess flood) if you'll send too much messages.

  62. "remote_execute" command

    Definition:

    Calls a procedure stored on remote bot on BOTNET.

    Syntax:

    $result=remote_execute "botname" some_procedure($parameter1,"parameter #2")
    Notes: This executes above procedure on bot named "botname". In the variable "$result" there will be stored string saying if it was successful. NOTE! You should test this string with command:
    if_in $result "something"
    (or "!if_in") because of future compatibility, since there could be more flags. In the above example the "something" could be one of following:
    "@not_linked@" - this means that bot (as above named "botname") is not linked at the moment, so it has failed.
    "@remote_not_supported@ " - this means that another bot is VooDoo cIRCle version < 1.0.14, that is BOTNET protocol version < 3, so it doesn't support to call procedures remotely.
    "@args_too_long@" - this means that you have exceeded number of bytes in the arguments of your call. There is limit approximatelly 63 kilobytes (i.e. 64512 characters).
    "@ok@" - this means that remote procdure call packet has been successfuly sent.

    NOTE: Even if it returns "@ok@" it doesn't mean that procedure on remote side hass been executed. This is unreliable, because that procedure on remote side MUST be allowed for source bot to be executed (flag "remote_bot_call", see command ".rproc" on DCC/telnet connection). Also the packet may not be delivered due to error on network.

    Example of procedure that could be called from bot named "abc" remotely:
    procedure test($channel,$what)
    {
        last_changed 0
        remote_bot_call abc
        msg LOW $channel $what
    }
    If your procedure contains this command, the whole procedure will not be replicated to bot of version <1.0.14, that is BOTNET protocol < 3, for compatibility reasons, since this command was introduced in version 1.0.14.

  63. "delete_irc_servers" command

    Definition:

    Erases server mask from irc server list. It is good to re-initialize list of servers before chunk of commands "irc_server".

    Syntax:

    delete_irc_servers "*"
    delete_irc_servers "[*.org]:*"
    delete_irc_servers "[irc.non-existing-domain.org]:6667"

    Note: Domain of server must be enclosed in "[]" and port is defined after ":".

    Note: If your procedure contains this command, the whole procedure will not be replicated to bot of version <1.0.24, that is BOTNET protocol < 6, for compatibility reasons, since this command was introduced in version 1.0.24.

  64. "delete_nicks" command

    Definition:

    Erases bot's nick mask from nick list. It is good to re-initialize list of servers before chunk commands "bot_nick".

    Syntax:

    delete_nicks "*"
        delete_nicks "Nick*"

    Note: If your procedure contains this command, the whole procedure will not be replicated to bot of version <1.0.24, that is BOTNET protocol < 6, for compatibility reasons, since this command was introduced in version 1.0.24.

  65. "admin_msg" command

    Definition:

    Sends an administrative message to local users, or to users on other connected bots (a message to DCC/telnet connections).

    Syntax:

    admin_msg "@telnet@" "Voo*Man" "Hello!"
    admin_msg "@telnet@" "*" "Bot is going down in 5 minutes for maintenance."
    admin_msg "@telnet@" "VooDooMan@*" "Hello VooDooMan on all connected bots!"
    admin_msg "@telnet@" "*@*" "Bot will be delinked and go down in 5 minutes."

    Notes:
    The first argument are flags telling where the message will go to, and SHOULD contain sub-string "@telnet@". In the future, there may be also other flags specified, now, others are ignored. If the string doesn't contain "@telnet@", nothing will be done.
    The second argument is mask of users (using wildcards "*", "?", and "#" for one numeric character) to send message to. If they are connected to DCC/telnet connection, they will receive message. If this string contains at-sign ("@"), then follows mask of names of bots to send message to users on those bots. Names of users and bots used to match the specified mask are taken from user's / bot's name as defined in "logic.txt".
    The third argument is the whole message.

    Examples:

    admin_msg "@telnet@" "*" "message here!"
    (will send message to all DCC/telnet-connected users, but LOCALLY connected, because here is missing "@" character.)

    admin_msg "@telnet@" "user*" "message here!"
    (will send message to all DCC/telnet-connected users whose names - as name defined in "logic.txt" - begins with "user", but LOCALLY connected, because here is missing "@" character.)

    admin_msg "@telnet@" "user*@bot2" "message here!"
    (will send message to all DCC/telnet-connected users whose names - as name defined in "logic.txt" - begins with "user", but only those connected to bot named "bot2" - as in file "logic.txt". This requires bot "bot2" to be currently linked.)

    admin_msg "@telnet@" "*@*" "message here!"
    (will send message to all DCC/telnet-connected users on all connected bots.)

    Note: The message will receive also user(s) who is connected to DCC/telnet connection, but it is not required them to be on any partyline channel.

    Note: The message to other bot(s) is forwarded between all linked bots on all the BOTNET, and on remote bot it is passed to all linked bots on its side, to provide propagation of the message, but message is processed (e.g. sent to users) on one bot only if that bot's name matches bot name mask (which is following to at-sign in second argument).

    Note (compatibility): If your procedure contains this command, the whole procedure will not be replicated to bot of version <1.0.50, that is BOTNET protocol < 10, for compatibility reasons, since this command was introduced in version 1.0.50.

    Note (compatibility): Bot of version < 1.0.50 will also forward messages to other bots, but will not process it (e.g. will not show it to its locally-connected users).

    Good tip. Administrators of multiple linked bot(s) will find useful this procedure:
    set on this procedure right "access_usage_procedure" to yourself, and then use this commands on DCC/telnet connection:

    .execute shutdown()
    This example will produce message similar to this on locally connected users:

    *** ADMIN MESSAGE on Wed Jun 29 09:51:32 2005 received from bot (this local bot) sent to *: Bot will be restarted for maintenance, you will need to re-establish your DCC/telnet connection.

    and on other linked bots:

    *** ADMIN MESSAGE on Wed Jun 29 09:51:32 2005 received from bot your_bot_name_here sent to *@*: Bot will be de-linked for maintenance.

    This will inform users on partyline channels that something unusual will happen, to not to worry and not to spam you with messages on IRC saying "hey! why users connected to your bot has left our partyline channel, saying that botnet-split occured?!?! what are you doing with that bot?!".

File "conf.txt"

Let's got to explain what each line means:

  1. botname - name of your bot
  2. admin - your e-mail
  3. botnet_penalty - number of seconds, to penalty bot when it passes bad password (for high CPU usage protection)
  4. log_echo_debug - set to 1 (one) if you want to see in the console debug messages
  5. log_echo_irc - set to 1 (one) if you want to see in the console IRC messages
  6. log_echo_socket - set to 1 (one) if you want to see in the console socket error messages
  7. log_echo_bot - set to 1 (one) if you want to see in the console bot messages
  8. log_echo_identd - set to 1 (one) if you want to see in the console IDENTD messages
  9. log_echo_botnet - set to 1 (one) if you want to see in the console botnet messages
  10. log_echo_botnet_debug - set to 1 (one) if you want to see in the console botnet debug messages
  11. log_debug - set to 1 (one) if you want to log debug messages to file in logs directory
  12. log_irc - set to 1 (one) if you want to log IRC messages to file in logs directory
  13. log_socket - set to 1 (one) if you want to log socket error messages to file in logs directory
  14. log_bot - set to 1 (one) if you want to log bot messages to file in logs directory
  15. log_identd - set to 1 (one) if you want to log IDENTD messages to file in logs directory
  16. log_botnet - set to 1 (one) if you want to log botnet messages to file in logs directory
  17. log_botnet_debug - set to 1 (one) if you want to log botnet debug messages to file in logs directory
  18. php_processor - full path to PHP preprocessor (in most cases on Windows(TM) it is c:\php\php.exe)
  19. php_script_dir - relative path (from irc_bot.exe) to scripts directory - should be .\scripts\
  20. php_1 - name of PHP file for script #1
  21. php_2 - name of PHP file for script #2, ...
  22. php_2_1 - name of PHP file for script #1 for method php_2
  23. dcc_bind_ip - IPv4 address that should TCP listening socket bound for DCC connections
  24. dcc_bind_ip6 - IPv6 address that should TCP listening socket bound for DCC connections
  25. notify_interval - number in minutes for noitifying users about filesystem messages / files
  26. dcc_max_transfers - number of maximum DCC concurrent transfers
  27. ctcp_lag_user_msgs - number of CTCP (and also DCC) requests limit for time (see next field) to ban user from using DCC/CTCP (for flood protection)
  28. ctcp_lag_user_seconds - number of seconds to ban user for (see previous filed)
  29. dcc_send_timeout - time in seconds considered as timeout if nothing has been transferred via DCC
  30. irc_bot_flood_bytes - maximum number of bytes to send to IRC sever (PRIVMSG or NOTICE) to prevent flood
  31. irc_bot_flood_seconds - number of seconds to live entry in flood history to prevent flood (see above line)
  32. irc_bot_flood_lines - maximum number of lines (commands) to send to IRC server to prevent flood (see above 2 lines)
  33. 127.0.0.1_dcc_user - name of user, who is considered as it, when it is connecting from loop-back IP address to DCC server (either IPv4's "127.0.0.1", and IPv6's "::1").
  34. msg_force_secure_lines - maximum number of lines of message stored in filesystem. If number of lines is greater than this value, the message will be forced to set flag SECURE, to prevent flood, thus user need to connect via DCC CHAT to read it.
  35. irc_bot_flood_other_seconds - Number of seconds to wait for bot when sending for example WHOIS and MODE commands to prevent flood.
  36. try_reverse_lookup - if set to 1 (one), bot tries to use reverse lookup DNS resolution, if some user has as host obtained from IRC server IPv4 address instead of DNS name - it helps to bot identify user, even if IRC server accidentally could not perform reverse lookup successfully.
  37. important_ident_daemon - if set to 1 (one), when bot detects that it could not bind socket for IDENT daemon, it will not connect to IRC server, until socket could be bound.
  38. compress_mode_wait - number of seconds to put each mode (except of +/-b, e, I) to queue for, to "compress" modes (it will not be send 2 times +o and once +v, but +oov)
  39. smart_mode - only applicable if compress_mode_wait is non-zero. If set to 1 (one) bot will remove from queue modes that are set by other users, bots, and servers after net split, if same channel name, nick, and mode (including "+" and "-") are in the queue.
  40. send_+R - ignored for backward compatibility. Now the bot is using RPL_ISUPPORT - 005 information message to decide if to send "MODE #channel +R"
  41. dcc_chat_ping_interval - Ping message interval in seconds on DCC/telnet (not BOTNET) connection to console to help detect if user is alive, or the connection was broken without notification from IP stack. This could prevent (in theory) hung "zombie" users on partyline. Ping message interval can be set in seconds, or zero for dissable.
  42. lockout_duration - Lock out IP address for this interval in seconds. (see bellow)
  43. lockout_count - Number of unsuccessful log ins from one IP address to be considered as intruder is guessing password, so lock this IP address for "lockout_duration" seconds. (see above)
  44. dcc_max_message_size - Number of bytes as maximum size of message to other user via filesystem - helps to control memory resources. When set to 0 (zero), it is ignored.
  45. dcc_max_sessions_per_ip - Number of maximum sessions on DCC/telnet connection for one IP. Useful for defence against DoS attacks, and to save memory resources. If it is exceeded, the session with largest idle time is closed.
  46. auto_backup_interval - Number of seconds of interval to automatically backup configuration (as command ".backup" does). Zero (0) to disable.
  47. disable_ident_daemon - Set to "1" (one) if your ISP or your system runs IDENT daemon, so bot will disable its internal ident daemon emulator. Still you should use command "bot_ident" to make bot know what to pass as argument to "USER" command for IRC server. If set to "1", value of "important_ident_daemon" is ignored.
  48. dcc_always_want_nick - Set to "1" (one) if you want to force user connecting on DCC connection is required to enter their nick name (as in "logic.txt"), and then password. If set to 0 (zero), they are only required to enter password (bot recognizes them by host mask) - this was default on versions prior to 1.0.52. Security note: If it is turned on, and user types nick of someone else who don't have password set yet, bot rejects it and closes connection with error message. This is because of security reasons.

Quick start

You should start with this logic.txt file:


Botnet and replication

Botnet are two or more bots (of same vendor) connected together.

Basic knowlegde:

replication PUSH - means that this bot will push this object to another bot if it has an old version of object

replication PULL - means that this bot will request other bot to get object from it if it has a newer version of object

replication PUSHPULL - means that this and another bot will check who has newer version of object, and, if needed, it will be replicated

In order to replicate object (an user, procedure, channel definition, or private section), one bot need to be PUSH, the second PULL or PUSHPULL, or vice-versa, or both PUSHPULL.

Example to add to logic.txt file of bot1:

and bot2:

You can also add line:

replication bot_name push

to procedures, channel definitions and private section. Note that the other bot needs privileges, such as "access_to_+user 1" to add a new user. Since version 1.0.26, the remote bot needs to have locally flags "access_usage_procedure" on procedures which are assigned to user's on_XXX events; if event has already assigned procedure, it needs also this flag for old assigned procedure. Also, since version 1.0.26, remote bot needs to have also flag "access_grant_can_send_unknown_users 1" in order to change from "can_send_unknown_users 0" to "can_send_unknown_users 1", or vice-versa, to existing user, or to set to "can_send_unknown_users 1" to new user in process of creating/updating new/existing user.

You must also set password for this bot in pass.txt encoded via MD5 algorithm, and set it also to remote bot itself. You can use ".chpass" command on DCC/telnet connection, if you have "access_to_user" flag for that bot.

It is strongly recommended that all your bots on the botnet are connected in "mesh topology" - each one with each one. But do not connect your bot1 to link to bot2, and bot2 to link to bot1 - use only one connection to other bot. However, there is algorhitm to detect and kill these doubled connections attempts.

Example of link procedure:

and then call procedure "link_bot_once" in "_sys_startup" procedure.

There is another scenario used when we don't know predefined IP address of remote bot (DHCP), so we use for "on_join" event procedure "another_bot_join()":

 


PHP scripting (old method)

Your PHP script should look like:

Note, that you need comment lines with strings "// INIT" and "// RESULT" keep untouched, since bot will replace them with channel information. Result code, that will be processed by php preprocessor will look like this:

The bot processes the output of PHP script (stdout pipe). So the result should look like this:

Which means than on second line raw NOTICE command put to queue with high priority to put to IRC server, on next one raw message for low queue, another one, deop some nick in critical mode (the raw message is sent IMMEDIATELLY to IRC server - which is not recommended, because multiple of these could violate flood rules on server, and your bot could end up with "excess flood" - should be used only for deopping and banning at critical moments). On another one, there is put log entry for channel "#channel" into logs, and on the last one, there is execution of procedure in "logic.txt" - this feature was introduced in version 1.0.14.

To modify filesystem attributes, use script that looks like:

Note that you need use doubled escape characters in NotifyUserMessage and NotifyOwnerMessage messages, so "\n" should be "\\n" in order to bot process it correctly, because "\n" will generate new line.

See section about filesystem too.


PHP scripting ("php_2" method)

Your PHP script should look like:

Note, that you need comment lines with strings "// INIT" and "// RESULT" keep untouched, since bot will replace them with channel information. Result code, that will be processed by php preprocessor will look like this:

The bot processes the output of PHP script (stdout pipe). So the result should look like this:

Which means than on second line raw NOTICE command put to queue with high priority to put to IRC server, on next one raw message for low queue, another one, deop some nick in critical mode (the raw message is sent IMMEDIATELLY to IRC server - which is not recommended, because multiple of these could violate flood rules on server, and your bot could end up with "excess flood" - should be used only for deopping and banning at critical moments). On another one, there is put log entry for channel "#channel" into logs, and on the last one, there is execution of procedure in "logic.txt" - this feature was introduced in version 1.0.14.

To modify filesystem attributes, use script that looks like:

Note that you need use doubled escape characters in NotifyUserMessage and NotifyOwnerMessage messages, so "\n" should be "\\n" in order to bot process it correctly, because "\n" will generate new line.

See section about filesystem too.


DCC / telnet commands

Note: When you are connecting via telnet, you MUST enter your "nick name", it is the name from "logic.txt" (user "your_name_here"), but it is case-sensitive, so "MyNaMe" is NOT the same as "myname"!

Note: Every command MUST begin with dot ("."), in other case, if you are on a partyline channel, it will go to the partyline chat.

  1. .help

    Displays list of these commands.

  2. .whois <name>

    Displays parameters for user as known in logic.txt (under user "your_name_here")

    Examples:

    .whois your_name_hehe

    .whois your*

    .whois *name*

  3. .+user

    Adds new user. You need enough privileges (access_to_+user).

  4. .edituser

    Use this for editing an user. You need enought privileges (access_to_group XXX, and that user must be member of group XXX)

  5. .+proc

    Adds new procedure. You need enough privileges (access_to_+proc).

  6. .editproc

    Use this to edit a procedure. You need enough privileges (access_to_procedure XXX)

  7. .editchan

    Use this to edit channel definitions.

    You need enough privileges (access_to_channel)

  8. .+chan

    Use this to add a channel definition.

  9. .quit

    Closes DCC / telnet connection.

  10. .backup

    Saves configuration to logic.txt

    Note: This command should be followed by ".rehash" to make changes affected.

  11. .rehash

    Rehashes configuration (reloads logic.txt)

  12. .filesystem

    Enters the filesystem.

    Note: You need to have privilege ("access_to_filesystem").

    See section filesystem.

  13. .msg

    Use this to store message in filesystem for another user

  14. .getfile <filename> <optional_dcc_group>

    Gets file from filesystem.

    Note: You need to have privilege ("access_to_filesystem").

    The last parameter is optional, and indicates which DCC server to user (see dcc_server command for details).

    Examples:

    .getfile abc.txt

    .getfile sound.mp3

    .getfile abc.txt 1

    Note: Name of the file is case-sensitive!

    See section filesystem.

  15. .partyline <partyline_channel_(optional)>

    Enters the partyline channel.

    Examples:

    .partyline
    (Enters partyline channel "partyline")

    .partyline my_channel
    (Enters partyline channel "my_channel")

  16. .leave

    Leaves a partyline channel.

  17. .restart

    Restarts a bot.

    Note: The bot MUST be invoked by service, in order to run again. In other case, it simply dies.

    Note: You need privilege "access_to_restart".

  18. .die

    Causes the bot to die.

    Note: You need privilege "access_to_die".

  19. .+group <groupname>

    Adds a new group of name <groupname>.

    Tip: Always do this before you add a new object (user, procedure), in order to put it to a new group!

  20. .private

    Edits a private query messages for bot.

    Note: You need to have privilege "access_to_private".

  21. .replication

    Edits a replication parameters for objects.

    Note: You need to have privilege "access_grant_replication".

  22. .terminator

    Puts / removes user to / from terminator.

    Note: You need to have enough privileges ("access_to_group XXX", and that user must be member of group XXX).

  23. .lang

    Changes current bot's language for current DCC / telnet connection.

    Note: There is only english ("en") supported yet. I am searching for localizers! :-)

  24. .part

    Parts (leaves) a channel, as first parameter is channel name and, optionally, following with reason

    Examples:

    .part #channel

    .part #channel just testing :-)

    Note: You need to have access_to_channel privilege on that channel.

  25. .join

    Joins a channel as first parameter and, optionally, followed by channel key (if the channel is +k for key, this can be omitted, so bot will try every key that has in the key history for that channel)

    Example:

    .join #channel

    .join #channel this_is_key

    Note: You need to have access_to_channel privilege on that channel.

  26. .rproc

    By typing this command you can edit list of another bots on BOTNET wheter they can call procedures remotely. At default it is dissabled on all procedures. You'll get list of procedures of those you have access to ("access_to_procedure") to select one, and then you can edit list of bots for it.

  27. .upgrade

    This command has been introduced in version 1.0.20. It is for safer upgrading of your bot. Place new executable binary of new version into directory "upgrade", with name of file that doesn't contain space character. As a first parameter to this command use name of that file (plain, just a file name, not path!). At this moment bot will close any listening sockets (in order to new instance of bot could bind/reuse them), and in the console (the old bot) will inform you if new instance of bot, that will be ran, joins channels. This is done by comparing host and full name mask associated with user (bot) with "host_bot" attribute in file "logic.txt". Also, you will be informed when new instance of bot changes its nick, or if it have received "+o", "-o", "+v", and "-v" status on channels. If this mode change has origin of the old instance of bot, note that there is queue for "LOW" and "HIGH" priorities, for example, of command "op" in "logic.txt", so if you have "compress_mode_wait" enabled, it may take that numer of seconds (or few more) from you receive information in the console to real post the mode change to server. If the new instance is not detected to join another channel (the old bot is on) for 3 minutes, the old instance is automatically shuted down. You can force shut down by command ".die".

    Note: You need to have "access_to_upgrade" privilege in order to use this command.

  28. .chpass

    Changes password. Syntax:
    .chpass <name_of_user> <new_password>

    Note: Name of user is also case-sensitive. You can change your own password; if you need to change other user's password, you need to have access_to_group privilege on group that is that user member of.

  29. .showbots

    Shows bots that are linked to local bot, and those which were delinked (marks them as "trying to connect").

  30. .broadcastping

    Broadcasts to each connected bot ping message and shows pong's and their lag. Note that this is done by special partyline message, as you have had posted it to some channel, so bots in the Botnet are forwarding this message, thus you can get doubled results. This message is also limited by partyline flood limit setting.

  31. .execute

    Executes a procedure stored in "logic.txt".

    Example:
    .execute unban_user("#mychannel","nick!ident@host.org")

    Note: You need "access_usage_procedure" right on procedure you want to execute.

  32. .apply

    This command causes re-validation of users on channels (something like "soft rehash"), e.g. who should get +o, or +v status. For example, if you want to delegate some user to be dynamic ban editor on some channel, and you don't want to give them "access_to_backup" and "access_to_rehash" rights, they should have "access_to_apply" right and use this command to apply changes they made. See section "Good tips" for explanation why you should not to give "access_to_backup" and "access_to_rehash" rights to common users, because ".backup" and ".rehash" in reverse order could be dangerous.

    Note: You need "access_to_apply" right in order to use this command.


Filesystem

There are in the filesystem stored messages and files.

Files and messages are these attributes:

  1. Inernal name (this is name of file stored in the filesystem, it is only for internal purposes)

  2. Public name - this is original name of file from user who sent it, and it is representing the public name (.getfile <public_name> command). For case of message, this is the subject of the message.

  3. Subject of the message (see Public name)

  4. Time - timestamp of creation of the object.

  5. Published - internal flag, indicating that the user who uploaded the file has set attributes.

  6. Complete - internal flag, indicating that user has successfully uploaded the file via DCC SEND, or if file is not complete, thus user will be notified that it should try apply DCC RESUME, or DCC SEND to overwrite the file and upload it again.

  7. Expiration - timestamp when will be object discarded.

Access attributes of the object:

  1. OWNER - this flag is set if the user is owner, thus have right to delete object, or set attributes, and an expiration. Note that there can be multiple owners for one object.

  2. READ - this flag is set if user can read the message, or download the file via DCC SEND.

  3. DELETE - this right gives user right to delete the object from the filesystem.

  4. SECURE - this flag is set if authentication before download the file / read the message is required (user is notified that it must connect via DCC CHAT, authenticate by password, and then it gets thru). Note, that there is "conf.txt" file, which contains value for key "msg_force_secure_lines", so if number of line of this message excess this value, message is automatically flagged as SECUREd, to prevent bot from flooding the IRC server with PRIVMSG.

  5. NOTIFY_OWNER - this flag is set if owner(s) is (are) notified if someone have read the message or downloaded the file.

  6. NOTIFY_USER - this flag is set if user who has READ permission should be notified to download file, or the message will be sent to them, or if there is SECURE flag set, it will be notified that it should connect via DCC CHAT and read the message.

Every object also has set of events, saying such as "user was notified according to flag NOTIFY_USER", "user has read the message", or "owner was already notified about someone has read message / downloaded the file".


VooDoo cIRCle service (Windows(TM) only)

Installation of service:

  1. enter directory with file "vdcsvc.exe"

  2. run command "vdcsvc.exe -install"

Configuration of service:

Configuration file must be stored in "C:\vdc.txt"

Contents of this file:

  1. First line is a path, where is located file "irc_bot.exe" and configuration files

  2. Second line is a number of seconds to wait to run the bot, after the service has started. (This allows you to run more bots, avoiding IDENTD server conflicts).

  3. Third line must contains only . (a dot)

  4. Fourth line is path to next bot (as step 1.).

Example:

This example runs two bots.


SSL

There is possibility for these bots on BOTNET to talk via SSL to each other. Here is sample file describing certificates:

Note: All certificates must be in PEM format.

This means that bot will accept ONLY connecting client's certificate issued by CA's with its certificates stored in file "cert\CAs.crt" passed one by one.

As Telnet Server, it uses as server's certificate chain and key files "cert\server.crt" and "cert\server.key" respectively.

As a client connecting to other bot, it will use certificate chain and key files "cert\client.crt" and "cert\client.key" respectively.

And finally, "[abc]" section means, that when remote bot with name "abc" (from logic.txt file) connects, it will be checked against file "cert\abc.crt" (against its SHA1 hash) - this client should use this certificate.

Important security note: You should ALWAYS generate your own certificates, and/or certificates of your own Certification Authority due to security reasons. You should use default ones in distribution only for testing.


MOTD - Message Of The Day file

There could be "motd.txt" file (in the same directory as executable), which is copied to console when user successfully logs-in on DCC/telnet interface. This feature was there since first release, but it was forgotten in this documentation.

CLI - command line interface

Command-line options as follows:
-h or --help prints out supported options.
-v or --version prints out ONLY version, then exits.
-i or --interactive runs in interactive mode (opposite to --daemon) - default on win32
-d or --daemon runs in background, returns to shell (opposite to --interactive) - default for non-win32, not applicable in win32.

Good tips

  1. When you creating new user, ALWAYS put them to group that you have "access_to_group" privilege, or you will not have access to them!

  2. On DCC / telnet connection, you should type ".help" command to get available commands. Note, that you would not have access to some of them, unless you set it "logic.txt" or (if you have privileges) via DCC / telnet.

  3. Always do ".backup" and then ".rehash" on DCC/telnet connection, not in reverse order, because ".rehash" flushes current configuration and reloads it from file "logic.txt" and you could lost your changes. You can consider using ".apply" in combination with "auto_backup_interval" attribute in "conf.txt" file


FAQ's

I hope, that this section will contain more information later, since this is the very first release.

Q: How can I delete user?
A: You cannot delete user, because of simple reason. When you would delete user, another bot in the botnet would find out, that bot on which you have deleted an user doesn't have this user, so the replication would cause to user exist again. Instead of deletion, you should use command ".terminator" in DCC / telnet connection, and set user as "terminator". Bot will flag this user as terminator, and update its last_changed value, so the record (with terminator flag) should replicate to all bots. If an user is "terminator", it tells the bot to silently ignore them at all, but it still exists in the database.

Q: Which host masks/wildcards are supported?
A: You can use wildcard "*" to match any or zero number of characters, "?" to match one character, or "#" to match one numeral character (0-9) for nick, ident, or host. You can match host by CIDR notation, but in this case, you can't use wildcards in host part. If host mask is for instance "*!ident@0:0:0:0:0:ffff:10.0.0.2/120" (any nick, "ident" as ident, and IPv4-mapped address "10.0.0.2" with CIDR 120 bit long) will match users with any nick, "ident" as ident, and IPv4 address "10.0.0.x", where "x" is any number (0-255). So you can freely use IPv6 addresses, or IPv4-mapped IPv6 adresses, as well. IPv4 addresses, given by IRC server, or you, will be converted to IPv4-mapped IPv6 address first. Another example for host mask is "nick!ident@10.0.0.#", which match user with "nick" as nickname, "ident" as ident and IP address "10.0.0.x", where "x" stands for any one numeral character (0-9). For your consideration: It should be better for this instance to use host mask "nick!ident@10.0.0.0/24", which means that "x" can be number in range 0-255. You can also specify wildcarded host name in the mask, such as "*!ident@*.net". If you specify exact host name, such as "*!ident@host.net", the bot will try to resolve it to IPv4 address, and then, if succeed, convert it to IPv4-mapped IPv6 address and then check for match. Remember: Do not mix both CIDR notation and wildcards in host name part of host mask, so host mask "*!ident@10.0.*.23/24" is wrong.

Q: Does IPv6 host masks for IPv6 IRC users work even bot is not compiled with IPv6 support?
A: Yes, it works. IPv6 support in VooDoo cIRCle is experimental, and fact that it is compiled with this support means only that you can use IPv6 socket for telnet user/bot connections. There is also IPv6 connection to IRC server, and DCC CHAT/SEND thru IPv6 as well. However, if the bot is not compiled with IPv6 support, DNS resolving of IPv6 host (needed to satisfy host masks) will not work.

Q: How could I compile bot with IPv6 support?
A: Define global preprocessor directive:
#define IPv6
or un-comment that one in file "params.h", but do not touch directive INET6 in match.cpp, because this code is hacked from ircd for IRCnet, and it is only for matching IPv6 host masks, not for IP traffic, so it must be defined to work properly.

Q: There is feature that supports recognition also by their "full name mask". Can I turn it off?
A: The full name is field in the WHOIS command, initally set by USER command at IRC protocol authentication. In some IRC clients it is "real name" field in connection dialog. If you don't want to use this feature, you can simply set for particular user full name mask of "*" wildcard, so it will match any full name.

Q: How can I compile this bot?
A: See documentation for your platform in the source package in direcory "voodoo_circle-src/docs/compile/".

If you have some questions, feel free to send me a mail to ghostvoodooman [NOSPAM] (at) [NOSPAM] users (dot) [NOSPAM!] sourceforge (dot) net. (Please use "VooDoo cIRCle" as the subject, so I will know that it is not a spam).


Additional information

This IRC bot was developed and tested on Windows 2003 Server, using these compilers:

Successfully tested on IRCnet, UnderNet, UnrealIRCd.

I am now searching for "porter developer" who could port this bot to other Operating System(s). I am also searching for localizers, who could localize file "lang01.txt" to other languages. If you are, or you know some, please, send me a mail.


Credits

At first, thank to Jarkko Oikarinen for ideas and code for first IRC protocol, and to all the people who help to develop and keep IRC alive.

I would like to thank to MacO (http://www.cw.sk/) for founding name VooDoo cIRCle, and for logo for this bot.

My thanks also goes:

To Robey Pointer, and the Eggheads Development Team for developing IRC bot Eggdrop (for inspiration).

To http://www.sourceforge.net/, and Free Software Foundation, Inc. for great ideology.

To Pharmacy, for benzodiazepines, which are making a good mood for coding ;-) and also for Magnesium pills I am using to get energy when I'm  beginning to be overworked.

And last, but not least, to caffeine and nicotine for better (but shorter) life ;-)


GNU GENERAL PUBLIC LICENSE

GNU logo

Version 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc.  
59 Temple Place - Suite 330, Boston, MA  02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.

Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.

c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following:

a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,

c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it.

6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found.

one line to give the program's name and an idea of what it does.
Copyright (C) yyyy  name of author

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

Hosted by SourceForge.net Logo

Valid HTML 4.01!