[Ubuntu] VirtualBox Guest Addtion 설치 가이드

VirtualBox에 Ubuntu를 설치하면 처음에는 창 크기에 맞춰 해상도가 바뀌지 않는다. 호스트와 클립보드도 공유되지 않는다. VirtualBox Guest Additions를 설치하면 화면 크기 자동 조정, 클립보드 공유, 드래그 앤 드롭, 공유 폴더를 쓸 수 있다.

Guest Additions는 설치할 때 게스트 커널에 맞춰 커널 모듈을 빌드한다. 그래서 VirtualBox 버전이 오래되면 최신 Ubuntu 커널에서 빌드가 실패한다. 이 글에서는 Ubuntu 게스트에 Guest Additions를 설치하고 동작을 확인하는 절차를 정리한다. 빌드 실패에 대처하는 방법도 함께 다룬다.

빌드에 필요한 패키지 설치

게스트 Ubuntu에서 컴파일러와 현재 커널의 헤더를 설치한다.

sudo apt update
sudo apt install -y build-essential bzip2 linux-headers-$(uname -r)
패키지용도
build-essentialgcc, make 등 커널 모듈 빌드 도구
linux-headers-$(uname -r)실행 중인 커널의 헤더. 버전이 다르면 모듈을 빌드할 수 없다
bzip2설치 파일(VBoxLinuxAdditions.run)의 압축 해제

Guest Additions CD 이미지 삽입

VM 창의 메뉴에서 장치(Devices) > 게스트 확장 CD 이미지 삽입(Insert Guest Additions CD image)…을 선택한다. VirtualBox는 자기 버전과 같은 Guest Additions ISO를 게스트의 광학 드라이브에 넣는다.

Ubuntu 데스크톱은 CD를 자동으로 마운트한다. 마운트 위치와 Guest Additions 버전을 확인한다.

mount | grep VBox

디렉터리 이름의 버전이 7.0.x 이하이면 다음 섹션의 “최신 Guest Additions ISO 사용”을 먼저 본다. 7.0.10은 Ubuntu 24.04의 6.8 커널에서 빌드에 실패한다.

VBoxLinuxAdditions.run 실행

cd /run/media/$USER/VBox_GAs_*
sudo ./VBoxLinuxAdditions.run

설치 프로그램은 vboxguest(기본 모듈), vboxsf(공유 폴더), vboxvideo(그래픽) 모듈을 차례로 빌드한다. 설치 파일은 /opt/VBoxGuestAdditions-<버전>에 들어간다. 설치가 끝나면 게스트를 재부팅한다.

sudo reboot

최신 Guest Additions ISO 사용

Guest Additions 7.0.10은 Ubuntu 24.04의 커널 6.8.0-149에서 빌드에 실패한다. vboxguest 모듈이 쓰는 함수 중 하나가 6.8 커널에서 빠졌기 때문이다. 빠진 함수는 strlcpy()다.

VirtualBox Guest Additions: Building the modules for kernel 6.8.0-149-generic.

VirtualBox Guest Additions: Look at /var/log/vboxadd-setup.log to find out what
went wrong
...
VirtualBox Guest Additions: kernel modules and services were not reloaded

# /var/log/vboxadd-setup.log 발췌
/tmp/vbox.0/VBoxGuest-linux.c:1364:9: error: implicit declaration of function ‘strlcpy’; did you mean ‘strscpy’? [-Werror=implicit-function-declaration]

이때는 VirtualBox를 최신 버전으로 올린다. VirtualBox를 바로 올릴 수 없으면 최신 Guest Additions ISO만 받아 넣는다. 최신 버전 번호는 LATEST-STABLE.TXT에 있다.

VER=$(curl -s https://download.virtualbox.org/virtualbox/LATEST-STABLE.TXT)
echo $VER
curl -O https://download.virtualbox.org/virtualbox/$VER/VBoxGuestAdditions_$VER.iso
curl -s https://download.virtualbox.org/virtualbox/$VER/SHA256SUMS | grep VBoxGuestAdditions_$VER.iso | sha256sum -c
7.2.22
VBoxGuestAdditions_7.2.22.iso: OK

호스트에서 받은 ISO는 장치 > 광학 드라이브(Optical Drives) > 디스크 파일 선택(Choose a disk file)…으로 넣는다. 그다음 앞의 VBoxLinuxAdditions.run 실행 단계를 따른다.

기존에 설치했던 7.0.10 버전에서 실행 했을 때는 기존 버전을 제거하고 7.2.22 버전이 설치됐다.

호스트가 VirtualBox 7.0.10이어도 Guest Additions 7.2.22는 설치된다. vboxguest와 vboxsf가 정상으로 빌드된다. 게스트는 호스트 버전을 아래와 같이 읽는다.

$ VBoxControl --version
7.2.22r175245
$ VBoxControl guestproperty get /VirtualBox/HostInfo/VBoxVer
Value: 7.0.10

같은 조합에서 vboxvideo 빌드는 drm_fb_helper_alloc_info 오류로 실패했다. 그래픽 컨트롤러가 기본값인 VMSVGA이면 게스트는 커널의 vmwgfx 드라이버를 쓰므로 화면 기능에 영향이 없다.

설치 확인

재부팅한 뒤 커널 모듈, 서비스, 버전을 확인한다.

lsmod | grep -E '^vbox'
modinfo -n vboxguest
systemctl is-active vboxadd vboxadd-service
VBoxControl --version
lspci -k | grep -A2 -i vga

modinfo -n의 경로가 misc/이면 Guest Additions가 빌드한 모듈이다. kernel/drivers/이면 Ubuntu 커널에 들어 있는 모듈이 그대로 로드된 것이다.

기능 확인

화면 크기 자동 조정

VM 창의 크기를 마우스로 바꾸면 게스트 해상도가 창 크기에 맞게 바뀐다. 바뀌지 않으면 보기(View) > 게스트 화면 자동 크기 조정(Auto-resize Guest Display)이 켜져 있는지 확인한다.

클립보드 공유와 드래그 앤 드롭

두 기능은 기본으로 꺼져 있다. 장치 > 클립보드 공유(Shared Clipboard) > 양방향(Bidirectional)을 선택한다. 드래그 앤 드롭도 같은 메뉴에서 켠다.

공유 폴더

  1. 장치 > 공유 폴더(Shared Folders) > 공유 폴더 설정…을 연다.
  2. 추가 아이콘을 누르고 호스트 폴더 경로를 고른다.
  3. “자동 마운트(Auto-mount)”와 “항상 사용(Make Permanent)”을 선택한다.

자동 마운트된 공유 폴더는 /media/sf_<폴더 이름>에 붙는다. 이 디렉터리는 vboxsf 그룹만 읽을 수 있으므로 사용자를 그룹에 추가하고 다시 로그인한다.

sudo usermod -aG vboxsf $USER
# 다시 로그인한 뒤
id -nG
ls /media/sf_*

Guest Additions 제거

Guest Additions를 제거하거나 다른 버전으로 바꿀 때는 설치 디렉터리의 uninstall.sh를 실행한다.

$ sudo /opt/VBoxGuestAdditions-*/uninstall.sh
Removing installed version 7.2.22 of VirtualBox Guest Additions...
VirtualBox Guest Additions: Updating initramfs
update-initramfs: Generating /boot/initrd.img-6.8.0-149-generic

uninstall.sh는 vboxsf 그룹을 지우지 않는다. 필요 없으면 sudo groupdel vboxsf로 지운다.

문제 해결

증상원인조치
kernel modules and services were not reloaded커널 모듈 빌드 실패/var/log/vboxadd-setup.log에서 error: 줄을 찾는다
로그에 strlcpy 오류Guest Additions가 커널보다 오래됨VirtualBox를 올리거나 최신 Guest Additions ISO를 넣는다
헤더를 찾지 못한다는 메시지linux-headers-$(uname -r) 없음헤더를 설치하고 sudo /sbin/rcvboxadd quicksetup all을 실행한다
커널 업데이트 후 기능이 꺼짐새 커널용 모듈이 없음새 커널의 헤더를 설치하고 sudo /sbin/rcvboxadd quicksetup all을 실행한다
/media/sf_* 접근 거부사용자가 vboxsf 그룹에 없음usermod -aG vboxsf 후 다시 로그인한다
클립보드가 동작하지 않음클립보드 공유가 “사용 안 함”장치 메뉴에서 양방향으로 바꾸고, 안 되면 다시 로그인한다

주의사항

  • 헤더를 설치하기 전에 VBoxLinuxAdditions.run을 실행하지 말 것. 모듈 빌드가 실패한다. 이미 실행했다면 헤더를 설치하고 rcvboxadd quicksetup all로 다시 빌드한다.
  • 설치 출력의 마지막 줄만 보고 성공으로 판단하지 말 것. 일부 모듈 빌드가 실패해도 설치 프로그램은 끝까지 진행한다. lsmod와 modinfo -n으로 확인한다.
  • Ubuntu 저장소의 virtualbox-guest-utils 패키지와 섞어 설치하지 말 것. 두 방식이 같은 모듈과 서비스를 설치하므로 하나만 쓴다.
  • 커널을 업데이트한 뒤에는 기능이 동작하는지 다시 확인할 것. 모듈은 설치 시점의 커널용으로만 빌드된다.

마무리

Guest Additions 설치는 헤더 설치, CD 삽입, VBoxLinuxAdditions.run 실행, 재부팅 순서다. 빌드가 실패하면 먼저 Guest Additions 버전을 확인하고, 커널보다 오래된 버전이면 최신 ISO로 바꾼다.

참고

답글 남기기