문서 홈 · 설치 가이드 · 쉬운 용어집 · 문제 해결 가이드
이 문서는 설치를 마친 뒤 DawnShell을 사용하는 방법을 설명합니다. Debian과 SSH를 아직 구성하지 않았다면 먼저 설치 가이드를 따라 주세요.
앱은 자주 하는 일을 세 화면으로 나눕니다.
| 화면 | 포함된 기능 |
|---|---|
| 홈 | 처음 설치, 자동 시작, 서버 시작·중지·상태 확인 |
| 접속 | SSH 키와 debian·root 로컬 암호 |
| 고급 | USB, 하드웨어 코덱, cgroup, Docker, 진단, 삭제 |
모든 스위치, 선택 항목, USB ID 입력은 같은 규칙을 사용합니다. 값을 바꾸면 하단 탐색 메뉴 위에 적용 바가 나타납니다. 여러 설정을 바꿔도 한 번만 누르면 되며, 런타임 정책 변경이 필요할 때 실행 중인 Debian을 최대 한 번만 재시작합니다. 설치·시작·중지·검사·키 내보내기·암호 변경은 설정이 아니라 명령이므로 해당 버튼을 누르면 즉시 실행됩니다.
- BFU(Before First Unlock)는 재부팅 후 첫 잠금 해제 전 상태입니다.
- AFU(After First Unlock)는 재부팅 후 잠금을 한 번 이상 해제한 상태입니다.
- DawnShell은 BFU에서 Debian
systemd와 SSH를 시작합니다. - 잠금을 해제해도 같은 Debian과 SSH가 계속 실행됩니다.
- Debian은 Android 네트워크를 공유하므로 일반 가상 머신처럼 완전히 격리되지 않습니다.
DE, CE, rootfs, PID 같은 표현은 쉬운 용어집에 설명되어 있습니다. Direct Boot 자체의 동작은 Google 공식 문서에서 확인할 수 있습니다.
다이렉트 부트 Debian 부트스트랩 활성화는 다음 재부팅부터 자동으로 Debian을 시작할지 결정합니다. 스위치를 바꾼 뒤에는 하단의 적용을 누릅니다.
Magisk 루트 권한 요청 / 확인은 현재 앱이 root를 사용할 수 있는지 확인합니다. BFU에서는 Magisk 승인 창을 띄울 수 없으므로 미리 영구 허용해야 합니다.
BFU 검사 결과 새로고침은 마지막 부팅 때 기록된 결과를 읽습니다. 잠금 해제 후 이 버튼을 눌러도 BFU 검사가 새로 실행되지는 않습니다.
CE 저장소를 읽을 수 있는 BFU 환경 허용은 위험한 예외 옵션입니다. 정상적인 FBE(File-Based Encryption) 기기에서는 꺼 둡니다. 이 옵션은 암호화를 고치는 기능이 아니며, ROM이 이미 CE를 노출하는 위험을 사용자가 수락할 때만 차단을 해제합니다.
Debian 13 Trixie rootfs 설치는 /data/local/debian에 Debian 전체 파일
구조를 만듭니다. 기존의 정상 설치를 자동으로 덮어쓰지 않습니다.
Debian 13 systemd + SSH 구성은 다음 항목을 준비합니다.
- systemd와 D-Bus
- OpenSSH 서버
debian사용자- 앱이 생성한 공개 키
- 부팅 성공을 확인하는 서비스
두 작업은 Android 잠금을 해제한 상태에서만 시작할 수 있습니다. 진행 상황은 각각 Debian 설치와 시스템 구성 로그에서 확인합니다.
구성 작업은 일부 Android 커널에 필요한 _apt 인터넷 GID 3003을 자동으로
설정하고, 이전 실패로 중단된 dpkg 작업을 올바른 private mount 환경에서 먼저
복구합니다.
일부 LineageOS 기기에서 _apt만 네트워크 권한 오류를 내면
LineageOS apt 네트워크 권한 해결 가이드를
따르세요. 인터넷 연결이나 DNS가 없는 경우와는 원인이 다릅니다.
- 시작은 설치 상태를 확인한 뒤 Debian systemd를 시작합니다.
- 재시작은 기존 인스턴스를 정상 종료한 뒤 새로 시작합니다.
- 상태는 systemd, D-Bus, SSH, TCP 22, cgroup 상태를 확인합니다.
- 중지는 Debian 서비스를 정리하고 SSH를 중지합니다.
Android 잠금 해제 이벤트는 서버를 중지하지 않습니다. 수동으로 중지했다면 시작을 누르거나 다음 재부팅 때 자동 시작을 기다립니다.
다른 PC에서는 SSH 개인 키 파일 내보내기를 사용하는 방법을 권장합니다.
chmod 600 dawnshell-ed25519
ssh -i ./dawnshell-ed25519 -p 22 debian@PHONE_IP같은 휴대폰의 신뢰할 수 있는 로컬 셸에서는 다음 순서로 진행합니다.
- 로컬 셸용 개인 키 가져오기 명령 복사를 누릅니다.
- 경고를 확인하고 복사한 명령을 본인의 로컬 셸에서 한 번 실행합니다.
- SSH 접속 명령 복사를 누르고 복사한 명령을 실행합니다.
가져오기 명령에는 SSH 개인 키 전체가 포함됩니다. 메신저, 공유 화면, 다른 앱의 셸에 붙여 넣지 마세요. 클립보드는 120초 뒤 지워지지만, 가능하면 파일 내보내기를 사용해 주세요.
새 임의 SSH 클라이언트 키 생성은 기존 키를 영구 교체합니다. 교체할 때는 다음 순서를 지킵니다.
- 필요한 기존 개인 키를 백업합니다.
- 새 키를 생성합니다.
- Debian 13 systemd + SSH 구성을 다시 실행합니다.
- 새 개인 키를 다시 내보냅니다.
- 새 키로 접속한 뒤 이전 파일을 폐기합니다.
rootfs 재설치 후 SSH 호스트 키 경고가 발생하면 실제 재설치 여부를 확인한 뒤 해당 주소의 항목만 지웁니다.
ssh-keygen -R "[PHONE_IP]:22"앱에서 root와 debian의 로컬 비밀번호를 각각 설정할 수 있습니다. 비밀번호는
Debian의 chpasswd에 직접 전달되며 앱 설정, DE 저장소, 로그에 저장되지
않습니다. SSH 비밀번호 인증은 계속 꺼진 상태로 유지됩니다.
SSH로 debian에 접속한 뒤 root로 전환하려면 다음 명령을 실행합니다.
su root앱에서 설정한 root 비밀번호를 입력합니다. root 셸에서 나가려면 exit를
실행합니다. 이 root는 Android 기기 수준 권한을 사용할 수 있으므로 신뢰한
명령만 실행해 주세요.
Android 전체를 재부팅하려면 root 셸에서 다음 명령을 사용합니다.
reboot --check
reboot nowreboot --check는 연결 기능만 확인합니다. reboot now는 Android 기기 전체를
즉시 재부팅합니다. systemctl reboot는 Debian 격리 환경 시험용이므로 Android
재부팅 명령으로 사용하지 않습니다.
Android 재부팅은 이 reboot 명령을 통해서만 가능합니다. Debian과 그 안에서
실행되는 컨테이너는 커널에 직접 재부팅을 요청할 수 없습니다. 일부 커널은
컨테이너의 재부팅 요청을 격리하지 못해 기기 전체가 재시작되기 때문입니다.
Docker 컨테이너를 시작하거나 정리할 때 기기가 재부팅되는 문제가 이렇게
차단됩니다.
raw USB 공유는 기본적으로 꺼져 있습니다. 모드를 선택한 뒤 공통 적용 버튼을 누릅니다. USB·cgroup·Docker 변경은 한 작업으로 합쳐지므로 실행 중인 Debian은 최대 한 번만 재시작하고, 중지 상태라면 다음 시작부터 적용합니다. USB Ethernet은 Debian이 Android network namespace를 이미 공유하므로 이 설정이 필요하지 않습니다.
구형 커널에서 Debian 13의 lsusb -t는 커널에 없는 최신 rx_lanes와
tx_lanes sysfs 속성을 조회할 수 있습니다. DawnShell은 USB 정책 적용 때 관리형
호환 래퍼를 설치하여 이 속성의 예상된 ENOENT 메시지만 숨기고 다른 USB 오류는
그대로 표시합니다.
- 직접 패스스루는
/dev/bus/usb를 노출하고 hot-plug를 반영하되 Android 커널 드라이버 연결을 유지합니다. 일반 libusb 확인에는 먼저 이 모드를 씁니다. - 독점 패스스루는 정확한
VID:PID를 입력한 장치의 모든 interface를 추가로 unbind합니다.0403:6001, 10c4:ea60처럼 쉼표 또는 공백으로 구분하며 하나 이상이 필수입니다. 새로 연결된 일치 장치도 감시하고 Debian 종료 때 분리한 드라이버 복원을 시도합니다.
끄기는 정확히 raw USBFS 정책입니다. /dev/bus/usb를 가리고 문자 장치 major
189를 거부하지만 Android 커널의 USB 감지를 중단하지는 않으므로 공유 sysfs에서
장치가 계속 보일 수 있습니다. 또한 커널 드라이버가 만든 /dev/block/sd*, USB
Ethernet, ttyUSB/ttyACM, input, video, audio 같은 파생 자원은 raw USBFS 정책
범위 밖이며 장치 class별 추가 격리가 필요합니다.
ls -l /dev/bus/usb/*/* 2>/dev/null
lsusb 2>/dev/null || true
dmesg | tail -n 100USB 시리얼, 저장장치, 카메라, 오디오와 입력 장치는 Android 커널이 지원해야
합니다. root라도 SELinux가 접근을 거부할 수 있습니다. 독점 모드는 Android
입력, 저장장치, 네트워크, ADB 또는 복구 연결을 끊을 수 있으므로 고장 나도 되는
주변기기와 별도 복구 수단으로 시험하세요. 비정상 종료 뒤에는 장치를 뽑거나
재부팅해야 할 수 있습니다. 휴대전화 내부 USB/gadget controller는 선택하지 말고,
같은 USB 저장장치 파일시스템을 양쪽에서 동시에 마운트하지 마세요. Docker에는
필요한 노드를 --device로 별도 전달하고 --privileged는 피하세요.
Debian에서 영상을 인코딩하거나 디코딩할 때 Android의 전용 영상 코덱을 대신 사용하게 하는 기능입니다. GPU 패스스루가 아닙니다. Debian은 컨테이너 분해와 재조립만 담당하고, 실제 코덱 작업은 명령별 bionic NDK worker가 수행한 뒤 상속 공유 descriptor로 결과만 돌려줍니다.
- 앱에서 다이렉트 부트에서 하드웨어 코덱 브리지 활성화를 켭니다.
- 하단의 적용을 누릅니다.
- 하드웨어 코덱 검사를 누릅니다.
- Debian 13 systemd + SSH 구성을 다시 실행합니다.
- 파일 기반 하드웨어 AVC 디코드 자체 검사 다운로드 및 실행을 누릅니다.
- Debian에서
sudo dawnshell-codec health --format json을 실행합니다.
구성이 끝나면 Debian에 다음 명령이 설치됩니다.
| 명령 | 용도 |
|---|---|
dawnshell-ffmpeg |
기존 FFmpeg 명령을 그대로 받아 자동으로 하드웨어 처리 |
dawnshell-hwdecode |
H.264/HEVC 디코딩 |
dawnshell-hwencode |
I420 원본 영상을 H.264/HEVC로 인코딩 |
dawnshell-hwtranscode |
H.264/HEVC를 H.264로 재인코딩 |
dawnshell-live-encode |
USB 웹캠·HLS·RTSP 입력을 실시간 AVC로 인코딩 |
dawnshell-codec-self-test |
코덱 브리지 동작 확인 |
gsmi |
3D GPU 상태와 DawnShell 코덱 작업을 구분해 표시 |
dawnshell-ffmpeg는 일반 ffmpeg와 같은 명령줄을 받습니다. 하드웨어로 똑같이
처리할 수 있으면 코덱 브리지로 보내고, 그렇지 않으면 원래 FFmpeg에 그대로
넘깁니다. 필터나 옵션이 조용히 무시되는 일은 없습니다.
dawnshell-ffmpeg -i input.mp4 -c:v libx264 -b:v 3M output.mp4
dawnshell-ffmpeg -i input.mp4 output.yuvDebian 구성 시 기본적으로 /usr/local/bin/ffmpeg가 DawnShell 래퍼를 가리킵니다.
상태를 확인하거나 안전하게 끄고 켜려면 관리 명령을 사용합니다.
dawnshell-ffmpeg-integration status
sudo dawnshell-ffmpeg-integration disable
sudo dawnshell-ffmpeg-integration enable
hash -r/usr/local/bin이 /usr/bin보다 앞에 있으므로 ffmpeg를 이름으로 실행하는
프로그램은 래퍼를 찾습니다. /usr/bin/ffmpeg 절대 경로를 쓰는 프로그램은 항상
Debian의 원래 FFmpeg를 사용합니다.
동작 방식은 환경 변수로 바꿀 수 있습니다.
| 값 | 동작 |
|---|---|
auto(기본값) |
가능하면 하드웨어, 아니면 소프트웨어 |
off |
항상 원래 FFmpeg 사용 |
require |
하드웨어로 처리할 수 없으면 오류로 중단 |
DAWNSHELL_FFMPEG_BRIDGE=require dawnshell-ffmpeg -i input.mp4 -c:v libx264 out.mp4성능을 비교하거나 문제를 확인하려면 require로 실행해 실제로 하드웨어 경로를
타는지 확인하세요.
- 입력이 H.264 또는 HEVC이고 영상 하나만 사용합니다.
- 출력 코덱이 AVC/HEVC MediaCodec 또는 지원되는 AVC 별칭이거나, 출력이
.yuv/.i420원본입니다. - 해상도가 16~4096이고 가로·세로가 짝수입니다.
-b:v는 1000~100000000 범위입니다.
다음은 소프트웨어로 넘어갑니다.
-vf,-filter등 필터 사용-crf,-preset같은 x264 전용 옵션- 입력이 여러 개이거나 오디오를 인코딩·필터링하는 경우
-c:v copy처럼 코덱 작업이 필요 없는 경우- VP9, AV1 등 지원하지 않는 코덱
전체 명령표, 자동 연동, 오디오 재결합 및 폴백 조건은 FFmpeg 하드웨어 코덱 사용법을 참고하세요.
-hwaccel mediacodec, -c:v h264_mediacodec 같은 순정 FFmpeg 문법도 그대로
동작합니다. 명령에 MediaCodec을 직접 적으면 하드웨어가 필수 조건이 되므로,
조용히 libx264로 떨어지지 않고 오류로 종료합니다. 자세한 내용은
순정 FFmpeg 문법 호환성 (MediaCodec)을
참고하세요.
오디오를 재인코딩하지 않고 유지하는 일반적인 명령은 다음과 같습니다.
sudo ffmpeg -y -i input.mp4 -c:a copy \
-c:v h264_mediacodec -b:v 4M output.mp4실시간 USB 웹캠과 HLS 사용법은 FFmpeg 가이드의 실시간 인코딩 절을 참고하세요. 하드웨어 작업 중 상태는 다른 셸에서 다음처럼 확인합니다.
gsmi --loop 1sudo dawnshell-codec health --format json
sudo dawnshell-codec-self-test앱의 파일 기반 하드웨어 AVC 디코드 자체 검사 버튼은 Debian에 wget과
ca-certificates가 없으면 apt로 먼저 설치한 뒤, test-videos.co.uk의 Big Buck
Bunny 1920x1080 H.264 MP4를 Debian에서 다운로드합니다. 앱은 다운로드된 파일을
DE 검사 디렉터리로 넘겨 MediaExtractor와 하드웨어 MediaCodec으로 직접
디코드합니다. 이 앱 내부 검사는 프로세스 간 영상 전송을 사용하지 않으며 검사
로그의 interprocess_media_bytes=0으로 이를 확인할 수 있습니다. 첫 실행은 패키지 설치와 약
5 MB 다운로드 때문에 시간이 더 걸릴 수 있습니다.
dawnshell-codec-self-test는 별도의 고급 private-worker 검사입니다. 파일 기반
검사가 성공해도 이 명령이 실패한다면 하드웨어 코덱 자체가 아니라 private worker
시작 또는 상속 memfd/eventfd 전송 문제로 구분할 수 있습니다.
backend에 실제 선택된 코덱 이름이 표시됩니다. 소프트웨어 코덱이 조용히
선택되는 일은 없으며, 하드웨어를 쓸 수 없으면 명확한 오류를 남깁니다. 코덱
기능이 실패해도 Debian과 SSH는 계속 동작합니다.
BFU에서 코덱이 실패한다면 Android 미디어 서비스가 아직 준비되지 않았을 수 있습니다. 잠금 해제 후 다시 시도해 차이를 확인하세요.
cgroup(control group)은 Linux가 프로세스 자원과 장치 접근을 관리하는 기능입니다. 기본값인 자동: cgroup v2 → v1 전환을 권장합니다.
- 자동은 전용 v2 하위 트리와 device BPF 연결을 실제로 시험하고, 실패한 검사 자원을 정리한 뒤 v1으로 전환합니다.
- v2 강제는 fallback을 끄므로 지원이 부족한 커널에서 Debian이 시작되지 않을 수 있습니다.
- v1 강제는 레거시 devices controller가 필요한 기기 진단용입니다.
선택은 다음 Debian 시작 또는 재시작부터 적용됩니다. 커널 버전 숫자만으로 backend를 결정하지 않으며 실제 capability 검사 결과를 사용합니다.
Docker의 안전한 시작점은 안전한 호스트 네트워크만 사용입니다.
docker info --format '{{.CgroupDriver}}'
docker run --rm --network host hello-world첫 명령 결과는 cgroupfs여야 합니다. DawnShell은 Docker가 Android 쪽 systemd에
container scope를 만들지 않도록 전용 cgroup 안에서 이 driver를 사용합니다.
컨테이너에 호스트 IPC 사용은 기본으로 켜져 있습니다. 일부 커널은 container의 private IPC namespace나 mqueue 설정에서 Android 전체를 재부팅할 수 있기 때문에, DawnShell은 위험한 생성 호출을 차단하고 관리형 wrapper가 다음을 적용합니다.
docker run과docker create에 명시적 IPC 설정이 없으면--ipc=host추가docker compose에는 각 service용 임시ipc: hostoverride 생성- 사용자가 직접 지정한
--ipc또는ipc:는 그대로 우선
host IPC는 Android, Debian, container가 IPC 객체를 공유하므로 격리가 약해집니다. 신뢰하지 않는 container에는 적합하지 않습니다. 설정을 바꾼 뒤에는 하단의 공통 적용 버튼을 누릅니다.
bridge 모드는 Android 전체의 방화벽, NAT(Network Address Translation), route와 forwarding을 변경할 수 있습니다. Wi-Fi, 모바일 데이터, USB Ethernet, VPN, Tailscale과 현재 SSH 연결이 끊길 수 있습니다. 별도 복구 방법이 없으면 강제 bridge 옵션을 사용하지 마세요. 오류별 조치는 문제 해결 가이드에 정리되어 있습니다.
상단의 로그에서 다음 화면을 열 수 있습니다.
- 앱 작업
- Debian 설치
- 시스템 구성
- 호환성 정책
- USB 패스스루
- 하드웨어 영상 코덱
- 장시간 코덱 검사
- 서버 수명 주기
- Direct Boot 진단
로그는 1초마다 갱신됩니다. 길게 눌러 필요한 부분을 선택하거나 전체 내용을 복사할 수 있습니다. 이전 줄을 읽기 위해 위로 스크롤하면 자동 따라가기가 멈춥니다. 오류를 공유할 때는 개인 키와 비밀번호를 추가하지 마세요.
SSH 서버는 Android 네트워크 주소가 아직 없어도 TCP 22에서 대기합니다. Android가 나중에 Wi-Fi, 모바일 데이터 또는 USB Ethernet 주소를 준비하면 Debian을 다시 시작하지 않아도 접속할 수 있습니다.
같은 Wi-Fi의 PC에서는 다음과 같이 접속합니다.
ssh -i ./dawnshell-ed25519 -p 22 debian@PHONE_IP같은 휴대폰에서는 앱이 복사해 주는 localhost 접속 명령을 사용합니다.
Tailscale을 커널 네트워크 모드로 사용하면 tailscale0 장치와 경로 설정이
Android와 공유됩니다. 재사용 인증 키를 BFU rootfs에 저장하지 마세요.
tailscaled.state도 PIN 입력 전 사용할 수 있는 기기 인증 정보로 취급합니다.
시스템 구성 후 DawnShell은 /usr/local/bin에 croc 호환 래퍼를 설치합니다. 명시적인
송신 파일과 수신 code는 열린 non-TTY stdin을 자동으로 무시하지만,
printf 'data' | croc send처럼 파일 인자가 없는 pipe 전송은 원래 동작을
유지합니다. 진단과 /usr/bin/croc 우회 방법은
croc 문제 해결을
참고하세요.
다음 항목을 백업하는 것을 권장합니다.
- 앱에서 내보낸 SSH 클라이언트 개인 키
- Debian의 필요한
/etc설정과 사용자 데이터 - 설치한 패키지 목록과 서비스 설정
앱을 제거하면 앱 DE/CE와 생성한 키는 삭제되지만 /data/local/debian은 남습니다.
Debian까지 완전히 삭제하려면 다음 순서로 진행합니다.
- 필요한 데이터와 키를 백업합니다.
- 중지를 누르고 상태에서 systemd가 종료됐는지 확인합니다.
- 위험 구역 → Debian rootfs 영구 삭제를 누릅니다.
- 두 확인 창을 읽고
DELETE를 입력합니다. - 로그에서
DEBIAN_ROOTFS_REMOVE_SUCCEEDED를 확인합니다. - Android 설정에서 DawnShell 앱을 제거합니다.
부팅, root, 설치, SSH, 네트워크, Docker, USB, 코덱 오류의 단계별 진단은 별도 문제 해결 가이드에 있습니다. 앱의 관련 실시간 로그와 Android 버전, CPU ABI, BFU/AFU 상태, 선택한 옵션을 함께 준비하면 좋습니다.