Bold text can be inserted by typing %BText%B
Index
To install you will need a server that is running unix, has perl 5 installed and you have CGI access on. There are two methods of installing detailed below for people who have FTP access and for people with shell access to their account.
Firstly you will need download the zip or tar.gz file to your computer and edit the config file (see the config section for more information). Once you have got the config file edited load your FTP program and login to your server. Then upload the files in the cgi-bin directory in ASCII format (make sure you actually select ASCII, don't let the FTP client auto detect the type as they often get it wrong) put the files in your cgi-bin directory, or make a subdirectory called irc for example if you have a lot of CGIs and want to keep them seperate (if you are not sure where your cgi-bin directory is see the support section of your host's website or ask them). Then make sure that all the files are correctly set, all the files need to be 755 (read, write and execute permissions for user, read and execute permissions for group and other).
Next upload all the files in the html directory to your html directory (the same place that you set in the config file). Once all the files are uploaded go to irc.cgi in the place you installed it (for example http://user.domainname.com/cgi-bin/irc.cgi), if it is installed properly you should get a login box and be able to use it. If there is an error see the problems section below.
This is easier than ftp install (well i think it is ;). Get the tarball on
to your server something like:
wget http://cgiiirc.sourceforge.net/cgiirc-0.4.2.tar.gz
Then untar the tarball with:
tar zxvf cgiirc-0.4.2.tar.gz
You then need to change directory into cgiirc-0.4.2, then edit the config file in
cgi-bin/config (read the instructions on this, you may
prefer to edit it on your system and then put it on the shell..). Once you have
got the config file how you want it, put the contents of the cgi-bin directory
into your cgi-bin directory in your webspace (if you are not sure where this is
ask your admin):
cp -rp cgi-bin ~/public_html/cgi-bin/ (that is an example the
second part may be different and you may not need the -p option to cp if you
are on a system other than linux.)
Some sites allow CGI to be executed in all directories so you
may be able to just put it into your public_html directory. Then copy the
contents of the html directory into the location that is where the html
directory is defined in the config file is.
That should be it as the tarball contains the correct permissions if the
correct permissions aren't set check that the cgi scripts are correctly set to
755 or with ls -l the files should show -rwxr-xr-x.
The configuration of CGI:IRC is very flexable but that also means it is quite hard to configure...
You shouldn't actually need to change much of the config file, the defaults
will almost always work. The things that you need to change are the default_ to
match your channel, server and so on and the htmlpath. The config file contains
lines like something=somethingelse, that means 'something' is set
to 'somethingelse', a line that starts with a # is a comment and is ignored,
and so are blank lines.
default_server sets the server that appears in the login form, it doesn't
set any restrictions, see the access controls for those. default_nick is the
deafult nickname format to use, a ? will be replaced with a random number.
default_name is what to put in the realname field. default_channels the the
default channel to join (you could have more than one by putting spaces in)
The irc_ is the location of the scripts, you shouldn't need to change these
unless you use a CGI wrapper or something that gives a different path (note:
using CGI:IRC with a CGI wrapper can cause problems, so avoid it if you can).
htmlpath is the location of the images and help html files on your
webserver, you can put either a location like /html/ or http://site.com/html/,
what you put here is basically put in front of the image name being passed to
the web browser in the <img> tag.
You shouldn't need to edit any of the settings below the htmlpath, apart from access controls
The tmpfile_prefix controls where the files created by CGI:IRC go. If you
want to put them into another directory because you can't write to /tmp or
something you can change it
These are appearence settings: welcome is the message displayed when CGI:IRC loads, version_string is used
in various places and i don't recommend you change it. monospaced makes CGI:IRC
use a monospaced font you may want to use it if you use an ASCII art logo.
userstyle defines the style of the userlist, radio is a list of radio buttons the disadvantage being on big channels you have to scroll the whole frame, select is smaller and doesn't scroll the frame but doesn't look as good. format is the name of the format file, at the moment the only one avaible is cgiirc but there may be more on the site by the time you read this. hiddenform uses a hidden form to submit the text to, the advantage is it's quicker, the disadvantage is that it neeeds javascript. timestamps means that timestamps are put in front of commands. margin means the nicknames are slightly indented like with xchat. completion means that nicknames are completed when they end in :, so nickn: would turn into nickname: if 'nickname' was on the current channel. hidelogin will hide all text that comes before the join, this looks nice but hides some information.
Server settings: floodtime this is the time between CTCP
requests that is considered a flood, this is best left alone :).
default_mode this is the mode that users get on join, invisible is
a good idea but you may want to turn wallops (w) off. encoded_ips
this enables encoded_ips, see the information on abuse for how to use this.
ipaccess contains the name of the file with ip addresses that are allowed access or not allowed access (see
below for more information). This is probally best left alone. referer This controls how other people can link to your script (but as an access control it isn't very secure..), 0 = none, 1 = check after login, 2 = check on all (login form and main). kill_password allows you to kick people off, see the section below for information.
There are lots more settings but i think if you need the others you will
know.., but form_redirect is very useful.
These are very powerful and allow you to control what commands, channels and servers can be used via your CGI:IRC. They all take a regular expression as input so if you know these you'll find them easy. If you don't then you can adapt from one of the examples.
The basics are that #channel matches #channel and !#channel matches anything that isn't #channel
access_channels
setting this to #channel would allow access to only #channel, you can match multiple channels like this: (#chat|#other)
Examples:
access_channels=#chat (Allow access to the #chat channel only)
access_channels=(#chat|#other) (Allow only the #chat and #other channels)
access_channels=!#admins (Disallow access to the #admins channel)
Servers are similar to the channels but a more powerful feature of regualar
expressions is useful here:.*\.blitzed\.org that would allow access to all servers
ending in blitzed.org (ie. all blitzed.org irc servers). You can also use the same uses
as are used in channels (and you could use the trick used in the server on
channels too). Examples:
access_servers=irc.host.com (this allows access to only one server)
access_servers=.*\.dal\.net (the rule seen above to allow access to all dal.net
servers)
See the section on Administration Features for more details on how you can
control access to your script
The login form doesn't always look very professional, you can look at the
template in launch.html to see how you can include it in your webpage. Or you can
also use javascript to prompt for it like this (you will need to change the
script location, server and channel but you must keep %23 for the # in the channel name:
<a href="http://host.server.com/irc.cgi?myaction=load&p=6667&s=irc.server.com&r=CGI+User&c=%23channel&n=" onClick="location=this.href+=prompt('Please enter a nickname','');return false">Talk to us!</a>
Hopefully using CGI:IRC should be easy enough but this is a quick guide on how to use it.
Basically when you join a channel there is a form at the bottom which you can type text into and select which channel to send it to (if you open a query the nickname will come into the box too). The userlist lists all the users in the channel and you can perform several actions on a user such as whois and so on. The main frame contains all the messages that are sent to you.
If you click stop then you will be disconnected this is due to the fact CGI:IRC sends a stream and can't be changed.
CGI:IRC supports completion of nicknames, this means that if you type nickn: and 'nickname' is on the channel CGI:IRC will replace nickn: with nickname: once you have learnt how to use this feature it really makes chatting much quicker.
CGI:IRC supports most IRC commands, these are the basic commands:
/msg nick text
/query nick
/notice nick text
/whois nick
/ping nick
/whowas nick
/who #Channel
/list
/topic
/join #Channel
/part #Channel
/nick NewNick
/me text
/quit text
/names #channel
/ctcp nick type
/ignore nick
/quote command
/help
Channel Op commands
/op nickname
/deop nickname
/voice nickname
/devoice nickname
/mode #Channel +modes
/kick nick
/ban nickname
/unban *!ident@*.*
/topic newtopic
Your server may support more commands or it may not support all of these
commands. As with nickname completion commands are completed so you can type
/na and it will actually do /names.
Nicknames can be completed by pressing tab
Color can be inserted by typing %C1 where 1 is a number from the color chart below. If you want to have a background too you can by typing %C1,2 where 2 is another color from the chart. You type %C again to end the color, for example %C1,7Color Text%C
Bold text can be inserted by typing %BText%B
Formats provide a flexible way of changing the appearence of CGI:IRC, there are
several formats included with CGI:IRC, cgiirc is the default and the look is
fairly standard, text is a look more like a unix console irc client or with
some scripts for mIRC, text-white is similar to text but has a white
background. 900degrees is a bluish format that is fairly easy to use and only
supports and single channel. basic is designed for use where you want to hide
all hostnames or provide a very simple interface.
To select a format you can either put it in the config file and it will then be
the default format, or you can use launch.html and change the style hidden
input to the name of the format.
These are very powerful and allow you quite a lot of control over your users
This allows you to kill a user from CGI:IRC (basically disconnect them), to
use it you do /ctcp user KILL password reason when you are
connected to the same IRC server as them, you can do this from any IRC
client.
To actually enable it you need to add a unix crypt into the config file on the
kill_password line. This is a standard UNIX crypt if you have
shell access it can make one with perl -e'print crypt("password","ko"),"\n"' replace the password with the password you want and replace ko with any random letters (these are used for secruity and you don't need to know them).
If you only have CGI access you could make a CGI to print the crypt for you so
you can save it into the config file. Something like this uploaded as a CGI and
correctly chmoded (755) will print the crypt when you visit it, make sure to delete
it once you have got the crypt.
#!/usr/bin/perl
As with the example above replace password with the password.
print "Content-type: text/plain\n\n";
print crypt("password","ko"),"\n";
An extenstion of this feature is ctcp ban, this allows you to ban a user from CGI:IRC, to make it work you need to allow the webserver write access to the ipaccess file, the easiest way to do it is to chmod 666 the ipaccess file. Then when you do /ctcp user ban reason, it will ban the user's IP Address.
CGI:IRC provides many methods for controlling abuse. The main ones are the ipaccess file which specifies what ips are allowed to use CGI:IRC, ctcp kill is very useful and allows you to kill a user from the chat (but doesn't ban them) and there are several methods that you can get a users ip address.
ipaccess is fairly simple, it's a file of IP addresses that are allowed and
disallowed. When the file is read, denys will overrule allows. The default
configuration is to have *.*.*.* at the bottom that allows all ip addresses. To
ban a particular IP address just put !192.168.1.3 on a line by
itself, that will then ban 192.168.1.3. You can also allow and deny based on *s
so any part of the ip can be matched with a *.
To be able to deny someone you need to know their IP address, CGI:IRC provides several ways to do this, the easiest is to do /ctcp user USERINFO, that will give back to you their ip address and also their browser version. encoded_ips also gives the ip address in an encoded format which appears in /whois and would also be avaiable in /whowas for a short time after the user has disconnected, you can either use the /decode command within CGI:IRC like /decode ab98fcaa, or use the included script in the extra-scripts directory to decode it. Finally if you have the ident server enabled you can put the encoded_ip in the ident, this means that you can set a ban on the ident and ban ip addresses which is very useful.
This script allows you to see where your users are (server, nickname and channel) and also kick them and message a single user or them all. Hopefully the use should be fairly easy to understand. The kill_password as detailed above also controls access to admin.cgi. So once that is set the admin interface will work.
These are not essential but make CGI:IRC access easier to control. They will need either root access (for the ident server) or admin access to your irc network/server (for the hostserv script)
This requires root access to your hosting machine but it makes the script much nicer to use, instead of nobody@yourhost it's either the users encoded IP address or the nickname. To install it edit the /etc/inetd.conf file and add this line, (you will have to adjust the path of where you have put the file, i recommend /usr/local/sbin/identd.pl) ident stream tcp nowait nobody /usr/local/sbin/identd.pl You then need to move your orginal ident server to another port, you will need to add a relevant entry in /etc/services and for example add ident2 as port 114 Then set up ident to run on that port. You may need to edit the script to connect to your actual ip rather than localhost so real ident queries work. (it may begin with auth, depends on your system, see /etc/services on your system and look for either auth or ident and use the one you find).
This has not been tested very well so if you have any problems feel free to email me.
This bot allows you to change the host of your users to their real ip address, it requires an IRCD with SETHOST or CHGHOST
support, there are patches to allow most ircds to support this, but obviously you will either have to know the admin really well
or run the server yourself. To run the bot, give it an O: line on your server and change the settings in the hostserv.pl script
to the settings you need. Once you have set it up correctly, you need to patch a line into CGI:IRC which sends the bot the line.
Find the line where CGI:IRC gets the '001' reply from the server in the nph-irc.cgi file, in 0.4 it is line number 335, below
the line where it says $config{server}=$_[0]; add this line:
irc_server_raw("PRIVMSG", "HostServ :cgiirchost $ENV{REMOTE_ADDR}");
You will need to change the HostServ line to what your host serv bot is called, and the cgiirchost to the password you set.
The scripts each have a purpose, the irc.cgi is used to launch the main frame and also print out a login form. nph-irc.cgi is the main program and actually displays the messages from irc. form.cgi is the bottom frame that is used to send messages back to the main program and userlist.cgi is the userlist.
Look at the included formats for examples, basically the formats are all anon subroutines within a hash, they just need to output the information that is passed to them. Also there are some hashes for colours and messages changing these can affect the colours or messages. Basically just play around with it.
Last Updated: 27 October 2001, Version 1.4 (for CGI:IRC 0.4.3)
©David Leadbeater - This documentation is released under the OpenContent License v1.0