1# [![ZNC](http://wiki.znc.in/resources/assets/wiki.png)](http://znc.in) - An advanced IRC bouncer
3[![Travis Build Status](https://img.shields.io/travis/znc/znc/master.svg?label=linux%2Fosx)](https://travis-ci.org/znc/znc)
4[![AppVeyor Build status](https://img.shields.io/appveyor/ci/DarthGandalf/znc/master.svg?label=windows)](https://ci.appveyor.com/project/DarthGandalf/znc/branch/master)
8## Table of contents
10- Minimal Requirements
11- Optional Requirements
12- Installing ZNC
13- Setting up znc.conf
14- Special config options
15- Using ZNC
16- File Locations
17- ZNC's config file
18- Writing own modules
19- Further infos
21## Minimal Requirements
25* GNU make
27* GCC 4.7 or clang 3.2
28* autoconf and automake (if building from git)
30## Optional Requirements
33* openssl 0.9.7d or later
34 * try installing openssl-dev, openssl-devel or libssl-dev
35 * Mac OS X: OpenSSL from Homebrew is prefered over system
38* perl and its bundled libperl
39* SWIG if building from git
42* python and its bundled libpython
43* perl is required
44* Mac OS X: Python from Homebrew is preferred over system version
45* SWIG if building from git
48* This module needs cyrus-sasl2
51* To get proper character encoding and charsets install ICU (`libicu4-dev`)
53## Installing ZNC
55Installation from source code is performed using the `automake` toolchain.
56If you are building from git, you will need to run `./autogen.sh` first to
57produce the `configure` script.
65You can use `./configure --help` if you want to get a list of options, though
66the defaults should be suiting most needs.
68## Setting up znc.conf
70For setting up a configuration file in `~/.znc` you can simply do
71`znc --makeconf` or `./znc --makeconf` for in-place execution.
73If you are using SSL you should do `znc --makepem`
75## Special config options
77When you create your ZNC configuration file via --makeconf, you are asked
78two questions which might not be easy to understand.
80> Number of lines to buffer per channel
82How many messages should be buffered for each channel. When you connect to
83ZNC you get a buffer replay for each channel which shows what was said
84last. This option selects the number of lines this replay should consist
85of. Increasing this can greatly increase ZNC's memory usage if you are
86hosting many users. The default value should be fine for most setups.
88> Would you like to keep buffers after replay?
90If this is disabled, you get the buffer playback only once and then it is
91deleted. If this is enabled, the buffer is not deleted. This may be useful
92if you regularly use more than one client to connect to ZNC.
94## Using ZNC
96Once you have started ZNC you can connect with your favorite IRC-client to
97ZNC. You should use `username:password` as the server password (e.g.
100Once you are connected you can do `/msg *status help` for some commands.
101Every module you have loaded (`/msg *status listmods`) should additionally
102provide `/msg *modulename help`
104## File Locations
106In its data dir (`~/.znc` is default) ZNC saves most of its data. The only
107exception are modules and module data, which are saved in
108`<prefix>/lib/znc` and `<prefix>/share/znc`, and the znc binary itself.
109More modules (e.g. if you install some later) can be saved in
110`<data dir>/modules` (-> `~/.znc/modules`).
112In the datadir is only one file:
114- `znc.pem` - This is the server certificate ZNC uses for listening and is
115created with `znc --makepem`.
117These directories are also in there:
119- configs - Contains `znc.conf` (ZNC's config file) and backups of older
121- modules - ZNC also looks in here for a module.
122- moddata - Global modules save their settings here.
123 (e.g. webadmin saves the current skin name in here)
124- users - This is per-user data and mainly contains just a moddata
127## ZNC's config file
129This file shouldn't be too hard too understand. An explanation of all the
130items can be found on the
132**Warning: better not to edit config, while ZNC is running.** Use the
133[webadmin] and [controlpanel] modules instead.
138If you changed some settings while ZNC is running, a simple
139`pkill -SIGUSR1 znc` will make ZNC rewrite its config file. Alternatively
140you can use `/msg *status saveconfig`
142## Writing own modules
144You can write your own modules in either C++, python or perl.
146C++ modules are compiled by either saving them in the modules source dir
147and running make or with the `znc-buildmod` shell script.
149For additional info look in the wiki:
151- [Writing modules](http://wiki.znc.in/Writing_modules)
153Perl modules are loaded through the global module
156Python modules are loaded through the global module
159## Further infos
161Please visit http://znc.in/ or
162[#znc on freenode](ircs://irc.freenode.net:6697/#znc) if you still have
165You can get the latest development version with git:
166`git clone https://github.com/znc/znc.git --recursive`