Differences

This shows you the differences between two versions of the page.

--- arnold [2007/09/27 19:35]
faltin
+++ arnold [2012/11/12 09:23]
bredal [NAV 3.13]
@@ Line 1: / Line 1: @@
 ====== Arnold ======
-//This document is under construction.//
+//This documentation is for Arnold in NAV 3.4 and newer.  For previous NAV versions, see an older revision of this page (dated 2008/04/01).//
-{{tools:arnold.png|}} Arnold is a subsystem to NAV-v3, first released in NAV-v3.1. Arnold is a port-blocker 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. Version 2 of Arnold was released in NAV 3.4. 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.
+===== 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 on 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.
-====== What does Arnold do? ======
+:!: 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|seed database tool]].
-Arnold is a system that blocks switch-ports by using SNMP-set commands. It does this based one or more ip-addresses given as input on runtime. Based on the address it uses the NAV-database to locate the correct switch-port to block, and attempts to block it using SNMP. \\
-:!: NB: It is important that the write-community is set in the NAV-database, otherwise Arnold will not be able to disable or enable ports. 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 ======
+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.
-====== Running Arnold ======
-Arnold consists of a couple of scripts, 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.
 ===== The web-interface =====
-To access the web-interface you can use the Toolbox or just type ''arnold'' in your NAV-uri. The first page is the list of currently blocked (or disabled) ports. Above the list you will see a number of links which you can use to access more of Arnolds functionality. Here is the list:
+To access the web-interface, use the Toolbox and locate the Arnold subsystem there. The first page is the list of currently detained ports. Above the list you will see a number of links which you can use to access more of Arnolds functionality. Here is the list:
-  * **History:** List all ports you have disabled...ever.
+  * **History:** List all computers and ports you have detained.
-  * **Blocked ports:** All currently blocked ports. This is the default page.
+  * **Blocked ports:** All currently detained ports. This is the default page.
   * **Search:** Search the database.
-  * **Add blockreason:** When blocking/disabling a port, you will need a reason for it (really!). Here is where you add such reasons. Nothing stops you from making a "For fun"-tuple, but it might be frowned upon by some.
+  * **Add detentionreason:** When detaining a port, you will need a reason for it. Here is where you add such reasons. :!: The reasons used in Predefined detentions are not available for use in manual detentions anymore.
-  * **Manual block:** This page lets you block a port on your network. All you need is an ip-address and a Reason.
+  * **Manual detention:** This page lets you detain a computer or switchport on your network. All you need is an ip or mac-address and a reason. :!: Note that to quarantine a computer you need to first define a quarantine vlan in the "Add Quarantine vlan" section.
-  * **Blocktypes:** Here you add predefined blocks that may be used by for instance scripts.
+  * **Predefined detentions:** Here you add predefined detentions that may be used by for instance scripts.
+  * **Add Quarantine vlan:** A quarantine vlan is used when quarantining computers. Define your quarantine vlans here.
 As the functionality of these pages are more or less self-explaining, I will not document all of them. But there are a page that demands som explaining, which hereby follows:
-**Blocktypes**
+===Predefined detentions===
-The concept //Blocktype// may be hard to understand at first (which is partly because the word does not very accurately describe the concept). However, a blocktype is a predefined blocking. Why use it?
+A predefined detention lets you specify parameters for a detention before the detention is carried out. Why use it?
- - It saves you the trouble of choosing all parameters when blocking.
+  * It saves you the trouble of choosing all parameters when detaining.
- - It is perfect for use by other scripts and by a cronjob.
+  * It is perfect for use by other scripts and by a cronjob.
- - It is perfect for use when you have a lot of computers to block at the same time.
+  * It is perfect for use when you have a lot of computers to block at the same time.
-So, hit the "Add new blocktype"-link and lets start!
+So, hit the "Add new predefined detention"-link and lets start!
-  * **Title:** is the title of the block type. This is just a name used on the web-site.
+  * **Detainmenttype:** Choose whether you want to block computers or put them on a quarantine vlan.
+  * **Title:** is the title of the predefined detention. This is just a name used to refer to it.
   * **Description:** is also just used at the website to tell users why and how.
-  * **Reason:** is the reason used when blocking with this block type. You can choose one already defined or add a new one by using the respective fields.
+  * **Reason:** is the reason used when detaining with this predefined detention. You can choose one already defined or add a new one by using the respective fields.
-  * **Path to mailfile:** is the name of the mail template-file you must make if you want to send mail to the people responsible for the computers that are blocked by this block type. Read more about the mail templates in the "Configuring Arnold"-section.
+  * **Path to mailfile:** is the name of the mail template-file you must make if you want to send mail to the people responsible for the computers that are detentioned. Read more about the mail templates in the "Configuring Arnold"-section.
-  * **Path to inputfile:** is the path to the input file. The input file is the file containing the list of ip-addresses to block. More info to come.
+  * **Path to inputfile:** is the path to the input file. The input file is the file containing the list of addresses to detain.
-  * **Block pursuit:** decides how Arnold will behave when pursuing a computer that moves to other ports when blocked. "Open on move" means that Arnold will open the former port when blocking the new port, "All closed" means that Arnold will not open any ports when pursuing (ie. all ports will stay blocked). The computer will leave a "trail of no connection".
+  * **Detention pursuit:** decides how Arnold will behave when pursuing a computer that moves to other ports when detained. "Open on move" means that Arnold will enable the former port when detaining the new port, "All closed" means that Arnold will not enable any ports when pursuing (ie. all ports will stay detained). The computer will leave a "trail of no connection" or, in the case of quarantines, a trail of quarantine vlans.
-  * **Exponential increase:** is a nifty feature that blocks previous mischievers for a longer timespan for each new block. 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.
-  * **Block 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 block type, 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).
-  * **User:** enables you to choose the username that appears as the blocker.
+  * **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 defined blocktype**
+**How to use a predefined detention**
-The only way to use a defined block type when blocking is by using the ''start_arnold.pl''-script. When you have defined a block type 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.py''-script. When you have defined a predefined detention you should make a cron-job or some other way of running ''start_arnold.py'' automatically whenever you want. See section about start_arnold.py.
-Examples:
-<code>
-[prompt]# crontab -e
-0 * * * $NAVDIR/bin/start_arnold -i 2 -f $SCANFILES/scan.txt >> $LOGDIR/blocktype2.log
-:wq
-</code>
-<code>
-[prompt]# cd nav/bin
-[prompt]# ./start_arnold.pl -i2
-.241.xxx.xxx
-<CTRL-D>
-.241.xxx.xxx (connected to nett-ans-xxx-h.ntnu.no 1:8) disabled successfully.
-[prompt]#
-</code>
 ===== The scripts =====
-Arnold consists of four scripts, which all are located in the ''nav/bin'' directory.
+Arnold consists of three scripts, which all are located in the ''nav/bin'' directory.
-  * **arnold.pl:** is the main script which disables and enables ports.
+  * **autoenable.py:** enables ports based on the autoenable-variable.
-  * **autoenable.pl:** is run by cron and enables ports based on the autoenable-variable.
+  * **start_arnold.py:** is used in combination with a //predefined detention// to invoke a series of detentions.
-  * **start_arnold.pl:** is used in combination with a //Blocktype// to invoke a series of disablings.
+  * **t1000.py:** is the "pursuer of justice". It makes sure that if someone moves to another port, the detention is enforced there aswell.
-  * **t1000.pl:** is the "pursuer of justice". It makes sure that if someone moves to another port, the block stays with him/her/it.
-==== 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 script is removed, and may or may not come alive again depending on demand.
-NB: All information listed here is from our test-install, thus the information may seem a little immature. This indicates a healthy working environment.
+==== autoenable.py ====
-**Disabling a port**
+''autoenable.py'' fetches all disabled ports with an autoenable-value and enables each of those ports if the time is due.  It can be run manually, but should be added as a periodic cron job for it to be truly automatic.
-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.
+The simplest way of adding this script as a cronjob is to create a file containing a short cron snippet that calls the autoenable.py program as often as you would like autoenable timeouts to be checked.  Save this snippet in a file called ''autoenable'' in NAV's ''etc/cron.d/'' directory.  That way, you can add it to the ''navcron'' user's crontab by calling ''nav start autoenable''.
-: Locate the victim - i.e. an ip-address.
+==== start_arnold.py ====
-: 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:
-: Vi sperrer porter fordi det er gøy.
-: Next reason
-: Lav sko
-</code>
-: Determine time for auto enable (how many days before enabling of port happens automatically). not specified = forever.
-: Run the script:
 <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
-.241.xxx.xxx (connected to nett-ans-xxx-h.ntnu.no 1:8) disabled successfully.
 </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
-.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** :!: is not in use anymore. Use logging.conf for setting specific loglevels.
+  * **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 ====
+''nav/etc/arnold/mailtemplates/*''
-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).
+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.
-====== 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/*''
-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.
+====== Logging ======
+The arnold scripts logs to individual files stored in ''nav/var/log/arnold''. The webinterface logs to STDERR, which apache most probably puts in it's error.log. The loglevel used for each script is defined in logging.conf.
-More to come.
-====== Details ======
+====== Changes ======
-More details.
+===== NAV 3.13 =====
-Logs of arnold-activity are stored in ''nav/var/log/arnold''.
+Arnold needed to be rewritten to not use mod_python and to use django models. Also, the code was in dire need of a cleanup. The rewrite tried to make as little changes as possible and at the same time fix the bugs that were reported.
-====== Arnold - why that name? ======
+Some changes were introduced though:
+  * The shell-script for interacting with arnold is gone. If there is an outcry for it, it will be reintroduced.
+  * The workflow when manually detaining was altered to something better.
+  * The reasons used for automatic detentions are no longer available when manually detaining. This is done to be able to differ between manual and automatic detentions. If you detain for the same reason both manually and automatically, just create two similar reasons.
+  * Logleves are no longer set in arnold.conf. Use logging.conf to alter loglevels for the scripts and web.
+  * Some bugs were found that was not reported.
+    * The "Open on move"-option in a predefined detention was never used. This is fixed.
+    * Pursuing was not done in some cases.
+  * Reported bugs that are fixed:
+    * #341703 Manual detention does not pursue client
+    * #361530 Predefined detention does not exponentially increase detentions
+    * #744932 Arnold should give warning if snmp write is not configured
-The story.
+===== NAV 3.4 =====
+The main addition to arnold in version 2 (that came with NAV 3.4) is the ability to change vlans on ports instead of just blocking them. This is done so that if you have available quarantine vlans defined on your network, you can put computers on those vlans instead of blocking them. Putting computers in a quarantine vlan is more helpful and convenient for the user of the computer than suddenly losing the internet connection, which often leads to frustration and helpdesk calls. The action of changing a vlan on a port with the help of Arnold is called a //quarantine//.
+Other new features:
+  * Totally rewritten in python to better interface with the rest of NAV.
+  * Arnold Python module makes it easy for developers to use arnold-functionality in other scripts and webpages.
+  * New concept - //detention// - introduced. A detention is the action done to a computer to "punish" it, and refers to both a quarantine and a block.
+  * 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.
+  * 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.

NAV Wiki

User Tools

Site Tools

Differences

Page Tools