# Hướng dẫn cài iSecOS 1.0-alpha6 (MotaX) — amd64

> alpha6 = alpha5 + **nâng cấp tại chỗ bằng `isecos-upgrade`** + **bộ cài đồ họa
> GTK là mặc định** (menu boot chờ 5 giây rồi tự chạy) + **USB Live có thể lưu
> bền vững (persistence)** + cổng quản trị mới tại
> `https://isecos.isecurity.vn/portal/`.
>
> Đĩa vẫn được **mã hóa toàn bộ theo mặc định** (LUKS2 + LVM). Khi cài bạn chỉ
> đặt **2 mật khẩu**: mật khẩu người dùng và passphrase đĩa. Máy có TPM 2.0 sẽ
> mở khóa đĩa tự động sau khi kích hoạt.

---

## Mục lục

1. [Yêu cầu máy](#1-yêu-cầu-máy)
2. [Tạo USB cài đặt](#2-tạo-usb-cài-đặt-rufus)
3. [Cài đặt](#3-cài-đặt-bộ-cài-đồ-họa-tự-động)
4. [Lần bật máy đầu tiên](#4-lần-bật-máy-đầu-tiên)
5. [Nâng cấp bằng `isecos-upgrade`](#5-nâng-cấp-bằng-isecos-upgrade)
6. [Kích hoạt các tính năng bảo mật (MFA · NAC · DLP)](#6-kích-hoạt-các-tính-năng-bảo-mật-mfa--nac--dlp)
7. [Tạo USB Live lưu bền vững (persistence)](#7-tạo-usb-live-lưu-bền-vững-persistence)
8. [Sự cố thường gặp](#8-sự-cố-thường-gặp)

---

## 1. Yêu cầu máy

| Thành phần | Tối thiểu | Khuyến nghị |
|---|---|---|
| **CPU** | amd64 (Intel/AMD 64-bit) | — |
| **RAM** | 4 GB | 8 GB trở lên |
| **Đĩa cài** | 40 GB | SSD 60 GB trở lên |
| **Chế độ boot** | UEFI hoặc BIOS cũ | **UEFI** (điều kiện cần cho TPM) |
| **TPM 2.0** | Không bắt buộc | Có, bật trong BIOS — mở khóa đĩa tự động |
| **Mạng** | Không bắt buộc khi cài | Có — để nhận repo iSecOS sau khi cài |

Ghi chú:

- **Không có TPM vẫn cài và dùng bình thường** — bạn gõ passphrase đĩa mỗi
  lần bật máy.
- ⚠️ Bộ cài **xóa toàn bộ đĩa được chọn** — chỉ cài lên máy thử hoặc đĩa
  trống. Sao lưu dữ liệu trước khi bắt đầu.

## 2. Tạo USB cài đặt (Rufus)

### 2.1. Tải ISO và file kiểm tra

Tải từ `https://isecos.isecurity.vn/iso/`:

- `isecos-desktop-1.0-alpha6-amd64.iso` (bản desktop, có bộ cài đồ họa)
- `isecos-server-1.0-alpha6-amd64.iso` (bản server, bộ cài text)
- `SHA256SUMS.txt`
- `isecos-desktop-1.0-alpha6-amd64.iso.sig` (và `.sig` tương ứng cho server)
- `isecos-release-public.asc` (khóa GPG công khai của đội phát hành)

### 2.2. Kiểm tra toàn vẹn và chữ ký (khuyên dùng — chống ISO bị sửa)

```sh
# 1) Đối chiếu SHA256
sha256sum -c SHA256SUMS.txt --ignore-missing

# 2) Nhập khóa phát hành iSecOS
gpg --import isecos-release-public.asc

# 3) Kiểm tra chữ ký GPG trên ISO
gpg --verify isecos-desktop-1.0-alpha6-amd64.iso.sig isecos-desktop-1.0-alpha6-amd64.iso
```

Kết quả phải hiện:

```
Good signature from "iSecOS Release <isecos@isecurity.vn>"
Primary key fingerprint: 33D4 52CF 996B C871 50D2  91AB 00F6 23A3 E6B3 5107
```

> Khóa hiện hành (từ 05-11): `33D452CF996BC87150D291AB00F623A3E6B35107`.
> Cảnh báo "This key is not certified with a trusted signature" là bình thường
> — bạn chưa tự ký tin cho khóa này; fingerprint phía trên mới là căn cứ đối
> chiếu.

### 2.3. Ghi USB bằng Rufus

1. Tải **Rufus** từ <https://rufus.ie>, cắm USB ≥ 8 GB (dữ liệu trên USB sẽ mất).
2. Chọn **SELECT** → chỉ ISO vừa tải.
3. **Partition scheme**:
   - **GPT** — cho máy boot **UEFI** (khuyến nghị, kể cả máy có TPM);
   - **MBR** — cho máy **BIOS** cũ.
4. Bấm **START**. Rufus hỏi **ISO mode** hay **DD mode**: **cả hai đều được**
   (ISO iSecOS là isohybrid chuẩn; ISO mode khuyến nghị vì giữ USB dùng lại
   được bằng Windows).

## 3. Cài đặt (bộ cài đồ họa, tự động)

Từ alpha6, mục **"Start installer"** trên menu boot là **bộ cài đồ họa GTK**
và là **mặc định** — menu chỉ chờ **5 giây** rồi tự chạy. Cắm USB là vào cài,
không cần bấm gì (muốn vào chế độ Live để thử trước, bấm phím mũi tên trong
5 giây rồi chọn *Live system*).

1. Boot từ USB → menu **iSecOS** hiện ra → chờ 5 giây (hoặc Enter ngay) vào
   **Start installer** — bộ cài đồ họa tiếng Việt tự chạy.
2. Trong toàn bộ quá trình, bạn chỉ được hỏi **2 mật khẩu**:
   - **Mật khẩu người dùng** (`isecos`) — nhập 2 lần. Đây cũng là mật khẩu
     sudo trên máy.
   - **Passphrase đĩa (LUKS)** — nhập 2 lần, sau bước xóa an toàn đĩa (~10–15
     phút). **GHI NHỚ VÀ BẢO QUẢN AN TOÀN**: mất passphrase = mất toàn bộ
     dữ liệu, không ai khôi phục được.
3. Phần còn lại hoàn toàn tự động: locale `vi_VN`, múi giờ
   `Asia/Ho_Chi_Minh`, phân vùng `/boot` 512 MB + LUKS2 + LVM (root + swap),
   cài gói, cài GRUB.
4. Cài xong máy **tự tắt** (tổng ~15–30 phút tùy máy). Rút USB, bật máy lại.

> Muốn cài kiểu cũ (bộ cài text) hoặc xem các tùy chọn nâng cao: bấm phím
> trong 5 giây menu boot → *Advanced options*.

## 4. Lần bật máy đầu tiên

1. Máy hỏi `Please unlock disk sda5_crypt:` → gõ **passphrase đĩa** đã đặt
   khi cài.
2. Màn hình đăng nhập GDM → vào **isecos** + **mật khẩu người dùng**.
3. **Máy có TPM 2.0**: hộp thoại *"Kích hoạt mở khóa tự động bằng TPM"* hiện
   ra ở lần đăng nhập đầu:
   - Nhập **passphrase đĩa** → **Kích hoạt** → thông báo
     *"Đã kích hoạt mở khóa tự động bằng TPM."* — từ lần khởi động sau
     **không cần gõ mật khẩu đĩa nữa**.
   - Bấm **Bỏ qua (không hỏi lại)** nếu không muốn — máy sẽ không hỏi lại
     (kích hoạt sau bằng tay: `sudo isecos-tpm-enroll`).
4. **Máy không có TPM**: không có hộp thoại — gõ passphrase mỗi lần bật máy
   (bình thường).

Sau khi vào desktop, khuyến nghị làm ngay:

```sh
# Thêm khóa dự phòng (recovery) cho đĩa — lưu nơi KHÁC máy này
sudo cryptsetup luksAddKey /dev/sda5     # hỏi passphrase hiện tại + khóa mới
```

## 5. Nâng cấp bằng `isecos-upgrade`

alpha6 giới thiệu công cụ nâng cấp **tại chỗ** — không cần tải ISO mới hay cài
lại máy: `alpha6 → alpha7 → … → 1.0 stable`. Phiên bản OS được đánh dấu bằng
gói `isecos-base` (gói này sở hữu `/etc/os-release`); khi repo có bản mới,
`isecos-upgrade` tải về, xác thực rồi cài.

### Các lệnh

```sh
# Xem phiên bản hiện tại và trạng thái (không cần root)
isecos-upgrade status

# Kiểm tra có bản nâng cấp mới trên repo chưa (không cần root)
isecos-upgrade check

# Thực hiện nâng cấp (CẦN root)
sudo isecos-upgrade apply

# Ép cài lại / sửa chữa (bỏ qua so sánh phiên bản — KHÔNG bỏ qua xác thực)
sudo isecos-upgrade apply --force
```

### `apply` làm gì

1. `apt update` — làm mới chỉ mục gói từ `https://isecos.isecurity.vn/apt/`.
2. Tải + xác thực metadata phiên bản từ repo
   (`https://isecos.isecurity.vn/apt/isecos/`, suite `mota-x`).
3. So sánh phiên bản `isecos-base` trên repo với máy — có bản mới mới nâng cấp.
4. Tải `.deb` mới, **đối chiếu SHA256**, **sao lưu `/etc/os-release`** vào
   `/var/backups/isecos/` (giữ 10 bản cũ nhất) rồi cài.
5. `apt full-upgrade` — nâng cấp toàn bộ phần mềm còn lại.

Mọi dữ liệu tải về đều được xác thực chuỗi GPG đầy đủ (chữ ký *InRelease* →
SHA256 *Packages* → SHA256 *`.deb`*). `--force` chỉ bỏ qua **so sánh phiên
bản**, không bao giờ bỏ qua xác thực toàn vẹn.

Ghi chú thêm:

- Log đầy đủ: `/var/log/isecos-upgrade.log`.
- Nếu có kernel mới, công cụ sẽ nhắc khởi động lại (`sudo reboot`).
- Lab/test có thể trỏ repo khác bằng biến môi trường:
  `ISECOS_UPGRADE_REPO` (mặc định `https://isecos.isecurity.vn/apt/isecos`)
  và `ISECOS_UPGRADE_SUITE` (mặc định `mota-x`).

## 6. Kích hoạt các tính năng bảo mật (MFA · NAC · DLP)

Cả ba dịch vụ đã được cài sẵn trên máy; dưới đây là lệnh kích hoạt nhanh.

### MFA — xác thực đa yếu tố (TOTP / FIDO U2F / smart card)

```sh
isecos-mfa enroll        # kích hoạt cho user hiện tại: sinh QR + secret TOTP
                          # + 10 mã khôi phục một-lần (IN ra màn hình — lưu ngoài máy!)
isecos-mfa status        # trạng thái enroll (TOTP/U2F)
isecos-mfa disable       # tắt MFA cho user
isecos-mfa repair        # sửa cấu hình PAM nếu gói khác ghi đè
```

Sau khi enroll: đăng nhập console, **sudo** và **SSH** đều hỏi thêm mã OTP.
Máy phải đồng hồ NTP chuẩn (mặc định đã bật `systemd-timesyncd`).

### NAC — kiểm soát truy cập mạng (802.1X / posture)

```sh
isecos-nac status                # posture: đã xác thực 802.1X chưa?
sudo isecos-nac enforce on       # bật chế độ enforce: chưa 802.1X → chặn mọi
                                 # outbound trừ DHCP/EAPOL (default-deny)
sudo isecos-nac enforce off      # tắt enforce
```

Chứng thư máy đặt tại `/etc/isecos/nac/` (cấp qua CA công vụ).

### DLP — chống thất thoát dữ liệu (USB)

USB storage **mặc định bị chặn**; bàn phím/chuột (HID) luôn hoạt động.

```sh
isecos-dlp status                                  # thiết bị + chính sách hiện tại
sudo isecos-dlp allow-usb-storage 0951:1666 "USB công việc"   # whitelist 1 thiết bị
sudo isecos-dlp deny-all-storage                   # chặn lại toàn bộ
```

Mọi lần cắm/rút USB đều được ghi audit (`/var/log/usbguard/`).

### Quản trị tập trung

Máy tự đăng ký về cổng quản trị **iSec Control Center**:
`https://isecos.isecurity.vn/portal/` — xem posture MFA/NAC/DLP của toàn bộ
đội máy, bật/tắt chính sách từ xa (agent `isecos-agent`, chu kỳ 5 phút).

## 7. Tạo USB Live lưu bền vững (persistence)

Chế độ **Live system** (thử iSecOS không cài) từ alpha6 hỗ trợ **lưu bền vững**:
mọi thay đổi — file tạo thêm, gói cài thêm, cấu hình — **giữ lại sau khi
reboot**, nếu USB có phân vùng persistence. USB thường (không có) vẫn boot
live bình thường, hoàn toàn vô hại.

Các bước (sau khi đã ghi ISO vào USB bằng Rufus/dd):

```sh
# USB là /dev/sdX (kiểm tra bằng: lsblk)
# 1) Tạo phân vùng mới trong CHỖ TRỐNG CUỐI USB (GParted, fdisk, parted...)

# 2) Định dạng ext4 với label BẮT BUỘC là "persistence"
sudo mkfs.ext4 -L persistence /dev/sdX3

# 3) Tạo file persistence.conf chứa "/ union" ở GỐC phân vùng
sudo mount /dev/sdX3 /mnt
echo "/ union" | sudo tee /mnt/persistence.conf
sudo umount /mnt
```

Boot USB → bấm phím trong 5 giây → chọn **Live system**. Từ giờ mọi thay đổi
của phiên Live được lưu vào phân vùng này và còn nguyên sau khi khởi động lại.

Ghi chú:

- `/ union` = lưu bền vững **toàn bộ** hệ thống file. Muốn chỉ lưu vài thư
  mục, liệt kê mỗi thư mục một dòng (xem tài liệu live-boot).
- Mục **Live system (fail-safe)** không dùng persistence — cố ý giữ sạch để
  khắc phục sự cố.
- Phân vùng persistence **không được mã hóa** theo cấu hình này — không lưu
  dữ liệu nhạy cảm trên USB persistence; dữ liệu nhạy cảm hãy cài lên đĩa
  (LUKS2 mặc định).

## 8. Sự cố thường gặp

| Triệu chứng | Nguyên nhân & xử lý |
|---|---|
| Menu boot chờ 5 giây rồi tự vào installer | Đây là hành vi mặc định mới của alpha6. Muốn chọn mục khác: bấm phím mũi tên **trong 5 giây** rồi chọn *Live system* / *Advanced options*. |
| Boot USB không thấy menu iSecOS | Chọn đúng USB trong boot menu của máy (F12/F8/Esc tùy hãng); tắt *Fast Boot* trong BIOS; kiểm tra scheme Rufus khớp máy (GPT↔UEFI, MBR↔BIOS). |
| Hỏi passphrase đĩa mỗi lần bật dù đã enroll TPM | Bật/tắt **Secure Boot** giữa các lần boot làm đổi PCR7 → TPM từ chối mở khóa. Enroll lại: hộp thoại tự hỏi lại, hoặc chạy `sudo isecos-tpm-enroll`. |
| Quên passphrase đĩa | **Không khôi phục được** — chỉ còn đường vào nếu đã thêm khóa dự phòng (`cryptsetup luksAddKey`, mục 4). |
| Cắm USB storage không thấy phân vùng | DLP mặc định chặn (usbguard). Xem thiết bị + cho phép: `isecos-dlp status` → `sudo isecos-dlp allow-usb-storage <vendor:product>`. |
| Mã OTP luôn bị từ chối | Kiểm tra đồng hồ máy (`timedatectl` — phải NTP sync); mã đã dùng không dùng lại được (disallow-reuse). Thử mã mới nhất trên app OTP. |
| `sudo apt update` / `isecos-upgrade check` lỗi mạng | Repo hệ thống `https://isecos.isecurity.vn/apt/os/` (suite `mota-x`) có thể **đang đồng bộ mirror** — thử lại sau vài giờ. Cài đặt từ ISO không bị ảnh hưởng (gói có sẵn trên đĩa). |
| `isecos-upgrade check` báo "repo cũ hơn bản hiện tại" | Mirror chưa kịp có bản build mới nhất. Ép cài lại bản trên repo: `sudo isecos-upgrade apply --force` (xác thực GPG vẫn được thực hiện đầy đủ). |
| Bật `isecos-nac enforce on` rồi không SSH được | Đúng thiết kế: máy chưa xác thực 802.1X thì bị default-deny. Tắt enforce từ console: `sudo isecos-nac enforce off`. |
| Live USB mất hết thay đổi sau reboot | USB chưa có phân vùng persistence — làm theo mục 7, hoặc kiểm tra lại label (`persistence`) và nội dung `persistence.conf`. |
| Cài xong không lên GNOME | Chụp ảnh màn hình lỗi và báo đội phát triển: isecos@isecurity.vn. |

---

# English (concise)

## iSecOS 1.0-alpha6 (MotaX) Install Guide — amd64

alpha6 adds in-place upgrades (`isecos-upgrade`), a GTK graphical installer as
the boot default (5-second timeout), persistent Live USB, and the new admin
portal at `https://isecos.isecurity.vn/portal/`. Full-disk encryption (LUKS2 +
LVM) remains the default; you only set two passwords during install.

### 1. Requirements

| Component | Minimum | Recommended |
|---|---|---|
| CPU | amd64 (Intel/AMD 64-bit) | — |
| RAM | 4 GB | 8 GB+ |
| Disk | 40 GB | SSD 60 GB+ |
| Boot mode | UEFI or legacy BIOS | UEFI (required for TPM) |
| TPM 2.0 | Optional | Enabled in BIOS — automatic disk unlock |

⚠️ The installer **erases the entire target disk**. Use a test machine or
empty disk only.

### 2. Create install USB (Rufus)

Download from `https://isecos.isecurity.vn/iso/`:
`isecos-desktop-1.0-alpha6-amd64.iso`, `SHA256SUMS.txt`, the matching
`.iso.sig`, and `isecos-release-public.asc`. Verify before writing:

```sh
sha256sum -c SHA256SUMS.txt --ignore-missing
gpg --import isecos-release-public.asc
gpg --verify isecos-desktop-1.0-alpha6-amd64.iso.sig isecos-desktop-1.0-alpha6-amd64.iso
# expect: Good signature from "iSecOS Release <isecos@isecurity.vn>"
# key fingerprint: 33D4 52CF 996B C871 50D2  91AB 00F6 23A3 E6B3 5107
```

Rufus (<https://rufus.ie>): select ISO → scheme **GPT** (UEFI) or **MBR**
(legacy BIOS) → START. Either **ISO mode** or **DD mode** works (ISO is
standard isohybrid; ISO mode recommended).

### 3. Install — graphical, automatic

Boot the USB. The menu defaults to **Start installer** (GTK graphical,
Vietnamese) after a **5-second timeout** — no keypress needed. Press an arrow
key within 5 seconds to pick *Live system* or *Advanced options* instead.

You are only asked for two passwords:

- **User password** (user `isecos`; also the sudo password).
- **Disk passphrase (LUKS)** — **store it safely**: if lost, all data is
  unrecoverable.

Everything else is automatic (locale `vi_VN`, timezone, `/boot` + LUKS2 + LVM
partitioning, GRUB). The machine powers off when done (~15–30 min). Remove
the USB and power on.

### 4. First boot

1. `Please unlock disk sda5_crypt:` → type your **disk passphrase**.
2. GDM login: user **isecos** + **user password**.
3. **With TPM 2.0**: a dialog *"Kích hoạt mở khóa tự động bằng TPM"* (Enable
   automatic TPM unlock) appears at first login — enter the **disk
   passphrase** → *Kích hoạt*. From the next boot the disk unlocks itself.
   Choose *Bỏ qua* (Skip) to decline (won't be asked again; CLI later:
   `sudo isecos-tpm-enroll`).
4. **Without TPM**: no dialog — type the passphrase at every boot (normal).

Recommended right after install:

```sh
sudo cryptsetup luksAddKey /dev/sda5   # add a recovery key, store OFF this machine
```

### 5. Upgrading with `isecos-upgrade`

```sh
isecos-upgrade status     # current version (no root needed)
isecos-upgrade check      # check repo for a newer release (no root needed)
sudo isecos-upgrade apply # perform the upgrade (root required)
sudo isecos-upgrade apply --force   # repair / re-install (still GPG-verified)
```

`apply` = `apt update` + install the new `isecos-base` package (it owns
`/etc/os-release`, backed up to `/var/backups/isecos/`) + `apt
full-upgrade`. Every download is verified end-to-end (signed InRelease →
SHA256 of Packages → SHA256 of the `.deb`). Log: `/var/log/isecos-upgrade.log`.

### 6. Security features (quick start)

```sh
isecos-mfa enroll         # TOTP + 10 one-time recovery codes (print & store offline)
isecos-mfa status
isecos-nac status         # 802.1X posture
sudo isecos-nac enforce on|off
isecos-dlp status         # USB policy (storage blocked by default)
sudo isecos-dlp allow-usb-storage 0951:1666 "work USB"
```

Fleet management: machines auto-enroll to the admin portal at
`https://isecos.isecurity.vn/portal/` (agent checks in every 5 minutes).

### 7. Persistent Live USB

Write the ISO to USB, then create an extra partition in the free space at the
end of the stick:

```sh
sudo mkfs.ext4 -L persistence /dev/sdX3      # label MUST be "persistence"
sudo mount /dev/sdX3 /mnt
echo "/ union" | sudo tee /mnt/persistence.conf
sudo umount /mnt
```

Boot → press a key within 5 s → *Live system*. All changes (files, packages,
settings) now survive reboots. The fail-safe Live entry stays non-persistent
by design. The persistence partition is **not encrypted** — do not keep
sensitive data on it.

### 8. Troubleshooting

| Symptom | Fix |
|---|---|
| Menu auto-runs installer after 5 s | New alpha6 default. Press an arrow key within 5 s to choose another entry. |
| USB won't boot | Pick the right boot device (F12/F8/Esc); disable Fast Boot; match Rufus scheme to firmware (GPT↔UEFI, MBR↔BIOS). |
| Disk passphrase asked despite TPM enroll | Secure Boot toggling changes PCR7 — re-enroll (auto prompt, or `sudo isecos-tpm-enroll`). |
| Forgot disk passphrase | Unrecoverable — only a previously added recovery key helps. |
| USB storage not mounting | DLP blocks it by default: `isecos-dlp status`, then `sudo isecos-dlp allow-usb-storage <vendor:product>`. |
| OTP always rejected | Check NTP sync (`timedatectl`); codes are single-use — use the freshest one. |
| `apt update` / upgrade check fails | System mirror (`/apt/os/`, suite `mota-x`) may still be syncing — retry later. Install from ISO is unaffected. |
| `check` says repo is older than installed | Mirror lag; force re-install with `sudo isecos-upgrade apply --force` (integrity checks still apply). |
| SSH blocked after NAC enforce | Expected default-deny until 802.1X passes. From console: `sudo isecos-nac enforce off`. |
| Live changes lost on reboot | No persistence partition — see section 7 (check label and `persistence.conf`). |
| No GNOME after install | Screenshot the error and report to isecos@isecurity.vn. |

---
*iSecOS 1.0-alpha6 (MotaX) — internal alpha release, not yet certified for
production. Feedback/issues: isecos@isecurity.vn*