Page 1 of 10
KEYHOLE RADIO
TMVirtual machine administration
Version 3.0 Contents 1. Installation 1.1 System requirements 1.2 Registering the VM 1.3 Network configuration 1.4 Initialisation 1.5 SSL setup 1.6 DNS setup 2. Licensing 3. Operation 4. Administration 4.1 Terrain data 4.2 User accounts 4.3 Antenna patterns 4.4 Ground clutter 4.5 Database admin 5. Trouble shooting 1. Installation 1.1 System requirements VMware software (Player, ESX, Workstation or Fusion). Download VMware player for free at http://vmware.com
Google earth (Free, Pro or Enterprise). Download at http://earth.google.com
At least 120GB free hard disk
At least 2GB free memory
Internet connection (For initial DEM download only)
1.2 Registering the VM
Unzip the folder containing the virtual machine and place it into a folder on your host machine where you have at least 50GB of free space.
The VM (uncompressed) starts with a disk size of ~3.5GB and will grow with usage up to a maximum of 100GB. The elastic disk image will expand as required.
Page 2 of 10
Using your chosen VMware application; choose to ‘open a virtual machine’ then navigate to the folder you created. Select the VMX file inside that folder to have the machine added to your inventory.
1.3 Network configuration
Only dynamic IP addressing (DHCP) is supported, your network must have a DHCP server. The options in the VM’s configuration are disabled as standard.
There are two network services running on the VM. A web server is running on TCP 80 and 443 and SSH on 22. As a minimum port 443 will need to be accessible to use the system. Host specific trouble shooting guides for VM networking are available at vmware.com. Windows 7 firewall trouble shooting guide:
http://kb.vmware.com/selfservice/microsites/search.do?cmd=displayKC&externalId=1004813 1.4 Initialisation
The first time you start up the machine you will be prompted to answer if you moved or copied it. Click ‘I copied it’ then change the encryption password when prompted and proceed to boot. Ensure you note the password you enter as this is not recoverable. Once at the terminal login you will be presented with networking information displaying the IP address of your VM which you must type into a web browser like so:
https://192.168.x.x
If you do not have any IP addresses listed then check your network mode (host only, NAT or bridged) and confirm the host OS has network connectivity and can see a DHCP
Page 3 of 10 1.5 SSL setup (optional)
To enhance confidentiality the system is configured for SSL transport security. To enable this just prefix the URL with https:// or click the SSL link in the http:// interface.
The certificate used will not initially be recognised by web browsers until it is installed manually. To do this, click ‘I understand the risks’ then ‘Add Exception’ in Firefox. The wording will vary by browsers but the concept is the same.
1.6 DNS setup (optional)
To access Keyhole Radio via a friendly name instead of an IP address, click the ‘DNS setup’ link in the left menu to download a Windows batch script called ‘updatehosts.bat’. You must save this script to your computer and run it as an administrator. The script will append an entry to your ‘hosts’ file which maps names to IP addresses. To test if it has worked visit this
Page 4 of 10
URL in your browser and if you receive any certificate warnings, add the certificate as before.
https://keyholeradio
If it doesn’t work, open C:\Windows\System32\drivers\etc\hosts and check the
‘keyholeradio’ entry has the correct IP address, if not delete the entry and re-run the script. If you change your IP address you will need to repeat this process or establish your own DNS system on your network to map the IP address to keyholeradio. If you are ever prompted with a security warning choose to add an exception, Get the certificate then ‘Confirm security exception’ to confirm you trust the site.
Page 5 of 10
Without a valid licence the machine will revert to evaluation mode which enables all features but only in the region of the Falkland Islands in the South Atlantic only for just one user. To unlock all features you must click the ‘licensing’ link in the bottom menu and enter your email and licence string. Be warned that an incorrect licensing attempt will automatically place the machine into evaluation mode. Once licensed your details and licence limits will be visible on the main screen.
3. Operation
The main menu lists links to all the key features.
The three large icons in the middle are shortcuts to the Android app, Google earth layer and optional web interface. Documentation for all can be found in the left menu.
To launch the Google earth KML layer click the Google earth icon.
When you open Keyhole Radio layer in Google earth for the first time you will be challenged for a login for an account. See accounts section for
creating accounts.
A successful login will display a screen overlay with your username and IP address and a nested network link your left hand places menu. After this point, operation is the same as the public Keyhole Radio interface and documentation can be found via the documentation link on the menu or online at http://keyhole.cloudrf.com/docs/krs
Page 6 of 10 4. Administration
4.1 Terrain data
The system uses SRTM2 terrain data from NASA converted to a format (SDF) suitable for radio planning. The full data set is nearly 80GB so only a small selection (Islands) has been pre-installed on the system to facilitate testing. Once established users can choose to download more data (Internet connection required) via the ‘SRTM-download.sh’ command. To execute this command, login to the command shell, issue the command then answer the questions. The destination location will be /var/SRTM3 and the regions are defined as follows:
Region Tiles Approximate download time
Eurasia (Europe, Middle East, Russia, Far east) 5876 489 mins North America (US & Canada up to 60N) 2413 201 mins
South America 1807 150 mins
Africa 3250 270 mins
Islands (Atlantic, Pacific and New Zealand) 141 11 mins
Page 7 of 10
Do not interrupt the process once started. Download times will vary by connection and time of day. As the data is hosted for free by a third party (US Geological survey) users are encouraged to be courteous and patient when acquiring the data.
To visually confirm the data for your target region has been downloaded and converted ok you can open a layer in Google earth from the main menu (‘Terrain Coverage’) which will draw a green rectangle for covered areas. Falkland Islands will always be covered.
4.2 User accounts
To create a user account go to the ‘User accounts’ section from the main menu (requires admin login) and enter an email address or username and a password/PIN. Ensure the password is at least 6 characters. Click save to have the system add the account to the database and secure the password with a SHA1 hash. Ensure you note the password as the hashing process cannot be reversed. Accounts can also be added manually to the ‘users’
table in the ‘api’ SQL database from the terminal.
Page 8 of 10 4.3 Antenna patterns
The system ships with a significant number of 3D antenna patterns for enhancing planning accuracy. These can be viewed from the main menu via the ‘Antennas’ link.
Existing patterns can be sorted by directional gain and the horizontal and vertical plots viewed in full by clicking the image.
New patterns can be added to the system providing they are in .ant format which is 360 rows of horizontal relative field strength referenced to 0 followed by 360 rows of vertical relative field strength, again referenced to 0. For reference an example ant file is provided at /API/antennas/example.ant
4.4 Ground clutter
You can simulate man made obstacles by uploading KML layers containing points, lines or polygons. Each KML point should have a height defined otherwise it will be assigned a default height of 8m above ground level. To add clutter create some points with Google earth, then save it as a KML file (Not KMZ). Next click the ‘Clutter upload’ link on the main menu and upload the KML file you saved. If successful you should receive a list of co-ordinates for observed points. Ensure
your layer is not nested in a KML folder structure otherwise this can fail.
Each user has their own private clutter and can choose to benefit from everyone’s clutter each time they perform a calculation. At the point of upload you determine for which user the clutter is for with the default being user1. The user can be changed easily by clicking one of the links at the top of the clutter upload page.
Page 9 of 10 4.5 Database administration (Advanced users)
The system is supported by a MySQL database which you can login to with username krs and password krs1. Be very careful when working with the database as a mistake here can break your system.
Use this command to access the api database: mysql –u krs –p api
Common admin tasks: Delete all calculations: delete from rflog where 1; delete from bounds where 1; Delete clutter for user 2:
delete from clutter where uid=2;
5. Trouble shooting
VM has no IP address listed
Check which networking mode you are using within the VM’s settings menu and confirm your hosts network adapters are functioning ok and connectivity is as expected. Next login at the welcome screen with krs/krs1 and issue ifconfig to see a list of network adapters. As
Page 10 of 10
well as lo (loopback interface) you should have at least one other with an IP address. If not, power off the VM switch to a different network mode and power it on again.
Keyhole radio layer opened but no login prompt appears
The login prompt is a separate window which occasionally becomes obscured by the main Google earth window. To bring it to the fore ground in Windows use Alt-tab.
Calculation fail
If after entering settings and running a calculation it dies early with a calculation fail message there are a variety of reasons this could be. The first is licensing as an invalid licence will disable the engine. The only way to re-enable it is to enter a valid licence. To eliminate the Keyhole Radio interface as source of the problem you can attempt a calculation via one of the API examples located at /API/. If this fails then you must contact support@cloudrf.com with your purchase details for assistance.
Calculation failed with a numerical error code
If you run a calculation and receive an error response in the form of a number then this usually means one of your input parameters is out of bounds. Check all your input values for bad data and if that doesn’t fix it, open up your calculation archive from the main menu and select ‘use as template’ to reload settings from a past calculation which you know worked.
For assistance contact the support address at support@cloudrf.com
CloudRF.com Online radio planning
