이야기 5.3 사용자 매뉴얼 (이 프로젝트용)

이 문서는 도스 + 이야기 5.3를 이 저장소의 패키지(직접 실행/AppImage)로 사용하는 방법을 정리한 한국어 매뉴얼입니다.

1) 개요

• 이야기 5.3는 원래 모뎀(AT 명령) 기반 통신 프로그램입니다.
• 이 프로젝트는 모뎀 대신 다음 경로로 비비에스(BBS)에 연결합니다.
• 이야기 5.3 -> 도스박스 가상 모뎀 -> 브리지(bridge) -> SSH 서버(또는 비비에스(BBS))
• 기본 구성은 SSH_AUTH_MODE=bbs이며, SSH 키 없이 세션을 열고 BBS 내부 로그인(ID/PW)을 사용하는 시나리오를 기본으로 둡니다.

2) 실행 방법

2-1. 직접 실행 (개발/테스트)

bash tools/run-dosbox.sh

2-2. AppImage 실행

AppImage 직접 실행:

./dist/IYAGI-linux-x86_64.AppImage

3) 첫 실행 시 설정 파일

실행 모드에 따라 .env 위치가 다릅니다.

• 직접 실행(tools/run-dosbox.sh) 기본값: iyagi-data/.env (저장소 루트 기준)
• AppImage 직접 실행 기본값: ${XDG_DATA_HOME:-~/.local/share}/iyagi-terminal/ 한 디렉터리에 .env, keys/, app/, downloads/, staging/ (구조는 run-dosbox.sh의 iyagi-data/와 동일). 예전에는 ~/.config/iyagi-terminal/.env만 쓰기도 했으며, 최신 런처는 예전 경로에 .env가 있으면 새 위치로 복사합니다.
• Windows 패키지(launch.bat) 기본값:
  • 설정: 설치/압축 해제 폴더의 .env
  • 예: C:\Users\<사용자>\Downloads\IYAGI\.env
• macOS .app 런처(Contents/MacOS/launcher) 기본값:
  • 설정: ~/Library/Application Support/IYAGI/.env
  • 데이터: ~/Library/Application Support/IYAGI/downloads/
• 공통: USER_DATA_ROOT를 지정하면 해당 경로를 우선 사용합니다.

.env는 언제 생기나요? 사용자 데이터 경로에 .env가 없을 때 첫 실행에서 번들된 .env.example을 복사해 만듭니다. (이미 있으면 덮어쓰지 않습니다.)

런처의 값 해석 우선순위:

1. 셸에서 export한 환경변수
2. .env
3. 런처 기본값(${VAR:-default})

현재 접속 모델은 ATDT 직접 다이얼 기반이며, 호스트는 다이얼 문자열에서 결정됩니다.

IYAGI_USER=ssh_접속_계정
BRIDGE_PORT=2323
SSH_AUTH_MODE=bbs

주요 옵션:

• SSH_AUTH_MODE=bbs: 기본값. 키 생성 없이 비비에스(BBS) 스타일 접속.
• SSH_AUTH_MODE=key: 전통 SSH 키 인증 사용(이 경우에만 iyagi-data/keys 사용).
• DOSBOX_SCANLINES: 스캔라인 셰이더 on/off
• DOSBOX_GLSHADER: 스캔라인 셰이더 프리셋

4) 접속 절차 (이 프로젝트 기준)

1. 런처가 브리지(bridge) 프로그램을 먼저 실행합니다. (127.0.0.1:2323 대기)
2. 도스박스에서 이야기 5.3가 시작됩니다.
3. 이야기에서 ATDT호스트:포트를 입력해 다이얼합니다. (예: ATDT127.0.0.1:40000)
4. 브리지(bridge) 프로그램이 ATDT의 호스트/포트를 파싱해 해당 SSH 대상으로 연결합니다.

4-1. 다이얼 문자열 형식

• ATDT호스트:포트
  • 예: ATDT127.0.0.1:40000
• ATDT=호스트:포트
  • = 접두어를 허용합니다.
  • 예: ATDT=bbs.runable.app:40000
• ATDT=사용자@호스트:포트
  • 다이얼 문자열에서 SSH 사용자를 직접 지정합니다.
  • 예: ATDT=ssh@localhost:40000 -> ssh@localhost -p 40000 형태로 연결
• ATDT-...
  • 빠른 다이얼 모드(다이얼/링 사운드 생략)로 즉시 연결 시도

4-2. 문자 다이얼 DTMF 매핑

숫자 0-9, *, #은 기존처럼 해당 DTMF 음을 재생합니다.

문자가 포함된 다이얼 문자열은 전화 키패드 기준으로 숫자 DTMF로 변환해 재생합니다.

• ABC -> 2
• DEF -> 3
• GHI -> 4
• JKL -> 5
• MNO -> 6
• PQRS -> 7
• TUV -> 8
• WXYZ -> 9

예: ATDT=bbs.runable.app:40000 입력 시 bbsrunableapp 부분은 위 매핑에 따라 숫자 DTMF가 재생됩니다.

5) 전화번호부/통신 설정

이 프로젝트는 빌드 시 scripts/configure_iyagi.py로 이야기 설정 파일을 자동 패치합니다.

• COM4 -> 브리지(bridge) 프로그램(BRIDGE_PORT) 경로 사용
• 다운로드 경로를 패키지 구조에 맞게 조정

6) 파일 전송 (ZMODEM)

이야기 5.3는 ZMODEM 전송을 지원합니다.

• 업로드: 이야기의 파일전송 메뉴에서 업로드 실행
• 다운로드: 이야기의 파일전송 메뉴에서 다운로드 실행
• 자동 다운로드/프로토콜 동작은 상대(BBS) 측 설정에 따라 달라질 수 있습니다.

수신 파일 저장 위치:

• 직접 실행 기본값: iyagi-data/downloads/
• AppImage 기본값: ${XDG_DATA_HOME:-~/.local/share}/iyagi-terminal/downloads/
• Windows 패키지(launch.bat) 기본값: (설치/압축 해제 폴더)\downloads\
• macOS .app 런처 기본값: ~/Library/Application Support/IYAGI/downloads/

7) 자주 쓰는 조작

원본 도움말(I.HLP) 기준으로 F1 도움말 체계가 제공됩니다.

• F1: 도움말/현재 항목 안내
• 통신, 캡처, 전송, 스크립트 등은 이야기 내부 메뉴에서 접근 가능
• CLS 또는 CLEAR: 명령 모드에서 빈 줄 28개를 출력해 화면을 빠르게 정리

주의: 배포본/키맵 파일(KEY.DEF)에 따라 일부 단축키 체계가 달라질 수 있으므로, 실제 사용 중에는 F1 도움말을 우선 기준으로 보세요.

9) 문제 해결

9-1. 키 폴더가 보이는데 필요한가?

• 기본 SSH_AUTH_MODE=bbs에서는 필요 없습니다.
• SSH_AUTH_MODE=key일 때만 iyagi-data/keys를 사용합니다.
• keys 폴더는 SSH 키 인증에 쓰는 개인키/공개키 파일을 보관하는 위치입니다. 즉, 서버에 비밀번호 대신 키로 로그인할 때만 사용됩니다.
• 기본 BBS 모드에서는 키 인증을 쓰지 않으므로, 폴더가 비어 있어도 정상입니다.

9-2. 창이 너무 크거나 일부만 채워짐

• tools/run-dosbox.sh와 tools/run-appimage.sh를 같은 USER_DATA_ROOT로 맞춰 실행하세요.
• .env에서 CPU/출력 옵션을 조정하세요.
  • 커서가 너무 빠르면: DOSBOX_CPU_CYCLES=1000 (또는 더 낮게)
  • 스캔라인 셰이더를 끄려면: DOSBOX_SCANLINES=0

9-3. 메뉴바(상단 도스박스 메뉴) 숨기기

현재 런처는 도스박스 실행 시 메뉴를 숨기도록 설정되어 있습니다.

10) 원문 자료

• DNAVI DOS UTIL - 이야기 5.3
• 이야기 5.3 소개 글 (수알치 블로그)