VChat conference server and control utility installation notes: =============================================================== This file was last revised on: $Id: INSTALL,v 1.11 2006/08/07 13:21:25 mickey Exp $ I. Installation checklist: ----------------------------- [ ] 1. Bourne shell or compatible installed [ ] 2. C compiler installed (gcc recommended) [ ] 3. make installed (either some pmake variant or GNU make should suffice) [ ] 4. GNU autoconf 2.59 or higher installed (only required when you retrieved the CVS version of this software via CVSup) II. Building and installing: ------------------------------ 1. In case you retrieved the CVS version of this software from a CVSup server you will first have to run 'autoheader' and then 'autoconf' from within the distribution directory in order to generate the configure script. This requires GNU autoconf 2.59 or higher to be installed on your system. Since the configure script is the generated output of other files, it is not included in the CVS version of this software. If you have downloaded this software in form of a package, then you should already have the configure script and may directly proceed with the next step. 2. Run './configure --help" from within the distribution directory to see a list of configuration options that may be specified as arguments to the configure script. The most commonly used option is the --prefix option that may be used to specify an alternate installation base directory. 3. If you need to specify any environment variables that influence the build process, like special CFLAGS, set them up now. 4. Run './configure' with any arguments that you may need from within the distribution directory. The configure script will try to determine various characteristics of your operating system and configure the software accordingly. 3. When the configure script was successfully completed, type 'make' within the distribution directory. This will compile the software. 4. If you need to switch to a privileged user for installing the software into the right places, do this now. 5. You may now install the software and manual pages by typing 'make install' from within the distribution directory. Congratulations! You've successfully installed the software. You should now visit section IV of this document for instructions on completing the necessary post-installation steps. III. Other make targets: -------------------------- The following other make targets are available from within the distribution directory: 1. Typing 'make clean' will remove all targets and intermediate object files that were created as a result of compiling the correspondig C source files. 2. Typing 'make distclean' will remove all files that were created during the process of configuring and building the software. This is equivalent to resetting the distribution directory to it's initial state. 3. Typing 'make develclean' will remove *all* intermediate target and object files as well as files that were generated by autoconf. *WARNING* You will definately need an installed version of GNU autoconf to get things back going in your distribution directory after doing a 'make develclean'. You have been warned! 4. Typing 'make uninstall' will remove the installed targets and manual pages from your system. IV. Post-Installation Notes: ------------------------------- If you are installing this software for the first time, the following steps may be necessary prior to running the software in order to get a working setup. 1. Creating the user database file Before the VChat conference server vserver(8) can start into normal operations, it needs a user database file, which will contain information about users that are registered on your VChat server and the privileges you may give to them. Initially this file will only contain one user account, which receives full administrative permissions, and is the starting point for creating other user accounts later. This file may be created by using the '/CREATEUDB' commandline qualifier of vserver, i.e. vserver /CREATEUDB This will interactively create the user database file with the account you specify during this process. The user database file will be created within the vserver base directory. If you intend to use an alternate location for the base directory, then you should also specify the full pathname of your base directory location, by using the '/BASEDIR' qualifier as well, i.e. vserver /BASEDIR=/some/nonstandard/location /CREATEUDB In this case you will also need to put the correct '/BASEDIR' qualifier into your startup script (See 2. Startup script). The created user database file should be owned by the user which you intend to run vserver(8) as, and this user should have read and write permissions for the user database file, but noone else, since it contains the passwords of the users that will be using your VChat conference server. So for example you could do the following: chown vchat:vchat /usr/local/etc/vchat/user.db chmod 600 /usr/local/etc/vchat/user.db This assumes the user and group you want vserver to run as are both called 'vchat' and are already present in your /etc/passwd and /etc/group files. 2. Startup script You probably want to set up a startup script, that starts the VChat conference server at system boot time. How this can be accomplished depends on the type of operating system that you are using, since every operating system has slightly different policies on how startup scripts are usually installed and configured. FreeBSD: If you are installing this software from the FreeBSD ports collection, a startup script should already have been installed to '/usr/local/etc/rc.d/vserver.sh'. Otherwise the script 'startup-freebsd.sh' found in the 'scripts' directory of this distribution may be copied to '/usr/local/etc/rc.d/vserver.sh'. To enable the VChat conference server to be started at boot time you will have to add the following line to your '/etc/rc.conf' file: vserver_enable="YES" If you need to specify any additional commandline qualifiers to vserver when it is being started, then you may also want to add a line specifying these: vserver_flags="" To have the vserver(8) binary run as an unprivileged user ID, you have to set up a user and group to be used for this purpose. By default the user and the group are both named 'vchat' and have the UID/GID 128. Again, if you are installing from the FreeBSD ports, then this should have already been done for you. Otherwise you may create the appropriate user and group as follows: pw groupadd -n vchat -g 128 pw useradd -n vchat -u 128 -c "VChat conference service" \ -d /usr/local/etc/vchat -g vchat -s /sbin/nologin Now tell rc.conf to use this user/group to start vserver by adding the following lines to '/etc/rc.conf': vserver_user="vchat" vserver_group="vchat" NetBSD: The rc.conf meachanism used in NetBSD for control of the system startup process is very similar to that of FreeBSD but varies in some detail. A startup script,suitable for use with with NetBSD is the 'startup-netbsd.sh' script found in the 'scripts' directory of this distribution. Copy this file to '/etc/rc.d/vserver.sh' and make sure it has the read and execute permissions set. Now add the following line to your '/etc/rc.conf' file: vserver="YES" This will enable the boot script to start vserver at system boot-time. Additional commandline qualifiers to vserver(8) may be specified by also adding the following line to the '/etc/rc.conf' file: vserver_flags="" OpenBSD: OpenBSD uses an old style 'rc.local' file for starting up various local system services. To arrange for vserver being started up at boot time first insert the contents of the file 'startup-openbsd.sh' found in the 'scripts' directory of this distribution into your '/etc/rc.local' file. Then add the following lines to '/etc/rc.conf.local': vserver="YES" vserver_flags="" You may add any additional commandline qualifiers that you may want to pass to vserver(8) upon startup to the variable 'vserver_flags'. See vserver(8) for a detailed description of commandline qualifiers. IRIX: On IRIX a system tool called 'chkconfig' is used to enable, disable or show the current state of system services. You may copy the file 'startup-irix.sh' from the 'scripts' directory of this distribution to '/etc/init.d/vserver' and then use chkconfig to enable the service: chkconfig vserver on Linux (Debian): Debian Linux uses some sort of SVR4 init mechanism. You may use the 'startup-generic.sh' script from the 'scripts' directory of this distribution and copy it to the file '/etc/init.d/vserver'. Then place a symbolic link into the '/etc/rc3.d' directory that points to the script by using: ( cd /etc/rc3.d; ln -s ../init.d/vserver S99vserver ) Also make sure the file has the read and execute bits set. This may be accomplished by typing: chmod 755 /etc/init.d/vserver Linux (SuSE): SuSE Linux, like debian uses an SVR4 init mechanism, though the directory naming is slightly different. The generic startup script 'startup-generic.sh' from the 'scripts' directory of this distribution may be used for SuSE Linux. Copy this script to '/etc/init.d/vserver'. Then place a link pointing to the script into the '/etc/init.d/rc3.d' directory as follows: ( cd /etc/init.d/rc3.d; ln -s ../vserver S99vserver ) Make sure the script has proper permissions set up, so that it may be read and executed, i.e. chmod 755 /etc/init.d/vserver Linux (RedHat): RedHat Linux comes with an SVR4 style init mechanism and the 'chkconfig' utility that may be used to toggle each configured service 'on' or 'off'. The 'startup-redhat.sh' script from the 'scripts' directory of this distribution is suitable for use with RedHat Linux. Copy this file to '/etc/rc.d/init.d/vserver' and make sure it has read and execute permissions set up properly. You may now use the 'chkconfig' utility to enable the service: chkconfig --add vserver You may use chkconfig's query feature to verify that it has added the vserver service by typing: chkconfig --query | grep vserver The output should look like this: vserver 0:off 1:off 2:on 3:on 4:on 5:on 6:off Solaris: The 'startup-generic.sh' script from the 'scripts' directory of this distribution is suitable to be used with the Solaris SVR4 style init mechanism. Copy this file to '/etc/init.d/vserver' and make sure it has read and execute permission set up properly. Now place a symbolic link to the script in the directory '/etc/rc3.d' to have it started up at run level 3 e.g. after NFS filesystems have been mounted. For example: ( cd /etc/rc3.d ; ln -s ../init.d/vserver S99vserver ) Other UNIX or UNIX like operating systems: Please see your operating system documentation on how to install a boot-time startup script for network services. You may use the 'startup-generic.sh' script from the 'scripts' directory as a template in creating a suitable start up script for your operating system. This script is suitable for most UNIX operating systems and supports the standard options "start", "stop" and "restart". V. Testing the installation: -------------------------------- 1. Start up the VChat conference server vserver(8) by running the startup script you have created, usually giving it the word 'start' as an argument. For example: /usr/local/etc/rc.d/vserver.sh start 2. If there were no apparent errors during start up, then vserver(8) should now be up an running, which could be verified by using 'ps', i.e. ps -ax | grep vserver or on SVR4: ps -ef | grep vserver When everything is fine, you should now see that the vserver process is running. If you have configured vserver(8) to log it's activities by either using the /LOGFILE commandline qualifier for file based logging, or the /SYSLOG qualifier for syslog(3) based logging, then you should also see messages in the log output that tell you if the server started up successfully, or if not, to where the problem is located. 4. If you have already built and installed the VChat client software, which comes as a separate distribution package, then you may now use the vchat(1) client, to connect to your server, i.e. vchat -s -n You should use the username you specified when creating the user database file for the argument, and enter the corresponding password when being asked for. If all is well, you are now signed on to your conference server. VI. Troubleshooting: ----------------------- This section gives a brief overview of possible pitfalls that may be encountered when setting up vserver(8) and the corresponding solutions: P: When trying to start vserver, a message like this appears: vserver [CRITICAL] Failed to open user database '...' S: There is a problem with your user database file. The most common reason for this is, that you have not yet created the user database file. This can be evidenced by the error message 'No such file or directory' appearing within the context of above message. Other possibilities for this to happen are, that the user ID you are starting vserver(8) as has not sufficient privileges to access the user database file, or that the user database file does not have the proper permissions and owner set. This is probably the case, when 'Permission denied' occurs somewhere in the error message. Make sure the user database file exists (if not see IV/1 of this document on how to create it) and make sure it is owned by the user which vserver(8) will be running as. Also the file should be readable and writeable by that user and not readable or writeable by anyone else, since it contains the passwords of the users that will be using your VChat server. P: When trying to start vserver, a message like this appears: vserver [CRITICAL] Failed to initialize server control socket ... S: This is caused by vserver not being able to create a unix domain socket which is used for communications with the vserver process. Have a close look at the error message. It should give you two pieces of information: a) The pathname which was used when trying to create the socket b) The system error message that says why it could not be created. Common causes for this to happen include that one of the directories within the path used to create the socket is either not existent or not accessible by the user ID which you are running vserver as. Make sure the directory exists and is writeable by the user you are starting vserver as. P: When starting vserver, a message like this appears: vserver [CRITICAL] Failed to open lastlog database ... S: The lastlog database file which is used by vserver to record last logins of users could not be opened or created. Along with this message you should also see the full path which vserver tried to open/create the lastlog database as, as well as the system error message stating the reason why the file could not be opened/created. Make sure that the user you are running vserver as has write access to this directory, so it can create the file. P: When trying to start vserver, a message like this appears: vserver [CRITICAL] bind() returned status 48 (Address already in use) S: This problem occurs when vserver is unable to bind it's network socket, cause the address or TCP port it is trying to bind is already being used. Most commonly this happens when vserver is already running, and you try to start another instance. Another possible reason could be, that some other software is already running on your machine, that has bound a server socket to the same address and TCP port that vserver is trying to use. Make sure that no other instance of vserver is already running. If this is the case, you may want to shut it down before restarting it by either using 'vchatctl STOP SERVER' or sending the vserver process an INT, QUIT or TERM signal. If another software is using the same address and TCP port, decide which software you want to use this address/port and configure the other to use another TCP port and/or address. VII. Submitting bug reports: ------------------------------ Should you encounter any problems during the build, installation or use of this software or it's documentation, you are encouraged to submit a bug report about this problem. This will help to improve the quality of this software, and likewise raise the chances that your specific problem is being fixed in the next software release, or that you will be sent a patch for the problem even prior to the next release. Please understand, that in order to reproduce, analyze and finally fix your specific problem, concise information about your operating system, build environment and any other possibly associated circumstances is needed. Therefore it is best to take some time to submit a bug report, and to fill in all information regarding the problem you are having with the software and/or it's documentation. To submit a bug report, please visit the following URL: http://www.enforcer.cc/vchat/sendpr