From bcb704366cb5e333a626c18c308c7e0448a8e69f Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdenetwork@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/lisa/Makefile.am | 4 + doc/lisa/index.docbook | 694 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 698 insertions(+) create mode 100644 doc/lisa/Makefile.am create mode 100644 doc/lisa/index.docbook (limited to 'doc/lisa') diff --git a/doc/lisa/Makefile.am b/doc/lisa/Makefile.am new file mode 100644 index 00000000..085981d9 --- /dev/null +++ b/doc/lisa/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/lisa/index.docbook b/doc/lisa/index.docbook new file mode 100644 index 00000000..d93e31d5 --- /dev/null +++ b/doc/lisa/index.docbook @@ -0,0 +1,694 @@ + +LISa"> + + resLISa"> + + + +]> + + + + + +The &lisa; Handbook + + + +Alexander +Neundorf + +
neundorf@kde.org
+ + + + + + + + +2001 +Alexander Neundorf + + +2001-07-07 +0.01.00 + + +&lisa; is intended to provide a kind of network +neighborhood, but only relying on the TCP/IP protocol stack, no +SMB or anything else required. + +This is the handbook to both the LAN +Information Server (&lisa;) and the Restricted LAN +Information Server (&reslisa;) + + + + +KDE +kdenetwork +LAN +network +network neighborhood + + + + + +Introduction + +&lisa; is intended to provide a kind of network +neighborhood, but only relying on the TCP/IP protocol stack, no +smb or whatever. + +It is completely independent from &kde;/&Qt;. + +The list of running hosts is provided via TCP +port 7741. + +&lisa; supports two ways of finding hosts: + + + +You give &lisa; a range of IP addresses, then +&lisa; will send ICMP echo requests to all given +IP addresses, and wait for the answers. + + +You can tell &lisa; to execute nmblookup +. The command line tool +nmblookup must be installed from the Samba package. +nmblookup sends a broadcast to +the attached networks, and all hosts running SMB +services will answer this broadcast. + + + + + + + +How it works + +In the configuration file you provide a range of IP-addresses +which &lisa; should check to see whether they are running. + +In the most simple case this could be your network +address/subnetmask, then &lisa; would check every possible host of your +network to see if it is running. + +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. Therefore it needs root privileges. This socket is opened +right after the start of the program, after successfully opening the +socket root privileges are dropped immediately (see +main.cpp and +strictmain.cpp). + +If you configure &lisa; so that it also uses +nmblookup, it will popen("nmblookup +\"*\"") and then parse the results. + +Since the ICMP requests and the broadcasts 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 (or nmblookup), they send a +broadcast on port 7741. + +If somebody answers this broadcast, they will retrieve the +complete list of running hosts via TCP port 7741 from +this host and will not start to ping (or +nmblookup). + +If nobody answers, the host which sent the broadcast will start +pinging the hosts (or nmblookup) 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 (or +nmblookup) the hosts. + +In other words, the servers are lazy, they work like I will +only do something if nobody else can do it for me. + +There is another feature which reduces the network load. + +Let's say you configured &lisa; to update every 10 minutes. Now +you don't access your server very often. If nobody accesses the server +for the last update period, the server will update (either itself or +from the one which actually does the work) and then double its update +period, &ie; the next update will happen after 20 minutes. + +This will happen 4 times, so if nobody accesses the server with +update period 10 minutes for a long time, its update interval will +increase up to 160 minutes, almost three hours. If then somebody +accesses the data from the server, he will get an old list ( up to 160 +minutes old). With accessing the server will reset its update interval +to its initial value, &ie; 10 minutes and immediately start updating if +the last update is more than these 10 minutes over. This means if you +get a very old list, you can try some seconds later again and you should +get a current version. + +This will have fast effect for the servers, which don't ping (or +nmblookup) theirselves, since only one user usually accesses them, and +it will have less effect for the server which does the pinging (or +nmblookup), since this server is accessed from all +other servers in the network. + +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 +necessary to know wether there is a server (&ie; 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 &kde; 2, 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 his &lisa; client +directly with 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 does the pinging itself, make it use another port with the +command line option or . 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. + +The data provided over the socket has a simple format: + +<decimal ip address in network byte order><one space +0x20><full name of the host><a terminating +'\0'><newline '\n'< +and the last line +0 succeeded<'\n'> + + +For example, + +17302538 some_host.whatever.de +18285834 linux.whatever.de +17827082 nameserver.whatever.de +0 succeeded + +This should make it easy parseable. + +If there are very strict security rules in your network, some +people might consider the pinging a potential attack. If you have +problems with this, try the restricted version, &reslisa;. + + + + +&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. You are still able to use +nmblookup. + +&reslisa; will also only provide the information over a unix +domain socket, &ie; not over the network. The name of the socket is +/tmp/resLisa-YourLoginname so &reslisa; can be +safely 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), they are only +needed to create a raw socket for sending the ICMP +echo requests. + +It will also not send or receive broadcasts. The first client for +this is also an ioslave for &kde; 2 (rlan:/ in +&konqueror; for example.) + + + + +The Configuration File + +Now an example config file: + + +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; +PingNames = bb_mail; +AllowedAddresses = 192.168.0.0/255.255.0.0 +BroadcastNetwork = 192.168.100.0/255.255.255.0 +SearchUsingNmblookup = 1 #also try nmblookup +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 + + + +<option>PingAddresses</option> + +This is probably the most important entry. + +Here you say which addresses will be pinged. You can specify +multiple ranges, they are divided by semicolons. + +There are four possible ways to define addresses: + + + +net address/network mask + +192.168.100.0/255.255.255.0, &ie; an IP address + and the assigned network mask. + +This doesn't have to be the network address and netmask of your +machine. For example, if you have 10.0.0.0/255.0.0.0 as your own +address, you could specify 10.1.2.0/255.255.255.0 if you are only +interested in these addresses. The combination IP +address-network mask must be divided by a slash / and the +address does not have to be a real network address, it can also be a +host address of the desired network, &ie; 10.12.34.67/255.0.0.0 is the +same as 10.0.0.0/255.0.0.0 . + + + + +a range of IP addresses + +For example: 192.168.100.10-192.168.199.19 + +An IP-address where pinging will start and an +IP-address where pinging will end. + +Both addresses must be divided by a -. + +In this example this would produce 199-100+1=100, 100*256=25.600, +25.600+(19-10+1)=25.590 addresses + + + + +An IP address, as represented by ranges of each +of the four decimal numbers + +An IP address can be represented by its four +decimal numbers, and you can specify ranges four each of these four +numbers: 192-192.169-171.100-199.0-9 + + +In this example all IP addresses with first +number 192, second number from 168 to 168, third number from 100 up to +199 and last number from 0 up to 9 will be pinged. This would give +1*1*100*10=1.000 addresses. + +This is probably only useful in very seldom cases. Here you have +to provide ranges for every four numbers, always divided by +-. + + + + +Single IP addresses or host names + +The IP address or host name of any machine you +are particularly interested in. + + + + +It is also valid to leave this entry empty. + + + + +<option>PingNames</option> + +Here you can additionally specify hosts to ping using their names. +The names have to be divided by semicolons. + +It is also valid to leave this entry empty. + + + + +<option>AllowedAddresses</option> + +This is also 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! + +For example, 192.168.0.0/255.255.0.0;192.169.0.0 + +A complete network and a single address are valid. Always make +this as strict as possible, usually your network address/subnetmask is a +good choice. + + + + +<option>BroadcastNetwork</option> + +This entry contains exactly one network address/subnet mask. To +this network broadcasts will be sent. Usually this should be your own +network address/subnetmask, for example: 192.168.0.0/255.255.0.0 + + + + +<option>SearchUsingNmblookup</option> + +Here you can give 0 or +1. 1 means that &lisa; +will execute nmblookup and parse +the output from this command. This produces less network traffic than +the pinging, but you will only get hosts which have a +SMB service running (&Windows; machines or machines +running samba). + +If you enable this option and also give IP +addresses to ping, then nmblookup will be executed +first and then the pinging will start. Then only addresses will be +pinged, which were not already delivered from +nmblookup. This should slightly decrease the network +load. + + + + +<option>FirstWait</option> + +If &lisa; pings, &ie; if it sends the ICMP echo +requests, it sends a bunch of requests at once, and the it will wait for +the number of hundredth seconds you specify here. Usually values from 5 +to 50 should be good, the maximum is 99 (gives 0.99 seconds, a very long +time). Try to make this value as small as possible while still finding +all running hosts. + + + + +<option>SecondWait</option> + +After &lisa; has sent the echo requests the first time, it can be +possible that some hosts were not found. To improve the results, &lisa; +can ping a second time. This time it will only ping hosts, from which it +didn't receive answers. If you have good results with pinging only once, +you can disable the second time with setting SecondWait to +-1. + +Otherwise it might be a good idea to make this value a little bit +bigger than the value for , since the hosts +which were not found on the first try, are probably slower or further +away so they might take some milliseconds longer to answer. Usually +values from 5 to 50 should be good or -1 to disable the second scan. +The maximum is 99 (gives 0.99 seconds, a very long time). + + + + +<option>UpdatePeriod</option> + +This is the interval after which &lisa; will update. After this +time &lisa; will again ping or nmblookup or get the +list of hosts from the &lisa; server which actually does the +pinging. + +Valid values are between 30 seconds and 1800 seconds (half an +hour). If you have a big network, don't make the interval too small (to +keep network load low). Values from 300 to 900 seconds (5 to 15 minutes) +might be a good idea. + +Keep in mind that the update period is doubled if nobody accesses +the server, up to 4 times, so the interval will become 16 times the +value given here and will be reseted to the value given here if somebody +accesses the server. + + + + +<option>DeliverUnnamedHosts</option> + +If an answer to an echo request from an IP address was received, +were &lisa; could not determine a name, it will be only delivered over +the port if you set this to 1. + +I am not really sure if this is a useful feature, but maybe there +are some infrastructure devices in your network without assigned names, +so they don't have to be published. Set this to 0 if you want to keep +them secret ;-) If unsure, say 0. + + + + +MaxPingsAtOnce + +When sending the pings (echo requests), &lisa; sends a bunch of +these at once and then waits for the answers. By default there are 256 +pings sent at once, usually you should not need the change this +value. If you make it much bigger, the internal receive buffers for the +answers to the echo requests may become to small, if you make it to +small, the updating will be slower. + + + + +Three more example files + + +FIXME + +You are member of a small network with 24 bit network mask, &ie; +up to 256 hosts: + + +PingAddresses = 192.168.100.0/255.255.255.0 +AllowedAddresses = 192.168.100.0/255.255.255.0 +BroadcastNetwork = 192.168.100.0/255.255.255.0 +SearchUsingNmblookup = 0 #don't use nmblookup +FirstWait = 20 #20 hundredth seconds +SecondWait = 30 #30 hundredth seconds on the seconds try +UpdatePeriod = 300 #update after 300 secs +DeliverUnnamedHosts = 0 #don't publish hosts without name + + + + + +Configuration file for hosts running <acronym>SMB</acronym> +only + +You are only interested in hosts running SMB +services and you don't have routers in your network: + + +AllowedAddresses = 192.168.100.0/255.255.255.0 +BroadcastNetwork = 192.168.100.0/255.255.255.0 +SearchUsingNmblookup = 1 #use nmblookup +UpdatePeriod = 300 #update after 300 secs +DeliverUnnamedHosts = 0 #don't publish hosts without name + + + + +Configuration file using both <command>nmblookup</command> and +pinging + +The same network, but here both nmblookup and pinging is +used. + + +PingAddresses = 192.168.100.0/255.255.255.0 +PingNames = bb_mail +AllowedAddresses = 192.168.0.0/255.255.0.0 +BroadcastNetwork = 192.168.100.0/255.255.255.0 +SearchUsingNmblookup = 1 #also try nmblookup +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 + + + + + +Configuration file for &reslisa; + +And now a configuration file for &reslisa;, PingAddresses is not +used by &reslisa;, neither is BroadcastNetwork. + + +PingNames = bb_mail;some_host;some_other_host +AllowedAddresses = 192.168.0.0/255.255.0.0 +SearchUsingNmblookup = 1 # use nmblookup +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 + + + + + + + +Command Line Options and Other Usage + +The following command line options are supported: + + + +, + +Prints brief version information. + + + + +, + +Gives an overview of the command line options + + + + +, + +Search at first for +$HOME/.lisarc, then for +/etc/lisarc. This is the default behavior. + + + + +, + +Search first for +$HOME/.kde/share/config/lisarc, then +for +$KDEDIR/share/config/lisarc. + + + + +, + +Looks for the file lisarc in every folder +returned by running kde-config + config + + + + +, +FILE + +Read FILE and no other configuration +file. + + + + +, +PORTNR + +Start the server on this portnumber. If you use this, &lisa; +won't be able to cooperate with other &lisa;'s on the network. This +option is not available for &reslisa; + + + + + +If you send the Hangup-Signal to &lisa; or &reslisa;, it will reread its +configuration file (killall ). + +If you send the User1-Signal to &lisa; or &reslisa;, it will print +some status information to the standard output +(killall ). You won't see anything if the console from +which &lisa;/&reslisa; was started has terminated. + + + + + + +Credits and Licenses + +&lisa; and &reslisa; copyright 2000, 2001, Alexander +Neundorf + + + + + +Have fun, Alexander Neundorf neundorf@kde.org + +&underFDL; +&underGPL; + + + + +Installation + +&lisa; and &reslisa; need a libstdc++ (it uses only the +string-class from it), it does not need either &Qt; +nor &kde;. + +&install.compile.documentation; + + +Other Requirements + +Both &reslisa; and &lisa; open a so called raw +socket to send and receive ICMP echo requests +(pings). To do this, they need root privileges. + + +&lisa; offers a service on TCP port 7741, and +should be installed by root +and started when the system comes up. It depends greatly on your &OS; +how to achieve this. + +&reslisa; is intended to be started per user, it doesn't offer +anything to the network. It needs to be installed setuid root. + +If you use the rlan ioslave from &kde; 2, +&reslisa; can be started automatically. + +&lisa; reads the file lisarc, &reslisa; reads +the file reslisarc. If you want to be able to +configure both from &kcontrol;, you have to start them using the command +line switch . + +For more information where they look for configuration files read +the chapter on . + + + + -- cgit v1.2.1