Porta VM Helper Commands and Scripts

This page is the reference for the bash commands and shell scripts that ship with the Porta VM image. They are available from any shell on the VM — over SSH, or at the VirtualBox console — and are grouped by the task they help you accomplish.

• For a symptom-driven walk-through that uses these helpers in context, see the Porta VM Troubleshooting guide.
• For a quick-reference cheatsheet covering helpers, log paths, container internals, and monitoring URLs together, see the Porta VM Diagnostics Cheatsheet.

How to read this page

• Commands appear as bare names, like porta_check_version. These are bash shortcuts available on VM image 0.9.14.2 and newer. Type them at the prompt and press Enter.
• Scripts appear with their full path, like ~/scripts/setup_static_ip.sh. These are the underlying shell scripts and are available on all VM images. Run them by executing the full path.
• Available since indicates the earliest Porta VM image version that ships the helper. All means it has been there since the first release. Run porta_check_version (or read the VM image filename) to find your version.

Note

The ~ character is shorthand for the home directory of the user portavm, which is /home/portavm. Using ~ in place of /home/portavm works in most contexts; use the full path if you run into a problem.

Diagnostics

Helper	What it does	Available since
collect_data	Runs various diagnostics to gather system and app data. Results are stored under ~/logs/collected_data/YYYYMMDD/HH-SS/.	0.9.14.2+
porta_diag	Runs the full Porta servers diagnostics.	0.9.14.2+
view_hosts_file	Prints the contents of /etc/hosts.	0.9.14.2+
check_diskspace	Simple disk space check.	0.9.14.2+
check_diskspace_sorted	Disk space check sorted by size.	0.9.14.2+
docker_disk_usage	Docker disk usage by images, containers, and volumes.	0.9.14.2+
docker_volume_size <volume_name>	Inspects the size of a named Docker volume.	0.9.14.2+
~/scripts/vm_info.sh	Prints the VM’s hostname, IPv4 address, MAC address, and /etc/hosts contents.	All
~/scripts/porta-manager/check-conn-cache.sh	Shows the cached connections, the loaded in-memory connections, and the database connection cache for every Porta Manager container.	All

Versioning

Helper	What it does	Available since
porta_check_version	Prints Porta version information, including Laravel, PHP, MySQL, Redis, and OS.	0.9.14.2+
mngr_check_version	Prints Porta Manager version information.	0.9.14.2+
~/scripts/porta-manager/check-manager-version.sh	Underlying script for mngr_check_version.	All

Logs

Each Porta log helper has a paired _follow variant that tails the file (equivalent to tail -f) instead of dumping its current contents.

Helper	What it shows	Available since
porta_laravel_logs / porta_laravel_logs_follow	/var/www/storage/logs/laravel-YYYY-MM-DD.log from the porta container.	0.9.14.2+
porta_php_errors / porta_php_errors_follow	/var/log/php/errors.log from the porta container.	0.9.14.2+
porta_horizon_logs / porta_horizon_logs_follow	/var/www/logs/horizon.log — queue workers and sequence playout.	0.9.14.2+
porta_task_logs / porta_task_logs_follow	/var/www/logs/default_tasks.log — scheduled tasks, database backups, socket checks.	0.9.14.2+
porta_main_db_logs / porta_main_db_logs_follow	MySQL error log on this machine, when it is the main machine.	0.9.14.2+
porta_backup_db_logs / porta_backup_db_logs_follow	MySQL error log on this machine, when it is the backup machine.	0.9.14.2+
porta_arbiter_db_logs / porta_arbiter_db_logs_follow	MySQL error log on this machine, when it is the arbiter machine.	0.9.14.2+
mngr_app_logs	Porta Manager app container logs.	0.9.14.2+
mngr_horizon_logs	Porta Manager installer wizard processing logs.	0.9.14.2+
mngr_task_logs	Porta Manager background task runner logs.	0.9.14.2+
~/scripts/porta-manager/view-logs.sh [container] [lines]	Underlying script for the mngr_*_logs commands. [container] is app, horizon, or task. [lines] is a line count, or f to follow.	All

Note

On older VM images that don’t have the bash shortcuts, use view-logs.sh directly. For example, ~/scripts/porta-manager/view-logs.sh app 300 tails the last 300 lines of the manager app container’s log, and ~/scripts/porta-manager/view-logs.sh horizon f follows the horizon container’s log.

Replication

Helper	What it does	Available since
porta_group_status	Shows the group replication status as reported by this machine.	0.9.14.2+
porta_all_group_status	Runs the same status query against every machine in the group using the entries in /etc/hosts. Each VM’s /etc/hosts must be correct for this to work.	0.9.14.2+
porta_start_repl	Runs START GROUP_REPLICATION on this machine.	0.9.14.2+
porta_stop_repl	Runs STOP GROUP_REPLICATION on this machine.	0.9.14.2+
porta_bootstrap	Bootstraps the replication group from this machine. Check first with porta_all_group_status — only run this if no other member is already primary.	0.9.14.2+
porta_set_bootstrap_ON	Persists the bootstrap flag as ON. This machine will always set itself as primary on startup. Useful only for single-VM setups — never use it on a multi-VM replication group, as it can cause split-brain.	0.9.14.2+
porta_set_bootstrap_OFF	Persists the bootstrap flag as OFF. This is the default state for a Porta VM.	0.9.14.2+
~/scripts/porta/view-ALL-group-repl-status.sh	Underlying script for porta_all_group_status.	All

Database backups

Helper	What it does	Available since
porta_backup_db	Creates a backup of the Porta database. The resulting ZIP archive is saved inside the porta container at /var/www/storage/app/Porta-Backups.	0.9.14.2+
porta_restore_db	Restores the Porta database from a backup. Prompts with a list of locally available dumps.	0.9.14.2+
porta_db_dump [db_container_name] [db_name]	Runs a raw mysqldump. Defaults to porta-db and the porta database.	0.9.14.2+
porta_db_restore [db_container_name] [db_name]	Restores a database from a mysqldump. Defaults to porta-db and the porta database. Prompts with a list of locally available dumps.	0.9.14.2+
porta_reset_db	Destructive — wipes all data on this machine and recreates the database from migrations. Used as the last-resort step in disaster recovery.	0.9.14.2+

Note

Automatic backups run every three hours on a non-primary machine — usually the arbiter — and are saved inside the porta container at /var/www/storage/app/Porta-Backups. Filenames look like arbiter-machine-mysql-3-backup-YYYY-MM-DD-HH-mm-ss.zip.

For full backup and recovery procedures, see Porta VM Disaster Backup and Restore.

Scheduler playout

These helpers query the same Scheduler tables but on different machines in the replication group. Use the variant that matches the machine you are currently on — for example, run porta_playouts from the main machine, porta_backup_playouts from the backup machine.

Helper	What it shows	Available since
porta_playouts	Last 50 Scheduler playouts, including the currently active and next entries. Main machine only.	0.9.14.2+
porta_playout_history	Last 50 Scheduler playout history items. Main machine only.	0.9.14.2+
porta_backup_playouts	Last 50 Scheduler playouts. Backup machine only.	0.9.14.2+
porta_backup_playout_history	Last 50 Scheduler playout history items. Backup machine only.	0.9.14.2+
porta_arbiter_playouts	Last 50 Scheduler playouts. Arbiter machine only.	0.9.14.2+
porta_arbiter_playout_history	Last 50 Scheduler playout history items. Arbiter machine only.	0.9.14.2+

VM lifecycle

Helper	What it does	Available since
~/scripts/reset_identity.sh	Picks a new hostname and unique machine ID, updates /etc/hosts, and reboots. Run this after importing the VM image to a second or third host so the copies don’t share an identity. See Manually Resetting the Identity of a Porta On Prem VM.	All
~/scripts/setup_static_ip.sh	Sets a static IP via netplan. The Porta VM PowerShell setup script does this automatically — only run manually if setup failed mid-flight. See Manually Setting Up a Static IP.	All
~/scripts/disable_static_ip.sh	Disables the static IP configuration by renaming /etc/netplan/99-portacfg.yaml. The VM will fall back to DHCP on next boot.	All
~/scripts/reset_dhcp.sh	Forces a new DHCP lease and clears cached leases. Only meaningful when the VM is not using a static IP.	All
~/scripts/static_ip_info.sh	Prints the current netplan static IP configuration.	All
~/scripts/setup_shared_folders.sh	Prepares the VM side of a VirtualBox shared folder for file export to Windows. See Porta On Prem VM Windows Shared Folder.	All

Warning

~/scripts/setup_static_ip.sh and ~/scripts/disable_static_ip.sh restart networking on the VM. Run them from the VirtualBox console, not over SSH. If executed over SSH, the connection drops when networking restarts and the script fails mid-flight.

Porta Manager lifecycle

Helper	What it does	Available since
update_manager (alias install_manager)	Downloads the latest available Porta Manager build and runs the installer. Automatically runs backup-env.sh first so APP_KEY is preserved across the update.	All
mngr_init_user	Initialises the first Porta Manager admin user. Only needed after a full Porta Manager database wipe.	0.9.14.2+
mngr_backup_env	Copies the .env file from the porta-manager-app container to ${MNGR_CONFIG_DIR}/.env to preserve APP_KEY between updates. Runs automatically when calling update_manager.	0.9.14.2+
mngr_restore_env	Restores the preserved .env file from ${MNGR_CONFIG_DIR}/.env back into the porta-manager-app container.	0.9.14.2+
mngr_recreate	Recreates the Porta Manager containers from their existing images, preserving data volumes. Useful if the VM’s IP changed without running Fix IP Settings in the Porta Manager dashboard.	0.9.14.2+
mngr_wipe_recreate	Destructive — wipes Porta Manager data and storage volumes, then recreates the containers from existing images. Porta application data is not affected.	0.9.14.2+
~/scripts/porta-manager/install-manager.sh	Underlying script for update_manager.	All
~/scripts/porta-manager/init-manager-user.sh	Underlying script for mngr_init_user.	All
~/scripts/porta-manager/backup-env.sh	Underlying script for mngr_backup_env. Runs automatically as part of install-manager.sh.	All