Administration Guide
Administration Guide
Table of Contents
$Id: install.txt,v 1.12 2004/12/24 05:46:43 haplo Exp $
This document contains installation, configuration and use documentation for
the NexusChat telnet chat daemon.
I am working on an install script, but for now you'll have to install it
yourself. There are basically two steps.
1) Decide where you want NexusChat's home directory to be. I suggest
creating an `nchat' user and /home/nchat home directory. I would also
separate the installation further by creating a data/ subdirectory in
/home/nchat. This way you can store all the data files in there and
put the nchat and userdb binaries in /home/nchat.
Then run 'setup.sh' and answer the questions. Then run 'make' to
build your binaries and you're ready to install.
2) Copy your nchat and userdb binaries where you want them. Then copy the
everything in the etc/ directory to your data directory if you want to
use the default data. Now you can start nchat and log in as 000 with
`root' as your password.
NexusChat is licensed under the GNU General Public License (GPL) and is
located in the file COPYING.
There are sample/default datafiles included in the etc/ dir of the source.
The following explains their usage:
nc_ansi_login Color ANSI screen presented to the user when they
connect to nchat.
nc_login Login screen presented to users without ANSI color.
nc_motd Message of the day. This file is sent to the user
after they have successfully logged in.
nc_log Not included in the example directory, this will be
created when nchat is run and will log various actions.
nchatrc This is the resource file for the daemon, there are
only a few options that can be set, look at the file
for more info.
nc_ban_list This file holds a list of ip/mask entries which will
be added to the ban list on bootup. Each entry must
be on a separate line
nc_class This specifies your user classes. NexusChat requires
you to have the GUEST and SYSOP classes (NexusChat is
case sensitive) To find out more about the class file
structure, skip ahead to the User Classes section.
nc_register This file is sent to the user when they first enter the
self registration process. Here you can put in
instructions for the user, such as they must put a
valid email address, or the phone field is optional.
msg/ This directory is where you can store message files.
Any file/directory in this directory can be accessed
by users with the /m command. Example, you have a file
called 'info' in the directory. A user typing '/minfo'
will have the file sent to them.
User classes allow you to have more control over what your users have access
to command-wise, and also allow you to separate them into groups. In versions
of NexusChat prior to v3.1, these access restrictions were hardcoded.
The Class File
The class file 'nc_class' by default, contains the specification for your user
classes. NexusChat requires that you have the two classes GUEST and SYSOP,
because there is some internal workings that require these basic classes.
Also remember that NexusChat is case sensative, a 'User' class is not the
same as 'USER'. A very simple class file may look like this:
[ GUEST ]
handle=?
time=15
node_flags=()
toggles=e
priority=0
CMD_HELP CMD_SUSERS CMD_HANDLE CMD_QUIT
[ SYSOP ]
time=-1
node_flags={}
toggles=e
priority=10
(GUEST)
CMD_KILL
This of course doesn't even allow for 1/10 of the commands nchat has
available, but it is only an example. The class name is specified in
brackets [] and then default options are specified. These default options
are set when a class is selected in the user editor. The default options are
as follows:
handle This is the default handle for the user
time The default time limit for the class
node_flags These are parts of the handle that are often used to identify
the authority of a user.
toggles These are the default toggles, a current list of toggles is:
a ANSI color
e Echo
l Lurking enabled
z Input locked
priority This is usually a value from 0-MAX_CLASSES, but it can be as
as big or small as an int. Priority is used to determine
whether or not users may /k each other. In order for someone
to /k another user, their priority must be greater than or
equal to the victim's. So, for example, there is a sysop
whose priority is ten, and a co sysop whose priority is 5.
The sysop may /k the co sysop, but the co sysop may not /k
the sysop. Okay that's kind of confusing, but its really very
simple. If a class's kill priority is set to 0, they may be
vote killed by users with access to the command.
(Note: in the above explanation and examples, it is assumed
that the classes have access to the /k command.)
These defaults can be changed in the user editor on a per user basis as
desired. Also, you do not have to include entries for all, or any of the
defaults.
** The one exception to both of these rules is 'priority'
** Kill priority may not be set on a per user level, and although nchat does
** not explicity require you to set the priority, it is defaulted to 0, which
** is probably NOT what you want (see above)
The lines below that are just a space-separated list of the commands that the
class is allowed to access. See the section 'COMMAND LIST' for a list of all
the command definitions.
Inheritance
Putting parenthesis around a class name on a line by itself, such as (GUEST)
in the example file, tells nchat to make that class inherit the other class'
command access. In the example the sysop class will inherit the GUEST class'
commands (CMD_HELP CMD_SUSERS CMD_HANDLE CMD_QUIT) and also get CMD_KILL.
Note: when using class inheritance, the inherited class must be defined before
it is included. In the above example, the GUEST class must come before the
sysop.
Limitations
- The classes are stored in an array, the current max class count
is 10, but you can increase it if you need.
- Each line in nc_class must be < 200 characters
There are two ways to create and edit users. You can use the user editor in
nchat, just type "/ue" to enter the user editor. To create a new user in the
editor type "load <user>" where <user> is the user number you would like to
create. You will then be presented with a blank user which you can edit. If
you set their Class first, it will fill in default data for you. To create a
sysop, enter "sysop" as the user"s class. Typing "quit" will then save the
user and exit the editor. You can type "help" in the editor for a list of
commands.
TIP: In the user editor, if you set the Class of the user first, it will
automatically fill in default data for them!
The second way to edit the user is via the command-line utility called userdb.
Run "userdb" by itself for a list of options.
Upon booting, NexusChat reads, by default, a file called 'nchatrc' which
contains a set of default values. The resource file's format is
<name>=<value> where name is the resource name, and value is it's assigned
value. A list of variables is as follows:
Name Type Default Description
port Integer 4000 Port to listen on
locked Boolean false Lock the system on boot
staple_time Integer 60 Time given by a /v (staple)
guest_kill Boolean true Enable vote killing of guests
quiet Boolean false Suppress all output
check_dup Boolean false Reset any duplicate users
ping_hack Boolean false Sends NULLs to idle sockets
chat_name String NexusChat Name of your chat
user String none User to run as
group String none Group to run as
chroot Boolean false chroot() to the data dir
sysp_priority Integer 1 Min priority to use /ps
broadcast_priority Integer 10 Lowest priority to get log
broadcasts
flood_count Integer 25 Max number of lines allowed
flood_time Integer 3 Exceeding flood_count in
flood_time seconds results in
a flood kill
ask_ansi Boolean false Instead of autodetecting ANSI
emulation, it prompts them
when they first connect
allow_registration Boolean true Whether or not to allow users
to register themselves
register_reserved Integer 50 IDs above this will be used
for self registration
user_notify Integer 000 The user to email registration
requests to
flood_priority Integer 10 Users at and above this
priority setting are not
affected by flood rules
Boolean values are specified by 'true' or 'false' (case matters). You may
provide comment lines by placing a # at the beginning of the line.
Note: If you are specifying a value with spaces in it, make sure to enclose
it in ""'s.
These options may also be set and saved while in Nexuschat using the /set
command, see the /set help for more details.
Now that you have set up your system with all external values set and classes
assigned, you can open your chat. Assuredly, there will be users that break
your rules or are otherwise obnoxious. NexusChat provides a series of
helpful commands to help administer the system remotelly in order to protect
other users and yourself.
KILL : The kill command, used in the format /K(node) (msg), will
disconnect the specified (node). The optional message may be used as a
kill message or some other notification. A blank message will not be sent,
so the message itself is totally optional.
ZONE/ZOMBIE : A zone or zombie state locks the input of a user. They will
be able to see all that is said, but no data that they send will be received
by the system--including all commands such as /s and even /q. This is an
excellant way to deal with spammers. Use the command /zz(node) to lock
a user's input.
LOCK : Locking the system prevents anybody who does not have an
account from logging in. It is toggled using the /lock (msg) command.
Again, the message is an optional lock message to be displayed to any user
before it disconnects them (if they do not have an account).
DEVALLIDATION: The term devalidation actually dates back to older chats and
BBS systems in which a user must have been validated to use their account.
Devallidation removes that right and renders the account unusable. To
devallidate somebody in nchat, go into the user editor and set their class
to something that doesn't exist. You should see their class show up as
"DISABLED", and it is just that. (note: you may also permanently by using the
command /ud or deleting them from the user editor)
IP BAN : An IP ban is a serious way to prevent a user from logging in.
Anybody with a given IP (or on a given IP block) will not be able to log in
if their IP is banned. IP bans are enacted or removed (or shown) via the
/banadd(IP)/(mask), /bandel(IP)/(mask), and /banlist commands. The mask
allows the administrator to be anybody from a specific provider's dialup.
Examples (and their simplest explanations):
152.167.34.87/32 - This will ban this EXACT IP ADDRESS. You may also
leave off the /32 and it will assume it.
152.167.34.0/24 - This will ban anybody with the first three octets
matching.
152.167.0.0/16 - ...bans matches to the first two octets.
152.0.0.0/8 - ...bans matches to the first octets.
As of the newer 3.2pre releases you can add a timed ban (in minutes)
Here is an example:
/banadd 152.167.34.0/24 10
This will ban the preceding subnet for 10 minutes.
As you can probably see, the masks determine how large a chunk is banned from
logging in to nchat. This can be very beneficial, but also very dangerous
if you do not know what you're doing. Note also that for /bandel to be
successful, it must match exactly to an entry in your banlist.
OTHER : There are other ways of punishing users for breaking rules
that are not neccesarily truly meant as such. For instance, you can /g a
user to a negative time (NOT -1, which is infinate,) to time them out
instantly. Similarly, changes through the user editor to time or flags may
be used to get your point across.
This is a list of all of NexusChat's commands, their function names as
needed by the class file, and their descriptions. If you want to look at
the table yourself, it is located in commands.c
Here is the complete command list:
CMD_HELP Displays this command list
CMD_QUIT Leaves NexusChat
CMD_HANDLE Set your handle
CMD_ECHO Toggles local echo
CMD_ANSI Toggles ANSI color
CMD_ACTION Perform an action
CMD_SET Set resource option
CMD_SAVE Save your preferences now
CMD_SUSERS Display online users (# = extended)
CMD_PASSWD Change your password
CMD_PRIVATE Send a private message
CMD_SQUELCH Disable /p's from user
CMD_INFO Display NexusChat info
CMD_AFK Set your away message
CMD_MESSAGE Display system message
CMD_CHANNEL Switch to another channel
CMD_LAST Display users call stats
CMD_CI Display channel info
CMD_CO Toggle channel lock status
CMD_CK Kick user from channel
CMD_CM Give user channel moderator status
CMD_CL Set channel limit
CMD_CLS List current channels
CMD_VOTEKILL Vote to kill a guest
CMD_KILL Disconnected a user
CMD_RELOG Send user back to login
CMD_LOG Display last ten system log entries
CMD_GTIME (+) Give (-) Take (=) Set time to (time)
CMD_BANADD Add an IP ban
CMD_BANDEL Remove an IP ban (match exactly)
CMD_BANLIST Display IP ban list
CMD_UE Enter user editor
CMD_US Display user info
CMD_UD Delete user
CMD_LURK Toggle Lurk flag
CMD_RESET Reset a node
CMD_LOCK Toggles the locked status
CMD_STAPLE Give guests extra time
CMD_PAGER Page another user
CMD_NEWS Add / remove news items
CMD_CS Class commands
CMD_MAIL View / send email
CMD_TALKTO 'Address' someone in a channel
CMD_KILLBAN Kill and ban a user/ip for a certain period of time
CMD_EHELP Extended help command
CMD_ZHANDLE Change another node's handle
CMD_ZCLASS Change a user's class
CMD_ZTEXT Output raw text
CMD_ZFREEZE Toggle a user's input lock
CMD_STAMP Toggle time stamps
CMD_CLS List all channels with information
CMD_USERS List all registered user accounts
With maybe some more commands to come :)
What is vote kill? Well, the vote kill command allows non-administrators to
get rid of pesky or annoying guests. The main idea behind vote kill is that
the majority can act in place of a sysop. Of course people with power like
to use it often, and not always properly. Vote kill is toggleable via a /set
command.
/set guest_kill (on | off)
So "/set guest_kill on" will enable the use of the command for those who's
class has access to it. So how does vote kill work? Pretty simple; vote kill
counts the number of users online that are NOT guests and do NOT have access
to the /k (kill/kick) command. The latter is to disqualify admins from the
count, in case they are not around or whatever.
Everytime a user votes, it is checked against the current count. NOTE: no
user may vote more than once, this is checked by storing the user number. If
the current count is *greater* than half of the counted users, the guest is
killed*.
* This is true in all cases except when there is only one counted user online,
if that is the case, the guest will not be able to be killed.
So, for example, say there is 1 sysop, 1 guest, and 2 users online. Both
users will have to vote to kick the guest. If three users are online, only
two of them must vote, and so on.
Another thing to note is that votes stick across voters calls. That means
that if a couple of users vote and then log out, and another user comes on and
votes, it will be calculated with the current online user count and the
cummulative vote count, if that makes any sense :)
Note: A guest is now defined as any user who's class kill priority is set
to 0. This differs from the old way of only counting the GUEST class.
These are a few tips, tricks, and quirks about nchat that might prove useful.
* In the user editor, you can set a user's class to a non-existant
class. A user with a non-existant class defined, will be denied
a login. You can use this to 'blacklist' users without actually
removing their account.
* Commands such as /zc /zz /g that modify a user's saveable info, are
TEMPORARY. That is, they will get discarded when the user logs off.
This is useful if you only want to give them extra time or temporary
elevated access for a single call. If you want something to be
permanent, you must use the user editor to set it explicitly.
I'd especially like to thank Jonathan Bravata, who donated much of his time to
help debug nchat, and for his countless suggestions and ideas.
I'd also like to thank the other users of the Monochrome Chaos who helped to
shape nchat into what it is today, thanks guys!
I'd also like to thank the following people for submitting bug reports or
patches:
Ryan Brown (ryan@wabdo.com)
NexusChat is free software, but my college tuition payments aren't free :)
So if you've got a little extra cash, I promise I won't turn it down.
I can be contaced via email at haplo81@comcast.net, or write me at:
Bryan Burns
1417 Challis Dr. Apt #7
Bloomington, IL 61704
Thats all for now, ciao.
