---
myst:
  html_meta:
    "description lang=en": "Installing NixOS on a Raspberry Pi"
    "keywords": "Raspberry Pi, rpi, NixOS, installation, image, tutorial"
---


# Raspberry Pi에 NixOS 설치하기

```{contributors}
:authors: domenkozar
:editors: proofconstruction
```

이 튜토리얼은 [4GB RAM을 탑재한 Raspberry Pi 4 Model B](https://www.raspberrypi.org/products/raspberry-pi-4-model-b/)를 가지고 있다고 가정합니다.

이 튜토리얼을 시작하기 전에 [필요한 모든 하드웨어](https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up/1)를 갖추었는지 확인하십시오.

- HDMI 케이블/어댑터.
- 8GB 이상의 SD 카드.
- SD 카드 리더기(사용하는 컴퓨터에 SD 슬롯이 없는 경우).
- Raspberry Pi용 전원 케이블.
- USB 키보드.

:::{note}
이 튜토리얼은 Raspberry Pi 4B를 기준으로 작성되었습니다. 3B나 3B+처럼 이전에 지원되던 모델도 이 튜토리얼을 일부 수정하면 사용할 수 있습니다.
:::

## NixOS 라이브 이미지 부팅하기

:::{note}
USB로 부팅하려면 EEPROM 펌웨어 업그레이드가 필요할 수 있습니다. 이 튜토리얼에서는 이러한 문제를 피하기 위해 SD 카드로 부팅합니다.
:::

Nix가 설치된 다른 기기에서 AArch64 이미지를 준비하려면 다음 명령을 실행하십시오.

```shell-session
$ nix-shell -p wget zstd

[nix-shell:~]$ wget https://hydra.nixos.org/build/226381178/download/1/nixos-sd-image-23.11pre500597.0fbe93c5a7c-aarch64-linux.img.zst
[nix-shell:~]$ unzstd -d nixos-sd-image-23.11pre500597.0fbe93c5a7c-aarch64-linux.img.zst
[nix-shell:~]$ dmesg --follow
```

:::{note}
[Hydra](https://hydra.nixos.org/job/nixos/trunk-combined/nixos.sd_image.aarch64-linux)에서 가장 최근에 성공한 빌드(녹색 체크 표시가 있는 빌드)를 클릭하고 빌드 결과물 이미지의 링크를 복사하여 최신 이미지를 다운로드할 수도 있습니다.
:::

:::{note}
사용 중인 시스템에서 [Etcher](https://www.balena.io/etcher/) 같은 소프트웨어를 사용할 수 있다면 이를 이용해 SD 카드에 이미지를 기록하는 편이 더 편리할 수 있습니다.
:::

터미널에 커널 메시지가 들어오는 대로 출력될 것입니다.

SD 카드를 꽂으면 터미널에 할당된 장치 이름이 출력됩니다(예: `/dev/sdX`).

<kbd>Ctrl</kbd>+<kbd>C</kbd>를 눌러 `dmesg --follow`를 중지하십시오.

다음 명령에서 `sdX`를 사용하는 장치 이름으로 바꾸어 NixOS를 SD 카드에 복사하십시오.

```console
[nix-shell:~]$ sudo dd if=nixos-sd-image-23.11pre500597.0fbe93c5a7c-aarch64-linux.img of=/dev/sdX bs=4096 conv=fsync status=progress
```

명령이 끝나면 **SD 카드를 Raspberry Pi에 옮겨 꽂고 전원을 켜십시오**.

새 셸이 나타날 것입니다.

이미지로 부팅되지 않는다면 [펌웨어를 업데이트](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#bootloader_update_stable)한 뒤 이미지로 다시 부팅해 보십시오.

## 인터넷에 연결하기

`sudo -i`를 실행하여 튜토리얼의 나머지 과정에서 사용할 root 셸을 얻으십시오.

이 단계에서는 인터넷 연결이 필요합니다. 이더넷 케이블을 사용할 수 있다면 케이블을 연결하고 다음 섹션으로 넘어가십시오.

Wi-Fi에 연결하려면 `ip link`를 실행하여 무선 네트워크 인터페이스의 이름을 확인하십시오. `wl`로 시작하는 인터페이스를 찾으십시오(일반적으로 `wlan0`).

`SSID`와 `passphrase`를 사용하는 Wi-Fi 정보로 바꾸고 다음을 실행하십시오.
```shell-session
# wpa_supplicant -B -i wlan0 -c <(wpa_passphrase 'SSID' 'passphrase') &
```

`wpa_supplicant`가 연결을 수립할 때까지 기다리십시오. 그런 다음 인터넷에 접속할 수 있도록 고정 IP 주소를 할당하십시오. `192.168.1.X`를 네트워크에서 사용 가능한 IP 주소로, `192.168.1.1`을 라우터의 게이트웨이 주소로 바꾸십시오:
```shell-session
# ip addr add 192.168.1.X/24 dev wlan0
# ip route add default via 192.168.1.1
```

이제 `dhcpcd`를 다운로드하고 실행하여 올바른 IP 주소를 받을 수 있습니다:
```shell-session
# nix-shell -p dhcpcd
# dhcpcd wlan0
```

몇 초 후, 다음을 실행하여 연결을 확인하십시오:
```shell-session
# host nixos.org
```

DNS 조회가 성공하면 인터넷에 연결된 것이므로 다음 섹션으로 넘어갈 수 있습니다.

오타를 냈다면 `pkill wpa_supplicant`를 실행하고 처음부터 다시 시작하십시오.

## 펌웨어 업데이트

제조사의 업데이트와 버그 수정을 반영하기 위해, 먼저 Raspberry Pi 펌웨어부터 업데이트하겠습니다:

```shell-session
# nix-shell -p raspberrypi-eeprom
# mount /dev/disk/by-label/FIRMWARE /mnt
# BOOTFS=/mnt FIRMWARE_RELEASE_STATUS=stable rpi-eeprom-update -d -a
```

## NixOS 설치 및 설정

이제 자체 설정으로 NixOS를 설치하겠습니다. 여기서는 `guest` 사용자를 만들고 SSH 데몬을 활성화합니다.

아래 `let` 바인딩에서 `SSID` 변수와 `SSIDpassword` 변수의 값을 앞서 사용한 `SSID` 값과 `passphrase` 값으로 바꾸십시오:

```nix
{ config, pkgs, lib, ... }:

let
  user = "guest";
  password = "guest";
  SSID = "mywifi";
  SSIDpassword = "mypassword";
  interface = "wlan0";
  hostname = "myhostname";
in {

  boot = {
    kernelPackages = pkgs.linuxKernel.packages.linux_rpi4;
    initrd.availableKernelModules = [ "xhci_pci" "usbhid" "usb_storage" ];
    loader = {
      grub.enable = false;
      generic-extlinux-compatible.enable = true;
    };
  };

  fileSystems = {
    "/" = {
      device = "/dev/disk/by-label/NIXOS_SD";
      fsType = "ext4";
      options = [ "noatime" ];
    };
  };

  networking = {
    hostName = hostname;
    wireless = {
      enable = true;
      networks."${SSID}".psk = SSIDpassword;
      interfaces = [ interface ];
    };
  };

  environment.systemPackages = with pkgs; [ vim ];

  services.openssh.enable = true;

  users = {
    mutableUsers = false;
    users."${user}" = {
      isNormalUser = true;
      password = password;
      extraGroups = [ "wheel" ];
    };
  };

  hardware.enableRedistributableFirmware = true;
  system.stateVersion = "23.11";
}
```

설정 전체를 직접 입력하는 시간을 줄이려면 설정을 다운로드하십시오:

```shell-session
# curl -L https://tinyurl.com/tutorial-nixos-install-rpi4 > /etc/nixos/configuration.nix
```

:::{note}
NixOS 설정에 작성한 자격 증명은 해당 설정을 빌드할 때 `/nix/store`에 평문으로 저장됩니다.

이를 **원하지 않는다면** 콘솔에서 자격 증명을 입력하거나, 커뮤니티에서 제공하는 암호화된 시크릿 관리 방법 중 하나를 사용할 수 있습니다.
:::

`nixos-sd-image`의 설계 방식 때문에 이 시점에서 NixOS는 사실 *이미 설치되어* 있으므로, 새 설정으로 `nixos-rebuild`만 하면 됩니다:

```shell-session
# nixos-rebuild boot
# reboot
```

시스템이 부팅되지 않으면 부트로더 메뉴에서 가장 오래된 설정을 선택하여 라이브 이미지로 돌아간 뒤 처음부터 다시 시작하십시오.

## 변경하기

부팅에 성공했습니다. 축하합니다.

설정을 추가로 변경하려면 [NixOS 옵션을 검색](https://search.nixos.org/options)하고, `/etc/nixos/configuration.nix`를 편집한 다음, 시스템을 업데이트하십시오:

```shell-session
$ sudo -i
# nixos-rebuild switch
```

## 다음 단계

- OS가 정상적으로 동작하면 `nixos-rebuild switch --upgrade`로 업그레이드하여 더 최신 버전의 패키지를 설치해 보고, 문제가 생기면 이전 설정으로 재부팅하십시오.
- 쾌적한 그래픽 데스크톱 환경을 위해 하드웨어 가속을 활성화하려면 [`nixos-hardware`](https://github.com/nixos/nixos-hardware) 모듈을 설정에 추가하십시오:

  ```nix
  imports = [
    "${fetchTarball "https://github.com/NixOS/nixos-hardware/tarball/master"}/raspberry-pi/4"
  ];
  ```

  `nixos-hardware`에 대한 참조를 고정하는 것을 권장합니다: [](ref-pinning-nixpkgs)

- 하드웨어에 영향을 주는 부트로더 옵션을 조정하려면 [`config.txt` 옵션](https://www.raspberrypi.org/documentation/configuration/config-txt/)을 참고하십시오. `mount /dev/disk/by-label/FIRMWARE /mnt`를 실행하고 `/mnt/config.txt`를 열어 이 옵션들을 변경할 수 있습니다.