.\"
.\" $Id: vserver.8.in,v 1.5 2006/08/20 17:11:02 mickey Exp $
.\"
.Dd Jun 03, 2006
.Os vserver @PACKAGE_VERSION@
.Dt VSERVER \&8 "VChat System Managers Manual"
.Sh NAME
.Nm vserver
.Nd @PACKAGE_NAME@
.Sh SYNOPSIS
.Nm
.Op Cm /ADDRESS Ns = Ns Ar inet_addr
.Op Cm /BASEDIR Ns = Ns Ar path
.Op Cm /CREATEUDB
.Op Cm /DETACH
.Op Cm /HOSTNAME Ns = Ns Ar fqdn
.Op Cm /LASTLOG Ns = Ns Ar num
.Op Cm /LOGFILE Ns Op Ns = Ns Ar file
.Op Cm /MAXPENDING Ns = Ns Ar num
.Op Cm /PORT Ns = Ns Ar num
.Op Cm /ROTATELOG Ns = Ns Ar num
.Op Cm /SYSLOG
.Pp
.Sh DESCRIPTION
The @PACKAGE_NAME@,
.Nm
provides text based, real-time network conferencing services to users. A
variety of client software may be used to join conferences hosted by
.Nm .
.\" ----------------------------------------------------------------------
.Ss Startup
Normally
.Nm
is started up during system boot from a startup script called by
.Xr rc 8
or
.Xr inittab 5
on SVR4. Along with the
.Nm
distribution you should have received a set of example startup scripts
that may be used for that purpose on various operating systems. The file
.Dv INSTALL
located within the top-level
.Nm
distribution directory contains detailed instructions on this.
.Pp
Before starting
.Nm
into normal operations for the first time, it is crucial to create an
initial user database file. This is accomplished by calling
.Nm
with the
.Cm /CREATEUDB
qualifier. If you intend to use an alternate base directory, make sure
to also specify the
.Cm /BASEDIR
qualifier, pointing to the correct path.
.Pp
.\" ------------------------------------------------------------------------
.Ss Qualifiers
All qualifiers are processed case insensitive and may be abbreviated as long
as they are unambigious. The qualifiers recognized by
.Nm
are as follows:
.Bl -tag -width "-lnum"
.It Cm /ADDRESS Ns = Ns Ar in_addr
By default
.Nm
binds it's network socket to INADDR_ANY, thus
accepting connections on all interface addresses that are configured for the
local processor. By using this qualifier, the address of the interface to which
.Nm
should bind it's network socket may be explicitily specified, so that it
will accept connections on the specified interface address only. The
.Ar in_addr
argument may either be specified as an IPv4 internet address in
standard quad dotted notation, or as a hostname.
.It Cm /BASEDIR Ns = Ns Ar path
This qualifier specifies an alternate base directory, where
.Nm
will keep configuration and data files. By default the directory
.Pa @DEFAULT_BASEDIR@
will be used.
.It Cm /CREATEUDB
When this qualifier is specified,
.Nm
enters interactive user database creation mode and exits thereafter. Any other
commandline qualifiers except the
.Cm /BASEDIR Ns = Ns Ar path
qualifier are discarded when this qualifier is present. This is used for initially
creating a user database file. You will be asked for an initial account user
name and password which will be written to the user database file.
.It Cm /DETACH
Causes
.Nm
to detach from the controlling terminal at startup and to
operate in the background as a daemon process. Note that this
qualifier may not be available, if the underlying operating system does
not supply such functionality.
.It Cm /HOSTNAME Ns = Ns Ar name
This qualifier overrides the servername that is announced to the
clients. Without this qualifier the servername defaults to the name that
is assigned to the interface address that each client has connected to.
.It Cm /LASTLOG Ns = Ns Ar num
This qualifier controls the server lastlog database size. The
.Ar num
argument specifies the number of lastlog records to be stored. In absence
of this qualifier the default of 16383 records will be used. The server lastlog
database is dynamically resized when
.Nm
starts up to match the specified size. Specifying the
.Ar num
argument as 0 disables the server lastlog completely without loosing previously
recorded lastlog data.
.It Cm /LOGFILE Ns Op = Ns Ar file
Specifying this qualifier enables file based logging. If the
.Ar file
argument is given,
.Nm
will write log output to the specified file. Otherwise the default
file
.Pa /var/log/vserver.log
will be used.
.It Cm /MAXPENDING Ns = Ns Ar num
This qualifier controls the maximum number of pending connection requests on
the server socket. When this limit is reached, any further clients trying to
connect to the service will get a
.Qq connection refused
error. The default which is used in absence of this qualifier is 4. It
should normally not be changed except when your machine is experiencing
high peak loads, where connecting clients would otherwise be rejected.
.It Cm /PORT Ns = Ns Ar num
Specifies the TCP port number that
.Nm
will bind it's network socket to. In absence of this qualifier the
default port 1168 will be used.
.It Cm /ROTATELOG Ns = Ns Ar num
With file based logging enabled by the
.Cm /LOGFILE
qualifier,
.Nm
offers the possibility to rotate it's logfile upon receipt of a SIGUSR1
signal. By default
.Nm
will keep 8 logfile generations when rotating the logfile. This qualifier
may be used to specify an alternate number of logfile generations that
is to be kept.
.It Cm /SYSLOG
Causes
.Nm
to report log output via the LOG_LOCAL1 stream of the
.Xr syslog 3
facility of your system. This qualifier is only valid when
.Nm
has been compiled with
.Xr syslog 3
support, which is automatically determined by autoconf prior to compilation.
.El
.\" ------------------------------------------------------------------------
.Ss Access Control List
The Access Control List (ACL) that is maintained by
.Nm
determines whether connecting clients are accepted or rejected based upon
the client's source internet address. The ACL consists of rules, each of which
has a rule number within the range 0 to 65535. Rules are processed in ascending
order until the first rule that matches the client's source address is
encountered. One special rule numbered 65535 that accepts any internet address
is always present. This special rule may neither be deleted nor be
modified. The ACL may be modified by either using
.Xr vchatctl 8
or the VChat client
.Xr vchat 1 ,
provided that the account you are logged on to possesses the appropriate
permissions.
.\" ------------------------------------------------------------------------
.Ss DNS checking
Each client that connects to
.Nm
undergoes a series of checks pertaining to the domain name that is associated
to it's source internet address. Dependent on the result of these tests, a
numerical DNS check level within the range 0 to 3 is assigned to each client:
.Bl -tag -offset indent
.It 0: (none)
No domain name is associated to the client's internet address at all.
.It 1: (fwd)
A domain name is associated to the client's internet address, but the
name does not correctly map back to any address.
.It 2: (rev)
A domain name is associated to the client's internet address, but the
address the name maps back to is different from the client's address.
.It 3: (strict)
The domain name that is associated to the client's internet address properly
maps back to exactly that address.
.El
.Pp
You may configure
.Nm
to reject clients not fulfilling the requirements of a particular DNS check
level by either using
.Xr vchatctl 8
or
.Xr vchat 1 .
By default all clients will be accepted regardless of their DNS check level.
.\" ------------------------------------------------------------------------
.Sh IMPLEMENTATION NOTES
The
.Nm
process will react to certain signals as follows:
.Pp
.Bl -tag -offset indent -compact
.Bl -tag -width SIGUSR1 -compact
.It Dv SIGUSR1
Causes
.Nm
to rotate the logfile (if any).
.El
.El
.\" ------------------------------------------------------------------------
.Sh FILES
The following set of files resides within the base directory of
.Nm ,
which defaults to
.Pa @DEFAULT_BASEDIR@ .
The base directory location may be changed from the default by specifying the
.Cm /BASEDIR
qualifier on the
.Nm
commandline:
.Pp
.Bl -tag -width @prefix@/etc/vserver.acl -compact
.It Pa acl.db
Access control list database.
.It Pa lastlog.db
Lastlog database.
.It Pa options
Stored server option setup.
.It Pa topic.db
Fixed channel topics database.
.It Pa user.db
User database.
.It Pa vctl
Server control socket.
.It Pa vserver.pid
Server process ID file.
.It Pa welcome.txt
Welcome banner text file.
.El
.Pp
If file based logging has been enabled by specifying the
.Cm /LOGFILE
qualifier on the
.Nm
commandline without any argument, then log output will by default be
written to the file
.Pa /var/log/vserver.log .
.\" ------------------------------------------------------------------------
.Sh COMPATIBILITY
The commandline syntax has been completely redesigned as of
.Nm
2.43a.
.Pp
As of
.Nm
2.43a file and syslog based logging are no longer mutually exclusive. So
specifying both,
.Cm /LOGFILE
and
.Cm /SYSLOG
will cause log output to be written to the logfile *and* to
.Xr syslog 3 .
.\" ------------------------------------------------------------------------
.Sh SEE ALSO
.Xr vchatctl 8 ,
.Xr vchat 1 ,
.Xr vchatd 8
.\" ------------------------------------------------------------------------
.Sh STANDARDS
The @PACKAGE_NAME@
.Nm
is expected to conform to the VChat protocol specification revision 4-11.
.\" ------------------------------------------------------------------------
.Sh HISTORY
The VChat conference server
.Nm
first appeared in 1993.
.\" ------------------------------------------------------------------------
.Sh AUTHORS
.An "Andreas S. Wetzel" Aq mickey@enforcer.cc
.\" ------------------------------------------------------------------------
.Sh BUGS
The current implementation of
.Nm
is single-threaded, which makes it potentially more vulnerable to denial of service
attacks, though this is not a
.Nm
specific problem. If this is of concern for you, then you should take
precautions by putting into operation a mechanism to limit the number of
TCP setup requests per time, that is passed through to
.Nm .