Infinitel HotSpotWeb User Manual

Infinitel HotSpotWeb User Manual

ADVANCED INSTALLATION SETTINGS ... 8

Application.properties file ... 8 Options ... 8 Setup database ... 9 FIRST USE ... 9 SETTINGS ... 10 ROUTERS MANAGEMENT ... 10 Name ... 11 IP Address ... 11 Port ... 12 API User ... 12 API Password ... 12 Customer ... 12

User Name Prefix ... 12

User Name Length ... 12

User Password Length ... 12

Profiles ... 12

Sequential ... 13

Next ... 13

Predefined User Names ... 13

License ... 14

TICKET FORMATS MANAGEMENT ... 14

Name ... 14 Content ... 14 PRINTERS MANAGEMENT ... 16 Name ... 16 Type ... 16 Network printer ... 17 Local Printer ... 17 Ticket ... 17 PRINTING TICKETS... 19 ROUTER ... 19 PROFILE ... 19 PRINTER ... 19 TICKET ... 20

USERNAME ... 20

PRINT ... 20

RESTFUL API REFERENCE ... 21

API ACCESS ... 21 SETTINGS MANAGEMENT ... 22 ENTITIES ... 22 Router ... 22 Ticket ... 23 Printer ... 23 UserLog ... 23

LIST OR CREATE ENTITIES ... 24

URL ... 24

Methods ... 24

List parameters ... 25

Examples ... 25

VIEW, MODIFY OR DELETE ENTITY ... 26

URL ... 26 Methods ... 26 Examples ... 27 PRINT COMMAND ... 27 URL ... 27 Parameters ... 27

JSON Response ... 28 Examples: ... 28 PROFILES COMMAND ... 29 URL ... 29 Parameters ... 29 JSON Response ... 29 Examples: ... 29 RUN COMMAND ... 30 URL ... 30 Parameters ... 30 JSON Response ... 30 Examples: ... 30 CHANGELOG ... 33 VERSION 1.0 ... 33

Introduction

Infinitel HotSpotWeb for Mikrotik is an application with a web interface to generate customized printed tickets with randomly generated or predefined usernames and passwords for one or more Mikrotik User Manager based HotSpots. HotSpotWeb also provides a RESTful API to provide third party systems integration to manage the application settings, generate users, print tickets and perform any RouterOS API command against the registered devices through HTTP/JSON.

HotSpotWeb connects to the registered Mikrotik User Manager throught RouterOS API devices and prints to a thermal ESC/POS printer either local or with network support (wifi or ethernet) to generate paper tickets.

Infinitel HotSpotWeb supports as many Mikrotik User Manager profiles as you need. You can set your Mikrotik User Manager to set tickets duration in minutes, hours, days or weeks and print them with a single touch.

The app allows you to setup many options:

 Can be installed as Windows service or started from command line.  Define available RouterOS devices

 Define available printers (local or TCP)

 Setup as many profiles/credits as needed per device.  Define the username prefix and length per device.  Define the password length per device.

 Define list of predefined reusable usernames per device.  Define multiple customized ticket/voucher formats:

o Format your text font: bold, underlined, double tall, double wide. o Align it to left, center or right.

o Print your custom logo.

o Set autocut paper if printer supports it.

Requirements

The app needs these requirements to properly operate:  Java Runtime 1.7 or higher

 A Mikrotik RouterOS 5.12 or higher that should accomplish:

o To have installed and configured an instance of Mikrotik User Manager o To have enabled API service

o To have a user with access to API service  A ticket printer (local or TCP) ESC/POS compatible

The host system must have network access to the device RouterOS API service.

Printers must be locally installed in the host where the app is running or must have network visibility from the host in case of network printers.

Installation

First step

Download the app file and uncompress to a folder.

Microsoft Windows

Once uncompressed, you must install the app as a Windows service. From a command line interface move to the installation folder and type:

HotSpotWeb.exe /install

To start the newly installed service type: HotSpotWeb.exe /start

Once the service is installed you can control the service state from the Services window on the Windows Administrative Tools.

Uninstall service

To stop the service type: HotSpotWeb.exe /stop

To uninstall the service: HotSpotWeb.exe /uninstall

Other OS

To run the app on any Java 1.7+ enabled OS you should check that the java executable is on path and use the following command to run the app:

java -jar HotSpotWeb.jar

Follow your OS indications to install a java process as a daemon if you want the app to autostart when the system boots.

Advanced installation settings

The default applications properties file contains: #Web server port

server.port=8080

# Use embedded hsqldb

spring.datasource.url=jdbc:hsqldb:file:data/hotspot # End Use hsqldb

# Use MySQL example

# spring.datasource.url=jdbc:mysql://localhost/hsweb # spring.datasource.username=user

# spring.datasource.password=password

# spring.datasource.driverClassName=com.mysql.jdbc.Driver # End Use MySQL example

#Generate and update database schema on start spring.jpa.hibernate.ddl-auto=update

#Log file location

logging.file=./log/log.txt

#Backup Schedule

backup.cron=0 0 6 * * ?

All lines starting with # are comments. Options

server.port: Web server port to access to the web app. logging.file: Log file location

backup.cron: Set non-blocking backup schedule in Quartz cron expression format. The backup will only work if the embedded hsql database is used, if another dbms is used you will have to use its own backup procedures. By default, if not set, the backup will be performed daily at 06:00 AM. The backup file can be found at .\backup\backup.tgz.

Setup database

By default the app uses an embedded HSQLDB to store the data but can be switched to any other SQL database with a JDBC driver supported by the HIBERNATE framework. In the default application.properties file there’s a commented example to setup a MySQL database.

Only the HSQLDB JDBC driver is included. If you want to use another database you must download the corresponding JDBC driver and place it in the <installation path>/lib directory before starting the application.

Only one datasource can be used at once, so if you switch to another database please comment or delete any other sprint.datasource.* entry.

Usually, on most dbms, you´ll have to create the database first. The application will create all needed tables on the first connection to a new database.

First use

Once installed and configured you can access the application using the url: http://<ipaddress_or_hostname>:<port>

If you use the default settings and you open the web browser in the same computer where you installed the app just type:

http://localhost:8080

To start using the application you must: 1. Setup at least one Router 2. Setup at least one Ticket format. 3. Setup at least one Printer

Settings

The home screen allows to access to all application settings.  Routers

To manage Mikrotik User Manager devices and their configuration.  Printers

To manage local and network printers.  Tickets

To create and edit available ticket formats.

Routers Management

Name

Name is a unique identifier for a Mikrotik User Manager device. It will be shown in selection lists when printing tickets.

IP Address

Port

The TCP port used to connect to the API service. By default 8728. API User

Username with enough permissions to access the Mikrotik device through API service, read settings and write new User Manager users. In our example

API Password

The password of the previously specified user. Customer

This parameter makes reference to the customer/subscriber (depending on User Manager’s version) that owns the profiles/credits that the application uses. Specifically, the owner of the profiles (in 5.x) or credits (in 4.17) and the owner of the newly created users that will get printed tickets.

User Name Prefix

Newly created user will get an username like [prefix][random string]. It can be left blank. User Name Length

This parameter specifies the length of the random string generated to compose the new usernames. It is recommended to use a string length greater than or equal to 4.

User Password Length

This parameter will set the default length for the newly generated user’s password which will always be a random string of the specified length.

Profiles

The profiles parameter refers to profile elements in Mikrotik 5.12 or higher, or credit elements in version 4.17. On the printed ticket the tag ${profile} will be replaced by:

 On version 4.17: The credit’s comment value will be used. If the value of comment is empty the name of the profile will be used instead.

 On version 5.12 or higher: The profile’s field “name-for-users” will be used. If not set, the name of the profile will be used instead.

Once name, ip address, port, API user, API password and customer are set you can use the Load Profiles button to preload the existing profiles in User Manager.

Sequential

When Sequential is enabled, usernames will be created sequentially building the username as [prefix]+[next number]. The username number will be taken from Next Number for Username and will be formatted as a zero filled string based on the value of Username Length. As an example, having a Username Length of 4 and a Prefix as Pre_ new generated users will be in the range of Pre_0001 and Pre_9999. Once, in this example, the 9999 value is reached count will restart at 1.

Next

The value for the next sequentially generated username. Fixed Password

If Fixed Password is checked, the generated password will be always equal to the generated username. Useful to setup single field login (instead of user/password login) captive portal.

Predefined User Names

List of predefined and reusable usernames. Those will be available from the print page.

This function can be easily explained through an example. Suppose we have a small hotel with 10 rooms. We want to assign a username to each room and change the password each time a new guest checks in. We should create a username list like this:

Room01 Room02 Room03 … Room10

If we choose a predefined username, Room03 as an example, and we push the print button, let’s say 1week. Within this example we will get a ticket with Room03 as username, for 1 week and with a random password. If user Room03 already exists in User Manager, it will be deleted and replaced with a newly created user.

License

The application is licensed per User Manager instance.

Ticket Formats Management

Name

Name is a unique identifier for a ticket format. Content

The ticket is a field to set the full content of the ticket that will be send to the printer when creating an user.

[C][LOGO] [B][U]HotSpot Infinitel [L][b][u] [B]Acceso: [b]${profile} [B]Nombre: [b]${user} [B]Clave: [b]${pass} [R][W][T]Thank you [CUT]

When editing the ticket we should specify the following variables:  ${profile} will be filled with the profile’s name

 ${user} will be filled with the generated username

 ${pass} will be filled with the generated random password  ${time} will be filled with the current time and date

To set the format of the ticket we can use the following tags:  [B] Set bold text

 [b] Unset bold text  [U] Set underlined text  [u] Unset underlined text  [T] Set double tall text  [t] Unset double tall text  [W] Set double wide text  [w] Unset double wide text  [L] o [l] Align to the left

 [C] o [c] Align to center  [R] o [r] Align to the right

 [LOGO] Print the bitmap set to the position 1 of NV memory in the ESC/POS printer  [CUT] Make paper cut (if supported by the printer)

Printers Management

HotSpotWeb supports any ESC/POS compatible printer.

Name

Name is a unique identifier for a printer. Type

Select printer type, Local or Network

A local printer can be chosen from the installed printers in the installation host. Network printer

 _Address

Ip address or hostname of the network printer.  _Port

TCP port where the printer listens to connections. Usually 9100. Local Printer

The dropdown list show all printers installed on the host machine. Ticket

Choose the default ticket format for this printer. If no ticket is chosen the ticket will output through the default printer selected here.

Printing Tickets

The Print page allows you to generate users and print tickets selecting the different options available:

Router

If more than one Mikrotik device has been setup you can choose where to generate the user. If only a single Mikrotik device has been setup this column will be hidden.

Profile

Shows the available profiles in the selected router. Once again if only one profile is available the column will be hidden, so no need to choose a profile.

Printer

Lists the available printers. Choose one to set the printer where the ticket is printed. If only one printer is available the column will remain hidden.

Ticket

Lists the available ticket formats. If none is chosen, the default ticket format for the selected printer will be used. If only one ticket format is defined the column will remain hidden.

Username

You can enter a custom username on the textfield and it will be used when printing the next ticket. If the router has a predefined list of usernames it will be shown below the textfield as a list. If you choose an entry from the list it will be used as username.

If left blank or have not choose a predefined user, the routers settings will apply.

If a user with the same username already exists on the router, it will be erased and created again with the selected profile.

Print

When printing, the app will connect to the User Manager, generate a user with the selected options and print a ticket thought the selected printer. If the process completes successfully the new username and password will be shown below. If something fails, the app will show below the failure reason.

RESTful API reference

Api access

To access the root resource for the RESTful API you can use: http://<ipaddress or hostname>:8080/api

You will obtain the following JSON response: { "_links" : { "printers" : { "href" : "http://localhost:8080/api/printers{?page,size,sort}", "templated" : true }, "userLogs" : { "href" : "http://localhost:8080/api/userLogs{?page,size,sort}", "templated" : true }, "routers" : { "href" : "http://localhost:8080/api/routers{?page,size,sort}", "templated" : true }, "tickets" : { "href" : "http://localhost:8080/api/tickets{?page,size,sort}", "templated" : true }, "profile" : { "href" : "http://localhost:8080/api/alps" } } }

Settings management

The settings management API provides access to the different entities through RESTful/JSON using the HATEOAS standard. For each entity type you can list/view (GET), create (POST), modify (PUT, PATCH) or delete (DELETE) instances through http.

Entities

Each router is a registered Mikrotik device.  _Fields

name: Name of the router entity. Required. address: Ip address or hostname. Required. port: RouterOS API tcp port number. Required.

apiUser: User with RouterOS API privileges. Required. apiPassword: API user’s password. Required.

customer: User Manager customer for new users and profile search. Required. userNamePrefix: Generated username prefix. Optional.

userNameLength: Length of the variable part of the generated username. Required. userPasswordLength: Length of the generated random password. Required.

profiles: List of available profiles in the web interface. Required.

sequential: Use secuential usernames (true) or random usernames (false). Required. next: Next sequential username number. Required.

predefinedUserNames: List of predefined usernames to show on web interface. Optional license: License code. Optional.

Ticket

Ticket is a ticket print format.  _Fields

name: Name of the ticket entity. Required.

content: Content of the ticket. Refer to the ticket format specified on the current manual. Required. Printer

Each of the available printers.  _Fields

name: Name of the printer entity. Required. type: LOCAL or NETWORK. Required. address: Required.

 For a network printer use ip address or hostname.  For a local printer use the system’s printer name.

port: Set the TCP port for a network printer. Defaults to 9100. Optional. ticket: Default ticket format for this printer. Required.

UserLog

Log of generated users  _Fields

username: Generated username.

profile: User Manager’s profile assigned to the user. router: Router where the user was created.

created: Entry UTC date and time.  _{Search query}

Returns all log entries from a start date (yyyy-mm-dd 00:00:00) until end date (yyyy-mm-dd 00:00:00). Optionally, the result can be paginated.

http://<ipaddress_or_hostname>:8080/api/userLogs/search/findByCreatedGreaterThan EqualAndCreatedLessThan{?start,end,page,size,sort}

start: Start date formatted as yyyy-mm-dd. Required. end: End date formatted as yyyy-mm-dd. Required.

page: Optional page number for result pagination. First page is 0. size: Optional page size for result pagination.

sort: Optional sort by fieldname.

Example, to list all users generated on January 2015:

http://<ipaddress_or_hostname>:8080/api/userLogs/search/findByCreatedGreaterThan EqualAndCreatedLessThan?start=2015-01-01&end=2015-02-01

List or create entities

http://<ipaddress or hostname>:8080/api/<entity> Methods

GET: List entities.

List parameters  _sort

http://<ipaddress or hostname>:8080/api/<entity>?sort=<field,[desc]>

Use sort to order the results by the selected field. By default the order applied is ascending. If you want descending order you should append “,desc”.

 _page

http://<ipaddress or hostname>:8080/api/<entity>?page=<int>

Use page to select list viewed page, by default page size is 20 and the default page is 0, which is the first one.

 _size

http://<ipaddress or hostname>:8080/api/<entity>?size=<int> Examples

 _{Sort routers by name:}

http://localhost:8080/api/routers?sort=name  _{Sort routers by descending name:}

http://localhost:8080/api/routers?sort=name,desc  _{View the second page of the list of routers:}

http://localhost:8080/api/routers?page=1  _{Set the page size to 50:}

 _{View the third page of 30 elements sorted by descending address:}

http://localhost:8080/api/routers?page=3&size=30&sort=address,desc  _{Create a new network printer with ticket id 1 associated:}

HTTP POST to: http://localhost:8080/api/printers Http Content-Type: application/json Http POST payload: { "name" : "Printer 1", "type" : "NETWORK", "address" : "192.168.1.20", "port" : 9100, "ticket" : "http://localhost:8080/api/tickets/1" }

View, modify or delete entity

http://<ipaddress or hostname>:8080/api/<entity>/<id> Methods

GET: View entity.

PUT: Modify entity. All fields must be included. Any excluded field defaults to NULL. PATCH: Modify entity. Only need to include modified fields.

Examples

 _{View router with id 6:}

http://localhost:8080/api/routers/6  _{Modify printer id 3 address:}

HTTP PATCH to: http://localhost:8080/api/printers/3 Http Content-Type: application/json

Http PATCH payload: {

"address" : "192.168.1.21" }

 _{Delete printer with id 4:}

HTTP DELETE to: http://localhost:8080/api/printers/4

Print command

Generates a new user and prints a voucher/ticket through the selected printer. URL

http://<ipaddress or hostname>:8080/api/print Parameters

router: Router ID. Optional if only one router is registered.

profile: User Manager profile to assign to the new user. Optional if only one profile is available on the target router.

ticket: Ticket ID. Optional. Use this parameter to override the default ticket format associated with the printer.

username: Fixed username. Optional. The new user will be created with the specified username. If the username already exists it will refresh the password and assign the selected profile.

JSON Response { "ok":false/true , "message":"Error message"/null, "username":”user”/null, "password":”password”/null }

ok: true if request has been processed correctly, false if something failed. message: Reports the error message is something fails, otherwise returns null. username: Username of the newly created user.

password: Password of the newly created user. Examples:

 _{Generate a new random user with the default router, profile and print through the default printer}

http://localhost:8080/api/print

 _{Generate user on router id 2 with profile “1day” throught printer id 3.}

http://localhost:8080/api/print?router=2&profile=1day&printer=3

 _{Generate user named “user”, through default router and default printer, with ticket format 5 with “1hour” profile.}

Profiles command

List all available User Manager profiles for a registered router. URL

http://<ipaddress or hostname>:8080/api/profiles Parameters

router: Router ID. Optional if only one router is registered. JSON Response { "profiles":["profile1","profile2",…,”profileN”]/null, "ok":false/true , "message":"Error message"/null }

ok: true if request has been processed correctly, false if something failed. message: Reports the error message is something fails, otherwise returns null. profiles: List of available profiles or null if an error occurred.

Examples:

 _{Get available User Manager profiles on router id 1.}

http://localhost:8080/api/profiles?router=1 Response: { "profiles":["default","1day"], "ok":true, "message":null }

Run command

Run command allows to execute any available command on the router through the RouterOS API service. For detailed information about the RouterOS API service command format please consult the Mikrotik RouterOS documentation.

URL

http://<ipaddress or hostname>:8080/api/run Parameters

router: Router ID. Optional if only one router is registered.

command: The command to execute on the router. Use the | (vertical bar) to indicate a carriage return. JSON Response { "ok":false/true , "message":"Error message"/null, “result”:[{“key1”:”value1”,…,”keyN”:”valueN”},{…}] }

ok: true if request has been processed correctly, false if something failed. message: Reports the error message is something fails, otherwise returns null.

result: If the command responds with any output it will be returned as an array of key/value lists. Examples:

 _{Get the default gateway on router id 1:}

http://localhost:8080/api/run?router=1&command=/ip/route/print|?dst-address=0.0.0.0/0 Response:

{

"ok":true, "message":null,

"result":[ { "!re":null, ".id":"*30000001", "dst-address":"0.0.0.0/0", "gateway":"172.17.1.254",

"gateway-status":"172.17.1.254 reachable via e10wan", "distance":"0", "scope":"30", "target-scope":"10", "vrf-interface":"e10wan", "active":"true", "dynamic":"true", "static":"true", "disabled":"false" } ] }  _{Reboot router id 3} http://localhost:8080/api/run?router=3&command=/system/reboot Response: { "ok":true, "message":null, "result":[] }

 _{Show fields bridge and interface of all bridge ports on default router:}

Response: { "ok":true, "message":null, "result":[ { "!re":null, "bridge":"bridge1", "interface":"ether1" },{ "!re":null, "bridge":"bridge1", "interface":"ether2" },{ "!re":null, "bridge":"bridge1", "interface":"ether3" } ] }

Changelog

Version 1.0

Version 1.2

 Added embedded hsql scheduled backup  Fixed log end date selection issue