User Manual Network Maintenance Tool for Evolving Computer Networks

Manfred Ramoser

07 Content 1 Development ...... 3 1.1 Used programs and versions ...... 3

2 Configuration ...... 3 2.1 Database ...... 3 2.2 LDAP server ...... 3 2.3 API...... 3

3 API...... 4

4 Deployment ...... 7

2

1 Development

1.1 Used programs and versions Name Version Link Ruby 1.8.6 (2007-03-13 http://rubyinstaller.rubyforge.org/wiki/wiki.pl for Windows patchlevel 0) http://www.ruby-lang.org/en/ for other OS’s Rails 1.2.3 http://www.rubyonrails.org/down Eclipse 3.3.0 http://www.eclipse.org/downloads/ 1.5.0.00001 http://www.aptana.com/download_rails_rdt.php (Eclipse plug-in) RadRails 0.8.0.200707021211 http://www.aptana.com/download_rails_rdt.php (Eclipse plug-in) Ruby 0.9.0.707021729NGT http://rubyeclipse.sourceforge.net/download.rdt.html development tools PostgreSQL 8.2 http://www.postgresql.org/download/ MySQL 5.0 http://dev.mysql.com/downloads/ CURL 7.16.3 (i586-pc- http://curl.haxx.se/download.html mingw32msvc) libcurl/7.16.3 zlib/1.2.2

2 Configuration

2.1 Database provides a very clean way to handle the configuration of the database. It stores database related information in a file called “database.yml” in the “config” folder of the . There are three different environments which can be set up; development, production and testing. For each environment it is possible to set another database adapter, username, password and host. The database configuration file makes it easy to switch from one database system to another. For example if MySQL should be used instead of PostgreSQL, in the normal case only the information in this file has to be changed. To set MySQL as database put “adapter: mysql” and modify the other entries according to your database settings. When switching from one database to another there may show up problems with the different representations of dates.

2.2 LDAP server To make the configuration of the LDAP server changeable there exists a file which contains all the required information which is called “ldap_server.yml”. It can be found in the folder “config” of the Rails application and stores the host name, the port number, the filter word and the base path on witch the search should be performed. What can not be changed is that the connection is encrypted; this means that the LDAP server sends a certificate which is accepted without checking it. Another setting which cannot be changed is that the search looks also in sub trees of the path. If a non encrypted connection to the LDAP server is required the port number can be changed to 389.

These last three modifications can only be made directly in the code.

2.3 API To make it possible to the user to change the behaviour of the API there exists a configuration file for the API. It is located in the folder “config” and is named “api.yml”. Inside this file the user can set if 3 he wants to include all associated objects if he requests a list of devices in xml format. E.g. when a list of computers is retrieved and “include_associated_objects” is set to true the xml file contains also the operating systems, display, networks, lans… which belong to each computer.

3 API PLEASE NOTE that all the examples where tried out on a local machine and therefore the URL to the application is localhost:3000. The correct URL’s are determined after deployment and should be something like https://lamj.inf.unibz.it:8000.

For the API development I used REST which is supported very well by Rails. To create a REST controller one should use “scaffold_resource controllerName” instead of “scaffold controllerName”. This creates a controller, a class, the associated unit and functional tests and adds an entry in the route.rb file which tells Rails how to handle requests. In the normal case Rails takes input URL’s like “www.myserver.com/controllername/action”. This means that for example the request “www.myserver.com/computers/new” would cause the execution of the method new in the computers controller and then the rendering of the template “new.rhtml”. This means that for each action that should be performed a method must exist in the controller which takes care to handle the action. The standard actions are list, new, edit, create, update and destroy. For a REST web service the HTTP methods GET, PUT, POST and DELETE are used to tell the web application which operation to perform. This means that the URL remains the same except for POST, because it creates a new entry. The URL consists of the host, the controller and the id of the element which is modified or requested.

HTTP method and URL Action which is performed GET www.myserver.com/computers/id Gets the specified computer in xml format. PUT www.myserver.com/computers/id Updates the specified computer. POST www.myserver.com/computers Creates a new computer; no id required. DELETE www.myserver.com/computers/id Deletes the specified computer.

This works well but for my application I needed something more. For example I needed a way to specify if an update is a global update or a normal update and I needed a way to retrieve the history of a device in xml format. I resolved these issues by sending additional attributes to the server which tells the application what to do. To test the functionalities of the API I used curl which is a command line tool to perform HTTP requests with parameters and data. As explained in chapter Decisions – Authentication for the API for every request the authentication data has to be provided. I was not able to manage the session with curl like a web browser does, but if a client is able to do that only one login is required for all requests. In order that the application recognizes that this is an API request in the header the “accept” variable has to be set to “application/xml”. To provide the authentication data I had to specify -v --basic –u “username:password” or –v --basic –u “username” if you would like to be prompted for the password. It can then be inserted without seeing it.

Command to login for the API (this command was not tested by me) curl –H “Accept:application/xml” –X POST –d “user[name]=username&user[password]=pswd” http://localhost:3000/login/try_to_login

I will show here some commands and explain them what they do.

4

The following command retrieves an XML file containing all actual computers. To get a list of other devices simply exchange computers with the name of the controller that you want to get. curl -v --basic -u "username" -H "Accept:application/xml" -X GET http://localhost:3000/computers Alternatively one could also omit the header and append .xml to the URL. curl -v --basic -u "username" -X GET http://localhost:3000/servers.xml

Device URL to retrieve list of actual devices Network http://localhost:3000/networks.xml LAN http://localhost:3000/lans.xml Computer http://localhost:3000/computers.xml Server http://localhost:3000/servers.xml Server unit http://localhost:3000/server_units.xml Server unit pool http://localhost:3000/server_unit_pools.xml Copier http://localhost:3000/copiers.xml Printer http://localhost:3000/printers.xml

Name URL to retrieve the list Event http://localhost:3000/events.xml Display http://localhost:3000/displays.xml Drive type http://localhost:3000/drive_types.xml Software http://localhost:3000/softwares.xml Service http://localhost:3000/services.xml http://localhost:3000/operating_systems.xml Cartridge http://localhost:3000/cartridges.xml User http://localhost:3000/users.xml

The following command creates a new desktop computer. First the authentication data is specified, then I specified that I want xml as a result. Here I do not get any result, but if there is an error then I get the error message in xml format. Then I specify with the –d instruction the data which has to be send to the web application. For the associated objects like software, network, drive type and operating system I have to provide an array of integers which hold all ids to which I want to associate the desktop computer. Finally I have to specify the URL to which I want to send the data. In this case I specify only the controller “desktops” because curls automatically command automatically a new entry is created. curl -v --basic -u "username" -H "Accept:application/xml" -d "device[unibz_stock_number]=123&device[type_model]=model&device[serial_numb er]=8888&device[purchase_date]=2000-01- 01&device[cpu_speed]=2000&device[main_memory_size]=1024&device[memory_size] =500&device[ip_address]=100.100.100.100&device[location]=POS&device[name]=m y name&device[description]=description&device[display_id]=1" -d software_ids[]=1 -d operating_system_ids[]=1 -d network_ids[]=1 -d network_ids[]=2 -d lan_ids[]=1 -d drive_type_ids[]=1 http://localhost:3000/desktops

Device Associated objects which can be specified Network LAN network_ids[] Computer device[display_id], software_ids[], drive_type_ids[], network_ids[], lan_ids[], operating_system_ids[]

5

Server device[server_unit_id], device[server_unit_pool_id], device[operating_system_id], software_ids[], service_ids[], lan_ids[] Server unit device[server_unit_pool_id], network_ids[] Server unit pool Copier device[network_id], cartridge_ids[] Printer device[network_id], cartridge_ids[]

This command updates an already existing desktop computer. The differences to the previous request are the PUT command and that the URL has to specify the id of the computer which is going to be updated. With this instruction the specified attributes are updated if they are “normal” attributes and the others are copied from the last most actual desktop computer. Attributes which are global are simply ignored and if there are unknown attributes the user gets an error message. Be aware that you have also to commit the associated objects, also if you don’t want to change them; otherwise the updated device has no associated objects. curl -v --basic -u "username" -H "Accept:application/xml" -X PUT -d "device[cpu_speed]=2000&device[main_memory_size]=11&device[memory_size]=22& device[ip_address]=200.200.200.200&device[location]=location&device[name]=m y new name&device[description]=description&device[display_id]=1" http://localhost:3000/desktops/24

To perform a global update the attribute “is_global_udpate=true” has to be added. This instruction works in the same way as the normal update. It updates only the provided attributes and reuses the not provided ones from a computer. The difference is that with this instruction all entries of a computer are changed which have the same temporal id. curl http://localhost:3000/computers/24 -v --basic -u "username" -H "Accept:application/xml" -X PUT -d "device[unibz_stock_number]=999&device[type_model]=new model&device[serial_number]=333&device[purchase_date]=1999-09- 09&device[cpu_speed]=5000&is_global_update=true”

The following command destroys a desktop computer. There is the HTTP DELETE command and the URL with the id of the computer which should be deleted. curl -v --basic -u "username" -X DELETE http://localhost:3000/computers/54.xml

To get the history of a device curl http://localhost:3000/computers.xml?temporal_id=1 -v --basic -u "username"

To perform a search through the API curl http://localhost:3000/computers.xml?search_key=E531 -v --basic -u "user:user"

To perform a temporal search through the API curl http://localhost:3000/computers.xml?date=2007-09-04 -v --basic -u "user:user" or

6 curl http://localhost:3000/computers.xml?date=2007-09-04+12:10:07 -v -- basic -u "user:user"

4 Patch instructions An important patch fixes an error with the “has and belongs to many” relation. To apply the patch, take the modified versions of the files from the CD if available.

Or follow the instructions which can be found at http://dev.rubyonrails.org/attachment/ticket/7576/has_and_belongs_to_many_interpolation.diff and replace or insert the specified code in the right place.

These are the files which have to be updated (path may differ with other versions): C:\ruby\lib\ruby\gems\1.8\gems\activerecord-1.15.3\test\associations_test.rb C:\ruby\lib\ruby\gems\1.8\gems\activerecord-1.15.3\test\fixtures\post.rb C:\ruby\lib\ruby\gems\1.8\gems\activerecord- 1.15.3\lib\active_record\associations\has_and_belongs_to_many_assiciation.rb

5 Deployment instructions These instructions were tested under Windows XP SP2.

For Linux the instructions may differ slightly and in front of the commands „sudo“ should be used because username rights are required.

The following instructions have to be performed on the server on which the application should be deployed.

1. Copy the application folder (Network_Maintenance_Tool) to the server. 2. Install Ruby: Windows: http://rubyinstaller.rubyforge.org/wiki/wiki.pl Ubuntu: sudo apt-get update sudo apt-get dist-upgrade sudo apt-get install ruby ri mysql-server libmysql-ruby sudo ruby1.8-dev ruby1.8-examples 3. Install Rails: gem install rails -y --no-rdoc --no-ri 4. Install Ferret: gem install ferret -y --no-rdoc --no-ri select appropriate version (mswin32 for Windows) gem install acts_as_ferret -y --no-rdoc --no-ri 5. Install LDAP: gem install ruby-net-ldap -y --no-rdoc --no-ri

ONLY FOR WINDOWS: download: http://webtest.wvu.edu/users/cbscharf/ldap/ldap.so Put ldap.so in: 7

C:\ruby\lib\ruby\site_ruby\1.8\i386-msvcrt 6. Install with: gem install mongrel -y --no-rdoc --no-ri select appropriate version (mswin32 for Windows) 7. For Ubuntu the components have to be copied to a different folder: cp /var/lib/gems/1.8/bin/* /usr/bin 8. Install MySQL Windows: http://dev.mysql.com/downloads/mysql/5.0.html#win32 Ubuntu: sudo apt-get install mysql-server sudo /ust/bin/mysqlusername –u root password mypassword 9. Login as root to MySQL with command line: Windows and Ubuntu: mysql -u root –p 10. Create database: create database network_maintenance_tool_production 11. Create user and grant access: USE network_maintenance_tool_production grant all on network_maintenance_tool_production to rails@localhost identified by ‘rails’; 12. Go to the directory of the application (cd Network_Maintenance_Tool) and migrate the database: environment RAILS_ENV=production db:migrate 13. Create power user Login to MySQL (see 8). USE network_maintenance_tool_production INSERT INTO users (name) VALUES (‘yourUsername e.g. mramoser’); 14. Apply the patches (see 4 Patch instructions) 15. Start mongrel: mongrel_rails start -d -p 8000 -e production

-d…mongrel is started as deamon -p…the port number -e…environment of rails which should be used 16. To stop mongrel: Windows: Ctrl+C Unix: mongrel_rails stop

8