]>
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 |
dd42fcd2 | 30 | * CMake |
7a157b26 | 31 | |
9aa1df15 | 32 | ## Optional Requirements |
7a157b26 | 33 | |
a405aadd TK |
34 | SSL/TLS support: |
35 | * openssl 0.9.7d or later | |
36 | * try installing openssl-dev, openssl-devel or libssl-dev | |
c7c878ad | 37 | * macOS: OpenSSL from Homebrew is preferred over system |
54d8cd68 | 38 | |
7a157b26 | 39 | modperl: |
a405aadd TK |
40 | * perl and its bundled libperl |
41 | * SWIG if building from git | |
54d8cd68 US |
42 | |
43 | modpython: | |
9ea9d308 | 44 | * python 3.4+ and its bundled libpython |
9ba1ea46 | 45 | * perl is a build dependency |
c7c878ad | 46 | * macOS: Python from Homebrew is preferred over system version |
a405aadd | 47 | * SWIG if building from git |
54d8cd68 | 48 | |
71df50ec | 49 | cyrusauth: |
a405aadd | 50 | * This module needs cyrus-sasl2 |
54d8cd68 | 51 | |
a405aadd TK |
52 | Character Encodings: |
53 | * To get proper character encoding and charsets install ICU (`libicu4-dev`) | |
7a157b26 | 54 | |
2e31a8ee | 55 | I18N (UI translation) |
2e31a8ee AS |
56 | * Boost.Locale |
57 | * gettext is a build dependency | |
58 | ||
9aa1df15 | 59 | ## Installing ZNC |
7a157b26 | 60 | |
561a1805 AS |
61 | Installation from source code is performed using the CMake toolchain. |
62 | ||
63 | ```shell | |
ece09d11 AS |
64 | mkdir build |
65 | cd build | |
66 | cmake .. | |
561a1805 AS |
67 | make |
68 | make install | |
69 | ``` | |
70 | ||
71 | You can use `cmake-gui` or `ccmake` for more interactiveness. | |
72 | ||
dd42fcd2 AS |
73 | There is also `configure.sh` which should make migration to CMake easier: |
74 | it accepts the same parameters as old `./configure`, | |
75 | but calls CMake with CMake-style parameters. | |
76 | ||
561a1805 AS |
77 | Note for FreeBSD users: |
78 | By default base OpenSSL is selected. | |
79 | If you want the one from ports, use `-DOPENSSL_ROOT_DIR=/usr/local`. | |
80 | ||
81 | For troubleshooting, `cmake --system-information` will show you details. | |
82 | ||
9aa1df15 | 83 | ## Setting up znc.conf |
7a157b26 | 84 | |
e6bff0c3 | 85 | For setting up a configuration file in `~/.znc` you can simply do |
79821695 | 86 | `znc --makeconf` or `./znc --makeconf` for in-place execution. |
7a157b26 | 87 | |
79821695 | 88 | If you are using SSL you should do `znc --makepem` |
7a157b26 | 89 | |
9aa1df15 | 90 | ## Special config options |
b475f5d6 | 91 | |
79821695 MS |
92 | When you create your ZNC configuration file via --makeconf, you are asked |
93 | two questions which might not be easy to understand. | |
b475f5d6 | 94 | |
95 | > Number of lines to buffer per channel | |
e6bff0c3 | 96 | |
79821695 MS |
97 | How many messages should be buffered for each channel. When you connect to |
98 | ZNC you get a buffer replay for each channel which shows what was said | |
99 | last. This option selects the number of lines this replay should consist | |
100 | of. Increasing this can greatly increase ZNC's memory usage if you are | |
101 | hosting many users. The default value should be fine for most setups. | |
b475f5d6 | 102 | |
103 | > Would you like to keep buffers after replay? | |
e6bff0c3 | 104 | |
b475f5d6 | 105 | If this is disabled, you get the buffer playback only once and then it is |
79821695 MS |
106 | deleted. If this is enabled, the buffer is not deleted. This may be useful |
107 | if you regularly use more than one client to connect to ZNC. | |
b475f5d6 | 108 | |
9aa1df15 | 109 | ## Using ZNC |
7a157b26 | 110 | |
79821695 MS |
111 | Once you have started ZNC you can connect with your favorite IRC-client to |
112 | ZNC. You should use `username:password` as the server password (e.g. | |
113 | `/pass user:pass`). | |
7a157b26 | 114 | |
e6bff0c3 | 115 | Once you are connected you can do `/msg *status help` for some commands. |
79821695 MS |
116 | Every module you have loaded (`/msg *status listmods`) should additionally |
117 | provide `/msg *modulename help` | |
7a157b26 | 118 | |
9aa1df15 | 119 | ## File Locations |
7a157b26 | 120 | |
e6bff0c3 | 121 | In its data dir (`~/.znc` is default) ZNC saves most of its data. The only |
79821695 MS |
122 | exception are modules and module data, which are saved in |
123 | `<prefix>/lib/znc` and `<prefix>/share/znc`, and the znc binary itself. | |
7cb4c3fc | 124 | More modules (e.g. if you install some later) can be saved in |
e6bff0c3 | 125 | `<data dir>/modules` (-> `~/.znc/modules`). |
7a157b26 | 126 | |
79821695 | 127 | In the datadir is only one file: |
e6bff0c3 | 128 | |
79821695 MS |
129 | - `znc.pem` - This is the server certificate ZNC uses for listening and is |
130 | created with `znc --makepem`. | |
7a157b26 | 131 | |
132 | These directories are also in there: | |
e6bff0c3 | 133 | |
79821695 MS |
134 | - configs - Contains `znc.conf` (ZNC's config file) and backups of older |
135 | configs. | |
e6bff0c3 KF |
136 | - modules - ZNC also looks in here for a module. |
137 | - moddata - Global modules save their settings here. | |
138 | (e.g. webadmin saves the current skin name in here) | |
79821695 MS |
139 | - users - This is per-user data and mainly contains just a moddata |
140 | directory. | |
7a157b26 | 141 | |
9aa1df15 | 142 | ## ZNC's config file |
7a157b26 | 143 | |
144 | This file shouldn't be too hard too understand. An explanation of all the | |
79821695 | 145 | items can be found on the |
a75ad25a JA |
146 | [Configuration](https://wiki.znc.in/Configuration) page. |
147 | **Warning: it is better not to edit config while ZNC is running.** Use the | |
79821695 | 148 | [webadmin] and [controlpanel] modules instead. |
7a157b26 | 149 | |
10bfece3 AS |
150 | [webadmin]:https://wiki.znc.in/Webadmin |
151 | [controlpanel]:https://wiki.znc.in/Controlpanel | |
7a157b26 | 152 | |
d252a2b4 | 153 | If you changed some settings while ZNC is running, a simple |
79821695 MS |
154 | `pkill -SIGUSR1 znc` will make ZNC rewrite its config file. Alternatively |
155 | you can use `/msg *status saveconfig` | |
c2e87beb | 156 | |
9aa1df15 | 157 | ## Writing own modules |
7a157b26 | 158 | |
8ca1859a | 159 | You can write your own modules in either C++, python or perl. |
7a157b26 | 160 | |
79821695 MS |
161 | C++ modules are compiled by either saving them in the modules source dir |
162 | and running make or with the `znc-buildmod` shell script. | |
7a157b26 | 163 | |
4abf3fea | 164 | For additional info look in the wiki: |
9aa1df15 | 165 | |
10bfece3 | 166 | - [Writing modules](https://wiki.znc.in/Writing_modules) |
7a157b26 | 167 | |
79821695 | 168 | Perl modules are loaded through the global module |
10bfece3 | 169 | [ModPerl](https://wiki.znc.in/Modperl). |
6a2b5a23 | 170 | |
79821695 | 171 | Python modules are loaded through the global module |
10bfece3 | 172 | [ModPython](https://wiki.znc.in/Modpython). |
7a157b26 | 173 | |
a75ad25a | 174 | ## Further information |
7a157b26 | 175 | |
a75ad25a JA |
176 | Please visit https://znc.in/ or #znc on freenode if you still have questions: |
177 | - [freenode webchat](https://webchat.freenode.net/?nick=znc_....&channels=znc) | |
178 | - [ircs://irc.freenode.net:6697/znc](ircs://irc.freenode.net:6697/znc) | |
7a157b26 | 179 | |
ed178040 | 180 | You can get the latest development version with git: |
79821695 | 181 | `git clone https://github.com/znc/znc.git --recursive` |