User Tools

Site Tools


arnold

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
arnold [2007/09/27 19:36]
faltin
arnold [2016/01/06 13:54] (current)
morten link to new location
Line 1: Line 1:
- +This has been moved into the official ​NAV documentation ​at https://nav.uninett.no/doc/latest/reference/arnold.html
- +
-====== Arnold ====== +
- +
-//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 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 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, 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: +
- +
-  * **History:​** List all ports you have disabled...ever. +
-  * **Blocked ports:** All currently blocked 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. +
-  * **Manual block:** This page lets you block a port on your network. All you need is an ip-address and a Reason. +
-  * **Blocktypes:​** Here you add predefined blocks that may be used by for instance scripts. +
- +
-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** +
- +
-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?  +
- +
- - It saves you the trouble of choosing all parameters when blocking. +
- - 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 blocktype"​-link and lets start! +
- +
-  * **Title:** is the title of the block type. This is just a name used on the web-site. +
-  * **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. +
-  * **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 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. +
-  * **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"​. +
-  * **Exponential increase:** is a nifty feature that blocks previous mischievers for a longer timespan for each new block. More details in the "​Details"​-section.  +
-  * **Block 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. +
-  * **User:** enables you to choose the username that appears as the blocker. +
- +
-**How to use a defined blocktype** +
- +
-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. +
- +
-Examples: +
-<​code>​ +
-[prompt]# crontab -e +
-0 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 +
-129.241.xxx.xxx +
-<​CTRL-D>​ +
-129.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.pl:​** is the main script which disables and enables ports. +
-  * **autoenable.pl:​** is run by cron and enables ports based on the autoenable-variable. +
-  * **start_arnold.pl:​** is used in combination with a //Blocktype// to invoke a series of disablings. +
-  * **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 ==== +
- +
-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. +
- +
-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** +
- +
-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. +
- +
-1: Locate the victim - i.e. an ip-address. +
- +
-2: List all reasons: +
- +
-<​code>​ +
-[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>​ +
-[prompt]# ./arnold.pl -x disable -a 129.241.xxx.xxx -r2 -t2 +
-129.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. +
- +
-**Enabling a port** +
- +
-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:  +
- +
-<​code>​ +
-[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. +
- +
-==== autoenable.pl ==== +
- +
-''​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. +
- +
-==== start_arnold.pl ==== +
- +
-''​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: +
- +
-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):​ +
- +
-<​code>​ +
-[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. +
- +
-==== 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/​*''​ +
- +
-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. +
- +
- +
-More to come. +
- +
-====== Details ====== +
- +
-More details. +
- +
-Logs of arnold-activity are stored in ''​nav/​var/​log/​arnold''​.  +
- +
- +
-====== Arnold - why the name? ====== +
- +
-The story. +
- +
arnold.1190921784.txt.gz · Last modified: 2007/09/27 19:36 by faltin