====== Arnold version 2 ====== //This document is under construction.// {{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. ===== 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 ===== The main addition to arnold in version 2 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. ====== 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. Nothing stops you from making a "For fun"-tuple, but it might be frowned upon by some. * **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.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. ===== The scripts ===== Arnold consists of four scripts, which all are located in the ''nav/bin'' directory. * **arnold.py:** is a script that gives you basic arnold-functions from a shell. Using the webinterface is preferred though. * **autoenable.py:** 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. * **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 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. ==== autoenable.py ==== ''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. ==== 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): [prompt]# cat scanresult.txt | ssh scanner@navinstall.network.com:nav/bin/start_arnold_py -i 1 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 the default webfront log, usually ''nav/var/log/webfront.log''. The loglevel used for each script is defined in arnold.conf.