Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ngircd.conf(5)			 ngIRCd	Manual			ngircd.conf(5)

       ngircd.conf - configuration file	of ngIRCd


       ngircd.conf  is	the configuration file of the ngircd(8)	Internet Relay
       Chat (IRC) daemon, which	must be	customized to  the  local  preferences
       and needs.

       Most  variables can be modified while the ngIRCd	daemon is already run-
       ning: It	will reload its	configuration file when	a HUP signal or	REHASH
       command is received.

       The file	consists of sections and parameters. A section begins with the
       name of the section in square brackets and  continues  until  the  next
       section begins.

       Sections	contain	parameters of the form

	      name = value

       Empty  lines  and  any  line beginning with a semicolon (';') or	a hash
       ('#') character are treated as a	comment	and will be  ignored.  Leading
       and trailing whitespaces	are trimmed before any processing takes	place.

       The file	format is line-based - that means, each	non-empty newline-ter-
       minated line represents either a	comment, a section name, or a  parame-

       Section and parameter names are not case	sensitive.

       There  are  three  types	of variables: booleans,	text strings, and num-
       bers.  Boolean values are true if they are "yes", "true", or  any  non-
       null  integer.  Text strings are	used 1:1 without leading and following
       spaces; there is	no way to quote	strings. And for numbers  all  decimal
       integer values are valid.

       In addition, some string	or numerical variables accept lists of values,
       separated by commas (",").

       The file	can contain blocks of seven types:  [Global],  [Limits],  [Op-
       tions], [SSL], [Operator], [Server], and	[Channel].

       The main	configuration of the server is stored in the [Global] section,
       like the	server name, administrative information	and the	ports on which
       the  server  should be listening. The variables in this section have to
       be adjusted to the local	requirements most of the time, whereas all the
       variables  in the other sections	can be left on their defaults very of-

       Options in the [Limits] block are used to tweak	different  limits  and
       timeouts	 of  the daemon, like the maximum number of clients allowed to
       connect to this server. Variables in the	[Options] section can be  used
       to  enable  or  disable	specific  features of ngIRCd, like support for
       IDENT, PAM, IPv6, and protocol and cloaking features. The  [SSL]	 block
       contains	 all SSL-related configuration variables. These	three sections
       are all optional.

       IRC operators of	this server are	defined	in [Operator] blocks. Links to
       remote  servers	are  configured	 in  [Server]  sections. And [Channel]
       blocks are used to configure pre-defined	("persistent") IRC channels.

       There can be more than one [Operator], [Server] and  [Channel]  section
       per  configuration  file,  one  for each	operator, server, and channel.
       [Global], [Limits], [Options], and [SSL]	sections  can  occur  multiple
       times,  too, but	each variable overwrites itself, only the last assign-
       ment is relevant.

       The [Global] section is used to define the main	configuration  of  the
       server,	like  the server name and the ports on which the server	should
       be listening.  These settings depend on your personal  preferences,  so
       you  should  make  sure	that  they correspond to your installation and

       Name (string; required)
	      Server name in the IRC network. This is an  individual  name  of
	      the  IRC server, it is not related to the	DNS host name. It must
	      be unique	in the IRC network and must contain at least  one  dot
	      (".") character.

       AdminInfo1, AdminInfo2, AdminEMail (string)
	      Information  about the server and	the administrator, used	by the
	      ADMIN command. This information is not required  by  the	server
	      but by RFC!

       HelpFile	(string)
	      Text  file which contains	the ngIRCd help	text. This file	is re-
	      quired to	display	help texts when	using the  "HELP  <cmd>"  com-
	      mand.   Please  note: Changes made to this file take effect when
	      ngircd starts up or is instructed	to re-read  its	 configuration

       Info (string)
	      Info  text  of the server. This will be shown by WHOIS and LINKS
	      requests for example.

       Listen (list of strings)
	      A	comma separated	list of	IP address on which the	server	should
	      listen.  If unset, the defaults value is "" or, if	ngIRCd
	      was compiled with	IPv6 support, "::,". So the server lis-
	      tens on all configured IP	addresses and interfaces by default.

       MotdFile	(string)
	      Text  file  with	the  "message of the day" (MOTD). This message
	      will be shown to all users  connecting  to  the  server.	Please
	      note:  Changes  made to this file	take effect when ngircd	starts
	      up or is instructed to re-read its configuration file.

       MotdPhrase (string)
	      A	simple Phrase (<127 chars) if you don't	want  to  use  a  MOTD

       Network (string)
	      The  name	 of the	IRC network to which this server belongs. This
	      name is optional,	should	only  contain  ASCII  characters,  and
	      can't  contain  spaces.	It is only used	to inform clients. The
	      default is empty,	so no network name is announced	to clients.

       Password	(string)
	      Global password for all users needed to connect to  the  server.
	      The  default  is empty, so no password is	required. Please note:
	      This feature is not available if ngIRCd is using PAM!

       PidFile (string)
	      This tells ngIRCd	to write its current process  ID  to  a	 file.
	      Note  that  the "PID file" is written AFTER chroot and switching
	      the user ID, therefore the directory the file resides in must be
	      writable	by  the	 ngIRCd	user and exist in the chroot directory
	      (if configured, see above).

       Ports (list of numbers)
	      Port number(s) on	which the server should	listen for unencrypted
	      connections.   There  may	 be more than one port,	separated with
	      commas (","). Default: 6667.

       ServerGID (string or number)
	      Group ID under which the ngIRCd daemon should run; you  can  use
	      the name of the group or the numerical ID.

	      For  this	 to  work  the server must have	been started with root

       ServerUID (string or number)
	      User ID under which the ngIRCd daemon should run;	 you  can  use
	      the name of the user or the numerical ID.

	      For  this	 to  work  the server must have	been started with root
	      privileges! In addition, the configuration and MOTD  files  must
	      be  readable  by	this  user, otherwise RESTART and REHASH won't

       This section is used to define some limits and timeouts for this	ngIRCd
       instance. Default values	should be safe,	but it is wise to double-check

       ConnectRetry (number)
	      The server tries every <ConnectRetry>  seconds  to  establish  a
	      link to not yet (or no longer) connected servers.	Default: 60.

       IdleTimeout (number)
	      Number  of  seconds after	which the whole	daemon should shutdown
	      when no connections are left active after	handling at least  one
	      client (0: never). This can be useful for	testing	or when	ngIRCd
	      is started using "socket activation" with	systemd(8), for	 exam-
	      ple. Default: 0.

       MaxConnections (number)
	      Maximum  number of simultaneous in- and outbound connections the
	      server is	allowed	to accept (0: unlimited). Default: 0.

       MaxConnectionsIP	(number)
	      Maximum number of	simultaneous connections from a	single IP  ad-
	      dress  that the server will accept (0: unlimited). This configu-
	      ration options lowers the	risk  of  denial  of  service  attacks
	      (DoS). Default: 5.

       MaxJoins	(number)
	      Maximum  number  of  channels  a	user  can  be member of	(0: no
	      limit).  Default:	10.

       MaxNickLength (number)
	      Maximum length of	an user	nickname (Default: 9, as in RFC	2812).
	      Please note that all servers in an IRC network MUST use the same
	      maximum nickname length!

       MaxPenaltyTime (number)
	      Maximum penalty time increase in seconds,	per penalty event. Set
	      to  -1  for no limit (the	default), 0 to disable penalties alto-
	      gether. ngIRCd doesn't use penalty increases higher than 2  sec-
	      onds  during  normal  operation, so values greater than 1	rarely
	      make sense.

       MaxListSize (number)
	      Maximum number of	channels returned in response to a  LIST  com-
	      mand. Default: 100.

       PingTimeout (number)
	      After <PingTimeout> seconds of inactivity	the server will	send a
	      PING to the peer to test whether it is alive  or	not.  Default:

       PongTimeout (number)
	      If a client fails	to answer a PING with a	PONG within <PongTime-
	      out> seconds, it will be disconnected by	the  server.  Default:

       Optional	features and configuration options to further tweak the	behav-
       ior of ngIRCd are configured in	this  section.	If  you	 want  to  get
       started	quickly,  you most probably don't have to make changes here --
       they are	all optional.

       AllowedChannelTypes (string)
	      List of allowed channel types (channel prefixes) for newly  cre-
	      ated  channels  on  the  local server. By	default, all supported
	      channel types are	allowed.   Set	this  variable	to  the	 empty
	      string  to disallow creation of new channels by local clients at
	      all. Default: #&+

       AllowRemoteOper (boolean)
	      If this option is	active,	 IRC  operators	 connected  to	remote
	      servers  are allowed to control this local server	using adminis-
	      trative commands,	for example like CONNECT, DIE, SQUIT etc.  De-
	      fault: no.

       ChrootDir (string)
	      A	 directory  to	chroot	in  when everything is initialized. It
	      doesn't need to be populated if ngIRCd is	compiled as  a	static
	      binary. By default ngIRCd	won't use the chroot() feature.

	      For  this	 to  work  the server must have	been started with root

       CloakHost (string)
	      Set this hostname	for every client instead of the	real one.  De-
	      fault:  empty,  don't  change. Use %x to add the hashed value of
	      the original hostname.

       CloakHostModeX (string)
	      Use this hostname	for hostname cloaking on clients that have the
	      user  mode "+x" set, instead of the name of the server. Default:
	      empty, use the name of the server. Use  %x  to  add  the	hashed
	      value of the original hostname

       CloakHostSalt (string)
	      The  Salt	 for cloaked hostname hashing. When undefined a	random
	      hash is generated	after each server start.

       CloakUserToNick (boolean)
	      Set every	clients' user name and real name to their nickname and
	      hide the one supplied by the IRC client. Default:	no.

       ConnectIPv4 (boolean)
	      Set this to no if	you do not want	ngIRCd to connect to other IRC
	      servers using the	IPv4 protocol. This allows the usage of	ngIRCd
	      in IPv6-only setups.  Default: yes.

       ConnectIPv6 (boolean)
	      Set this to no if	you do not want	ngIRCd to connect to other IRC
	      servers using the	IPv6 protocol.	Default: yes.

       DefaultUserModes	(string)
	      Default user mode(s) to set on new local	clients.  Please  note
	      that only	modes can be set that the client could set using regu-
	      lar MODE commands, you can't set "a" (away)  for	example!   De-
	      fault: none.

       DNS (boolean)
	      If  set  to  false,  ngIRCd  will	 not make any DNS lookups when
	      clients connect.	If you configure  the  daemon  to  connect  to
	      other  servers,  ngIRCd  may  still  perform a DNS lookup	if re-
	      quired.  Default:	yes.

       Ident (boolean)
	      If ngIRCd	is compiled with IDENT support this  can  be  used  to
	      disable IDENT lookups at run time.  Users	identified using IDENT
	      are registered without the "~" character prepended to their user
	      name.  Default: yes.

       IncludeDir (string)
	      Directory	  containing  configuration  snippets  (*.conf),  that
	      should be	read in	after parsing the current configuration	 file.
	      Default: none.

       MorePrivacy (boolean)
	      This  will  cause	ngIRCd to censor user idle time, logon time as
	      well as the PART/QUIT messages (that are sometimes used  to  in-
	      form everyone about which	client software	is being used).	WHOWAS
	      requests are also	silently ignored,  and	NAMES  output  doesn't
	      list  any	 clients  for non-members.  This option	is most	useful
	      when ngIRCd is being used	 together  with	 anonymizing  software
	      such  as TOR or I2P and one does not wish	to make	it too easy to
	      collect statistics on the	users.	Default: no.

       NoticeBeforeRegistration	(boolean)
	      Normally ngIRCd doesn't send any messages	to a client  until  it
	      is  registered.	Enable this option to let the daemon send "NO-
	      TICE *" messages to clients while	connecting. Default: no.

       OperCanUseMode (boolean)
	      Should IRC Operators be allowed to use the MODE command even  if
	      they are not(!) channel-operators? Default: no.

       OperChanPAutoOp (boolean)
	      Should  IRC  Operators  get AutoOp (+o) in persistent (+P) chan-
	      nels?  Default: yes.

       OperServerMode (boolean)
	      If OperCanUseMode	is enabled, this may  lead  the	 compatibility
	      problems	with Servers that run the ircd-irc2 Software. This Op-
	      tion "masks" mode	requests by non-chanops	as if they were	coming
	      from  the	 server. Default: no; only enable it if	you have ircd-
	      irc2 servers in your IRC network.

       PAM (boolean)
	      If ngIRCd	is compiled with PAM support this can be used to  dis-
	      able all calls to	the PAM	library	at runtime; all	users connect-
	      ing without password are allowed to connect, all passwords given
	      will  fail.   Users  identified using PAM	are registered without
	      the "~" character	prepended to their user	name.  Default:	yes.

       PAMIsOptional (boolean)
	      When PAM is enabled, all clients are required  to	 be  authenti-
	      cated using PAM; connecting to the server	without	successful PAM
	      authentication isn't possible.  If this option is	 set,  clients
	      not  sending a password are still	allowed	to connect: they won't
	      become "identified" and keep  the	 "~"  character	 prepended  to
	      their supplied user name.	 Please	note: To make some use of this
	      behavior,	it most	probably isn't useful to enable	"Ident", "PAM"
	      and  "PAMIsOptional"  at	the same time, because you wouldn't be
	      able to distinguish between  Ident'ified	and  PAM-authenticated
	      users:  both  don't  have	a "~" character	prepended to their re-
	      spective user names!  Default: no.

       PAMServiceName (string)
	      When PAM is enabled, this	value determines the used PAM configu-
	      ration.	This  setting  allows to run multiple ngIRCd instances
	      with different PAM configurations	on each	instance. If  you  set
	      it  to  "ngircd-foo", PAM	will use /etc/pam.d/ngircd-foo instead
	      of the default /etc/pam.d/ngircd.	 Default: ngircd.

       RequireAuthPing (boolean)
	      Let ngIRCd send an "authentication PING" when a new client  con-
	      nects,  and register this	client only after receiving the	corre-
	      sponding "PONG" reply.  Default: no.

       ScrubCTCP (boolean)
	      If set to	true, ngIRCd will silently drop	all CTCP requests sent
	      to  it  from  both clients and servers. It will also not forward
	      CTCP requests to any other servers. CTCP requests	can be used to
	      query user clients about which software they are using and which
	      versions said software is. CTCP  can  also  be  used  to	reveal
	      clients  IP  numbers. ACTION CTCP	requests are not blocked, this
	      means that /me commands will not be  dropped,  but  please  note
	      that blocking CTCP will disable file sharing between users!  De-
	      fault: no.

       SyslogFacility (string)
	      Syslog "facility"	to which ngIRCd	should send log	messages. Pos-
	      sible  values  are  system  dependent, but most probably "auth",
	      "daemon",	"user" and "local1" through "local7" are possible val-
	      ues; see syslog(3).  Default is "local5" for historical reasons,
	      you probably want	to change this to "daemon", for	example.

       WebircPassword (string)
	      Password required	for using the WEBIRC command used by some Web-
	      to-IRC  gateways.	 If not	set or empty, the WEBIRC command can't
	      be used.	Default: not set.

       All SSL-related configuration variables are located in the  [SSL]  sec-
       tion.  Please note that this whole section is only recognized by	ngIRCd
       when it is compiled with	support	for SSL	using OpenSSL or GnuTLS!

       CertFile	(string)
	      SSL Certificate file of the private server key.

       CipherList (string)
	      Select cipher suites allowed for SSL/TLS connections.  This  de-
	      faults   to  "HIGH:!aNULL:@STRENGTH:!SSLv3"  (OpenSSL)  or  "SE-
	      CURE128:-VERS-SSL3.0" (GnuTLS).  Please see 'man	1ssl  ciphers'
	      (OpenSSL)	and 'man 3 gnutls_priority_init' (GnuTLS) for details.

       DHFile (string)
	      Name  of	the Diffie-Hellman Parameter file. Can be created with
	      GnuTLS "certtool --generate-dh-params" or	"openssl dhparam".  If
	      this  file  is not present, it will be generated on startup when
	      ngIRCd was compiled with GnuTLS  support	(this  may  take  some
	      time).	If    ngIRCd   was   compiled	with   OpenSSL,	  then
	      (Ephemeral)-Diffie-Hellman  Key  Exchanges  and  several	Cipher
	      Suites will not be available.

       KeyFile (string)
	      Filename	of SSL Server Key to be	used for SSL connections. This
	      is required for SSL/TLS support.

       KeyFilePassword (string)
	      OpenSSL only: Password to	decrypt	the private key	file.

       Ports (list of numbers)
	      Same as Ports , except that ngIRCd will expect incoming  connec-
	      tions  to	 be SSL/TLS encrypted. Common port numbers for SSL-en-
	      crypted IRC are 6669 and 6697. Default: none.

       [Operator] sections are used to define IRC Operators. There may be more
       than one	[Operator] block, one for each local operator.

       Name (string)
	      ID of the	operator (may be different of the nickname).

       Password	(string)
	      Password of the IRC operator.

       Mask (string)
	      Mask  that  is to	be checked before an /OPER for this account is
	      accepted.	 Example: nick!ident@*

       Other servers are configured in [Server]	sections. If you  configure  a
       port  for  the  connection, then	this ngIRCd tries to connect to	to the
       other server on the given port (active);	if not,	it waits for the other
       server to connect (passive).

       ngIRCd supports "server groups":	You can	assign an "ID" to every	server
       with which you want this	ngIRCd to link,	and the	daemon ensures that at
       any given time only one direct link exists to servers with the same ID.
       So if a server of a group won't answer, ngIRCd tries to connect to  the
       next  server  in	the given group	(="with	the same ID"), but never tries
       to connect to more than one server of this group	simultaneously.

       There may be more than one [Server] block.

       Name (string)
	      IRC name of the remote server.

       Host (string)
	      Internet host name (or IP	address) of the	peer.

       Bind (string)
	      IP address to use	as source IP for the outgoing connection.  De-
	      fault is to let the operating system decide.

       Port (number)
	      Port  of	the  remote server to which ngIRCd should connect (ac-
	      tive).  If no port is assigned to	a configured server, the  dae-
	      mon only waits for incoming connections (passive,	default).

       MyPassword (string)
	      Own  password  for this connection. This password	has to be con-
	      figured as PeerPassword on the other server. Must	not  have  ':'
	      as first character.

       PeerPassword (string)
	      Foreign  password	 for  this connection. This password has to be
	      configured as MyPassword on the other server.

       Group (number)
	      Group of this server (optional).

       Passive (boolean)
	      Disable automatic	connection even	if port	 value	is  specified.
	      Default:	false.	 You  can use the IRC Operator command CONNECT
	      later on to create the link.

       SSLConnect (boolean)
	      Connect to the remote server using TLS/SSL. Default: false.

       ServiceMask (string)
	      Define a (case insensitive) list	of  masks  matching  nicknames
	      that  should be treated as IRC services when introduced via this
	      remote server, separated by commas (",").	REGULAR	SERVERS	 DON'T
	      NEED this	parameter, so leave it empty (which is the default).

	      When  you	are connecting IRC services which mask as a IRC	server
	      and which	use "virtual users" to communicate with,  for  example
	      "NickServ"  and  "ChanServ",  you	 should	 set this parameter to
	      something	  like	 "*Serv",   "*Serv,OtherNick",	  or	"Nick-

       Pre-defined  channels  can  be  configured  in [Channel]	sections. Such
       channels	are created by the server when starting	up  and	 even  persist
       when there are no more members left.

       Persistent  channels are	marked with the	mode 'P', which	can be set and
       unset by	IRC operators like other modes on the fly.

       There may be more than one [Channel] block.

       Name (string)
	      Name of the channel, including channel prefix ("#" or "&").

       Topic (string)
	      Topic for	this channel.

       Modes (string)
	      Initial channel modes.

       Key (string)
	      Sets initial channel key (only relevant if channel mode  "k"  is

       KeyFile (string)
	      Path and file name of a "key file" containing individual channel
	      keys for different users.	The file consists of plain text	 lines
	      with the following syntax	(without spaces!):

		     user : nick : key

	      user and nick can	contain	the wildcard character "*".
	      key is an	arbitrary password.

	      Valid examples are:


	      The  key file is read on each JOIN command when this channel has
	      a	key (channel mode +k). Access is granted, if  a)  the  channel
	      key  set using the MODE +k command or b) one of the lines	in the
	      key file match.

	      Please note:
	      The file is not reopened on each access, so you can  modify  and
	      overwrite	 it  without problems, but moving or deleting the file
	      will have	not effect until the daemon  re-reads  its  configura-

       MaxUsers	(number)
	      Set  maximum user	limit for this channel (only relevant if chan-
	      nel mode "l" is set).

       It's wise to use	"ngircd	--configtest" to  validate  the	 configuration
       file after changing it. See ngircd(8) for details.

       Alexander Barton, <>
       Florian Westphal, <>



ngIRCd				   Jan 2019			ngircd.conf(5)


Want to link to this manual page? Use this URL:

home | help