This is the readme to the Lan Information Server LISa and the Restricted LAN
Information Server resLISa.

+---------------+
|     LISa      |
+---------------+

LISa is intended to provide a kind of "network neighbourhood" but only
relying on the TCP/IP protocol stack, no smb or whatever.
In the configuration file you provide a range of IP-addresses which
LISa should check, wether they are running. In the most simple case
this could be your network address/subnetmask, then LISa would
check every host of your network wether it is running.
The list of running hosts is then provided via TCP port 7741.
The hosts are checked using ICMP echo requests. To be able to send and receive
ICMP echo requests and replies the program has to open a so-called
"raw socket". Therefor it needs root privileges. This socket is opened
right after the start of the program, after successfully opening the socket
root privileges are dropped immediatly (see main.cpp and strictmain.cpp).
Since so many ICMP requests can cause some network traffic if there
are more than one such server running in one network, the servers
cooperate with each other. Before they start pinging, they send a broadcast
on port 7741. If somebody answers to this broadcast, they will receive
the complete list via TCP port 7741 from this host and will not
start to ping theirselves. If nobody answers, the host which sent the broadcast
will start checking the hosts and then open a socket which listens
for the mentioned broadcasts. If the host received an answer to his broadcast,
it won't have the socket for listening to the broadcasts open. So
usually exactly one of the servers will have this socket open and only
this one will actually ping the hosts. They work like "I will only
do it if nobody else can do it for me".
This way it is possible that many hosts in a network run this server, but
the net load will remain low. For the user it is not neccessary to know
wether there is a server (i.e. a name server or fileserver or whatever)
in the network which also runs LISa. He can always run LISa locally
and LISa will detect if there is one, transparently to the user.
The first client for LISa is an ioslave for KDE2, so the user
can enter there lan://localhost/ or lan:/, which will both
contact LISa on the own system.
If there is a machine which runs all the time and the user knows
that this machine also runs LISa, he can use with his LISa-client directly
this server (would be with the mentioned ioslave lan://the_server_name/).

If you don't want that your LISa takes part in the broadcasting, but always
pings itself, make it use another port with the
command line option --port or -p.
This is not recommended !

If you send SIGHUP to LISa, it will reread its configfile.
If you send SIGUSR1 to LISa, it will print some status information to stdout.

If there are very strict security rules in your network, some people
might consider the pinging as an potential attack. If you
have problems with this, try the restricted version, resLISa.

Now an example config file:
PingAddresses = 192.168.100.0/255.255.255.0;192.168.200.10-192.168.200.20;192.168.200.1
PingNames = bb_mail;
AllowedAddresses = 192.168.0.0/255.255.0.0
BroadcastNetwork = 192.168.100.0/255.255.255.0
FirstWait = 30                          #30 hundredth seconds
SecondWait = -1                         #only one try
#SecondWait = 60                         #try twice, and the second time wait 0.6 seconds
UpdatePeriod = 300                      #update after 300 secs
DeliverUnnamedHosts = 0                 #don't publish hosts without name
MaxPingsAtOnce = 256                    #send up to 256 ICMP echo requests at once


The first line says which IP-addresses will be pinged.
The first partsays that all addresses in 192.168.100.0 with
subnetmask 255.255.255.0 will be pinged (i.e. 192.168.100.0 to
192.168.100.254), the second part says that additionally the addresses
192.168.200.10 to 192.168.200.20 will be pinged, and last but not least also
192.168.200.1 will be pinged. The lines must not contain whitespace between the
IP-addresses. In the next line ("PingNames") you can add additional hosts
by their name, also divided by semicolons ;
In this name the host named "bb_mail".

The line "AllowedAddresses" is very important. LISa will only ping addresses,
accept clients and answer broadcasts from addresses, which are covered by the
addresses given in this line. You can add up to 32 network addresses/network masks
or single addresses. Divide them by ; and don't put empty space between the
addresses !

In the given example all addresses from 192.168.0.0 up to
192.168.255.255 are valid. This is a very wide range, you should use a
stricter address range.

The next line contains exactly one network address/subnet mask.
To this network broadcasts will be sent. Usually this should be your
own networkaddress/subnetmask.

After LISa sent the ICMP echo requests, it waits a short moment for the answers.
In FirstWait you can specify in hundredth seconds, how long it will
wait. Try with values from 5 to 50 hundredth seconds.
If all hosts are found, you can set SecondWait to -1, then LISa will
send the pings only once, if you set SecondWait to something
bigger than 0, LISa will send the pings a second time, but only to the hosts
from which it received no answer yet. Since this are probaly slow hosts, it
will probably be useful to set SecondWait to a bigger value than
FirstWait. The maximum is 99 (almost a whole second).

UpdatePeriod is the number of seconds after which LISa will start to search
for hosts again (first broadcasting, then if required pinging).

With DeliverUnnamedHosts you can enable or disable, wether LISa will
also publish the hosts, which have no name assigned. This might
probably be some routers or servers or bridges or whatever. At
least these hosts probably have a reason for having no name, so
it might be a security point to disable this setting.

The last line MaxPingsAtOnce says how much ICMP echo requests
will be sent most at once. 256 should be OK, you can't increase it
very much, maybe a little bit, but you could try to make it smaller
and see wether it works better. Usually you can keep 256.


+------------------+
|     resLISa      |
+------------------+

If you hav very strict security rules in your network or you don't want to
have another port open or whatever, you can use resLISa. 

With resLISa you can't ping whole networks and address ranges, you can give
resLISa up to currently 64 hosts by their names in its config file. These
will be pinged.
resLISa will also only provide the information over a unix domain socket, i.e.
not over the network. The name of the socket is "/tmp/resLisa-YourLoginname",
so resLISa can be savely run by more users on one machine.
Since it should also not produce a security risk of any kind it is
safe to install reslisa setuid root. root privileges will be dropped
right after startup (see strictmain.cpp).
It will also not send or receive broadcasts.
Maybe it then actually works a bit more like ICQ.
The first client for this is also an ioslave for KDE2 (makes rlan:/ in e.g. konqy).

And now a configuration file for resLISa:

PingAddresses = 192.168.100.0/255.255.255.0;192.168.200.10-192.168.200.20; 192.168.200.1
PingNames = bb_mail;some_host;some_other_host
AllowedAddresses = 192.168.0.0/255.255.0.0
BroadcastNetwork = 192.168.100.0/255.255.255.0
FirstWait = 30                          #30 hundredth seconds
SecondWait = -1                         #only one try
#SecondWait = 60                         #try twice, and the second time wait 0.6 seconds
UpdatePeriod = 300                      #update after 300 secs
DeliverUnnamedHosts = 1                 #also publish hosts without name
MaxPingsAtOnce = 256                    #send up to 256 ICMP echo requests at once


As mentioned the line "PingAddresses" will be ignored, only the PingNames
will be used. The line "BroadcastNetwork" will be also ignored, since
resLISa doesn't send braodcasts.


For info about command line switches enter lisa -h and reslisa -h,
you should do this, since it contains some additional information.

LISa and resLISa need a libstdc++ (it uses only the string-class from it),
it *doesn't* need neither Qt nor KDE.

So, that's it for now.
If you have suggestions, problem or whatever, contact me.

Have fun
Alexander Neundorf
<neundorf@kde.org>

