README.md

   1 #[![ZNC](http://wiki.znc.in/skins/common/images/wiki.png)](http://znc.in) - An advanced IRC bouncer
   2
   3 ## Table of contents
   4
   5 - Minimal Requirements
   6 - Optional Requirements
   7 - Installing ZNC
   8 - Setting up znc.conf
   9 - Special config options
  10 - Using ZNC
  11 - File Locations
  12 - ZNC's config file
  13 - Writing own modules
  14 - Further infos
  15
  16 ## Minimal Requirements
  17
  18 Core:
  19
  20  - GNU make (try gmake if make fails)
  21  - GCC 4 or later
  22
  23 ## Optional Requirements
  24
  25 SSL support:
  26
  27  - openssl 0.9.7d or later (try installing openssl-dev, openssl-devel or
  28    libssl-dev)
  29
  30 modperl:
  31
  32  - This needs perl and its bundled libperl
  33
  34 modpython:
  35
  36  - This needs perl(!) and python's bundled libpython
  37
  38 cyrusauth:
  39
  40  - This module needs cyrus-sasl2
  41
  42 ## Installing ZNC
  43
  44 If you are building from git, you will need to run `./autogen.sh` first to
  45 produce the `configure` script. Note that this requires `automake` and
  46 `gettext` to be installed.
  47
  48 Installation is done with the `./configure ; make ; make install` commands.
  49
  50 You can use `./configure --help` if you want to get a list of options,
  51 though the defaults should be suiting most needs. After you compiled it
  52 with make (or gmake if make doesn't work) you can install it with
  53 `make install`.
  54
  55 ## Setting up znc.conf
  56
  57 For setting up a configuration file in `~/.znc` you can simply do
  58 `znc --makeconf` or `./znc --makeconf` for in-place execution.
  59
  60 If you are using SSL you should do `znc --makepem`
  61
  62 ## Special config options
  63
  64 When you create your ZNC configuration file via --makeconf, you are asked
  65 two questions which might not be easy to understand.
  66
  67 > Number of lines to buffer per channel
  68
  69 How many messages should be buffered for each channel. When you connect to
  70 ZNC you get a buffer replay for each channel which shows what was said
  71 last. This option selects the number of lines this replay should consist
  72 of. Increasing this can greatly increase ZNC's memory usage if you are
  73 hosting many users. The default value should be fine for most setups.
  74
  75 > Would you like to keep buffers after replay?
  76
  77 If this is disabled, you get the buffer playback only once and then it is
  78 deleted. If this is enabled, the buffer is not deleted. This may be useful
  79 if you regularly use more than one client to connect to ZNC.
  80
  81 ## Using ZNC
  82
  83 Once you have started ZNC you can connect with your favorite IRC-client to
  84 ZNC. You should use `username:password` as the server password (e.g.
  85 `/pass user:pass`).
  86
  87 Once you are connected you can do `/msg *status help` for some commands.
  88 Every module you have loaded (`/msg *status listmods`) should additionally
  89 provide `/msg *modulename help`
  90
  91 ## File Locations
  92
  93 In its data dir (`~/.znc` is default) ZNC saves most of its data. The only
  94 exception are modules and module data, which are saved in
  95 `<prefix>/lib/znc` and `<prefix>/share/znc`, and the znc binary itself.
  96 More modules (e.g. if you install some later) can be saved in
  97 `<data dir>/modules` (-> `~/.znc/modules`).
  98
  99 In the datadir is only one file:
 100
 101 - `znc.pem` - This is the server certificate ZNC uses for listening and is
 102 created with `znc --makepem`.
 103
 104 These directories are also in there:
 105
 106 - configs - Contains `znc.conf` (ZNC's config file) and backups of older
 107   configs.
 108 - modules - ZNC also looks in here for a module.
 109 - moddata - Global modules save their settings here.
 110   (e.g. webadmin saves the current skin name in here)
 111 - users   - This is per-user data and mainly contains just a moddata
 112   directory.
 113
 114 ## ZNC's config file
 115
 116 This file shouldn't be too hard too understand. An explanation of all the
 117 items can be found on the
 118 [Configuration](http://wiki.znc.in/Configuration)-Page.
 119 **Warning: better not to edit config, while ZNC is running.** Use  the
 120 [webadmin] and [controlpanel] modules instead.
 121
 122 [webadmin]:http://wiki.znc.in/Webadmin
 123 [controlpanel]:http://wiki.znc.in/Controlpanel
 124
 125 If you changed some settings while ZNC is running, a simple
 126 `pkill -SIGUSR1 znc` will make ZNC rewrite its config file. Alternatively
 127 you can use `/msg *status saveconfig`
 128
 129 ## Writing own modules
 130
 131 You can write your own modules in either C++, python or perl.
 132
 133 C++ modules are compiled by either saving them in the modules source dir
 134 and running make or with the `znc-buildmod` shell script.
 135
 136 For additional info look in the wiki:
 137
 138 - [Writing modules](http://wiki.znc.in/Writing_modules)
 139
 140 Perl modules are loaded through the global module
 141 [ModPerl](http://wiki.znc.in/Modperl).
 142
 143 Python modules are loaded through the global module
 144 [ModPython](http://wiki.znc.in/Modpython).
 145
 146 ## Further infos
 147
 148 Please visit http://znc.in/ or
 149 [#znc on freenode](ircs://irc.freenode.net:6697/#znc) if you still have
 150 questions.
 151
 152 You can get the latest development version with git:
 153 `git clone https://github.com/znc/znc.git --recursive`