From 7a157b26b3d341de5789a2ddacb7dfcaa88a90d0 Mon Sep 17 00:00:00 2001 From: psychon Date: Mon, 22 Oct 2007 21:49:39 +0000 Subject: [PATCH] Kill the docs dir and add a README file. This README file was started on Sep 15 and now finally gets its big moment! This file includes proposals from Kuja and prozac, thanks. git-svn-id: https://znc.svn.sourceforge.net/svnroot/znc/trunk@848 726aef4b-f618-498e-8847-2d620e286838 --- README | 117 +++++++++++++++++++++++++++++++++++++++ docs/Configuration.html | 62 --------------------- docs/Example.pm | 31 ----------- docs/ExampleWithSock.pm | 95 ------------------------------- docs/Installation.html | 27 --------- docs/ModuleHooks.html | 54 ------------------ docs/PerlMods.txt | 41 -------------- docs/UsingCommands.html | 63 --------------------- docs/WritingModules.html | 75 ------------------------- docs/index.html | 50 ----------------- 10 files changed, 117 insertions(+), 498 deletions(-) create mode 100644 README delete mode 100644 docs/Configuration.html delete mode 100644 docs/Example.pm delete mode 100644 docs/ExampleWithSock.pm delete mode 100644 docs/Installation.html delete mode 100644 docs/ModuleHooks.html delete mode 100644 docs/PerlMods.txt delete mode 100644 docs/UsingCommands.html delete mode 100644 docs/WritingModules.html delete mode 100644 docs/index.html diff --git a/README b/README new file mode 100644 index 00000000..a9014fad --- /dev/null +++ b/README @@ -0,0 +1,117 @@ +ZNC - An advanced IRC bouncer +============================= + +Table of contents: +- Minimal Requirements +- Optional Requirements +- Installing ZNC +- Setting up znc.conf +- Using ZNC +- File Locations +- ZNC's config file +- Writing own modules +- Further infos + +Minimal Requirements +-------------------- + +Core: + - GNU make (try gmake if make fails) + - GCC 3 or later + +Optional Requirements +--------------------- + +SSL support: + - openssl 0.9.7d or later (try installing openssl-dev or openssl-devel) +modperl: + - This needs perl and the bundled libperl +saslauth: + - This module needs cyrus-sasl2 + +Installing ZNC +-------------- + +Installation is done with the ./configure ; make ; make install commands. + +You can use + ./configure --help +if you want to get a list of options, though the defaults should be suiting +most needs. After you compiled it with make (or gmake if make doesnt work) you +can install it with + make install +though you don't need to as ZNC supports in-place execution. + +Setting up znc.conf +------------------- + +For setting up a configuration file in ~/.znc you can simply do + znc --makeconf +or + ./znc --makeconf +for in-place execution. + +If you are using SSL you should do + znc --makepem + +Using ZNC +--------- + +Once you have started ZNC you can connect with your favorite IRC-client to ZNC. +You should use username:password as the server password (e.g. /pass user:pass). + +Once you are connected you can do /msg *status help for some commands. +Every module you have loaded (/msg *status listmods) additionally gets + /msg *modulename help + +File Locations +-------------- + +In its data dir (~/.znc is default) ZNC saves most of its data. The only +exception are modules, which are saved in /libexec and the znc binary +itself. More modules (e.g. if you install some later) can be saved in +/modules (-> ~/.znc/modules). + +In the datadir are only two files: + znc.pid - The pid of the currently running ZNC instance. + znc.pem - This is the server certificate ZNC uses for listening and is created + with znc --makepem. + +These directories are also in there: + configs - Contains znc.conf (ZNC's config file) and backups of older configs. + modules - ZNC also looks in here for a module. + moddata - Global modules save their settings here. + (e.g. webadmin saves the current skin name in here) + users - This is per-user data and mainly contains just a moddata directory. + +ZNC's config file +----------------- + +This file shouldn't be too hard too understand. An explanation of all the +items can be found here: http://en.znc.in/wiki/index.php/Configuration + +Currently it is NOT possible to rehash the config file so you better use +webadmin or the admin module to change settings on-the-fly. + +Writing own modules +------------------- + +You can write your own modules in either C++ or perl. + +C++ modules are compiled by either saving them in the modules source dir and +running make or with the znc-buildmod shell script. + +For additional info look in the wiki: +http://en.znc.in/wiki/index.php/WritingModules +http://en.znc.in/wiki/index.php/ModuleHooks + +Perl modules are loaded through the global module modperl. +See http://en.znc.in/wiki/index.php/Modperl + +Further infos +------------- + +Please visit http://znc.sf.net or #znc on EFNet if you still have questions. + +You can get the latest development version with subversion: + svn checkout https://znc.svn.sourceforge.net/svnroot/znc/trunk znc diff --git a/docs/Configuration.html b/docs/Configuration.html deleted file mode 100644 index 522ede7d..00000000 --- a/docs/Configuration.html +++ /dev/null @@ -1,62 +0,0 @@ - - - - - - -ZNC - Configuration - - - -[Home] -- -[Project Page] - -
-

-

- File Locations -

-
    -
  • Config - ZNC gets its configuration by reading the file ~/.znc/znc.conf. See znc --help and znc --makeconf. -
  • Misc - Other files are also stored in the ~/.znc directory such as the SSL cert (znc.pem) and PidFile (znc.pid). -
  • Local Modules - Stored in ~/.znc/modules. ZNC will look in the local module dir first when trying to load a module. -
  • Global Modules - Stored in /usr/share/znc/modules by default. -
  • Binaries - znc, znc-config and znc-buildmod are stored in /usr/bin by default. You can change this when you configure by using ./configure --prefix=/whatever/path/you/want -
-

- Config File - (~/.znc/znc.conf) -

-
    -
  • Listen - The port that ZNC will listen on. If the port is prepended with a '+' then ZNC listens using ssl. If you want to listen on a specific ip, use the address as first argument and the port as second. -
  • Listen6 - The same as Listen, but uses IPv6 instead of IPv4. -
  • ISpoofFile - ZNC will write the ident of the user trying to connect to this file. Very useful if your shell supports oidentd. -
  • PidFile - The pid file that is created when znc starts. -
  • StatusPrefix - The prefix for the status and module queries. -
  • User - The user definition, you can have more than one.. -
      -
    • Pass - Used by the client to connect to ZNC. Can be a hash generated by znc --makepass -
    • Nick, AltNick, Ident, RealName, VHost - Setup your IRC user info. -
    • ChanModes - Default modes ZNC will set when you join an empty channel. -
    • KeepNick - Will keep trying to regain your primary nick if it is in use. -
    • QuitMsg - The default quit message znc will use when you jump servers or call shutdown. -
    • VersionReply - The reply sent to CTCP version requests while you are detached. -
    • AutoCycle - Set this to false if you don't want ZNC to part/join a channel when you are the last user left and not opped. -
    • Buffer - This is the amount of lines that the playback buffer will store before dropping off the oldest line. -
    • KeepBuffer - Buffer channels while you are attached and play the whole buffer back to you each time you connect. -
    • Server - Adds a server to the list of servers ZNC will connect to. -
    • LoadModule - Load a module on startup -
    • Chan - Channels you want ZNC to join when first launched. -
        -
      • Key - Key for the channel. -
      • Modes - Modes to override ChanModes. -
      • Buffer - You can set this to override the Buffer size set in the User section. -
      • KeepBuffer - You can set this to override the KeepBuffer option set in the User section. -
      • AutoCycle - You can set this to override the AutoCycle option set in the User section. -
      • Detached - If true, znc will join this channel as detached so that the IRC client will not be bothered by it. -
      -
    -
- - - diff --git a/docs/Example.pm b/docs/Example.pm deleted file mode 100644 index 9afae13d..00000000 --- a/docs/Example.pm +++ /dev/null @@ -1,31 +0,0 @@ -package Example; -use strict; - -# -# Create a constructor for the module -sub new -{ - my ( $classname ) = @_; - my $self = {}; - - bless( $self, $classname ); - - return( $self ); -} - -# -# we're going to hook this call back -sub OnChanMsg -{ - my ( $me, $nick, $chan, $msg ) = @_; - ZNC::PutTarget( $chan, "WTF!?, you said [$msg]\n" ); - return( ZNC::CONTINUE ); -} - -sub OnShutdown -{ - my ( $me ) = @_; -} - -1; - diff --git a/docs/ExampleWithSock.pm b/docs/ExampleWithSock.pm deleted file mode 100644 index e758d5f2..00000000 --- a/docs/ExampleWithSock.pm +++ /dev/null @@ -1,95 +0,0 @@ -package SampleSock; -use base 'ZNCSocket'; - -sub OnConnect -{ - my ( $me ) = @_; - ZNC::PutTarget( $me->{SamChan}, "I have FD [$me->{fd}]" ); -} - -sub OnReadLine -{ - my ( $me, $line ) = @_; - $line =~ s/\r?\n$//; - - ZNC::PutTarget( $me->{SamChan}, "I have a line [$line]" ); - $me->Write( "WHAAAAA!?\n" ); -} - -sub OnSockDestroy -{ - my ( $me ) = @_; - ZNC::PutTarget( $me->{SamChan}, "Ahhhh we be closed :(" ); -} - -sub OnSockDestroy -{ - ZNC::PutTarget( $me->{SamChan}, "destructor called, he wants his money back" ); -} - -sub OnNewSock -{ - my ( $me, $newfd ) = @_; - ZNC::PutTarget( $me->{SamChan}, "new created fd $newfd" ); - my $obj = new SampleSock( $me->{modobj}, $newfd ); - $obj->{SamChan} = $me->{SamChan}; - $obj->AddSock(); -} - -1; - -package ExampleWithSock; -use strict; - -sub new -{ - my ( $classname ) = @_; - my $self = {}; - - bless( $self, $classname ); - - print STDERR "WOOOF!\n"; - - return( $self ); -} - -sub OnChanMsg -{ - my ( $me, $nick, $chan, $msg ) = @_; - $nick =~ s/^(.+?)!.*/$1/; - - ZNC::PutTarget( $chan, "$nick, you said [$msg]?" ); - - if ( $msg =~ /^go\s+(.+?)\s+(.+)/i ) - { - my $obj = new SampleSock( $me ); - $obj->{SamChan} = $chan; - if ( $obj->Connect( $1, $2, 10, 1 ) ) - { - $obj->AddSock(); - } - } - elsif ( $msg =~ /^listen\s+([0-9]+)/ ) - { - my $obj = new SampleSock( $me ); - $obj->{SamChan} = $chan; - if ( $obj->Listen( $1, "", 1 ) ) - { - $obj->AddSock(); - } - else - { - ZNC::PutTarget( $chan, "Failed to setup listener!" ); - } - } - - return( ZNC::CONTINUE ); -} - -sub OnShutdown -{ - print STDERR "HERE I AM!!!!!\n"; -} - -1; - diff --git a/docs/Installation.html b/docs/Installation.html deleted file mode 100644 index 444f40f3..00000000 --- a/docs/Installation.html +++ /dev/null @@ -1,27 +0,0 @@ - - - - - - -ZNC - Installation - - - -[Home] -- -[Project Page] - -
-

-

    -
  1. Download Tarball -
  2. tar -xzvf znc*.*gz -
  3. cd znc* -
  4. ./configure (use --prefix=/path/to/shell/znc) if you don't want a system wide installation or simply don't have root -
  5. make -
  6. make install -
- - - diff --git a/docs/ModuleHooks.html b/docs/ModuleHooks.html deleted file mode 100644 index 41f2ef3c..00000000 --- a/docs/ModuleHooks.html +++ /dev/null @@ -1,54 +0,0 @@ - - - - - - -ZNC - Module Hooks - - - -[Home] -- -[Project Page] - -
-

-

- virtual bool OnLoad(const string& sArgs);
- virtual bool OnBoot();
- virtual void OnUserAttached();
- virtual void OnUserDetached();
- virtual void OnIRCDisconnected();
- virtual void OnIRCConnected();
-
-
- virtual bool OnDCCUserSend(const CNick& RemoteNick, unsigned long uLongIP, unsigned short uPort, const string& sFile, unsigned long uFileSize);
-
-
- virtual void OnOp(const CNick& OpNick, const CNick& Nick, const CChan& Channel, bool bNoChange);
- virtual void OnDeop(const CNick& OpNick, const CNick& Nick, const CChan& Channel, bool bNoChange);
- virtual void OnVoice(const CNick& OpNick, const CNick& Nick, const CChan& Channel, bool bNoChange);
- virtual void OnDevoice(const CNick& OpNick, const CNick& Nick, const CChan& Channel, bool bNoChange);
- virtual void OnRawMode(const CNick& OpNick, const CChan& Channel, const string& sModes, const string& sArgs);
-
-
- virtual bool OnUserRaw(string& sLine);
- virtual bool OnRaw(string& sLine);
-
-
- virtual bool OnStatusCommand(const string& sCommand);
- virtual void OnModCommand(const string& sCommand);
- virtual void OnModNotice(const string& sMessage);
- virtual void OnModCTCP(const string& sMessage);
-
-
- virtual void OnQuit(const CNick& Nick, const string& sMessage, const vector& vChans);
- virtual void OnNick(const CNick& Nick, const string& sNewNick, const vector& vChans);
- virtual void OnKick(const CNick& Nick, const string& sOpNick, const CChan& Channel, const string& sMessage);
- virtual void OnJoin(const CNick& Nick, const CChan& Channel);
- virtual void OnPart(const CNick& Nick, const CChan& Channel);
-
- - - diff --git a/docs/PerlMods.txt b/docs/PerlMods.txt deleted file mode 100644 index 3d98204b..00000000 --- a/docs/PerlMods.txt +++ /dev/null @@ -1,41 +0,0 @@ -Requires the global module g_modperl.so - -- oopish perl modules (man perlobj, also see Example.pm) -- Has all the same callbacks as c++ code, with the same arguments -- special destructor should be used instead of perl DESTROY - - OnShutdown, reason for this is during that destructor the user object - inside g_modperl is available for use - - - -- Builting Sockets - -- includes builtin sock support (see ExampleWithSocks.pm) -- can be used two methods - - method one is directly in your module itself, the sock fd is passed - around for your reference. The sock fd is ALWAYS the first argument - - method two is to instantiate in a new perl class (as used in - ExampleWithSocks.pm) - -- methods receiving callbacks are: - - OnSockDestroy() -- when this sock is being destroyed - - OnConnect( iParentFD ) -- called on the inbound/outbound socket, if this - is created from a listening socket, iParentFD will be > -1 - - OnConnectionFrom( sRemoteHost, iRemotePort ) -- called on the listening - socket when an inbound connection is coming in. If you return anything but - ZNC::CONTINUE, the connection will be denied. - - OnError( iErrorNum ) -- called when an error occurs. errno.h contains valid - error codes - - OnConnectionRefused() -- called when an outbound connection is refused - - OnTimeout() -- called when a connection times out - - OnDisconnect() -- called when a connection is closed - - ReadData( data, len ) -- called when data comes in, len contains the length - of the data being sent in - - ReadLine( line ) -- called when a line (ended by \n) comes down. You must - enable readline when the socket is creatd (via connect or listen) - - NOTE: all of the socket stuff is a basic wrapper around Csocket, and full - documentation can be found at http://csocket.net/docs/annotated.html - - - - diff --git a/docs/UsingCommands.html b/docs/UsingCommands.html deleted file mode 100644 index 60a8b3b4..00000000 --- a/docs/UsingCommands.html +++ /dev/null @@ -1,63 +0,0 @@ - - - - - - -ZNC - Using Commands - - - -[Home] -- -[Project Page] - -
-

-

- Commands -

-

-Commands are given to ZNC by messaging the virtual user *status. Likewise, modules are communicated to by messaging *modname as well. -

-

- Example: /msg *status listmods -

-
- <prozac> listmods
- <*status> +---------+------------------------------------------------------+
- <*status> | Name    | Description                                          |
- <*status> +---------+------------------------------------------------------+
- <*status> | email   | Monitors Email activity on local disk /var/mail/user |
- <*status> | shell   | Gives shell access.                                  |
- <*status> | schat   | Secure cross platform (:P) chat system               |
- <*status> +---------+------------------------------------------------------+
-
-

-The prefix for these virtual users can be changed from * in the znc.conf file. It is wise to use a character that is illegal to use on IRC so that you don't lose the ability to talk to a real person who happens to be using the same prefix on their IRC nick. -

-

- Command List -

-
- <zncuser> help
- <*status> +-----------+---------------------+-------------------------------------+
- <*status> | Command   | Arguments           | Description                         |
- <*status> +-----------+---------------------+-------------------------------------+
- <*status> | ListDCCs  |                     | List all active DCCs                |
- <*status> | ListMods  |                     | List all loaded modules             |
- <*status> | ListChans |                     | List all channels                   |
- <*status> | ListNicks | <#chan>             | List all nicks on a channel         |
- <*status> | Topics    |                     | Show topics in all channels         |
- <*status> | SetBuffer | <#chan> [linecount] | Set the buffer count for a channel  |
- <*status> | Jump      |                     | Jump to the next server in the list |
- <*status> | Send      | <nick> <file>       | Send a shell file to a nick on IRC  |
- <*status> | Get       | <file>              | Send a shell file to yourself       |
- <*status> | LoadMod   | <module>            | Load a module                       |
- <*status> | UnloadMod | <module>            | Unload a module                     |
- <*status> | ReloadMod | <module>            | Reload a module                     |
- <*status> +-----------+---------------------+-------------------------------------+
-
- - - diff --git a/docs/WritingModules.html b/docs/WritingModules.html deleted file mode 100644 index 2d26520c..00000000 --- a/docs/WritingModules.html +++ /dev/null @@ -1,75 +0,0 @@ - - - - - - -ZNC - Writing Modules - - - -[Home] -- -[Project Page] - -
-

-

- Overview -

-
    -
  • Create your own module.cpp file -
  • #include <main.h> and <Modules.h> -
  • Create a new class derived from CModule overriding any ModuleHooks that you need -
  • Be sure to add the macro call MODULEDEFS(CYourClass) at the END of the file -
  • Compile your module into a shared object (.so file) -
      -
    • The easy way to compile is to use the znc-buildmod script as long as your module is a single .cpp file -
        -
      • znc-buildmod example.cpp -
      -
    • alternative is to manually compile using znc-config to ensure that you are using the same flags and libs that the znc engine was compiled with -
        -
      • g++ `znc-config --cflags` `znc-config --include` `znc-config --libs` -shared -o example.so example.cpp -
      -
    -
  • Place the .so file into your ~/.znc/modules directory. You can load it with /msg *status loadmod foo. If you overwrite a .so file while znc has it loaded it can crash znc, /msg *status unloadmod foo first! -
-

- Code -

-
- #include <main.h>
- #include <Modules.h>
-
-
- class CExampleMod : public CModule {
- public:
-     MODCONSTRUCTOR(CExampleMod) {}
-     virtual ~CExampleMod() {}
-
-
-     virtual void OnModCommand(const string& sCommand) {
-         if (strcasecmp(sCommand.c_str(), "HELP") == 0) {
-             PutModule("I'd like to help, but I am just an example");
-         } else {
-             PutModule("Unknown command, try HELP");
-         }
-     }
- };
-
-
- MODULEDEFS(CExampleMod)
-
-

- Output -

-
- <zncuser> test
- <*example> Unknown command, try HELP
- <zncuser> help
- <*example> I'd like to help, but I am just an example
-
- - - diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index f9011441..00000000 --- a/docs/index.html +++ /dev/null @@ -1,50 +0,0 @@ - - - - - - -ZNC - Front Page - - - -[Home] -- -[Project Page] - -
-

-

- ZNC - An advanced IRC bouncer -

-

- Main Features -

-
    -
  • Detaching - ZNC will stay on IRC even while you are offline. -
  • Multiple Users - You can add additional users under one running process. Useful for public shells that limit background processes. -
  • Playback Buffers - Stay up-to-date with what happened while you were detached. -
  • SSL - Encryption for both the listen port and connecting to IRC servers. -
  • DCC Bouncing - Transparent bouncing for DCC anonymity. -
  • C++ Modules - Dynamically loaded shared objects. Just derive from CModule and overload any needed functions such as OnPrivMsg(). IRC scripting in C++, what could be better than that? -
      -
    • shell - Have your unix shell in a query window right inside of your IRC client. -
    • savebuff - Saves your channel buffers into an encrypted file so they can survive restarts and reboots. -
    • email - Monitors email activity on local disk /var/mail/user -
    • schat - SSL (encrypted) DCC chats. -
    • watch - Monitor activity for specific text patterns from specific users and have the text sent to a special query window. -
    • custom - Write your own modules to do whatever you want. -
    -
-

- Using ZNC -

- - - -