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/ Aptana 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 Ruby on Rails 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 web application. 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 Operating system 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