Infinitel HotSpotWeb User Manual

Transcription

1 Infinitel HotSpotWeb User Manual INTRODUCTION... 5 REQUIREMENTS... 6 INSTALLATION... 7 FIRST STEP... 7 MICROSOFT WINDOWS... 7 Uninstall service... 7 OTHER OS... 7 ADVANCED INSTALLATION SETTINGS... 8 Application.properties file... 8 Options... 8 Setup database... 9 FIRST USE... 9 SETTINGS ROUTERS MANAGEMENT Name IP Address Port API User API Password Customer Página 1 de 33

2 User Name Prefix User Name Length User Password Length Profiles Sequential Next Predefined User Names License TICKET FORMATS MANAGEMENT Name Content PRINTERS MANAGEMENT Name Type Network printer Local Printer Ticket PRINTING TICKETS ROUTER PROFILE PRINTER TICKET Página 2 de 33

3 USERNAME PRINT RESTFUL API REFERENCE API ACCESS SETTINGS MANAGEMENT ENTITIES Router Ticket Printer UserLog LIST OR CREATE ENTITIES URL Methods List parameters Examples VIEW, MODIFY OR DELETE ENTITY URL Methods Examples PRINT COMMAND URL Parameters Página 3 de 33

4 JSON Response Examples: PROFILES COMMAND URL Parameters JSON Response Examples: RUN COMMAND URL Parameters JSON Response Examples: CHANGELOG VERSION Página 4 de 33

5 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 o o o Format your text font: bold, underlined, double tall, double wide. Align it to left, center or right. Print your custom logo. Set autocut paper if printer supports it. HotSpotWeb is compatible with Mikrotik RouterOS or Página 5 de 33

6 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. Página 6 de 33

7 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. Página 7 de 33

8 Advanced installation settings Application.properties file 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 Página 8 de 33

9 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: If you use the default settings and you open the web browser in the same computer where you installed the app just type: 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 Go to the Settings section of this manual to perform these steps. Página 9 de 33

10 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 When editing or adding a router you will have the following fields to setup: Página 10 de 33

11 Name Name is a unique identifier for a Mikrotik User Manager device. It will be shown in selection lists when printing tickets. IP Address We must set the IP address or dns entry of the Mikrotik device running Mikrotik User Manager. Página 11 de 33

12 Port The TCP port used to connect to the API service. By default 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 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. Página 12 de 33

13 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 Página 13 de 33

14 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 user. The ticket is a field to set the full content of the ticket that will be send to the printer when creating an Página 14 de 33

15 [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 Página 15 de 33

16 [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 network printer needs network visibility from the host where the app is installed. Página 16 de 33

17 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 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. Página 17 de 33

18 Página 18 de 33

19 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. Página 19 de 33

20 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. Página 20 de 33

21 RESTful API reference Api access To access the root resource for the RESTful API you can use: or hostname>:8080/api You will obtain the following JSON response: { } "_links" : { "printers" : { "href" : " "templated" : true }, "userlogs" : { "href" : " "templated" : true }, "routers" : { "href" : " "templated" : true }, "tickets" : { "href" : " "templated" : true }, "profile" : { "href" : " } } Página 21 de 33

22 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 Router 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. Página 22 de 33

23 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 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. Página 23 de 33

24 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. 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: EqualAndCreatedLessThan?start= &end= List or create entities URL or hostname>:8080/api/<entity> Methods GET: List entities. POST: Create a new entity. Página 24 de 33

25 List parameters sort 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 or hostname>:8080/api/<entity>?page=<int> first one. Use page to select list viewed page, by default page size is 20 and the default page is 0, which is the size or hostname>:8080/api/<entity>?size=<int> Examples Sort routers by name: Sort routers by descending name: View the second page of the list of routers: Set the page size to 50: Página 25 de 33

26 View the third page of 30 elements sorted by descending address: Create a new network printer with ticket id 1 associated: HTTP POST to: Http Content-Type: application/json Http POST payload: { } "name" : "Printer 1", "type" : "NETWORK", "address" : " ", "port" : 9100, "ticket" : " View, modify or delete entity URL 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. DELETE: Delete entity. Página 26 de 33

27 Examples View router with id 6: Modify printer id 3 address: HTTP PATCH to: Http Content-Type: application/json Http PATCH payload: { } "address" : " " Delete printer with id 4: HTTP DELETE to: Print command Generates a new user and prints a voucher/ticket through the selected printer. URL or hostname>:8080/api/print Parameters router: Router ID. Optional if only one router is registered. target router. profile: User Manager profile to assign to the new user. Optional if only one profile is available on the printer: Printer ID. Optional if only one printer is registered. Página 27 de 33

28 printer. ticket: Ticket ID. Optional. Use this parameter to override the default ticket format associated with the 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 Generate user on router id 2 with profile 1day throught printer id 3. Generate user named user, through default router and default printer, with ticket format 5 with 1hour profile. Página 28 de 33

29 Profiles command List all available User Manager profiles for a registered router. URL 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. Response: { } "profiles":["default","1day"], "ok":true, "message":null Página 29 de 33

30 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 or hostname>:8080/api/run Parameters router: Router ID. Optional if only one router is registered. return. command: The command to execute on the router. Use the (vertical bar) to indicate a carriage 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: Response: { "ok":true, "message":null, Página 30 de 33

31 } "result":[ { } ] "!re":null, ".id":"* ", "dst-address":" /0", "gateway":" ", "gateway-status":" 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 Response: { } "ok":true, "message":null, "result":[] Show fields bridge and interface of all bridge ports on default router: =.proplist=bridge,interface Página 31 de 33

32 Response: { } "ok":true, "message":null, "result":[ { "!re":null, "bridge":"bridge1", "interface":"ether1" },{ "!re":null, "bridge":"bridge1", "interface":"ether2" },{ "!re":null, "bridge":"bridge1", "interface":"ether3" } ] Página 32 de 33

33 Changelog Version 1.0 Initial Release Version 1.2 Added embedded hsql scheduled backup Fixed log end date selection issue Added Fixed Password option on router configuration Página 33 de 33