Professional Documents
Culture Documents
Zerotruth en
Zerotruth en
Zerotruth en
http://www.zerotruth.net
Spesso gli amici mi chiedono
come faccio a far scuola.
Sbagliano la domanda,
non dovrebbero preoccuparsi
di come bisogna fare scuola,
ma solo di come bisogna essere
per poter fare scuola.
— Lorenzo Milani
ZeroTruth
Interface to ZeroShell’s Captive Portal
c
2012-2015
L EGAL N OTES
The author of this documentation is Nello Dalla Costa (with the only exception of Section 2, by
Fulvio Ricciardi). This documentation has educational value only and is provided free of charge.
This documentation is distributed in the hope that it will be useful, but without any warranty; with-
out even the implied warranty of merchantability or fitness for a particular purpose. The author
reserves the right not to be responsible for the topicality, correctness, completeness or quality of
the information provided. The author cannot be held liable for any damage or loss of a material or
non-material nature resulting from the use or non-use of the information provided or from the use
of incorrect or incomplete information. The author explicitly reserves the right to modify, supple-
ment or delete some of the pages or the entire content without providing separate notification,
or stop publication thereof temporarily or indefinitely.
All brand names and trademarks that are mentioned in the content of this guide may be pro-
tected by third parties and are unrestrictedly subject to the conditions of the applicable trade-
mark law and the ownership rights of the owner(s) thereof. Any redistribution or reproduction of
part or all of the contents in any form is prohibited without written agreement from the author.
However, Hyperlinks from other website to this documentation are very much appreciated. For
that purpose, you are invited to use the following link:
http://www.zerotruth.net/controldl.php?file=ZEROTRUTH-EN.pdf
Contents
1 Z ERO T RUTH AND Z ERO S HELL 1
2 CAPTIVE P OR TAL 2
2.1 H OTSPOT ROUTER FOR AUTHENTICATED NETWORK ACCESS . . . . . . . . . . . . . . . . . . . . . 2
2.2 T HE ENEMIES OF THE CAPTIVE P ORTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.3 S POOFING OF THE IP AND THE MAC ADDRESSES . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.4 D ENIAL OF S ERVICE (D O S) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.5 R OUTER OR B RIDGE ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 U SER AUTHENTICATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.7 RADIUS (PAP, EAP-TTLS E PEAP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.8 K ERBEROS 5 (ACTIVE DIRECTORY ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.9 X.509 D IGITAL C ERTIFICATES (S MART CARDS ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.10 S HIBBOLETH (I D P SAML 2.0) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.11 ACCOUNTING FOR TIME , TRAFFIC AND COST OF THE CONNECTIONS . . . . . . . . . . . . . . . . 9
2.12 N ETWORK ACCESS LIMITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.13 L OGGING OF USER ACCESSES AND TCP/UDP CONNECTIONS . . . . . . . . . . . . . . . . . . . 11
2.14 L OAD B ALANCING AND FAULT TOLERANCE OF THE I NTERNET C ONNECTIONS . . . . . . . . . . . 12
4 C ONFIGURATION 17
4.1 Z EROT RUTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2 A DMIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.3 U SERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.4 I MAGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.5 A STERISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.6 LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.7 LDAP C ONTROL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.8 K EYPAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.9 VSBS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.10 E XPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.11 F ONT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.12 T EST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
4.13 CAPTIVE P ORTAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
4.14 S ELF REGISTRATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4.14.1 R EGISTRATION WITH A STERISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.14.2 R EGISTRATION WITH SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
4.14.3 R EGISTRATION WITH T ICKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.15 N OTICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
4.16 T ICKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.17 PAY PAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.17.1 Z EROT RUTH PAY PAL C ONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.17.2 PAYPAL C ONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
4.18 PAYMENTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.19 L OCK / UNLOCK USERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.20 WALLED G ARDEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.20.1 L OCAL WALLED G ARDEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.20.2 E XTERNAL WALLED G ARDEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
i
4.21 P OPUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.22 L OGIN I MAGES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.23 FACEBOOK L IKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4.24 P ROXY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4.24.1 S QUID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.24.2 DANSGUARDIAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.24.3 H AVP +C LAMAV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.25 S HAPER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.26 B LOCKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.26.1 IP B LOCKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.26.2 AD B LOCKER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.27 E MAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.28 SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.28.1 MY SMS SCRIPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
4.28.2 G AMMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
4.29 M ULTI CP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
4.30 B ACKUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.30.1 B ACKUP WITH EMAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.30.2 B ACKUP WITH FTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.30.3 B ACKUP WITH D ROP B OX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
4.30.4 B ACKUP WITH SCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
4.30.5 R ESTORE B ACKUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.31 D ISK CAPACITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
4.32 G RAPHS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
4.33 U PGRADES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5 U SERS M ANAGEMENT 68
5.1 A DD U SER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.1.1 A DD SINGLE USER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.1.2 A DD MULTIPLE USERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.1.3 A DD USERS FROM FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.1.4 A DD U SERS B OUND TO T ICKETS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.2 U SERS L IST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.2.1 S TANDARD TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.2.2 U SERS LIST FOR SELF - REGISTRATION VIA TICKET . . . . . . . . . . . . . . . . . . . . . . . 74
5.2.3 R ICERCA UTENTI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.2.4 FAST TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
6 P ROFILES 77
6.1 P ROFILE TABLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
6.2 A DD P ROFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
6.3 PAYMENT P ROFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
6.4 P ROFILE WITH BANDWIDTH LIMITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
6.5 P ROFILE WITH NETWORK INTERFACE SPECIFICATION . . . . . . . . . . . . . . . . . . . . . . . . . 79
7 E MAIL 80
7.1 S END EMAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
8 SMS 81
8.1 S END SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
ii
9 CAPTIVE P OR TAL U SAGE 82
9.1 CAPTIVE P ORTAL L OGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
9.1.1 L OGIN STANDARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
9.1.2 O PEN L OGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
9.1.3 L OGIN WITH QR CODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.2 C HANGE PASSWORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
9.3 U SER CONNECTION DETAILS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
9.4 S ELF - REGISTRATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.4.1 S TANDARD S ELF - REGISTRATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
9.4.2 S ELF - REGISTRATION WITH S OCIAL N ETWORK . . . . . . . . . . . . . . . . . . . . . . . . 89
9.4.3 S ELF - REGISTRATION WITH A STERISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
9.4.4 S ELF - REGISTRATION WITH SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
9.4.5 S ELF - REGISTRATION WITH T ICKET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
9.5 PASSWORD R ECOVERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
9.5.1 S TANDARD PASSWORD R ECOVERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
9.5.2 PASSWORD R ECOVERY WITH A STERISK . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
9.6 CAPTIVE P ORTAL L OCKING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
D Scripts 106
D.1 Keypad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
iii
1 Z ERO T RUTH AND Z ERO S HELL
I NTRODUCTION
I came across ZeroShell when I was looking for a software application that clould manage one
or more Captive Portals but also had a simple enough interface for people with a limited back-
ground in network administration (e.g. a Secretary). Let me say that I was pleasantly surprised by
ZeroShell! In fact, I could manage to get it installed and configured on a little Alix in less than 20
minutes, after which the new system was already providing Internet conncetivity to mobile users!
How can I make ZeroShell’s Captive Portal capability more user-friendly to non-expert adminis-
trators?
After a first experience with an application written in PHP (it was a remote application running
on a computer connected to a ZeroShell server... very slow... too slow!) I decided to start over
again and create a new interface directly on the ZeroShell server. The resulting interface (Ze-
roTruth, which is now written in cgi-bin scripts) was much faster and, as a bonus, I gained access
to all ZeroShell’s functionalities, most of which were not accessible over the network.
ZeroTruth makes exstensive use of ZeroShell’s Captive Portal and Accounting functionalities but
it also adds much more to that, such as the remote management of multiple Captive Portals from
a single ZeroTruth station designated as master station. ZeroTruth is used in community centers,
libraries and schools as well as in many public hotspots where it can cover larger areas. ZeroTruth
aims at providing a complete, yet simple and scalable solution, to manage multiple Captive Por-
tals for different installation scenarios, which may be devised for serving not only few users but
thousands of them.
Without having ZeroShell functionalities, robustness and public availability, ZeroTruth would not
have come this far and obtained so much appreciation from many people, technicians and
companies around the globe. Lots of help came also from the Italian forum of ZeroShell where
several users did test ZeroTruth very extensively. The outcome of this were extremely useful sugges-
tions for general improvements and new features.
Last but not least, a special thanks goes to the developer of ZeroShell Fulvio Ricciardi, for his
technical support and trust in ZeroTruth’s project.
1
2 CAPTIVE P OR TAL
With granted permission of Fulvio Ricciardi, Text and images of this entire Section were taken from
“Hotspot router for authenticated network access”.
The purpose of this document is to describe the implementation of a gateway for Wi-Fi hotspots
using ZeroShell. We will focus especially on how to authenticate users (RADIUS, Kerberos 5 and
X.509 digital certificates) and on the RADIUS accounting for traffic, time and cost of the connec-
tions. It will take a look at the possibility of obtaining multi-WAN router with balancing and failover
of the Internet connections and functionality of Captive Portal.
In the hotspots, that is in public places where Internet access is given to occasional users, at least
some of the following features are required:
1. Authentication of the users,
2. Logging of the accesses to the network,
3. Accounting for traffic, time and cost of the user connections.
The authentication, that is the ability to uniquely identify the user and then grant access to the
network, it can be done via username and password or through a X.509 digital certificate that
could be stored on smart card.
The access log is sometimes required by law, because it allows us to trace the perpetrators of
illicit activities. Mind you that logging does not include registration of URLs or worse content that
the user had access, but simply record the date and time of start and end of each of the con-
nections to the Internet of the user and the IP address associated with the client (usually a laptop)
from where the connection took place.
The accounting, however, in addition to tracking the beginning and end of the connection,
record the time and traffic for connection of a user. Often the purpose of accounting is to al-
low the charging of costs for traffic in Megabytes and time in minutes of connection. In addition,
through accounting, you can set limits on traffic and time over which the user is disconnected from
the network. In particular, the accounting can allow the management of prepaid connections in
which the user must have a Credit to be online.
2
In order to obtain this functionality you can use one or both of the following methods of access:
• Captive Portal.
WPA/WPA2 Enterprise, which requires Wi-Fi Access Points associate a client only if the user has
valid credentials verified by a RADIUS server using 802.1x. In addition to authentication, traffic en-
cryption is also guaranteed between client and Access Point.
In the case of access via captive portal instead, the Access Points are programmed in open
mode, that is without any authentication and encryption. The client can associate freely and im-
mediately receives an IP address from DHCP server. However, the gateway to the Internet access
blocking communication with the outside and redirects any web request (http and https) to an
authentication page.
It soon becomes clear that WPA/WPA2 Enterprise is a more robust system in terms of security com-
pared to the captive portal, but on the other hand, it requires the user to configure his client
(supplicant) to authenticate via 802.1x. This configuration is not easy for occasional users of a
hotspot and for this reason, which in most cases, we prefer to give access using captive portal
that requires no configuration on the mobile devices.
Some Wireless Access Points internally implement a captive portal, but often this is not config-
urable and adaptable to the needs of a hotspot. It is more flexible and convenient to use low
cost WiFi Access Points, without any advanced feature and refer the captive portal function to a
router that acts as a gateway to the Internet as shown in Figure 1.
3
2.3 S POOFING OF THE IP AND THE MAC ADDRESSES
The security issue longer felt when talking about Captive Portal is spoofing the IP and MAC ad-
dresses of network card. In fact, the firewall of the Captive Portal unlocks clients authenticated
by identifying the IP and MAC addresses (the latter only if the captive portal is directly connected
at layer 2 of the network to be protected, that is there are no router half). Unfortunately, these 2
parameters can be set easily on any operating system and therefore, there is a risk that someone
with a sniffer captures traffic looking for a client already authenticated and set the same IP and
MAC addresses. This would disturb the communication of the client legitimately authenticated
that noting a low connection quality, abandons the use of the Internet, leaving space to fraud.
The problem is made worse by the fact that most of the captive portal implementations main-
tain an authenticated client connected until it is visible on the network without the client actively
participate in the renewal of authentication. Some implementations check the ARP table to see
if the client has recently made traffic or perform an ARP Request for checking the presence of the
IP on the network. Others use the table of the leases of the DHCP server, checking whether the
client has requested the renewal recently. These solutions are clearly insecure, because the client
has a passive role in the reaccreditation of authentication.
ZeroShell’s solution is instead to ensure that the client itself is to ask the captive portal gateway
the renewal of the authentication, presenting a packet encrypted with AES256, called Authenti-
cator. This is a secret shared only by the client and by captive portal (it travels in the SSL tunnel and
therefore can not be captured with a sniffer), so even if someone sets the IP and MAC address
of an authenticated user will not have the Authenticator required by the captive portal to renew
the authentication. The Authenticator is stored by the client in a popup window called Network
Access Popup that handles using Java Script to send it to the captive portal for renewal.
The popup window also performs other functions, such as to allow the user to disconnect and
view useful accounting information such as time, traffic and cost of the connection. It should
be noted that this window is not blocked by anti-popup which comes with almost every web
browser because it is opened by a synchronous request for user authentication. On the other
hand, the popup window has caused several problems with the advent of mobile devices such
as the iPhone, the iPad and other smartphones and PDAs (including Windows Mobile and An-
droid) that not having a multitasking system actually forgot to renew the authentication causing
the closure of the connection.
To remedy this problem, since the release 1.0.beta15 of ZeroShell, mobile devices are recognized
by the captive portal that does not impose them the renewal of authentication by sending the
Authenticator, but simply verifying their online presence.
4
Figure 4: Smartphones and other Mobile Devices configuration
The best known example of this category of programs is the Skype VoIP client, but many other
P2P systems and worms have the same behavior. You can imagine immediately that when a user
is associated with its clients to the network, but not yet authenticated by the Captive Portal, such
requests on the TCP ports 80 and 443 will be redirected to the authentication portal which would
try unsuccessfully to serve them given that the traffic is not HTTP. It is obvious that more the clients
are not authenticated yet and run these programs, more it increases the probability of occur-
rence of a DoS (Denial of Service) in which the portal of authentication is committed to serving
fake requests, failing to operate or handle very slowly rightful requests from web browsers.
ZeroShell restricts the occurrence of such situations by implementing a system of DoS Protection
using the Linux Netfilter to limit the maximum number of redirects per minute. The protection level
can be set on three levels (Low, Medium e High).
5
In addition, the mechanisms of Auto-Update of the Operating Systems and of the Antivirus Signa-
tures often use the http protocol to communicate with the updating repository and therefore may
exacerbate the situation, making requests that are added to the workload of the Captive Portal.
Again ZeroShell attempts to contain the problem by intercepting requests to the most common
repository avoiding unnecessary redirect to the authentication page of the Captive Portal.
• It is handled the MULTI interface where you can declare multiple network interfaces on which to
activate the Captive Portal. As shown in Figure 6 can also be enabled on 802.1q VLAN (Virtual
LAN Tagged),
• ZeroShell selects the bridge or router mode automatically checking whether or not an interface
is part of a bridge.
Putting together the two innovations, one deduces that the Captive Portal of ZeroShell can work
simultaneously on the same hardware box as a router for some LAN segments and as a bridge for
others.
6
can come from different domains. In this case, the user must select the authentication domain
using the selection box on the access page or by qualifying its username by using @domain suffix
(for example pluto@example.com).
7
The captive portal can make authentication requests via PAP or 802.1x (EAP-TTLS with PAP and
PEAP with MSCHAPv2). In the latter case, the captive portal appears to the RADIUS server as
a supplicant that attempts to access WiFi network via WPA/WPA2 Enterprise. The use of 802.1x
is recommended over the simple PAP if you need a higher level of security, guaranteed by TLS
protocol which EAP-TTLS, PEAP (EAP Protect) use.
The Kerberos 5 authentication allows captive portal to interface to a Windows Active Directory
domain. In fact, each Windows Server that is a domain controller has a Kerberos 5 KDC that
authenticates users in the Active Directory domain to which it belongs. Therefore, just add to the
captive portal authorized domains the name of the Active Directory domain to allow Windows
users to access the network. Note that if the automatic discovery of the REALM and KDC via DNS
SRV records is not active you need to manually specify the IP addresses (or FQDN hostnames) of
the authoritative KDC REALM.
In some situations it could be needed to allow access via captive portal only to user that belongs
to a group. This is not possible using Kerberos 5, since it only handles the Active Directory authenti-
cation while authorization is delegated to LDAP. However, you can turn on the domain controllers,
the IAS (the RADIUS service of Active Directory) and configure the captive portal to authenti-
cate against RADIUS. In this case, you can configure IAS to authorize only users who belong to a
selected group.
8
often related to that of the Smart Cards or of the USB tokens. These devices may keep the digi-
tal certificate in an extremely secure way because the private key can not be extracted with a
read operation from the outside. Smart Cards are therefore equipped with their own processor
chip that carries out the encryption and decryption requests via the API. To unlock the private key
used by the browser the Smart Card requires entering a PIN, which helps to increase security if the
card is lost.
Therefore, it is preferable to use SAML, where instead, credentials travel, starting from the user’s
browser to its authoritative IdP, always within the same SSL-encrypted tunnel, thereby guarantee-
ing the end-to-end authentication. More details on the Shibboleth Captive Portal are available
on the document “Configure the Captive Portal to authenticate users against an IdP SAML 2.0
using Shibboleth” (http://www.zeroshell.net/shibboleth-captive-portal/).
The accounting allows us to know, for each user, the time, the traffic and the cost of the connec-
tions. The Captive Portal of ZeroShell uses the RADIUS protocol to transmit such information, so
you can use an external server that supports the RADIUS accounting or just accounting module
inside ZeroShell based on FreeRADIUS. As the authentication, also the accounting can be central-
ized on a single RADIUS server that collects information from multiple hotspots. In addition, keep in
mind, that the accounting system of ZeroShell can, because it meets the standard RADIUS, collect
information also directly from the Wi-Fi Access Point that use WPA/WAP2 Enterprise with 802.1x.
9
Figure 11: User accounting details
Using RADIUS accounting it is possible also set connection limits for users. To do this, simply assign
the users to a class of accounting to which you give the following parameters:
10
2.13 L OGGING OF USER ACCESSES AND TCP/UDP CONNECTIONS
Although already the accounting keeps track of user connections to the network it is possible to
have more details on user authentication, looking at log messages referring to the Captive Portal.
Moreover, especially if the clients of the captive portal using private IP addresses, it can be useful
to keep track of TCP and UDP connections that are established with external servers, since the
captive portal must perform NAT (Network Address Translation), all connections appear gener-
ated by the router’s public IP.
The logging of the Connection Tracking must be explicitly enabled and it is recommended to
assess, before you enable it, that its use is permitted by privacy laws, taking into account the fact,
that it can not be used to know the contents of users’ communications, but only to determine
what servers have been contacted.
11
2.14 L OAD B ALANCING AND FAULT T OLERANCE OF THE I NTERNET C ONNECTIONS
In order to ensure adequate and stable bandwidth for Internet you can enable load balancing
and fault tolerance for WAN links. ZeroShell can work in two modes called Failover and Load
Balancing and Failover. In the first case all traffic is routed by the link most efficient, while other
connections are spares and only take place in case of failure of the active one. In Load Balanc-
ing and Failover mode, instead, all connections are simultaneously active and the traffic is routed
over them in round-robin. Even in the latter case is guaranteed fault tolerance, since, if a link is
inaccessible is automatically excluded from the balancing until it returns accessible.
In addition, you can balance the traffic manually. For example, you may decide that VoIP traf-
fic is routed by a link, while that generated by the transfer of files from one another. This will
avoid saturating the link that would produce noise in the VoIP communications. For more details,
read the document “Multiple Internet Connections by Balancing Traffic and Managing Failover”
(http://www.zeroshell.org/load-balancing-failover/).
12
3 I NSTALLATION AND R EMOVAL OF Z ERO T RUTH
It’s very easy to install ZeroTruth but, because ZeroTruth is based on ZeroShell, we must activate
some functions on ZeroShell first.
The SSH service can be enabled, depending on your needs, for a single IP address, a subnet or a
specific network interface.
You should also activate, on the Zeroshel’s GUI, both the Captive Portal and the Accounting
module otherwise, during the installation, ZeroTruth will ask for it.
The Captive Portal can be enabled, depending on your network, on one or more interfaces.
13
The accounting module can be easily activated without any particular procedure as follow:
At this point we will be able to connect via SSH to ZeroShell and to install ZeroTruth. If you are
connecting from a Linux environment you can simply use a terminal windown. Instead, if you are
connecting from a Windows system, you can download and install a freely available open source
tool called Putty.
Once you’ve got a working terminal window in your hands, just type in the following command:
“ssh admin@192.168.0.75”
In Figure 18 there is list of commands of ZeroShell and to select the Shell Prompt command it’s
necessary to type “S”.
The default credentials are “admin” as username and “zeroshell” as the corresponding password.
14
3.2 Z ERO T RUTH I NSTALLATION
We are now logged into our ZeroShell machine from which we are ready to install, for example, the
latest version 3.0 of ZeroTruth (zerotruth-3.0.tar.gz). To do this, it’s necessary to type the following
commands:
• cd /DB
• wget http://www.zerotruth.net/controldl.php?file=zerotruth-3.0.tar.gz
• tar zxvf zerotruth-3.0.tar.gz
• cd zerotruth-3.0
• ./install.sh
The command “./install.sh” will executes all the necessary operations needed for the installation
of ZeroTruth. It will also show the current step being excuted and report any error that may occur.
Removing ZeroTruth in this way, will only preserve the database of the users whereas any other
configuration will be removed.
Since version 1.0.beta2, the upgrade to any newer release can be done directly from the Ze-
roTruth GUI.
This is the preferred method since it does preserve not only the database of the users but also
any other pre-existing configuration.
15
3.5 ACCESS TO THE A DMINISTRATION GUI
Connecting with a Web browser to the default IP address of ZeroShell “http://192.168.0.75”, you
will be requested to select either the ZeroShell or ZeroTruth login.
We select ZeroTruth and then enter the default username “admin” and password “zerotruth” to
access the main page of ZeroTruth.
Figure 20: Select page (on the left), ZeroTruth login page (on the right)
After the authentication, you are directed to the page which displays the list of the users of the
Captive Portal to have an immediate overview of the system usage.
On your first login, you will have to configure ZeroTruth using the corresponding configuration
page. The “Config” button and the configuration page will be visible and accessible only to
the system administrator.
Note that the header buttons may vary depending on your configuration, services and current
logged in user. For example, in Figure 21, it is not present the SMS button because this service is
not yet configured or activated.
16
4 C ONFIGURATION
In the configuration page there are lots of links to different sections.
From this page you can also register ZeroTruth in order to install extra 2 functionalities and have
access to the latest updates.
Registration is automatic if you make a donation to ZeroTruth via Paypal. 3 In fact, you will shortly
receive an email with a personal code to be inserted in the appropriate form.
Upon registration, the main configuration page will show the authorized code in clear text since
it is not possible to use the same code on a different machine. The authorized code verifies the
MAC address of the network card seen by ZeroTruth as ETH00. 4 The code will be valid for any later
version of ZeroTruth when installed on the same machine.
1
Translations into newer languages and corrections to the currently supported ones are welcome!
2
such as Squid
, R Dansguardian
,R Gammu
andR the MultiCP module.
3
Beside making a donation via Paypal you can receive an activation code by adding the following link
”www.zerotruth.net” to your website and writing a little review or howto about ZeroTruth. Public schools, libraries, asso-
ciations etc can request an activation code for free.
4
If you happen to replace this card, the code won’t be valid any longer.
17
4.2 A DMIN
In this section you can change the credentials and other useful parameters of the system ad-
ministrator’s account (let’s understand this: the system administrator is you i.e. the person who’s
reading this guide and is setting up the Captive Portal).
• username
• password 5
• email
this email will be used to notify the system administrator about all sort of events and backups.
• phone number
for notifications via SMS
You can also choose which particular notification the system administrator will receive and by
which method (email vs SMS). 6 In this regard, a very useful notification which should always be
activated is when there is a reboot of the ZeroTruth machine so that you can immediately check
if the station is still operating normally after an unexpected shutdown or powercut.
Other notifications will be available with the installation of Gammu (Section4.28.2) which allows,
throughout the installation of a USB Key or phone, to let the system administrator know about
events even if the absence of the Internet connection.
5
The “glasses” icon allows the visualization of the password in clear text.
6
The email and/or SMS service must be configured and activated before you can select which notification to send
to the system administrator.
18
4.3 U SERS
From the “Users” configuration page it’s possible to add and to configure all other users especially
the managers (let’s understand this: managers are those special users who will have to run the
Captive Portal e.g. a Secretary). 7
Lots of different privileges can be assigned to each manager (only the administrator can do this!).
To assign some privileges to a certain user, therefore turning it into a manager, just click on the little
“pencil” icon on the corresponding row.
The privileges are mostly self-explanatory, here we list those that need a little explanation:
• Create Log
If enabled, the manager’s activities will be recorded in the system logs.
7
The limit of 6 managers has been removed from version 3.0 of ZeroTruth
8
The administrator can always change which user belongs to which manager. He can also assign any user to himself.
19
• Allow profiles usage
You can select which user profiles the manager will be able to assign for the registrations of the
Captive Portal.
• Deadline
The date beyond which the manager will have no more access to the system.
4.4 I MAGES
The ZeroTruth’s page logo can be replaced with another one but you must respect the logo’s size,
as shown in Figure 26. The second image that can be managed is the one that is displayed in the
header of each page of ZeroTruth and in the printing of the tickets (Section 4.16). The third image
that you can change is displayed in all access pages of the captive portal.
You must register ZeroTruth before you can change any of these images (Section 4).
20
4.5 A STERISK
Asterisk is a software implementation of a telephone private branch exchange (PBX); it allows at-
tached telephones to make calls to one another, and to connect to other telephone services,
such as the public switched telephone network (PSTN) and Voice over Internet Protocol (VoIP)
services.
If Asterisk is installed on ZeroShell, this page allows you to check its current configuration and
status of each registered “peer”.
From the GUI, you can view, edit and save Asterisk’s configuration files (“sip.conf ” and “exten-
sions.conf ”), together with the script (“zerotruth.sh”), for self-registration (Section 4.14).
21
4.6 LOG
Logs can be inspected and deleted from this page.
The page allows a check of the integrity of the database and reports any error. It is also possible
to repair the inconsistencies of the database via the link “Check and repair”.
22
4.8 K EYPAD
For those embedded devices, such as Alix or APU, which does not have the ability to manage
a keyboard and/or a monitor, it may be convenient to be able to give commands with a usb
numeric keypad.
To verify which “/dev/input” is connected to the keypad, it’s possible to type following commands:
23
To configure the correct mapping of the keypad keys, you can use the following command:
“/DB/apache2/cgi-bin/zerotruth/bin/configkeys”
What you see here are the system codes associated to my keypad keys.
Once the mapping is done (“Key.conf ” saved), you will be able to write your own scripts in order
to execute specific tasks upon recival of specific sequences of keys (codes) that you defined
yourselfi. The deamon which is listening for the codes must also be activated (Appendix D.1).
24
4.9 VSBS
From the “VSBS”tab you have acces to a very basic shell to control the system. Not all ZeroShell
commands are available in this basic shell but it is still very useful for intercating with the system
at low level. This utility can help in cases of remote connections or when you have problems
accessing ZeroShell.
4.10 E XPOR T
This utility allows you to export the users of the Caprive Portal in text or CSV format.
25
4.11 F ONT
In some cases, when the data entered in the user’s table of the Captive Portal screws up the
page layout, you can reduce (or increase) the size of the fonts (first two font entries). At the same
time you can also choose the size of the font used for printing the tickets of the users (last two
entries).
4.12 T EST
It’s possible to make tests on the hardware of the system and to the connection speed with differ-
ent Internet servers.
26
4.13 CAPTIVE P OR TAL
In this section you can find the steps to configure the Captive Portal.
1. Simultaneous connections
Simultaneous connections, that is the possibility for a user to simultaneously connect to different
devices, can be forbidden, permitted or deferred to the individual profiles. In the latter case
they will be managed and configured in each profile (Section 6), separately.
2. Authentication time limit
If the authentication popup window does not renew the request to remain connected to the
network (because it was closed, for example) then the client will be automatically discon-
nected after this time.
27
3. Global connections
In some cases it is possible that users connect to the Internet with too many connections, such
as using a torrent client, therefore saturating the node bandwidth. The administrator may want
to restrict this to a maximum number of connections after which the relative device is blocked
by the firewall.
4. Redirection choice
Redirection to the Captive Portal web interface is performed by using the default IP address of
the Captive Portal itself. Intead, you can either set the CN (“Common Name” of the cerificate),
or a specific URL, which can be useful for a SSL certificate of a SAN (Appendix A).
9. Online
Here we can decide if the Captive Portal is available to accept incoming connections or if it
will show an “out of service” error message.
28
13. Room name
For those situations where it is useful to have a meaningful name for the location of the Captive
Portal station, such as a school (class 3C) or a hotel (room 731), you can set it here. This name
can then be used in the user registrations and it will also appear in the tables of the users and
in the search form.
21. MB visualization
You can enable or disable the visualization of the total amount of network traffic generated
by the user. This figure will be expressed in megabyte (MB) inside in the user’s authentication
window of the Captive Portal.
29
25. Alert the user when the Internet is down
If you choose this option, in the case of absence of the Internet connection, the users are
notified. If the system uses a GMS Key and Gammu (Section 4.28.2), you can also set a notice
delivery via SMS to the system administrator.
29. Template
ZeroTruth provides a default user template which can be customized (Appendix B). Here you
can select the preferred template.
Self registration is one of the most important functions of ZeroTruth and by default is configured to
send the credentials via SMS and email. However, it can be configured in many different ways by
enforcing some limits and/or enabling additional features.
1. Enable Service
2. Select Profile
Users who will self-register from the Captive Portal’s main page will take the default settings from
the selected profile (Section 6).
30
3. Asterisk Registration
ZeroTruth allows to self-register using an Asterisk PBX server. For its configuration, please refer to
Section 4.14.1.
9. From Ticket
You can configure ZeroTruth so that it accepts self-registrations only from users who have re-
ceived a valid ticket, with a preset username (Section 9.4.5).
11. Deadline
You can set the date after which the user’s account will be labeled as “expired” and will no
longer be able to connect. Alternatively, it is possible to set the expiration date in a number of
days after the first authentication.
14. Days
The maximum number of days granted to the user is displayed according to the chosen profile.
31
4.14.1 R EGISTRATION WITH A STERISK
ZeroTruth allows to self-register in different ways. In order to have a certain level of reliability over
the user’s identity, ZeroTruth, by default, sends the credentials, via SMS or email, directly to the
corresponding user. By doing so, the system administrator (or manager) can verify that the user
has provided correct information, or at least try to trace back the user’s identity via the contract
signed with the telephone company, in case of fraud.
Text messages to the users can be sent via a web service (already integrated into ZeroTruth),
via a USB key or phone, or using a GSM gatewey (which can become quickly expensive if hun-
dreds or thousands of users are served by the Captive Portal).
Since version 2.1, ZeroTruth allows you to have the same degree of reliability in the manage-
ment of the self-registrations and password recoveries, using an Asterisk PBX server. This is a cost
effective solution to verify the authenticity of the users (no additional costs are charged for the
management of the Captive Portal).
2. choose a password (this password will be used by Asterisk to communicate with ZeroTruth in a
secure way),
3. set the time limit (granted to the user) for activating the registration (after this amount of time,
in hours, the user will be removed from the system),
4. set the phone number a user must call to activate the registration,
5. set the phone number a user must call to retrieve the password. 9
9
These two phone numbers can be set to the same phone number.
32
A STERISK C ONFIGURATION
The addon 40600 of ZeroShell allows you to install Asterisk 13.3.2. Asterisk, among the many fea-
tures it has, lets you run Asterisk scripts (agi-bin) upon the commands received from the caller.
To enable this feature, it’s sufficient to edit the configuration file “extensions.conf ” where you can
define which script has to be executed based on the received command associated to a par-
ticular phone number (by calling a specific phone number, a particular action or agi-bin script
execution, can be carried out by the Asterisk server).
You may also want to use an Asterisk server installed on a different machine. In this case, the
Asterisk server must be able to communicate with the ZeroTruth station over some network (LAN,
WAN, VPN etc.).
If Asterisk interacts with a single ZeroTruth station, then we can configure it to execute the cor-
responding command even without answering the phone call initiated by the caller (the user
calling for self-registration activation or password recovery won’t be charged for that because
he will hear a single ring after which the phone call will be ended by the server). In this case it’s
necessary to edit the “extensions.conf ” file located in “/opt/asterisk/etc/asterisk/ ” and place our
agi-bin script in “/opt/asterisk/var/lib/asterisk/agi-bin/ ” as follows:
Figure 41: Asterisk configuration and the script to unlock the user
Please note that the user will be enabled only if he will call the Asterisk server using the phone
number he provided during the self-registration. Because the user won’t receive any formal con-
firmation over the phone call, a notification will be sent to him.
If you want the user to receive a vocal confirmation over the phone (we can use the googletts-agi
scripts to read text messages), then the correspondig configuration is as follow:
Figure 42: Asterisk configuration and the script to unlock the user
33
If the Asterisk server will communicate with multiple ZeroTruth stations, then you can proceed as in
the following example:
Figure 43: Asterisk configuration and the script to unlock the user
To each ZeroTruth station is assigned a unique code (“xxx”, “yyy”, ...“zzz”) which must be also
used by the user.
If different phone numbers are used for self-registration activation and password recovery, then,
for the password recovery you can use the same configuration but you must change the corre-
sponding command script as follow:
Figure 44: Asterisk configuration and the script to unlock the user
If the Asterisk server is installed on the ZeroTruth machine, then all the configurations cab be exe-
cuted directly from the ZeroTruth GUI (Section 4.5).
If you use Gammu as SMS service (Section 4.28.2), then you will find the corresponding option in
the self-registration configuration as “Allow full registration via SMS”.
This is the fastest method for the user to get registered (Section 9.4.4).
34
4.14.3 R EGISTRATION WITH T ICKET
The self-registration with (pre-printed) Ticket is the third and last available option:
tick the checkbox “via Ticket” and then read Section 9.4.5.
4.15 N OTICES
In this page you can enter the various alert messages to the users.
Each field is used to enter the messages that will be used by the system in the different pages and
functions of ZeroTruth.
35
4.16 T ICKET
This page allows you to decide what to print on the tickets for the users.
Print options are: the QR code, only the QR code, date of creation, name if anonymous, profile
and expiring date. All these options are there to let you minimize the waste of paper when print-
ing several tickets at once.
36
4.17 PAY PAL
ZeroTruth allows you to create connection profiles which require a prepayment for the MB or hours
of use. The accumulated credit will allow the registered users to use the service until the corre-
sponding quota (in MB or minutes) is used. The payment functionality via PayPal was introduced
in version 1.0.beta2 of ZeroTruth. PayPal allows payment by credit card and instant notification of
accreditation (IPN).
To let the user have access to the PayPal web site during the self-registration, we must open the
firewall of the Captive Portal. PayPal does not have a range of fixed IPs, therefore it is not possible
to allow exclusive access to the registering user to any particular set of IP addresses. Instead, we
should only allow the connections to the PayPal web site that use the https protocol. We will also
enforce two more restrictions upon the user, such as the maximum number of attempts the user
can try a self-registration, and a time window (in seconds) the firewall will stay open allowing https
connections to PayPal. If the self-registration is not completed successfully either because of too
many attempts or because the connection time window to PayPal has expired, the user will be
inevitably locked out of the system.
In this form you can define the parameters for PayPal. Make also sure you have selected the
“PrePaid” profile for the self-registration (Section 4.14).
• the number of seconds that the firewall will allow https connections,
• the Time Zone (Italy’s GMT = +1), as the PayPal IPN uses a different one.
37
If a user is blocked, due to the excessive number of attempts, the administrator can unlock it by
choosing the corresponding MAC address in the “Free MAC” field.
IMPORTANT:
Because PayPal sends the IPN only through port 80 or 443, then you must redirect the selected
port to port 8088 of your ZeroTruth station.
After you have logged into your PayPal account, click on “Summary” and then “Seller prefer-
ences”.
You will be prompted with the following page in which you can set the needed configuration we
discussed above.
38
1. PAYPAL BUTTON
First you will have to create the PayPal button code to be pasted into the previous form, see
Figure 50).
Now copy and paste the code into the corresponding form, as shown in Figure 50.
2. AUTOMATIC RETURN
Insert this URL at the bottom of the form “http://yy.yy.yy.yy:8088/cgi-bin/register.sh” where “yy.yy.yy.yy”
represents the public IP address of the Captive Portal.
39
3. IPN
Insert this URL in the middle of the form “http://yy.yy.yy.yy/cgi-bin/controlpp.sh” where “yy.yy.yy.yy”
represents the public IP address of some router which, in turn, will forward the incoming IPN mes-
sages from PayPal to the Captive Portal’s public IP address on port 8088.
At this point, if you have selected a prepaid profile in the Captive Portal’s configuration and you
have activated the PayPal functionality, then, in the authentication page you will see an addi-
tional link labeled as “Recharge Cridit”.
This is the link from which the user can recharge its credit at anytime.
40
After the user enter his credentials, he will be able to choose the amount of the payment (from
the scroll-down menu) and proceed with the payment itself by clicking on the “Pay now” button
(generated by our PayPal button code).
After the credit purchase, the user will receive a notification of the payment. The available credit
will be also shown right abobe the “Close” button.
The user can follow the exact same procedure also in the case of self-registration. Once authenti-
cated, the user can increase its credit using the link that will appear in the pop-up authentication
window.
The received payments are not only stored in your PayPal account but also in the “Payments”
section of ZeroTruth (Section 6.4).
41
If a user does not successfully complete a self-registration (number of allowed attemps) or runs out
of time (Figure 50), he will be locked out of the system and notified with the following message.
4.18 PAYMENTS
In this page you can visualize and mage the payments received via PayPal or directly from the
user (cash).
You can sort the payments in alphabetical order (username), delete them or show only the pay-
ments corresponding to a particular user by clicking its username.
42
Figure 64: Single user payments
Some clients or services may require to not be intercepted by the Captive Portal i.e. to have direct
access to the Internet. Conversely, in other situations they may require to be entirely disconnected
from it. In this page you can manage this kind of situations.
To force the Captive Portal to not intercept a particular client, you can add its MAC or IP address
to the list of free clients. To force the Captive Portal to not intercept a particular service, you can
add its IP address, or port number or protocol name to the list of free services. To force the Captive
Portal to block a particular client, you can add its MAC address to the list of blocked MACs.
43
4.20 WALLED G ARDEN
On the Internet, a walled garden is an environment that controls the user’s access to web content
and services. In effect, the walled garden directs the user’s navigation within particular areas, to
allow access to a selection of material, or prevent access to other material. You may want to
fence in users for a several number of reasons but the one we are more interesed in is to let the
unauthenticated user have acces to some amount of information before setting up an account.
ZeroTruth allows an internal (local) and an external (via a remote server) Walled Garden.
The administrator can customize the Walled Garden page by inserting some text and images
using the GUI. The Walled Garden page can be freely modified with the only exception of the
embedded javascript functions. At the bottom of the configuration page there is also a little
preview window which allows the administrator to visualize the final look of the Walled Garden
page.
44
4.20.2 E XTERNAL WALLED G ARDEN
To set a remote Walled Garden you must fill in all the necessary fields, as shown in Figure 67. The
“Check” button will let you test the final result i.e. it will confine your browser (a new window will
popup) within the pages of the remote web bebsite, only.
45
4.21 P OPUP
The Popup configuration page allows the creation of a popup window which opens up automat-
ically in the browser of the client user. Just like the Walled Garden, the popup window can display
either a local page or a remote site. Its purpose is to advertise or give useful information about
something such as the location of the captive portal, the reason why it’s there, who’s responsible
for it, what are the rules etc. From this page you can also enable or disable the service, select
when the popup will be displayed in the user’s browser (login, authentication renewal or many
times), force the user to enable the popup visualization in his browser and define the popup win-
dow size. The “Check” button will generate a preview window of the popup so that you can
check the final result.
46
4.22 L OGIN I MAGES
Before the user can actually login, you can select one or more images to be displayed in the
user’s browser.
The images you want the user to see must be uploaded first. Once that is done, you can define
how to display them (sequence or random) and for how long each image will be displayed.
This method is far less intrusive than the popup window therefore it may be the preferred method,
depending on your needs.
47
4.23 FACEBOOK L IKE
You can let the users choose between being constantly annoyed by the popup window or to
leave a Like page on Facebook, thus disabling the popups asking for it.
First of all you need to get the “Plugin Code”, from the Facebook developers site (https://developers.faceb
following these steps:
48
On ZeroTruth, it is sufficient to adjust the code of the following script.
1. appId : ”XXXXXXXXXXXXXX”,
replace all the Xs with the assiged ID,
3. data-href=”https://developers.facebook.com/docs/plugins”
replace the address with the one of the page you want to assign the Like.
49
4.24 P ROXY
ZeroTruth allows you to use Squid together with Havp-ClamAV (a free antivirus software) and Dans-
Guardian (a free content filtering software). The proxy activation may take more than a minute
to complete therefore don’t get nervous too quickly if you see nothing happening on the screen
for a while... just be patient for a couple of minutes and, from time to time, refresh the page to
check if the proxy service becomes operative. The proxy configuration must be carry out directly
from the GUI of ZeroTruth. In fact, both Squid and DansGuardian (eventually) must be installed
from the GUI because they are not compatible with the verions of the same programs provided
by ZeroShell.
50
4.24.1 S QUID
Squid is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth
and improves response times by caching and reusing frequently-requested web pages. Squid has
extensive access controls and makes a great server accelerator. It is therefore extremely useful
in those situations in which the Internet bandwidth may saturate very quickly such as for schools,
libraries etc.
From the ZeroTruth’s GUI you can only configure the most important features of Squid. One of
these features is recording the connections activity directly into the logging mechanism od Ze-
roTruth. Please be aware that this functionality may be against the privacy law when not commu-
nicated and accepted by users.
4.24.2 DANSGUARDIAN
DansGuardian is an Open Source web content filter which can extend the functionalities of a
proxy server, such as Squid. 10 It filters the actual content of pages based on many methods
including phrase matching, PICS filtering and URL filtering. It does not purely filter based on a
banned list of sites like other filters. DansGuardian is designed to be completely flexible and al-
lows you to tailor the filtering to your exact needs. It can be as draconian or as unobstructive as
you want. The default settings are geared towards what a primary school might want but Dans-
Guardian puts you in control of what you want to block.
From the ZeroTruth’s GUI you can only configure the level of filtering (“Filter Level”) making it more
selective towards lower values of it. Please do some tests before enabling this service permanently.
ZeroTruth makes us of Havp (HTTP Anti Virus Proxy) and ClamAV (antivirus engine for detecting
trojans, viruses, malware and other malicious threats) as its default antivirus software tools. Please
refer to ZeroShell documentation for its configuration (Transparent Web Proxy with Antivirus Check
and URL Blacklisting).
10
Dansguardian must be activated along with Squid and/or HAVP
51
4.25 S HAPER
ZeroTruth provides a “shaper” which is a tool that allows the restriction of the traffic, going through
a specific network interface, by direct interaction with the Linux kernel. To make it easier to use
traffic shaping, ZeroTruth makes use of the excellent CBQ.init script.
When the service is active, different bandwidth limits can be defined for each profile (Section
6). The current statust of the shaper is also reported in the configuration section of ZeroTruth, as
shown in Figure 77.
52
4.26 B LOCKER
ZeroTruth allows you to activate and manage a fencing mechanism against intrusion attempts
and unwanted ads.
4.26.1 IP B LOCKER
In the Blocker section you can set a maximum number of failed attempts to access the administra-
tor’s GUI or SSH connections, after which the IP address of the malicious machine will be blocked.
Conversely, you can flag a certain IP address as trusted therefore shielding it from the fencing
mechanism.
4.26.2 AD B LOCKER
In the second part of the section is possible to activate and update an AD Blocker for a list of
unwanted sites. The update of the list can be done manually or automatically on a daily, weekly
or monthly basis.
53
4.27 E MAIL
ZeroTruth email service relies upon the presence of an external SMTP mail server to send messages.
By default, ZeroTruth is configured to use Gmail as its relay server. An open mail relay, such as Gmail
relay server, is an SMTP server configured in such a way that it allows anyone on the Internet to
send e-mail through it, not just mail destined to or originating from known users. If you will proceed
using Gmail relay server, just insert your (gmail) email address and password leaving all other fields
untouched.
This form also allows you to enter some text for both the email’s header and footer. If you do not
want the users to receive any automatic email from the system (such as during self-registration
etc.) you must untick the “User Notifications” checkbox. Bare in mind that the email service is
extremely important for the backup of the system and for the system administrator’s notifications.
54
4.28 SMS
Just like the email service, the SMS service relies upon an external SMS send and receive service
which is offered by several providers.
ZeroTruth is already configured to use some of the most known and reliable services on the net-
work:
• Skebby
• Mobyt
• Smsglobal
• Aimon
• Subitosms
• Smsbiz
It is possible to visualize both the remaining credit and number of available SMS if the selected
provider supports these features. ZeroTruth makes extensive use of text messagges (for instance,
user self-registration, unless Asterisk is installed), therefore it is a very important that this service is
working properly.
• Password recovery
• Users notifications
• Administrator notifications
There is also the option to use your own GSM Gateway, GSM Key or USB phone to be completely
independent from the Internet, especially in cases of loss of connectivity.
55
4.28.1 MY SMS SCRIPT
If you want to use a customized SMS service then it’s possible to use the “my SMS script” function.
You can customize the script directly from the GUI (please note that there are several commented
out variables which you can freely use).
56
4.28.2 G AMMU
If you want to use your own USB Key or GSM phone, ZeroTruth relies upon the support of “Gammu”.
Gammu is the name of the project as well as the name of a command line utility which you
can use to control your phone. Gammu command line utility provides access to wide range of
phone features, however support level differs from phone to phone and you might want to check
“Gammu Phone Database” for user experiences with different phones.
To properly configure the device, please refer to the tables on the web site of Gammu, in par-
ticular, make sure to use the correct parameter for the connection (at19200 in my case). If you
have only one usb device connected to the ZeroTruth station then the correct usb port should
be “/dev/ttyUSB0” If you are not sure, please use the “lsusb” and/or “dmesg” tool to discover the
correct mapping of your device into the device folder. If the configuration is successful, the page
should return the correct device and status (green tick in the middle of the page).
The latter feature can therefore be used, in conjuntion with Asterisk installation and configuration
(Section 4.14.1), to make the system execute specific commands.
57
4.29 M ULTI CP
ZeroTruth allows administrators to manage multiple remote Captive Portals as if they were just one.
This is one of the most interesting feautures of ZeroTruth which allows one ZeroTruth staion (desig-
nated as server) to work together with one or more ZeroTruth clients as if they were just a single
Captive Portal. The only difference is that each station (server included) will actually have its own
local connection to the Internet therefore, the ZeroTruth stations will not be sharing a single Inter-
net connection.
We refer to this setup as Multi Captive Portal or MultiCP where the management of all the Ze-
roTruth clients will take place on the ZeroTruth server station.
Please refer to this guide for a complete description of the MultiCP installation, configuration and
management.
58
4.30 B ACKUP
Backups have two distinct purposes. The primary purpose is to recover data after its loss, be it by
data deletion or corruption. The secondary purpose of backups is to recover data from an earlier
time, according to a pre-defined data retention policy.
ZeroTruth allows immediate (manual) Backups or automatic Backups on a daily, weekly or monthly
basis. 11 After each Backup you can choose to delete/clear from the system both the list of re-
moved users (removal from the internal database) and/or the system logs. 12
Sending Backups directly via email does not require any other type of configuration. It’s very easy,
very practical and it can turn out to be the most convenient solution for small systems. Backup
files will be sent in “tgz” format.
Sending backups to a remote FTP server requires, of course, to have an account on it, therefore,
just enter your credentials in the approprite fields.
11
Daily Backups: every day at 1 AM; Weekly Backups: every Monday at 1 AM; Monthly Backups: every 1st day of the
month at 1 AM.
12
Removed users are cleared from the database and stored in a particular folder, therefore users accounting data is
never lost.
59
4.30.3 B ACKUP WITH D ROP B OX
Onother option offered by ZeroTruth in terms of back up methods is Dropbox. If you plan to use this
option then you need to write and register a backup-interface appllication, between ZeroTruth
and Dropbox, on “https://www.dropbox.com/developers/apps”.
Secure copy or SCP is a means of securely transferring computer files between a local host and
a remote host. SCP uses Secure Shell (SSH) for data transfer and uses the same mechanisms
for authentication, thereby ensuring the authenticity and confidentiality of the data in transit.
There are several ways to use SSH but the one we are interested in (ZeroTruth SCP Backups) uses
a manually generated public-private key pair to perform the authentication, allowing users or
programs to log in without having to specify a password. In our scenario, the public key will be
placed in some user account on the remote backup host. Doing so, the owner of the matching
private key (root user of our ZeroTruth station) will be able to initiate SCP sessions (transfer files) with
the remote backup host, withount being asked for the user password of the remote account.
To enable the SCP backup mechanism, tick the “SCP” checkbox. To retrieve the public key for the
user account on the remote host, click on the “SSH Key” link. Now you should open up a terminal
window, log into the remote host using the corresponding user credentials and append the public
key to the end of the following file: “/home/REMOTE USER/.ssh/authorized keys”. 13 If the “.ssh”
folder is not present then create it with the following command: “mkdir ˜/.ssh ; chmod 700 ˜/.ssh”.
If the “authorized keys” file is not present then just create one. You must pay extreme attention to
the fact that the public key is a quite long sequence of characters all on a single line! Therefore,
if you are doing a copy and paste of that line, make sure it does not get split over multiple lines.
Once that is done, on the ZeroTruth station you must open the Shell of ZeroShell (root account
of ZeroShell/ZeroTruth station) and log into the remote user account using the ssh command, at
least one time. When you will be prompetd if you are sure you want to continue connecting,
answer yes! This last step is very important because it will modify the “/root/.ssh/authorized keys”
of the root account of your ZeroTruth station labeling the remote host as trusted. In fact, if you
now logout from the remote account and then login again, no questions will be prompted to you
(and no password request either). At this point, the SCP red cross should be a green tick mark.
13
REMOTE USER must be replaced with the correct username.
60
To make this whole process (public key installation over the remote server) somewhat easier, you
can edit and run the following script from the shell of ZeroShell:
“/DB/apache2/cgi-bin/zerotruth/scripts/ssh-copy-id”
Please remember to edit that script first. In fact, you must provide the IP address and username of
the remote server and account. You can double ckeck that the script was successful by refreshing
the Backup page of ZeroTruth: a green tick mark should be present intead of a red cross. 14
Cliccking the “Check Backups” button allows you to visualize, remove, download and restore
previous backups.
14
Every time the Backup page is opened or refreshed, the system tries to send over the remote host a test file. If the
test file is transferred successfully then the system turns the red cross into a green tick mark.
61
4.30.5 R ESTORE B ACKUP
Previous backups can be restored at anytime. If you are using any of the allowed methods but
SCP, then you must download the corresponding “backup-number.tgz” file, fisrt. Once the backup
file is downloaded somewhere on your system you can proceed with its upload and finally select
what part of it (if not all parts) should be restored on the system. 15 ,
,
Figure 92: Upload backup
If you are using the SCP method, then you can restore any backup direclty from the backups list,
as we have seen in Section 4.30.4 (icon with little circular arrow). In this case there is no need
to first download and then upload the backup archive file (everything is done automatically via
SCP).
After restoring a backup, you can check what has been actually done by the system from the
backup results page.
15
Currently it is not possible to restore backups from mismatching versions of ZeroTruth. This limitation may be removed
in future releases of ZeroTruth.
62
4.31 D ISK CAPACITY
Disk space does matter especially when Zerotruth is installed on small flash drives, for example. In
the “Disk” section of Zerotruth you can check how much space is left on the disk.
You can also select to be notified (via email or SMS) if the remaining disk space falls below a
certain value. In order to save disk space, you can also force Zerotruth to erase the system logs,
which can take up several megabytes.
4.32 G RAPHS
Zerotruth provides real-time graphs to check the current usage of several resources such as CPU,
Memory, Network and Captive Portal.
63
Memory real-time graph:
The graphs relative to the Captive Portal are updated each day at midnight. They report the
usage of the Captive Portal in terms of both connection hours and network traffic in MB. If you
need to generate the current graphs for such parameters, please click the “Update” button.
64
Figure 100: Monthly view of Captive Portal usage
65
Figure 103: Top-ten users view of Captive Portal usage
To have better control over the time window used for the generation of the graphs, you can define
the time window size and location as you like it (Figure 104).
66
4.33 U PGRADES
Newer releases of ZeroTruth can be easily installed from this page.
ZeroTruth upgrades can be either installed manually or automatically. In case they are installed
automatically, you can be notified via email when each upgrade has occurred.
Once an upgrade is performed either manually or automatically, the status of the last upgrade is
reported in the status column. Independently from the ZeroTruth Upgrades policy, the system will
check on a daily basis (at a random time over 24 hours) for the presence of an upgrade. If there
is one available upgrade and the preferred method is manual installation, then a little red dot will
be shown on top of both the “Config” and “Upgrade” buttons, as shown in Figures 107 and 108,
respectively.
If you are upgrading from version 2.1 to version 3.0 of ZeroTruth, then you cannot use the GUI. For
this upgrade you must use the shell of ZeroShell and perform a ZeroTruth installation (Section 3).
67
5 U SERS M ANAGEMENT
The view and management of the users is possible from the “Users List” page and “Add User”
page, correspondingly.
5.1 A DD U SER
We have already seen in Section 4.14 that ZeroTruth allows self-registration but there are actually
four more ways in which users can be added to the system.
A single user can be added to the system by specifying the following parameters.
1. The value of the “Username” field is automatically proposed but you can change it as you
want.
2. The value of the “Password” field is automatically proposed but you can change it as you want
(click the glasses icon to reveal the password).
3. The value of the “Name” field is mandatory unless you have enabled the “Allow anonymous
users” option in the Captive Portal configuration section (Figure 37).
4. The value of the “Family Name” field is mandatory unless you have enabled the “Allow anony-
mous users” option in the Captive Portal configuration section (Figure 37).
6. The value of the “Phone” field is optional. If present, do not insert the leading plus sign or zeroes.
7. The value of the “Profile” field is mandatory. The default profile is “DEFAULT ” which enforces no
limits upon the user.
8. The value of the “Int” field shows on which network interface the selected profile is active.
This field cannot be modified from here. You can change the value of this value following the
instructions in Section 6.
9. The value of the “Hide” field is set to No by default. In this way the user can be seen and
therefore managed by the managers of the Captive Portal. Vice versa, only the administrator
will be able to manage the user.
68
10. The values of the “Expiry date” fields do set the expiry date of the user’s account. If these fileds
are left blank, then the expiry date is set to infinity.
11. The expiry date can also be defined as the number of “Days” after the first user’s authentica-
tion.
12. If you have selected a prepaid profile, here you can set the initial “Credit”.
13. The values of the “Limits” fields are used to set the maximum hours per day and/or per month
the user is allowed to be logged in.
14. Same as above but with limits in megabytes.
15. Only in these “Days” the user can log in.
16. Only in these two “Time windows” the user can log in.
17. It is possible to enable and print the “Ticket” for the user in the selected language (Section
4.16).
18. Upon completion of the user’s registration you can choose to notify the corresponding user via
email or SMS. Make sure you’ve entered either the email address and/or user phone number
but also configured/activated the corresponding email/SMS services (Sections 4.27, 4.28).
19. Sometimes it’s useful to have a “Note” about the user.
ZeroTruth allows you to add multiple users in one go, if necessary. From the “Add User” page
select “Multi” link.
69
5.1.3 A DD USERS FROM FILE
A list of users can be added using a simple text file (“From File” link in “Add User” page). The
format of each line of the text file is composed of the following comma-separated fields:
“username,password,name,surname,email,phone”
As soon as the file is uploaded, the format is checked and the number of users being added is
displayed. For all users you can then set the profile, expiry date etc. but keep in mind that these
values will be applied to all users, indistinctly.
70
5.1.4 A DD U SERS B OUND TO T ICKETS
If in the self-registration configuration (Section 4.14) the “From Ticket” option is enabled, then a
third link will appear in the “Add user” page. From this link, also called “From Ticket”, it is possible
to specify how many users you want to add. Please remember that these users will be the oly ones
allowed to self-register on the Captive Portal.
In the next Section 5.2.2 we will see how to manage the users bound to tickets.
71
5.2 U SERS L IST
The users table is displayed either in the standard (normal) or fast mode depending on your Cap-
tive Portal’s configuration (Section 4.13). In particular, if you have enabled the “Enable fast user
table” option then the users table will be displayed in a more compact form leaving out the less
relevant information about the users.
The standard table lets you visualize and manage most of the parameters or aspects associated
to each user.
1. This column reports a progressive number linked to each user on the system. If you click on any
of these numbers then you will be redirected to the corresponding full user’s table from which
you can modify any paramemter associated to the user.
72
2. This column reports the the total number of session initiated by each user. If you click on any of
these numbers then you will be redirected to a detailed list of all sessions for the corresponding
user.
3. This column shows if a certain user is considered as valid or invalid by the system. A user is
considered as invalid when its account has expired or when the user has burned out all the
allowed hours, megabytes or credit.
4. This column shows if, to certain user, is associated some extra information or notes. By clicking
on the corresponfding icon you can take vision of such notes. These notes were either added
by the system administrator (or some manager) or by the system itself indicating, for example,
if the user has sef-registerd or has not yet completd the registration procedure (registartion with
Asterisk).
5. By clicking on the corresponding red cross icon you can erase the user from the system’s
database.
6. This column shows if a certain user is currently connected to the Captive Portal. In case the
corresponding icon shows a little red dot on it, then it means that the user is currently logged in
using multiple devices e.g. a tablet and a laptop. 16 .
If you click the corresponfding icon then the user will be disconnected from the Captive Portal
on all its devices. If you want to disconnect the user from the Captive Portal but only on one or
more devices then you must click the corresponing link (number) in the second column.
To disconnect the user on a certain device click the “Active” link as shown in Figure 123.
16
The red dot can only show up if the multiple connections option is enabled in the profile of the user
73
7. This column shows if a certain user is currently blocked or not. In case the corresponding icon
shows a red locket, then it means that the user is currently blocked (or locked). Users can get
blocked by the system for several reasons such as daily or montly limits (MB/hours per day or
per month) and time windows specification. The system automatically locks and unlocks users
based on these criteria but you can manually lock and unlock any user at any time.
8. The little pencil icon takes you to the user management page from which you can adjust, add
or modify several parameters.
The form in Figure 124 is identical to the one you get to when you add a new user. From
this form you can apply all necessary changes including printing a new ticket and notify the
corresponding user.
If in Section 4.14 you have enabled the “From Ticket” option then in the “Users List” page you will
see an additional link named “Waiting Users”. These are the users who have not yet used their
ticket to self-register.
Despite that, you can lock, unlock, remove or add new users and print their tickets.
74
5.2.3 R ICERCA UTENTI
In the “Users List” page there is also a “Search” button which can be used to query the system
database.
Any search through the database con be carried out using one or more of the fields proposed in
Figure 128. Here below is an example of what a search result may look like. Several actions can
be performed either on a single user or on a group of selected users.
• Erase
I remind you that erased users are only removed from the database and not from the system
itself. In this way you can still retrieve informations about these users and do your own checks.
• Disconnect
This action will disconnect the selected users from the Captive Portal.
• Lock
This action will first disconnect the selected users from the Captive Portal and then lock them.
75
• Unlock
This action will unlock the selected users.
• Hide
This action will hide the selected users from the managers making them manageble only for the
system administrator.
• Unhide
This action will reveal the selected users to the managers making them able to have control
over their configurations.
• Backup Sessions
This action will immediately backup the sessions of the selected users.
• Erase Sessions
This action will immediately erase the sessions of the selected users. It is highly recommended
to backup the users sessions before running this action.
• Change Profile
This action will change the profile of the selected users.
• Change Manager
This action will change the current manager of the selected users.
• Print Ticket
This action will print the tickets of the selected users.
The users table is displayed either in the standard (normal) or fast mode depending on your Cap-
tive Portal’s configuration (Section 4.13). In particular, if you have enabled the “Enable fast user
table” option then the users table will be displayed in a more compact form leaving out the less
relevant information about the users.
The Figure here below shows how the fast table will look like:
You can revert it back to the standard table by clicking the “Full View” button.
76
6 P ROFILES
Every single user in the system is associated to a profile. The only exception is the system adminis-
tratori, but that’s a different user, which can do anything he wants on the system.
Profiles can be added (created), modified or erased from the system. The only exception is the
“DEFAULT ” profile which cannot be modified or erased. The “DEFAULT ” profile carries no limita-
tions. If any other profile is erased then all users belonging to it will be automatically re-assigned
to the “DEFAULT ” profile.
The “Simultaneous connections” field will only be available if in the Captive Portal’s configuration
(Section 4.13) the very same option was enabled. Therefore, it is up to each profile the ultimate
decision about this option.
77
6.2 A DD P ROFILE
The “Add Profile” button at the bottom of Figure 131 will take you to this form.
Each profile defines a different set of rules (or limitations) to be enforced upon the users belonging
to that specific profile. For example, in a school you can define a different profile for teachers,
students, staff members and guests. The “Simultaneous connections” field will only be available if
in the Captive Portal’s configuration (Section 4.13) the very same option was enabled.
If you set the payment method to Prepaid then you can define a certain amount of time, called
“Free time” (in minutes, see Figure 134), during which the user can charge its credit balance
either via PayPal (if enabled) or directly to the cash. In the latter case, the sytem administrator or
manager of the Captive Portal will have to update the user’s table in the system by registering the
payment (Section 6.4).
78
6.4 P ROFILE WITH BANDWIDTH LIMITS
If the Shaper is enabled (Section 4.25) then it will be possible to define both donwnload and up-
load bandwidth limits in the profile form (Figures 132, 135). Bandwidth limits can also be assigned
per user. To do that, select “User” instead of “Profile” in the Type scroll-down menu.
When the Captive Portal is active on multiple interfaces you can select on which of them the
profile will also be active. This feature is very useful because it will restrict the access, to all the
users belonging to a specific profile, to the selected intefaces for that profile.
As a simple example think of a school for which you have defined two different profiles called
Student and Teacher. Suppose also you have access to two separate networks such as a wired
network connected to ETH00 and a wireless network connected to WLAN00. In the Student profile
you then select ETH00 only while in the Teacher profile you select both ETH00 and WLAN00. Doing
so, students will only be able to use the Captive Portal when connected to the wired network (a
computer lab, for example) while the professors will be able to use also their tablets or laptops.
The page listing all profiles will report very clearly to which interfaces each profile is active on
(Figure 137).
79
7 E MAIL
The Captive Portal can automatically send emails to the users in order to notify them about their
activities on the Captive Portal such as self-registration, credentials, credit balance etc. But there
are other situations in which the system administrator or a manager may need to contact the
users. Simple examples could be to inform the users about some maintenance of the Captive
Portal or to send Christmas greetings or to invite few user to a particular event like a social dinner
or a conference etc.
First thing to do is to find the users to which we would like to send the email. Obviously, only the
user with a registered email address will be scanned during the search.
Once you get them listed in the table shown in Figure 139, you can select who will receive the
email by ticking the corresponding checkbox (second column from the left). Right below the list
of users you can insert both the email subject and body. By default each email will also contain a
predefined header and footer (Section 4.27). All sent emails will be stored by the system for later
search, inspection and removal, eventually.
80
8 SMS
The Captive Portal can automatically send text messages (SMS) to the users in order to notify them
about their activities on the Captive Portal such as self-registration, credentials, credit balance
etc. If the system is configured to use text messagesi, then you can use this service to text the
users, manually.
Once you get them listed in the table shown in Figure 141, you can select who will receive the
SMS by ticking the corresponding checkbox (second column from the left). Right below the list of
users you can insert both the SMS body (max 160 chars). On top of the page you can also see the
remaining credit followed by the corresponing number of SMS you can still send. 17 All sent SMS
will be stored by the system for later search, inspection and removal, eventually.
17
This visualization is not always possible. It dependes from your SMS provider.
81
9 CAPTIVE P OR TAL U SAGE
From Wikipedia: “A Captive Portal is a special web page that is shown before using the Internet
normally. The portal is often used to present a login page. This is done by intercepting most
packets, regardless of address or port, until the user opens a browser and tries to access the web.
At that time the browser is redirected to a web page which may require authentication and/or
payment, or simply display an acceptable use policy and require the user to agree.”
The layout of the login page may depend on the device used for the connction. On a laptop,
for example, it should look like in Figure 142. The default language can be configured in Section
4 (Figure 22) but the user can change it by clicking on the corresponding flag icon. The selected
language will be used in any subsequent page and notification.
82
In the login page, the user can also take view of the Captive Portal policies or general informa-
tions, configured in Section 4.15 (“Informations” text area in Figure 47), by clicking the “Info” link.
Once the user is logged in using its credentials, the system will present the authentication popup
window in which are reported several parameters related to the user account (credit balance,
change password, etc.) and to the connection (device IP address, elapsed time, etc.).
The system administrator or manager can actually disable some of the informations (Figure 145)
reported in the authentication popup window, as described in Section 4.13.
83
The authentication popup window shown in Figures 144 and 145 is the default one i.e. the one
provided by ZeroShell. If you want, you can use the authentication popup window provided
by ZeroTruth which is more verbose and provides more functions (Figures 146, 147). Especially,
it informs the user when the device is about to be disconnected due to traffic, time or credit
balance limits/quota (Figure 147). If the user closes the authentication popup window then the
network connection is cut shortly after (“Authentication time limit” option in Figure 37).
Figure 147: ZeroTruth authentication popup with time/MB left warning message before network cut
ZeroTruth authentication popup can be enabled in the Captive Portal configuration (“ZeroTruth
authentication popup” option in Figure 37). Mobile devices may have troubles with popup win-
dows therefore, in the Captive Portal configuration you can enable the “Mobile device page”
option (Figure 37). With this option enabled, the mobile device will not try to display any popup
window. Instead, it will open a new (authentication) page in the browser (Figure 148). If the au-
thentication page is closed then the network connection is cut shortly after (“Authentication time
limit for mobile device page” option in Figure 37).
84
9.1.2 O PEN L OGIN
If in the configuration of the Captive Portal (Section 4.13) the option “open service” is set, then
the users will be able to access the Internet without entering any credential and, therefore, very
quickly. The only thing they have to do when they connect for the first time to the Captive Portal
is to read and accept the proposed agreement, as shown in Figure 149.
From the second connection on, they will only have to click on the big blue login button in order
to be authenticated, as shown in Figure 150.
From the open Login page, the users can also remove their accounts at any time. As always, the
system will first backup and then remove the users from the internal database only. Thus, login
sessions, users data, logs etc. won’t be lost and will still be available for later inspections.
85
9.1.3 L OGIN WITH QR CODE
Tickets with QR codes printed on them (Section 4.16) do represent a very quick way to get ac-
cess to the Internet for those devices that have a QR code scan-application installed, such as
smatrphones and tablets.
The email service of the system must be enabled to accomplish this task. In fact, the system will
send to the user a confirmation email with a secret code in it. The user will then have to copy and
paste the secret code into the confirmation window, as shown in Figure 152.
Obvoiusly, the user must also have been registered with an email address otherwise he will not be
able to ever confirm the password change. The user can also change the password if the system
is configured with Asterisk (Section 9.4.3), Gammu (Section 4.28.2) and SMS (Section 4.14.2).
86
9.3 U SER CONNECTION DETAILS
From the authentication popup window the user can select the “Connection details” link in order
to view its own data stored in the internal database and connection details (Figures 153, 154).
By clicking on the “Sessions” button (Figure 153), the user gets access to the records of all its
connections. Several details are reported for each connection:
In order to search for specific connections, the user can define a time window. Only the connec-
tions occurred in that time window will be displayed.
87
9.4 S ELF - REGISTRATION
Zetrotruth allows self-registration in few ways, as we are about to see in this Section. Zetrotruth also
makes a substantial effort in keeping track of the various connections, client devices and users in
order to have a handfull of tools for pinpointing out eventual frods. When the Captive Portal is
operating in open mode though, which is less secure but very useful in wired network for example,
only the MAC addresses of the client devices will be recorded.
Self-registration is allowed by default if and only if both email and SMS services are enabled. In
fact, credentials will be sent to the user in complete form (without the password) via email and in
compact form (with the password) via SMS.
After the first login, the user will be asked to agree to the policies or usage rules of the Captive
Portal (if it was configured so in Section 4.15, Figure 47) as shown in Figures 156, 157.
88
After the agreement page, the user will be also prompted with the post registration message
(Section 4.15, Figure 47) as shown in Figure 157.
Once the corresponding module is installed, ZeroTruth will allow self-registration using the accounts
of the most popular social networks, such as Facebook, Google+ e Twitter (Figures 158, 159 and
160). ZeroTruth verifies the user credentials (email, pass) against the account of the selected social
network. If they are correct, then ZeroTruth registers the user on the internal database paying
attention to store the password in MD5 format only. Doing so, the system administrator and/or
the managers will not be able to reveal the password of the users who have used this method
to create their accounts on the Captive Portal. Moreover, the users themselves will also not be
able to recover their password in case it’s forgotten, but they can change it before this happens
(changed password becomes local to the system, therefore it can be revealed and/or retrieved).
89
Here is ZeroTruth using Google+ credentials.
90
9.4.3 S ELF - REGISTRATION WITH A STERISK
If you have installed and configured Asterisk (Section 4.14.1), then the users can use this method
to self-register. I want to remind you that Asterisk is a cost effective solution which takes away all
costs, related to sending text messages (SMS) to the users, from the Captive Portal’s management.
Self-registration with Asterisk is accessed by simply following the “Registration” link in the login
page, as shown in Figure 161.
For an Asterisk registration, the most important field is the phone number because the user will
have to call the Asterisk service using exactly the phone with that number. If the user calls the
Asterisk service with a different phone, then he will never be able to complete the registration
successfully.
Once the registration is completed successfully, the user will find the assigned username and pass-
word at the bottom of the message shown in Figure 162.
91
At this point, the system administrator will find the new user in the users table. As you can see in
Figure 163, the Information column reports the presence of a user who has registered via Asterisk
(little Asterisk icon) but who has not yet called the Asterisk service to confirm its identity (red locket
icon). The system administrator or manager will, therefore, not be able to modify this user (the user
can only be erased, if necessary).
Figure 163: User registered with Asterisk but not yet verified
Once the user will have confirmed its identity, the lock will turn green (user unlocked) and the
system administrator will have full controll over the user’s account, profile etc.
When the system is configured to allow self-registration via text messages (SMS) only (Section
4.14.2) and the “Allow full registration via sms” option is enabled, the self-registration procedure
becomes really fast for the users. In fact, the users will not have to know (and call) the phone num-
ber of the Asterisk service in order to complete the registration. Moreover, with this procedure, the
phone number of the registering user will be used as its “username” and the login password will be
sent via SMS directly to the user’s phone number. When this method of self-registration is enabled,
the default one (or standard method), described in Section 9.4.1, is disabled.
Self-registration with Tickets (Section 4.14.3) works best for hotels, campings etc. In such places,
in fact, there is usually a reception area to welcome the clients i.e. the right place to give them
these tickets, directly. Each user will therefore receive a pre-printed ticket (Section 5.1.4) with just
a valid username on it, as shown in Figure 164.
Only the users owning such tickets will be able to self-register because the system will recognize
the corresponding (valid) usernames. Apart from this initial step, the self-registration procedure
will remain the same. Please keep in mind that if the self-registration with ticket method is enabled
then the default method will be automatically disabled.
92
9.5 PASSWORD R ECOVERY
ZeroTruth allows users to recover their passwords. The procedure may depend on the allowed
method for self-registration though.
From the login page, the user can just follow the “Forgotten Password” link, as shown in Figure 165
In order to receive the password (only possible via SMS), the user must provide the correct user-
name, email address and phone number.
If Asterisk is the configured self-registration method, then the user can recover the password by
calling the Asterisk service, as described in Section 4.14.1.
93
9.6 CAPTIVE P OR TAL L OCKING
If you need to set the Captive Portal offline for a scheduled maintenance, then you can just un-
tick the “Online” option in the Captive Portal configuration page (Section 4.13, option number
nine in Figure 37), as shown in Figure 166.
The warning message displayed to the users (Figure 167) can be easily modified (Section 4.15,
“Info CP Offline” message in Figure 47).
94
Appendix
A Installation and Configuration of SAN Certificates18
The importance of using cryptographic protocols for secure application-level data transport is
essential. The only drawback of using the self-signed Cerification Authority of ZeroShell is that
browsers will inevitably warn the users about such untrusted certificate. This can be very annoy-
ing and may lead the users to simply abbandon the connection to the Captive Portal, since it
appears to be an untrusted, or even worse, a malicious site (Figure 168).
To avoid this annoyance, we need to create a new Certification Authority (CA) for ZeroShell,
signed by a trusted CA. Doing so, browsers will be able to verify that the certificate they are
dealing with can be trusted because it is signed by a CA they have in their list of trusted Certi-
fication Authorities. But this is actually not quite the end of it because Captive Portals ususally
do operate on private domains while trusted CAs can only sign cerificates for public domains
(www.zerotruth.net in our case).
The purpose of a certificate with SAN is the same as that of other certificates. It provides a means
for a server to establish its identity and then set up a secure communication. Certificates with
SAN also provide a Subject Alternative Name field that allows additional domain names to be
protected with just one certificate. By utilizing this highly versatile single SAN certificate, you can
therefore protect multiple fully-qualified domain names (FQDN), private host names, IP addresses
etc. 19 In our case we will use a SAN certificate to protect the following two additional private
domains: hotspot.zerotruth.net and captive.zerotruth.net, on which our Captive Portal is listening.
• we demand everything (creation of private key and SAN certificate) to the trusted CA,
• we create our own private key and generate a Certificate Signing Request (CSR) to be sent
to the trusted CA.
We decide to take the second option, therefore we want to create our own private key and CSR.
To do this we can use several tools, depending on the platform you are most confortable with.
Let’s say that if you are using Windows, I strongly suggest to use the xca GUI, which is a simple
interface to the OpenSSL library for cryptographic operations. On Linux systems, instead, we can
use directly the openssl command line tool from any terminal window or console.
18
This howto is due to the essential and competent work of Jonatha Ferrarini.
19
The SAN certificates I normally use are the Comodo Positive UCC/SAN from www.megasslstore.com, which offer 3
expandable domains.
95
The first thing to do is to create the private key. The following command generates a 4096-bit long
private key of type RSA, as shown in Figure 169.
We must now edit the “/etc/ssl/openssl.cnf ” file in order to modify the “v3 req” section. Please
pay particular attention to the red arrows in Figure 170. We basically demand the subjectAlt-
Name parameter to a new section called alt names in which we specify the two private domains
hotspot.zerotruth.net and captive.zerotruth.net as the corresponding values for DNS.1 and DNS.2,
respectively.
The following command creates the CSR for www.zerotruth.net using the previous private key:
The most important parameter is the Common Name which must be set to the public domain
of the Captive Portal (www.zerotruth.net), as shown in Figure 171.
At this point we have both the private key (www.zerotruth.net.key) and CSR (www.zerotruth.net.csr)
files. The only file we must send to the trusted CA to be signed is the CSR.
96
The trusted CA will return us two separate files. The first file (www.zerotruth.net) corresponds to the
signed certificate for the Captive Portal host (Figure 173).
The second file (ca-bundle.crt) corresponds to the signed CA (or “Root CA”), as shown in Figure
174.
In order to import the root CA file (ca-bundle.crt) into the Tusted CAs section of ZeroShell we must
first change its extension from .crt to .pem with the command: mv ca-bundle.crt ca-bundle.pem
97
The signed host certificate for our Captive Portal (www.zerotruth.net) must also be imported into
the Imported section of ZeroShell, as shown in Figure 176.
At this point, if you click on the “View” link (Figure 176) to check the cartificate status, you will see
that ZeroShell is not ok with it yet (Status: Unable to get local issuer certificate), as shown in Figure
177.
In Fact, the host certificate file (www.zerotruth.net) was not signed with our root CA file (ca-
bundle.crt), as shown in Figure 173 (Verified by: COMODO RSA Domain Validation Secure Server
CA). Moreover, the root CA file (ca-bundle.crt) itself was also not signed by any of our certificates,
as shown in Figure 174 (Verified by: COMODO RSA Certification Authority).
To fix this problem we must therefore import the entire “certificate chain” into the Tusted CAs
section of ZeroShell. These publicly available intermediate certificates can be easily visualized on
the COMODO website:
From the two certificates we need to copy and paste into two separate files, with extension .pem
(such as comodoCA.pem and comodoDVSSCA.pem), what follow:
-----BEGIN CERTIFICATE-----
MIIFdDCCBFygAwIBAgIQJ2bu...
MQswCQYDVQQGEwJTRTEUMBIG...
...
pu/xO28QOG8=
-----END CERTIFICATE-----
The two files you have just created must now be imported into the Tusted CAs section of ZeroShell,
as shown in Figure 178.
98
The final resulting list of Tusted CAs should look like in Figure 178 (root CA: ca-bundle.crt, COMODO
RSA Certification Authority: comodoCA.pem, COMODO RSA Domain Validation Secure Server
CA: comodoDVSSCA.pem). The host certificate status should also be ok (Figure 179).
To make sure the Captive Portal is using the freshly imported host certificate (www.zerotruth.net),
we have to add a new zone in the DNS configuration of ZeroShell, as shown in Figures 180, 181.
Basically we need the system to use, as redirection address, one of the two private hostnames of
the SAN certificate, for example captive.zerotruth.net.
99
Inside the new DNS zone, we need to create a new record of type A assigning to it the private
IP address corresponding to captive.zerotruth.net, as shown in Figure 182 (Entry Name: captive,
Address Record: A, Address: 192.168.70.100).
Now, in the “Authentication” section of the “Captive Portal” configuration page of ZeroShell, we
need to set www.zerotruth.net as the default certificate . To do this, select “Imported” in the X.509
Host Certificate subsection and then choose the www.zerotruth.net host certificate, as shown in
Figure 183.
Back to ZeroTruth (Section 4.13), we can finally set the redirection URL of the Captive Portal to
“captive.zerotruth.net”, as shown in Figure 184.
If the Captive Portal is configured to use multiple interfaces (Section 4.13), then it will be possible
to define a redirection URL for each interface, as shown in Figure 185.
100
Figure 185: URL redirection with multiple interfaces
Keep in mind that for each interface you must also add the corresponding DNS record of type
A (Figures 182) if you intend to use it in conjunction with a private URL of the SAN cerificate (not
yet used). When the corresponding URL of some interface is left blank, then the IP address of that
interface will be used instead, for the redirection. In this case, the browser will not recognize the
connection as secure, and the users will be warned about that.
When the connection is recognized as secure, the browsers will usually show a little green lock, as
shown in Figures 186, 187.
101
B Create new template
ZeroTruth allows you to create your own template for the access pages of the Captive Portal (Sec-
tion 4.4, Figure 26). To create a new template, without modifying the existing ones, you can run
the following script from the ZeroTruth shell:
/DB/apache2/cgi-bin/zerotruth/scripts/createTemplate.sh
The script will only ask you for the name of the new template, as shown in Figure 188.
What the script does is basically to create a copy of the default template with the name you
gave it. In fact, as soon as the script is done, the new template will be immediately available, as
shown in Figure 189.
Once the new template is enabled, you can start changing it and testing it right away. If you do
any mistake with the new template, you can always go back to the default one, at any time.
All extra scripts, CSS and Images must be placed in the following folder (or subfolders):
/DB/apache2/htdocs/zerotruth/templates/new template
Don’t mess up with the subfolders structure! While you can add files to the subfolders, the sub-
folders structure itself must remain untainted.
If you need to remove any template but the default one, which cannot be removed, you can
use the following script:
/DB/apache2/cgi-bin/zerotruth/scripts/deleteTemplate.sh
102
C Midnight Commander, Nano and SSH Filesystem
ZeroShell and ZeroTruth allow you to completely configure and manage the Captive Portal from
their GUIs. In cases where you need to have direct control over the configuration files, ZeroShell
provides the file text editor “vi” (VIsual editor), from the shell. This editor is absolutely not intuitive
to use but extremely powerful. If you want to learn the basic commands of “vi”, please read the
following guide:
Vi Guide
Because “vi” has a steep learning curve, ZeroTruth provides a much more user friendly file text
editor called “nano” (Nano’s ANOther editor), which aims to introduce a simple interface and
intuitive command options to console based text editing. Beside “nano”, ZeroTruth does also
provide an intuitive visual file manager called “mc” (Midnight Commander). It’s a feature rich full-
screen text mode application that allows you to copy, move and delete files and whole directory
trees, search for files and run commands in the subshell. Both “nano” and “mc” can be easily
installed in ZeroTruth with the following set of commands:
cd /DB
wget http://zerotruth.net/download/zt-mc-nano.tar.gz
./install.sh
Figure 190 shows the installation process of Midnignt Commander and Nano from the ZeroTruth
shell.
In order to be able to use both tools immediately, without rebooting the system, it is necessary to
run this last command (pay attention to the initial dot, that’s not a typo!):
. /root/.bash profile
Please read the following guides to learn how to use Midnignt Commander and Nano:
Nano Guide
103
If you are not comfortable with any of the tools presented so far, the last option I have is to teach
you how to locally mount on your computer the remote filesystem of ZeroShell (ZeroTruth and Ze-
roShell share the same filesystem). SSHFS is a filesystem client based on the SSH File Transfer Protocol
(SFTP). Since most servers, such as our ZeroShell, already support this protocol it is very easy to set
up: i.e. on the server side there’s almost nothing to do. On the client side mounting the filesystem
is as easy as logging into the server with ssh. To enable SFTP in ZeroShell we have to change its
default login shell to bash. So, first open up the ZeroShell shell and then log in using the system
administrator credentials. Once you are logged in, type the following command (CHange SHell):
chsh
When you are promped to enter the new value for the default login shell, type “/bin/bash”, as
shown in Figure 191.
To mount the remote ZeroShell filesystem on your linux box, just follow the commands reported
in Figure 192 (you must enter the system administrator password when you run sshfs; pay also
attention to use the correct IP address of your ZeroShell server).
If you think this is too complicated, then you can use nautilus which is the default file manager
in Gnome-based Linux operating systems such as Ubuntu and Fedora. Select Connect to server
from the file menu, as shown in Figure 193.
104
In all cases, once the remote ZeroShell filesystem is mounted, you can use any of your preferred
tools to edit or move files. In Figures 194, 195 I show one of my favourites text editors, Geany, which
is very light and supports several programming languages.
105
D Scripts
Here I report few sample scripts which I’ve developed for ZeroTruth.
D.1 Keypad
In Section 4.8 we have seen that it is possible to make the system execute any command we want
by using a simple numeric Keypad. The available keys are:
0 1 2 3 4 5 6 7 8 9 + - * / Enter
The “Enter” key is used to close the sequence of characters, or commands, and to let the script
“/DB/apache2/cgi-bin/zerotruth/scripts/readkeys.sh” take that sequence and put it into the bash
variable called “CODE”. The first part of the script must remain unchanged because it is responsi-
ble for setting up the “CODE” variable for us, so don’t touch it.
#!/bin/bash
source /DB/apache2/cgi-bin/zerotruth/conf/zt.config
source /DB/apache2/cgi-bin/zerotruth/functions.sh
source /DB/apache2/cgi-bin/zerotruth/language/$C_LANGUAGE/$C_LANGUAGE.sh
NC="$(echo $1 | sed ’s/-/ /g’ | wc -w | awk ’{print $1}’)"
[ "$NC" == "0" ] && exit
CODE=""
for N in $(seq 2 $(($NC+1)));do
PC="$(echo $1 | cut -d’-’ -f$N)"
PC="$(cat $C_ZT_CONF_DIR/keys.conf | grep " $PC" | cut -d’ ’ -f1)"
CODE="${CODE}${PC}"
done
Right below the first part you can add your own commands. Here I report few sample commands.
D ISCONNECT A LL U SERS
106
L OCK A LL U SERS
U NLOCK A LL U SERS
107
R EGISTER U SER
In this example our command consists of the user’s phone number followed by the “+” sign. The
command will first register the user using its phone number as username and then will send a text
message (SMS) to the user, with the credentials.
108