From e6761d2551549530c315ebce55ca924115de66d2 Mon Sep 17 00:00:00 2001 From: dxpgitbuki Date: Sat, 25 Oct 2025 08:34:29 +0200 Subject: [PATCH] manual.html modernisiert --- .../remotectl/templates/remotectl/manual.html | 421 +++++++++++++----- 1 file changed, 312 insertions(+), 109 deletions(-) diff --git a/project/remotectl/templates/remotectl/manual.html b/project/remotectl/templates/remotectl/manual.html index 181929f..c43bf7f 100644 --- a/project/remotectl/templates/remotectl/manual.html +++ b/project/remotectl/templates/remotectl/manual.html @@ -1,130 +1,333 @@ {% extends 'remotectl/base.html' %} {% block title %}Manual | Remote Admin{% endblock %} {% block content %} -

Application Manual

-

Detailed reference for using the Remote Admin console. Use your - browser search (Ctrl+F) to find topics quickly.

-
-

1. Overview

-

This application lets you manage remote Linux hosts over SSH, execute ad-hoc commands, run saved tasks, and - process multi-step batch scripts with real-time streaming output via WebSockets.

+
+
+
+
+

Remote Admin Manual

+

Operate Linux fleets with clarity and control.

+

This guide highlights the essential flows for onboarding hosts, running + commands, orchestrating batches, and understanding every status signal the console emits.

+
+ + View workflow + Troubleshoot +
+
+
+

Snapshot

+
+
+
Channels
+
SSH + WebSockets
+
+
+
Run Modes
+
Single / Batch
+
+
+
Cancel Safety
+
Graceful SIGTERM
+
+
+
Auth
+
Key or Agent
+
+
+
+
+
-

2. Hosts

-

Create remote hosts under Hosts. Each host stores:

-
    -
  • name: Friendly display name
    • -
  • hostname: DNS name or IP
    • -
  • port: SSH port (default 22)
    • -
  • username: SSH login user
    • -
  • auth_method: ssh_key or agent (password not yet implemented)
    • -
  • key_path: Optional explicit private key path (not uploaded)
    • -
  • strict_host_key_checking: Enforce known_hosts validation
    • -
-

Example:

- 
Host: prod-app-1
+    

+        

+            Overview
+            Hosts
+            Console
+            Tasks
+            Batch scripts
+            Status
+            Logs
+            Workflow
+            Security
+            Troubleshooting
+            Future
+        

+    

+
+    

+        
01

+        
Overview

+        
Remote Admin lets you register hosts, dispatch commands through SSH, and observe output
+            in real time over WebSockets. Use it as a single pane of glass for routine ops, emergency fixes, and
+            long-running batch jobs.

+        

+            

+                
Visibility

+                
Live logs, exit codes, and batch step markers surface progress at a glance.

+            

+            

+                
Repeatability

+                
Save complex commands as tasks or batches for consistent, auditable actions.

+            

+            

+                
Control

+                
Cancel runs safely, and rely on strict host key checks for production-grade SSH.

+            

+        

+    

+
+    

+        

+            

+                
Hosts

+                Inventory
+            

+            
Create remote endpoints under Hosts. Each entry
+                stores credentials without uploading your private key.

+            

+                

+                    
name

+                    
Friendly display label.

+                

+                

+                    
hostname

+                    
DNS or IP.

+                

+                

+                    
port

+                    
Default 22 unless overridden.

+                

+                

+                    
username

+                    
SSH login user.

+                

+                

+                    
auth_method

+                    
ssh_key or agent.

+                

+                

+                    
key_path

+                    
Optional explicit key location.

+                

+            

+            

+                
Example

+                
Host: prod-app-1
 Hostname: 10.10.10.15
 User: deploy
 Auth: ssh_key
-Key Path: /home/deploy/.ssh/id_ed25519

+Key Path: /home/deploy/.ssh/id_ed25519
+
+ +
+
+

Console Modes

+ Run + Center +
+

Connect to a host then choose how to execute.

+
    +
  • +

    Saved Task

    +

    Pick a curated command and optionally edit before launch.

    +
    • +
  • +

    Ad-hoc

    +

    Type anything (e.g. uname -a) for fast diagnostics.

    +
    • +
  • +

    Batch

    +

    Execute multi-step scripts with streamed STDOUT/STDERR markers.

    +
    • +
+

Cancel anytime; the UI highlights stderr lines so failures stand out instantly.

+
+ -

3. Console

-

Connect to a host then choose one of:

- -

While running you can cancel. Output streams in real-time; stderr lines are highlighted.

- -

4. Tasks

-

Tasks are named reusable commands. Fields:

- -

Example task:

- 
Name: restart_app
+    

+        

+            
Reusable Commands

+            
Tasks

+            
Tasks encapsulate commands with friendly labels so teams can run critical actions
+                without remembering exact syntax.

+            
    
+                
  • name: Unique key (use dashes/underscores).
    • 
+                
  • label: Human friendly description.
    • 
+                
  • command: Executed verbatim on the remote host.
    • 
+            

+            

+                
Name: restart_app
 Label: Restart App Service
-Command: sudo systemctl restart app.service

-
-    
5. Batch Scripts

-    
A batch script is a list of steps (one per line). Blank lines and lines starting with # are ignored.
-        A line starting with cd <dir> sets the working directory for subsequent commands.

-    
Example batch:

-    
# Deploy sequence
+Command: sudo systemctl restart app.service

+            

+        

+        

+            
Multi-step orchestration

+            
Batch Scripts

+            
Define a sequence of commands, one per line. Blank lines or lines starting with
+                # are ignored. Use cd path to change context for subsequent steps.

+            

+                
# Deploy sequence
 cd /srv/app
 ./stop.sh
 ./build.sh
-./start.sh

-    
During execution you will see markers like:

-    
>>> [2/4] ./build.sh

+./start.sh
+
+

During execution you will see markers like >>> [2/4] ./build.sh + to track progress.

+ + -

6. Status & Progress

-

Status badge meanings:

- +
+
+
+

Signals

+

Status & Progress

+
+ Live badges +
+
+
+

CONNECTED

+

WebSocket open; idle until you run a task.

+
+
+

RUNNING / STEP X/Y

+

Command or batch in-flight; watch the live stream.

+
+
+

CANCELING

+

Terminate signal sent; waiting for graceful stop.

+
+
+

COMPLETED (exit n)

+

Finished with exit code context.

+
+
+

FAILED / ERROR

+

Non-zero exit or SSH/runtime problem.

+
+
+
-

7. Logs

-

Each execution creates a log entry with:

- +
+
+

Run evidence

+

Logs

+

Every execution produces a structured record:

+
    +
  • run_type: single or batch
    • +
  • status and exit_code
    • +
  • failed_step for batch failures
    • +
  • Tail output (last 32K), timestamps, and duration
    • +
+
+
+

Structured errors

+

Error shape

+
+ 
{"event":"error","type":"ssh|runtime","message":"..."}
+
+

SSH errors reflect connection/auth issues. Runtime errors signal validation or + conflicting state (for example, duplicate run requests).

+
+
-

8. Errors

-

Error events are structured as:

- 
{"event":"error","type":"ssh|runtime","message":"..."}
-

SSH errors come from connection/auth issues; runtime errors are validation or state (e.g. duplicate run).

- -

9. Cancellation

-

When you press Cancel the server sends a terminate signal; some commands may take time to exit gracefully. Batch - processing stops at the current step.

- -

10. Security Notes

- - -

11. Example Use Cases

-

Deploy Application

- 
Task: build_assets
-Command: npm run build
-
-Batch:
-cd /srv/app
+    

+        

+            

+                
Flow

+                
Deployment Workflow

+            

+            Best practice
+        

+        

+            

+                
Task example

+                
Task: build_assets
+Command: npm run build

+            

+            

+                
Batch companion

+                
cd /srv/app
 ./stop.sh
 ./deploy.sh
-./start.sh

+./start.sh
+ + +
+
1. Connect to host with validated keys.
+
2. Choose saved task or attach ad-hoc pre-flight checks.
+
3. Launch batch for deterministic rollout, watching live markers.
+
4. Inspect logs, confirm exit codes, archive evidence.
+
+ -

Quick Diagnostics

- 
Ad-hoc: df -h | grep /data
-Ad-hoc: sudo journalctl -u app.service -n 50
+
+

Control

+

Cancellation

+

Cancel sends a terminate signal to the remote process. Some commands need additional time + to unwind; batch processing stops immediately after the active step finishes.

+
-

12. Troubleshooting

- +
+
+

Security Notes

+

Hardening checklist

+
    +
  • Private keys stay on disk; only file paths are stored.
    • +
  • Enable strict host key checking in production.
    • +
  • Django authentication gates every operation.
    • +
+
+
+

Pro tips

+
    +
  • Segment hosts with naming conventions (prod-, staging-, etc.).
    • +
  • Store frequently used directories in batches via cd steps.
    • +
  • Use python -u or stdbuf -o0 to force unbuffered output.
    • +
+
+
-

13. Future Extensions

- +
+

Troubleshooting

+

Fix common blockers

+
+
+

Permission denied

+

Verify SSH user, key permissions (chmod 600), and host-based ACLs.

+
+
+

Host key not trusted

+

Add the host to known_hosts or temporarily disable strict checks only for development.

+
+
+

No output

+

Some binaries buffer stdout; prefer unbuffered flags such as python -u.

+
+
+
+ +
+

Roadmap hints

+

Future extensions

+ +
-{% endblock %} \ No newline at end of file +{% endblock %}