-
Notifications
You must be signed in to change notification settings - Fork 5
Code & Developer Documentation
This document is intended to provide information about the code and structure of RaspiPass for any developers seeking to improve or fork the project. Every effort will be made to keep this document up-to-date, but documentation is always a dislike of mine, and ends up with a low priority. If you do find any out of date information, hopefully the information here will allow you infer what you need.
Please note this document may contain information about features currently in testing - updating post-release is hard 😄
At its core, RaspiPass is a glorified BASH script. The addition of a Web GUI has necessitated the inclusion of three more languages (PHP, CSS, HTML), complicating the overall structure of the project.
Raspipass stores its code files in three main locations, along with a local Git mirror:
| Directory | Contents |
|---|---|
| /raspipass | Script files that don't require root access/execution |
| /raspi_secure | Script files that require root access/execution |
| /var/www/html | Web GUI files |
It also uses a local Git mirror located in /git with copies of the three directories above. This is to encourage development, as well as provide a simple means of updating. For the purposes of this document, all references will be to the non-Git directories above, unless otherwise specified.
| Directory | Contents |
|---|---|
| /git | Local Git mirror w/scripts |
These files do not require root access to edit, or contain any sensitive data or potential security breaches. (mac_restrict.txt should be moved to /raspi_secure once MAC restriction is actually functioning)
| File | Description |
|---|---|
| config.ini | RaspiPass config generated by Web GUI |
| hostapd.conf | hostapd config (without SSID info) |
| mac_addresses.txt | List of StreetPass Relay MACs |
| mac_restrict.txt | MAC restriction config (unused) |
| runchance.txt | Contains variable for run chance |
| version | Version/Changelog - Contains current version number as first line |
These files are locked down either to maintain device/network security, or because a script needs to be run as root and shouldn't be accessed by a non-root user
| File | Description |
|---|---|
| clear_logs.sh | Script for clearing common logs |
| crontab | Custom cronjob for root-executed jobs. Appended to root crontab after RaspiPass cron generation |
| firewall.rules | Firewall rules read on network start |
| iptables.sh | Script for setting iptables rules before export to firewall.rules |
| raspipass | The actual RaspiPass script |
All relevant web GUI files and folders are listed below.
| File/Folder | Resides in | Description |
|---|---|---|
| admintasks.php | html/ | Administrative tasks tab PHP code |
| admintasks.tpl | html/templates/ | Administrative tasks tab Smarty/HTML code |
| buttons/ | html/ | Folder containing button images |
| cache/ | html/ | Smarty system folder |
| config/ | html/ | Smarty system folder |
| config.php | html/ | Configuration tab PHP code |
| config.tpl | html/templates/ | Configuration tab Smarty/HTML code |
| error.php | html/ | Error page PHP code |
| errordirect.php | html/scripts/ | Externally-sourced rendering error handling for Smarty |
| error.tpl | html/templates/ | Error page Smarty/HTML code |
| footer_common.tpl | html/templates/ | Footer Smarty/HTML code for external sourcing |
| header_common.tpl | html/templates/ | Header Smarty/HTML code for external sourcing |
| head_menu.php | html/ | Head menu frame PHP code |
| head_menu.tpl | html/templates/ | Head menu frame Smarty/HTML code |
| home.php | html/ | Front page PHP code |
| home.tpl | html/templates/ | Front page Smarty/HTML code |
| .htaccess | html/ | Used to set options for site viewing (mainly no caching) |
| index.php | html/ | Main page PHP code |
| index.tpl | html/templates/ | Main page Smarty/HTML code |
| locales.php | html/scripts/ | Script to fetch available system locales and identify current locale |
| logo.png | html/ | Raspipass logo |
| logviewer.php | html/ | Log viewer tab PHP code |
| logviewer.tpl | html/templates/ | Log viewer tab Smarty/HTML code |
| maclist.php | html/ | MAC address list tab PHP code |
| maclist.tpl | html/templates/ | MAC address list tab Smarty/HTML code |
| raspipass.css | html/ | RaspiPass style sheet |
| reboot.php | html/ | Reboot script |
| save_config.php | html/ | Script called to save config in web GUI |
| save_maclist.php | html/ | Script for saving MAC address/SSD list |
| scripts/ | html/ | Directory containing scripts & data sourced by the Web GUI |
| set_locale.php | html/ | Script for setting system locale |
| setup.php | html/ | Contains Smarty configuration |
| shutdown.php | html/ | System shutdown script |
| smarty/ | html/ | Directory containing Smarty |
| start_ap.php | html/ | Script for manually raising StreetPass Relay AP |
| stub.php | html/ | Stub page PHP code |
| stub.tpl | html/templates/ | Stub page Smarty/HTML code |
| templates/ | html/ | Smarty templates (HTML/Smarty code) |
| templates_c/ | html/ | Smarty working directory |
| update.php | html/ | Update script |
| wificountries.php | html/scripts/ | Source of array of WiFi channels/countries |
/git contains the active mirror copies of the above /raspipass, /raspi_secure and /var/www/html directories in fully-editable form (777 permissions), as well as the files below. For ease of editing (given the various file permissions in the 'live' directories) it's recommended to edit within the /git directory and then run the /git/scripts/copy_to_sysdirs.sh script as root to test.
| File | Description |
|---|---|
| README.md | GitHub repo readme file |
| scripts/copy_to_sysdirs.sh | |
| scripts/filepermissions | CSV list of files, owners and security - used by copy_to_gitdir.sh |
| scripts/set_defaults.sh | Script to run before distribution/Git push to clear logs and set RaspiPass to default config |
| scripts/set_interfaces | Script to apply RaspiPass bridge config to /etc/network/interfaces |
RaspiPass has some of its files secured against user access, as well as having its main script root-executable, as the hostapd process requires root access for hardware control.
The following security changes have been made from the default Raspbian configuration:
- raspi user added, with passworded sudo access
- apache www-data user added with NOPASSWD sudo privileges (not root group privileges)
- iptables locked down to only permit the following:
- Loopback
- DHCP (to allow the 3DS to get an IP address)
- SSH
- HTTP in to RaspiPass device (for web GUI)
- HTTP requests originating from RaspiPass (no forwarding)
- DNS (to resolve StreetPass Relay servers)
- NTP (for clock updating)
- CIFS (For Windows name resolution)
- GitHub access (for pushing/pulling)
- StreetPass Relay server access
- Already-established connections