written by Jens Heine
How To View The Userkeystore Contents
Troubleshooting Hints and Tipps
You probably want to run your own comserver. The comserver is the central server where all your friends will connect to. When all friends are connected with their comboards you have a private room for talking and filesharing. This documentation describes how to setup your own comserver and how to manage it. Remember that if you run your own comserver you are responsible for the usermanagement and the security!
Please read more about Java and the IAIK Library.
Create a new folder: on Windows C:\Programme\comserver (on the english version this should be C:\Programs\comserver), on Linux/Unix: /opt/comserver. Download the comserver program file and copy it to the new folder. That's it. You can start the server now from the console with: “java -jar comserver.jar”. The comserver will start in a very open mode per default. Anybody can now connect to your comserver on port 2300. Now tune the options in the configurationfile to change the comserver behaviour.
It is a good idea to have a dns name or fixed ip address for your comserver. This makes it easier for your friends to get to your comserver address. If you do not have a static ip address or dns name you can try dynamic dns (i.e. http://www.dyndns.org).
Create comserver folder (i.e. /opt/comserver) and copy jar file there. Do all the steps as root for the first time. Only if you start the comserver on a port higher than 1023 you will not have to be root.
|
cd /opt mkdir comserver cd comserver |
Download the comserver.jar file from deepx.homelinux.net
|
wget /downloads/comserver/current/comserver.jar |
Create a file called “start.sh” with this content:
|
#!/bin/sh cd /opt/comserver java -jar comserver.jar& |
Make start script executeable:
|
chmod +x start.sh |
You should run the comserver in a screen-session or background it with nohup :-) Otherwise your shell has to be left open as long as the comserver is running. But let us run the server in the shell right now. The server starts on port 2300 and 2301 per default):
|
./start.sh |
That's all. The comserver is running. If you need init scripts for the automatic start of the comserver look here.
Create comserver folder (i.e. C:\programme\comserver) and copy jar file there. Do all the steps as “windows administrator” for the first time. Only if you start the comserver on a port higher than 1023 you will not have to be administrator (I guess :)
Open a dos box and change into the comserver folder. Then type “java -jar comserver.jar”. That's all.
Another possibility is to start the comserver with a batch file. Create a file called “startcomserver.bat” with this content (please check the java paths and adjust them for your java installation!!!):
|
rem rem start comserver rem echo "Checking installed java version..." echo java -version cd c:\programme\comserver java -jar comserver.jar |
You can now double click on the batch file or start it from a dos box.
If you want to stop the comserver just delete the file “delete-me-to-stop-server” in the comserver folder. You should watch the comserver.log file or the console output for information about the comserver status. You can also stop the comserver from a comboard. Read the section “Server commands” below for more info.
There are 2 main sources to get information about the status of the comserver. First you have the logfile which is located in the comserver folder. It is called comserver.log. If you use Linux you can watch the file with:
|
tail -f comserver.log |
You can set the logging mode in the comserver.conf file to values from debug (be verbose - log all) to fatal (be quiet - only log fatal errors).
The second way is to use the comserver gui. This is an integrated programm in the comserver.jar file. It communicates with the comserver over an unencrypted tcp connection. You can start it with:
|
java -jar comserver.jar -gui |
A window will open and you have to enter the hostname of the comserver and the monitoring portnumber. The monitoring portnumber is 231 per default. You can change it in the comserver.conf file. The monitoring gui should now display detailed informations about the comserver status. The comserver gui is a read only tool. You can not start or stop the comserver with it.
The comserver is public if you start it the first time. This means that any foreign comboard user can login. You can change this in the configurationfile “comserver.conf”. Read the information for the options “allowUnauthorizedLogin” and “enableDynamicUserRegistration”.
AllowUnauthorizedLogin means that the comserver is open. Any user can login. If the option is set to false, the comserver will only let known users in. A “known user” means that the certificate from the user exists in the userkeystore from the comserver. The userkeystore is a file in the comserver folder called “userkeystore”. You can import user certificates by commandline: “java -jar comserver.jar -i peter.certificate -a peter”. The file “peter.certificate” comes from peter. This file was created in the comboard folder when peter made his userkey. It is also possible that the comserver admin creates the comboard userkeys. This has the advantage that the keys will be imported to the comserver-userkeystore and that the userkeys will be signed by the comserver. The userkeys must be signed from the comserver when comboard users wants to authenticate the comserver. The disadvantage is that the comserver admin can read the private userkey. Decide yourself.
The option “enableDynamicUserRegistration” only works if the comserver does allow unauthorized logins (see text above). If the dynamic user registration is enabled, the comserver saves a copy of all user certificates in his userkeystore if they login the first time. This is made for lazy admins :) Now tell your friends that they should start their comboards and login. If all friends have logged in once, you can disable the “AllowUnauthorizedLogin” feature again. You can do this while the comserver is running. Watch the logfile to see what is happening. The comserver reloads the configuration file if the timestamp changes. The comserver is now private. Only users which are in the userkeystore can now login. Foreign logins are dropped. The “enableDynamicUserRegistration” option has now no effect. This has the advantage that you have (hopefully) all certificates from your friends in the userkeystore and no one has to send his certificate to you and you don't have to import each user certificate in the userkeystore by hand.
Try this on the commandline in the comserver folder:
|
java -jar comserver.jar -sc |
You can also access the userkeystore with server commands...
The server command interface enables you to control the comserver from a comboard. Just type the following chat message in your comboard when you are connected to the comserver. Note that you have to be an comserver “administrator”. This means that you have to edit the file “administrators.txt” (simple text file) in the comserver folder and add your comboard username to it. You only have to add the first administrator to the file. Later you can add more admins with the server commands. Now type this in the chat text field in the comboard (notice the leading “!”):
|
!help |
You will see possible commands to execute. You can can get more help about every command like this:
|
!<command> help |
Example: If you want to list all comserver administrators you type:
|
!adminstrator list |
Example: If you want to add another user as an administrator you type:
|
!adminstrator add peter |
The comserver creates some files in the working directory.
|
melvin@deepbluex $ ls -alh insgesamt 3,2M drwxr-xr-x 2 melvin users 4,0K 19. Jul 20:36 . drwxrwxrwt 33 root root 4,0K 19. Jul 20:36 .. -rw-r--r-- 1 melvin users 12 3. Sept 23:13 administrators.txt -rw-r--r-- 1 melvin users 3,2M 18. Jul 18:14 comserver.jar -rw-r--r-- 1 melvin users 4,5K 19. Jul 20:36 comserver.conf -rw-r--r-- 1 melvin users 0 19. Jul 20:36 delete-me-to-stop-server -rw-r--r-- 1 melvin users 0 19. Jul 20:36 emailaddresses -rw-r--r-- 1 melvin users 57 19. Jul 20:36 neighbourkeystore -rw-r--r-- 1 melvin users 0 19. Jul 20:36 neighbours -rw-r--r-- 1 melvin users 2,3K 19. Jul 20:36 server.key -rw-r--r-- 1 melvin users 57 19. Jul 20:36 userkeystore |
administrators.txt – Put your username into this textfile. Everybody who is allowed to execute server commands must be in this file. Administrators also have to be known in the userkeystore.
comserver.conf - The comserver.conf file is the configuration file where we can manipulate the server. Some of the variables in the configuration file can be changed while the server is running. Just change them and save the file. The server detects that the file date has changed and reloads the new settings.
delete-me-to-stop-server – Delete this file to stop the server.
emailaddresses – The server uses this file to store the emailaddresses of comboard users if they want an emailnotification from the server if commail is waiting for them. The comserver has his own mail agent. To enable the emailnotificationsystem you have to set it in the configuration file. Set the following variables in the comserver.conf file:
emailNotificationIsEnabled=true
emailMailserver=mail.emailprovider.com
emailMailserverUsername=myEmailUsername
emailMailserverPassword=myEmailPassword
emailFromLine=myEmailAddress
neighbourkeystore – The neighbourkeystore file is used to store neighbour certificates. This feature is not ready implemented yet.
neighbours – Add comserver ip addresses of comserver neighbours here. This feature is not ready implemented yet.
server.key – This is the server keystore file. The server key and the certificate are stored here.
userkeystore – If the server is running in private mode (variable in comserver.conf file: allowUnauthorizedLogin=false), the server accepts only connections from known users. “Know users” means for the server that he has the certificate of the user in his userkeystore.
Commandline options
Try the "-?" argument for more info about the comserver. Enter this on the commandline:
|
java -jar comserver.jar -? |
Login not possible
If you can not connect to the comserver with your comboard it can have several reasons.
The comboard has a wrong comserver address or port number.
The comboard has switched comserver authorisation on and the comserver is not the issuer of the comboard userkey.
The comserver has switched AllowUnauthorizedLogin off and the comboard user certificate is not known in the comservers userkeystore.
A comboard user has made himself a new/second userkey (and certificate) with his old username but there is an old certificate in the comservers userkeystore which is alread associated with the username. In this case the comserver admin has to delete the old certificate from the userkeystore: “java -jar comserver.jar -d peter”. Now the new certificate has to be imported into the userkeystore: “java -jar comserver.jar -i peter.certificate -a peter”. Or you make the comserver public (see AllowUnauthorizedLogin option) and enable the dynamic user registration.
A certificate has expired.
The comserver is not running
A firewall is blocking the line between comboard and comserver
Some options can not be found in the configuration file
If you have updated your comserver with a newer version and you start the new version, the old configuration file is used but not updated with new options. If you want to have a current configuration file, go to a different folder, copy the comserver.jar file there and enter:
|
java -jar comserver.jar -cc |
Then you can merge the differences between the old configuration file and the new one which has probably new options. Another way is to delete the old configuration file and start the new comserver. If there is no configuration file, a new one will be created automatically.
Unix/Linux
If you run a unix/linux system you may want to start/stop the server in some runlevels and you may want to create an init script. I run a linux system and I made some scripts for myself (Look in the download section for these and some more scripts). They work fine for me. If you have a good script you also may send it to me.
Windows
If you run a windows system it may be possible that you just have to douple click on the comserver.jar file and it will be startet. I would prefer to write a tiny batch file which will be executed when the computer is started. To do this you can use the autostart feature from windows. It is also possible to run the comserver as a service under NT-style systems like nt, w2k or xp. If you have experiences with running a comserver under windows please send them to me and I will fill up this dcoumentation.
How do your users find your comserver ip address?
If your friends want to connect to your server they will have to know your computers ip address. We recommend 2 ways of doing this. First you can register to a free dynamic dns service (i.e. dyndns.org). Than your friends only have to know your url. Second way is to copy your ip address and the comserver port to a file on a website. There is a script in the download section for linux which will do that for you (ip-uploader). There is also a programm for windows in the download section ("flatserver"). In both cases your friends have to check the checkbox "search comserver information under this url" in the comboard options.They have to put the url where you put your current ip-address-file in the textfield below the checkbox.
Firewalls
The comserver can be forwarded through firewalls. Just forward a firewall tcp port to your internal comserver listener port (for example: firewall:2300 to internal comserver-host:2300).
Slow machines
If you have a slow machine and you get timeouts you should try using a 512 bit key for the server.