Differences

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

--- arnold [2012/11/12 08:59] – [The scripts] bredal
+++ arnold [2016/01/06 13:54] (current) – link to new location morten
@@ Line 1: / Line 1: @@
-====== Arnold ======
+This has been moved into the official NAV documentation at https://nav.uninett.no/doc/latest/reference/arnold.html
-//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 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.
-:!: 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]].
-====== 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.
-===== The web-interface =====
-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 computers and ports you have detained.
-  * **Blocked ports:** All currently detained ports. This is the default page.
-  * **Search:** Search the database.
-  * **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 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.
-  * **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:
-===Predefined detentions===
-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 detaining.
-  * 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.
-So, hit the "Add new predefined detention"-link and lets start!
-  * **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 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 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 addresses to detain.
-  * **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 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.
-  * **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**
-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.
-===== The scripts =====
-Arnold consists of three scripts, which all are located in the ''nav/bin'' directory.
-  * **autoenable.py:** enables ports based on the autoenable-variable.
-  * **start_arnold.py:** is used in combination with a //predefined detention// to invoke a series of detentions.
-  * **t1000.py:** is the "pursuer of justice". It makes sure that if someone moves to another port, the detention is enforced there aswell.
-==== arnold.py ====
-This script is removed, and may or may not come alive again depending on demand.
-==== autoenable.py ====
-''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.
-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''.
-==== start_arnold.py ====
-''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:
-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):
-<code>
-[prompt]# cat scanresult.txt | ssh scanner@navinstall.network.com:nav/bin/start_arnold_py -i 1
-</code>
-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.
-==== t1000.py ====
-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).
-====== Configuring Arnold ======
-===== Config files =====
-The following configuration files are used by Arnold.
-====arnold.conf====
-''nav/etc/arnold/arnold.conf'' is divided into three sections.
-  * **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.
-====nonblock.conf====
-''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.
-====Mailtemplates====
-''nav/etc/arnold/mailtemplates/*''
-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.
-====== 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.