README

   1      goircd -- minimalistic simple Internet Relay Chat (IRC) server
   2      ==============================================================
   3
   4 DESCRIPTION
   5
   6 goircd is very simple IRC server, written on Go.
   7 It was heavily inspired by miniircd daemon written on Python.
   8 goircd is free software: see the file COPYING for copying conditions.
   9 It does not aim to replace full featured mass scalable IRC networks:
  10
  11 * It can not connect to other servers. Just standalone installation
  12 * It has few basic IRC commands
  13 * There is no support for channel operators, many modes, votes, invites
  14 * No ident lookups
  15
  16 But it has some convincing features:
  17
  18 * Only standard Go libraries, no external requirements
  19 * Single executable binary
  20 * No configuration file, just few command line arguments
  21 * IPv6 out-of-box support
  22 * Ability to additionally listen on TLS-capable ports
  23 * Optional channels logging to plain text files
  24 * Optional permanent channel's state saving in plain text files
  25   (so you can reload daemon and all channels topics and keys won't
  26   disappear)
  27 * Optional ability to authenticate users by nickname and password
  28
  29 Some remarks and recommendations related to it's simplicity:
  30
  31 * Use daemontools to daemonize, setuid/gid it
  32 * Just plaintext logging to stdout, without syslog support -- use
  33   daemontool's multilog
  34
  35 SUPPORTED IRC COMMANDS
  36
  37 * PASS/NICK/USER during registration workflow
  38 * PING/PONGs
  39 * NOTICE/PRIVMSG, ISON
  40 * AWAY, MOTD, LUSERS, NAMES, WHO, WHOIS, VERSION, WALLOPS, QUIT
  41 * LIST, JOIN, TOPIC, +k/-k channel MODE
  42
  43 USAGE
  44
  45 Just execute goircd daemon. It has following optional arguments:
  46
  47        -hostname: hostname to show for client's connections
  48            -bind: address to bind to (:6667 by default)
  49           -cloak: cloak user's host with the given hostname
  50            -motd: absolute path to MOTD file. It is reread every time
  51                   MOTD is requested
  52          -logdir: directory where all channels messages will be saved. If
  53                   omitted, then no logs will be kept
  54        -statedir: directory where all channels states will be saved and
  55                   loaded during startup. If omitted, then states will be
  56                   lost after daemon termination
  57         -tlsbind: enable TLS, specify address to listen on and path
  58          -tlspem: to PEM file with certificate and private key
  59          -passwd: enable client authentication and specify path to
  60                   passwords file
  61     -timestamped: enabled timestamps for stderr messages
  62         -verbose: increase verbosity
  63           -debug: also show traffic messages
  64  -perm-state-dir: permission (before umask) for newly created state directory
  65 -perm-state-file: permission (before umask) for newly created state file
  66   -perm-log-file: permission (before umask) for newly created log file
  67
  68 TLS
  69
  70 If you specify -bind and -tlsbind simultaneously, then you will have
  71 both raw and encrypted listening sockets. You can use -bind "" to
  72 disable raw socket.
  73
  74 AUTHENTICATION
  75
  76 You can turn on optional client authentication by preparing passwords
  77 file and using the -passwords argument. Format of passwords file is:
  78
  79     login1:hex(sha256(password1))\n
  80     login2:hex(sha256(password2))\n
  81     ...
  82
  83 You can get hashed password value using: echo -n password | sha256
  84
  85 LOG FILES
  86
  87 Log files are not opened all the time, but only during each message
  88 saving. That is why you can safely rename them for rotation purposes.
  89
  90 STATE FILES
  91
  92 Room's state is created/saved when either topic or key is set. State is
  93 a directory (room's name) with "topic" and "key" plaintext files.
  94
  95 LICENCE
  96
  97 This program is free software: you can redistribute it and/or modify
  98 it under the terms of the GNU General Public License as published by
  99 the Free Software Foundation, version 3 of the License.
 100
 101 This program is distributed in the hope that it will be useful,
 102 but WITHOUT ANY WARRANTY; without even the implied warranty of
 103 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 104 GNU General Public License for more details.