Vous êtes sur la page 1sur 115

Z ERO T RUTH

I NTERFACE TO Z ERO S HELL’ S CAPTIVE P ORTAL


VERSION 3.0

Nello Dalla Costa


July 1st, 2015

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

School has become the world religion


of a modernized proletariat,
and makes futile promises of salvation
to the poor of the technological age.
— Ivan Illich
Nello Dalla Costa

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

3 I NSTALLATION AND R EMOVAL OF Z ERO T RUTH 13


3.1 Z ERO S HELL P REPARATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
3.2 Z EROT RUTH I NSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 Z EROT RUTH R EMOVAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.4 Z EROT RUTH U PGRADE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.5 ACCESS TO THE A DMINISTRATION GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

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

A Installation and Configuration of SAN Certificates 95

B Create new template 102

C Midnight Commander, Nano and SSH Filesystem 103

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!

The only problem left was:

How can I make ZeroShell’s Captive Portal capability more user-friendly to non-expert adminis-
trators?

The answer was very simple:

I’m going to create a new interface (ZeroTruth) powered by ZeroShell.

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

2.1 H OTSPOT 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.

Figure 1: Hotspot network protected by a Captive Portal Router

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:

• Authentication and traffic encryption via WPA/WPA2 Enterprise,

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

Figure 2: Captive Portal Gateway configuration

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.

2.2 T HE ENEMIES OF THE CAPTIVE P OR TAL


The simplicity in the use of a captive portal even by a novice user is mainly due to the fact that
access to Level 2 of the network, whether it is wireless and wired network is open (that is no
authentication is required). The client just is associated the network immediately obtains an IP from
the DHCP server and communicates in a non-encrypted way. The counterpart to this simplicity
translates into an inherent weakness in terms of security. We will see in the next two paragraphs as
ZeroShell attempts to mitigate this weakness.

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.

Figure 3: Network Access Popup window

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

2.4 D ENIAL OF S ERVICE (D O S)


Some software in an attempt to communicate with the outside network at any cost, after at-
tempting to communicate on the TCP/UDP ports assigned to them, try the connection on TCP
ports 80 and 443 knowing that is not easy that a network administrator would close the outgoing
traffic on these ports preventing the http/https navigation and hence access the web.

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

Figure 5: Captive Portal Denial of Service Protection

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.

2.5 R OUTER OR B RIDGE ?


In Figure 1 the captive portal works as a Level 3 router connected directly to a modem which
connects to the Internet. It acts as the default gateway for clients that connect to the network. In
this configuration, said in Routed Mode, it is convenient the router performs the function of DHCP
and DNS servers. The ZeroShell’s Captive Portal can also work in Bridge Mode, where the network
to be protected by the Captive Portal shares the same IP subnet as the rest of the LAN. Therefore,
a client gets the same IP address if you connect from one side than the other and has the same
default gateway that is a router ahead of the Captive Portal. In this case, DHCP and DNS to be
used for the hotspot may be the same as those used for the rest of the LAN.
In previous versions of ZeroShell you had to explicitly declare the operating mode (Routed or
Bridge) of the captive portal. Since the release 1.0.beta15, however, there are 2 news about:

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

Figure 6: Captive Portal applied on multiple network interfaces

2.6 U SER AUTHENTICATION


The Captive Portal of ZeroShell can use different authentication sources simultaneously. By default,
it authenticates users using its Kerberos 5 KDC that contains principals for internal users stored in
the LDAP Directory and managed through the web interface. However, you can use external
authentication sources such as Kerberos 5 REALMs, RADIUS servers and Identity Providers SAML 2.
In addition, there is also the login using X.509 digital certificates that would allow access the net-
work via Smart Card or USB Token. In the case of RADIUS or Kerberos 5 authentication the users

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

Figure 7: Authorized Authentication Domains for the hotspot

2.7 RADIUS (PAP, EAP-TTLS E PEAP)


RADIUS authentication is one of the most widely used protocols for the recognition of users on
network devices such as Wireless Access Points or layer 2 Switches that allow access to Level 2
only after authentication has been successful. The Captive Portal of ZeroShell allows RADIUS au-
thentication requests to external servers via proxy. In other words, the captive portal requires
authentication to its internal FreeRADIUS server, that if it discovers that it is not authoritative for the
domain to which the user belongs, it forwards the authentication request to the external author-
itative RADIUS server. Clearly, the external RADIUS server must be configured in the list of proxy
servers by specifying the Shared Secret. On the other hand, even on the external RADIUS server,
an entry must be added between the RADIUS clients to enable the IP address of the Captive
Portal using the same shared secret. In the list of RADIUS proxy, you can add the DEFAULT RADIUS
server that is used when none of the other servers is authoritative for authenticating the user. The
default proxy radius is often used even when the captive portal has to authenticate against a
RADIUS server hierarchy.

Figure 8: Distributed Hotspots by using a centralized RADIUS server

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.

2.8 K ERBEROS 5 (ACTIVE DIRECTORY )

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.

Figure 9: Kerberos 5 realms configuration

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.

2.9 X.509 D IGITAL C ER TIFICATES (S MAR T CARDS )


Authentication via X.509 digital certificates allow to access the network without typing your user-
name and password. In other words, each user who needs access to the network must have a
personal certificate with its private key loaded into the web browser. Pressing the [X.509] button in
the authentication portal, if the certificate is signed by a Certificate Authority enabled within the
captive portal configuration, the user has access to the network. The use of digital certificates is

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.

2.10 S HIBBOLETH (I D P SAML 2.0)


Using Shibboleth Service Provider, the Captive Portal of ZeroShell allows user authentication against
an Identity Provider SAML 2. This is often used in the federations in which each member of a fed-
eration implements an IdP to recognize users and several web services (Service Provider). These
services can include access to a Wi-Fi network, in which the user is redirected to the WAYF/DS
from which he/she selects the Identity Provider authoritative to authenticate it. It could be ar-
gued that attaching the captive portal to a hierarchy of RADIUS servers (such as EDUROAM with
regard the Universities and the Research Institutions) would be however a federated access to
the network. However, while in the case of 802.1x the so-called end-to-end authentication takes
place also crossing the hierarchy of RADIUS servers, with the captive portal that is not guaranteed.

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/).

2.11 ACCOUNTING FOR TIME , TRAFFIC AND COST OF THE CONNECTIONS

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.

Figure 10: RADIUS Accountig information

9
Figure 11: User accounting details

2.12 N ETWORK ACCESS LIMITS

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:

• Type of payment (prepaid and postpaid),

• Cost per megabyte of traffic,

• Cost per hour of the connection,

• Maximum limit of traffic (incoming and outgoing) in Megabytes,

• Time limit of connection.

Figure 12: User limits configuration in the accounting

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.

Figure 13: Log messages of 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.

Figure 14: Connection Tracking of the TCP/UDP connections

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.

3.1 Z ERO S HELL P REPARATION

Figure 15: SSH Abilitation

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.

Figure 16: Captive Portal Abilitation

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:

Figure 17: Accounting Abilitation

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”

Figure 18: ZeroShell localman

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

Figure 19: ZeroTruth Installation

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.

3.3 Z ERO T RUTH R EMOVAL


In the same folder where we have installed the program, in our example “/DB/zerotruth- 3.0”, you
will also find the script “uninstall.sh” to completely uninstall ZeroTruth without affecting ZeroShell.

3.4 Z ERO T RUTH U PGRADE


Before attempting any upgrade to a newer version, without using the GUI of ZeroTruth, you must
first remove the installed version as we have described before.

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.

Figure 21: ZeroTruth’s main page header with general links

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.

4.1 Z ERO T RUTH

Figure 22: Configuration page header with links

In the “ZeroTruth” section you can set:

• the name of the workstation


This name will be used in communications, via email and/or SMS, to the users and to the admin-
istrator. This name will be also used to identify the backup of the workstation.

• the interface language


The following languages are currently available: Italian, French, English, Polish, Portuguese,
Spanish and German. 1

• the listening ports


If you change the default values to any one of these ports, you must reboot the system in order
to make the chages effective.

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

Figure 23: Admin configration

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

• priority over the normal (less privileged) administrators


in such a situation, a normal administrator will not be able to login until the system administrator
is connected

• registration of the system administrator’s activity in the system logs.

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

Figure 24: Users configration

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.

Figure 25: User privileges

The privileges are mostly self-explanatory, here we list those that need a little explanation:

• Manage own users only


The user to which this priviledge is assigned will only be able to see, and therefore manage, the
users he himself did add to the system. 8

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

Figure 26: ZeroTruth and Captive Portal Images

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

Figure 27: Asterisk and peers control

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

Figure 28: sip.conf configuration

21
4.6 LOG
Logs can be inspected and deleted from this page.

Figure 29: Log

4.7 LDAP C ONTROL

Figure 30: Ldap

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.

Figure 31: Keypad

To verify which “/dev/input” is connected to the keypad, it’s possible to type following commands:

1. check the menu to see which input devices are mapped,

2. connect the keypad,

3. check which device was added, and select it.

23
To configure the correct mapping of the keypad keys, you can use the following command:

“/DB/apache2/cgi-bin/zerotruth/bin/configkeys”

and then follow the on-screen instructions.

What you see here are the system codes associated to my keypad keys.

Figure 32: configkeys command

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

Figure 33: 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

Figure 34: Export

This utility allows you to export the users of the Caprive Portal in text or CSV format.

25
4.11 F ONT

Figure 35: Font

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

Figure 36: Test

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.

Figure 37: Captive Portal

The most important configurations are (see corresponding arrow):

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

Figure 38: Redirection choice

5. Do not use HTTPS


For data communication between the clients and the Captive Portal, you can use the HTTPS
or HTTP protocols. Be aware that by using the HTTP protocol you will face some serious safety
concerns since all data is transmitted in clear text.

6. Disable CP on port 443


If a user is redirected to the Captive Portal for authentication trying to access a page in HTTPS,
although reliable, he will be notified that the site’s certificate is not safe. If you chose to disable
CP on port 443, the HTTPS site will be unreachable forcing the user to connect to HTTP sites only.

7. Mobile device page


For mobile devices, which have difficulties in managing the popup authentication window you
can use an alternative method as explained in the Standard Login section 9.1.1.

8. Authentication time limit for mobile device page


Devices for which the authentication pop-up window is not provided, an authentication time
limit (in minutes) can be set. After this period of time, if the system does not detect the presence
of the “mobile device page” on the device, the device itself will be disconnected.

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.

10. Open Service


ZeroTruth allows to set up the Internet access in a completely open manner, with no need
for the user to enter any username or password. In such a case, the MAC address of the
connecting device will be used and stored on the system as the client’s username. This device
will still be subjected to the rules defined in the self-registration configuration and all the details
of the connection will also be stored in the accounting data base of the system.

11. ZeroTruth authentication popup


The system uses the default popup authentication method of ZeroShell (even thouh I’ve added
some additional features to it), but you can select an alternative popup window which has
even more features and resembles the overall ZeroTruth webpages layout more closely.

12. Default prefix


Where a phone number is requested to be entered (self registration, password recovery etc.),
it’s possible to set the default country code (which can always be modified by the user).

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.

14. Username prefix


In addition to the normal user registration, ZeroTruth allows you to quickly enter large groups
of users (Section 5.1.2). In this case it can be helpful to have a prefix (e.g. teacher, customer,
partner, etc.) so that the users will be registered as, for example, “teacher001”, “teacher002”,
“teacher003”, etc.

15. Block user after incorrect login


If you set this control, the users of the Captive Portal are blocked after each failed attempt
(invalid credentials) for a certain amount of time (in minutes).

16. Disconnect if idle


You can set the number of minutes after which a user will be automatically disconnect from
the system if he generates not network traffic (stays idle).

17. Enable fast user table


If you do not need a complete view of the user table, you can set this option. The reduced
user table will be much faster to scroll on the display (you will always be able to switch back to
full view, anyway).

18. Enable Popup


The pop-up communication window to the users, which can be configured in section 9.3, can
be quickly enabled or disabled from here.

19. Enable Walled Garden


The Walled Garden, which can be configured in section 9.2, can be quickly enabled or dis-
abled from here.

20. Password Recovery


From the login page of the Captive Portal, any user can recover its own password, unless it is
disabled here.

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.

22. Show connection’s costs


You can enable or disable the visualization of the accumulated cost of the ongoing connec-
tion. This figure will be visible inside in the user’s authentication window of the Captive Portal.

23. Show remaining MB


If in the user’s profile a network quota traffic is set (for example 200 MB) then, as soon as the
remeining quota reaches this value, a popup window will inform the corresponding user about
the imminent (forced) disconnection.

24. Show remaining time


If in the user’s profile a connection time quota is set (for example 200 minutes) then, as soon
as the remeining quota reaches this value, a popup window will inform the corresponding user
about the imminent (forced) disconnection.

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.

26. Enable image at login


The login image, which can also be used for important communications to the users (see Sec-
tion 9.4 for its configuration), can be quickly enabled or disabled from here.

27. URL redirection with QR code


The access to the system can be granted by means of a QR code (Section 4.16). In this case
you can set the redirection URL after login, right here.

28. Enable login language selection


The users of the Captive Portal can choose the preferred language with which the Captive
Portal pages and notifications will be displayed. Here it’s possible to enable or disable this
option.

29. Template
ZeroTruth provides a default user template which can be customized (Appendix B). Here you
can select the preferred template.

4.14 S ELF REGISTRATION

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.

Figure 39: Self-registration

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.

4. Allow Registration with Social Network


ZeroTruth allows to self-register using the account of the most common Social Networks (Section
9.4.2).

5. Automatic Username (cell phone number)


The system automatically generates the username for the connecting client and sets it equal
to the phone number entered during the self-registration.

6. Allow new registration once expired


If a user has exceeded the maximum number of hours, the number of allowed MB or the ex-
piration date of his account has passed (all these parameters are set in each user’s profile),
then the account will be disabled. Because the account’s data won’t be removed from the
system’s data base, the user won’t be able to register again, unless you set this option.

7. Send password with email


For added security the password is not sent to the user via email. In some cases you may
decide to overcome this limitation.

8. Block new registration from MAC address


To discourage any massive attempt of self-registration from the same client, you can use this
option.

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

10. Disable Email


ZeroTruth usually sends an email to the user with the registration data. Here you can prevent
ZeroTruth from sending this email.

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.

12. Time limit


The maximum number of hours per day and per month is displayed according to the chosen
profile.

13. Traffic limit


The maximum number of MB per day and per month granted to the user is displayed according
to the chosen profile.

14. Days
The maximum number of days granted to the user is displayed according to the chosen profile.

15. Usage controls


Usage controls lets you restrict the surfing times per user. You define when individual users can
be connected to the Internet via a time switch (two windows per day are available for each
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).

Z ERO T RUTH C ONFIGURATION

In order to activate Asterisk, you have to do the following:

Figure 40: Activation and registration with Asterisk

1. tick the checkbox “Registration with Asterisk” to enable the service,

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

In our example, the command is:

“curl http://IP ZEROTRUTH:8089/cgi-bin/unlockasterisk.sh?C=$1+gtTYR65fgt”

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:

“curl http://IP ZEROTRUTH:8089/cgi-bin/forgotasterisk.sh?C=$1+gtTYR65fgt”

Instead, if the phone numbers are identical then follow this:

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

4.14.2 R EGISTRATION WITH SMS

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

Figure 45: 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:

Figure 46: Registration via Ticket

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.

Figure 47: Notices

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.

Figure 48: Ticket configuration

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.

Here are some examples of printed tickets:

Figure 49: Ticket samples

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

4.17.1 Z ERO T RUTH PAY PAL C ONFIGURATION

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

Figure 50: Paypal configuration

In the form you should enter:

• the code of the button for the PayPal website,

• the post-payment notification message,

• the number of allowed attempts to complete the self-registration,

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

4.17.2 PAYPAL C ONFIGURATION

After you have logged into your PayPal account, click on “Summary” and then “Seller prefer-
ences”.

Figure 51: PayPal - Seller preferences

You will be prompted with the following page in which you can set the needed configuration we
discussed above.

Figure 52: PayPal - management of payment buttons

Let’s see them in more detail.

38
1. PAYPAL BUTTON

First you will have to create the PayPal button code to be pasted into the previous form, see
Figure 50).

Figure 53: PayPal - payment buttons configuration

Figure 54: PayPal - payment button code

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.

Figure 55: PayPal - Automatic return to the Captive Portal webpage

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.

Figure 56: PayPal - IPN’s redirection to the Captive Portal station

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.

Figure 57: Login with “Recharge Cridit” link

Figure 58: Recharge Cridit login window

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

Figure 59: Recharge Cridit PayPal button

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.

Figure 60: Post-payment message

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.

Figure 61: Popup with “Recharge Credit” link

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.

Figure 62: MAC blocked message

For a more descriptive guide, please refer to this documentation:

http://www.zerotruth.net/controldl.php?file=ZT PAYPAL En.pdf

4.18 PAYMENTS
In this page you can visualize and mage the payments received via PayPal or directly from the
user (cash).

Figure 63: Payments management

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

4.19 L OCK / UNLOCK USERS

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.

Figure 65: Lock/unlock of users and services

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.

4.20.1 L OCAL WALLED G ARDEN

Figure 66: Local 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

Figure 67: Remote Walled Garden configuration

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.

Figure 68: Remote Walled Garden preview

45
4.21 P OPUP

Figure 69: Popup configuration

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.

Figure 70: Login images configuration

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:

1. Move to the relevant page

Figure 71: The like button

2. Follow the “Like Box” link

Figure 72: Like Box link

3. Fill in the form to receive the code

Figure 73: Like Button form

4. Gather the data for ZeroTruth

Figure 74: Like Button ZeroTruth

48
On ZeroTruth, it is sufficient to adjust the code of the following script.

Figure 75: Configuration of the Facebook Like button on ZeroTruth

1. appId : ”XXXXXXXXXXXXXX”,
replace all the Xs with the assiged ID,

2. js.src = /connect.facebook.net/it IT/sdk.js#xfbml=1&appId=XXXXXXXXXXXXXXX&version=v2.0;


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.

Figure 76: Proxy Configuration

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.

4.24.3 H AVP +C LAMAV

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.

Figure 77: Activation and Shaping control

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.

Figure 78: Configuration of IP Blocker and Ad Blocker

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.

Figure 79: Email Configuration

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.

Figure 80: SMS Configuration

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.

Beside self-registration, text messages are used for:

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

Figure 81: my SMS script configuration

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.

Figure 82: Gammu Configuration

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 main advantage of using Gammu is two fold:

• it is independent from the Internet (loss of connectivity),

• it can receive SMS.

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.

Figure 83: MultiCP Configuration

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.

Figure 84: MultiCp: Server view

Figure 85: MultiCP: Client view

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

Figure 86: Backup Configuration

4.30.1 B ACKUP WITH EMAIL

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.

4.30.2 B ACKUP WITH FTP

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

Figure 87: Dropbox access confirmation

4.30.4 B ACKUP WITH SCP

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.

Figure 88: Backup with SCP

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”

Figure 89: Public Key remote installation

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

Figure 90: SCP correctly enabled

Figure 91: Check Backups

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

Figure 93: Choose what to restore

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

Figure 94: Restore backup results

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.

Figure 95: Disk capacity and notification

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.

CPU real-time graph:

Figure 96: CPU usage

63
Memory real-time graph:

Figure 97: Memory usage

Network real-time graph:

Figure 98: Network usage

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.

Figure 99: Yearly view of Captive Portal usage

64
Figure 100: Monthly view of Captive Portal usage

Figure 101: Daily view of Captive Portal usage

Figure 102: Hourly 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).

Figure 104: Time window size and location

66
4.33 U PGRADES
Newer releases of ZeroTruth can be easily installed from this page.

Figure 105: ZeroTruth Upgrade

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.

Figure 106: ZeroTruth Upgrade status

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.

Figure 107: Available Upgrade warning sign

Figure 108: Available Upgrade warning sign

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.

5.1.1 A DD SINGLE USER

A single user can be added to the system by specifying the following parameters.

Figure 109: Add user form

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

5. The value of the “Email” field is optional.

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.

5.1.2 A DD MULTIPLE USERS

ZeroTruth allows you to add multiple users in one go, if necessary. From the “Add User” page
select “Multi” link.

Figure 110: Add multiple users

Figure 111: Multi link

1. Number of users to add.


2. Username prefix (not mandatory).
3. If some initial credit is specified, then it adds an entry (for each user) in the payments table
(Figure 63) as cash.
After you click the “Save” button it will be possible to print the corresponding tickets, which can
then be handed in to the reception of a public library, for example.

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”

Figure 112: From File link

Figure 113: User list text file sample

Figure 114: Upload of user list from file

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.

Figure 115: Inserimento utenti da file

This is why I recommend grouping up similar users sharing a common configuration.

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.

Figure 116: From Ticket link

Figure 117: From Ticket link

Figure 118: Tickets for self-registration

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.

5.2.1 S TANDARD TABLE

The standard table lets you visualize and manage most of the parameters or aspects associated
to each user.

Figure 119: Standard Users List

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.

Figure 120: User’s complete details table

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.

Figure 121: User’s connections list

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 .

Figure 122: Multiple connections icon

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.

Figure 123: Multiple connections list

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.

Figure 124: User Update

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.

5.2.2 U SERS LIST FOR SELF - REGISTRATION VIA TICKET

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.

Figure 125: Waiting Users link

Figure 126: Waiting Users management

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.

Figure 127: Search for users

Figure 128: Search Form

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.

Figure 129: Ricerca utenti

Possible actions are:

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

5.2.4 FAST TABLE

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:

Figure 130: Fast Table

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.

6.1 P ROFILE TABLES

Figure 131: Profile Tables

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.

Figure 132: Profile 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.

6.3 PAYMENT P ROFILE


Payments can either be configured as Prepaid or Postpaid. If you set the payment method to Post-
paid then the system will calculate the user’s network charges based on the cost per megabyte
or hour of connection. The user will be requested to pay the network expenses before his depar-
ture from the hotel or camping, for example, or when the profile limits have been reached. In
fact, in the latter case, the user will be automatically locked out by the system, preventing any
further access to the network.

Figure 133: Postpaid method

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

Figure 134: Prepaid method

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.

Figure 135: Bandwidth limits

6.5 P ROFILE WITH NETWORK INTERFACE SPECIFICATION

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.

Figure 136: Profile with network interface specification

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

Figure 137: Profiles list with interfaces

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.

7.1 S END EMAIL

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.

Figure 138: Email - find users

Figure 139: Email - insert text

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.

8.1 S END SMS


First thing to do is to find the users to which we would like to send the SMS. Obviously, only the user
with a registered phone number will be scanned during the search.

Figure 140: SMS - find users

Figure 141: SMS - insert text

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

9.1 CAPTIVE P OR TAL L OGIN


Just like in Wikipedia’s description of the Captive Portal, ZeroTruth will intercept and redirect the
client to the login page shown in Figure 142, unless it is configured differently (Section 4.13, “Open
Service” option in Figure 37).

9.1.1 L OGIN STANDARD

Figure 142: Login Page

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.

Figure 143: User Informations

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

Figure 144: Authentication popup window

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.

Figure 145: Authentication popup window (elapsed time only)

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 146: ZeroTruth authentication popup

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

Figure 148: Pagina di autenticazione per device mobili

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.

Figure 149: Self-registration with open Captive Portal

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.

Figure 150: Login with open Captive Portal

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.

9.2 C HANGE PASSWORD


From the authentication popup window the user can select the “Change Password” link in order
to change the login password (Figure 151).

Figure 151: Change password

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.

Figure 152: Confirmation window

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

Figure 153: User details

Figure 154: User connections

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:

• IP and MAC address of the device used for the connection,


• date and time the connection started,
• date and time the connection ended,
• download in MB,
• upload in MB,
• total network traffic in MB;
• total connection time,
• connection cost.

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.

9.4.1 S TANDARD S ELF - REGISTRATION

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.

Figure 155: Self-registration

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.

Figure 156: Captive Portal usage rules agreement form

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.

Figure 157: Post registration message

9.4.2 S ELF - REGISTRATION WITH S OCIAL N ETWORK

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

Figure 158: Self-registration with Facebbok

89
Here is ZeroTruth using Google+ credentials.

Figure 159: Self-registration with Google+

Here is ZeroTruth using Twitter credentials.

Figure 160: Self-registration with Twitter

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.

Figure 161: Self-registration with Asterisk

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.

Figure 162: Post-registration message with credentials

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.

9.4.4 S ELF - REGISTRATION WITH SMS

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.

9.4.5 S ELF - REGISTRATION WITH T ICKET

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.

Figure 164: Ticket samples

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.

9.5.1 S TANDARD PASSWORD R ECOVERY

From the login page, the user can just follow the “Forgotten Password” link, as shown in Figure 165

Figure 165: Standard Password Recovery

In order to receive the password (only possible via SMS), the user must provide the correct user-
name, email address and phone number.

9.5.2 PASSWORD R ECOVERY WITH A STERISK

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.

Figure 166: Captive Portal offline configuration

Figure 167: Captive Portal offline message

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

Figure 168: Warning message of uncertified connection

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.

To obtain a SAN certificate we have the following choices:

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

openssl genrsa -out www.zerotruth.net.key 4096

Figure 169: Generate private key

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.

Figure 170: V3 req extensions

The following command creates the CSR for www.zerotruth.net using the previous private key:

openssl req -new -key www.zerotruth.net.key -out www.zerotruth.net.csr -sha512

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.

Figure 171: Creation of CSR

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.

Figure 172: Private key and CSR files

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

Figure 173: Signed Host Certificate

The second file (ca-bundle.crt) corresponds to the signed CA (or “Root CA”), as shown in Figure
174.

Figure 174: Signed root CA

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

Figure 175: Import Root CA into Tusted CAs section of ZeroShell

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.

Figure 176: Import signed host certificate

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.

Figure 177: Missing Certificate Chain

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:

COMODO RSA Certification Authority


COMODO RSA Domain Validation Secure Server CA

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

Figure 178: Import COMODO certificates

Figure 179: Host certificate Status

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.

Figure 180: Create DNS zone

Figure 181: DNS zone form

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

Figure 182: Insert record of type A

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.

Figure 183: Select imported host certificate

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.

Figure 184: ZeroTruth Redirection URL

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.

Figure 186: Trusted Certificate

Figure 187: Trusted Certificate

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.

Figure 188: Create new template

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.

Figure 189: Enable new template

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

tar zxvf zt-mc-nano.tar.gz

./install.sh

Figure 190 shows the installation process of Midnignt Commander and Nano from the ZeroTruth
shell.

Figure 190: Midnignt Commander and Nano Installation

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:

Midnignt Commander Guide

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.

Figure 191: Change login shell

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

Figure 192: Mount remote filesystem

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.

Figure 193: Nautilus

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.

Figure 194: Geany - open file

Figure 195: Geany - GUI

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.

CAPTIVE P ORTAL OFFLINE

if [ "$CODE" == "15556" ];then


ln -f -s $C_HTDOCS_TEMPLATE_DIR/cp_showauth_custom-off \
$C_CP_DIR/Auth/Template/cp_showauth_custom
exit
fi

CAPTIVE P ORTAL ONLINE

if [ "$CODE" == "16668" ];then


ln -f -s $C_HTDOCS_TEMPLATE_DIR/cp_showauth_custom-on \
$C_CP_DIR/Auth/Template/cp_showauth_custom
exit
fi

D ISCONNECT A LL U SERS

if [ "$CODE" == "1563546" ];then


CONNECTED=$(ls $C_CP_DIR/Connected)
for IP in $CONNECTED;do
$C_ZT_BIN_DIR/zt "Disconnetti" "$IP"
done
exit
fi

106
L OCK A LL U SERS

if [ "$CODE" == "986546" ];then


USERS=$(/usr/local/bin/ldapsearch -xLLL -b "ou=Radius,$C_LDAPBASE" ’(!(sn=*-*))’ cn | \
sed -n ’/cn:/p’ | awk ’{ print $2 }’)
[ -z "$USERS" ] && exit
for USER in $USERS;do
if [ "$USER" != "admin" ];then
CONNECTED=$(ls $C_CP_DIR/Connected )
for IP in $CONNECTED;do
if [ $(cat $C_CP_DIR/Connected/$IP/User | cut -d"@" -f1) == "$USER" ];then
$C_ZT_BIN_DIR/zt "Disconnetti" "$IP" "$USER"
fi
done
RADIUS=$(/usr/local/bin/ldapsearch -xLLL -b "ou=Radius,$C_LDAPBASE" cn=$USER sn)
PASS=$( echo $RADIUS | awk ’{print $NF}’)
PASSLOCK="$PASS-$RANDOM"
DATA="dn: cn=$USER,ou=Radius,$C_LDAPBASE\nsn: $PASSLOCK"
echo -e "$DATA" | ldapmodify -c -x -D "$C_LDAPMANAGER,$C_LDAPBASE" \
-w $C_LDAPROOT > /dev/null
DATA="dn: uid=$USER,ou=PEOPLE,$C_LDAPBASE\nlocked: yes"
echo -e "$DATA" | ldapmodify -c -x -D "$C_LDAPMANAGER,$C_LDAPBASE" \
-w $C_LDAPROOT > /dev/null
fi
done
exit
fi

U NLOCK A LL U SERS

if [ "$CODE" == "134321" ];then


USERS=$(/usr/local/bin/ldapsearch -xLLL -b "ou=Radius,$C_LDAPBASE" ’(&(sn=*-*))’ cn | \
sed -n ’/cn:/p’ | awk ’{ print $2 }’)
[ -z "$USERS" ] && exit
for USER in $USERS;do
if [ "$USER" != "admin" ];then
RADIUS=$(/usr/local/bin/ldapsearch -xLLL -b "ou=Radius,$C_LDAPBASE" cn=$USER sn)
PASS=$( echo $RADIUS | awk ’{print $NF}’)
PASS=$(echo "$PASS" | cut -d’-’ -f1)
DATA="dn: cn=$USER,ou=Radius,$C_LDAPBASE\nsn: $PASS"
echo -e "$DATA" | ldapmodify -c -x -D "$C_LDAPMANAGER,$C_LDAPBASE" \
-w $C_LDAPROOT > /dev/null
DATA="dn: uid=$USER,ou=PEOPLE,$C_LDAPBASE\nlocked: no"
echo -e "$DATA" | /ldapmodify -c -x -D "$C_LDAPMANAGER,$C_LDAPBASE" \
-w $C_LDAPROOT > /dev/null
fi
done
exit
fi

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.

if [ -n "$(echo "$CODE" | grep ’+$’)" ];then


PHONE="$(echo "$CODE" | cut -d’+’ -f1)"
USERNAME="$PHONE"
NAME="$L_ANONYMOUS"
LAST_NAME="$L_ANONYMOUS"
CLASS="DEFAULT"
MATRICE="abcdefghilmnpqrstuvz123456789"
while [ "${a:=1}" -le $C_LENGH_PASSWORD ];do
PASSWORD="$PASSWORD${MATRICE:$(($RANDOM%${#MATRICE})):1}"
let a+=1
done
SHADOWEXPIRE=$(dateDiff -d "1970-01-01" "2037-12-31")
ldap_add_people
ldap_add_radius
$C_ZT_BIN_DIR/zt "ControlAcct" "$USERNAME"
$C_ZT_BIN_DIR/zt "ControlLimits" "$USERNAME"
$C_ZT_BIN_DIR/zt "AddK5" "$PASSWORD" "$USERNAME" "2037-12-31"
TEXT_SMS="$C_HOTSPOT_NAME user: $USERNAME password: $PASSWORD - $L_FOOTER_SMS"
$C_ZT_BIN_DIR/zt "InviaSms" "$C_SMS_PROVIDER" "$PHONE" "$TEXT_SMS"
exit
fi

108