Custom GUI

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.

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.

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.

First, register the logged in user with the “login user” command. Nameless user need not be registered.

# login user user1 user1
# login user user2 user2
# login user user3 user3

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.

# httpd custom-gui user user1 directory=/gui/user1 index=default.html

Set likewise for “user2” user.

# httpd custom-gui user user2 directory=/gui/user2 index=default.html

Omit the user name for nameless user.

# httpd custom-gui directory=/gui/anonymous index=default.html

The following is an example of configuring a relative path for a directory using the set command.

# set PWD=/gui
# httpd custom-gui user user1 directory=user1 index=default.html
# httpd custom-gui user user2 directory=user2 index=default.html
# httpd custom-gui user directory=anonymous index=default.html

“user3” user uses data on a USB stick, so configure it as follows.

# httpd custom-gui user user3 directory=usb1:/gui/user3 index=default.html

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

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:

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.

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 .

We will explain the method of creating a GUI for configuring a router. You need a basic knowledge of HTTP Protocol, HTML, and JavaScript.

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.

POST /custom/execute HTTP/1.1
Accept: */*
Accept-Language: en
Referer: http://192.168.100.1/custom/anonymous.user/
Content-Type: text/plain
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.1; WOW64; Trident/4.0; SLCC2; .NET CLR 2.0.50727; .NET CLR 3.5.30729; .NET CLR 3.0.30729; Media Center PC 6.0; .NET4.0C; .NET4.0E; InfoPath.3)
Host: 192.168.100.1
Content-Length: 69
Connection: Keep-Alive
Cache-Control: no-cache
Authorization: Basic Og==

#2450035272
ip lan2 address 10.0.0.1/8
syslog debug on
show config

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.

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

Input command and output content are all transferred.

HTTP/1.0 200 OK
Date: Sun, 18 Oct 2009 21:40:42 GMT
Expires: Sun, 18 Oct 2009 21:40:42 GMT
Server: YAMAHA-RT
Allow: HEAD, GET, POST
Content-Type: text/plain;charset=us-ascii

# ip lan2 address 10.0.0.1/8
# syslog debug on
# show config
# RTX1200 Rev.10.01.16 (Tue Sep 29 15:44:22 2009)
# MAC Address : 00:a0:de:37:b5:04, 00:a0:de:37:b5:05, 00:a0:de:37:b5:06
# Memory 128Mbytes, 3LAN, 1BRI
# main:  RTX1200 ver=b0 serial=D26009558 MAC-Address=00:a0:de:37:b5:04 MAC-Address=00:a0:de:37:b5:05 MAC-Address=00:a0:de:37:b5:06
# Reporting Date: Oct 19 06:40:42 2009
login password *
administrator password *
login user user1 *
ip lan1 address 192.168.0.1/24
ip lan2 address 10.0.0.1/8
syslog debug on
httpd custom-gui user user1 directory=/gui/user1 index=default.html
#

Only “show config” output content is transferred.

HTTP/1.0 200 OK
Date: Sun, 18 Oct 2009 21:40:42 GMT
Expires: Sun, 18 Oct 2009 21:40:42 GMT
Server: YAMAHA-RT
Allow: HEAD, GET, POST
Content-Type: text/plain;charset=us-ascii

# RTX1200 Rev.10.01.16 (Tue Sep 29 15:44:22 2009)
# MAC Address : 00:a0:de:37:b5:04, 00:a0:de:37:b5:05, 00:a0:de:37:b5:06
# Memory 128Mbytes, 3LAN, 1BRI
# main:  RTX1200 ver=b0 serial=D26009558 MAC-Address=00:a0:de:37:b5:04 MAC-Address=00:a0:de:37:b5:05 MAC-Address=00:a0:de:37:b5:06
# Reporting Date: Oct 19 06:40:42 2009
login password *
administrator password *
login user user1 *
ip lan1 address 192.168.0.1/24
ip lan2 address 10.0.0.1/8
syslog debug on
httpd custom-gui user user1 directory=/gui/user1 index=default.html

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.

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

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.

http://(router IP address)/custom/stat_graph.html?type=type[&span=SPAN][&if=INTERFACE][&class=CLASS]

Designate the graph type with the “type” parameter The settings values and meanings are as follows.

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.

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.

When “type” is QoS statistics, the acquisition period is fixed at 10 second intervals over the past 20 minute period.

The sequence from accessing the router Top Page and transferring settings, and acquiring execution results is as follows.

+----------+                                          +----------+ 
|  host    |                                          | router   | 
+-----+----+                                          +-----+----+ 
      |                                                     |
      |    access  http://192.168.100.1/ and login          | 
      |---------------------------------------------------->|
      |                                                     | 
      |   Redirect to http://192.168.100.1/custom/user/     |
      |<----------------------------------------------------|
      |                                                     |
      |       POST settings to ustom/execute                | 
      |---------------------------------------------------->|
      |                                                     | 
      | Transmit Execution results                          |
      |<----------------------------------------------------|
      |                                                     |

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.

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.

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.

[Syntax]

set NAME=VALUE
no set NAME[=VALUE]

[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]

[Syntax]

httpd custom-gui use USE
no httpd custom-gui use [USE]

[Setting and Initial value]

• USE
  • [Setting] :

    Setting	Description
    on	Enable
    off	Disable

  • [Initial value] : off

[Description]

Sets whether to use the custom GUI.

[Models]

[Syntax]

httpd custom-gui user [USER] directory=PATH  [index=NAME]
no httpd custom-gui user [USER...]

[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]

[Syntax]

httpd custom-gui api use USE
no httpd custom-gui api use [USE]

[Setting and Initial value]

• USE
  • [Setting] :

    Setting	Description
    on	Enable
    off	Disable

  • [Initial value] : off

[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]

[Syntax]

httpd custom-gui api password PASSWORD
no httpd custom-gui api password [PASSWORD]

[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]