CT-Ops

Host Tools

How to use CT-Ops host tasks, automated logs, terminal access, and host deletion controls.

The Tools area contains actions and action history. Unlike monitoring and inventory pages, tools can execute work against the host or expose direct terminal access, so use them deliberately.

The area contains three child tabs:

Tasks tab

The Tasks tab lets permitted operators run supported host tasks and review task history. Available actions include patch runs, custom scripts, service actions, and Ansible ping checks when automation integration is enabled.

Task history shows task type, details, status, started time, and a link to the live or completed task run. It also supports selecting old task runs for deletion. CT-Ops lists the latest 50 operator-triggered runs for the host. The table refreshes every 5 seconds while any visible run is pending or running, then every 30 seconds after all visible runs are complete or failed.

The action buttons are role-aware:

The task history table contains:

When there are no operator-triggered task runs, CT-Ops shows No task runs yet and directs you to use the action buttons above the table.

Patch tasks

Patch tasks can run all updates or security-only updates. The task result can show whether a reboot is required.

The Run Patch dialog contains:

The agent detects supported Linux package managers such as apt, dnf, yum, and zypper. Patch controls are not shown for non-Linux hosts, and the backend also rejects patch runs for non-Linux hosts.

Use patch tasks when the host needs controlled remediation from CT-Ops. For larger rollouts, prefer group-level patching from Hosts -> Groups so you can control concurrency across multiple hosts.

Custom scripts

Custom script tasks can run shell, Bash, or Python scripts. Output is streamed through the task run.

The Run Script dialog contains:

Validation and behavior:

Use scripts for controlled one-off diagnostics or remediation. Keep scripts small, explicit, and reversible where possible. For repeated workflows, consider moving the logic into a reviewed automation template rather than pasting ad hoc scripts.

Service actions

Service actions can start, stop, restart, or check status for a named service. The service picker can query services from the host to reduce typing mistakes.

The Service Action dialog contains:

Service management requires Linux with systemctl. The run button is disabled until a service name is present. Service action controls are not shown for non-Linux hosts from the Tasks tab, and the backend also rejects service actions for non-Linux hosts.

Use service actions when you need a controlled service operation with recorded evidence. Review the task result to confirm whether the service is active or inactive after the action.

Ansible ping

Ansible ping checks SSH connectivity to Linux hosts using a configured credential profile and SSH port. It is available only when Ansible automation is enabled, the Ansible API is healthy, at least one credential profile exists, and the current user can run host tasks.

The Run Ansible Ping dialog contains:

Validation and behavior:

Use it before running SSH-based automation. A failed ping tells you to fix credentials, host reachability, SSH port, or host policy before attempting a more meaningful task.

Logs tab

The Logs tab shows automated system runs for the host, such as periodic software inventory scans. Each row shows task type, details, status, start time, and a link to the task run.

These are system-triggered runs rather than operator-triggered task runs. Use them when data looks stale or missing and you need to see whether background collection was pending, running, completed, or failed. CT-Ops lists the latest 50 automated runs for the host. The table refreshes every 5 seconds while any visible run is pending or running, then every 30 seconds after all visible runs are complete or failed.

When there are no automated runs, CT-Ops shows No automated runs yet and explains that rows will appear after the system schedules its next scan.

Use this tab to verify background collection activity. For example, if software inventory is stale, check automated logs to see whether scans are failing, pending, or not running.

Terminal tab

The Terminal tab launches controlled terminal access when the feature is enabled, the host allows it, SSH host keys are trusted, and the current user is authorised.

The terminal launcher checks access before opening a session. Access can be blocked by Terminal Access Settings, the host-level Enable Terminal switch, the host user allowlist, untrusted or changed SSH host keys, role permissions, or a disconnected agent. When access is blocked, CT-Ops shows the denial reason instead of launching a session.

The launch form contains:

Terminal and Host Editor sessions open in the shared bottom workspace. Use the full-screen toolbar button to expand the active tab to the whole viewport, then use the restore button to return it to the bottom panel.

Validation and behavior:

Use terminal access for interactive investigation when passive telemetry and task workflows are not enough. Prefer checks, logs, and tasks where they provide the same answer, because they produce more structured evidence.

SFTP tab

The SFTP tab is the file companion to terminal access. It lets an engineer browse remote paths, upload and download files, and open, edit, diff, back up, save, and roll back remote text files over SSH/SFTP.

Global SFTP Security Settings decide whether CT-Ops applies the host-level allowlist and denylist before file operations, or whether SFTP relies on the remote host permissions only. When CT-Ops path policy is enabled, the host editor policy is configured by an administrator on the host Management -> Settings tab and opening, saving, creating, deleting, uploading, downloading, and rolling back require a matching CT-Ops allow rule. When CT-Ops path policy is disabled, Linux permissions for the SSH user decide whether the remote read, write, upload, download, or delete succeeds.

The remote file browser starts at / and lists directories that the SSH user can list on the host. Double-click a file in the browser to open it; each opened file appears as a tab above the editor. Closing a tab with unsaved changes prompts before discarding the draft. Global SFTP host availability can deny the tab for a specific host even when SFTP is otherwise enabled across the instance, or invert access so only selected hosts can launch SFTP.

SFTP status messages, including upload errors such as an existing remote file, can be dismissed manually and clear automatically after five seconds. The same messages remain visible in the collapsible current-session activity log, so an operator can return later in the same browser session and review what happened.

Uploads use the Host Editor streaming upload route rather than a base64 server action payload. This keeps large maintenance artifacts, such as installer images or support bundles, out of browser and web-server memory while preserving per-file progress in the transfer monitor. New files are added to the upload queue first; the queue processor wakes periodically and starts the next file only when no other upload is active, so CT-Ops transfers one uploaded file at a time. CT-Ops still enforces the active SFTP security mode, audits successful uploads, and rejects files over the 5 GiB upload limit before the browser starts sending an oversized file. The bundled nginx proxy streams Host Editor uploads to the web app instead of buffering the whole request first, so multi-GB ISO files can start transferring immediately and a stopped upload is cancelled promptly. Completed and failed transfer cards can be dismissed individually, or the transfer monitor can clear all finished transfers at once. Operators can stop an active or queued upload; stopped uploads are shown as a user-stopped warning rather than an error for 10 seconds, then removed from the transfer list. The transfer monitor can also be hidden from its own header and shown again from the remote file browser toolbar.

Downloads use a separate streaming read route. CT-Ops checks the active Host Editor session, the active SFTP security mode, and the SSH credential, then hands the selected remote file to the browser download manager as an attachment instead of first building a browser Blob. Downloads preserve binary file bytes and are capped at 5 GiB to keep the web service bounded. The bundled nginx proxy streams Host Editor downloads without response buffering, so multi-GB ISO or bundle files can flow from SFTP through CT-Ops to disk without being spooled in the browser or proxy first. Use the remote file browser toolbar download button when the file is too large or too binary to open in the browser editor.

The server-copy control opens a modal for copying files or folders between the current SFTP host and another SSH/SFTP server. The left pane shows the current host filesystem, and the right pane first asks for the other server’s hostname or IP address plus username and password. After the other server connects, both panes show their current folder above a selectable file tree. Use the arrow buttons between the panes to copy selected paths to the other server or back to the current host.

Peer copies run as background jobs and stream over SSH/SFTP through CT-Ops. CT-Ops applies the active SFTP policy to the managed host side of the transfer: copying from the current host requires read access to the selected source path, and copying back to the current host requires write access to the selected destination folder. The ad-hoc peer server is checked by its SSH credentials and remote filesystem permissions. CT-Ops warns when a peer copy expands to more than 200 files so the operator can cancel before starting a large background job. Confirmed peer copies remain bounded by the 5 GiB SFTP transfer limit, and the peer server password is used for the active job only.

The server-copy modal supports multiple peer connection tabs. Each tab has its own selected paths, queued and active jobs, and bottom transfer status, so file counts and byte totals only reflect the selected peer connection. After an operator adds selected paths to the queue, CT-Ops clears that selection to avoid accidentally queueing the same file again. Closing a peer connection tab with queued or active transfers prompts for confirmation, cancels that tab’s active transfer jobs, and switches to the next available connection tab.

While a peer copy is running, the modal shows an overall byte-based progress bar with file counts, transferred bytes, percentage complete, live speed, estimated time remaining, and a needle-based speed indicator with labelled graticules but no circular progress fill. The speed indicator uses a moving average of the current transfer rate over roughly 20 seconds and holds through short polling gaps, so the needle does not snap back to zero between updates. It still settles back to zero when the copy is queued, complete, cancelled, failed, or has stopped moving data. This means a single multi-GB file moves during the transfer instead of staying at 0% until the file finishes. The details button opens a separate log modal showing the current file, current-file byte progress, each copied file, status, and destination path. Use View jobs to review recent background peer-copy jobs, refresh their status, cancel a queued or active transfer, and inspect transferred/total bytes for each file. The background jobs dialog shows one overall progress bar for all visible jobs, followed by one combined file list covering queued, transferring, completed, failed, and cancelled files. Operators can start another peer-copy job while one is already running; the new job appears in the same file list and waits in the queue until the active job completes or is cancelled. The peer-copy overview aggregates queued and active jobs, so selecting two files as separate copy actions still shows the combined file and byte total while CT-Ops transfers one file job at a time. Cancellation is checked during the active file stream so CT-Ops can stop a large file transfer promptly and clean up its temporary upload file.

SFTP security model

SFTP can use two permission layers:

Terminal access and SFTP access are separate features. They share SSH host-key trust and familiar credential fields, but enabling terminal access does not automatically grant SFTP access.

CT-Ops does not store SFTP plaintext SSH credentials. The credentials are used for the active editor operation and are not written to audit metadata.

File browser actions

The toolbar above the remote file browser is available to users with write access under the active SFTP security mode:

Uploads preserve the local file bytes and are intended for SFTP-style transfer workflows. Binary files can be uploaded, but they are not opened in the browser editor. The transfer monitor shows each queued, active, completed, or failed file, while stopped files remain visible for 10 seconds before being removed. Use the per-file Stop upload button or Stop all to cancel queued or active uploads; CT-Ops marks the card as stopped immediately and removes any partial remote file when the SFTP stream is cancelled or fails. CT-Ops bounds uploads to protect the web service from unreasonable request sizes; for larger transfer jobs, use terminal access or a native SFTP client.

The remote file browser toolbar is the primary place to download a selected path. The file editor toolbar also has Download after a text file is open, so operators can save a local copy without making an edit.

Admin configuration

Admins configure global SFTP behavior from Settings -> Security -> SFTP. Admins configure the optional CT-Ops host path policy from the host Management -> Settings tab:

Use narrow allowlists when CT-Ops path policy is enabled. Prefer exact files or small configuration directories, for example /etc/nginx/**, rather than broad system paths. If global SFTP path policy is set to Use host permissions only, these host allowlists and denylists are not applied to SFTP operations.

Engineer workflow

The SFTP launcher opens in the same persistent bottom panel as terminal sessions. Terminal and SFTP sessions appear as tabs in one shared panel, so engineers can switch between shell access and file maintenance without stacking separate panels. SFTP tabs support the same tab menu pattern for renaming, colour marking, and closing the session.

After login, the workspace shows a remote-file tree rooted at /, quick-open path entry, and CodeMirror editor. Until a file is open, the editor area shows a centered prompt to choose a file instead of an empty editor surface. Directory expansion follows the SSH user’s Linux permissions and can show files that are not allowed for editing. When global SFTP path policy is enabled, CT-Ops checks the host editor policy when the user opens or changes a selected file. The allowed-path list is collapsed behind an expander so the file browser and editor keep most of the panel space.

The top bar shows the host, open path, matched mode, and dirty state. Read-only paths can be opened but not saved. Sudo-write paths require Save with sudo; normal Save is disabled for those paths.

Backups, diffs, and sudo

Before a save, CT-Ops reads the current remote file and refuses to save if the file changed since it was opened. It then creates a backup next to the original file using a .ctops-backup-<timestamp> suffix.

Diff preview reads the current remote file and compares it with the editor buffer on demand. The result opens in a modal so the editor does not reserve permanent space for a diff panel.

Normal saves use SFTP as the SSH user. Sudo-write saves use the configured SSH user and non-interactive sudo for the copy/write step. If the target host requires an interactive sudo prompt, the save fails and CT-Ops shows an explicit sudo failure message.

Every open/read attempt, write attempt, denied attempt, backup, rollback, and save is written as an audit event with path, SSH username, mode, session ID, hashes, sizes, and backup path where relevant. File contents and SSH credentials are not included in audit metadata.

Access can be denied when host editor access is disabled, no paths have been allowed, the requested path is outside the allowlist, the path matches a blocked pattern, the requested operation is stronger than the matched path mode, the file is too large, the payload is too large, the content appears binary, SSH host-key verification fails, or the remote Linux user lacks filesystem permission.

Use Host Editor for policy-gated file maintenance. Use Terminal when the work is interactive command-line investigation rather than editing a known file.

Delete host

Users with host-management access can delete a host from the host detail page. When supported, the delete flow can also request agent uninstall before the host record is removed.

The delete dialog explains that deletion removes associated data including metrics, checks, alerts, certificates, users, and SSH keys. The action cannot be undone.

If uninstall fails, CT-Ops keeps the dialog open and shows the error. Operators can uncheck the uninstall option and retry host-record deletion when the remote agent cannot receive or complete the uninstall command.

Use deletion for decommissioned hosts, failed test registrations, or records that should no longer appear in inventory. Do not delete a host just to silence an alert; resolve the underlying monitoring, agent, or infrastructure issue instead.