commit e345717385c899074ce46c015902a129a35e2879 from: Omar Polo date: Fri Feb 16 09:23:36 2024 UTC add a readme commit - 5b30aca674fcba8d97a4da8fabbc55413eb6220e commit + e345717385c899074ce46c015902a129a35e2879 blob - 575549cb07006b848d0eef1ae865d5e61a98487e blob + 6de50f2483acbc17a6b86c98a7fdb1a6e87a99e9 --- Makefile +++ Makefile @@ -4,4 +4,7 @@ MAN= icbirc.8 CFLAGS+= -Wall -Werror -Wstrict-prototypes -ansi +${.CURDIR}/README.md: icbirc.8 + mandoc -T markdown -l $? > $@ + .include blob - /dev/null blob + 026dbeb5886bd3542029879988051f173b3348be (mode 644) --- /dev/null +++ README.md @@ -0,0 +1,201 @@ +ICBIRC(8) - System Manager's Manual + +# NAME + +**icbirc** - proxy IRC client and ICB server + +# SYNOPSIS + +**icbirc** +*host*\[:*port*]\[/*room*] + +# DESCRIPTION + +**icbirc** +is a proxy that allows to connect an IRC client to an ICB server. +The proxy talks IRC via standard input and standard output, +so it's suitable to be run with +inetd(8), +and connects to the ICB server specified in the command line, optionally +joining automatically a room. + +Commands from the IRC client are translated to ICB commands and forwarded +to the ICB server. +Messages from the ICB server are translated to IRC messages and forwarded +to the IRC client. + +IRC (Internet Relay Chat) and ICB (Internet Citizen's Band) are two separate +chat protocols. +ICB is an older and simpler protocol, basically a subset of IRC. +The two most significant differences (from the client's perspective) are: + +* an ICB client can only join a single channel (called group). + Joining a second channel automatically parts the first channel. + +* an ICB channel can only have a single operator (called moderator). + Giving operator status to a second client automatically removes + operator status from the first client. + +# SUPPORTED COMMANDS + +**icbirc** +supports the following IRC commands: + +CAP LS, CAP REQ, CAP END + +> Basic IRCv3 capability handling is present for compliance with a wider +> range of IRC clients. + +PASS + +> Set the default group, used during login. + +NICK + +> Set or change nickname. + +USER + +> Supply additional user information (like ident), used during login. + +LIST + +> List all groups. + +WHOIS + +> Shows information about a user. + +WHO + +> Lists matching users. +> Arguments starting with '#' are interpreted as channel names +> (listing all users in the specified channel), anything else +> is used for a simple string search within users' 'nick!ident@host'. + +JOIN + +> Join a group. + +PRIVMSG + +> Send an open or personal message. + +NOTICE + +> Same as PRIVMSG. + +TOPIC + +> Set group topic. + +KICK nick + +> Boot nick from group. + +MODE +o nick + +> Pass moderation to nick. + +QUIT + +> Close client and server connection, wait for next client connection. + +Additionally, the command RAWICB can be used to send custom ICB +commands. +The proxy automatically prefixes the correct command length and +replaces commas with ICB argument separators. +For example: + +RAWICB hm,nick,msg + +> Send msg to nick. + +# EXAMPLES + +Connect to the ICB server +'default.icb.net' +on the default port 7326, accepting IRC commands on standard input and +faking IRC server messages on standard output: + + $ icbirc default.icb.net + +Like the previous, but join automatically the group (channel) +'slackers': + + $ icbirc default.icb.net/slackers + +Run +**icbirc** +with +inetd(8), +suitable for connecting with IRC clients that don't support talking +IRC on a pipe: + + 6667 stream tcp nowait user /usr/local/bin/icbirc icbirc example.com + +'user' +needs to be changed with a valid, local user name. + +# SEE ALSO + +*Internet Relay Chat Protocol*, +RFC 1459. + +*Internet Relay Chat: Client Protocol*, +RFC 2812. + +*Internet Relay Chat: Channel Management*, +RFC 2811. + +*ICB Protocol*, +ftp://ftp.icb.net/pub/icb/src/icbd/Protocol.html. + +*The History of ICB*, +http://www.icb.net/history.html. + +*General guide to Netiquette on ICB*, +http://www.icb.net/\_jrudd/icb/netiquette.html. + +# HISTORY + +The first version of +**icbirc** +was written in 2003. + +# AUTHORS + +**icbirc** +was written by +Daniel Hartmeier <daniel@benzedrine.cx> +and is maintained by +Omar Polo <op@openbsd.org>. + +# CAVEATS + +ICB is not IRC. +Depending on the ICB community on a particular server, netiquette rules +vary greatly from common IRC rules (or lack thereof). + +Client scripts or other forms of automated client actions might generate +noise or violate ICB community policies, and lacking support for some +commands might confuse the script. +Clients should be properly configured and tested on a dedicated server +before connecting to a public server. + +In particular, WHOIS and WHO filtering is done on the proxy. +Each such request causes the proxy to fetch the entire user list from the +ICB server (there are no ICB commands that take filters), hence +automatic WHOIS requests from the IRC client can cause unwanted load on +the ICB server +(turn off 'WHOIS on JOIN' in the IRC client, if enabled). + +# BUGS + +On ICB, a moderator (channel operator) can leave the group (channel) and +rejoin later, preserving his status, as compared to IRC, where the channel +would be left operator-less in this case. +The proxy does not currently detect the operator status on rejoin in this +case, and the IRC client will (temporarily) show the channel op-less. + +OpenBSD 7.4 - August 20, 2023