| blob | c6d5d1bdb9978e03a5964d618ff1b7322aa8a726 |
1 This is the readme to the Lan Information Server LISa and the Restricted LAN
2 Information Server resLISa.
4 +---------------+
5 | LISa |
6 +---------------+
8 LISa is intended to provide a kind of "network neighbourhood" but only
9 relying on the TCP/IP protocol stack, no smb or whatever.
10 It is completely independent from KDE/Qt.
11 The list of running hosts is provided via TCP port 7741.
13 LISa supports two ways of finding hosts:
15 1. you give LISa a range of of IP-addresses, then LISa will send
16 ICMP echo requests to all given IP addresses and wait for the answers
18 2. you can say LISa to execute "nmblookup "*" ", i.e. the command line tool
19 nmblookup must be installed, it is part of the samba package.
20 nmblookup "*" sends a broadcast to the attached networks and all hosts
21 running smb-services will answer this broadcast
23 lisa and reslisa are distributed under the GNU General Public License.
27 How it works
28 -------------
30 In the configuration file you provide a range of IP-addresses which
31 LISa should check, wether they are running. In the most simple case
32 this could be your network address/subnetmask, then LISa would
33 check every possible host of your network wether it is running.
34 The hosts are checked using ICMP echo requests. To be able to send and receive
35 ICMP echo requests and replies the program has to open a so-called
36 "raw socket". Therefor it needs root privileges. This socket is opened
37 right after the start of the program, after successfully opening the socket
38 root privileges are dropped immediately (see main.cpp and strictmain.cpp).
39 If you configure LISa this way, that it also uses nmblookup, it will
40 popen("nmblookup \"*\"") and then parse the results.
42 Since the ICMP requests and the broadcasts can cause some network traffic
43 if there are more than one such server running in one network, the servers
44 cooperate with each other. Before they start pinging (or nmblookup),
45 they send a broadcast on port 7741.
46 If somebody answers this broadcast, they will retrieve the complete list
47 of running hosts via TCP port 7741 from this host and will not start to
48 ping (or nmblookup) theirselves. If nobody answers, the host which sent
49 the broadcast will start pinging the hosts (or nmblookup) and then open a
50 socket which listens for the mentioned broadcasts. If the host received an
51 answer to his broadcast, it won't have the socket for listening to the
52 broadcasts open. So usually exactly one of the servers will have this
53 socket open and only this one will actually ping (or nmblookup) the hosts.
54 In other words, the servers are lazy, they work like "I will only do something
55 if nobody else can do it for me".
57 There is another feature which reduces the network load. Let's say you configured LISa
58 to update all 10 minutes. Now you don't access your server very often.
59 If nobody accesses the server for the last update period, the server will
60 update (either itself or from the one which actually does the work) and then
61 double its update period, i.e. the next update will happen after 20 minutes.
62 This will happen 4 times, so if nobody accesses the server with update period
63 10 minutes for a long time, its update interval will increase up to
64 160 minutes, almost three hours. If then somebody accesses the data from the
65 server, he will get an old list ( up to 160 minutes old). With accessing
66 the server will reset its update interval to its initial value,
67 i.e. 10 minutes and immediately start updating if the last update is more
68 than these 10 minutes over. This means if you get a very old list, you can try
69 some seconds later again and you should get a current version.
70 This will have fast effect for the servers, which don't ping (or nmblookup)
71 theirselves, since only one user usually accesses them, and it will have
72 less effect for the server which does the pinging (or nmblookup), since
73 this server is accessed from all other servers in the network.
76 This way it is possible that many hosts in a network run this server, but
77 the net load will remain low. For the user it is not necessary to know
78 wether there is a server (i.e. a name server or fileserver or whatever)
79 in the network which also runs LISa. He can always run LISa locally
80 and LISa will detect if there is one, transparently to the user.
81 The first client for LISa is an ioslave for KDE2, so the user
82 can enter there lan://localhost/ or lan:/, which will both
83 contact LISa on the own system.
84 If there is a machine which runs all the time and the user knows
85 that this machine also runs LISa, he can use his LISa client directly with
86 this server (would be with the mentioned ioslave lan://the_server_name/).
88 If you don't want that your LISa takes part in the broadcasting, but always
89 does the pinging itself, make it use another port with the
90 command line option --port or -p.
91 This is not recommended !
93 If you send SIGHUP to LISa, it will reread its configfile.
94 If you send SIGUSR1 to LISa, it will print some status information to stdout.
96 The data provided over the socket has a simple format:
98 <decimal ip address in network byte order><one space 0x20><full name of the host><a terminating '\0'><newline '\n'>
99 and the last line
100 0 succeeded<'\n'>
102 e.g.
104 "17302538 some_host.whatever.de
105 18285834 linux.whatever.de
106 17827082 nameserver.whatever.de
107 0 succeeded
108 "
110 This should make it easy parseable.
112 If there are very strict security rules in your network, some people
113 might consider the pinging a potential attack. If you
114 have problems with this, try the restricted version, resLISa.
116 +------------------+
117 | resLISa |
118 +------------------+
120 If you hav very strict security rules in your network or you don't want to
121 have another port open or whatever, you can use resLISa.
123 With resLISa you can't ping whole networks and address ranges, you can give
124 resLISa up to currently 64 hosts by their names in its config file. These
125 will be pinged. You are still able to use nmblookup.
126 resLISa will also only provide the information over a unix domain socket, i.e.
127 not over the network. The name of the socket is "/tmp/resLisa-YourLoginname",
128 so resLISa can be safely run by more users on one machine.
129 Since it should also not produce a security risk of any kind it is
130 safe to install reslisa setuid root. root privileges will be dropped
131 right after startup (see strictmain.cpp), they are only needed to create a raw socket
132 for sending the ICMP echo requests..
133 It will also not send or receive broadcasts.
134 The first client for this is also an ioslave for KDE2 (makes rlan:/ in e.g. konqy).
138 Configuration
139 -------------
141 Now an example config file:
143 PingAddresses = 192.168.100.0/255.255.255.0;192.168.100.10-192.168.199.19;192.168.200.1;192-192.168-168.100-199.0-9;
144 PingNames = bb_mail;
145 AllowedAddresses = 192.168.0.0/255.255.0.0
146 BroadcastNetwork = 192.168.100.0/255.255.255.0
147 SearchUsingNmblookup = 1 #also try nmblookup
148 FirstWait = 30 #30 hundredth seconds
149 SecondWait = -1 #only one try
150 #SecondWait = 60 #try twice, and the second time wait 0.6 seconds
151 UpdatePeriod = 300 #update after 300 secs
152 DeliverUnnamedHosts = 0 #don't publish hosts without name
153 MaxPingsAtOnce = 256 #send up to 256 ICMP echo requests at once
156 PingAddresses
158 This is probably the most important entry.
159 Here you say which addresses will be pinged. You can specify multiple
160 ranges, they are divided by semicolons.
162 There are four possible ways to define addresses:
163 -net address/network mask: 192.168.100.0/255.255.255.0, i.e. an IP address
164 and the assigned network mask. This doesn't have the real network address
165 and netmask of your machine, it can be less. E.g. if you have
166 10.0.0.0/255.0.0.0, you could specify 10.1.2.0/255.255.255.0 if you are only
167 interested in these addresses. The combination IP address-network mask
168 must be divided by a slash "/" and the address does not have to be a real
169 network address, it can also be a host address of the desired network,
170 i.e. 10.12.34.67/255.0.0.0 is the same as 10.0.0.0/255.0.0.0 .
172 -a range of following IP addresses: 192.168.100.10-192.168.199.19, i.e.
173 an IP-address where pinging will start and an IP-address where pinging will end.
174 Both addresses must be divided by a "-".
175 In this example this would produce 199-100+1=100, 100*256=25.600,
176 25.600+(19-10+1)=25.590 addresses
178 -an IP-address can be presented by its four decimal numbers, you can specify
179 ranges four each of these four numbers: 192-192.169-171.100-199.0-9
180 In this example all IP addresses with first number 192, second number from
181 168 to 168, third number from 100 up to 199 and last number from 0 up
182 to 9 will be pinged. This would give 1*1*100*10=1.000 addresses.
183 This is probably only useful in very seldom cases.
184 Here you have to provide ranges for every four numbers, always divided
185 by "-".
187 -single IP-addresses: 192.168.200.1
188 well, single IP addresses or host names
190 It is also valid to leave this entry empty.
193 PingNames
194 here you can additionally specify hosts to ping using their names.
195 The names have to be divided by semicolons.
197 It is also valid to leave this entry empty.
200 AllowedAddresses
202 This is also very important. LISa will only ping addresses,
203 accept clients and answer broadcasts from addresses, which are covered by the
204 addresses given in this line. You can add up to 32 network addresses/network masks
205 or single addresses. Divide them by ; and don't put empty space between the
206 addresses !
207 Example: 192.168.0.0/255.255.0.0;192.169.0.0
208 -> a complete network and a single address are valid
209 Always make this as strict as possible, usually
210 your network address/subnetmask is a good choice.
213 BroadcastNetwork
215 This entry contains exactly one network address/subnet mask.
216 To this network broadcasts will be sent. Usually this should be your
217 own network address/subnetmask.
218 Example: 192.168.0.0/255.255.0.0
221 SearchUsingNmblookup
223 Here you can give 0 or 1.
224 1 means that LISa will execute "nmblookup "*" " and parse the output
225 from this command. This produces less network traffic than the pinging,
226 but you will only get hosts which have a smb-service running (Windows
227 machines or machines running samba).
228 If you enable this option and also give IP addresses to ping, then nmblookup
229 will be executed first and then the pinging will start.
230 Then only addresses will be pinged, which were not already delivered
231 from nmblookup. This should slightly decrease the network load.
234 FirstWait
236 If LISa pings, i.e. if it sends the ICMP echo requests, it sends a bunch
237 of requests at once, and the it will wait for the number of hundredth seconds
238 you specify here. Usually values from 5 to 50 should be good, the maximum
239 is 99 (gives 0.99 seconds, a very long time).
240 Try to make this value as small as possible while still finding all
241 running hosts.
244 SecondWait
246 After LISa sent the echo requests the first time, it can be possible
247 that some hosts were not found. To improve the results, LISa can ping a
248 second time. This time it will only ping hosts, from which it didn't receive
249 answers. If you have good results with pinging only once, you can disable
250 the second time with setting SecondWait to -1.
251 Otherwise it might be a good idea to make this value a little bit bigger
252 than the value for FirstWait, since the hosts which were not found
253 on the first try, are probably slower or further away so they might take
254 some milliseconds longer to answer.
255 Usually values from 5 to 50 should be good or -1 to disable the second scan.
256 The maximum is 99 (gives 0.99 seconds, a very long time).
259 UpdatePeriod
261 This is the interval after which LISa will update, i.e. ping or nmblookup
262 or get the list of hosts from the LISa server which actually does the pinging.
263 Valid values are between 30 seconds and 1800 seconds (half an hour).
264 If you have a big network, don't make the interval to small (to keep
265 network load low). Values from 300 to 900 seconds (5 to 15 minutes) might be
266 a good idea. Keep in mind that the update period is doubled
267 if nobody accesses the server, up to 4 times, so the interval will become
268 16 times the value given here and will be reseted to the value given here
269 if somebody accesses the server.
272 DeliverUnnamedHosts
274 If an answer to an echo request from an IP address was received, were LISa
275 could not determine a name, it will be only delivered over the port
276 if you set this to 1.
277 I am not really sure if this is a useful feature, but maybe
278 there are some infrastructure devices in your network without assigned names,
279 so they don't have to be published. Set this to 0 if you want to keep them
280 secret ;-)
281 If unsure, say 0.
283 MaxPingsAtOnce
285 When sending the pings (echo requests), LISa sends a bunch of these at once
286 and then waits for the answers. By default there are 256 pings sent at once,
287 usually you should not need the change this value. If you make it much bigger,
288 the internal receive buffers for the answers to the echo requests may become to small,
289 if you make it to small, the updating will be slower.
292 Three different example config files:
294 You are member of a small network with 24 bit network mask, i.e.
295 up to 256 hosts:
297 PingAddresses = 192.168.100.0/255.255.255.0
298 AllowedAddresses = 192.168.100.0/255.255.255.0
299 BroadcastNetwork = 192.168.100.0/255.255.255.0
300 SearchUsingNmblookup = 0 #don't use nmblookup
301 FirstWait = 20 #20 hundredth seconds
302 SecondWait = 30 #30 hundredth seconds on the seconds try
303 UpdatePeriod = 300 #update after 300 secs
304 DeliverUnnamedHosts = 0 #don't publish hosts without name
307 You are only interested in hosts running smb services and you don't have
308 routers in your network:
310 AllowedAddresses = 192.168.100.0/255.255.255.0
311 BroadcastNetwork = 192.168.100.0/255.255.255.0
312 SearchUsingNmblookup = 1 #use nmblookup
313 UpdatePeriod = 300 #update after 300 secs
314 DeliverUnnamedHosts = 0 #don't publish hosts without name
317 The same network, but here both nmblookup and pinging is used.
319 PingAddresses = 192.168.100.0/255.255.255.0
320 PingNames = bb_mail
321 AllowedAddresses = 192.168.0.0/255.255.0.0
322 BroadcastNetwork = 192.168.100.0/255.255.255.0
323 SearchUsingNmblookup = 1 #also try nmblookup
324 FirstWait = 30 #30 hundredth seconds
325 SecondWait = -1 #only one try
326 #SecondWait = 60 #try twice, and the second time wait 0.6 seconds
327 UpdatePeriod = 300 #update after 300 secs
328 DeliverUnnamedHosts = 0 #don't publish hosts without name
329 MaxPingsAtOnce = 256 #send up to 256 ICMP echo requests at once
331 And now a configuration file for resLISa, PingAddresses is not used by resLISa,
332 neither is BroadcastNetwork.
334 PingNames = bb_mail;some_host;some_other_host
335 AllowedAddresses = 192.168.0.0/255.255.0.0
336 SearchUsingNmblookup = 1 # use nmblookup
337 FirstWait = 30 #30 hundredth seconds
338 SecondWait = -1 #only one try
339 #SecondWait = 60 #try twice, and the second time wait 0.6 seconds
340 UpdatePeriod = 300 #update after 300 secs
341 DeliverUnnamedHosts = 1 #also publish hosts without name
342 MaxPingsAtOnce = 256 #send up to 256 ICMP echo requests at once
345 +----------------------+
346 | Installation |
347 +----------------------+
349 Both reslisa and lisa open a so called raw socket to send and receive
350 ICMP echo requests (pings). To do this, they need root privileges.
352 lisa offers a service on TCP port 7741, it should be installed by root
353 and started when the system comes up, it depends on your distribution
354 how to do this.
356 reslisa is intended to be started per user, it doesn't offer anything to
357 the network. It needs to be installed setuid root.
359 If you use the rlan-ioslave from KDE2, reslisa can be started automatically
360 by reslisa.
362 lisa reads the file lisarc, reslisa reads the file reslisarc.
363 If you want to be able to configure both from the KDE Control Center,
364 you have to start them using the command line switch -K.
366 For more information where they look for configuration files read
367 the next chapter.
370 +--------------------------------------------+
371 | Command Line Options and other usage |
372 +--------------------------------------------+
374 The following command line options are supported:
376 -v, --version prints a short version info
377 -h, --help gives an overview over teh command line options
379 Some options regarding search order for the configuration files.
380 For reslisa the file is named reslisarc instead lisarc.
382 -u, --unix search at first for $HOME/.lisarc, then
383 for /etc/lisarc, this is the default behaviour
385 -k, --kde1 search at first for $HOME/.kde/share/config/lisarc,
386 then for $KDEDIR/share/config/lisarc
388 -K, --kde2 looks for the file lisarc in every directory
389 returned by running "kde-config --path config"
391 -c, --config=FILE read this and no other configuration file
394 This one is only available for LISa, not for resLISa.
396 -p, --port PORTNR start the server om this portnumber
397 if you use this LISa won't be able to
398 cooperate with other LISa's in the network
401 If you send the Hangup-Signal to lisa or reslisa, it will reread its
402 configuration file (killall -HUP lisa).
404 If you send the User1-Signal to lisa or reslisa, it will print some status
405 information to the standard output (killall -USR1 lisa). You won't see
406 anything if the console from which lisa/reslisa was started has terminated.
409 LISa and resLISa need a libstdc++ (it uses only the string-class from it),
410 it *doesn't* need neither Qt nor KDE.
412 So, that's it for now.
413 If you have suggestions, problems or whatever, contact me.
416 Have fun
417 Alexander Neundorf
418 <neundorf@kde.org>