Summary
The custom GUI functionality allows the user to design and embed a unique GUI (a user interface that can be used in a web browser) for configuring router settings. The router has an interface for transferring the settings from the host via HTTP; and the user can create a GUI using JavaScript.
Yamaha Routers have an on board web browser configuration support functionality, however, it used to be impossible to change settings screens for individual users. Using this functionality, multiple custom GUIs can be embedded and switched according to the logged in user so that the screen can be switched for each logged in user.
In this document, first we will describe GUI data save locations, then we will explain of configuration methods for saved multiple data items to be switched for individual logged in users. In addition, we will explain specific custom GUI creation methods, and finally give a listing of commands that can be used with this functionality.
Compatible Models and Firmware Revisions
Yamaha network products support the custom GUI in the following models and firmwares.
Model | Firmware |
---|---|
FWX120 | From initial release |
RTX810 | From initial release |
Details
GUI Data Save Locations
In this functionality, built-in flash ROM (RTFS) or external memory can be used as the save location for created GUI data (such as HTML files). With the httpd custom-gui user command, when configuring a directory to serve as the home directory for the individual user, input the absolute path or a relative path using the PWD environmental variable. F0r specific methods of configuring absolute paths and relative paths, refer to RTFS External Spec.
GUI Switch by Logged in User
When the Top Page of the router is accessed by a web browser, a Basic authentication dialog is displayed. It is possible to change the GUI that is output to the browser according to the user name entered here. In the following, we will give a specific example of the method of configuring the router and explain the operations in doing so.
Configuration Summary
Register four names, user1, user2, and user3, and nameless user as users to use the custom GUI, and configure a directory to serve as the home directory for each user as per the following table.
User name | Media | Directory that serves as home directory |
---|---|---|
user1 | Built-in flash ROM (RTFS) | /gui/user1 |
user2 | Built-in flash ROM (RTFS) | /gui/user2 |
user3 | USB flash drives | usb1:/gui/user3 |
nameless user | Built-in flash ROM (RTFS) | /gui/anonymous |
Router Settings
First, register the logged in user with the “login user” command. Nameless user need not be registered.
Next, configure data for the GUI used by each user with the httpd custom-gui user command.
As the “user1” user uses “/gui/user1” in the built-in flash ROM (RTFS), set the directory to “/gui/user1.” For “index,” specify the file name to be displayed when accessing with a URL ending in a "/ (slash)." Designate default.html in this example.
Set likewise for “user2” user.
Omit the user name for nameless user.
The following is an example of configuring a relative path for a directory using the set command.
“user3” user uses data on a USB stick, so configure it as follows.
In addition to the above, you must use the following settings.
- Enable the HTTP server functionality with the “httpd service” command.
- Permit host to router access with the “httpd host” command.
- Include “HTTP” in the “connection” attributes for each user with the “user attribute” command.
- When operations that require administrator permissions are conducted via CUI command from the custom GUI, the administrator attribute for the individual user is “on.”
- httpd custom-gui use command is “on.”
Operation
We will explain the operations for accessing the Top Page of the router at IP address 192.168.100.1 (http://192.168.100.1/) and login by each username.
When user1 logs in at the authentication dialog on the Top Page, browser is redirected to “http://192.168.100.1/custom/user1/” and “/gui/user1/default.html” is output.
When accessing another URL under “/custom/user1,” a file is referenced using “/gui/user1” as the home directory. Here is an example:
URL | Referenced file path |
---|---|
http://192.168.100.1/custom/user1/nat/ | /gui/user1/nat/default.html |
http://192.168.100.1/custom/user1/tunnel/template.html | /gui/user1/tunnel/template.html |
The same applies to the users ”user2” and ”user3”. The URL for "nameless user” is “http://192.168.100.1/custom/anonymous.user/”.
Users configured with the httpd custom-gui user command cannot access the ordinary GUI embedded in the router. Even if the URL is entered directly and the ordinary GUI is accessed, the browser will not be redirected to the custom GUI and there will be an authentication error.
Logged in User Permissions
For the custom GUI to be displayed for the individual user, the user must login with general permissions (user name + login password). This cannot be displayed with administrator permissions (user name + administrator password).
To perform an operation from the custom GUI with a CUI command that requires administrator permissions, you must login with administrator permissions after logging in with general permissions. We will explain the details in Settings Transfer from Host to Router .
GUI Creation Method
We will explain the method of creating a GUI for configuring a router. You need a basic knowledge of HTTP Protocol, HTML, and JavaScript.
Settings Transfer from Host to Router
Transfer settings from a host such as PC to the router by requesting a POST method via “/custom/execute.” We will describe the settings content in the POST method content part. As for the data format, the router commands used in CUI are separated individually with linefeed code. The linefeed code is CRLF.
The following shows an example of transmitting a request to the router from Internet Explorer 8.
Line 1 of the content part is the Session ID. The router provides this value upon GUI data acquisition, and for security reasons (CSRF measures), the value must be written at the head of the content part. If this value does not exist, or if it does not match the value stored in the router, the settings will not be applied, and the server will return “506 CGI Permission Denied”. We will explain the method for acquiring this value in GUI Sample.
When a request is transmitted that includes a command that requires administrator permissions, the command will not be executed and an authentication dialog will be displayed. At this point, you must login again with administrator permissions.
Execution results acquisition
The router transmits the command execution results as a POST request reply. The content is identical to the message output when the command is input from the CUI. For example, if you execute “show config,” a listing of configuration commands is displayed. If you mistakenly input a command, an error message will be displayed.
You can select ON/OFF for echo back when execution results are acquired. When echo back is “ON,” both the input command and the execution results will be output. When echo back is “OFF”, only the execution results will be output. With echo back is “OFF”, when there is no content to be displayed as execution results, nothing will be displayed.
echo back is set to “OFF” in the default settings To set it to “ON,” write “#echoback=on” in the second line of the POST request content part (next line after Session ID).
Replies to a request transmitted as an example in Transferring settings from host to router are displayed below for respective cases of echo back “ON/OFF.”
When echo back is “ON”
Input command and output content are all transferred.
When echo back is “OFF”
Only “show config” output content is transferred.
Logout
The Yamaha Router’s HTTP server is set so that multiple users cannot log in from the same IP address at the same time. Thus, after a user has logged in, for another user to log in from the same host, that user must wait until the login timer is finished or for logout to be processed.
To perform the logout process at the custom GUI, transmit a POST request with “session ID” written in the first line of the content part and “#logout” in the second line to “/custom/execute”. If you have logged out properly, the server will return “200 OK”.
Be careful to exit the browser immediately after logout processing. If you continue on by accessing another page, login processing will reoccur.
Commands that cannot be executed from a custom GUI
The following commands cannot be executed from a custom GUI
- administrator
- administrator password
- administrator password encrypted
- copy
- copy config
- copy exec
- delete
- execute batch
- exit
- commands with “grep” concatenated with '|’
- commands with “less” concatenated with '|’
- commands starting with “less”
- login password
- login password encrypted
- make directory
- password reenter
- ping
- ping6
- quit
- remote setup
- rename
- rtfs format
- rtfs garbage collect
- scp
- show techinfo
- ssh
- sshd host key generate
- telnet
- traceroute
- traceroute6
Statistical Info Graph
Assuming use of the CUI command, and with a custom GUI, configuration and referencing status are enabled for almost all router functionalities. However, for statistical information, data cannot be acquired with the CUI command, so you must either display a graph from the “Statistical Data” page of the WWW Browser Settings Support Function or export the data to external memory.
Due to such circumstances, we have prepared a dedicated statistical information page designed for incorporation into a custom GUI using such as inline frames.h You can display multiple graphs at one time with the “Statistical Information” page of the WWW Browser Settings Support Function, but for a Statistical Information Page dedicated to a custom GUI, you can acquire only specific graphs by specifying URL parameters.
The URL specification method is as described below.
Designate the graph type with the “type” parameter The settings values and meanings are as follows.
settings value | Meaning |
---|---|
cpu | CPU use rate |
memory | memory use rate |
flow | fastpath flow number |
route | route number |
nat | NAT entry number |
filter | policy filter or dynamic filter session number |
traffic | traffic statistics |
qos | QoS statistics |
Configure the data acquisition interval with the “span” parameter. The maximum amount of data you can acquire is fixed, so by specifying an interval, you also determine the acquisition period. The settings values and meanings are as follows.
settings value | Meaning |
---|---|
1s | 1 second intervals, for past 2 minutes |
1m | 1 minute intervals, for past 2 hours |
12m | 12 minute intervals, for past 1 day |
6h | 6 hour intervals, for past 30 days |
Specify the names of interfaces such as “lan1,” “pp1,” or “tunnel1” with the “if” parameter.
Specify the “QoS” class with the “class” parameter.
Regarding each of the “span,” “if,” and “class” parameters, the things that must be specified will differ depending on the “type” parameter settings value. The correspondence relationship is as follows.
Settings value of the “type” parameter | The necessary parameters |
---|---|
cpu, memory, flow, route, filter | span |
nat, traffic | span, if |
qos | if, class |
When “type” is QoS statistics, the acquisition period is fixed at 10 second intervals over the past 20 minute period.
Communications sequence
The sequence from accessing the router Top Page and transferring settings, and acquiring execution results is as follows.
GUI Samples
We will introduce samples of custom GUIs. For detailed information on such as JavaScript and HTML, refer to such as reference books and explanatory sites.
- Use the JavaScript XMLHttpRequest object to transmit POST requests with router setting commands written in the content part. Execution results transmitted from the router are set with the “responseText” property.
- To acquire a Session ID, import “/custom/custom_gui_lib.js” as an external file, and call the “getSessionId()” method. The value returned by this method is the Session ID.
Sample files are here. In this scenario, the branch side router connects to the Internet by PPPoE, and connects to the center side router by IPsec tunneling.
The configuration API is used by HTTP clients other than browsers.
To POST settings to /custom/execute (REST API), a Session ID has to be added as a CSRF measure. When attempting to configure the router from a simple HTTP client created with languages such as Perl and Ruby, you need to have a JavaScript engine embedded to acquire the Session ID, and this is not easy.
With this function, so that you can perform configuration from an HTTP client other than a www browser, we have separately prepared the REST API, which does not need a Session ID to be added. The URL is a /custom/api.
To use this API, you need the following settings.
- The httpd custom-gui api use command must be “on”.
- You must set the password with the httpd custom-gui api password command.
When there is a POST by a HTTP client of a router configuration command involving /custom/api, the password set with the httpd custom-gui api password is specified as a URL parameter.
For example, if the password is “doremi,” the URL will be as follows.
http://(router IP address)/custom/api?password=doremi
To access this URL, “Basic” authentication is not necessary. Additionally, as stated earlier, a Session ID is not necessary, and no CSRF measures are performed, so you should not access this from the browser.
And, to set Echo Back to “on” for requests to /custom/api, “#echoback=on” is written in the first line of the content part.
On Japanese language
Multi-byte characters via POST are set for processing as UTF-8.
As for a POST of a /custom/api command that includes a multi-byte language such as Japanese (such as the “description” command), set the client side character code to Shift_JIS.
In external memory file operations, file names and directories can be specified to include Japanese Commands, but with this functionality URLs that contain Japanese do not work properly.
Command
Set Environment Variables
[Syntax]
[Setting and Initial value]
- NAME
- [Setting] : Environment variable name
- [Initial value] : -
- VALUE
- [Setting] : Setting
- [Initial value] : -
[Description]
Sets the routers environment variables.
The environment variable naming rules are listed below.
- Alphanumeric characters and underscores can be used, but names cannot start with underscores or numbers.
- There is no variable name length limit, but the set command cannot be executed if it exceeds the maximum command line length (4095 characters).
- Names are case-sensitive. For example, "abc" and "Abc" are treated as different variables.
[Note]
Set the path parameter to the absolute directory of the starting path or to a relative path. If you set to a relative path, it is interpreted as a path starting with the PWD environment variable. You can change PWD with the set command. Its initial value is "/".
[Models]
RTX810 | RTX5000 | FWX120 |
Set Whether to Use the Custom GUI
[Syntax]
[Setting and Initial value]
- USE
- [Setting] :
Setting Description on Enable off Disable - [Initial value] : off
- [Setting] :
[Description]
Sets whether to use the custom GUI.
[Models]
RTX810 | FWX120 |
Configure Custom GUI User Settings
[Syntax]
[Setting and Initial value]
- USER
- [Setting] : User name
- [Initial value] : -
- PATH
- [Setting] : The absolute or relative path of the starting directory
- [Initial value] : -
- NAME
- [Setting] : The file that appears when the user accesses the GUI through a URL that ends with a slash
- [Initial value] : index.html
[Description]
Configures custom GUI user settings. When you access http://(the IP address of the router)/ and login with a user name specified by this command, you will be redirected to http://(the IP address of the router)/custom/user/.
If you omit the user parameter, the settings for an anonymous user are configured. The URL in this case is http://(the IP address of the router)/custom/anonymous.user/.
PATH must be specified absolute path to the directory. Or must be specified relative path with set command. Set the name parameter to the file name that you want to display when the user accesses the GUI through a URL that ends with a slash.
[Note]
Before you configure the settings for any user other than an anonymous user with this command, you must first register the user with login user user command. An error will occur if you execute this command using the name of an unregistered user.
Auto serching function on the external memory cannot be supported. NAME cannot be specified with the string including ‘/’.
The users whose settings are configured by this command cannot access the normal internal router GUI.
[Models]
RTX810 | FWX120 |
Set Whether to Use the Custom GUI API
[Syntax]
[Setting and Initial value]
- USE
- [Setting] :
Setting Description on Enable off Disable - [Initial value] : off
- [Setting] :
[Description]
Sets whether to accept POST requests to the API URL, which is "http://(the IP address of the router)/custom/api".
[Note]
To use the API URL, in addition to setting this command, you must also execute the httpd custom-gui use on command.
Even when setting this command on, you cannot use the URL for the API without specifying the httpd custom-gui api password command.
[Models]
RTX810 | FWX120 |
Set the Password for Accessing the Custom GUI API
[Syntax]
[Setting and Initial value]
- PASSWORD
- [Setting] : Password
- [Initial value] : -
[Description]
Sets the password that is used when POST requests are sent to the API URL. The password can be set using up to 32 alphanumeric characters.
For example, if you use this command to set the password to doremi, the URL will be http://(the IP address of the router)/custom/api?password=doremi.
[Models]
RTX810 | FWX120 |
SYSLOG Message List
Level | Output message | Meaning |
---|---|---|
INFO | Login succeeded for HTTP: IP_ADDR USER_NAME | User USER_NAME whose IP address is IP_ADDR logged into the HTTP server of the router. |
'administrator' succeeded for HTTP: IP_ADDR USER_NAME | User USER_NAME whose IP address is IP_ADDR is promoted to Administrator. | |
Logout from HTTP: IP_ADDR USER_NAME | User USER_NAME whose IP address is IP_ADDR logged out from the HTTP server. | |
DEBUG | [CUSTOM_GUI] Execute 'COMMAND' | Execute the “COMMAND” command with the custom GUI function. |