[solanum.git] / README.md

# charybdis [![POSIX Build Status](https://travis-ci.org/charybdis-ircd/charybdis.svg?branch=master)](https://travis-ci.org/charybdis-ircd/charybdis) [![Windows Build Status](https://ci.appveyor.com/api/projects/status/is0obsml8xyq2qk7/branch/master?svg=true)](https://ci.appveyor.com/project/kaniini/charybdis/branch/master)

Charybdis is an IRCv3 server designed to be highly scalable.  It implements IRCv3.1 and some parts of IRCv3.2.

It is meant to be used with an IRCv3-capable services implementation such as [Atheme][atheme] or [Anope][anope].

   [atheme]: http://www.atheme.net/
   [anope]: http://www.anope.org/

# necessary requirements

 * A supported platform
 * A working dynamic library system
 * A working lex and yacc - flex and bison should work

# platforms

Charybdis is designed with portability in mind, but does not target older systems nor those of solely academic
interest.

Do note that operating systems are only supported if they are supported by their vendor.

## Tier 1

These platforms are the best supported, and should always work. They are actively tested. If you encounter
problems, please file a bug.

* FreeBSD 10.x and above (i386 and amd64)
* Linux 2.6.x and above with glibc or musl (i386, x86_64, and ARM)
* Mac OS X 10.7 and above
* Windows Vista/Server 2008 and above (x86 or x64)

## Tier 2

These platforms are supported and occasionally tested, and most features should work, but this is not
guaranteed. If you find any problems, file a bug, but as these are not regularly tested platforms, a timely
resolution may not be possible.

* DragonflyBSD 4.4 and above (i386)
* Linux with uClibc (i386 or x86_64)
* NetBSD 6.1.x and above (i386, amd64)
* OpenBSD 5.6 and above (i386, amd64)
* Solaris 10 and above (i386)

## Tier 3

Anything else that hasn't been tested. Charybdis may or may not work on it; patches welcome if they don't.

# platform specific errata

These are known issues and workarounds for supported platforms.

 * **Mac OS X and macOS **: you must set the LIBTOOLIZE environment
   variable to point to glibtoolize before running autogen.sh:
   `$ brew install libtool`
   `$ LIBTOOLIZE="/opt/local/bin/glibtoolize"`
   `$ export LIBTOOLIZE`
   `$ ./autogen.sh`

 * **FreeBSD**: if you are compiling with ipv6 you may experience
   problems with ipv4 due to the way the socket code is written.  To
   fix this you must: "sysctl net.inet6.ip6.v6only=0"

 * **Solaris**: you may have to set your PATH to include /usr/gnu/bin and /usr/gnu/sbin before /usr/bin
   and /usr/sbin. Solaris's default tools don't seem to play nicely with the configure script.

# building from git

We no longer supply a prebuilt configure script in git, due to use of automake and libtool causing problems.
You will need to run `autogen.sh` to build the autotools files prior to building charybdis.

# feature specific requirements

 * For SSL/TLS client and server connections, one of:

   * OpenSSL 1.0.0 or newer (--enable-openssl)
   * LibreSSL (--enable-openssl)
   * mbedTLS (--enable-mbedtls)
   * GnuTLS (--enable-gnutls)

 * For certificate-based oper CHALLENGE, OpenSSL 1.0.0 or newer.
   (Using CHALLENGE is not recommended for new deployments, so if you want to use a different TLS library,
    feel free.)

 * For ECDHE under OpenSSL, on Solaris and RHEL/Fedora (and its derivatives such as CentOS) you will
   need to compile your own OpenSSL on these systems, as they have removed support for ECC/ECDHE.
   Alternatively, consider using another library (see above).

# tips

 * To report bugs in charybdis, visit us at irc.charybdis.io #charybdis

 * Please read doc/index.txt to get an overview of the current documentation.

 * Read the NEWS file for what's new in this release.

 * The files, /etc/services, /etc/protocols, and /etc/resolv.conf, SHOULD be
   readable by the user running the server in order for ircd to start with
   the correct settings.  If these files are wrong, charybdis will try to use
   127.0.0.1 for a resolver as a last-ditch effort.

# git access

 * The Charybdis GIT repository can be checked out using the following command:
	`git clone https://github.com/charybdis-ircd/charybdis`

 * Charybdis's GIT repository depot can be browsed over the Internet at the following address:
	https://github.com/charybdis-ircd/charybdis
Commit	Line	Data
427ed8ea	1	# charybdis [![POSIX Build Status](https://travis-ci.org/charybdis-ircd/charybdis.svg?branch=master)](https://travis-ci.org/charybdis-ircd/charybdis) [![Windows Build Status](https://ci.appveyor.com/api/projects/status/is0obsml8xyq2qk7/branch/master?svg=true)](https://ci.appveyor.com/project/kaniini/charybdis/branch/master)
67603230	2
be9fb5ac	3	Charybdis is an IRCv3 server designed to be highly scalable. It implements IRCv3.1 and some parts of IRCv3.2.
41976628	4
be9fb5ac	5	It is meant to be used with an IRCv3-capable services implementation such as [Atheme][atheme] or [Anope][anope].
67603230 AC	6
	7	[atheme]: http://www.atheme.net/
	8	[anope]: http://www.anope.org/
	9
	10	# necessary requirements
	11
	12	* A supported platform
fcf13f6d EM	13	* A working dynamic library system
	14	* A working lex and yacc - flex and bison should work
	15
	16	# platforms
	17
	18	Charybdis is designed with portability in mind, but does not target older systems nor those of solely academic
	19	interest.
	20
	21	Do note that operating systems are only supported if they are supported by their vendor.
	22
	23	## Tier 1
	24
	25	These platforms are the best supported, and should always work. They are actively tested. If you encounter
	26	problems, please file a bug.
	27
	28	* FreeBSD 10.x and above (i386 and amd64)
	29	* Linux 2.6.x and above with glibc or musl (i386, x86_64, and ARM)
	30	* Mac OS X 10.7 and above
	31	* Windows Vista/Server 2008 and above (x86 or x64)
	32
	33	## Tier 2
	34
61566826 EM	35	These platforms are supported and occasionally tested, and most features should work, but this is not
	36	guaranteed. If you find any problems, file a bug, but as these are not regularly tested platforms, a timely
	37	resolution may not be possible.
fcf13f6d EM	38
	39	* DragonflyBSD 4.4 and above (i386)
	40	* Linux with uClibc (i386 or x86_64)
	41	* NetBSD 6.1.x and above (i386, amd64)
	42	* OpenBSD 5.6 and above (i386, amd64)
	43	* Solaris 10 and above (i386)
	44
	45	## Tier 3
	46
61566826	47	Anything else that hasn't been tested. Charybdis may or may not work on it; patches welcome if they don't.
fcf13f6d EM	48
	49	# platform specific errata
	50
	51	These are known issues and workarounds for supported platforms.
	52
19ec5fb1 AJ	53	* Mac OS X and macOS : you must set the LIBTOOLIZE environment
	54	variable to point to glibtoolize before running autogen.sh:
	55	`$ brew install libtool`
	56	`$ LIBTOOLIZE="/opt/local/bin/glibtoolize"`
	57	`$ export LIBTOOLIZE`
	58	`$ ./autogen.sh`
	59
fcf13f6d EM	60	* FreeBSD: if you are compiling with ipv6 you may experience
	61	problems with ipv4 due to the way the socket code is written. To
	62	fix this you must: "sysctl net.inet6.ip6.v6only=0"
	63
	64	* Solaris: you may have to set your PATH to include /usr/gnu/bin and /usr/gnu/sbin before /usr/bin
	65	and /usr/sbin. Solaris's default tools don't seem to play nicely with the configure script.
67603230	66
0409e18f AC	67	# building from git
	68
	69	We no longer supply a prebuilt configure script in git, due to use of automake and libtool causing problems.
	70	You will need to run `autogen.sh` to build the autotools files prior to building charybdis.
	71
67603230 AC	72	# feature specific requirements
67603230 AC	73
354fd351 AC	74	* For SSL/TLS client and server connections, one of:
354fd351 AC	75
fd9f6521 AJ	76	* OpenSSL 1.0.0 or newer (--enable-openssl)
	77	* LibreSSL (--enable-openssl)
	78	* mbedTLS (--enable-mbedtls)
	79	* GnuTLS (--enable-gnutls)
354fd351	80
fd9f6521	81	* For certificate-based oper CHALLENGE, OpenSSL 1.0.0 or newer.
354fd351 AC	82	(Using CHALLENGE is not recommended for new deployments, so if you want to use a different TLS library,
354fd351 AC	83	feel free.)
67603230	84
fd9f6521 AJ	85	* For ECDHE under OpenSSL, on Solaris and RHEL/Fedora (and its derivatives such as CentOS) you will
	86	need to compile your own OpenSSL on these systems, as they have removed support for ECC/ECDHE.
	87	Alternatively, consider using another library (see above).
67603230 AC	88
	89	# tips
	90
d7f66fc3	91	* To report bugs in charybdis, visit us at irc.charybdis.io #charybdis
67603230 AC	92
	93	* Please read doc/index.txt to get an overview of the current documentation.
	94
fcf13f6d EM	95	* Read the NEWS file for what's new in this release.
fcf13f6d EM	96
67603230 AC	97	* The files, /etc/services, /etc/protocols, and /etc/resolv.conf, SHOULD be
	98	readable by the user running the server in order for ircd to start with
	99	the correct settings. If these files are wrong, charybdis will try to use
	100	127.0.0.1 for a resolver as a last-ditch effort.
	101
238db377 EM	102	# git access
	103
	104	* The Charybdis GIT repository can be checked out using the following command:
3eb5fee4	105	`git clone https://github.com/charybdis-ircd/charybdis`
238db377 EM	106
	107	* Charybdis's GIT repository depot can be browsed over the Internet at the following address:
	108	https://github.com/charybdis-ircd/charybdis