# The &lisa; Handbook

## 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:

1. 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.

2. 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 `--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.

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

### `PingAddresses`

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.

### `PingNames`

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.

### `AllowedAddresses`

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.

### `BroadcastNetwork`

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

### `SearchUsingNmblookup`

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.

### `FirstWait`

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.

### `SecondWait`

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 `FirstWait`, 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).

### `UpdatePeriod`

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.

### `DeliverUnnamedHosts`

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 SMB 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 `nmblookup` 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:

`-v`, `--version`

- Prints brief version information.

`-h`, `--help`

- Gives an overview of the command line options

`-u`, `--unix`

- Search at first for `$`HOME`/.lisarc`, then for `/etc/lisarc`. This is the default behavior.

`-k`, `--kde1`

- Search first for `$`HOME`/.kde/share/config/lisarc`, then for `$`KDEDIR`/share/config/lisarc`.

`-K`, `--kde2`

- Looks for the file `lisarc` in every folder returned by running ``kde-config` `--path` `config``

`-c`, `--config=``FILE`

- Read `FILE` and no other configuration file.

`-p`, `--port` `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` `-HUP lisa``).

If you send the User1-Signal to &lisa; or &reslisa;, it will print some status information to the standard output (``killall` `-USR1 lisa``). 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 `-K`.

For more information where they look for configuration files read the chapter on command-line-options.