Hi, This is a draft of the admin doc. Any comments/suggestions/critique or unrelated remarks are welcome :) Alexis 1. Overview This overview implies that the reader has familirized her/himself with the myASn user documentation and frequently asked questions. http://www.ris.ripe.net/myasn/help.html http://www.ris.ripe.net/myasn/faq.html myASn system internally consists basically of three parts: - frontend (web interface presently running on halfweg.ripe.net ) - backend (two perl demon scripts running on weesp.ripe.net ) - database (presently resided on weesp.ripe.net) Frontend consist of collection of Mason enabled web pages and help files that use perl libraries to access myASn database to configure the system and view the results of the processing done by backend. There are two versions of frontend: standalone and LIR Portal. The LIR Portal version of the frontend is not deployed at this moment and will be documented elsewhere. Everything below applies to the standalone version. Backend consist of two perl demon scripts: myasn-scan - that does the processing of the data and generates alarms that are stored in the myasn database myasn-send - that send the email notifications of the alarms that are generated by myasn-scan Both frontend and backend use the same set of perl modules. 2. myASn Installation pre-required modules: Alzabo::MethodMaker Alzabo::Runtime::Schema Apache::DBI DBI Exception::Class IO::Socket Lingua::EN::Inflect Mail::RFC822::Address Net::IP Socket Text::ASCIITable URI XML::Parser myASn installation on both frontend and backend servers should be as simple as checking the myASn package out of master CVS repository. export CVS_RSH=ssh export CVSROOT :ext:cow.ripe.net:/ncc/cvsroot cvs co myasn Further updates of myasn system can be simply done by issuing cvs up in the myasn directory. (use cvs -n up first, to see what's about to happen :) myASn system should be installed on both frontend and backend server into /home/risops/myasn directory. This directory is hard-coded into use lib statements of the following files in the distribution: ./backend/myasn-scan.perl ./backend/myasn-send.perl ./lib/RIPE/NCC/myASn.pm ./www/syshandler as long as it might be specified in myasn.conf configuration file. Once myasn check out the following symbolic links should be made on frontend server (halfweg.ripe.net): ln -s /home/risops/myasn/www /home/risops/www/ris/myasn ln -s /home/risops/myasn/alzabo/schemas/myasn /var/www/alzabo/schemas/myasn XXX Arife might want to add here comments about ris.rc file she made. 3. Configuring myASn Once myASn is installed the configuration of myasn is done via master configuration file, /home/risops/myasn/etc/myasn.conf It basically consists of line with name = value, where in most cases name is the same as a command line arguement of myasn scripts without leading dashes. For example, one could put risdb-username = myasn which would be similar to issuing myasn-scan --risdb-username myasn There are a number of variables that are common to all myASn components, example values are given: risdb_hostname = 193.0.0.210 Hostname or ip address of the RIS database. risdb_username = myasn Username to use for connecting to RIS database. risdb_password = ticvdkjw Password to go with the username above. myasn_database = myasn Hostname or ip address of the myASn database. myasn_hostname = 193.0.0.210 myasn_username = myasn Username to use for connecting to myASn database. myasn_password = tiablkdfd;akj The password to use to connect to myASn datbase. myasn_port = 3306 Port to use to connect to myASn database. pidfile_dir = /home/risops/myasn/log The directory where all the pid/lockfiles will be created. Must be writable to myasn-scan and myasn-send invoking users. The pid files will be created in the format of: $pidfile_dir/myasn-scan.$rrc.pid $pidfile_dir/myasn-send.pid This option can be overwritten with pidfile option that doesnt do rrc name expansion like shown above. The same rules apply to logfile_dir and logfile variables. logfile_dir = /home/risops/myasn/log The directory where all the logfiles will be stored. Same requirement as above. rrc_list = rrc00 rrc01 rrc02 rrc03 rrc04 rrc05 rrc06 rrc07 rrc08 rrc10 rrc11 White-space separated list of the route collectors. Once a new RRC is added it should be added here as well and myasn related tables should be created. XXX Arife more on this? # wait these many seconds for myasn-send loop wait = 900 This one is myasn-send specific. myasn-send will wait this many seconds before starting sending a new serious of alarm notifications by email. # wait these many seconds for myasn-scan loop loop-wait = 300 This is a similar variable for myasn-scan. myasn-scan will wait this many seconds before processing new series of bgp updates. # delay this many seconds before forking next child fork-delay = 30 myasn-scan will wait this many seconds before forking another child process. This is done to desyncronize processing of rrc to avoid peak mysql workloads. To configure the frontend, the Apache's httpd.conf needs the following lines added: <Location /myasn> AuthType Basic AuthName "MyASN Login" AuthUserFile /home/risops/myasn/etc/myasn-passwords Require valid-user SetHandler perl-script PerlHandler HTML::Mason::ApacheHandler PerlSetVar MasonAllowGlobals $User PerlSetVar MasonAutohandlerName autohandler.html </Location> The first section is responsible for authenticating users, and the second one makes sure that the myASn files are handled by Mason. 4. Accounts and users myASn account in standalone version is the same thing as LIR registry in the original LIR portal version. myASn account might have a number of users that share the same alarm configuration and have access to the same information. As a matter of fact myASn doesn't know anything about users, it only cares about the accounts or registries. Usernames are used solely for access authorization purposes and welcome text. As far as user accounts are concerned they are created automatically based on the $User->username and $User->regid global variables. These variables are either initialized by LIR Portal (for LIR Portal version) or by syshandler in the standalone version. In standalone version $User->username and $User->regid are produced by splitting Apache username into username@regid parts. Therefore Apache username alexis@55555 will result in $User->username = 'alexis' and $User->regid = '55555' If myasn account 55555 does not exist yet, it will be created automatically. Therefore to create a new myasn account a new user should be added into /home/risops/myasn/etc/myasn-passwords file. It can be done with htpasswd /home/risops/myasn/etc/myasn-passwords username@accountname password, for example: htpasswd /home/risops/myasn/etc/myasn-passwords alexis@55555 alexis123 will create an account 55555 with username alexis that will have password 123 To change user password the same command as above should be used. XXX - User management, put e-mail template of user request XXX I'm not sure what kind of template I must provide?!? 5. Logging myASn logfiles go into the location specified by --logfile or --logfile-dir options specified either in myasn.conf configuration file or at command line. When myasn-scan is invoked with --logfile-dir, logfile name expansion is being made in a form of: $logfile_dir/myasn-scan.$rrc.log So ig logfile_dir is /home/risops/myasn/log, then for every rrc there will be a separate logfile created. For example for rrc05: /home/risops/myasn/log/myasn-scan.rrc05.log The same applies to --pidfile and --pidfile-dir directives. 6. Backend demon's invokation As mentioned above, two myasn demons are running on weesp.ripe.net (or whatever backend server is in use): myasn-scan myasn-send myasn-scan needs to know to which databases to connect and which credentials to use, location of its logfile and pidfile directory, and loop-wait, fork-delay. All of which is normally specified in myasn.conf file. The only command line myasn-scan should require if myasn.conf is properly setup is: myasn-scan.perl --fork --loop This command tells that myasn-scan should loop, that is keep on waiting on an processing incoming data, and that it should fork a separate process for every rrc. It is important that fork-delay variable is configured, so that not all the processes will be accessing the database exactly at the same time, but with some offset. myasn-send will fork by default so it doesn't require any command line. 7. Maintenance XXX To be developed