﻿============================================================
  OSH CLI (osh.exe) — HƯỚNG DẪN CÀI ĐẶT (Windows)
============================================================

OSH CLI là công cụ dòng lệnh: gõ

      osh user@server

từ cmd / PowerShell — giống "ssh user@server" nhưng đi qua
cổng zero-trust và tự ghi lại phiên làm việc.

Gói này dùng osh.exe BUILD SẴN — KHÔNG cần cài Go hay tải
mã nguồn. Cài cho từng người dùng, KHÔNG cần Administrator.

Yêu cầu: Windows 10/11 (64-bit).

------------------------------------------------------------
 CÀI ĐẶT
------------------------------------------------------------

1. Giữ "install.bat" và "osh.exe" TRONG CÙNG MỘT THƯ MỤC.

2. Nháy đúp "install.bat".
   (Nếu SmartScreen chặn: chuột phải osh.exe -> Properties
    -> tích "Unblock" -> OK, rồi chạy lại install.bat.)

   Script sẽ:
     - Chép osh.exe vào %LOCALAPPDATA%\PamZta\bin
     - Thêm thư mục đó vào PATH của bạn

3. MỞ MỘT CỬA SỔ TERMINAL MỚI (quan trọng — PATH chỉ có
   hiệu lực ở cửa sổ mới). Kiểm tra:

      osh --help

------------------------------------------------------------
 DÙNG LẦN ĐẦU
------------------------------------------------------------

1. Đăng ký thiết bị với gateway (địa chỉ do admin cấp):

      osh enroll --gateway https://<dia-chi-gateway>

   -> osh tạo khoá thiết bị (TPM) và in ra MÃ 4 SỐ.

2. Gửi MÃ 4 SỐ cho admin để duyệt thiết bị (trong app
   PAM-ZTA CA / App Signer).

   Mã có HẠN. Hết hạn thì chạy lại "osh enroll" để lấy mã
   mới (không cần --force).

3. Sau khi được duyệt, kết nối:

      osh user@server

------------------------------------------------------------
 CÁC LỆNH CHÍNH
------------------------------------------------------------

  osh enroll --gateway https://gw   Đăng ký thiết bị lần đầu
  osh enroll --force                Tạo lại khoá thiết bị mới
  osh status --gateway https://gw   Kiểm tra kết nối gateway
  osh user@server                   Kết nối SSH (+ ghi phiên)
  osh connect user@server           Giống trên (dạng đầy đủ)
  osh connect user@server -p 2222   Kết nối khi sshd KHÔNG ở
                                    cổng 22
  osh config                        Xem cấu hình
  osh --help                        Trợ giúp

------------------------------------------------------------
 KHỎI GÕ --gateway MỖI LẦN
------------------------------------------------------------

Đặt biến môi trường một lần:

      setx OSH_GATEWAY https://<dia-chi-gateway>

Mở terminal MỚI, từ đó chỉ cần "osh user@server".
(Biến thứ hai: OSH_LOG_SERVER — mặc định 127.0.0.1:9923.)
Gõ kèm cờ --gateway thì cờ vẫn thắng biến môi trường.

Lưu ý: -p là cờ CỦA "connect" nên đặt SAU địa chỉ máy:
"osh user@server -p 2222". Viết "user@server:2222" KHÔNG
chạy — phải dùng -p.

------------------------------------------------------------
 GHI PHIÊN (session recording)
------------------------------------------------------------

Mỗi phiên tương tác được lưu tại:
  %USERPROFILE%\.osh\sessions\<request-id>.cast
(định dạng asciinema v2). Phát lại:
  pip install asciinema
  asciinema play <file>.cast

------------------------------------------------------------
 GỠ CÀI ĐẶT
------------------------------------------------------------

Chạy "uninstall.bat". Khoá thiết bị + bản ghi phiên trong
%USERPROFILE%\.osh\ KHÔNG bị xoá (xoá tay nếu muốn).

------------------------------------------------------------
 XỬ LÝ LỖI
------------------------------------------------------------

* "osh is not recognized" -> mở cửa sổ terminal MỚI.
* "device not enrolled"   -> chạy lệnh osh enroll ở trên.
* osh.exe không chạy / bị chặn -> chuột phải osh.exe ->
  Properties -> Unblock.
* Kết nối bị từ chối -> osh in rõ lý do (vd "Permission
  denied" khi người duyệt từ chối, hoặc không có quy tắc
  truy cập nào cho phép). Đọc dòng lỗi cuối cùng.

------------------------------------------------------------
 PHIÊN BẢN
------------------------------------------------------------

osh.exe — OSH SSH Zero Trust client (Windows, TPM device key).
Gói CLI 0.2.0.

File trong gói này CHƯA ký số -> SmartScreen sẽ cảnh báo
"Unknown publisher". Đây là chủ ý; xem mục XỬ LÝ LỖI để bỏ
chặn.

Có vấn đề, liên hệ admin / đội kỹ thuật.
============================================================
