]>
Commit | Line | Data |
---|---|---|
10bfece3 | 1 | # [![ZNC](https://wiki.znc.in/resources/assets/wiki.png)](https://znc.in) - An advanced IRC bouncer |
f63c3131 | 2 | |
c7c878ad | 3 | [![Travis Build Status](https://img.shields.io/travis/znc/znc/master.svg?label=linux%2Fmacos)](https://travis-ci.org/znc/znc) |
98a1a2dd | 4 | [![Jenkins Build Status](https://img.shields.io/jenkins/s/https/jenkins.znc.in/job/znc/job/znc/job/master.svg?label=freebsd)](https://jenkins.znc.in/job/znc/job/znc/job/master/) |
bc77cf79 | 5 | [![AppVeyor Build status](https://img.shields.io/appveyor/ci/DarthGandalf/znc/master.svg?label=windows)](https://ci.appveyor.com/project/DarthGandalf/znc/branch/master) |
f63c3131 | 6 | [![Bountysource](https://www.bountysource.com/badge/tracker?tracker_id=1759)](https://www.bountysource.com/trackers/1759-znc?utm_source=1759&utm_medium=shield&utm_campaign=TRACKER_BADGE) |
f1c721ce | 7 | [![Coverage Status](https://img.shields.io/codecov/c/github/znc/znc.svg)](https://codecov.io/gh/znc/znc) |
b17481b7 | 8 | [![Coverity Scan Build Status](https://img.shields.io/coverity/scan/6778.svg)](https://scan.coverity.com/projects/znc-coverity) |
9aa1df15 U |
9 | |
10 | ## Table of contents | |
e6bff0c3 | 11 | |
a75ad25a JA |
12 | - [Minimal Requirements](#minimal-requirements) |
13 | - [Optional Requirements](#optional-requirements) | |
14 | - [Installing ZNC](#installing-znc) | |
15 | - [Setting up znc.conf](#setting-up-zncconf) | |
16 | - [Special config options](#special-config-options) | |
17 | - [Using ZNC](#using-znc) | |
18 | - [File Locations](#file-locations) | |
19 | - [ZNC's config file](#zncs-config-file) | |
20 | - [Writing own modules](#writing-own-modules) | |
21 | - [Further information](#further-information) | |
7a157b26 | 22 | |
9aa1df15 | 23 | ## Minimal Requirements |
7a157b26 | 24 | |
25 | Core: | |
e6bff0c3 | 26 | |
a405aadd TK |
27 | * GNU make |
28 | * pkg-config | |
d2fb2283 | 29 | * GCC 4.8 or clang 3.2 |
561a1805 AS |
30 | * Either of: |
31 | * autoconf and automake (but only if building from git, not from tarball) | |
32 | * CMake | |
7a157b26 | 33 | |
9aa1df15 | 34 | ## Optional Requirements |
7a157b26 | 35 | |
a405aadd TK |
36 | SSL/TLS support: |
37 | * openssl 0.9.7d or later | |
38 | * try installing openssl-dev, openssl-devel or libssl-dev | |
c7c878ad | 39 | * macOS: OpenSSL from Homebrew is preferred over system |
54d8cd68 | 40 | |
7a157b26 | 41 | modperl: |
a405aadd TK |
42 | * perl and its bundled libperl |
43 | * SWIG if building from git | |
54d8cd68 US |
44 | |
45 | modpython: | |
5b5ab5cf | 46 | * python 3.3+ and its bundled libpython |
9ba1ea46 | 47 | * perl is a build dependency |
c7c878ad | 48 | * macOS: Python from Homebrew is preferred over system version |
a405aadd | 49 | * SWIG if building from git |
54d8cd68 | 50 | |
71df50ec | 51 | cyrusauth: |
a405aadd | 52 | * This module needs cyrus-sasl2 |
54d8cd68 | 53 | |
a405aadd TK |
54 | Character Encodings: |
55 | * To get proper character encoding and charsets install ICU (`libicu4-dev`) | |
7a157b26 | 56 | |
2e31a8ee AS |
57 | I18N (UI translation) |
58 | * CMake-based build only | |
59 | * Boost.Locale | |
60 | * gettext is a build dependency | |
61 | ||
9aa1df15 | 62 | ## Installing ZNC |
7a157b26 | 63 | |
561a1805 AS |
64 | Currently there are 2 build systems in place: CMake and `./configure`. |
65 | `./configure` will eventually be removed. | |
e95f0ea6 | 66 | There is also `configure.sh` which should make migration to CMake easier: |
561a1805 AS |
67 | it accepts the same parameters as `./configure`, |
68 | but calls CMake with CMake-style parameters. | |
69 | ||
70 | ### Installing with CMake | |
71 | ||
72 | Installation from source code is performed using the CMake toolchain. | |
73 | ||
74 | ```shell | |
ece09d11 AS |
75 | mkdir build |
76 | cd build | |
77 | cmake .. | |
561a1805 AS |
78 | make |
79 | make install | |
80 | ``` | |
81 | ||
82 | You can use `cmake-gui` or `ccmake` for more interactiveness. | |
83 | ||
84 | Note for FreeBSD users: | |
85 | By default base OpenSSL is selected. | |
86 | If you want the one from ports, use `-DOPENSSL_ROOT_DIR=/usr/local`. | |
87 | ||
88 | For troubleshooting, `cmake --system-information` will show you details. | |
89 | ||
90 | ### Installing with `./configure` | |
91 | ||
9242307f | 92 | Installation from source code is performed using the `automake` toolchain. |
79821695 | 93 | If you are building from git, you will need to run `./autogen.sh` first to |
9242307f | 94 | produce the `configure` script. |
991e7f2f | 95 | |
a405aadd | 96 | ```shell |
ece09d11 AS |
97 | mkdir build |
98 | cd build | |
99 | ../configure | |
a405aadd TK |
100 | make |
101 | make install | |
102 | ``` | |
de99f5b1 | 103 | |
9242307f N |
104 | You can use `./configure --help` if you want to get a list of options, though |
105 | the defaults should be suiting most needs. | |
7a157b26 | 106 | |
9aa1df15 | 107 | ## Setting up znc.conf |
7a157b26 | 108 | |
e6bff0c3 | 109 | For setting up a configuration file in `~/.znc` you can simply do |
79821695 | 110 | `znc --makeconf` or `./znc --makeconf` for in-place execution. |
7a157b26 | 111 | |
79821695 | 112 | If you are using SSL you should do `znc --makepem` |
7a157b26 | 113 | |
9aa1df15 | 114 | ## Special config options |
b475f5d6 | 115 | |
79821695 MS |
116 | When you create your ZNC configuration file via --makeconf, you are asked |
117 | two questions which might not be easy to understand. | |
b475f5d6 | 118 | |
119 | > Number of lines to buffer per channel | |
e6bff0c3 | 120 | |
79821695 MS |
121 | How many messages should be buffered for each channel. When you connect to |
122 | ZNC you get a buffer replay for each channel which shows what was said | |
123 | last. This option selects the number of lines this replay should consist | |
124 | of. Increasing this can greatly increase ZNC's memory usage if you are | |
125 | hosting many users. The default value should be fine for most setups. | |
b475f5d6 | 126 | |
127 | > Would you like to keep buffers after replay? | |
e6bff0c3 | 128 | |
b475f5d6 | 129 | If this is disabled, you get the buffer playback only once and then it is |
79821695 MS |
130 | deleted. If this is enabled, the buffer is not deleted. This may be useful |
131 | if you regularly use more than one client to connect to ZNC. | |
b475f5d6 | 132 | |
9aa1df15 | 133 | ## Using ZNC |
7a157b26 | 134 | |
79821695 MS |
135 | Once you have started ZNC you can connect with your favorite IRC-client to |
136 | ZNC. You should use `username:password` as the server password (e.g. | |
137 | `/pass user:pass`). | |
7a157b26 | 138 | |
e6bff0c3 | 139 | Once you are connected you can do `/msg *status help` for some commands. |
79821695 MS |
140 | Every module you have loaded (`/msg *status listmods`) should additionally |
141 | provide `/msg *modulename help` | |
7a157b26 | 142 | |
9aa1df15 | 143 | ## File Locations |
7a157b26 | 144 | |
e6bff0c3 | 145 | In its data dir (`~/.znc` is default) ZNC saves most of its data. The only |
79821695 MS |
146 | exception are modules and module data, which are saved in |
147 | `<prefix>/lib/znc` and `<prefix>/share/znc`, and the znc binary itself. | |
7cb4c3fc | 148 | More modules (e.g. if you install some later) can be saved in |
e6bff0c3 | 149 | `<data dir>/modules` (-> `~/.znc/modules`). |
7a157b26 | 150 | |
79821695 | 151 | In the datadir is only one file: |
e6bff0c3 | 152 | |
79821695 MS |
153 | - `znc.pem` - This is the server certificate ZNC uses for listening and is |
154 | created with `znc --makepem`. | |
7a157b26 | 155 | |
156 | These directories are also in there: | |
e6bff0c3 | 157 | |
79821695 MS |
158 | - configs - Contains `znc.conf` (ZNC's config file) and backups of older |
159 | configs. | |
e6bff0c3 KF |
160 | - modules - ZNC also looks in here for a module. |
161 | - moddata - Global modules save their settings here. | |
162 | (e.g. webadmin saves the current skin name in here) | |
79821695 MS |
163 | - users - This is per-user data and mainly contains just a moddata |
164 | directory. | |
7a157b26 | 165 | |
9aa1df15 | 166 | ## ZNC's config file |
7a157b26 | 167 | |
168 | This file shouldn't be too hard too understand. An explanation of all the | |
79821695 | 169 | items can be found on the |
a75ad25a JA |
170 | [Configuration](https://wiki.znc.in/Configuration) page. |
171 | **Warning: it is better not to edit config while ZNC is running.** Use the | |
79821695 | 172 | [webadmin] and [controlpanel] modules instead. |
7a157b26 | 173 | |
10bfece3 AS |
174 | [webadmin]:https://wiki.znc.in/Webadmin |
175 | [controlpanel]:https://wiki.znc.in/Controlpanel | |
7a157b26 | 176 | |
d252a2b4 | 177 | If you changed some settings while ZNC is running, a simple |
79821695 MS |
178 | `pkill -SIGUSR1 znc` will make ZNC rewrite its config file. Alternatively |
179 | you can use `/msg *status saveconfig` | |
c2e87beb | 180 | |
9aa1df15 | 181 | ## Writing own modules |
7a157b26 | 182 | |
8ca1859a | 183 | You can write your own modules in either C++, python or perl. |
7a157b26 | 184 | |
79821695 MS |
185 | C++ modules are compiled by either saving them in the modules source dir |
186 | and running make or with the `znc-buildmod` shell script. | |
7a157b26 | 187 | |
4abf3fea | 188 | For additional info look in the wiki: |
9aa1df15 | 189 | |
10bfece3 | 190 | - [Writing modules](https://wiki.znc.in/Writing_modules) |
7a157b26 | 191 | |
79821695 | 192 | Perl modules are loaded through the global module |
10bfece3 | 193 | [ModPerl](https://wiki.znc.in/Modperl). |
6a2b5a23 | 194 | |
79821695 | 195 | Python modules are loaded through the global module |
10bfece3 | 196 | [ModPython](https://wiki.znc.in/Modpython). |
7a157b26 | 197 | |
a75ad25a | 198 | ## Further information |
7a157b26 | 199 | |
a75ad25a JA |
200 | Please visit https://znc.in/ or #znc on freenode if you still have questions: |
201 | - [freenode webchat](https://webchat.freenode.net/?nick=znc_....&channels=znc) | |
202 | - [ircs://irc.freenode.net:6697/znc](ircs://irc.freenode.net:6697/znc) | |
7a157b26 | 203 | |
ed178040 | 204 | You can get the latest development version with git: |
79821695 | 205 | `git clone https://github.com/znc/znc.git --recursive` |