User Manual

Get Started

MADMIN runs on Ubuntu 24.04 LTS. The automated installer handles everything: system packages, PostgreSQL, Python virtualenv, Nginx reverse proxy, iptables/ipset rules, and the systemd service.

Requirements

• Ubuntu 24.04 LTS (fresh install recommended)
• Root / sudo access
• Internet connectivity (for apt and pip packages)

Installation

1. Clone the repository: git clone https://github.com/EdoardoFiore/madmin.git
2. Enter the directory: cd madmin
3. Run the setup script with your chosen admin username and password:

   sudo bash scripts/setup-madmin.sh -u <username> -p '<password>'

Post-install access

Security checklist (post-install)

• Change the default admin password
• Enable TOTP 2FA for all admin accounts
• Confirm DEBUG=false in /opt/madmin/backend/.env
• Review default_rules.json firewall rules
• Replace the self-signed TLS cert in the Nginx config if needed
• Set up a remote backup destination in Settings → Backup

Useful commands

systemctl status madmin       # check service status
systemctl restart madmin      # restart after config changes
journalctl -u madmin -f       # follow live logs

1. Access

The portal is reachable via browser at the server address on port 7443 (HTTPS). The certificate is self-signed: the browser will show a security warning that can be dismissed by accepting the risk.

Login

Enter your username and password on the login screen and click Sign in. Credentials are set during installation.

Two-factor authentication (2FA)

If the account has 2FA enabled (or it is enforced globally), a second field appears after credentials where you enter the 6-digit code generated by your authenticator app (Google Authenticator, Authy, or similar).

2. Dashboard

The dashboard is the main screen and shows a real-time overview of system status.

The traffic chart updates automatically. Historical data is retained for the last 24 hours.

3. User Management

Accessible from the sidebar. Split into two parts: your own profile and management of other users (admin-only).

My Profile

Every user can update their own security settings regardless of permissions.

Change password

1. Enter current password, new password, and confirm.
2. Click Save Password.

Configure 2FA

1. Click Configure 2FA to open the wizard.
2. Scan the QR code with your authenticator app or enter the secret manually.
3. Enter the 6-digit code from the app to verify.
4. Save the provided backup codes in a safe place — they allow access if you lose your device.
5. To disable 2FA, click Remove 2FA and confirm.

User Management (admins only)

The table shows all users with status, creation date, and assigned permissions.

Create a new user

1. Click New User.
2. Fill in: Username (3–50 chars, letters/numbers/hyphens/underscores), Email (optional), Password, Active, Superuser, Force 2FA.
3. Select the permissions to assign.
4. Click Save.

Core permissions

Each module adds its own permissions (e.g. wireguard.view, dhcp.manage).

4. Firewall

The firewall manages the machine's iptables rules, organised by table and chain.

Tables and Chains

Adding a Rule

1. Select table and chain.
2. Click Add Rule.
3. Fill in the relevant fields (irrelevant ones can be left empty).

Common fields

Additional fields — Filter

Additional fields — NAT

Rule ordering

Rules are evaluated top to bottom: the first match determines the outcome. Drag rows to reorder — order is saved automatically.

iptables preview

The Preview panel shows the exact iptables command that will be executed for the selected rule.

Import / Export

Chain rules can be exported to JSON and re-imported on another system using the dedicated buttons.

5. Network Interfaces

Shows all physical interfaces with real-time statistics: status, speed, configuration type (DHCP or Static), primary / secondary IPs, IPv6, MAC, MTU, traffic counters and error counts.

WAN interface (eth0)

The WAN interface is read-only — it cannot be configured from the portal.

Configure an interface (non-WAN)

1. Click the gear icon on the interface card.
2. Choose DHCP (automatic) or Static (enter IP CIDR, gateway, DNS).
3. Optionally set a custom MTU.
4. Click Save, then Apply Netplan.

6. Modules

Modules are optional components that extend MADMIN. They must first be activated from the Modules section, after which they appear in the sidebar menu.

Activate / Deactivate a Module

1. Go to Modules in the sidebar.
2. Click Activate — the system installs dependencies and initialises the database.
3. Click Deactivate to disable it and remove its data.

7. Crontab (Scheduled Tasks)

Schedule automatic execution of commands at regular intervals.

Add a Task

1. Click New Task.
2. Define the schedule via Preset (predefined list) or Manual (5 cron fields: Minute Hour Day Month Weekday).
3. Enter the Command to run (absolute path recommended).
4. Enable or disable the task with the toggle.
5. Click Save.

Cron expression examples

0 2 * * *      → every day at 02:00
*/15 * * * *   → every 15 minutes
0 0 1 * *      → first day of every month at midnight

8. Logs & Audit

Audit Log

Records every operation performed through the portal (who did what and when).

Available filters: Category (Writes / All / Reads), User, keyword search, Date range. Click a row to view the request payload. Export CSV downloads filtered logs as a spreadsheet.

System Log

Shows MADMIN service logs in real time (equivalent to journalctl). Options: line count, text filter, Hide AUDIT.

• Red: critical errors
• Orange: warnings
• Cyan: audit log entries
• Dark grey: HTTP access log entries

9. Settings

Customisation

• Company name: text in the menu and header (default: MADMIN)
• Primary colour: colour picker, propagated via CSS variable
• Theme: light or dark

Backup

• Export backup: archive with system configuration
• Import backup: restore from a previous backup file
• Scheduled backups: daily, weekly, or monthly to a local or remote destination (S3, FTP)

Security

• Enforce 2FA globally: all users must configure 2FA
• Token lifetime: session validity in minutes (default 720 = 12h)

Audit

• Log retention: days to keep audit logs (older entries are automatically pruned)

10. Common Configurations

Practical examples using the portal firewall.

10.1 DNAT — Port Forwarding (inbound traffic)

Scenario: connections to the public IP on port 8080 → internal server 192.168.1.10 port 80.

Where: Table NAT → Chain PREROUTING

10.2 SNAT — Change the outbound source IP

Scenario A — specific IP for an internal machine: traffic from 192.168.1.50 exits with secondary IP 1.2.3.4.

Where: Table NAT → Chain POSTROUTING

Scenario B — specific IP for a VPN: traffic from interface wg0 exits with secondary IP 1.2.3.4.

10.3 Masquerade — Dynamic NAT for LAN

Scenario: devices on 192.168.1.0/24 exit to the internet using the server's public IP (dynamic IP).

Where: Table NAT → Chain POSTROUTING

10.4 Block an IP or Network

Where: Table Filter → Chain INPUT

10.5 Allow only specific inbound ports

Scenario: allow only SSH (22) and HTTPS (443), drop everything else.

Where: Table Filter → Chain INPUT