HackerOS Containers

01 Przegląd

hco (HackerOS Containers) to lekki, niskopoziomowy runtime kontenerów napisany w Rust. Nie zależy od Dockera ani containerd — zarządza cyklem życia kontenerów bezpośrednio przez syscalle Linuksa.

Główne możliwości:

• Izolacja przez przestrzenie nazw (UTS, PID, MNT, NET, IPC, USER)
• OverlayFS — wielowarstwowy system plików jak w Dockerze
• Ograniczenia zasobów przez cgroups v2 (pamięć, CPU)
• Pobieranie obrazów OCI z rejestrów (Docker Hub, własne)
• Przekierowanie portów przez iptables/DNAT (TCP i UDP)
• Seccomp — filtrowanie syscalli z profili JSON
• Tryb rootless (user namespaces)
• Pods — grupy kontenerów ze wspólną siecią/PID/IPC
• REST API (axum) z opcjonalnym TLS (rustls) i Bearer token auth
• Eksport metryk w formacie Prometheus z realnym pomiarem CPU (delta)
• Structured logging (tracing) + OpenTelemetry OTLP exporter
• SQLite WAL jako backend stanu (zamiast JSON w /var/run)
• IPAM — pula IP z gwarancją braku kolizji
• Automatyczne restartowanie (auto_restart)
• PTY shell — wejście do działającego kontenera
• Systemd unit + socket activation

02 Instalacja

hacker unpack hackeros-containers

Powyższa komenda pobierze i zainstaluje najnowszą wersję hco wraz ze wszystkimi zależnościami. Po zakończeniu procesu hco będzie dostępne w systemie.

03 Architektura

Kontener jest tworzony przez wywołanie nix::sched::clone() z odpowiednimi flagami przestrzeni nazw. Proces potomny wywołuje child_entrypoint(), który konfiguruje sieć, montuje OverlayFS, wykonuje pivot_root i uruchamia docelowy program przez execve.

Stan kontenerów i podów jest przechowywany w bazie SQLite w trybie WAL (/var/lib/hackeros/state.db). Adresy IP są zarządzane przez wbudowany moduł IPAM — każdy kontener dostaje unikalny sufiks z puli 2–254.

hco run
  │
  ├─ ImageManager::resolve_image_layers()   ← pobierz/cache OCI
  ├─ setup_overlayfs()                      ← zmontuj rootfs
  ├─ setup_bridge() / setup_cni()           ← skonfiguruj sieć
  ├─ setup_cgroups()                        ← ogranicz zasoby
  ├─ db::ipam_allocate()                    ← przydziel unikalny IP
  ├─ clone(CLONE_NEWUTS|PID|NS|NET|IPC)     ← nowe namespaces
  │     └─ child_entrypoint()
  │           ├─ setup_namespaces()         ← user ns (rootless)
  │           ├─ seccomp_setup()            ← załaduj profil
  │           ├─ sethostname()
  │           ├─ bind mounts (walidowane)
  │           ├─ pivot_root → /
  │           └─ execve(cmd)
  ├─ create_veth_pair()                     ← sieć host↔kontener
  ├─ setup_port_forwarding()                ← iptables DNAT (TCP+UDP)
  ├─ db::insert_container()                 ← zapisz stan + pełny HkConfig
  └─ ContainerLogger::start_capture()      ← capture stdout (100MB limit)

Moduły

04 CLI — Komendy

hco run

hco run <name> -i <image> [opcje]

# Uruchom nginx w tle z przekierowaniem portu
hco run my-nginx -i nginx:alpine -p 8080:80 -d

# Uruchom z limitem pamięci i CPU
hco run db -i postgres:15 -e POSTGRES_PASSWORD=secret \
    --memory 512MB --cpu 50 -d

# Uruchom Alpine z wolumenem i auto-restartem
hco run dev-box -i alpine:latest -v /home/user/code:/app \
    --auto-restart -d

# Uruchom w trybie interaktywnym (foreground)
hco run test -i alpine:latest

hco stop

hco stop <name_lub_id_prefix>

Wysyła SIGTERM, czeka 10 sekund (sprawdzając co 100 ms), następnie wysyła SIGKILL. Czyści iptables (DNAT + FORWARD), veth, OverlayFS, cgroups i wpis z bazy SQLite.

hco list / hco ps

hco list
hco ps

Wyświetla tabelę z kolumnami: ID (skrócony), NAME, IMAGE, STATUS, IP, POD. Dane pobierane z SQLite.

hco enter

hco enter <name_lub_id>

Otwiera interaktywną sesję PTY w przestrzeniach nazw działającego kontenera. Wymaga roota.

hco stats

hco stats <name_lub_id> [-w]

Wyświetla statystyki pamięci i CPU z cgroups v2. Flaga -w / --watch włącza live refresh co 1 sekundę (bez czyszczenia całego ekranu — tylko kursor na górę).

hco image

# Usuń nieużywane warstwy obrazów (garbage collect)
hco image gc

# Importuj obraz z archiwum Docker save
hco image import my-image:local -f /tmp/myimage.tar

hco api

hco api [opcje]

hco api \
  --api-addr 0.0.0.0:8443 \
  --api-token "$(cat /etc/hco/token)" \
  --tls-cert /etc/hco/tls.crt \
  --tls-key  /etc/hco/tls.key \
  --json-logs \
  --otlp http://otel-collector:4317

05 Pliki konfiguracyjne (.hk)

Kontenery można opisywać plikami .hk — własnym formatem konfiguracyjnym HackerOS. Pliki te są ładowane przez HkConfig::from_file().

[Metadata]
-> name = "my-app"
-> version = "1.0"
-> authors = "devops@example.com"
-> license = "MIT"

[Specs]
-> base_image = "alpine:latest"
-> memory_limit = "256MB"
-> cpu_percent = 50
-> mounts = "/data:/mnt/data"
-> port_mappings = "8080:80"
-> env = "APP_ENV=production,LOG_LEVEL=info"
-> cmd = "/usr/bin/myapp,--config,/etc/app.conf"

[Runtime]
-> auto_restart = true
-> network_mode = "bridge"

[Security]
-> rootless = false
-> readonly_root = false
-> drop_caps = "CAP_SYS_ADMIN"
-> seccomp_profile = "/etc/hco/profiles/default.json"

[Network]
-> bridge_name = "hkbr0"
-> subnet = "10.10.0.0/24"
-> gateway = "10.10.0.1"

Sekcje konfiguracji

06 Pods

Pod to grupa kontenerów współdzielących przestrzenie nazw sieci, PID i/lub IPC. Wzorowane na Kubernetes Pods — kontenery w jednym podzie widzą się nawzajem przez localhost.

Każdy pod uruchamia proces pause (/usr/libexec/hco/pause), który trzyma współdzielone przestrzenie nazw przez cały czas życia poda. Jeśli binarium pause nie istnieje, używany jest fallback sleep infinity.

Plik specyfikacji poda (YAML)

name: web-pod
shared_network: true
shared_pid: false
shared_ipc: true
containers:
  - metadata:
      name: web
      version: "1.0"
      authors: ""
      license: ""
    specs:
      base_image: nginx:alpine
      port_mappings: ["80:80"]
      mounts: []
      env: []
      cmd: []
    runtime:
      auto_restart: false
      network_mode: none
    security:
      rootless: false
      readonly_root: false
      allow_raw_sockets: true
      drop_caps: []
  - metadata:
      name: sidecar
    specs:
      base_image: alpine:latest
      cmd: ["/bin/sh", "-c", "while true; do sleep 5; done"]

Komendy pod

# Utwórz i uruchom poda ze specyfikacji YAML
hco pod create my-pod -f my-pod.yaml

# Wyświetl działające pods
hco pod list

# Zrestartuj zatrzymane kontenery w podzie
hco pod start my-pod

# Zatrzymaj poda (i wszystkie jego kontenery)
hco pod stop my-pod

07 REST API

Po uruchomieniu hco api dostępny jest serwer HTTP/HTTPS (axum 0.7) z endpointami do zarządzania kontenerami i podami. Serwer obsługuje paginację, timeouty żądań (60 s), limit rozmiaru body (10 MB) oraz opcjonalną autoryzację Bearer tokenem.

hco api --api-addr 0.0.0.0:8080

hco api \
  --api-addr 0.0.0.0:8443 \
  --api-token my-secret-token \
  --tls-cert /etc/hco/tls.crt \
  --tls-key  /etc/hco/tls.key

Endpointy — Kontenery

Endpointy — Pods

Endpointy — System ZAKTUALIZOWANE

Paginacja

Listy kontenerów i podów obsługują paginację przez query string:

GET /containers?page=2&per_page=25
GET /pods?page=1&per_page=10

{
  "containers": [...],
  "total": 142,
  "page": 2,
  "per_page": 25
}

Przykład — tworzenie kontenera (curl)

curl -X POST https://localhost:8443/containers \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer my-secret-token" \
  -d '{
    "name": "my-nginx",
    "image": "nginx:alpine",
    "ports": ["8080:80/tcp"],
    "env": ["NGINX_ENTRYPOINT_QUIET_LOGS=1"],
    "memory_limit": "128MB",
    "cpu_percent": 25,
    "auto_restart": true
  }'

{ "id": "a3f7c2d1-8b4e-4f2a-b1c3-d5e6f7a8b9c0" }

Health check

curl https://localhost:8443/health

{
  "status": "ok",
  "version": "0.3.0",
  "containers_running": 5
}

Schemat błędów

{ "error": "Invalid port mapping '99999:80': port numbers must be > 0" }

08 Autoryzacja API NOWE

API obsługuje opcjonalną autoryzację przez Bearer token. Gdy --api-token jest podany, wszystkie chronione endpointy wymagają nagłówka Authorization: Bearer <token>. Brak tokenu lub nieprawidłowy token zwraca 401 Unauthorized.

# Ustaw token przy starcie
hco api --api-token "$(openssl rand -hex 32)"

# Użyj tokenu w żądaniach
curl -H "Authorization: Bearer <token>" \
     https://localhost:8443/containers

Endpointy GET /health i GET /metrics są publiczne — nie wymagają tokenu, co umożliwia zewnętrzny scraping metryk i health check przez load balancer.

09 TLS / HTTPS NOWE

Serwer API obsługuje TLS przez bibliotekę rustls (bez OpenSSL). Certyfikat i klucz prywatny podajesz w formacie PEM. Obsługiwane formaty klucza: PKCS8 i RSA PKCS1.

Generowanie self-signed certyfikatu (dev)

mkdir -p /etc/hco
openssl req -x509 -newkey rsa:4096 -keyout /etc/hco/tls.key \
  -out /etc/hco/tls.crt -days 365 -nodes \
  -subj "/CN=hco-api/O=HackerOS"

Uruchomienie z TLS

hco api \
  --api-addr 0.0.0.0:8443 \
  --tls-cert /etc/hco/tls.crt \
  --tls-key  /etc/hco/tls.key \
  --api-token my-secret

Implementacja

TLS loop w src/api.rs akceptuje połączenia przez tokio::net::TcpListener, opakowuje je w tokio_rustls::TlsAcceptor i podaje do hyper 1.x przez adapter TowerToHyperService (bridge między tower::Service a hyper::service::Service).

10 Metryki Prometheus ZAKTUALIZOWANE

Serwer API eksportuje metryki pod GET /metrics w formacie Prometheus text. Metryki CPU są teraz realne — background task (spawn_metrics_collector) co 1 sekundę czyta cpu.stat z cgroup v2, oblicza deltę usage_usec i przelicza na procenty z uwzględnieniem liczby rdzeni CPU.

# HELP hco_containers_running Number of currently running containers
# TYPE hco_containers_running gauge
hco_containers_running 3

# HELP hco_container_memory_bytes Memory usage in bytes
# TYPE hco_container_memory_bytes gauge
hco_container_memory_bytes{id="a3f7...",name="my-nginx"} 1.24e+07

# HELP hco_container_cpu_usage_percent CPU usage percent (1-second window)
# TYPE hco_container_cpu_usage_percent gauge
hco_container_cpu_usage_percent{id="a3f7...",name="my-nginx"} 2.3

Konfiguracja Prometheus scrape

scrape_configs:
  - job_name: 'hco'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: /metrics
    scrape_interval: 5s

11 Observability / OpenTelemetry NOWE

hco używa biblioteki tracing do structured logging. Wspiera eksport tracingów przez protokół OTLP gRPC do OpenTelemetry Collector, Jaeger, Tempo lub innego backendu.

Structured logging

Domyślnie logi są wypisywane w formacie tekstowym. Flaga --json-logs włącza format JSON:

hco api --json-logs 2>&1 | jq .

{
  "timestamp": "2025-05-18T12:34:56.789Z",
  "level": "INFO",
  "target": "hco::container",
  "fields": {
    "id": "a3f7c2d1",
    "name": "my-nginx",
    "pid": 12345,
    "ip": "10.10.0.5",
    "message": "Container started"
  }
}

OpenTelemetry OTLP

Flaga --otlp włącza eksport tracingów do OTLP endpoint (gRPC):

hco api --otlp http://localhost:4317 --json-logs

Poziom logowania

Steruj poziomem przez zmienną środowiskową:

# Pokaż tylko błędy i ostrzeżenia
RUST_LOG=warn hco api

# Debug dla modułu hco::container
RUST_LOG=warn,hco::container=debug hco api

12 Seccomp / Bezpieczeństwo

hco obsługuje filtrowanie syscalli przez seccomp przy użyciu biblioteki libseccomp. Profile są plikami JSON kompatybilnymi ze schematem Docker/Podman.

Walidacja inputów

Moduł src/validation.rs waliduje wszystkie dane wejściowe CLI i API:

• Nazwy — tylko [a-zA-Z0-9_-], max 128 znaków
• Obrazy — blokuje metaznaki shell ($ ; & | ` \ { })
• Montowania — blokuje path traversal (../), wymaga ścieżek absolutnych, blokuje wrażliwe ścieżki (/proc, /sys, /etc/shadow itd.)
• Porty — format host:container[/tcp|udp], zakres 1–65535
• Env — klucz musi pasować do [A-Za-z_][A-Za-z0-9_]*
• Memory limit — format \d+(B|KB|MB|GB)
• CPU percent — zakres 1–100

Format profilu seccomp (JSON)

{
  "default_action": "SCMP_ACT_ERRNO",
  "architectures": ["x86_64", "aarch64"],
  "syscalls": [
    {
      "names": ["read", "write", "open", "close", "stat",
                "fstat", "lstat", "poll", "lseek", "mmap",
                "mprotect", "munmap", "brk", "rt_sigaction",
                "rt_sigprocmask", "ioctl", "access", "pipe",
                "select", "nanosleep", "getpid", "fork",
                "execve", "exit", "exit_group", "getdents64"],
      "action": "SCMP_ACT_ALLOW"
    }
  ]
}

Dostępne akcje

13 Stan — SQLite NOWE

Stan kontenerów, podów i alokacji IP jest przechowywany w bazie danych SQLite w trybie WAL (Write-Ahead Logging). Zastępuje poprzednie podejście z plikami JSON w /var/run/hackeros/, eliminując race conditions przy równoległych operacjach.

Lokalizacja bazy

/var/lib/hackeros/state.db

Można zmienić przez flagę --db <path> przy starcie hco api.

Schemat bazy

sqlite3 /var/lib/hackeros/state.db \
  "SELECT id, name, image, status, ip_address FROM containers;"

# Sprawdź alokacje IP
sqlite3 /var/lib/hackeros/state.db \
  "SELECT container_id, suffix, released FROM ipam;"

14 Systemd / Socket Activation NOWE

hco dostarcza plik unit systemd (hco-api.service) oraz opcjonalny plik socket (hco-api.socket) dla socket activation.

Instalacja

sudo cp hco-api.service /etc/systemd/system/
sudo cp hco-api.socket  /etc/systemd/system/   # opcjonalnie

sudo systemctl daemon-reload
sudo systemctl enable --now hco-api.service

Konfiguracja przez EnvironmentFile

Utwórz plik /etc/hco/hco.env z nadpisaniami:

HCO_API_ADDR=0.0.0.0:8443
HCO_API_TOKEN=my-production-secret
HCO_TLS_CERT=/etc/hco/tls.crt
HCO_TLS_KEY=/etc/hco/tls.key
HCO_OTLP=http://otel-collector:4317
RUST_LOG=hco=info

Zarządzanie serwisem

# Status serwisu
systemctl status hco-api

# Logi (journald)
journalctl -u hco-api -f

# Restart
systemctl restart hco-api

Socket Activation

Plik hco-api.socket umożliwia uruchomienie serwisu dopiero przy pierwszym połączeniu na port 8080. Oszczędza zasoby przy starcie systemu.

sudo systemctl enable --now hco-api.socket
# hco-api.service uruchomi się automatycznie przy pierwszym połączeniu

15 Sieć / CNI

Domyślny tryb sieciowy to bridge. Każdy kontener dostaje parę interfejsów veth: jeden po stronie hosta (podłączony do mostu hkbr0), drugi wewnątrz kontenera jako eth0. Adres IP jest przydzielany przez IPAM z gwarancją unikalności.

Tryby sieci

Konfiguracja mostu

Most jest tworzony automatycznie przy pierwszym uruchomieniu:

Domyślna podsieć: 10.10.0.0/24
Gateway:         10.10.0.1  (przypisany do hkbr0)
IP kontenerów:   10.10.0.2 — 10.10.0.254  (zarządzane przez IPAM)
NAT:             iptables MASQUERADE na ruch wychodzący
FORWARD:         reguły ACCEPT dla każdego przekierowanego portu

Przekierowanie portów

Reguły iptables DNAT są dodawane dla każdego mapowania portów. Obsługiwane protokoły: tcp i udp. Nieużywany interfejs veth host-side jest usuwany przez ip link del po zatrzymaniu kontenera (nazwa zapisana w SQLite jako veth_host).

hco run dns -i coredns:latest -p 5353:53/udp -d

16 Obrazy OCI

hco pobiera obrazy bezpośrednio z rejestrów OCI (Docker Hub, prywatne) bez potrzeby instalowania Dockera. Warstwy są buforowane lokalnie.

Format referencji obrazu

Cache warstw i timeouty

Warstwy obrazów są zapisywane w /var/lib/hackeros/layers/. Przy ponownym użyciu tej samej warstwy (identyczny digest SHA256) pobieranie jest pomijane. Każda pobrana warstwa jest weryfikowana przez SHA256.

Garbage collect

# Usuń warstwy nieużywane przez żaden obraz
hco image gc

Import z archiwum tar

hco image import my-image:local -f /tmp/myimage.tar

17 Błędy i diagnostyka

hco używa biblioteki miette do czytelnych komunikatów błędów z kontekstem i wskazówkami. Logowanie odbywa się przez tracing z filtrem kontrolowanym przez RUST_LOG.

Logi kontenerów

Stdout kontenera jest przechwytywany do pliku z limitem 100 MB i rotacją 3 plików (np. .log.1, .log.2, .log.3):

/var/log/hackeros/<container-id>.log

tail -f /var/log/hackeros/a3f7c2d1-8b4e-4f2a-b1c3-d5e6f7a8b9c0.log

# Lub przez API:
curl -H "Authorization: Bearer <token>" \
     https://localhost:8443/containers/a3f7c/logs | jq .logs

Rollback przy błędzie startu

Jeśli start kontenera nie powiedzie się na dowolnym etapie (np. błąd sieci po zamontowaniu OverlayFS), struktura StartResources automatycznie cofa wszystkie operacje: odmontowuje overlayfs, usuwa veth, czyści reguły iptables, usuwa wpis z SQLite i zwalnia IP z IPAM.

Typowe błędy

18 Licencja

HackerOS Containers jest udostępniany na licencji MIT.

Copyright (c) HackerOS Team <hackeros068@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.