Manual:Customizing Hotspot

Applies to RouterOS: v3, v4, v5+

HTML customizations

Summary

You can create a completely different set of servlet pages for each HotSpot server you have, specifying the directory it will be stored in html-directory property of a HotSpot server profile /ip hotspot profile. The default servlet pages are copied in the directory of your choice right after you create the profile. This directory can be accessed by connecting to the router with an FTP client. You can modify the pages as you like using the information from this section of the manual. Note that it is suggested to edit the files manually, as automated HTML editing tools may corrupt the pages by removing variables or other vital parts.

Available Pages

Main HTML servlet pages, which are shown to user:

• redirect.html - redirects user to another url (for example, to login page)
• login.html - login page shown to a user to ask for username and password. This page may take the following parameters:
  • username - username
  • password - either plain-text password (in case of PAP authentication) or MD5 hash of chap-id variable, password and CHAP challenge (in case of CHAP authentication). This value is used as e-mail address for trial users
  • dst - original URL requested before the redirect. This will be opened on successfull login
  • popup - whether to pop-up a status window on successfull login
  • radius<id> - send the attribute identified with <id> in text string form to the RADIUS server (in case RADIUS authentication is used; lost otherwise)
  • radius<id>u - send the attribute identified with <id> in unsigned integer form to the RADIUS server (in case RADIUS authentication is used; lost otherwise)
  • radius<id>-<vnd-id> - send the attribute identified with <id> and vendor ID <vnd-id> in text string form to the RADIUS server (in case RADIUS authentication is used; lost otherwise)
  • radius<id>-<vnd-id>u - send the attribute identified with <id> and vendor ID <vnd-id> in unsigned integer form to the RADIUS server (in case RADIUS authentication is used; lost otherwise)
• md5.js - JavaScript for MD5 password hashing. Used together with http-chap login method
• alogin.html - page shown after client has logged in. It pops-up status page and redirects browser to originally requested page (before he/she was redirected to the HotSpot login page)
• status.html - status page, shows statistics for the client. It is also able to display advertisements automatically
• logout.html - logout page, shown after user is logged out. Shows final statistics about the finished session. This page may take the following additional parameters:
  • erase-cookie - whether to erase cookies from the HotSpot server on logout (makes impossible to log in with cookie next time from the same browser, might be useful in multiuser environments)
• error.html - error page, shown on fatal errors only

Some other pages are available as well, if more control is needed:

• rlogin.html - page, which redirects client from some other URL to the login page, if authorization of the client is required to access that URL
• rstatus.html - similarly to rlogin.html, only in case if the client is already logged in and the original URL is not known
• radvert.html - redirects client to the scheduled advertisement link
• flogin.html - shown instead of login.html, if some error has happened (invalid username or password, for example)
• fstatus.html - shown instead of redirect, if status page is requested, but client is not logged in
• flogout.html - shown instead of redirect, if logout page is requested, but client is not logged in

Serving Servlet Pages

The HotSpot servlet recognizes 5 different request types:

1. request for a remote host
   • if user is logged in and advertisement is due to be displayed, radvert.html is displayed. This page makes redirect to the scheduled advertisment page
   • if user is logged in and advertisement is not scheduled for this user, the requested page is served
   • if user is not logged in, but the destination host is allowed by walled garden, then the request is also served
   • if user is not logged in, and the destination host is disallowed by walled garden, rlogin.html is displayed; if rlogin.html is not found, redirect.html is used to redirect to the login page

2. request for "/" on the HotSpot host
   • if user is logged in, rstatus.html is displayed; if rstatus.html is not found, redirect.html is used to redirect to the status page
   • if user is not logged in, rlogin.html is displayed; if rlogin.html is not found, redirect.html is used to redirect to the login page

3. request for "/login" page
   • if user has successfully logged in (or is already logged in), alogin.html is displayed; if alogin.html is not found, redirect.html is used to redirect to the originally requested page or the status page (in case, original destination page was not given)
   • if user is not logged in (username was not supplied, no error message appeared), login.html is showed
   • if login procedure has failed (error message is supplied), flogin.html is displayed; if flogin.html is not found, login.html is used
   • in case of fatal errors, error.html is showed

4. request for "/status" page
   • if user is logged in, status.html is displayed
   • if user is not logged in, fstatus.html is displayed; if fstatus.html is not found, redirect.html is used to redirect to the login page

5. request for '/logout' page
   • if user is logged in, logout.html is displayed
   • if user is not logged in, flogout.html is displayed; if flogout.html is not found, redirect.html is used to redirect to the login page

Note: If it is not possible to meet a request using the pages stored on the router's FTP server, Error 404 is displayed

There are many possibilities to customize what the HotSpot authentication pages look like:

• The pages are easily modifiable. They are stored on the router's FTP server in the directory you choose for the respective HotSpot server profile.
• By changing the variables, which client sends to the HotSpot servlet, it is possible to reduce keyword count to one (username or password; for example, the client's MAC address may be used as the other value) or even to zero (License Agreement; some predefined values general for all users or client's MAC address may be used as username and password)
• Registration may occur on a different server (for example, on a server that is able to charge Credit Cards). Client's MAC address may be passed to it, so that this information need not be written in manually. After the registration, the server should change RADIUS database enabling client to log in for some amount of time.

To insert variable in some place in HTML file, the $(var_name) syntax is used, where the "var_name" is the name of the variable (without quotes). This construction may be used in any HotSpot HTML file accessed as '/', '/login', '/status' or '/logout', as well as any text or HTML (.txt, .htm or .html) file stored on the HotSpot server (with the exception of traffic counters, which are available in status page only, and error, error-orig, chap-id, chap-challenge and popup variables, which are available in login page only). For example, to show a link to the login page, following construction can be used:

<a href="$(link-login)">login</a>

Variables

All of the Servlet HTML pages use variables to show user specific values. Variable names appear only in the HTML source of the servlet pages - they are automatically replaced with the respective values by the HotSpot Servlet. For most variables there is an example of their possible value included in brackets. All the described variables are valid in all servlet pages, but some of them just might be empty at the time they are accesses (for example, there is no uptime before a user has logged in).

List of available variables

Common server variables:

• hostname - DNS name or IP address (if DNS name is not given) of the HotSpot Servlet ("hotspot.example.net")
• identity - RouterOS identity name ("MikroTik")
• login-by - authentication method used by user
• plain-passwd - a "yes/no" representation of whether HTTP-PAP login method is allowed ("no")
• server-address - HotSpot server address ("10.5.50.1:80")
• ssl-login - a "yes/no" representation of whether HTTPS method was used to access that servlet page ("no")
• server-name - HotSpot server name (set in the /ip hotspot menu, as the name property)

Links:

• link-login - link to login page including original URL requested ("http://10.5.50.1/login?dst=http://www.example.com/")
• link-login-only - link to login page, not including original URL requested ("http://10.5.50.1/login")
• link-logout - link to logout page ("http://10.5.50.1/logout")
• link-status - link to status page ("http://10.5.50.1/status")
• link-orig - original URL requested ("http://www.example.com/")

General client information:

• domain - domain name of the user ("example.com")
• interface-name - physical HotSpot interface name (in case of bridged interfaces, this will return the actual bridge port name)
• ip - IP address of the client ("10.5.50.2")
• logged-in - "yes" if the user is logged in, otherwise - "no" ("yes")
• mac - MAC address of the user ("01:23:45:67:89:AB")
• trial - a "yes/no" representation of whether the user has access to trial time. If users trial time has expired, the value is "no"
• username - the name of the user ("John")

User status information:

• idle-timeout - idle timeout ("20m" or "" if none)
• idle-timeout-secs - idle timeout in seconds ("88" or "0" if there is such timeout)
• limit-bytes-in - byte limit for send ("1000000" or "---" if there is no limit)
• limit-bytes-out - byte limit for receive ("1000000" or "---" if there is no limit)
• refresh-timeout - status page refresh timeout ("1m30s" or "" if none)
• refresh-timeout-secs - status page refresh timeout in seconds ("90s" or "0" if none)
• session-timeout - session time left for the user ("5h" or "" if none)
• session-timeout-secs - session time left for the user, in seconds ("3475" or "0" if there is such timeout)
• session-time-left - session time left for the user ("5h" or "" if none)
• session-time-left-secs - session time left for the user, in seconds ("3475" or "0" if there is such timeout)
• uptime - current session uptime ("10h2m33s")
• uptime-secs - current session uptime in seconds ("125")

Traffic counters, which are available only in the status page:

• bytes-in - number of bytes received from the user ("15423")
• bytes-in-nice - user-friendly form of number of bytes received from the user ("15423")
• bytes-out - number of bytes sent to the user ("11352")
• bytes-out-nice - user-friendly form of number of bytes sent to the user ("11352")
• packets-in - number of packets received from the user ("251")
• packets-out - number of packets sent to the user ("211")
• remain-bytes-in - remaining bytes until limit-bytes-in will be reached ("337465" or "---" if there is no limit)
• remain-bytes-out - remaining bytes until limit-bytes-out will be reached ("124455" or "---" if there is no limit)

Miscellaneous variables:

• session-id - value of 'session-id' parameter in the last request
• var - value of 'var' parameter in the last request
• error - error message, if something failed ("invalid username or password")
• error-orig - original error message (without translations retrieved from errors.txt), if something failed ("invalid username or password")
• chap-id - value of chap ID ("\371")
• chap-challenge - value of chap challenge ("\357\015\330\013\021\234\145\245\303\253\142\246\133\175\375\316")
• popup - whether to pop-up checkbox ("true" or "false")
• advert-pending - whether an advertisement is pending to be displayed ("yes" or "no")

RADIUS-related variables:

• radius<id> - show the attribute identified with <id> in text string form (in case RADIUS authentication was used; "" otherwise)
• radius<id>u - show the attribute identified with <id> in unsigned integer form (in case RADIUS authentication was used; "0" otherwise)
• radius<id>-<vnd-id> - show the attribute identified with <id> and vendor ID <vnd-id> in text string form (in case RADIUS authentication was used; "" otherwise)
• radius<id>-<vnd-id>u - show the attribute identified with <id> and vendor ID <vnd-id> in unsigned integer form (in case RADIUS authentication was used; "0" otherwise)

Working with variables

$(if <var_name>) statements can be used in theses pages. Following content will be included, if value of <var_name> will not be an empty string. It is an equivalent to $(if <var_name> != "") It is possible to compare on equivalence as well: $(if <var_name> == <value>) These statements have effect until $(elif <var_name>), $(else) or $(endif). In general case it looks like this:

some content, which will always be displayed
$(if username == john)
Hey, your username is john
$(elif username == dizzy)
Hello, Dizzy! How are you? Your administrator.
$(elif ip == 10.1.2.3)
You are sitting at that crappy computer, which is damn slow...
$(elif mac == 00:01:02:03:04:05)
This is an ethernet card, which was stolen few months ago...
$(else)
I don't know who you are, so lets live in peace.
$(endif)
other content, which will always be displayed

Only one of those expressions will be shown. Which one - depends on values of those variables for each client.

Customizing Error Messages

All error messages are stored in the errors.txt file within the respective HotSpot servlet directory. You can change and translate all these messages to your native language. To do so, edit the errors.txt file. You can also use variables in the messages. All instructions are given in that file.

Multiple Versions of HotSpot Pages

Multiple HotSpot page sets for the same HotSpot server are supported. They can be chosen by user (to select language) or automatically by JavaScript (to select PDA/regular version of HTML pages).

To utilize this feature, create subdirectories in HotSpot HTML directory, and place those HTML files, which are different, in that subdirectory. For example, to translate everything in Latvian, subdirectory "lv" can be created with login.html, logout.html, status.html, alogin.html, radvert.html and errors.txt files, which are translated into Latvian. If the requested HTML page can not be found in the requested subdirectory, the corresponding HTML file from the main directory will be used. Then main login.html file would contain link to "/lv/login?dst=$(link-orig-esc)", which then displays Latvian version of login page: <a href="/lv/login?dst=$(link-orig-esc)">Latviski</a> . And Latvian version would contain link to English version: <a href="/login?dst=$(link-orig-esc)">English</a>

Another way of referencing directories is to specify 'target' variable:

        <a href="$(link-login-only)?dst=$(link-orig-esc)&target=lv">Latviski</a>
        <a href="$(link-login-only)?dst=$(link-orig-esc)&target=%2F">English</a>

After preferred directory has been selected (for example, "lv"), all links to local HotSpot pages will contain that path (for example, $(link-status) = "http://hotspot.mt.lv/lv/status"). So, if all HotSpot pages reference links using "$(link-xxx)" variables, then no more changes are to be made - each client will stay within the selected directory all the time.

Misc

If you want to use HTTP-CHAP authentication method it is supposed that you include the doLogin() function (which references to the md5.js which must be already loaded) before the Submit action of the login form. Otherwise, CHAP login will fail.

The resulting password to be sent to the HotSpot gateway in case of HTTP-CHAP method, is formed MD5-hashing the concatenation of the following: chap-id, the password of the user and chap-challenge (in the given order)

In case variables are to be used in link directly, then they must be escaped accordingly. For example, in login page, <a href="https://login.example.com/login?mac=$(mac)&user=$(username)">link</a> will not work as intended, if username will be "123&456=1 2". In this case instead of $(user), its escaped version must be used: $(user-esc): <a href="https://login.server.serv/login?mac=$(mac-esc)&user=$(user-esc)">link</a>. Now the same username will be converted to "123%26456%3D1+2", which is the valid representation of "123&456=1 2" in URL. This trick may be used with any variables, not only with $(username).

There is a boolean parameter "erase-cookie" to the logout page, which may be either "on" or "true" to delete user cookie on logout (so that the user would not be automatically logged on when he/she opens a browser next time.

Firewall customizations

Summary

[ Top | Back to Content ]