Installer and Configuration Guide body { font-family: Arial, sans-serif; line-height: 1.6; margin: 20px; } pre { background: #f4f4f4; padding: 10px; border: 1px solid #ddd; } code { background: #f4f4f4; padding: 2px 4px; border-radius: 3px; } table { border-collapse: collapse; width: 100%; } th, td { border: 1px solid #ddd; padding: 8px; } th { background-color: #f4f4f4; } blockquote { border-left: 4px solid #ccc; margin: 1em 0; padding-left: 1em; color: #555; }
 
Installer and Configuration Guide
=================================
 
> **Note:** This guide is for environments running the **Helix Remote Admin (HRA)** version of Command‑Runner. For other environments, please confirm with your administrator.
 
Overview
--------
 
This guide explains how to install and configure the **command‑runner** utility using the updated `install_command-runner.sh` script. The installer will:
 
*   Install the new binary.
*   Set up a systemd service and timer (replacing legacy cron jobs).
*   Adjust SELinux contexts (if applicable).
*   Create or update the `.push_metrics.cfg` file (unless skipped with the `-m` flag).
*   Back up existing installations and configurations.
 
The installer also supports various options (e.g. test mode, forced installation) so that you can customize the process to your environment.
 
Prerequisites
-------------
 
Before running the installer, ensure that:
 
*   You have **root** or **sudo** access.
*   The **command‑runner** binary (`command-runner-linux-amd64`) and (optionally) `cmd_config.yaml` are in the **current directory**.
*   For SELinux environments, required utilities (`semanage` and `restorecon`) are installed.
*   The installer creates backups of any overwritten files or cron jobs (e.g. in `/p4/<instance>/tmp/`).
 
Installation
------------
 
### Basic Usage / Quickstart
Download latest release
 
    wget https://swarm.workshop.perforce.com/downloads/guest/perforce_software/command-runner/packages/command-runner-linux-amd64.tar.gz
 
Decompress tar ball
 
    tar -zvxf command-runner-linux-amd64.tar.gz
    cd command-runner
 
By default, the installer runs in **dry‑run mode** (printing actions without making changes). To run in dry‑run mode:
 
    sudo ./install_command-runner.sh
 
To really install, use the `-y` to continue in interactive mode flag:
 
    sudo ./install_command-runner.sh -y
 
### Available Options
 
Option
 
Description
 
Default
 
`-d PATH`
 
Destination path for the `command-runner` binary.
 
`/p4/common/site/bin/command-runner`
 
`-c DIR`
 
Directory for `cmd_config.yaml`.
 
`/p4/common/config`
 
`-p FILE`
 
Path for `.push_metrics.cfg`.
 
`/p4/common/config/.push_metrics.cfg`
 
`-u OWNER`
 
User:Group ownership for files.
 
`perforce:perforce`
 
`-i INSTANCE`
 
Instance name (auto‑detects if omitted).
 
Auto‑detect
 
`-y`
 
Apply changes (disable dry‑run).
 
`-f`
 
Force re‑installation even if the versions match.
 
 
 
 
### Example Installations
 
#### Standard Installation (Dry‑Run by Default)
 
    sudo ./install_command-runner.sh
 
#### Full Installation
 
    sudo ./install_command-runner.sh -y
 
#### Specify a Custom User and Instance
 
    sudo ./install_command-runner.sh -y -u myuser:mygroup -i prod
 
#### Skip `.push_metrics.cfg` Update
 
    sudo ./install_command-runner.sh -y -m
 
Systemd Service & Timer
-----------------------
 
The installer sets up a systemd **service** and **timer** that replace legacy cron jobs. They are installed as follows:
 
*   **Service:** `/etc/systemd/system/command-runner.service` – Executes the `command-runner` binary on demand.
*   **Timer:** `/etc/systemd/system/command-runner.timer` – Controls when the service runs.
 
#### Managing the Service/Timer
 
*   **Check status:** `systemctl status command-runner.timer`
*   **Enable and start the timer:** `systemctl enable --now command-runner.timer`
*   **Disable and stop the timer:** `systemctl disable --now command-runner.timer`
*   **Manually trigger the service:** `systemctl start command-runner.service`
 
Legacy Cron Job Removal
-----------------------
 
The installer automatically removes outdated cron jobs referencing `report_instance_data.sh` from the target user’s crontab. Before modifying the crontab, a backup is created in:
 
    /p4/<instance>/tmp/crontab_backup_<user>_<timestamp>.bak
 
`.push_metrics.cfg` Configuration
---------------------------------
 
Unless skipped with the `-m` flag, the installer creates or updates the `.push_metrics.cfg` file using default values or user input. To manually edit the file after installation, run:
 
    nano /p4/common/config/.push_metrics.cfg
 
Troubleshooting
---------------
 
If `command-runner` does not run as expected, try the following steps:
 
1.  **Check systemd logs:**
    
        journalctl -u command-runner.service --no-pager --reverse
    
2.  **Verify binary installation:**
    
        ls -l /p4/common/site/bin/command-runner
    
3.  **Manually run the binary:**
    
        /p4/common/site/bin/command-runner --version
    
4.  **Review the installer log:** Check `/tmp/cmd-runner_installer.log` for detailed output.
 
Self‑Update
-----------
 
A separate self‑update script (`self_update.sh`) is provided to download a new release and spawn the installer. The self‑update script performs the following tasks:
 
*   Fetches the latest version number.
*   Downloads and verifies a tarball using a SHA‑256 checksum.
*   Extracts the new version and spawns the installer (with appropriate flags) in a background process.
*   The spawned installer runs as the service owner (as defined in the systemd unit file) so that file ownership and logs are set correctly.
 
Summary
-------
 
*   **Systemd** replaces legacy cron jobs.
*   The default mode is **dry‑run**; use `-y` to apply changes.
*   The installer auto‑detects instances but also allows manual selection.
*   **Backups** are created before any files or configurations are overwritten.
*   The installer supports an optional **test mode**.
*   You can skip updating `.push_metrics.cfg` using the `-m` flag.
*   The **self‑update** mechanism uses HTTPS and verifies checksums to ensure integrity.