remote maintenance access service (rmas) user manual · password. following the link in the email,...
TRANSCRIPT
____________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 1 of 54
Document Reference: TEC4362/J/23.10.2019
Document Type: User Manual
Remote Maintenance Access Service (RMAS)
User Manual
Business Function: Costain Technology Solutions
Document Owner: Charlotte Webb
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 2 of 54
REVISION HISTORY:
Document number TEC4362/J/23.10.2019
Title Remote Maintenance Access Service (RMAS) User Manual
Project No.: 1564/1/0 Product No.: 730 Status: Definitive
Current Revision:
Prepared By
(Author)
Reviewed By
(Reviewer)
Approved By
(Authorisation) Date
Print name Mubin Khan
Jason Rutherford
Vimal David Charlotte Webb 23/10/2019
Changes Updated as per RMAS WP-004 (Improve Device Information Page), WP-008 (Improve Device List Page) and WP-006 (Web Interface Change)
Change History:
Rev Prepared By Reviewed By Approved By Date
A
Print name James Carr / James Ruffle
Megan O’Connor Louis Thompson 22/02/2016
Changes Original Issue
B
Print name Sergio Martin Sánchez
James Ruffle Dave Collins 03/03/2017
Changes Created User Manual
C
Print name Boriss Redkins Richard Shapland
Jose Trujillo Brenes
Dave Collins 27/04/2017
Changes Updated as per RMAS Phase 1.5 changes
D
Print name Boriss Redkins James Ruffle
Dave Collins 25/05/2017
Changes
Updated as per RMAS Phase 2 release 1 changes
E
Print name
Jose Trujillo Brenes
Dave Collins Dave Collins 10/08/2017
Changes
Updated as per RMAS Phase 2 release 2 changes
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 3 of 54
F
Print name Manuel Benitez Sanchez
Sabrina Rayfield Dave Collins 22/09/2017
Changes
Updated as per RMAS Phase 2 release 3 changes
G
Print name Boriss Redkins Dave Collins Dave Collins 23/11/2017
Changes Updated as per RMAS Phase 2 release 4 changes
H
Print name Boriss Redkins Simon Wade Dave Collins 30/01/2018
Changes Updated as per RMAS Phase 2 release 5 changes
I
Print name Mubin Khan Vimal David Charlotte Webb 23/09/2019
Changes Updated as per RMAS WP-003 changes (Improve firmware functionality)
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 4 of 54
CONTENTS: Page No.
1.0 DOCUMENT PURPOSE 9
1.1 SYSTEM OVERVIEW 9
2.0 FUNCTIONALITIES IN RMAS SERVICE 10
2.1 USER MANAGEMENT 10 2.1.1 ACCESSING THE SERVICE 10 2.1.2 RMAS WELCOME PAGE 11 2.1.3 USER REGISTRATION 12 2.1.4 PASSWORD CHANGES 13 2.1.5 TWO FACTOR AUTHENTICATION 15 2.1.6 VIEW USER ACCOUNT DETAILS 17 2.1.7 EDIT USER ACCOUNT DETAILS 17 2.1.8 LOCKED USER ACCOUNT 18 2.1.9 SUSPENDED USER ACCOUNT 18 2.1.10 ACTIVITY HISTORY 19 2.2 DEVICE MANAGEMENT 20 2.2.1 ROADSIDE DEVICE LIST VIEW 20 2.2.2 FILTERS FOR DEVICE LIST 21 2.2.3 DEVICE ENROLMENT 21 2.3 DEVICE DASHBOARD 25 2.4 DEVICE OPERATION 26 2.4.1 RESET DEVICE 28 2.4.2 DOWNLOAD LOGS 29 2.4.3 SCHEDULE LOGS DOWNLOAD 29 2.4.4 REMOVE OLD SSH PUBLIC KEYS 30 2.4.5 VERIFYING FIRMWARE 30 2.4.6 UPGRADING FIRMWARE 32 2.4.7 REMOVING A DEVICE FROM RMAS 33 2.4.8 UPLOAD FIRMWARE FROM FIRMWARE STORE TO ROADSIDE DEVICE 34 2.4.9 DEVICE DATA REFRESH 35 2.4.10 DOWNGRADE FIRMWARE 36 2.4.11 CONSOLE 37 2.4.12 EMENU 38 2.4.13 WEB INTERFACE 40 2.5 BULK FIRMWARE OPERATIONS 40 2.6 DEVICE FIRMWARE MANAGEMENT 44 2.6.1 UPLOADING FIRMWARE TO FIRMWARE STORE ON RMAS 44 2.7 SSH KEY 46 2.7.1 VIEW CURRENT PUBLIC KEY 46
3.0 API REFERENCE 47
3.1 API TOKENS MANAGEMENT 47 3.1.1 VIEWING API TOKENS 47 3.1.2 ADDING OR REMOVING API TOKENS 49 3.2 DEVICE OPERATION 49 3.2.1 REFRESH RMAS DEVICE DATA 49 3.2.2 REFRESH RMAS DEVICE DATA EXAMPLE 50
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 5 of 54
3.2.3 DOWNLOAD LOGS INTO RMAS 50 3.2.4 DOWNLOAD LOGS INTO RMAS EXAMPLE 50 3.3 RMAS OPERATION 51 3.3.1 CHECK OPERATION RESULTS 51 3.3.2 CHECK OPERATION RESULTS EXAMPLE 51 3.3.3 GET DEVICE DATA 52 3.3.4 GET DEVICE DATA EXAMPLE 52 3.3.5 GET DOWNLOADED LOGS 53 3.3.6 GET DOWNLOADED LOGS EXAMPLE 53
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 6 of 54
List of Figures Figure 1 Login .................................................................................................................................... 10 Figure 2 Welcome to RMAS ............................................................................................................... 11 Figure 3 User Registration ................................................................................................................. 12 Figure 4 Successful User Registration ............................................................................................... 13 Figure 5 Reset Password ................................................................................................................... 13 Figure 6 Request Password Reset ..................................................................................................... 14 Figure 7 Change Password ................................................................................................................ 15 Figure 8 Two Factor Authentication.................................................................................................... 16 Figure 9 View User Details ................................................................................................................. 17 Figure 10 Edit User Details ................................................................................................................ 18 Figure 11 Activity History ................................................................................................................... 19 Figure 12 Activity Details .................................................................................................................... 20 Figure 13 Device List ......................................................................................................................... 21 Figure 14 Device Enrolment ............................................................................................................... 22 Figure 15 Upload Device Enrolment CSV page ................................................................................. 23 Figure 16 Device Enrolment CSV example ........................................................................................ 23 Figure 17 Device Dashboard.............................................................................................................. 25 Figure 18 Device Operation – Device Details ..................................................................................... 26 Figure 19 Device Operation – Device History ..................................................................................... 26 Figure 20 Device Operation – Device Operations .............................................................................. 27 Figure 21 Reset Device...................................................................................................................... 28 Figure 22 Download Logs .................................................................................................................. 29 Figure 23 Remove Old Public SSH Keys ........................................................................................... 30 Figure 24 Verify Firmware .................................................................................................................. 31 Figure 25 Upgrade Firmware ............................................................................................................. 32 Figure 26 Device Removal Form ........................................................................................................ 33 Figure 27 List of Approved Firmware in the Firmware Store ............................................................... 34 Figure 28 Upload Firmware Confirmation ........................................................................................... 34 Figure 29 Downgrade Firmware ......................................................................................................... 36 Figure 30 Console Operation PEW number dialog ............................................................................. 37 Figure 31 Console Access ................................................................................................................. 38 Figure 32 E-Menu PEW number dialog .............................................................................................. 39 Figure 33 E-Menu Access .................................................................................................................. 39 Figure 34 Web Interface Access PEW number dialog ........................................................................ 40 Figure 35 End Web Interface Session ................................................................................................ 40 Figure 36 Bulk Operation Confirmation .............................................................................................. 41 Figure 37 Bulk Operation Details ....................................................................................................... 42 Figure 38 Bulk Operation Progress .................................................................................................... 43 Figure 39 Bulk Activity Details ............................................................................................................ 44 Figure 40 Upload Firmware to Firmware Store ................................................................................... 45 Figure 41 View Public SSH Key ......................................................................................................... 46 Figure 42 API Tokens ........................................................................................................................ 47 Figure 43 API Token Details .............................................................................................................. 48 Figure 44 Adding API token ............................................................................................................... 49
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 7 of 54
References:
[1] TR2597 Generic Roadside Device Requirements for Remote Access
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 8 of 54
Glossary: RMAS Remote maintenance access service 2FA Two factor authentication NRTS National Roads Telecommunications Service RCC Regional Control Centre CURL Command line tool for making HTTP requests
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 9 of 54
1.0 DOCUMENT PURPOSE
This manual, documents the features provided by the RMAS systems to a RMAS user.
1.1 SYSTEM OVERVIEW
The main objective of the RMAS Core System is to minimise the need for site visits. To this end, the RMAS System will provide authorised users a secure interface for remote access to TR2597A [1] compliant Roadside Devices in order to carry out maintenance tasks like firmware upgrade, download static data, view/download application log files, etc.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 10 of 54
2.0 FUNCTIONALITIES IN RMAS SERVICE
RMAS is targeting to support all supported version of Internet Explorer available for supported Windows Desktop operating systems. and all supported version of Chrome and Firefox browsers.
2.1 USER MANAGEMENT
2.1.1 ACCESSING THE SERVICE
When a user wishes to use RMAS for the first time the user registration process must be completed. This is available from the RMAS login page (https://www.he-rmas.org.uk), press the “Sign Up” button to view the User Registration page.
Figure 1 Login
If the user is already registered to use RMAS enter the username (email address1) and password to login. As soon as the user gets into RMAS, as shown in Figure 2, a page will be displayed and the user will be able to see last successful login. If a user is logged in the RMAS system and is idle for more than 10 minutes, then the user will be logged out unless there is an ongoing activity. A user account can only have one active connection to the RMAS system at a time. In case of not logging out properly, the user might need to wait up to 10 minutes for the session to expire.
1 Note that the local part of email (prior to @) is case sensitive and should be used consistently in all logins
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 11 of 54
2.1.2 RMAS WELCOME PAGE
RMAS welcome page contains Service Status and News sections. These will display any information related to, planned downtime or which new features were added in the last release. The welcome page also contains user manual links appropriate for the given user, and links to RAIT installer and RAIT user manual. Information on the Service Desk can be found at the bottom of the page.
Figure 2 Welcome to RMAS
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 12 of 54
2.1.3 USER REGISTRATION
User registration allows a user to sign up on the system; all registrations must be approved by a HE Approver or a Service Manager. When a user wants to register as an HE Approver the corresponding tick box should be selected.
Figure 3 User Registration
All the fields on the User Registration page must be completed (apart from Mobile number and HE approver checkbox which are optional). It is essential that the email address2 is entered correctly as this is used as the account username and the address that RMAS uses for communication with the user. The page can only be submitted when the user has read and accepted the “Terms of Use Agreement”.
2 Note that the local part of email (prior to @) is case sensitive and should be used consistently in all logins
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 13 of 54
When the form is completed and submitted, the user is redirected to the Login Page.
Figure 4 Successful User Registration
When the user registration request is approved by the project sponsor (HE Approver) the user is sent an email containing a link to set the account password for the first time. This link takes the new user to a page to set the password. If the user registration request is rejected, the user will also be sent an email informing them about the reason of rejection.
Figure 5 Reset Password
2.1.4 PASSWORD CHANGES
A user can reset/change their password when the user:
• Is unable to access the account
• Requests a password change
• Password has expired
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 14 of 54
New passwords must follow the HE password policy for the password strength and will be validated by the system. Details of the HE password policy can also be found on the reset/change password pages.
2.1.4.1 USER UNABLE TO ACCESS ACCOUNT
If a user is unable to access account, the user can select “Reset Password” from the login page. A form is displayed asking for the email address3 of the account that needs a password reset.
Figure 6 Request Password Reset
For a correctly entered email address, an email is sent providing instructions on how to reset the password. The email includes a unique, one time and time limited link to reset the password. Following the link in the email, the user is presented with the Reset Password page listing the HE password policy and providing input fields to enter the new password and a verification of the new password. Once submitted, the user’s password is reset and a confirmation email is sent to the user.
2.1.4.2 USER REQUESTS A PASSWORD CHANGE
If the user is logged in, clicking the username in the top right corner of the page opens a menu with “Change Password” option. The user is presented with a page listing the HE password policy and providing input fields for the user to enter their current password, new password and a verification of the new password. Once submitted, the user’s password is reset and a confirmation email is sent to the user.
3 Note that the local part of email (prior to @) is case sensitive and should be used consistently in all logins
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 15 of 54
Figure 7 Change Password
2.1.4.3 USER PASSWORD HAS EXPIRED
Once the user is logged in, if the user password has not been changed for 90 days, the Change Password page is displayed to allow the user to change it. This prompt will be displayed every time the user logs in until the password is changed.
2.1.5 TWO FACTOR AUTHENTICATION
2.1.5.1 TWO FACTOR AUTHENTICATION OVERVIEW
Two factor authentication requires the use of a TOTP authenticator app, for example Google authenticator. Two factor authentication works by having a per user secret, stored securely on the RMAS system and entered into the authenticator app. The authenticator app generates a new token every 30 seconds based on this known secret and is then verified by the RMAS system when the user enters it for each login attempt. When logging in, a user with 2FA enabled will be presented with an extra field in which the token from the authenticator app will need to be entered.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 16 of 54
2.1.5.2 ENABLING TWO FACTOR AUTHENTICATION
Any user can select to enable 2FA on their account. Once enabled it cannot be disabled except by calling the RMAS service desk. To enable 2FA, select the “Security token” item from the user menu. Here the current status of 2FA for the account is displayed along with instructions on enabling 2FA.
Figure 8 Two Factor Authentication
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 17 of 54
2.1.6 VIEW USER ACCOUNT DETAILS
The name of the current logged-in user appears on the top right hand corner of the page. Clicking the username opens a menu with an option called “View Profile”. Selecting this option, the user is directed to the “User Details” page that displays the user account details.
Figure 9 View User Details
2.1.7 EDIT USER ACCOUNT DETAILS
To edit user details, the user has to navigate to the “User Details” page. Clicking the “Edit” button, makes all the fields on the page editable except the email address. If the email address is to be changed then the user needs to contact the RMAS service desk. Otherwise, the changes are reflected immediately after the user clicks the “Save” button and a confirmation email is sent to the user.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 18 of 54
Figure 10 Edit User Details
2.1.8 LOCKED USER ACCOUNT
A user account will be locked if it has not been used for 90 days or longer. It is also locked if a user enters an incorrect password and/or the 2FA code more than five times consecutively. When the user account is locked, the user is notified via email. The user has to contact the RMAS service desk to request that the account be unlocked.
2.1.9 SUSPENDED USER ACCOUNT
If a user account or a user group has been suspended, the user will not be able to log in to the RMAS service and the user should see a message informing that the account has been locked. The user should contact the project sponsor for further information.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 19 of 54
2.1.10 ACTIVITY HISTORY
To see history of device operations, navigate to the user menu and select Activity History. There is a table that shows the main details of the operations sorted by date:
Figure 11 Activity History
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 20 of 54
To see detailed information about an operation, click on a corresponding entry in the table:
Figure 12 Activity Details
For download logs activity the Activity Details will contain a “Download” link to the archive containing the log files. These links are available for 7 days.
2.2 DEVICE MANAGEMENT
2.2.1 ROADSIDE DEVICE LIST VIEW
The “Device List” page displays a list of devices accessible to the user in the RMAS system. A total of 10 devices are displayed on each page, user can navigate between pages using the buttons provided at the end of the device list. A device can be selected by clicking on the IP address. This displays the “Device Operation” page with information about the device and lists available actions for the device.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 21 of 54
Figure 13 Device List
2.2.2 FILTERS FOR DEVICE LIST
On the roadside device list view, a user can search for devices that match specific criteria using filters. These filters reduce the number of displayed devices by selecting certain attributes of interest. The user will have some default filters already applied based on the user’s group and these filters are detailed in the text above the filter fields. This will restrict the devices that can be accessed in the RMAS system. In addition to default filters, user is presented with the following filter fields,
• IP address
• HE geographic address
• RCC
• Manufacturer
• Firmware version
• Maintenance Region
• Device status The RCC field will appear as a disabled text field if user’s group permissions allow user to view devices belonging to only one RCC or as a drop-down list if user is allowed to view devices from more than one RCC. Device status is presented as a drop-down list to the user with options like OK, ENROLLED, FAULTY and PENDING.If device status has a single predefined filter, then it will be disabled, similar to RCC dropdown. The user can add extra filters and modify or reset the applied filters within the constraints imposed by the group filters. Note that filters for text fields are of “start with type” and filters for dropdown fields need to be exact match.
2.2.3 DEVICE ENROLMENT
2.2.3.1 SINGLE DEVICE ENROLMENT
In order to enrol a new device in the RMAS system, the user needs to click the “Add device” button on the device list page. This opens the “Device Enrolment” page with fields to enter
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 22 of 54
device details. If the form is submitted with valid details, the device should appear in the device list view. If the device that is being enrolled is present in the latest version of NRTS live data imported into RMAS, the status of the device is set to “ENROLLED” otherwise the device status is set to “PENDING”. If the device status is set to “ENROLLED”, RMAS system attempts to connect to the device and download static data from the device. Enrolling the device, updates the Device history in the device operation page. The enrolled device status and timestamp is updated in the list. If a bandwidth limit is entered (optional field) then it is used when connecting to the device providing that it is within the permissible limits for the span type. If the entered value exceeds the limit, then the connection speed used will be restricted to the maximum for the span type.
Figure 14 Device Enrolment
2.2.3.2 DEVICE RE-ENROLMENT
The re-enrolment process uses the same form as the enrolment process. Therefore, if the user enrols a device which is already present, the device will be re-enrolled.
2.2.3.3 DEVICE ENROLMENT IN BULK
One of the mechanisms by which new Roadside Devices are enrolled onto the RMAS is an enrolment using a device enrolment CSV file. To upload a device enrolment CSV file login to RMAS and navigate to the Devices menu and click on Add devices in bulk button:
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 23 of 54
Figure 15 Upload Device Enrolment CSV page
RMAS will process this file and complete device enrolment process, which includes checking NRTS data and getting static data. The CSV file containing devices should contain these columns so that RMAS can parse the file correctly:
• IP_Address (1st column) *
• RCC (2nd column) *
• Enrolment_Date (3rd column)
• Bandwidth_Limit (4th column)
• Maintenance_Region (5th column) * mandatory The RCC must be an exact match for a valid RCC, this is case sensitive. The value of the enrolment date, or today’s date if left blank, will be used for new devices, for existing devices the enrolment date will remain unchanged. Note the enrolment date must be in ISO 8601 format: YYYY-MM-DD This is an example of the Device Enrolment CSV file:
Figure 16 Device Enrolment CSV example
To ensure that a file to be uploaded is in the correct format, a template file containing example data can be downloaded using the ‘download template file’ link on the Upload Device Enrolment CSV page.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 24 of 54
2.2.3.4 DEVICE ENROLMENT NOTIFICATION
Once the devices complete the entire enrolment process, an email will be sent during the night with the status of all the devices to the user who enrolled them. Connection characteristics According to a network national contract, each copper span is limited to 2 simultaneous connections from RMAS to roadside devices. Fibre spans are allowed a maximum of 40 connections overall, not limited per span. This may result in the user being unable to perform an operation on a device at a particular instant indicated by the message “Connection Limit Reached”.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 25 of 54
2.3 DEVICE DASHBOARD
RMAS Users with access to a list of devices can also see a graphical dashboard type view of the status of those devices.
Figure 17 Device Dashboard
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 26 of 54
2.4 DEVICE OPERATION
The “Device Operation” page is where a user performs the various device operations in RMAS. The page displays the following sections,
• Device Details
• Device History
• Device Operation Device Details display information relating to a device which includes device specification, device enrolled date, list of connected devices etc. After each activity is completed on a device, the device status is updated depending on whether the connection could be established.
Figure 18 Device Operation – Device Details
Device History is an expandable section that lists the following information,
• Enrolment history
• Reset history
• Firmware change history In order to view device history, click on the Device History text. The history panel expands to display the three above mentioned sections. Enrolment history section displays list of status and timestamp when the device is ENROLLED, REMOVED and in a PENDING state. Whenever the device is reset, the Reset history list is updated with a timestamp. The reset history list displays a maximum of 10 recent records. Firmware change history displays list of firmware update and downgrade timestamps for that device.
Figure 19 Device Operation – Device History
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 27 of 54
Device Operations is further divided into following subsections based on the nature of the operation,
• Firmware
• Access
• State
• Logs The above mentioned operations can be performed on the selected device, however, if the device status is “PENDING” (on the device list), the device can only be removed and no other operation can be performed on the device.If the device status is “FAULTY”, firmware operation can’t be performed on the device. The device operations involving firmware upgrade and downgrade, resetting or removing a device, updates the Device history section based on the action performed on the device.
Figure 20 Device Operation – Device Operations
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 28 of 54
2.4.1 RESET DEVICE
This feature enables an RMAS user to reset a device. Click on the “Reset Device” button. This opens a pop up where the user must confirm that wants to reset the device. The device can then be reset by clicking on the “Accept” button. This will show the status of the reset device operation. Reset history list is updated after a successful reset.
Figure 21 Reset Device
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 29 of 54
2.4.2 DOWNLOAD LOGS
This feature enables a user to download log files from a roadside device for a given period. The logs are stored in a ZIP archive.
To perform the operation, click on the “Download logs” button on the “Device Operations” page. This will open a window with a date range picker. The default values for “Start Date” and “End Date” will be set to today’s date. The date picker ensures the range is always valid, for example if “Start Date” is selected after “End Date”, “Start Date will be set to “End Date”. The user will not be able to select a “Start Date” before the device enrolment date or RMAS start-up date if there was no device enrolment date. Once the download is complete a pop up message will display a “Download” link to the archive containing the log files.
Figure 22 Download Logs
The links to the log archives also can be found in the Activity History. These links are available for 7 days.
2.4.3 SCHEDULE LOGS DOWNLOAD
Users will be able to schedule a logs download every night for 7 consecutive days. The downloads will commence from the following night when the device was marked, once the log is complete. In order to perform this activity, users only need to have the permission required to download logs and click on the button that is on Device Operation page. See Figure 18. After marking the device, users can navigate into said device and see the log downloads expiry date in the device details panel. See Figure 20. Additionally, this expiry date can be updated at any moment to schedule another 7 days.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 30 of 54
2.4.4 REMOVE OLD SSH PUBLIC KEYS
This feature enables a user to remove any SSH public keys other than the one that was used to establish secure connectivity between RMAS and the roadside device. To remove SSH keys, the user has to click on the “Remove old keys” button on the “Device Operation” page. This opens a pop up as shown below which shows the status of the operation.
Figure 23 Remove Old Public SSH Keys
2.4.5 VERIFYING FIRMWARE
This feature enables an RMAS user to verify firmware on a device. To verify firmware on the device, the user has to click on the “Verify firmware” button. This opens a pop up window, which will show the status of the operation.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 31 of 54
Figure 24 Verify Firmware
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 32 of 54
2.4.6 UPGRADING FIRMWARE
This feature enables an RMAS user to upgrade the firmware on a device using firmware already uploaded from RMAS to device (see section 2.4.8). To be able to upgrade firmware, it is mandatory for the user’s account to have been set up with 2FA. If not, then the user will be redirected to set up 2FA immediately after successfully logging into the RMAS system. To upgrade the firmware on the device, the user has to click on the “Upgrade firmware” button. This opens a pop up as shown below. It is mandatory for the user to enter a PEW number and confirm that the PEW number and the contact details of the user are accurate and up to date. It is only after these steps, that the user is able proceed with the operation of upgrading the firmware on the device by clicking on the “Upgrade firmware” button. This will show the status of the upgrade operation. Once the firmware is upgraded, the Device history section is updated displaying the timestamp information of the firmware upgrade for that device under the Firmware change section.
Figure 25 Upgrade Firmware
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 33 of 54
2.4.7 REMOVING A DEVICE FROM RMAS
By clicking on the “Remove Device” button on the “Device Operation” page a user can remove the device from RMAS system. A confirmation pop up “Device Removal Form” is displayed as below. Clicking the “Submit” button will remove the device. No operation can be performed on a device that has been removed. If a device is already in use, then the user is not allowed to remove it. A removed device can be recovered by re-enrolling the device using the “Device Enrolment Form” using the same IP address. Once the device is recovered, the pre-existing Enrolment history is updated with the status and timestamp when the device was removed from the system in addition to the status and timestamp at which the device was re-enrolled to RMAS.
Figure 26 Device Removal Form
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 34 of 54
2.4.8 UPLOAD FIRMWARE FROM FIRMWARE STORE TO ROADSIDE DEVICE
The user can initiate the process by clicking on the “Upload Firmware” button on the “Device Operation” page. The firmware store displays a list of all available approved firmware that matches the ‘Manufacturer Code’ and ‘Device Type’ of the device. . Click on a firmware to upload.
Figure 27 List of Approved Firmware in the Firmware Store
The version of the firmware is checked and a warning is displayed if the hardware version do not match the device (if the upload is part of a bulk operation the warning is shown if the firmware does not match any of the selected devices). It is mandatory for the user to enter a PEW number and confirm that the PEW number and the contact details are accurate and up to date. If the user clicks “Accept” the firmware is then uploaded to the device and it subsequently be “Activated” on the device to become operational. The RMAS system will verify the firmware and inform the user and a confirmation email will be sent.
Figure 28 Upload Firmware Confirmation
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 35 of 54
2.4.9 DEVICE DATA REFRESH
This operation updates the system to reflect the current data on the roadside device. When the RMAS system can establish a connection with an enrolled device and obtain the static data, the RMAS system will set the device status to “OK”. And once the device is enrolled static data is obtained every night to keep the system updated with device status.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 36 of 54
2.4.10 DOWNGRADE FIRMWARE
This feature enables an RMAS user to downgrade the firmware on a device. To be able to downgrade firmware, it is mandatory for the user’s account to have been set up with 2FA. If not, then the user will be redirected to set up 2FA immediately after successfully logging into the RMAS system. To downgrade firmware on a device, the user should click on “Downgrade firmware” button on “Device Operation” page. This opens a pop up and the user must enter a PEW number and confirm that the PEW number and the contact details are accurate and up to date. It is only after these steps, that the user can proceed with the operation of downgrading the firmware on the device by clicking on the “Downgrade firmware” button. This opens a pop up, which will show the status of the operation. Once successful, the Firmware change list under Device history is updated with the firmware downgrade timestamp.
Figure 29 Downgrade Firmware
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 37 of 54
2.4.11 CONSOLE
By default, the Console access is disabled on all RMAS user accounts. To enable it, please contact the RMAS Service Desk. The console access is granted only for a limited period of time. To be able to have full console access, it is mandatory for the user’s account to have been set up with 2FA. If not, then the user will be redirected to set up 2FA immediately after successfully logging into the RMAS system. It is also required to have sufficient screen resolution to view console access, therefore on some smaller devices a message may be displayed advising that console access is not supported. The user will require a PEW number to perform this operation. The user can have full console access to the roadside device by using the “Console” button on the “Device Operation” page. From the console page users can perform specific RMAS console operations as allowed by the device manufacturer. The user can choose to close the session and return to the “Device Operation” page by clicking on the “Close and Exit session”. If the console is not properly closed, then the device remains in use until the server session expires.
Figure 30 Console Operation PEW number dialog
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 38 of 54
Figure 31 Console Access
2.4.12 EMENU
To be able to have menu based terminal access, it is mandatory for the user’s account to have been set up with 2FA. If not, then the user will be redirected to set up 2FA immediately after successfully logging into the RMAS system. The user will require a PEW number to perform this operation. The user can have the menu based terminal access to the device by using the “Emenu” button on the “Device Operation” page. All the emenu options made available by the device can be used from this page. The user can choose to close the session and return to the “Device Operation” page by clicking on the “Close and Exit session”. If the emenu is not closed properly, then the device remains in use until the server session expires.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 39 of 54
Figure 32 E-Menu PEW number dialog
Figure 33 E-Menu Access
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 40 of 54
2.4.13 WEB INTERFACE
The user can have the web interface access to the device (if device provides one) by using the “Web interface” button on the “Device Operation” page. The user is required to have 2FA enabled to perform this operation. If the operation to be performed is a non-service affecting operation, then click the “non-service affecting operation” checkbox shown in Figure 32. Or if the operation is a service affecting operation, enter the appropriate PEW number and confirm that the PEW number and the contact details are accurate and up to date. Once the user provides this information and clicks on “Open web interface” button, the web interface of the selected device is opened in another tab.
Figure 34 Web Interface Access PEW number dialog
The web interface session can be closed by clicking on the “End web interface session” button shown on the first tab. See Figure 35 End Web Interface Session. If the web interface is not closed properly then the device remains in use until the server session expires.
If the device that the user is connecting to does not have the web interface service, a message informing the user about it is displayed.
Figure 35 End Web Interface Session
2.5 BULK FIRMWARE OPERATIONS
Bulk firmware operations are available to users with the appropriate permissions and are performed from the “Device List” page (Figure 13 Device List). Above the list of devices table, there is a “Bulk Operation” button that will ask the user to confirm that a bulk operation is required before going to the bulk operation menu.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 41 of 54
Figure 36 Bulk Operation Confirmation
Note that bulk operations are limited to a maximum of 100 devices, if the list of devices is larger than this, a warning is displayed so that the filter can be refined to reduce the size of the list. The “Bulk Operation” page shows the filter that was used to select the devices for the operation, buttons are presented to execute the available operations. The corresponding user manual sections explain these operations.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 42 of 54
Figure 37 Bulk Operation Details
When the bulk operation is started the bulk operation progress screen is displayed with a link to view the bulk activity details for the operation
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 43 of 54
Figure 38 Bulk Operation Progress
The “Bulk Activity Details” page is like the Activity History page (Figure 11 Activity History) and shows the status of each device operation included in a bulk operation. Each row in the table can be clicked on to show the Activity Details for the device operation.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 44 of 54
Figure 39 Bulk Activity Details
This page can also be obtained from the Activity History page for the user. In this case the phrase ‘Bulk operation’ is shown in place of the Device IP and the Status is blank. Clicking on this row navigates to the “Bulk Activity Details” page.
2.6 DEVICE FIRMWARE MANAGEMENT
2.6.1 UPLOADING FIRMWARE TO FIRMWARE STORE ON RMAS
The user can add a new version of Roadside Device Firmware using the “Upload Firmware to Firmware Store” option under the “Firmware Store” menu. The user will be prompted for information about the firmware, any supporting documentation and the firmware files.
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 45 of 54
Figure 40 Upload Firmware to Firmware Store
The user is presented with the following fields,
• Roadside device type(s)
• Hardware revision
• New firmware version number
• Manufacturer code
• HE approver
• Roadside device supplier contact details
• New firmware file(s)
• Documentation file(s)
• Checksum file The "Roadside device type(s)" is a multiselect drop-down list. The Manufacturer code will be presented to the user as a text field or a drop-down list based on the User Group of the user.
The system differentiates between firmware based on the ‘Roadside device type’, ‘Hardware revision’, ‘Manufacturer code’ and ‘New firmware version number’. If there is already firmware with the same values as those being entered the system will show a message saying “The firmware already exists”.
In addition to this the user will be able to upload a checksum file. The selected method to check the data integrity is the Secure Hash Algorithm 256 – SHA256. The checksum file should be in plain text in the following format:
• Each line in the file must have a SHA256 hash followed by the name of the firmware file
• The hash and the filename should be separated by a single space
• There should be one line for each firmware file included in the upload
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 46 of 54
For example: 595f44fec1e92a71d3e9e77456ba80d1 firmwareFileA.iso 71f920fa275127a7b60fa4d4d41432a3 firmwareFileB.iso 43c191bf6d6c3f263a8cd0efd4a058ab firmwareFileC.iso Once the new firmware has been submitted, an email will be sent to the HE approver informing them that new Firmware has been uploaded and is pending approval. Once it is approved by the HE approver, such firmware is subsequently available for uploading to roadside devices.
2.7 SSH KEY
2.7.1 VIEW CURRENT PUBLIC KEY
The SSH Key page will display the current public key that has been used to secure communications between RMAS and roadside devices.
Figure 41 View Public SSH Key
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 47 of 54
3.0 API REFERENCE
RMAS provides a REST API which can be accessed to perform certain operations. To perform a REST request an API token is required.
3.1 API TOKENS MANAGEMENT
3.1.1 VIEWING API TOKENS
To see the tokens, navigate to the user menu and select API Tokens.
Figure 42 API Tokens
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 48 of 54
To see a token’s details, click on the token:
Figure 43 API Token Details
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 49 of 54
3.1.2 ADDING OR REMOVING API TOKENS
To create a new API token, navigate to the API Tokens page and click on the Add API token button:
Figure 44 Adding API token
Then enter a description and click on the Save button. To remove a token, navigate to the API Token Details page and click on the Delete button.
3.2 DEVICE OPERATION
Every device operation requires a request to start it, which will return an activity id. This activity id may be used in a second request to check the operation result.
3.2.1 REFRESH RMAS DEVICE DATA
• Request URL: https://he-rmas.org.uk/rmas-core/activity/staticData
• Request Method: POST
• Headers: o ipAddress: The IP address of the device from which RMAS would download the
static data o Authorization: Keyword Bearer, followed by a space and an API token
• Body: Empty
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 50 of 54
• Response: o activityId: The Id used to check the result of the operation
3.2.2 REFRESH RMAS DEVICE DATA EXAMPLE
• Request URL: https://he-rmas.org.uk/rmas-core/activity/staticData
• Request Method: POST
• Headers: o ipAddress: 10.163.49.68 o Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f
• Body: Empty
curl --header "ipAddress: 10.163.49.68" --header "Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f" --data "" -i https://he-rmas.org.uk/rmas-core/activity/staticData {"activityId":"e7301523-790a-4807-8707-37b3a1fbb099"}
3.2.3 DOWNLOAD LOGS INTO RMAS
• Request URL: https://he-rmas.org.uk/rmas-core/activity/downloadLogs
• Request Method: POST
• Headers: o ipAddress: The IP address of the device from which RMAS would download logs o Authorization: Keyword Bearer, followed by a space and an API token o Content-Type: application/json
• Body: o startDate: First date, in format YYYY-MM-DD, of the date range from which to
download the logs o endDate: Last date, in format YYYY-MM-DD, of the date range from which to
download the logs
• Response: o activityId: The Id used to check the result of the operation and to get the Zip file
with all the available device logs
3.2.4 DOWNLOAD LOGS INTO RMAS EXAMPLE
• Request URL: https://he-rmas.org.uk/rmas-core/activity/downloadLogs
• Request Method: POST
• Headers: o ipAddress: 10.163.49.68 o Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f o Content-Type: application/json
• Body: o startDate: 2017-12-19 o endDate: 2018-01-19
• Response: o activityId: The Id used to check the result of the operation and to get the Zip file
with all the available device logs
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 51 of 54
curl --header "ipAddress: 10.163.49.68" --header "Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f" --header "Content-Type: application/json" --data "{\"startDate\": \"2017-12-19\", \"endDate\": \"2018-01-19\"}" -i https://he-rmas.org.uk/rmas-core/activity/downloadLogs {"activityId":"02196e19-8ef1-4697-bc37-bc43b30ae3bd"}
3.3 RMAS OPERATION
These requests retrieve data related to devices from RMAS but they do not perform any actions directly on the devices.
3.3.1 CHECK OPERATION RESULTS
• Request URL: https://he-rmas.org.uk/rmas-core/activityResult/{activityId} o activityId: Id from the response when refreshing RMAS device data or
downloading logs into RMAS
• Request Method: GET
• Headers: o Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f
• Body: Empty
• Response: o activityId: Id from the request o status: Status of the operation, which can be:
▪ PENDING: The operation is still running, please try again later ▪ SUCCESS: All files were downloaded into RMAS. ▪ FAILURE: There was a problem running the operation ▪ ABORTED: The operation was cancelled ▪ UPDATED: Only present when refreshing device data. The static data was
downloaded and has changed since the last check ▪ PARTIAL_SUCCESS: Only present when downloading logs. Some of the
logs were downloaded and some failed.
• errorMessages: Explains why the operation failed or was aborted
• result: empty
• command: Name of the command. staticData or downloadLogs
• deviceId: IP Address where the command ran
• startDate: Timestamp from when the operation started
• endDate: Timestamp from when the operation finished
• userId: Id of the user that started the operation
3.3.2 CHECK OPERATION RESULTS EXAMPLE
• Request URL: https://he-rmas.org.uk/rmas-core/activityResult/02196e19-8ef1-4697-bc37-bc43b30ae3bd
• Request Method: GET
• Headers: o Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f
• Body: Empty
curl --header "Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f" -i https://he-rmas.org.uk/rmas-core/activityResult/02196e19-8ef1-4697-bc37-bc43b30ae3bd {"activityId":"02196e19-8ef1-4697-bc37-bc43b30ae3bd ",
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 52 of 54
"status":"PARTIAL_SUCCESS", "errorMessages":["Failed to download one or more files"], "result":"", "command":"downloadLogs", "deviceId":"10.163.49.68", "startDate":"2018-01-19T09:23:37.158Z", "endDate":"2018-01-19T09:25:25.913Z", "userId":"5172c56d68881249fbf88259"}
3.3.3 GET DEVICE DATA
• Request URL: https://he-rmas.org.uk/rmas-core/devices/{ipAddress} o ipAddress: The IP address of the device from which to get the device data
• Request Method: GET
• Headers: o Authorization: Key word Bearer, followed by a space and an API token
• Body: Empty
• Response: All device data stored in RMAS
3.3.4 GET DEVICE DATA EXAMPLE
• Request URL: https://he-rmas.org.uk/rmas-core/devices/10.163.49.68
• Request Method: GET
• Headers: o Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f
• Body: Empty
• Response: All device data stored in RMAS
curl --header "Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f" -i https://he-rmas.org.uk/rmas-core/devices/10.163.49.68 {"ipAddress" : "10.163.49.68", "maintenanceContractRegion" : "South West", "rccRegion" : "South West", "manufacturer" : "SSL", "enrolmentDate" : "2016-03-23T00:00:00Z", "bandwidthLimit" : 256, "manufacturerType" : "typ123", "serialNumber" : "ser123", "hardwareVersion" : "har123", "firmwareVersion" : "fir123", "hostname" : "M1-4567A1.ami.ha.org", "manufacturerSpecificData" : "---", "haGeographicAddress" : "M1-4567A1", "latitude" : 53.050274, "longitude" : -2.191667, "deviceList" : { "ami" : [ "signal450enforcement" ] },
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 53 of 54
"status" : "OK", "spanType" : "COPPER", "spanName" : "8RMD-M18/7525B-01", …}
3.3.5 GET DOWNLOADED LOGS
• Request URL: https://he-rmas.org.uk/rmas-core/activity/{activityId}/logArchive o activityId: Id from the response when downloading logs into RMAS
• Request Method: GET
• Headers: o Authorization: Key word Bearer, followed by a space and an API token
• Body: Empty
• Response: Zip file with all the available device logs
3.3.6 GET DOWNLOADED LOGS EXAMPLE
• Request URL: https://he-rmas.org.uk/rmas-core/activity/02196e19-8ef1-4697-bc37-bc43b30ae3bd/logArchive
• Request Method: GET
• Headers: o Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f
• Body: Empty
• Response: Zip file with all the available device logs curl --header "Authorization: Bearer fa3ac4a4-bfd4-4339-b69d-6694185b183f" https://he-rmas.org.uk/rmas-core/activity/02196e19-8ef1-4697-bc37-bc43b30ae3bd/logArchive --output logs.zip
_________________________________________________________________________________
TEC4362/J/23.10.2019 < UNRESTRICTED > Page 54 of 54
END OF DOCUMENT