Welcome to the Kewlio Looking Glass =================================== 0. REQUIREMENTS Web-server capable of executing PHP code (e.g. Apache) PHP 5.4+ (tested up to and including 5.6.x) PHP modules needed (some built-in these days): mysqli (optional) pcre sockets spl pecl-ssh2 (optional, required for ssh access) (optional) MySQL server for friendly name lookups Firewall requirements: The looking glass needs to communicate with your routers via telnet. It will also do lookups via WHOIS protocol where possible. You will require outbound connections on TCP ports 23 and 43. 1. QUICK INSTALL a) extract all files into your PHP-enabled webspace b) create a mysql user of your choice c) create a mysql db of your choice. ensure the user above has the full access control for the db. d) import the sql scheme into the mysql db as follows: mysql --user=username --password=password database < klg_schema.sql where username, password and database are substituted for the details in steps 1b and 1c. e) configure the looking glass configuration file, klg_config.php You will need to configure at minimum the mysql details, page name and of course add one or more routers! f) if you have enabled logging, please create the file and ensure it is writable by the webserver/php user, as follows: touch klg.log; chown www klg.log g) go to http://www.your.url/klg.php and test the looking glass! If you do not wish to use MySQL, you can set the relevant configuration variable and skip steps b, c and d above. 2. BGP COMMUNITY NAMES The looking glass makes it possible to translate BGP communities into human readable textual format communities. This is done MANUALLY as no unified method of looking up these has been identified. To add a community, you have to enter a record into the "BGPcommunities" table manually. This can be done on the command line as follows: mysql --user=username --password=password database This will bring you into the mysql interactive mode (type "quit" to exit) As an example, we will add the community 3344:62999 (Kewlio.net null-route) mysql> INSERT INTO BGPcommunities VALUES("3344","62999","NULL-ROUTE"); The "mysql>" prompt is already supplied for you. MySQL should respond with a line indicating "OK" or Success (it is normal for it to say 0 lines affected) Repeat the INSERT command for each community you wish to add. Communities added via this method do not expire. If you do not wish to use this feature, you can disable it in klg_config.php 3. AS NAMES Autonomous system numbers are automatically looked up and translated for you via this looking glass. The looking glass will look up via WHOIS interface in the following order: RIPE,ARIN,APNIC When a match is found, it is entered into the local database and cached for 30 days (or any other time as configured via the configuration file) The looking glass first checks the local database for AS names to avoid excessive lookups. The looking glass uses non-recursive lookups with RIPE-based WHOIS servers to avoid getting automatically blocked for excessive lookups. If you wish to override an AS Name, you can modify the record in the "asnumbers" table. To stop an overridden entry from expiring, set the "ts" field to "0" for any records you wish to override. If you do not wish to use this feature, you can disable it in klg_config.php 4. ROUTER PERMISSIONS This section details the router permissions in the configuration file. Some people may find the permissions confusing, this section tries to make this more understandable. Each router has a "flags" variable, which is a number (see below) $routers[0]["flags"] = 13; The number 32767 demonstrates the flags allowed for this router. This number is calculated by the sum of all the permissions from the "flag_allow_" variables. The above example is comprised of the following flags: $flag_allow_ipv4 1 $flag_allow_show_ip_bgp 4 $flag_allow_show_ip_bgp_summary 8 -- TOTAL 13 At the time of writing, the sum of all flags is 65535. 5. HTML OUTPUT TEMPLATE The looking glass allows you to format the output in (almost) any format. The template file is described in the klg_config.php file as follows: $config["page_template"] = "klg_template.html"; The contents of the template are very basic, with all variables denoted with '%%' before and after the variable name. ALL variables are required in the template and some simple sanity checking is used. The variable names should be self explanatory. The template may not contain any PHP code. The following variable may be set in klg_config.php to set max line length: $config["output_max_width"] = 124;