Virtual machine administration

Transcription

1 KEYHOLE RADIO TM Virtual 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 Google earth (Free, Pro or Enterprise). Download at 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 1 of 10

2 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: 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: 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 server/router. Page 2 of 10

3 1.5 SSL setup (optional) To enhance confidentiality the system is configured for SSL transport security. To enable this just prefix the URL with or click the SSL link in the 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 3 of 10

4 URL in your browser and if you receive any certificate warnings, add the certificate as before. 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. 2. Licensing Page 4 of 10

5 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 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 Page 5 of 10

6 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) mins North America (US & Canada up to 60N) mins South America mins Africa mins Islands (Atlantic, Pacific and New Zealand) mins Australia mins Page 6 of 10

7 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 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. The number of accounts you can add will depend on your licence. Page 7 of 10

8 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 8 of 10

9 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 9 of 10

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 [email protected] 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 [email protected] CloudRF.com Online radio planning Page 10 of 10