Makovec is a simple Laravel-based web application to manage devices not using 802.1X to connect to local area network (LAN) in CESNET's Telehouse offices.
This application is written in Laravel 11 and uses PHP version at least 8.2.
Authentication is managed by locally running Shibboleth Service Provider, so Apache web server is highly recommended as there is an official Shibboleth module for Apache.
- PHP 8.2
- MariaDB 10
- Shibboleth SP 3
- Apache 2.4
The above mentioned requirements can easily be met by using Ubuntu 24.04 LTS (Noble Numbat). For those running older Ubuntu or Debian, Ondřej Surý's PPA repository might be very appreciated.
In order for the Envoy script to be really useful and do what it is designed for, you must setup Apache, PHP, MariaDB and Shibboleth SP at the destination host first.
(To prepare a server for Makovec, I am using an Ansible playbook that is currently not publicly available due to being part of our larger and internal mechanism, but I am willing to share it and most probably will do that in the future.)
Install Apache using apt.
apt install apache2Then get a TLS certificate. If you would like to avoid paying to a Certificate Authority, use Certbot to get a certificate from Let's Encrypt for free. Then configure Apache securely according to Mozilla SSL Configuration Generator using the following stub.
<VirtualHost *:80>
ServerName server.example.org
Redirect permanent / https://server.example.org
</VirtualHost>
<VirtualHost _default_:443>
ServerName server.example.org
DocumentRoot /home/web/makovec/current/public/
# TLS settings
<Directory /home/web/makovec/current/public>
AllowOverride All
</Directory>
<Location />
AuthType shibboleth
ShibRequestSetting requireSession 0
<RequireAll>
Require shibboleth
</RequireAll>
</Location>
<Location /Shibboleth.sso>
SetHandler shib
</Location>
</VirtualHost>It is also highly recommended to allow web user (the user defined in envoy file in the TARGET_USER variable, i.e. the one under which Makovec application is saved in /home directory) to reload and restart PHP-FPM. It helps with minimizing outage during deployment of a new version. Edit /etc/sudoers.d/web accordingly:
web ALL=(ALL) NOPASSWD:/bin/systemctl reload php8.3-fpm,/bin/systemctl restart php8.3-fpm
PHP 8.3 is present as an official package in recommended Ubuntu 24.04 LTS (Noble Numbat).
apt install php-fpmThen follow information in your terminal.
a2enmod proxy_fcgi setenvif
a2enconf php8.3-fpm
systemctl restart apache2(In case you still run on older Ubuntu version or Debian distribution with not so current PHP version, you might find Ondřej Surý's repository highly useful.)
Install and configure Shibboleth SP.
apt install libapache2-mod-shibThere is documentation (in Czech language, though) available at eduID.cz federation web page.
<ApplicationDefaults entityID="https://server.example.org/shibboleth"
REMOTE_USER="uniqueId"
sessionHook="/Shibboleth.sso/AttrChecker"
cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">
<Sessions lifetime="28800" timeout="3600" relayState="ss:mem"
checkAddress="false" handlerSSL="true" cookieProps="https"
redirectLimit="exact">
<!-- Attribute Checker -->
<Handler type="AttributeChecker" Location="/AttrChecker" template="attrChecker.html"
attributes="uniqueId mail cn" flushSession="true"/>
</Sessions>
<!-- Extract information from SAML metadata -->
<AttributeExtractor type="Metadata" DisplayName="displayName"
InformationURL="informationURL" OrganizationURL="organizationURL">
<ContactPerson id="Technical-Contact" contactType="technical" formatter="$EmailAddress"/>
</AttributeExtractor>
</ApplicationDefaults>Then tweak attrChecker.html, localLogout.html and metadataError.html so users are informed properly when any issue occurs. If you need any help, check GÉANT's documentation regarding attribute checking.
The easiest way to install Makovec is to use Laravel Envoy script that is included in this repository.
Laravel Envoy is currently available only for macOS and Linux operating systems. However, on Windows you can use Windows Subsystem for Linux. Of course, you can also use a virtualized Linux system inside, for example, a VirtualBox machine.
The destination host should be running Ubuntu 22.04 LTS (Jammy Jellyfish) with PHP 8.3. If that is not the case, take care and tweak PHP-FPM service in Envoy.blade.php and in Apache configuration accordingly.
Clone this repository:
git clone https://github.com/CESNET/makovecInstall PHP dependencies:
composer installPrepare a configuration file for your deployment using envoy.example template.
cp envoy.example envoyTweaking envoy file to your needs should be easy as all the variables within the file are self explanatory. Then just run the deploy task.
./vendor/bin/envoy run deployThere are two tasks available — deploy and cleanup.
The deploy task simply deploys the current version available at the repository into timestamped directory and makes a symbolic link current. This helps you with rolling back to the previous version if you need to. Just ssh into your web server and create a symbolic link to any previous version still available.
./vendor/bin/envoy run deployThe cleanup task helps you keeping your destination directory clean by leaving only three latest versions (i.e. timestamped directories) available and deletes all the older versions.
./vendor/bin/envoy run cleanupLaravel Envoy allows to use "stories" to help with grouping a set of tasks. Eventually, it makes the whole script much more readable as well as reusable.
There is one downside with stories, though. If your SSH agent requests confirming every use of your key (a highly recommended best practice!), you must confirm the key usage for every single Envoy story. I find it very annoying so therefore I have decided not to use stories after all.
To run this application locally for development, the easiest way is via Laravel Sail.
git clone https://github.com/CESNET/makovec
cd makovec
composer install
cp .env.example .env
php artisan key:generate
./vendor/bin/sail up -d