# 終端機模組:admin(Linux 系統管理 / 伺服器架設)

給課程作者看的說明。啟用方式:terminal 單元的 `config` 加上 `'modules' => ['admin']`,初始世界用 `'world' => ['admin' => [...]]` 提供。
所有指令都是記憶體中的模擬,不會碰真實系統。需要 root 的指令請在課程裡教學員加 `sudo`;沒加會得到真實風格的授權失敗訊息。

## 支援的指令

### 使用者與權限(真的改寫虛擬的 /etc/passwd、/etc/group、/etc/shadow)
| 指令 | 支援 | 說明 |
|---|---|---|
| `useradd` | `-m -M -s -G -g -u -d -c -r -N -o` | 沒加 `-m` 不建家目錄;沒加 `-s` 預設 shell 是 `/bin/sh`(與真實相同)。`-m` 會複製 /etc/skel |
| `usermod` | `-aG -G -g -s -L -U -d [-m] -l -u -c` | `-L/-U` 會在 /etc/shadow 密碼欄加/去掉 `!` |
| `userdel` | `-r -f` | 同名私有群組一併刪除;`-r` 刪家目錄 |
| `groupadd` / `groupdel` / `gpasswd -a/-d` | `groupadd -g -r -f` | 刪使用者主要群組會失敗(真實訊息) |
| `id` / `groups` / `getent passwd\|group\|hosts` / `who` / `last` | `id -u -g -G -n` | `who`、`last` 為示意輸出 |
| `chown` / `chgrp` | `-R -v`、`user:group`、`:group` | 無 sudo 一律 Operation not permitted;檔案的群組存在 `node.group`(核心的 `ls -l` 目前還顯示兩次擁有者) |
| `passwd` | `-l -u -S -d -e` | 練習環境不能互動輸入密碼:不加選項會回說明訊息。設密碼請教學員用 `echo 'user:密碼' \| sudo chpasswd` |
| `chpasswd` | stdin `user:password` | 需 sudo |

預設帳號:root、daemon、www-data、sshd、nobody、student(1000,加入 adm、sudo,可用 `world.student_groups` 改)。

### systemd
- `systemctl`:`status start stop restart reload try-restart reload-or-restart enable disable [--now] mask unmask is-active is-enabled is-failed cat daemon-reload reset-failed list-units [--type=service] [--all] [--state=] --failed list-unit-files [--state=]`。其他子命令與 `--user` 回「練習環境尚未支援」。
- 改變狀態的子命令沒有 sudo 會顯示 `Failed to start x.service: Interactive authentication required.`(enable/disable/mask/daemon-reload 各有對應真實訊息)。`status`、`is-*`、`list-*` 不需要 sudo。
- `status` 會顯示 Loaded / Active / Docs / Main PID / Tasks / Memory / CPU / CGroup 與最近 10 行日誌(`-n N`);failed 狀態顯示 `×`、`Result: exit-code` 與失敗原因日誌。
- `journalctl`:`-u`(可多個)`-n -p -r -b -e -x -o cat -t -g --since --until --no-pager`。`--since` 支援 `today`、`yesterday`、`N min|hour|day ago`、`YYYY-MM-DD [HH:MM[:SS]]`。`-f` 回「尚未支援」。
- 虛擬時鐘固定在 2026-11-06 10:42:17 UTC,每次改變服務狀態前進幾秒(`date` 指令是核心的、顯示真實時間)。

### 套件
- `apt` / `apt-get`:`update upgrade full-upgrade install remove purge autoremove search show list [--installed|--upgradable] clean`。`-y` 可有可無(練習環境永遠自動回答 Y)。`-s` 模擬模式不支援。`apt-cache search|show`。
- `dpkg`:`-l [樣式]`、`-L`、`-s`、`-S`。`-i/-r/-P` 回尚未支援。
- `dnf`:`install remove list installed search update`(RHEL 系簡化對照,與 apt 共用同一份套件狀態;套件可用 `rhel` 欄位指定 RHEL 名稱,例如 apache2 的 `httpd`)。
- 安裝後會建立 `files` 與 `bins` 的檔案、套件的 `service`(自動 enable + start,並寫日誌);`remove` 保留 /etc 設定檔(dpkg 狀態 `rc`),`purge` 才刪;依賴套件標為 automatic,`autoremove` 會清掉不再需要的。
- 未用 sudo:`E: Could not open lock file /var/lib/dpkg/lock-frontend ... are you root?`,exit 100。

### 網路與防火牆
- `ip addr|link|route|neigh [show]`(`-br`、`dev`),只能查詢;`add/del/set` 回尚未支援。
- `ss -tlnp / -tulpn / -tln`:依「執行中服務」的 listen port 產生;`-p` 的程序欄位只有 sudo 才看得到(與真實相同)。
- `ping [-c N] 主機`(預設送 4 筆,示意;名稱解析見 `world.hosts`)。
- `curl [-s -S -I -i -L -f -o 檔 -w "%{http_code}"] URL`:只支援 GET/HEAD,回應由 `world.http` 與服務的 `http` 決定。
- `ufw`:`status [verbose|numbered] enable disable reload reset logging default allow|deny|reject|limit [in|out] 埠[/協定]|服務名|'App 名稱'|from IP [to any port N proto tcp] delete 規則|編號 insert N`。規則真的儲存;預設會同時建立 v6 規則。需 sudo(否則 `ERROR: You need to be root to run this script`)。`enable`/`reset` 的確認提示自動回答 y。
- `hostnamectl [status|set-hostname]`(set 會寫 /etc/hostname,但提示字元仍是 manco-lab)、`timedatectl [status|set-timezone|set-ntp]`。

### 儲存與系統資訊
`lsblk [-f] [-o 欄位]`、`df [-h] [-T] [路徑]`、`mount`(只列出)、`findmnt`、`blkid`(需 sudo)、`free [-h|-m|-g]`、`uptime [-p|-s]`、`lscpu`。這些會覆蓋核心同名的示意指令,內容由 world 設定。

### 排程
`crontab -l`、`crontab 檔案`、`crontab -`(stdin)、`crontab -r`、`crontab -u 使用者`(需 sudo)。安裝時驗證 5 欄格式,錯誤時回 `"檔案":行號: bad minute` 與 `errors in crontab file, can't install.`。實際存放於 `/var/spool/cron/crontabs/<使用者>`。`crontab -e` 不支援(沒有編輯器)。`/etc/cron.d` 只是普通檔案。

### 文字與檔案工具
- `sed`:`-n -E -i -e`;`s/舊/新/[g|p|I]`(任意分隔字元、`&`、`\1`)、`/樣式/d`、`Nd`、`$d`、`Np`、`N,Mp`、`/樣式/p`、`q`、`!`。沒有 sudo 對 /etc 檔案 `-i` 會得到真實的 `couldn't open temporary file`。
- `awk`:`-F` `-v`;`BEGIN`/`END`、`pattern {action}`、pattern 可為 `/regex/`、`NR==N`、`$N ~ /re/`、比較與 `&&`/`||`;`print`、`printf`、`$N`/`$NF`/`NR`/`NF`、變數賦值與 `+=`、`length toupper tolower substr index int`。不支援 if/for/while、陣列、自訂函式、輸出導向。
- `tee [-a]`、`ln [-s] [-f]`(符號連結會即時反映目標內容;硬連結是簡化的複本)、`readlink [-f]`、`stat [-c 格式]`、`which`、`diff [-u] [-q]`。
- `tar`:`-c -x -t -z -j -v -f -C --exclude`(`tar czf x.tgz dir` 舊式寫法也可)。封存檔是練習環境專用格式(檔頭 `MANTAR1`),只能由本模組的 tar 解開;權限、擁有者會保存,還原時只有 root 會還原擁有者。

## world 設定格式
```php
'world' => ['admin' => [
    'student_groups' => ['adm', 'sudo'],            // student 所屬的補充群組(預設如此)
    'groups' => [['name' => 'webteam', 'gid' => 2000, 'members' => ['alice']]],   // 也可直接寫字串 'webteam'
    'users'  => [['name' => 'alice', 'uid' => 1001, 'shell' => '/bin/bash', 'groups' => ['webteam'],
                  'comment' => 'Alice', 'home' => '/home/alice', 'create_home' => true, 'locked' => false]],
    'services' => [[
        'name' => 'nginx', 'description' => 'A high performance web server',
        'state' => 'failed',                         // active | inactive | failed(預設 inactive)
        'enabled' => true,                           // true | false | 'static' | 'masked'
        'port' => 80,                                // 或 'ports' => [80, '127.0.0.1:3306', '53/udp']、'local' => true(只聽 127.0.0.1)
        'process' => 'nginx', 'exec' => '/usr/sbin/nginx', 'cmdline' => 'nginx: master process ...', 'docs' => 'man:nginx(8)',
        'aliases' => ['sshd'], 'can_reload' => true,
        'logs' => ['啟動時的日誌行', ['msg' => '警告行', 'prio' => 'warning']],   // 初始日誌
        'fail_when' => [                             // 啟動/restart/reload 時,任一條件成立就失敗
            ['path' => '/etc/nginx/nginx.conf', 'contains' => ';;'],   // 另有 not_contains、matches、not_matches、missing => true
            ['port_busy' => 80],                     // 另一個執行中的服務占用該 port
        ],
        'fail_logs' => ['nginx: [emerg] unexpected ";" in /etc/nginx/nginx.conf:5'],  // 失敗原因(進入 journal 與 status)
        'http' => '<h1>歡迎</h1>',                    // 服務啟動後對 localhost:<port>/ 的回應(字串或 ['body'=>..,'server'=>..])
        'unit_file' => "[Unit]\nDescription=...",    // systemctl cat 與 /usr/lib/systemd/system/*.service 的內容
    ]],
    'packages' => [[                                 // 與內建套件庫合併(同名覆蓋);內建有 nginx、apache2、mariadb-server、openssh-server、ufw、cron、curl、vim、git、htop、tree、net-tools、rsync、unzip、fail2ban、postgresql、redis-server 等
        'name' => 'myapp', 'version' => '1.0-1', 'description' => '我的應用', 'depends' => ['libfoo'],
        'installed' => false, 'upgrade_to' => '1.1-1',        // 設了 upgrade_to 且已安裝 → 出現在 apt list --upgradable
        'files' => ['/etc/myapp/app.conf' => "port=8080\n"], 'bins' => ['myapp'], 'rhel' => 'myapp',
        'service' => ['name' => 'myapp', 'description' => 'My App', 'port' => 8080, 'fail_when' => [...]],   // 安裝後自動建立並啟動
        'user' => 'myapp',                            // 安裝時建立同名系統使用者
        'size' => 300,                                // 下載大小 kB
    ]],
    'default_packages' => true,                      // false = 不使用內建套件庫
    'apt_requires_update' => false,                  // true = 必須先 apt update 才能 install
    'files' => ['/etc/motd' => '歡迎'],               // 額外的初始檔案(也可直接用 config.fs)
    'network' => ['interfaces' => [['name' => 'ens3', 'mac' => '52:54:00:12:34:56', 'ip' => '192.168.56.10/24']],
                  'gateway' => '192.168.56.1', 'internet' => true, 'unreachable' => ['10.9.9.9'], 'hosts' => ['db.lan' => '192.168.56.20']],
    'hosts' => ['intranet.local' => '10.0.0.8'],     // 名稱解析(ping、curl、getent hosts)
    'listeners' => [['port' => 631, 'proto' => 'tcp', 'addr' => '127.0.0.1', 'process' => 'cupsd', 'pid' => 800]],   // 不屬於任何服務的監聽(未設定時預設只有 systemd-resolved 的 53)
    'http' => [                                      // curl 的回應表;key 可含或省略 http://、結尾 /
        'http://localhost' => '<h1>Hello</h1>',
        'http://localhost:8080/health' => ['status' => 200, 'body' => 'ok', 'headers' => ['X-App' => 'demo'], 'requires' => 'myapp'],  // requires:服務名稱或 port;false=不檢查
        'http://example.com/old' => ['status' => 301, 'headers' => ['Location' => 'http://example.com/new']],
    ],
    'ufw' => ['enabled' => false, 'rules' => ['allow 22/tcp'], 'default_incoming' => 'deny', 'logging' => 'low'],
    'disks' => [['name' => 'sda', 'size' => '40G', 'children' => [
        ['name' => 'sda1', 'size' => '39G', 'fstype' => 'ext4', 'mount' => '/', 'used' => '12G', 'uuid' => '...', 'label' => 'root']]]],
    'tmpfs' => [['mount' => '/run', 'size' => '390M', 'used' => '1.1M']], 'mounts' => [['dev' => '/dev/sdb1', 'mount' => '/data', 'fstype' => 'ext4', 'size' => '20G', 'used' => '1G']],
    'memory' => ['total_mb' => 3884, 'used_mb' => 612, 'free_mb' => 2458, 'shared_mb' => 12, 'cache_mb' => 860, 'avail_mb' => 3068, 'swap_mb' => 2048],
    'uptime' => ['days' => 3, 'hours' => 2, 'minutes' => 11, 'users' => 1, 'load' => [0.08, 0.03, 0.01]],
    'cpu' => ['cores' => 2, 'model' => 'Intel(R) Xeon(R) ...'],
    'logins' => [['user' => 'student', 'tty' => 'pts/0', 'from' => '192.168.56.1']],   // who / last
    'timezone' => 'Etc/UTC',
]]
```
沒設定的項目都有合理預設。內建套件的服務(ssh、cron、ufw)會一開始就是 active;其他套件在 `apt install` 之後才出現。

## check 類型
| type | 欄位 | 說明 |
|---|---|---|
| `service` | `name`、可選 `state`(active/inactive/failed)、`enabled`(true/false)、`masked` | 服務存在且符合條件。`enabled:false` 表示未啟用(含 masked) |
| `package` | `name`、可選 `installed`(預設 true) | 套件已安裝/未安裝(remove 後設定檔殘留不算已安裝) |
| `user` | `name`、可選 `exists`(預設 true)、`groups`(字串或陣列,皆須包含,含主要群組)、`shell`、`home`、`uid`、`locked`、`home_exists` | 使用者條件 |
| `group` | `name`、可選 `exists`、`members`(陣列,皆須在補充成員內) | 群組條件 |
| `port` | `listening`(port 號)、可選 `proto`;或 `listening_not` | 有執行中服務監聽該 port |
| `ufw` | 可選 `status`(active/inactive)、`rule`(規則文字,例如 `80/tcp`、`ALLOW`、`10.0.0.5`)、`absent`(true=不應包含)、`default_incoming` | 防火牆狀態與規則 |
| `cron` | 可選 `user`(預設 student)、`contains` | 該使用者已安裝 crontab 且內容含文字 |
| `owner` | `path`、可選 `owner`、`group` | 擁有者/群組(可驗 chown) |
| `symlink` | `path`、可選 `target` | 該路徑是用 `ln -s` 建的符號連結 |
| `hostname` | `equals` | /etc/hostname 的內容 |

另外可直接用核心的 `exists`/`contains`/`equals`/`mode`/`ran`/`out`,例如檢查 `/etc/ssh/sshd_config` 含 `Port 2222`、或用 `ran` 檢查學員有執行 `systemctl status`。

## 範例單元
```php
['title' => '救援 nginx 並上線', 'type' => 'terminal', 'xp' => 40,
 'content' => <<<'TXT'
你剛接手一台網站主機:nginx 服務壞了,而且還沒有部署帳號與防火牆。請依序……
TXT,
 'config' => [
    'modules' => ['admin'],
    'fs' => [
        'etc' => ['nginx' => ['nginx.conf' => "user www-data;\nevents {}\nhttp {\n  server {\n    listen 80;;\n  }\n}\n"]],
        'home' => ['student' => ['backup.cron' => "0 2 * * * /home/student/backup.sh\n", 'site' => ['index.html' => "hi\n"]]],
    ],
    'world' => ['admin' => [
        'users' => [['name' => 'alice']], 'groups' => [['name' => 'webteam']],
        'services' => [[
            'name' => 'nginx', 'description' => 'A high performance web server', 'state' => 'failed', 'enabled' => false, 'port' => 80,
            'fail_when' => [['path' => '/etc/nginx/nginx.conf', 'contains' => ';;']],
            'fail_logs' => ['nginx: [emerg] unexpected ";" in /etc/nginx/nginx.conf:5', 'nginx: configuration file /etc/nginx/nginx.conf test failed'],
        ]],
    ]],
    'tasks' => [
        ['title' => '把 alice 加入 webteam', 'hint' => 'sudo gpasswd -a alice webteam', 'check' => ['type' => 'group', 'name' => 'webteam', 'members' => ['alice']]],
        ['title' => '新增 deploy 使用者(家目錄、bash、加入 webteam)', 'hint' => 'sudo useradd -m -s /bin/bash -G webteam deploy', 'check' => ['type' => 'user', 'name' => 'deploy', 'groups' => ['webteam'], 'shell' => '/bin/bash', 'home_exists' => true]],
        ['title' => '修好 nginx 設定並啟動服務', 'hint' => '先 systemctl status nginx、journalctl -u nginx 看原因,再用 sed -i 修正', 'check' => ['type' => 'service', 'name' => 'nginx', 'state' => 'active']],
        ['title' => '設定 nginx 開機自動啟動', 'hint' => 'sudo systemctl enable nginx', 'check' => ['type' => 'service', 'name' => 'nginx', 'enabled' => true]],
        ['title' => '啟用防火牆並開放 80/tcp', 'hint' => 'sudo ufw allow 80/tcp 然後 sudo ufw enable', 'checks' => [['type' => 'ufw', 'status' => 'active'], ['type' => 'ufw', 'rule' => '80/tcp']]],
        ['title' => '把 ~/site 交給 deploy:webteam', 'hint' => 'sudo chown -R deploy:webteam ~/site', 'check' => ['type' => 'owner', 'path' => '~/site', 'owner' => 'deploy', 'group' => 'webteam']],
        ['title' => '安裝 tree,並安裝每日備份排程', 'hint' => 'sudo apt install -y tree;crontab backup.cron', 'checks' => [['type' => 'package', 'name' => 'tree', 'installed' => true], ['type' => 'cron', 'contains' => 'backup.sh']]],
    ],
    'solution' => ['sudo gpasswd -a alice webteam', 'sudo useradd -m -s /bin/bash -G webteam deploy', 'systemctl status nginx', 'journalctl -u nginx -n 5 --no-pager',
        "sudo sed -i 's/;;/;/' /etc/nginx/nginx.conf", 'sudo systemctl start nginx', 'sudo systemctl enable nginx', 'sudo ufw allow 80/tcp', 'sudo ufw enable',
        'sudo chown -R deploy:webteam ~/site', 'sudo apt install -y tree', 'crontab backup.cron'],
 ],
],
```

## 限制與注意
- 檔案權限以核心為準(只看擁有者與其他人,不看群組位元);群組成員資格不影響檔案存取。
- 符號連結以「即時反映目標」的方式模擬,核心的 `ls -l` 看不到 `->`;可用 `readlink`/`stat` 驗證。
- 管線中的 `sudo` 只套用在 sudo 後面的那個指令(例如 `echo x | sudo tee /etc/f` 可行,`sudo echo x > /etc/f` 的重新導向仍會 Permission denied,這與真實相同)。
- 任務檢查發生在每個指令之後;狀態 reset 時整個模組重新建立。
