Documentation

Staging, uploading, the deploy manager and its scripts, file headers, our command-line tools, and how we work.

Staging

The staging area is where code passes between us and a device. stage.sh packs a directory and uploads it under a prefix; pull.sh, on the other end, downloads that package and unpacks it. Used one way it pushes code to a device, the other way it brings code back from one, and many projects use both. Both scripts are installed with deploy.

Staging code:

  1. Put your code in the ./live folder
  2. Run ./stage.sh testing, where testing is the prefix that identifies the customer or project
  3. Put your secret token in the .secret file in the current directory, or give it on the command line as the second parameter

Options: --live <dir> stages a directory other than ./live, --ignore <file> leaves a file out (repeat it for more than one), and --list shows what is in the package before it is uploaded.

Example Output:

[2025-10-14 20:35:22] Starting backup of ./live
[2025-10-14 20:35:22] Creating tar file: testing_staging.tar.gz
[2025-10-14 20:35:22] Tar file created successfully: testing_staging.tar.gz
[2025-10-14 20:35:22] Uploading testing_staging.tar.gz to https://www.gensoftware.dev/upload.php
File uploaded successfully as testing_staging.tar.gz
[2025-10-14 20:35:22] Upload completed successfully
[2025-10-14 20:35:22] Cleaning up local tar file
[2025-10-14 20:35:22] Backup process completed successfully

Pulling staged code:

To pull the staged code on the receiving machine:

  1. Create a directory called live
  2. Install the pull.sh script using deploy
  3. Execute ./pull.sh testing with your secret token in .secret or passing it as parameter 2
  4. The payload will be downloaded and expanded into ./live

This is how alpha and beta code reaches remote servers and devices during development. Anything that moves the code from ./live into its final location runs after the pull, either as a separate script or by extending pull.sh.

Uploading Files

Any file can be sent to the staging area from the command line:

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" -F "file=@test.txt" -F "name=test.txt" https://www.gensoftware.dev/upload.php

This uploads test.txt to the staging area as test.txt, under the account that owns the token. It works from anything with curl, which is nearly everything, embedded Linux included, so it is how diagnostics, log files and data files come back to us. During alpha and beta testing it is the usual route for debug output and error captures.

Compress large files first.

Deploy Script Manager

deploy installs, updates and removes the scripts in our catalogue, including stage and pull. It runs on Linux, macOS and Windows; each build only lists and installs scripts written for its own platform, bash on Linux and macOS, PowerShell on Windows.

INSTALL:

curl https://www.gensoftware.dev/deploy/ | bash                 # Linux and macOS
irm https://www.gensoftware.dev/deploy/?os=windows | iex        # Windows PowerShell

It installs to /usr/bin/deploy on Linux and /usr/local/bin/deploy on macOS (both need sudo), and to %LOCALAPPDATA%\Programs\Deploy\deploy.exe on Windows.

DEPLOY KEY:

Scripts are fetched against a deploy key tied to your account, which we issue. Set it with deploy key <key>; it is stored in ~/.deploykey, and running the command again replaces it. For unattended use, such as cron, set DEPLOY_KEY in the environment instead.

USAGE:

deploy <command> [options] [arguments]

COMMANDS:

  • list - List available scripts from the repository
  • install <script> - Install/update a script
  • reinstall <script> - Force reinstall a script (bypass version check)
  • remove <script> - Remove an installed script
  • force-remove <script> - Force remove script (ignores tracking file)
  • update [script] - Update all scripts or a specific script
  • upgrade - Upgrade the deploy manager itself
  • key <key> - Set or replace the deploy key for this install
  • installed - Show currently installed scripts
  • cleanup - Remove orphaned entries from the tracking file

OPTIONS:

  • -d, --directory DIR - Install scripts to specific directory (default: current)
  • -h, --help - Show this help message

EXAMPLES:

  • deploy list - Show available scripts
  • deploy install setip - Install the setip script
  • deploy install setip toast - Install multiple scripts
  • deploy reinstall setip - Force reinstall setip script
  • deploy remove setip - Remove the setip script
  • deploy force-remove setip - Force remove (ignores tracking issues)
  • deploy update - Update all installed scripts
  • deploy update setip - Update only the setip script
  • deploy upgrade - Upgrade deploy manager itself
  • deploy key ABC123... - Set or replace this install's key
  • deploy installed - Show what scripts are installed

Software Headers

C'ish Languages (/* */)

/*
  ░░░░░░░░ ░░░░░░░ ░░░░░░░░░
  ▒▒               ▒▒     ▒▒
  ▒▒    ▒▒ ▒▒▒▒▒▒▒ ▒▒     ▒▒
  ▓▓    ▓▓ ▓▓      ▓▓     ▓▓
  ████████ ███████ ██     ██

  GEN Software Systems Development Team
├─────────────────────────────────────────────
│ Copyright (c) 2025 Global Enterprise Networks
│ Website: www.gensoftware.dev /  www.gen.uk
│ License: https://www.gen.uk/?page=license
│ Author: Richard Taylor (109)
│ BugTracker: https://mantis.gensoftware.dev
│ Mantis Tracks:
│ Project Name:
│ Dependencies:
│ Languages:
├─────────────────────────────────────────────
│ Revision History
│
├─────────────────────────────────────────────
*/

Script Languages (#)

#
# ░░░░░░░░ ░░░░░░░ ░░░░░░░░░
# ▒▒               ▒▒     ▒▒
# ▒▒    ▒▒ ▒▒▒▒▒▒▒ ▒▒     ▒▒
# ▓▓    ▓▓ ▓▓      ▓▓     ▓▓
# ████████ ███████ ██     ██
#
# GEN Software Systems Development Team
#├─────────────────────────────────────────────
#│ Copyright (c) 2025 Global Enterprise Networks
#│ Website: www.gensoftware.dev /  www.gen.uk
#│ License: https://www.gen.uk/?page=license
#│ Author: Richard Taylor (109)
#│ BugTracker: https://mantis.gensoftware.dev
#│ Mantis Tracks:
#│ Project Name:
#│ Dependencies:
#│ Languages:
#├─────────────────────────────────────────────
#│ Revision History
#│
#├─────────────────────────────────────────────
#

Scripts

The scripts available to everyone through deploy. Customers may see more with their own deploy key.

Name Language Version Description
archive universal 1.0.2 Archive files older than X days while maintaining folder structure
clamavmon bash 1.0.0 Monitor ClamAV freshclam update status and alert if database is out of date
debugceph bash 1.1.2 Collect deep Ceph cluster diagnostics (mon/mgr/osd, crush, pools, rbd, cephfs, rgw, pg, LUKS/dmcrypt OSDs, daemon log files and per-OSD bluestore/rocksdb internals) into a structured debugceph.txt (GENREPORT/1 sections)
debuginfo bash 1.3.2 Collect Linux / Proxmox diagnostics into a structured debuginfo.txt (GENREPORT/1 sections)
doveaccess bash 1.0.0 Report distinct external login IPs per mailbox user from Dovecot/Postfix maillog
ffpolicyw powershell 1.0.1 Deploy Firefox policy configuration from GEN Software
fpbx-ext-qualify bash 1.0.0 Show FreePBX extensions with name, registration and qualify RTT, address, user agent, DND/CF, calls today and calls in progress, plus trunk status
fpbx17-fix bash 1.0.5 Lock sangoma out of SSH, manage support users, remove FreePBX commercial modules except sysadmin, and generate strong passwords
fwblock bash 1.0.0 Block IP addresses or subnets using firewalld rich rules
genfile bash 1.0.3 Download and install the genfile binary for Linux (amd64/arm64) into a system PATH directory
genlogin bash 1.0.3 Setup SSH banner and useful login script with system information
httpcheck bash 1.0.0 Validate Apache HTTP Configuration and SSL certificates
KillEdge powershell 1.0.0 Remove Microsoft Edge shortcut links from all user Desktops and Start Menus (incl. common/Public Start Menu)
maillog bash 1.0.2 Build and Upload Maillog Analysis
makeptr bash 1.0.0 Build reverse zone for Unbound server. File will need editing with zone and reverse ranges.
monitor powershell 1.7.0 Capture the state of a collapsing Windows Server 2025 RDSH (local AD DS health for an RDSH that is also the sole DC, Terminal Services, licensing, memory, CPU, handles, services, ports, event logs) every few minutes. Every collector runs under a hard time
newDKIM bash 1.0.0 Add domain to OpenDKIM configuration and generate new keys
pbs-cert-renew bash 1.0.0 Request and Install StepCA Certificates
prox-backup-configdb bash 1.0.0 Backup the Proxmox cluster configuration database (/var/lib/pve-cluster/config.db). Stops pve-cluster with verification, creates a timestamped tar.gz backup, then restarts the service and confirms it is running.
prox-cert-renew bash 1.0.0 Request and Install StepCA Certificates
prox-gensupport bash 1.0.0 Setup GENSupport logins on Proxmox
prox-list-storage bash 1.0.0 Scan Proxmox VM and container configs and write a JSON inventory of assigned storage backends
prox-no-nag bash 1.0.0 Silence the relentless no subscription nag
prox-show-iowait bash 1.1.7 Attribute a Proxmox host's IO Delay to the guest or host process causing it, including delay from NFS, CIFS, CephFS and RBD storage that block-layer tools cannot see. Counts NFS operations per originating guest via kernel tracepoints, and ranks guests by
prox-show-swap bash 1.0.0 Show Proxmox Swap Usage
prox-tools bash 1.0.0 Install the diagnostic toolset on a Proxmox VE 9.x host: pidstat/iostat/sar, perf (including perf kvm stat), trace-cmd, bpftrace and bcc, cpupower/turbostat, numastat, ioping, fio, iperf3 and similar. Packages not in the configured repositories are skippe
pull bash 1.0.2 GEN Staging Downloader to ./live
push bash 1.0.1 GEN Staging push files to GEN Staging
reboot bash 1.0.0 Schedule a daily reboot at a set time using a systemd timer instead of cron. Fires on the second, never catches up a missed run at boot, and skips the reboot if the machine has been up under an hour. Optional kexec mode skips firmware POST for a faster re
setip bash 1.0.0 Set the IP Address of the first physical network adapter
stage bash 1.0.1 Staging Upload Tool from ./live to the staging server
windowsmemory powershell 1.0.0 Show where the memory has gone on a Windows host that is running out of it: system totals, how much processes account for, what is left unaccounted for (a hypervisor balloon driver takes memory this way), then totals per program, per session and the large

Tools

Internal tools used by GEN developers and operations.

How We Work

Delivery

Every project runs the same course:

  1. Functional design specification, agreed before any code is written
  2. Alpha
  3. Beta
  4. Staging
  5. Live

Version Control

  • Git: feature branches for new work, clear commit messages, and code review on every merge
  • Subversion: for legacy projects and enterprise environments
  • Stage: our own staging system, described above

Testing

Testing is extensive, and runs through every stage from alpha to live.