Glossary
A-Z definitions of every term used in Portlama documentation, each explained at three levels of depth.
In Plain English
This page is a dictionary for Portlama. Every technical term you encounter in the documentation is defined here. Each entry has three parts:
- Plain English: A non-technical explanation anyone can understand
- Technical: The precise definition for developers
- Where it appears: Where you encounter this term in Portlama
If you are reading documentation and hit an unfamiliar term, this is the place to look.
Terms
Atomic Write
Plain English: A way of saving a file that guarantees it is either fully saved or not saved at all — never half-written.
Technical: A write pattern where data is first written to a temporary file (.tmp), flushed to disk (fsync), and then renamed over the target file. The rename system call is atomic on POSIX filesystems, so readers never see a partially written file. This prevents corruption if the process crashes mid-write.
Where it appears: Portlama uses atomic writes for panel.json, tunnels.json, and Authelia's users.yml. This is critical because Authelia reads users.yml on every authentication request — a half-written file would break login.
Authelia
Plain English: The bouncer at the door of your tunneled apps. When someone visits your app through the tunnel, Authelia asks for a username and a time-based code from their phone before letting them in.
Technical: Authelia is a lightweight open-source authentication server written in Go. It implements forward authentication — nginx delegates auth decisions to Authelia before proxying requests to the backend. Portlama uses Authelia's file-based user store (users.yml) with bcrypt password hashing and TOTP (Time-based One-Time Password) for two-factor authentication. It runs as a systemd service binding 127.0.0.1:9091 and uses approximately 25MB of RAM.
Where it appears:
- Installed during the onboarding provisioning step
- Manages user authentication for all tunneled apps on port 443
- Users are created and managed through the panel's Users page
- Configuration lives at
/etc/authelia/configuration.yml - User database lives at
/etc/authelia/users.yml
bcrypt
Plain English: A way of scrambling passwords so that even if someone steals the password file, they cannot figure out the original passwords.
Technical: A password hashing function based on the Blowfish cipher. It is intentionally slow (configurable cost factor) to resist brute-force attacks. Each hash uses approximately 4KB of RAM. Portlama mandates bcrypt over argon2id because argon2id uses ~93MB per hash, which causes out-of-memory kills on the 512MB droplet.
Where it appears:
- Authelia's
users.ymlstores bcrypt-hashed passwords - The panel server generates bcrypt hashes when creating or updating users
- This is a hard constraint — argon2id must never be used on the 512MB droplet
CA (Certificate Authority)
Plain English: A trusted stamp-maker. The CA creates a master stamp, and any certificate it stamps is considered trustworthy. In Portlama, the CA is self-created and exists only on your droplet.
Technical: A Certificate Authority issues and signs digital certificates. Portlama generates a self-signed CA during installation (4096-bit RSA key, 10-year validity) stored at /etc/portlama/pki/ca.key and /etc/portlama/pki/ca.crt. This CA signs client certificates for mTLS admin authentication. nginx is configured to trust only certificates signed by this CA. The CA is distinct from Let's Encrypt, which is used for public-facing TLS.
Where it appears:
- Generated by the installer's mTLS certificate task
- Referenced in
/etc/nginx/snippets/portlama-mtls.confasssl_client_certificate - Used to sign client certificates for admin panel access
- Can issue additional client certificates through the panel's Certificates page
certbot
Plain English: A robot that automatically gets and renews free HTTPS certificates from Let's Encrypt, so your domain shows the padlock icon in browsers.
Technical: The official ACME client for Let's Encrypt. Portlama uses certbot with the nginx plugin (python3-certbot-nginx) to obtain and auto-renew TLS certificates for the configured domain and its wildcard subdomains. Certificates are stored in /etc/letsencrypt/. A systemd timer (certbot.timer) runs renewal checks twice daily.
Where it appears:
- Installed by the installer as a system package
- Runs during onboarding provisioning to issue the first certificate
- Auto-renews via
certbot.timersystemd timer - Monitored on the panel's Certificates page
Chisel
Plain English: A program that creates a secret tunnel between your machine and the droplet. Web traffic goes through this tunnel disguised as normal HTTPS traffic, so firewalls and ISP filters do not block it.
Technical: Chisel is an open-source tunneling tool written in Go that creates TCP tunnels over WebSocket connections. In Portlama, the Chisel server runs on the droplet (binding 127.0.0.1:9090) and the Chisel client runs on your machine (macOS or Linux). The tunnel is established as a WebSocket upgrade inside a standard HTTPS connection, making it indistinguishable from normal web traffic to deep packet inspection (DPI) systems. The server uses approximately 20MB of RAM.
Where it appears:
- Server binary:
/usr/local/bin/chisel - Server systemd unit:
chisel.service - Installed during onboarding provisioning
- Client runs on your machine (launchd on macOS, systemd on Linux)
- Configured when tunnels are created through the panel
Client Certificate
Plain English: A digital ID card that lives in your browser. When you visit the admin panel, your browser shows this ID card to prove you are the admin. No username or password needed — the ID card is the proof.
Technical: An X.509 certificate installed in the browser's certificate store. During TLS handshake, the server requests the client's certificate (ssl_verify_client on), and the browser presents it. If the certificate is signed by the trusted CA, the connection proceeds. If not, the TLS handshake fails before any HTTP traffic occurs. Portlama generates a PKCS12 (.p12) bundle containing the client certificate, private key, and CA certificate for easy browser import.
Where it appears:
- Generated during installation as
/etc/portlama/pki/client.p12 - Imported into the admin's browser during setup
- Verified by nginx on every request to port 9292
- Can be rotated through the panel's Certificates page
DNS (Domain Name System)
Plain English: The internet's phone book. When you type example.com in your browser, DNS looks up the phone number (IP address) of the server that hosts that domain.
Technical: A hierarchical naming system that translates human-readable domain names to IP addresses. Portlama requires two DNS records: an A record for the base domain and a wildcard A record (*.example.com) pointing to the droplet's IP. The wildcard allows creating tunnels like app.example.com without adding individual DNS records for each subdomain.
Where it appears:
- Configured during the onboarding DNS verification step
- The panel verifies DNS resolution before proceeding with provisioning
- Required records:
A example.com → <droplet-ip>andA *.example.com → <droplet-ip>
Droplet
Plain English: DigitalOcean's name for a virtual server in the cloud. Portlama uses the cheapest one available as a relay point.
Technical: A virtual machine instance on DigitalOcean's infrastructure. Portlama requires the $4/month tier (512MB RAM, 1 vCPU, 10GB SSD) running Ubuntu 24.04 LTS. While DigitalOcean is the reference platform, Portlama works on any VPS provider with a public IP and Ubuntu 24.04.
Where it appears:
- Created by the user as the first step of setup
- Hosts all Portlama server-side components
- Referenced throughout documentation as "the droplet" or "the VPS"
execa
Plain English: A helper library that lets Node.js run system commands (like nginx -t or systemctl restart) in a safe, reliable way.
Technical: A Node.js library for executing external processes. It replaces child_process.exec/spawn with a promise-based API, proper error handling, and array-based argument passing (preventing shell injection). Portlama uses execa exclusively for all system command execution — child_process is never used directly.
Where it appears:
- Used throughout
create-portlamainstaller tasks - Used in
panel-serverbusiness logic (lib/) for nginx, certbot, systemctl operations - Always called with array arguments:
execa('nginx', ['-t']), never string interpolation
fail2ban
Plain English: A security guard that watches log files. If someone tries to guess passwords too many times, fail2ban blocks their IP address for an hour.
Technical: An intrusion prevention framework that monitors log files for patterns indicating brute-force attacks and temporarily bans offending IP addresses using firewall rules. Portlama configures two jails: sshd (monitors /var/log/auth.log) and nginx-http-auth (monitors /var/log/nginx/error.log). Both jails ban IPs for 3600 seconds (1 hour) after 5 failed attempts. Uses approximately 35MB of RAM.
Where it appears:
- Installed and configured during the installer's hardening step
- Configuration:
/etc/fail2ban/jail.d/portlama.conf - Runs as a systemd service:
fail2ban.service
Fastify
Plain English: The engine that powers the Portlama admin panel's backend. It receives requests from your browser and responds with data, like a restaurant kitchen receiving orders and sending out dishes.
Technical: A high-performance Node.js web framework. Portlama uses Fastify for the panel server REST API because it provides built-in schema validation (used with Zod), native WebSocket support (for live log streaming), and a structured plugin system. The panel server binds to 127.0.0.1:3100 and is accessed only through the nginx reverse proxy. Routes handle HTTP concerns only; business logic lives in lib/ modules.
Where it appears:
- Panel server entry point:
packages/panel-server/src/index.js - Routes:
packages/panel-server/src/routes/ - Business logic:
packages/panel-server/src/lib/ - Runs as the
portlama-panelsystemd service
Forward Auth
Plain English: A security checkpoint. Before nginx lets a visitor reach your app, it first asks Authelia: "Is this person allowed in?" If Authelia says no, the visitor sees a login page instead of your app.
Technical: An authentication pattern where the reverse proxy (nginx) makes a subrequest to an authentication service before proxying the original request. If the auth service returns a success status code (2xx), nginx proceeds with the proxy. If it returns a 401/403, nginx redirects the client to a login page. nginx implements this with the auth_request directive pointing to Authelia's /api/verify endpoint.
Where it appears:
- Configured in nginx vhost files for tunneled apps (port 443)
- Authelia handles the verification at
127.0.0.1:9091 - Not used for the admin panel (which uses mTLS instead)
FQDN (Fully Qualified Domain Name)
Plain English: The complete address of a website, including all its parts. Like a full postal address compared to just a street name.
Technical: A domain name that specifies its exact location in the DNS hierarchy, including all labels up to the root. For example, myapp.example.com. is an FQDN (the trailing dot is the root, often omitted). In Portlama, each tunnel gets an FQDN like myapp.example.com that resolves to the droplet's IP through the wildcard DNS record.
Where it appears:
- Each tunnel creates a subdomain FQDN (e.g.,
myapp.example.com) - Used in nginx vhost
server_namedirectives - Used in Let's Encrypt certificate Subject Alternative Names
launchd
Plain English: The macOS system that automatically starts programs when your Mac boots up and restarts them if they crash. Portlama uses it to keep the tunnel client running permanently.
Technical: The macOS init system and service manager (equivalent to systemd on Linux). Portlama provides a launchd property list (.plist) file for the Chisel client that configures it to start at boot, auto-restart on failure, and run in the background. The plist is downloaded from the panel's Tunnels page after creating a tunnel.
Where it appears:
- Plist files are generated and downloadable from the Tunnels management page
- Installed to
~/Library/LaunchAgents/on the user's Mac - Manages the Chisel client process lifecycle
Let's Encrypt
Plain English: A free service that gives your domain an official HTTPS certificate, so browsers show the padlock icon and trust your site. Certificates renew automatically every 90 days.
Technical: A nonprofit Certificate Authority providing free, automated TLS certificates via the ACME protocol. Portlama uses Let's Encrypt through certbot to issue certificates for the configured domain and wildcard subdomains. Certificates have a 90-day validity period and are auto-renewed by the certbot.timer systemd timer. Let's Encrypt certificates are used for public-facing port 443 traffic; the admin panel on port 9292 uses a self-signed certificate instead.
Where it appears:
- Certificates issued during onboarding provisioning
- Stored in
/etc/letsencrypt/live/<domain>/ - Referenced in nginx vhost configurations for port 443
- Monitored on the Certificates management page
- Auto-renewed by
certbot.timer
Listr2
Plain English: A library that shows progress bars and checkmarks in the terminal while the installer runs, so you can see what is happening at each step.
Technical: A Node.js library for building terminal task lists with nested subtasks, progress indicators, and concurrent execution support. The Portlama installer uses Listr2 to orchestrate all installation tasks in a visually structured pipeline. Each task can have skip guards (for idempotency) and persistent output messages.
Where it appears:
- Used exclusively in
create-portlama(packages/create-portlama/src/index.js) - Each installer phase is a Listr2 task with nested subtasks
- Task files in
packages/create-portlama/src/tasks/return Listr2 subtask arrays
mTLS (Mutual TLS)
Plain English: A two-way ID check. Normally, only the website proves its identity to your browser (one-way TLS). With mTLS, your browser also proves its identity to the website using a client certificate. It is like both people showing ID at a door, not just the person entering.
Technical: Mutual Transport Layer Security extends standard TLS by requiring both parties to present certificates during the handshake. In Portlama, nginx on port 9292 is configured with ssl_verify_client on, meaning the TLS handshake fails before any HTTP traffic if the client does not present a valid certificate signed by the Portlama CA. This provides authentication at the transport layer — there is no login form to brute-force, no session cookies to steal, and no credentials transmitted over the wire.
Where it appears:
- Configured in
/etc/nginx/snippets/portlama-mtls.conf - Enforced on the admin panel vhost (port 9292)
- Client certificates generated during installation and importable as
.p12files - LXD (the Linux container manager) uses the same pattern, which inspired Portlama's approach
See also: Client Certificate, CA
nginx
Plain English: The traffic director. nginx sits at the front door of the droplet and decides where each request goes — admin panel requests go to the panel server, app requests go through the tunnel, and everything else gets blocked.
Technical: A high-performance HTTP reverse proxy, load balancer, and web server. In Portlama, nginx is the only process binding to public ports. It handles TLS termination (both Let's Encrypt and self-signed), mTLS client certificate verification, forward authentication with Authelia, WebSocket upgrades for Chisel and the panel API, and static file serving. It uses approximately 15MB of RAM.
Where it appears:
- Installed by the installer as a system package
- Listens on port 443 (tunnel vhosts) and port 9292 (admin panel)
- Vhost files:
/etc/nginx/sites-available/portlama-* - mTLS snippet:
/etc/nginx/snippets/portlama-mtls.conf - Always validated with
nginx -tbefore reloading
Onboarding
Plain English: The setup wizard that runs the first time you open the admin panel. It walks you through connecting your domain and installing the remaining components.
Technical: A multi-step wizard in the panel UI that transitions the system from FRESH state to COMPLETED state. The onboarding flow is: domain input, DNS verification, stack provisioning (Chisel, Authelia, certbot, nginx vhosts). Onboarding API endpoints are guarded by an onboarding middleware — they return 410 Gone after completion, while management endpoints return 503 Service Unavailable before completion.
Where it appears:
- Panel client:
packages/panel-client/src/pages/onboarding/ - Panel server routes:
packages/panel-server/src/routes/onboarding/ - State tracked in
panel.jsonunderonboarding.status - States:
FRESH→DOMAIN_SET→DNS_READY→PROVISIONING→COMPLETED
PKCS12
Plain English: A file format (ending in .p12) that bundles a certificate and its private key together in one password-protected file. It is the format browsers understand for importing client certificates.
Technical: A binary archive format (also known as PFX) defined by RFC 7292 for storing a private key, certificate, and optionally the CA certificate chain, all encrypted with a password. Portlama generates the .p12 bundle using OpenSSL with legacy-compatible encryption (PBE-SHA1-3DES) and MAC algorithm (sha1) to ensure compatibility with macOS Keychain, which does not support newer encryption modes for PKCS12 import.
Where it appears:
- Generated during installation at
/etc/portlama/pki/client.p12 - Password stored at
/etc/portlama/pki/.p12-password(mode 0600) - Downloaded by the admin via SCP after installation
- Imported into the browser for mTLS authentication
Panel (Panel Server / Panel Client)
Plain English: The admin control center. The panel server is the backend brain that manages everything, and the panel client is the visual interface you see in your browser.
Technical: The panel consists of two packages. The panel server is a Fastify REST API running as the portlama-panel systemd service, binding 127.0.0.1:3100. It handles all business logic: nginx vhost management, Chisel tunnel configuration, Authelia user management, certbot operations, and system monitoring. The panel client is a React 18 SPA built with Vite and Tailwind CSS, served as static files from /opt/portlama/panel-client/dist/. It communicates with the panel server via /api/* routes proxied through nginx.
Where it appears:
- Server:
packages/panel-server/, deployed to/opt/portlama/panel-server/ - Client:
packages/panel-client/, built to/opt/portlama/panel-client/dist/ - Accessible at
https://<ip>:9292(through nginx mTLS proxy)
TOTP (Time-based One-Time Password)
Plain English: The six-digit code that changes every 30 seconds on your phone (in apps like Google Authenticator or Authy). It is the second factor in two-factor authentication — even if someone knows your password, they also need your phone.
Technical: An algorithm defined in RFC 6238 that generates short-lived codes from a shared secret and the current time. The server and the client (authenticator app) independently compute the same code because they share the same secret and clock. Portlama uses TOTP through Authelia for all tunneled app authentication. The shared secret is provisioned via QR code during user creation.
Where it appears:
- Authelia manages TOTP enrollment and verification
- QR codes shown during onboarding completion and user creation in the panel
- Used for logging into tunneled apps (not the admin panel, which uses mTLS)
Tunnel
Plain English: A private passage between your machine and the droplet. Web traffic travels through this passage so your local app is accessible from the internet, even though your machine is behind a firewall.
Technical: A reverse TCP tunnel established by the Chisel client connecting outbound from your machine to the Chisel server on the droplet via a WebSocket-over-HTTPS connection. The "reverse" means the server-side port is forwarded to the client-side port. Each tunnel maps a subdomain (e.g., myapp.example.com) to a local port (e.g., localhost:8001). The tunnel is persistent — the Chisel client automatically reconnects on network interruptions.
Where it appears:
- Created and managed through the panel's Tunnels page
- Definitions stored in
/etc/portlama/tunnels.json - Each tunnel gets an nginx vhost and a Chisel port mapping
- Client-side managed by Chisel client (launchd plist on macOS)
UFW (Uncomplicated Firewall)
Plain English: A lock on the droplet's doors. UFW closes all doors except the three Portlama needs: SSH (port 22), web traffic (port 443), and the admin panel (port 9292). Everything else is blocked.
Technical: A frontend for Linux's iptables/nftables firewall. Portlama configures UFW to deny all incoming traffic by default and allow only three ports: 22/tcp (SSH), 443/tcp (HTTPS for tunneled apps), and 9292/tcp (admin panel). Outgoing traffic is unrestricted (needed for package updates, Let's Encrypt validation, etc.).
Where it appears:
- Configured during the installer's hardening step
- Rules:
ufw allow 22/tcp,ufw allow 443/tcp,ufw allow 9292/tcp - Status viewable with
ufw status
Vhost (Virtual Host)
Plain English: A way for nginx to serve different websites from the same server. Each tunnel gets its own vhost, so blog.example.com and app.example.com are handled differently even though they share the same IP address.
Technical: An nginx server block that matches requests by server_name (the Host header). Portlama creates one vhost per tunnel at /etc/nginx/sites-available/portlama-tunnel-<subdomain> and symlinks it to /etc/nginx/sites-enabled/. The admin panel also has its own vhost at /etc/nginx/sites-available/portlama-panel-ip. After any vhost change, the panel server runs nginx -t to validate the configuration before reloading — if validation fails, the change is rolled back.
Where it appears:
- Created automatically when tunnels are added through the panel
- Files:
/etc/nginx/sites-available/portlama-* - Enabled via symlinks in
/etc/nginx/sites-enabled/ - Always validated with
nginx -tbefore activation
WebSocket
Plain English: A persistent two-way communication channel between a browser (or program) and a server. Unlike normal web requests where you ask and get a response, a WebSocket stays open so both sides can send messages at any time.
Technical: A protocol defined in RFC 6455 that provides full-duplex communication over a single TCP connection, initiated via an HTTP upgrade handshake. Portlama uses WebSockets in two places: (1) Chisel tunnels use WebSocket-over-HTTPS to carry TCP traffic between the local client and the droplet server, and (2) the panel server uses WebSockets for real-time features like live log streaming and provisioning progress. The key advantage of WebSocket-over-HTTPS for tunneling is that it is indistinguishable from normal web traffic, bypassing DPI and corporate firewalls.
Where it appears:
- Chisel client-server communication (tunnel data transport)
- Panel server API (live log streaming, provisioning progress)
- nginx is configured with
proxy_http_version 1.1andUpgradeheaders to support WebSocket proxying
Zod
Plain English: A validation library that checks whether incoming data has the right shape and type before the server processes it. Like a form that rejects submissions with missing fields.
Technical: A TypeScript-first schema validation library. Portlama uses Zod at the Fastify route level to validate all incoming API request bodies, query parameters, and URL parameters. Schemas are defined inline in route files and used with Fastify's schema-first validation hooks. This ensures that business logic in lib/ modules receives well-typed, validated data.
Where it appears:
- Used in
packages/panel-server/src/routes/for request validation - Every API endpoint validates inputs before processing
- Error responses follow a consistent
{ error: string }format for validation failures
Quick Reference
Alphabetical Index
| Term | One-Line Summary |
|---|---|
| Atomic Write | Write to temp file, then rename — never half-written |
| Authelia | TOTP 2FA authentication server for tunneled apps |
| bcrypt | Password hashing algorithm (~4KB RAM per hash) |
| CA | Self-signed certificate authority for mTLS |
| certbot | ACME client for free Let's Encrypt certificates |
| Chisel | WebSocket-over-HTTPS tunnel (Go binary) |
| Client Certificate | Browser-based digital ID for admin panel access |
| DNS | Maps domain names to IP addresses |
| Droplet | DigitalOcean virtual machine ($4/mo minimum) |
| execa | Node.js library for safe shell command execution |
| fail2ban | Brute-force protection (bans IPs after failed attempts) |
| Fastify | Node.js web framework powering the panel API |
| Forward Auth | nginx delegates auth checks to Authelia |
| FQDN | Complete domain name (e.g., myapp.example.com) |
| launchd | macOS service manager for Chisel client |
| Let's Encrypt | Free TLS certificate authority (auto-renewing) |
| Listr2 | Terminal task runner for the installer |
| mTLS | Two-way TLS — both server and client prove identity |
| nginx | Reverse proxy, TLS termination, sole public-facing service |
| Onboarding | First-run wizard: domain, DNS, provisioning |
| PKCS12 | .p12 file format for client certificate + key bundle |
| Panel | Admin UI (React SPA) + REST API (Fastify) |
| TOTP | Six-digit codes from authenticator apps |
| Tunnel | Reverse TCP tunnel from local machine to droplet via WebSocket |
| UFW | Firewall allowing only ports 22, 443, 9292 |
| Vhost | nginx server block routing by domain name |
| WebSocket | Full-duplex communication protocol (RFC 6455) |
| Zod | Schema validation for API inputs |
Port Quick Reference
| Port | Service | Auth Method |
|---|---|---|
| 22 | SSH | Key-based (fail2ban protected) |
| 443 | Tunneled apps | Authelia (username + TOTP) |
| 9292 | Admin panel | mTLS (client certificate) |
| 3100 | Panel server | Localhost only (no auth needed) |
| 9090 | Chisel server | Localhost only |
| 9091 | Authelia | Localhost only |
Key File Paths
| Path | Contents |
|---|---|
/etc/portlama/panel.json | Main configuration |
/etc/portlama/tunnels.json | Tunnel definitions |
/etc/portlama/pki/ | All certificates and keys |
/opt/portlama/ | Panel server + client |
/var/www/portlama/ | Static site files |
/etc/nginx/sites-available/portlama-* | nginx vhosts |
/etc/authelia/ | Authelia config + user database |
Related Documentation
- What is Portlama? — project overview
- How It Works — architecture and data flow
- Quick Start — from zero to first tunnel
- Tunneling — deep dive on Chisel tunnels
- mTLS — client certificate authentication
- Authentication — Authelia and TOTP
- Security Model — defense-in-depth layers