Remote Maintenance Access Service (RMAS) User Manual · password. Following the link in the email, the user is presented with the Reset Password page listing the HE password policy

____________________________________________________________________________

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

_________________________________________________________________________________


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


_________________________________________________________________________________


F

Print name Manuel Benitez Sanchez

Sabrina Rayfield Dave Collins 22/09/2017

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)

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


References:

[1] TR2597 Generic Roadside Device Requirements for Remote Access

_________________________________________________________________________________


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

_________________________________________________________________________________


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.

_________________________________________________________________________________


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

https://www.he-rmas.org.uk/

_________________________________________________________________________________


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

_________________________________________________________________________________


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”.


_________________________________________________________________________________


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

_________________________________________________________________________________


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.


_________________________________________________________________________________


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.

_________________________________________________________________________________


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

_________________________________________________________________________________


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.

_________________________________________________________________________________


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.

_________________________________________________________________________________


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

_________________________________________________________________________________


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.

_________________________________________________________________________________


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

_________________________________________________________________________________


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:

_________________________________________________________________________________


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.

https://www.iso.org/iso-8601-date-and-time-format.html

_________________________________________________________________________________


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”.

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


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.

_________________________________________________________________________________


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.

_________________________________________________________________________________


Figure 24 Verify Firmware

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


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.

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


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.

_________________________________________________________________________________


Figure 32 E-Menu PEW number dialog

Figure 33 E-Menu Access

_________________________________________________________________________________


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.

_________________________________________________________________________________


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.

_________________________________________________________________________________


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

_________________________________________________________________________________


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.

_________________________________________________________________________________


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.

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


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

_________________________________________________________________________________


To see a token’s details, click on the token:

Figure 43 API Token Details

_________________________________________________________________________________


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

_________________________________________________________________________________


• 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


• 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


• 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


• 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

_________________________________________________________________________________


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



• 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 ",

_________________________________________________________________________________


"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


• 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



• 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" ] },

_________________________________________________________________________________


"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


• 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



• 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

_________________________________________________________________________________


END OF DOCUMENT

Documents

Remote Maintenance Access Service (RMAS) User Manual · password. Following the link in the email, the user is presented with the Reset Password page listing the HE password policy