Installation & administration

PortGuard Console manual

Install Console, connect endpoints, and manage your deployment.

Choose the operating system and architecture of the computer that will host Console. Endpoint software is covered in the Agent manual.

Before you begin

• Console is the management application you open in a browser.
• Agent runs on each managed endpoint and connects to Console using its full server URL.
• Version and build identify the installed application and package revision. All platforms share a product version; build numbers identify package revisions within a platform.

Use a fixed LAN address or a DHCP reservation for the Console host. You need administrator access to install services and configure inbound network access.

Dashboard, disk tree and automatic USB monitoring

The Dashboard summarizes online endpoints, devices needing attention, active alerts, USB interfaces from fresh reports, available internal capacity, operating-system distribution and recorded activity. Links lead to the corresponding report. Offline or stale reports are not presented as current USB attachments.

Disk Capacity shows one primary row per hostname with aggregate capacity, usage and free space. Expanded C:, D: and other volume rows use smaller text, tighter spacing and a shallow indent so the hostname remains visually dominant. Select its arrow to expand or collapse the volume detail. Shared pools count once; CSV exports retain volume detail.

Console requests a read-only USB status check at the configured interval while each compatible Agent sends heartbeat. The default interval is 60 seconds and can be changed under Settings → USB monitoring (30–3600 seconds). Existing queued commands are not duplicated. USB Devices refreshes the displayed report every five seconds; Check USB remains available.

A newly observed USB storage interface creates an alert, a red alert count and an in-app notification. A later verified report without that interface resolves the alert. Failed, partial or stale reports do not claim disconnection. Detection is periodic: a brief connection between checks may be missed. USB alerts appear in Console and can be forwarded to the configured central log server; SMTP email remains for capacity alerts.

Testing: capacity reports, alerts and Console approval

Linux x86-64 Testing: Console 0.2.2 build 0008. A red badge on Enroll agents shows how many requests await administrator approval. It refreshes about every five seconds while the page is visible, including while the enrollment dialog is closed, and clears after the requests are approved, rejected or expired. Compact Windows, Linux and macOS icons identify endpoints and USB Devices. Hover an icon to read its operating system. OS details and search remain available. Disk capacity reports, usage/free percentages, threshold alerts, optional SMTP email and Settings categories are included. It also supports administrator-approved Agent enrollment. The Linux x86-64 package below is build 0008. Raspberry Pi, ARMv6, macOS and Windows remain on their existing build 0006 packages; the Stable platform tabs remain available separately.

• Ubuntu x86-64: Installer · Package · SHA-256
• Raspberry Pi ARM64: Installer · Package · SHA-256
• Raspberry Pi ARMv6: Installer · Package · SHA-256
• macOS: Installer · Package · SHA-256
• Windows x64: Installer · Package · SHA-256

For an existing managed Linux Console, open Settings → Console updates → Testing, check for updates, and install build 0008. Raspberry Pi remains on Testing build 0006. For a new installation, use the matching installer and package above. Windows/macOS use their platform installer; native update testing is pending.

1. Update Console first, then install Linux Agent 0.1.8 Testing.
2. For a new device, provide the Console LAN address during Agent installation. It appears under Endpoints → Enroll agents as connected and awaiting approval.
3. Compare the installation ID with the Agent and choose Approve enrollment or Reject. Pending connections consume no seat. A valid license and a free seat are required for approval.
4. After approval, the Agent enrolls automatically and starts heartbeat. Existing enrolled Agents preserve identity on upgrade.

Requests expire after 24 hours. Older clients can use Legacy deployment file. Windows and macOS Testing Agents support Console approval; use the matching Agent manual and testing checklist. Remote Agent updates are not implemented.

Current release

Install Console for your host platform, activate your license, and enroll endpoints using a reusable deployment file. The current Stable release includes authenticated Agent connections, persistent identities, USB inventory and license-seat enforcement.

Use a trusted network for the default IP/HTTP installation. HTTP connections are not encrypted.

Install by platform

Choose the tab matching your Console host. Each tab provides the current Stable installer, matching archive and checksum. For an existing managed Linux/Pi installation, choose Stable in Console updates; a download alone does not update a running server.

curl -fLO https://portguard.kamindo.co/downloads/server/linux/0.2.2/build0001/install.sh
sudo bash install.sh https://portguard.kamindo.co/downloads/server/linux/0.2.2/build0001/portguard-console-0.2.2-build0001.tar.gz

curl -fLO https://portguard.kamindo.co/downloads/server/raspberry-pi/0.2.2/build0001/install.sh
sudo bash install.sh https://portguard.kamindo.co/downloads/server/raspberry-pi/0.2.2/build0001/portguard-console-0.2.2-build0001.tar.gz

curl -fLO https://portguard.kamindo.co/downloads/server/raspberry-pi-armv6/0.2.2/build0001/install.sh
sudo bash install.sh https://portguard.kamindo.co/downloads/server/raspberry-pi-armv6/0.2.2/build0001/portguard-console-0.2.2-build0001.tar.gz

curl -fLO https://portguard.kamindo.co/downloads/server/macos/0.2.2/build0001/install.sh
sudo bash install.sh https://portguard.kamindo.co/downloads/server/macos/0.2.2/build0001/portguard-console-0.2.2-build0001.tar.gz

Ubuntu installation

Requirements

Use a supported Ubuntu host with sudo access, an available HTTP port 80, and outbound access to the download portal and dependency repositories. Nginx serves Console; the backend listens locally on port 8100.

Install

1. Select the matching Ubuntu package above.
2. Run the installation command on the host.
3. Open http://IP-CONSOLE and create the initial administrator account.
4. Continue with license activation and Linux Agent enrollment.

If a managed Console installation already exists, use Settings → Console updates. The installer does not overwrite an existing managed deployment.

Verify the installation

curl -fsS http://127.0.0.1/api/v1/health
sudo systemctl status portguard-backend portguard-updater nginx --no-pager

The health response should contain "state":"ok". The application's footer shows its product version and build; display_version in the health response reports the same identity. The compatibility field version is used internally by the updater.

Raspberry Pi with Ubuntu ARM64

Use the Ubuntu ARM64 package on a host reporting aarch64. The installation and verification steps match Ubuntu. This package does not support 32-bit Raspberry Pi OS.

Raspbian ARMv6

Use the dedicated ARMv6 package for a host reporting armv6l on 32-bit Raspbian 13 with Python 3.13, including Raspberry Pi Model B+. The installer uses prebuilt, hash-verified dependencies. Do not substitute an ARM64 package.

cat /etc/os-release
uname -m
getconf LONG_BIT
python3 --version

Choose the Raspbian ARMv6 download above, run its installer, then verify the services as described for Ubuntu. Keep power and network connectivity available while dependencies are installed.

Create your administrator account

1. Open the Console address in a browser.
2. Enter an administrator username, password and password confirmation.
3. Sign in and open Settings to activate your license if required.
4. Continue with the license and enrollment workflow below; the deployment file carries the complete Console URL, including its port.

On reinstall, retained accounts remain available. Use the existing credentials rather than expecting the initial setup screen.

macOS installation

Install native Python 3.12 with venv support. If you use Homebrew, run the following as your regular user:

brew install python@3.12

Then run the macOS download command above with sudo. The installer uses the invoking user for the Console service. You may add --port 8181, --user USER, or --python /absolute/path/to/python3.12 when needed. Use native Python rather than a Rosetta interpreter on Apple Silicon.

Open http://localhost:8080 on the Mac. Other computers use http://IP-MAC:8080. Allow the chosen inbound TCP port in your firewall and keep the Mac awake for Agent connectivity.

curl -fsS http://127.0.0.1:8080/api/v1/health
sudo launchctl print system/co.kamindo.portguard.console
sudo tail -n 80 "/Library/Application Support/PortGuard Console/logs/console-error.log"

Uninstall or reinstall

The default uninstall retains the database and logs:

sudo bash "/Library/Application Support/PortGuard Console/uninstall.sh"

Back up retained data while the service is stopped before reinstalling. Use the same Mac account. To permanently remove saved data as well, run:

sudo bash "/Library/Application Support/PortGuard Console/uninstall.sh" --purge --yes

The purge option permanently deletes accounts and saved Console data. GUI updates are not available on macOS.

Windows installation

1. Download Windows x64 Setup and approve the administrator prompt.
2. Choose an unused HTTP port. The default is 8080.
3. Keep Allow access from devices on private/domain networks selected for LAN access.
4. Review the settings and select Install.
5. Open Console from the Finish page and sign in or create the initial administrator account.

Console runs as the PortGuardConsole Windows Service and starts automatically with Windows. Windows ARM64 and 32-bit systems are not supported by this package. The installer is not Authenticode-signed; Windows may display an unknown-publisher notice.

Firewall and LAN access

Other computers use http://IP-WINDOWS:8080, with the port selected during setup. The installer adds an inbound rule for the Console application on Private/Domain profiles. Public profiles are not opened automatically.

If Windows rejects the rule, select Try Again after correcting the problem, Continue to finish without a rule, or Cancel to cancel installation while keeping saved data. The error and Windows error code are recorded in %ProgramData%\Kamindo\PortGuard Console\logs\setup.log.

If no rule was added, open PowerShell as Administrator on the Console host and run the following, adjusting the port if necessary:

New-NetFirewallRule -DisplayName "PortGuard Console HTTP" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8080 -Program "$env:ProgramFiles\Kamindo\PortGuard Console\runtime\python.exe" -Profile Private,Domain

Use Get-NetConnectionProfile to check the network category. For a trusted LAN, select Private in Windows Settings → Network & Internet → connection properties. Test access from another Windows computer:

Test-NetConnection -ComputerName <IP-WINDOWS> -Port 8080

Organization policy, another firewall, or network isolation can still block access. Keep the exact error if rule creation fails; do not disable the firewall.

Files and service

Application files are under %ProgramFiles%\Kamindo\PortGuard Console. Saved data and logs are under %ProgramData%\Kamindo\PortGuard Console. Check http://localhost:8080/api/v1/health and inspect the service in Windows Services.

Uninstall or reinstall

1. Open Settings → Apps → Installed apps and select PortGuard Console → Uninstall.
2. Leave Permanently delete saved Console data and logs unchecked to keep accounts and data.
3. Complete uninstall, then run the new installer if reinstalling.

Selecting permanent removal deletes the saved database and logs. The Windows Agent is a separate application and is not removed. Manually created firewall rules require manual removal if the installer did not create them. GUI updates are not available on Windows.

Console updates

GUI updates are available for managed Ubuntu and Raspbian installations. Windows and macOS use the reinstall instructions above.

1. Sign in as an administrator and open Settings → Console updates.
2. Select Stable, then Check for updates.
3. Review the release notes. Update Console is enabled when a compatible newer package is available.
4. Confirm the update. A progress panel shows the current stage: queued, download, preparation and installation. It remains visible while Console restarts and waits for the server to reconnect. Dependency preparation can take several minutes.
5. After completion, Console refreshes the interface. If your session ends, select Sign in and check the result in Settings. Confirm that Agents reconnect.

Stable provides the current release. A build that is already installed is not offered for reinstallation. Updates require administrator confirmation and are not installed automatically. A fresh installation of the latest package correctly reports no newer update.

If activation fails, the updater attempts to restore the previous application and data snapshot. If recovery requires attention, contact your administrator and inspect the updater log. Do not delete the transaction journal to force another update. Restoring a snapshot can discard writes made during a failed activation.

When updating from an older interface, refresh the browser once after the server returns. The footer then shows the installed product version and build. The progress panel becomes available after installing a package that includes it.

Set up your deployment

Prepare your Console host, Linux endpoint, available license seat, and a USB storage device for verifying your configuration. The Console needs outbound HTTPS access to licensing.kamindo.co; the Agent needs access to the Console LAN address.

1. Issue a license

1. Open License Server. The licensing administrator signs in with the existing administrator token.
2. Enter an organization name, choose the required endpoint seats, and select Generate activation code.
3. Copy the code while it is displayed and deliver it privately to the Console administrator. One license is bound to one Console instance; issue a separate license for each Console tested.

See the License Server operator guide. Its seat total is the allocated license capacity, not live endpoint usage; actual usage is reported by Console.

2. Activate Console

1. Install from the platform tab above and open the Console LAN address. Create the administrator username, password and confirmation, then sign in.
2. Open Settings → License, enter the activation code and activate. Confirm the organization, seat limit and available seats.
3. Open Console from an address reachable by the endpoint, for example http://192.168.1.10 on Linux/Pi or http://192.168.1.10:8080 on Windows/macOS. Do not generate the deployment file through localhost for another computer.

Increase licensed seats

In Settings → License, enter a new activation code and choose Replace license / increase seats. Review the confirmation. The new entitlement sets the total seat capacity: replacing 10 with 20 gives 20 seats, not 30. The replacement must have the same or greater capacity. Existing Agent identities, credentials and used seats stay intact; no re-enrollment is needed. Invalid codes, a license bound to another Console, and lower capacity are rejected. License Server retires the previous code after successful replacement. If a response is interrupted, retry the same new code.

3. Enroll endpoints

Recommended: Console approval. Install the current Linux or Windows Agent, enter the reachable Console address, then review its installation UUID under Endpoints → Connected agents and approve it. Pending devices do not use seats. This flow does not require transferring JSON. A deployment profile is an optional alternative for managed rollout:

1. Open Endpoints → Enroll agents. Enter a profile name, select the allowed operating systems (Linux, Windows, macOS, or a combination), set the enrollment limit and expiry, then choose Download deployment file.
2. Maximum enrollments limits new registrations using this deployment file; it does not add license seats. A limit of 1,000 with a 50-seat license still allows only 50 enrolled endpoints in total. With 20 seats occupied, only 30 more can enroll.
3. Transfer portguard-deployment.json privately to the Linux endpoint. One profile supports multiple installations; each endpoint generates its identity automatically, without a manually entered per-device code.
4. Download and install the Linux Agent using that file. Follow the Agent guide for checksums, prerequisites, HTTP opt-in and service checks.

4. Verify authentication and storage control

1. Confirm both Agent services are active and the endpoint appears online. A new enrolled identity consumes one seat; a restart or upgrade preserves the same identity and seat.
2. Use Check Status. Confirm that the connected USB storage is visible to Linux. Seat allocation and protection are separate. Protected means the Agent confirms its block policy; Unprotected means access is allowed or protection is not confirmed. With the current Linux Agent, a saved Block policy stays Protected while no USB storage is attached; Allow is Unprotected.
3. Safely unmount the USB filesystem, then request Block USB Storage. Check the command result and device-access evidence.
4. Request Allow USB Storage and confirm access returns. Block applies to USB mass-storage interfaces without an ID whitelist, including external USB HDD/SSD; mounted or in-use devices are refused.

Change the Console IP or address

An enrolled Agent is bound to the Console instance, not permanently to its IP. Follow the Agent address-change instructions. The Agent checks that the new address exposes the same Console instance and accepts its existing identity before saving the change. A new installation of Console with a new database is a different instance and cannot be substituted by changing the URL. The Agent cannot discover a changed IP automatically.

5. Capacity and cleanup

With all licensed seats allocated, enrolling a new identity must fail. An offline endpoint still occupies its seat. Agent revocation through the administrator Agent-management API releases its seat; uninstalling alone does not. License Server revocation blocks future activation and does not remotely cancel an entitlement already stored by Console. Use a separate license for each Console instance.

Agent API documentation and body examples are available from Console at /docs and /openapi.json on a new installation. See the deployment checklist for expected outcomes and troubleshooting.

Connect and verify endpoints

Complete the enrollment workflow above, then open Endpoints → View details. Confirm the endpoint name, connection status, operating system, Agent version and observed storage policy. Agent and Console versions are independent.

Internal disk capacity

The Internal Disk column shows used/free percentages and reported capacity. Open View details → Internal Disk Capacity for total, used and available space per mounted internal volume. USB storage, external HDD/SSD and network drives are outside this inventory. Shared storage pools are counted once in the endpoint total.

Not reported means the Agent has not sent capacity data. Unavailable means no measurement is available; Partial report means some volumes could not be measured. Check the report time and online/offline state before interpreting the figures. Capacity reporting requires Linux Agent 0.1.6 or newer (including the current x86-64 / ARM64 installer). After updating Console, allow up to five minutes for the Agent to discover capacity support; subsequent samples refresh about once per minute. Windows/macOS Agent implementations must send the same inventory extension.

Disk capacity report

Available in the current Testing packages.

Open Disk Capacity from Management. Each row shows an endpoint and its volume or shared storage pool: total bytes, used bytes and percentage, available bytes and percentage, and the last collection time. Export CSV downloads the report for capacity planning. Endpoint details also display these percentages.

Shared pools are counted once; only internal mounted storage is included. Free/available space excludes filesystem reserves, so usage plus available space can be less than 100%. Missing measurements remain unavailable rather than appearing as zero. Offline endpoints and samples older than five minutes show stale data and do not trigger a new capacity alert.

Capacity thresholds and Alerts

An administrator opens Settings → Capacity alerts, enables monitoring and sets the used percentage (default 90%). Each capacity group is evaluated independently when an authenticated heartbeat arrives. At or above the threshold, one active alert appears under Alerts. Repeated heartbeats update the same alert instead of creating duplicates.

Usage must fall below the threshold minus two percentage points to resolve an alert; zero usage always permits recovery. This gap prevents repeated alerts around the threshold. Missing, partial or stale data does not imply recovery. Disabling monitoring resolves its active alerts with a monitoring-disabled reason. The Alerts page offers active, resolved and all views, timestamps and email delivery status.

Email notifications

Open Settings → Email. Enter SMTP host, port, connection security, sender, optional login and one or more comma-separated recipients. Choose STARTTLS (commonly port 587) or implicit TLS (commonly 465) according to your provider. Plain SMTP is available only for a trusted relay without login. Enable Receive capacity alerts by email and save, then choose Send test email. The page reports queued, sent or failed status; a successful test requires the receiver to confirm arrival.

A blank password retains the saved credential; use Remove saved SMTP password to clear it. API responses never return the password. The runtime SMTP key and database must be backed up together. Email is off by default, and settings are restricted to administrators.

New alert openings queue email; enabling email does not resend older alerts. Sending runs separately from Agent heartbeat. Failed delivery retries up to five times with increasing delay. An SMTP server accepting a message is not a guarantee of inbox delivery. Rare interruptions after SMTP acceptance can cause a retry and duplicate message; inspect delivery status and your mail server logs if needed.

Settings navigation

Settings is divided into My account, License, Users, Console updates, Capacity alerts, Email, USB monitoring and Log server. Administrative categories are hidden from basic users. Select a category to work in one section at a time.

Central log server

Open Settings → Log server and enter the hostname or IP address, listener port, transport and facility. TLS on port 6514 is the recommended default; the Console validates the server certificate using the host trust store. Choose TCP only on a trusted network. Save the configuration and select Send test log to check the transport.

PortGuard sends RFC 5424 records with JSON event data, UTF-8 encoding and RFC 6587 octet-counted TCP framing. TLS transport follows RFC 5425. Records include Console authentication and state-changing operations, capacity and USB alerts, email delivery results, and Agent API requests such as heartbeat, command polling and command results. Request bodies, passwords and bearer tokens are not forwarded.

Events queue in the Console runtime database and retry when the receiver is unavailable. Pending records are retained until a transport write succeeds; sent local copies are kept for seven days. A sent status confirms the TCP/TLS write, not that the receiver indexed the record. Use each record’s event_id to identify retries or deduplicate records.

Troubleshooting

• Local access works, remote access fails: verify the server IP, selected port, firewall profile and network isolation.
• Checksum verification fails: download the matching files again; do not bypass verification.
• The installed version appears unchanged: confirm the server address, refresh the browser and compare the footer with the health response. Downloading a package does not update a running installation.
• Installation fails: retain the failed step and service/setup logs. Do not delete saved data to work around a startup failure.

For support, provide the product version/build, operating system, architecture, failed step and exact error. Remove passwords and tokens from material you share.

Deployment operations

Restrict access to the intended network, keep regular backups, and schedule maintenance for updates. Keep old update backups until you have verified the new installation. Default installation uses HTTP; deployments requiring transport encryption need an appropriately configured reverse proxy or network protection.

Release information

Choose the current installer in your platform tab. Existing devices retain their identities and seats when updated using the documented procedure. Earlier download URLs remain available for existing installations.

Release information