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.