arnoldv2
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
arnoldv2 [2008/04/02 09:37] bredal |
arnoldv2 [2008/04/30 09:38] (current) morten |
||
|---|---|---|---|
| Line 3: | Line 3: | ||
| //This document is under construction.// | //This document is under construction.// | ||
| - | {{tools:arnold.png|}} Arnold is a subsystem to NAV-v3, first released in NAV-v3.1. Arnold is a port-blocker, and now vlan changer, and was originally made to be able to easier remove mischievers from the campus-internet. | + | {{tools:arnold.png|}} Arnold is a subsystem to NAV 3, first released in NAV 3.1. Arnold is a port-blocker and vlan changer, and was originally made to be able to easier remove mischievers from the campus-internet. |
| This document will give you information about how Arnold works and how to use and configure it. A FAQ-section will be added as questions are received. | This document will give you information about how Arnold works and how to use and configure it. A FAQ-section will be added as questions are received. | ||
| + | |||
| + | ===== What does Arnold do? ===== | ||
| + | |||
| + | Arnold is a system that blocks or changes vlan on (from now on referred to as a "detention") switch-ports by using SNMP-set commands. It does this based one or more ip or mac-addresses given as input on runtime. Based on the address it uses the NAV-database to locate the correct switch-port to detain, and attempts to detain it using SNMP. | ||
| + | |||
| + | :!: NB: It is important that the write-community is set in the NAV-database, otherwise Arnold will not be able to detain or enable ports on the switch. You specifiy write community when you add or edit a new netbox in the [[seedessentials#registering_a_new_ip_device|edit database tool]]. | ||
| + | |||
| + | Arnold does not scan or in any other way detect or judge mischievers, it leaves that to the persons or scripts giving it input. It is like the executioner getting the "Chop"-signal, happily blocking away doing its job. | ||
| ===== New features in arnold v2 ===== | ===== New features in arnold v2 ===== | ||
| Line 17: | Line 25: | ||
| * Both ip and mac-addresses may be used to detain a computer. | * Both ip and mac-addresses may be used to detain a computer. | ||
| * Given address does not have to be active at the moment to be detained. | * Given address does not have to be active at the moment to be detained. | ||
| - | * Better and more options when enabling (enable also refers to "unquarantining") ports. | + | * More and better options when enabling (enable also refers to "unquarantining") ports. |
| * Vlans can now be specified to limit the area of a predefined detention. If an address is outside or moves outside this area, a detention will not be enforced. | * Vlans can now be specified to limit the area of a predefined detention. If an address is outside or moves outside this area, a detention will not be enforced. | ||
| - | |||
| - | |||
| - | |||
| - | ===== What does Arnold do? ===== | ||
| - | |||
| - | Arnold is a system that blocks or changes vlan on (from now on referred to as a "detention") switch-ports by using SNMP-set commands. It does this based one or more ip or mac-addresses given as input on runtime. Based on the address it uses the NAV-database to locate the correct switch-port to detain, and attempts to detain it using SNMP. | ||
| - | |||
| - | :!: NB: It is important that the write-community is set in the NAV-database, otherwise Arnold will not be able to detain or enable ports on the switch. You specifiy write community when you add or edit a new netbox in the [[seedessentials#registering_a_new_ip_device|edit database tool]]. | ||
| - | |||
| - | Arnold does not scan or in any other way detect or judge mischievers, it leaves that to the persons or scripts giving it input. It is like the executioner getting the "Chop"-signal, happily blocking away doing its job. | ||
| - | |||
| - | |||
| ====== Running Arnold ====== | ====== Running Arnold ====== | ||
| Arnold consists of a couple of scripts (including a arnold-module), a web-interface and a database. For basic use you will never have to touch the scripts, just use the web-interface to disable and enable ports. Arnold should be ready to use without any fuzz as long as the NAV-database is up to date. Some of the features requires some editing in config-files, which is documented later in this document. | Arnold consists of a couple of scripts (including a arnold-module), a web-interface and a database. For basic use you will never have to touch the scripts, just use the web-interface to disable and enable ports. Arnold should be ready to use without any fuzz as long as the NAV-database is up to date. Some of the features requires some editing in config-files, which is documented later in this document. | ||
| + | |||
| Line 70: | Line 67: | ||
| * **Exponential increase:** is a nifty feature that detains previous mischievers for a longer timespan for each new detention. More details in the "Details"-section. | * **Exponential increase:** is a nifty feature that detains previous mischievers for a longer timespan for each new detention. More details in the "Details"-section. | ||
| * **Detention duration:** is the same as auto enable - it decides the timespan the port is disabled. | * **Detention duration:** is the same as auto enable - it decides the timespan the port is disabled. | ||
| - | * **Active:** check this to activate the predefined detention, uncheck to disable it. | + | * **Active on vlans:** lets you limit the vlans the detentions are enforced on. If a computer is on a vlan not specified in this field, it will not be detained. If left blank, all vlans are used. The format is a comma-separated list of vlannumbers (e.g. 123,234). |
| + | * **Active:** check this to activate the predefined detention, uncheck to disable it. Disabled predefined detentions will do nothing when asked to detain computers. | ||
| **How to use a predefined detention** | **How to use a predefined detention** | ||
| - | The only way to use a predefined detention is by using the ''start_arnold.pl''-script. When you have defined a predefined detention you should make a cron-job or some other way of running ''start_arnold.pl'' automatically whenever you want. | + | The only way to use a predefined detention is by using the ''start_arnold.pl''-script. When you have defined a predefined detention you should make a cron-job or some other way of running ''start_arnold.pl'' automatically whenever you want. See section about start_arnold.py. |
| - | + | ||
| - | Examples: | + | |
| - | <code> | + | |
| - | Create some examples here. | + | |
| - | </code> | + | |
| ===== The scripts ===== | ===== The scripts ===== | ||
| Line 91: | Line 83: | ||
| * **t1000.py:** is the "pursuer of justice". It makes sure that if someone moves to another port, the detention is enforced there aswell. | * **t1000.py:** is the "pursuer of justice". It makes sure that if someone moves to another port, the detention is enforced there aswell. | ||
| - | ==== arnold.pl ==== | + | ==== arnold.py ==== |
| - | This is the workhorse of the system. You can run ''arnold.pl -h'' to get a huge list of options. It //always// demands the -x parameter to be set, other than that it is all dependent on what you want to do. I do not recommend "pushing all the buttons to see what happens". I will throw in some examples for basic use. | + | This used to be the workhorse of the system. This is no longer the case as the python module 'arnold' now does all the work. This script is used now for basic use of arnold via a shell. You can run ''arnold.py -h'' to get a list of options. |
| - | NB: All information listed here is from our test-install, thus the information may seem a little immature. This indicates a healthy working environment. | ||
| - | **Disabling a port** | + | ==== autoenable.py ==== |
| - | If you, for some reason, want to disable a port using the script and not using the web-interface, this is the way to do it. | + | ''autoenable.py'' is run by cron and should not need to be run by any other user. All it does is fetch all disabled ports with an autoenable-value and enable that port if the time is due. Running it manually does the same thing. |
| - | 1: Locate the victim - i.e. an ip-address. | + | ==== start_arnold.py ==== |
| - | 2: List all reasons: | + | ''start_arnold.py'' should be used in conjunction with a //predefined detention//. This is first defined using the webinterface with name, options and so on. When it is defined you can use ''start_arnold.py'' to run a detention. Confusing? Yes. It was made for ease of use from other computers which had large lists of ip-addresses to be detained. Lets make a scenario: |
| - | <code> | + | We want to scan our network for malicious computers. We have our own scanning-computer that has more-than-normal access to the whole network, and this is not the computer NAV is installed on. How do we deliver the list from the scanning-computer to arnold for detentions? Well, first we make a predefined detention with the options we want, using the webinterface. We give the scanning-computer a public-key tuple on the NAV-server. Then we do some scanning which gives us a list of computers we don't want on the network anymore. We transfer the list like this (the -i option is the id of the predefined detention): |
| - | [prompt]# ./arnold.pl -l | + | |
| - | Reasons for blocking currently in the database: | + | |
| - | 1: Vi sperrer porter fordi det er gøy. | + | |
| - | 2: Next reason | + | |
| - | 3: Lav sko | + | |
| - | </code> | + | |
| - | + | ||
| - | 3: Determine time for auto enable (how many days before enabling of port happens automatically). not specified = forever. | + | |
| - | + | ||
| - | 4: Run the script: | + | |
| <code> | <code> | ||
| - | [prompt]# ./arnold.pl -x disable -a 129.241.xxx.xxx -r2 -t2 | + | [prompt]# cat scanresult.txt | ssh scanner@navinstall.network.com:nav/bin/start_arnold_py -i 1 |
| - | 129.241.xxx.xxx (connected to nett-ans-xxx-h.ntnu.no 1:8) disabled successfully. | + | |
| </code> | </code> | ||
| - | Now we have disabled //port 8// in //module 1// on the switch //nett-ans-xxx-h.ntnu.no// (which is where 129.241.xxx.xxx is located). It will stay disabled for two days or until we manually enable it. | + | This will ensure a clean and tidy run of arnold and some detained ports. Of course you can also use ''start_arnold.py'' to just pipe a local list of addresses in, quick and easy. The main advantage is that all options are set and you have an easy way to "feed" Arnold. |
| - | **Enabling a port** | + | ==== t1000.py ==== |
| - | Enabling of a port should really only be done by the web-interface. If you are very stubborn, find the id of the block in the database, and run this command: | + | This script is run by cron. It fetches all detained ports from the database and starts checking if the mac-address which was behind that port is active any other place in the network. If it is, it enforces the detention on that port aswell. Depending on options given at detention-time it will either enable the old port or just leave it. Needless to say this does not detain the new port immediately after a detained computer has moved to it as it takes some time before the mac-address is discovered, but it is as good as it gets (for now). |
| - | <code> | + | ====== Configuring Arnold ====== |
| - | [bredal@isbre bin]$ ./arnold.pl -x enable -i 7 | + | |
| - | 129.241.xxx.xxx (connected to nett-ans-xxx-h.ntnu.no 1:8) enabled successfully. | + | |
| - | </code> | + | |
| - | **Other options** | ||
| - | More to come. | + | ===== Config files ===== |
| - | ==== autoenable.pl ==== | + | The following configuration files are used by Arnold. |
| - | ''autoenable.pl'' is run by cron and should not need to be run by any other user. All it does is fetch all disabled ports with an autoenable-value and enable that port if the time is due. Running it manually does the same thing. | + | ====arnold.conf==== |
| - | ==== start_arnold.pl ==== | + | ''nav/etc/arnold/arnold.conf'' is divided into three sections. |
| - | ''start_arnold.pl'' should be used in conjunction with a //blocktype//. A blocktype is first defined on the web-interface with name, options and so on. When a blocktype is defined you can use ''start_arnold.pl'' to run a block by that blocktype. Confusing? Yes. It was made for ease of use from other computers which had large lists of ip-addresses to be blocked. Lets make a scenario: | + | * **arnold** is the section that contains information about what database to use and on what networking equipment Arnold should be able to detain ports. You also define email-addresses here. |
| + | * **loglevel** defines the different loglevel for each of arnold's scripts (the webinterface logs to the default weblog-file, and that loglevel is not defined here). | ||
| + | * **arnoldweb** has just one config option, which sets the default detention method when loading the webinterface. | ||
| - | We want to scan our network for malicious computers. We have our own scanning-computer that has more-than-normal access to the whole network, and this is not the computer NAV is installed on. How do we deliver the list from the scanning-computer to arnold for blocking? Well, first we make a blocktype with the options we want. This is done by using the web-interface. We give the scanning-computer a public-key tuple on the NAV-server. Then we do some scanning which gives us a list of computers we don't want on the network anymore. We transfer the list like this (the -i option is the id of the blocktype): | + | ====nonblock.conf==== |
| - | <code> | + | ''nav/etc/arnold/nonblock.conf'' is not really a config-file but an exception list. Some computers (ip-addresses) does not want to be detained. If you want to grant them their wish, enter their ip-address in this file. The format is cleary defined in the file, and is quite flexible. You also have the possibility to define equipment-types that you don't want to block. This is a rather depricated option, but some switches that does not support snmp-set are included by default. |
| - | [prompt]# cat scanresult.txt | ssh scanner@navinstall.network.com:nav/bin/start_arnold_pl -i 1 | + | |
| - | </code> | + | |
| - | This will ensure a clean and tidy run of arnold and some blocked ports. Of course you can also use ''start_arnold.pl'' to just pipe a local list of ip-addresses in, quick and easy. The main advantage is that all options are set by defining a blocktype and you have an easy way to "feed" Arnold. | + | ====Mailtemplates==== |
| - | + | ||
| - | ==== t1000.pl ==== | + | |
| - | + | ||
| - | This script is run by cron. It fetches all blocked ports from the database and starts checking if the mac-address which was behind that port is active any other place in the network. If it is, it blocks that port. Depending on options given at block-time it will either open the old closed port or just leave it closed. Needless to say this does not block the new port immediately after a blocked computer has moved to it, but it is as good as it gets (for now). | + | |
| - | + | ||
| - | ====== Configuring Arnold ====== | + | |
| - | + | ||
| - | ===== Config files ===== | + | |
| - | + | ||
| - | Arnold has two config-files, which both are quite small. | + | |
| - | + | ||
| - | ''nav/etc/arnold/arnold.cfg'' has three options. You specify the mail-program Arnold uses to send mail, the from-address Arnold identifies itself by, and a recipient which Arnold uses to send mail if something went wrong. All these are marked clearly in the file. | + | |
| - | + | ||
| - | ''nav/etc/arnold/nonblock.cfg'' is not really a config-file but an exception list. Some computers (ip-addresses) does not want to be blocked. If you want to grant them their wish, enter their ip-address in this file. The format is cleary defined in the file, and is quite flexible. You also have the possibility to define equipment-types that you don't want to block. This is a rather depricated option, but some switches that does not support snmp-set are included by default. | + | |
| - | + | ||
| - | In addition we have these: | + | |
| ''nav/etc/arnold/mailtemplates/*'' | ''nav/etc/arnold/mailtemplates/*'' | ||
| - | If you make a //Blocktype// you will notice a textfield called "Path to mailfile". Arnold may send mail to those listed as responsible for the ip-address it tries to block. Who is responsible is fetched from the NAV-database. But Arnold does not know what you want to tell these people, so you have to write the general format of the mail yourself. This template is what you write and place in the mailtemplates-folder, and the name of the file you make (which contains your template) is placed in the "Path to mailfile"-textfield. A description on how to make a template is in the ''README''-file located in the ''mailtemplates/''-folder. | + | If you make a //predefined detention// you will notice a textfield called "Path to mailfile". Arnold may send mail to those listed as responsible for the address it tries to detain. Who is responsible is fetched from the NAV-database (the contact address defined for an organisation). But Arnold does not know what you want to tell these people, so you have to write the general format of the mail yourself. This template is what you write and place in the mailtemplates-folder, and the name of the file you make (which contains your template) is placed in the "Path to mailfile"-textfield. A description on how to make a template is in the ''README''-file located in the ''mailtemplates/''-folder. |
| - | + | ||
| - | + | ||
| - | More to come. | + | |
| - | + | ||
| - | ====== Details ====== | + | |
| - | + | ||
| - | More details. | + | |
| - | + | ||
| - | Logs of arnold-activity are stored in ''nav/var/log/arnold''. | + | |
| - | + | ||
| - | + | ||
| - | ====== Arnold - why the name? ====== | + | |
| - | The story. | + | ====== Logging ====== |
| + | The arnold scripts logs to individual files stored in ''nav/var/log/arnold''. The webinterface logs to the default webfront log, usually ''nav/var/log/webfront.log''. The loglevel used for each script is defined in arnold.conf. | ||
arnoldv2.1207129027.txt.gz · Last modified: 2008/04/02 09:37 by bredal
Page Tools
