linuxcloth

linuxcloth는 공식 TableCloth 카탈로그의 금융·공공 서비스를 Linux에서 일회용 Windows 11 QEMU/KVM 세션으로 여는 데스크톱 앱과 CLI입니다. 서비스에 필요한 Windows 패키지 설치와 실행은 게스트 안의 공식 Spork/SporkBootstrap에 맡기며, 카탈로그 패키지를 Linux 호스트에서 실행하지 않습니다.

현재 상태: 기술 프리뷰

실제 Windows 11 + KVM 환경에서 설치부터 금융 사이트 실행·종료까지 이어지는 end-to-end 검증이 아직 완료되지 않았습니다. 위협 모델의 production readiness 항목을 해소하기 전에는 실제 금융 업무에 사용하지 마세요.

설치 및 사용법

요구사항

• x86_64 Linux와 하드웨어 가상화가 활성화된 CPU
• 현재 사용자에게 읽기·쓰기 가능한 /dev/kvm
• QEMU/KVM, Q35 Secure Boot OVMF, swtpm, Bubblewrap, passt, virt-viewer
• 이미지 준비에 필요한 7z, wimlib-imagex, xorriso, mtools
• Windows 11 x64 ISO와 해당 Windows를 사용할 수 있는 유효한 라이선스
• 기본값 기준 Windows 게스트용 메모리 6 GiB와 96 GiB sparse 기준 이미지 및 세션 overlay를 수용할 디스크 공간
• 고정된 virtio-win 미디어를 처음 받을 네트워크 연결 또는 Windows 11 amd64용 vioscsi, NetKVM, qxldod, 게스트 도구가 들어 있는 로컬 virtio-win ISO

linuxcloth는 libvirt, TAP/bridge 네트워크, root 실행을 요구하지 않습니다. /dev/kvm 접근 문제를 해결하려고 앱 전체를 sudo로 실행하지 마세요. 설치 후 실제 준비 상태는 배포판 이름이 아니라 다음 검사 결과로 확인합니다.

linuxcloth doctor

호스트 요구사항과 배포판별 참고 사항은 운영 가이드에서 자세히 설명합니다.

패키지 설치

첫 공개 프리뷰의 패키지 대상은 다음과 같이 확정했습니다.

환경	설치 채널	현재 상태
Debian 12 (bookworm) x86_64	Cloudsmith APT	저장소 namespace·slug 설정 후 활성화
Fedora 44 x86_64	Cloudsmith DNF	저장소 namespace·slug 설정 후 활성화
Arch Linux x86_64	AUR linuxcloth-bin	최초 태그 게시 후 활성화
위 세 환경	GitHub Release 직접 설치	태그 게시 자동화 준비 완료

Cloudsmith의 실제 namespace와 repository slug는 아직 Git에 설정할 수 있는 값으로 제공되지 않았으므로, 복사 가능한 APT/DNF 저장소 등록 URL을 임의로 적지 않았습니다. 첫 태그 전 릴리스 운영 가이드의 1회 설정을 마치고 이 표와 설치 링크를 실제 값으로 갱신해야 합니다. Ubuntu, RHEL/CentOS 계열과 다른 Debian/Fedora 릴리스는 아직 지원 대상으로 검증하지 않았습니다.

GitHub Release에서 직접 설치

GitHub Releases에서 해당 버전의 SHA256SUMS와 전체 릴리스 자산을 같은 디렉터리에 내려받습니다. 먼저 모든 checksum이 일치하는지 확인합니다.

sha256sum --check --strict SHA256SUMS

릴리스 자산에는 GitHub OIDC 기반 provenance와 SBOM attestation도 생성됩니다. GitHub CLI가 있다면 설치할 원본 자산을 이 저장소에 대해 추가로 검증할 수 있습니다.

gh attestation verify ./linuxcloth_*_amd64.deb --repo shiinamachi/linuxcloth
gh attestation verify ./linuxcloth-*.x86_64.rpm --repo shiinamachi/linuxcloth

사용 중인 배포판 형식 하나만 설치합니다.

Debian 계열:

sudo apt install ./linuxcloth_*_amd64.deb

Fedora 계열:

sudo dnf install ./linuxcloth-*.x86_64.rpm

APT와 DNF 채널이 활성화된 뒤

이 README에 게시될 정확한 Cloudsmith Setup 링크에서 저장소 URL과 전체 GPG fingerprint를 확인해 저장소를 등록한 뒤 배포판 패키지 관리자를 사용합니다.

# Debian 12
sudo apt install linuxcloth

# Fedora 44
sudo dnf install linuxcloth

APT 및 DNF 저장소의 무료 오픈 소스 호스팅은 Cloudsmith가 제공합니다.

AUR 채널이 활성화된 뒤

AUR은 Arch Linux의 공식 바이너리 저장소가 아니므로 빌드 recipe를 직접 검토하세요. 최초 게시 후 다음과 같이 linuxcloth-bin의 세 관리 파일을 확인하고 빌드할 수 있습니다.

git clone https://aur.archlinux.org/linuxcloth-bin.git
cd linuxcloth-bin
less PKGBUILD .SRCINFO LICENSE
makepkg -si

CI는 Debian 12와 Fedora 44에서 완성 패키지의 설치·CLI smoke test·제거를 수행하고, 고정 Arch 컨테이너에서 AUR recipe 생성, makepkg, pacman 설치, 파일/ELF/CLI 검사와 제거까지 수행합니다. Cloudsmith는 APT index를 GPG 서명하고, DNF index와 RPM 패키지를 GPG 서명합니다. 서명 후 Cloudsmith RPM의 바이트는 GitHub 원본과 달라지므로 GitHub attestation 검증은 GitHub Release의 원본 RPM에 적용하고, Cloudsmith RPM은 서명·NEVRA·payload 동등성으로 검증합니다. AUR은 GitHub tar의 정확한 SHA-256과 내부 파일 manifest를 검사합니다.

이번 프리뷰의 GuestBridge는 Authenticode로 서명되어 있지 않습니다. 위 채널 서명과 attestation은 배포 바이트를 보호하지만 Windows 발행자 신원을 대신하지 않습니다. 자세한 경계는 패키징 가이드와 ADR-0039를 확인하세요.

처음 실행하고 Windows 환경 준비하기

애플리케이션 메뉴에서 linuxcloth를 열거나 터미널에서 데스크톱 앱을 시작합니다.

linuxcloth-desktop

처음 실행하면 다음 순서로 준비합니다.

1. linuxcloth가 남은 세션 복구, 호스트 기능, 패키지에 포함된 GuestBridge, Secure Boot OVMF와 기존 Windows 환경을 검사합니다.
2. 필수 호스트 패키지가 없으면 Windows 환경 준비하기에서 검토된 Arch/Debian/Fedora 의존성 계획을 보여 줍니다. PackageKit을 사용할 때만 명시적인 사용자 동의와 polkit 인증 뒤 설치하고 다시 검사합니다. PackageKit이 없으면 표시된 명령을 사용자가 직접 실행해야 합니다.
3. 사용자가 직접 준비한 정품 Windows 11 x64 ISO를 선택합니다. linuxcloth는 ISO를 업로드하지 않으며, 제한된 Bubblewrap 환경에서 내용을 검사하고 SHA-256을 계산합니다.
4. linuxcloth가 릴리스에 고정된 virtio-win ISO를 정확한 크기와 SHA-256으로 검증해 준비합니다. 네트워크를 사용할 수 없으면 호환되는 로컬 virtio-win ISO를 선택할 수 있습니다.
5. 선택한 Windows edition을 새 qcow2 디스크에 설치하고 GuestBridge, 드라이버와 SPICE 화면 통합을 검증한 뒤 기준 이미지를 봉인합니다. 중단되거나 복구 가능한 실패가 발생하면 staging 상태를 보존해 다시 이어갈 수 있습니다.
6. 카탈로그에서 서비스를 골라 실행합니다. 정상 종료 뒤 세션별 qcow2 overlay와 일회용 상태를 정리하며 기준 이미지는 변경하지 않습니다.

Windows ISO, 제품 키, 생성한 기준 이미지와 세션 디스크는 linuxcloth 배포물에 포함되지 않습니다. ISO 선택, 복구, 기준 이미지 관리와 선택적 폴더 공유의 전체 동작은 운영 가이드를 참고하세요.

CLI로 사용하기

사용 가능한 명령과 옵션은 내장 도움말이 가장 정확합니다.

linuxcloth --help
linuxcloth catalog --help
linuxcloth image --help
linuxcloth run --help

카탈로그에서 서비스 ID를 찾고 준비된 이미지를 확인합니다.

linuxcloth catalog search WooriBank
linuxcloth image list
linuxcloth image verify windows-11

설치된 패키지에서 CLI로 기준 이미지를 직접 만드는 전문 사용자 흐름은 로컬 virtio-win ISO 경로를 명시해야 합니다.

linuxcloth image build start windows-11 \
  --windows-iso /absolute/path/Windows11.iso \
  --virtio-win-iso /absolute/path/virtio-win.iso \
  --guest-bridge /usr/lib/linuxcloth/guest/linuxcloth-guest-bridge.exe

ISO에 지원되는 Windows edition이 여러 개이고 하나를 자동 추천할 수 없을 때만 --windows-image-index를 추가합니다. 보존된 staging 디렉터리를 복구하거나 이어 가는 명령은 linuxcloth image --help와 이미지 수명 주기 문서를 참고하세요.

준비한 이미지에서 서비스를 실행합니다.

linuxcloth run WooriBank --image windows-11

네트워크를 끈 진단 세션은 --no-network를 추가합니다. 클립보드는 기본적으로 꺼져 있으며 꼭 필요한 세션에서만 --enable-clipboard로 명시적으로 허용할 수 있습니다. 비정상 종료 뒤 남은 세션은 소유 프로세스를 검증한 다음 안전하게 복구·정리합니다.

linuxcloth cleanup

보안 기본값과 알려진 제한

• 공식 TableCloth 카탈로그 원본을 수정하지 않으며, 카탈로그의 설치 파일은 Windows 게스트 안에서만 처리합니다.
• 일반 세션은 읽기 전용 기준 이미지와 세션별 qcow2 overlay를 사용합니다. 정상 종료 또는 소유권을 입증한 복구 뒤 일회용 상태를 지우고, 소유권이 불명확하면 조사할 수 있도록 보존합니다.
• 호스트 폴더 공유, 클립보드, USB redirection, 마이크와 카메라는 기본적으로 꺼져 있습니다. 폴더 공유는 매 세션 명시적으로 선택해야 하며 새 선택은 읽기 전용으로 시작합니다.
• 게스트로 들어오는 네트워크 연결과 포트 전달은 차단합니다. 네트워크 사용 세션의 외부 연결은 허용되며, 현재 passt 경계는 private/LAN, link-local, metadata 주소로 향하는 연결까지 차단하지는 않습니다.
• remote-viewer는 아직 Bubblewrap으로 격리하지 않습니다. GuestReady 상태는 고정·검증된 Spork 프로세스 시작을 뜻할 뿐, 요청한 사이트가 실제로 열렸다는 증명은 아닙니다.
• GuestBridge Authenticode와 실제 Windows/KVM end-to-end 검증 등 남은 금융 업무·production readiness 게이트는 위협 모델에 기록합니다.

기여자를 위한 빌드 가이드

소스와 고정 도구 준비

개발 도구 버전은 mise.toml과 global.json에 정확히 고정되어 있습니다. 현재 .NET SDK는 10.0.302이며 floating SDK alias를 사용하지 않습니다. x86_64 Linux에서 Git과 mise를 준비한 다음 공식 카탈로그 submodule과 도구를 설치합니다.

git submodule update --init --recursive
mise install
mise exec -- dotnet --version

마지막 명령은 10.0.302를 출력해야 합니다.

복원, 빌드, 테스트

잠금 파일을 변경하지 않는 locked restore 뒤 format, Release 빌드와 전체 테스트를 실행합니다.

mise exec -- dotnet restore linuxcloth.slnx --locked-mode
mise exec -- dotnet format linuxcloth.slnx --verify-no-changes --no-restore
mise exec -- dotnet build linuxcloth.slnx --configuration Release --no-restore
mise exec -- dotnet test linuxcloth.slnx --configuration Release --no-build --no-restore

패키징 shell script를 변경했다면 CI와 같은 정적 검사도 실행합니다.

shellcheck eng/*.sh

변경 범위에 맞는 테스트를 먼저 실행하고, 제출 전에는 위 전체 검증을 통과시키세요. 개발 규칙은 AGENTS.md, 주요 설계 결정은 ADR 목록, 데이터 경계는 카탈로그 계약과 WSB/Spork 계약에 있습니다.

개발 빌드 실행

CLI와 Avalonia 데스크톱 앱을 소스에서 실행할 수 있습니다.

mise exec -- dotnet run --project src/LinuxCloth.Cli -- doctor
mise exec -- dotnet run --project src/LinuxCloth.Cli -- catalog search WooriBank
mise exec -- dotnet run --project src/LinuxCloth.Desktop

데스크톱 프로젝트의 개발 Run target은 현재 win-x64 GuestBridge를 single-file로 publish해 데스크톱 출력의 관리 대상 guest 디렉터리에 둔 뒤 앱을 시작합니다.

릴리스 staging과 패키지 검증

릴리스 staging은 self-contained linux-x64 CLI/데스크톱과 single-file win-x64 GuestBridge를 한 설치 tree로 만듭니다. artifacts/stage가 아직 존재하지 않는 깨끗한 checkout에서 실행합니다.

mise exec -- eng/publish-linux.sh --output artifacts/stage
eng/validate-package-tree.sh --root artifacts/stage --strict-tools

DEB/RPM 도구를 한 호스트에 모두 설치하지 않았다면 CI와 같은 digest 고정 Debian 12/Fedora 44 컨테이너에서 두 형식을 만들고 설치 smoke test를 실행합니다. Docker 또는 Podman이 필요합니다.

eng/package-in-containers.sh --stage artifacts/stage --output artifacts/packages
eng/test-packages-in-containers.sh --packages artifacts/packages

배포판별 직접 빌드, staging tree 구조, 재현성, SBOM, attestation과 서명 책임은 패키징 가이드에 있습니다. 운영 데이터 경로와 복구 절차는 운영 가이드를 확인하세요.

태그 형식, GitHub Environment, Cloudsmith OIDC/GPG, AUR SSH key, 부분 게시 복구와 v0.1.0-preview.1 실행 절차는 릴리스 운영 가이드를 따르세요.

라이선스

linuxcloth 소스 코드는 별도 표기가 없는 한 GNU Affero General Public License v3.0 이상 조건으로 제공됩니다. 공식 TableCloth 카탈로그와 기타 제3자 구성 요소에는 각각의 라이선스가 적용됩니다.