NAME

klask - port and search manager for switches, map management

USAGE

 klask version
 klask help

 klask updatedb [--verbose|-v] [--verb-description|-d] [--chk-hostname|-h] [--chk-location|-l] [--no-rebuildsw|-R]
 klask exportdb [--format|-f txt|html]
 klask removedb ipv4_addr* computer*
 klask insertdb --ip ipv4_addr --mac mac_addr --network vlan_name
 klask cleandb  [--verbose|-v] [--day number_of_day] [--repair-dns]

 klask updatesw [--verbose|-v]
 klask exportsw [--format|-f txt|dot] [--modulo|-m XX] [--shift|-s YY] [--way all|desc|child|parent] [--no-header|-H]

 klask searchdb [--kind|-k host|mac] computer [mac-address]
 klask search   computer
 klask search-mac-on-switch [--verbose|-v] [--vlan|-i vlan-id] switch mac_addr

 klask ip-free [--verbose|-v] [--day|-d days-to-death] [--format|-f txt|html] [vlan_name]

 klask bad-vlan-id [--day|-d days_before_alert] [--format|-f txt|html]

 klask enable  [--verbose|-v] switch port
 klask disable [--verbose|-v] switch port
 klask status  [--verbose|-v] switch port

 klask poe-enable  [--verbose|-v] switch port
 klask poe-disable [--verbose|-v] switch port
 klask poe-status  [--verbose|-v] switch port

 klask vlan-getname switch vlan-id
 klask vlan-list switch

DESCRIPTION

Klask is a small tool to find where is connected a host in a big network and on which VLAN. Klask mean search in brittany. No hight level protocol like CDL, LLDP are use. Everything is just done with SNMP request on MAC address.

Limitation : loop cannot be detected and could be problematic when the map is created (updatesw method). If you use PVST or MSTP and create loop between VLAN, you have to use portignore functionality on switch port to cut manually loop (see config file below).

When you use a management port to administrate a switch, it's not possible to create the map with this switch because it does not have a MAC address, so other switch cannot find the real downlink port... One way to work around this problem is, if you have a computer directly connected on the switch, to put this IPv4 as the fake ip for the switch. The MAC address associated will be use just for the map detection. The fake-ip parameter is defined in the config file.

Klask has now a web site dedicated for it: http://servforge.legi.grenoble-inp.fr/projects/klask!

COMMANDS

Some command are defined in the source code but are not documented here. Theses could be not well defined, not finished, not well tested... You can read the source code and use them at your own risk (like for all the Klask code).

search

 klask search   computer

This command takes one or more computer in argument. It search a computer on the network and give the port and the switch on which the computer is connected.

search-mac-on-switch

 klask search-mac-on-switch [--verbose|-v] [--vlan|-i vlan-id] switch mac_addr

This command search a MAC address on a switch. To search on all switch, you could put '*' or all. The VLAN parameter could help.

enable

 klask enable  [--verbose|-v] switch port

This command activate a port (or an agrregate bridge port) on a switch by SNMP. So you need to give the switch name and a port on the command line. See "ABBREVIATION FOR PORT".

Warning: You need to have the SNMP write access on the switch in order to modify it's configuration.

disable

 klask disable [--verbose|-v] switch port

This command deactivate a port (or an agrregate bridge port) on a switch by SNMP. So you need to give the switch name and a port on the command line. See "ABBREVIATION FOR PORT".

Warning: You need to have the SNMP write access on the switch in order to modify it's configuration.

status

 klask status  [--verbose|-v] switch port

This command return the status of a port number on a switch by SNMP. The return value could be enable or disable word. So you need to give the switch name and a port on the command line. See "ABBREVIATION FOR PORT".

If it's not possible to change port status with command "enable" and "disable" (SNMP community read write access), it's always possible to have the port status even for bridge agrregate port.

updatedb

 klask updatedb [--verbose|-v] [--verb-description|-d] [--chk-hostname|-h] [--chk-location|-l] [--no-rebuildsw|-R]

This command will scan networks and update the computer database. To know which are the cmputer scanned, you have to configure the file /etc/klask/klask.conf. This file is easy to read and write because Klask use YAML format and not XML (see "CONFIGURATION").

Option are not stable and could be use manually when you have a new kind of switch. Maybe some option will be transfered in a future checksw command!

The network parameter scan-mode can have two values: active or passive. By default, a network is active. This means that an fping command is done at the beginning on all the IPv4 of the network and the computers that was not detected in this pass, but where their Klask entry is less than one week, will have an arping (some OS do not respond to ping but a computer have to respond to arping if it want to interact with other). In the scan mode passive, no fping and no arping are done. It's good for big subnet with few computer (telephone...). The idea of the active scan mode is to force computer to regulary send packet over the network.

At the beginning, the command verify that the switch map checksum is always valid. Otherwise, a rebuild procedure will ne done automatically.

exportdb

 klask exportdb [--format|-f txt|html]

This command print the content of the computer database. There is actually only two format : TXT and HTML. By default, format is TXT. It's very easy to have more format, it's just need times...

removedb

 klask removedb ipv4_addr* computer*

This command remove an entry in the database. There is only one kind of parameter, the IPv4 of the computers to be removed. You can put as many IPv4 as you want...

Computer DNS names are also a valid entry because a DNS resolver is executed at the beginning.

insertdb

 klask insertdb --ip ipv4_addr --mac mac_addr --network vlan_name

This command insert an entry in the database. The IPv4 must not exist previously in the database and the reverse DNS name resolution must be active for that IPv4.

The date or timestamp of the entry will be number_of_day in the past (by default 15, see "cleandb") from today or from the oldest entry with the same MAC-Address. This command could be use to add pseudo entry and help in the process to detect bad vlan configuration (see "bad-vlan-id").

cleandb

 klask cleandb  [--verbose|-v] [--day number_of_day] [--repair-dns]

Remove double entry (same MAC-Address) in the computer database when the older one is older than X day (--day) the new one. Computer name beginning by 'float' (regex ^float) are not really taken into account but could be remove. This could be configure with the global regex parameter float-regex in the configuration file /etc/klask/klask.conf. This functionality could be use when computer define in VLAN 1 could have a float IPv4 when they are connected on VLAN 2. In the Klask database, the float DNS entries are less important.

When reverse DNS has not been done by the past, option --repair-dns force a reverse DNS check on all unkown host.

updatesw

 klask updatesw [--verbose|-v]

This command build a map of your manageable switch on your network. The list of the switches must be given in the file /etc/klask/klask.conf (see "CONFIGURATION").

The database has a checksum which depend of all the active switches. It's use when rebuilding the database in case of change in switch configuration (one more for example).

exportsw

 klask exportsw [--format|-f txt|dot] [--modulo|-m XX] [--shift|-s YY] [--way all|desc|child|parent] [--no-header|-H]

This command print the content of the switch database. There is actually two format. One is just TXT for terminal and the other is the DOT format from the graphviz environnement. By default, format is TXT.

Options for TXT format:

Tree tables are print : desc gives the switches description, model and revision, child return the switch to parent switch table and parent return the switch parent to parent child table. With option --way, you can choose which on to print. all will print all and child,parent will print only child and parent table. With option --no-header, you can remove the header for each table.

Options for DOT format:

 klask exportsw --format dot > /tmp/map.dot
 dot -Tpng /tmp/map.dot > /tmp/map.png

In case you have too many switch connected on one switch, the graphviz result graph could be too much vertical. With --modulo > 0, you can specify how many switches (connected on one switch) are on the same columns before shifting them to one column to the left and back again. The --shift parameter must be 1, 2 or 3. With --shift egual to 2, the shift will be to two column to the left. With 3, it will be 1 to the left and 2 to the left one time over two ! In practise, we just add virtuals nodes in the dot file, that means the result graph is generated with theses virtuals but invisibles nodes...

ip-free

 klask ip-free [--verbose|-v] [--day|-d days-to-death] [--format|-f txt|html] [vlan_name]

This command return IPv4 address that was not use (detected by Klask) at this time. The list returned could be limited to just one VLAN. IP returned could have been never used or no computer have been detected since the number of days specified (2 years by default). This parameter could also be define in the configuration file /etc/klask/klask.conf (see "CONFIGURATION").

 default:
   days-to-death: 730

Computer that does not have the good IPv4 but takes a float one (see "cleandb") are taken into account.

bad-vlan-id

 klask bad-vlan-id [--day|-d days_before_alert] [--format|-f txt|html]

This command return a list of switch port that are not configure with the good VLAN. Computer which are in bad VLAN are detected with the float regex parameter (see "cleandb") and another prior trace where they had the good IPv4 (good DNS name). The computer must stay connected on a bad VLAN more than XX days (15 days by default) before alert. This parameter could also define in the configuration file /etc/klask/klask.conf (see "CONFIGURATION").

 default:
   days-before-alert: 15

This functionality is not need if your switch use RADIUS 802.1X configuration...

poe-enable

 klask poe-enable  [--verbose|-v] switch port

This command activate the PoE (Power over Ethernet) on a switch port by SNMP. So you need to give the switch name and a port on the command line. See "ABBREVIATION FOR PORT".

Warning: Only NEXANS switches are supported (we do not have other switch for testing). You need to have the SNMP write access on the switch in order to modify it's configuration.

poe-disable

 klask poe-disable [--verbose|-v] switch port

This command deactivate the PoE (Power over Ethernet) on a switch port by SNMP. So you need to give the switch name and a port on the command line. See "ABBREVIATION FOR PORT".

Warning: Only NEXANS switches are supported (we do not have other switch for testing). You need to have the SNMP write access on the switch in order to modify it's configuration.

poe-status

 klask poe-status  [--verbose|-v] switch port

This command return the status of the PoE (Power over Ethernet) on a switch port by SNMP. The return value could be enable or disable word. So you need to give the switch name and a port on the command line. See "ABBREVIATION FOR PORT".

If it's not possible to change the PoE status with command "poe-enable" and "poe-disable" (SNMP community read write access), it's always possible to have the PoE port status.

Warning: Only NEXANS switches are supported (we do not have other switch for testing).

CONFIGURATION

Because Klask need many parameters, it's not possible actually to use command line parameters for everything. The configuration is done in a /etc/klask/klask.conf YAML file. This format have many advantage over XML, it's easier to read and to write !

Here an example, be aware with indent, it's important in YAML, do not use tabulation !

 default:
   community: public
   community-rw: private
   snmpport: 161
   float-regex: '(?^msx: ^float )'
   scan-mode: active

 network:
   labnet:
     ip-subnet:
       - add: 192.168.1.0/24
       - add: 192.168.2.0/24
     interface: eth0
     vlan-id: 12
     main-router: gw1.labnet.local

   schoolnet:
     ip-subnet:
       - add: 192.168.3.0/24
       - add: 192.168.4.0/24
     interface: eth0.38
     vlan-id: 13
     main-router: gw2.schoolnet.local
     scan-mode: passive

   etunet:
     ip-subnet:
       - add: 192.168.5.0/24
     interface: eth2
     vlan-id: 14
     main-router: gw3.etunet.local
     scan-mode: passive

 switch:
   - hostname: sw1.klask.local
     location: BatY / 1 floor / K004
     portignore:
       - 1
       - 2

   - hostname: sw2.klask.local
     location: BatY / 2 floor / K203
     type: HP2424
     portignore:
       - 1
       - 2
     fake-ip: 192.168.9.14

   - hostname: sw3.klask.local
     location: BatY / 2 floor / K203

I think it's pretty easy to understand. The default section can be overide in any section, if parameter mean something in theses sections. Network to be scan are define in the network section. You must put an add by network. Maybe I will make a delete line to suppress specific computers. The switch section define your switch. You have to write the port number to ignore, this was important if your switchs are cascades (right now, method updatesw find them automatically) and is still important if you have loop (with PVST or MSTP). Just put the ports numbers between switch.

The community parameter is use to get SNMP data on switch. It could be overload for each switch. By default, it's value is public and you have to configure a readonly word for safety reason. Some few command change the switch state as the commands "enable" and "disable". In theses rares cases, you need a readwrite SNMP community word define in your configuration file. Klask then use since version 0.6.2 the community-rw parameter which by default is egal to private.

ABBREVIATION FOR PORT

HP Procurve and Nexans switches have a simplistic numbering scheme. It's just number: 1, 2, 3... 24. On HP8000 chassis, ports names begin with an uppercase letter: A1, A2... Nothing is done on theses ports names.

On HP Comware and DELL, port digitization schema use a port speed word (generally a very verbose word) followed by tree number. In order to have short name, we made the following rules:

 Bridge-Aggregation     -> Br
 FastEthernet           -> Fa
 Forty-GigabitEthernet  -> Fo
 FortyGigabitEthernet   -> Fo
 GigabitEthernet        -> Gi
 Giga                   -> Gi
 Port-Channel           -> Po
 Ten-GigabitEthernet    -> Te
 TenGigabitEthernet     -> Te
 Ten                    -> Te

All Klask command automatically normalize the port name on standart output and also on input command line.

In the case of use an aggregator port (Po, Tk, Br ...), the real ports used are also return.

SWITCH SUPPORTED

Here is a list of switches where Klask gives or gave (for old switches) good results. We have only a few manageable switches to actually test Klask. It is quite possible that switches from other brands will work just as well. You just have to do a test on it and add the line of description that goes well in the source code. Contact us for any additional information.

In the following list, the names of the switch types written in parentheses are the code names returned by Klask. This makes it possible to adjust the code names of the different manufacturers!

HP: J3299A(HP224M), J4120A(HP1600M), J9029A(HP1800-8G), J9449A(HP1810-8G), J4093A(HP2424M), J9279A(HP2510G-24), J9280A(HP2510G-48), J4813A(HP2524), J4900A(HP2626A), J4900B(HP2626B), J4899B(HP2650), J9021A(HP2810-24G), J9022A(HP2810-48G), J8692A(HP3500-24G), J4903A(HP2824), J4110A(HP8000M), JE074A(HP5120-24G), JE069A(HP5120-48G), JD377A(HP5500-24G), JD374A(HP5500-24F), J4121A(HP4000M), J9145A(HP2910-24G), J3298A(HP212M), J9625A(HP2620-24P).

BayStack: BayStack 350T HW(BS350T)

Nexans: GigaSwitch V3 TP SFP-I 48V ES3(NA3483-6G), GigaSwitch V3 TP.PSE.+ 48/54V ES3(NA3483-6P), GigaSwitch V5 TP(PSE+) SFP-2VI 54VDC(NA5542-7G)

DELL: PC7024(DPC7024), N2048(DN2048), N4032F(DN4032F), N4064F(DN4064F)

H3C and 3COM switches have never not been tested but the new HP Comware switches are exactly the same...

H3C: H3C5500

3COM: 3C17203, 3C17204, 3CR17562-91, 3CR17255-91, 3CR17251-91, 3CR17571-91, 3CRWX220095A, 3CR17254-91, 3CRS48G-24S-91, 3CRS48G-48S-91, 3C17708, 3C17709, 3C17707, 3CR17258-91, 3CR17181-91, 3CR17252-91, 3CR17253-91, 3CR17250-91, 3CR17561-91, 3CR17572-91, 3C17702-US, 3C17700.

FILES

 /etc/klask/klask.conf
 /var/lib/klask/klaskdb
 /var/lib/klask/switchdb

VERSION

$Id: klask 402 2018-10-02 12:31:09Z g7moreau $

AUTHOR

Written by Gabriel Moreau <Gabriel.Moreau(A)univ-grenoble-alpes.fr>, Grenoble - France

SPECIAL THANKS

The list of people below did not directly contribute to Klask's source code but provided me with some data, returned bugs or helped me in another small task like having new ideas ... Maybe I forgot your contribution in recent years, please forgive me in advance and send me an e-mail to correct this.

Kevin Reverchon, Olivier De Marchi, Patrick Begou, Herve Colasuonno, David Gras.

LICENSE AND COPYRIGHT

License GNU GPL version 2 or later and Perl equivalent