Redclaw Linux

Guide for D-branch x86_64

It is recommended to read this guide after booting into Redclaw.

--- Console Fonts

The system console font is defined with the FONT variable in /etc/vconsole.conf. Fonts can be found in /usr/share/consolefonts with the .psf.gz and the .psfu.gz for fonts.

The default font is Lat2-Terminus16, and it is recommended to keep it for its wide compatibility with many locales and keymaps. If you want a legacy font, swap the font in the FONT variable to a console font of your choice.

You can also run localectl set-font <font> to change the font.

Reboot the system to make changes go into effect.

--- Disk Preparation

To manually set up a mass storage device to load Redclaw on, multiple tasks must happen.

Depending on the type of drive, /dev will report devices with the following common notations:

• Numbered drives (p# for partitions): nvme#p# for NVMe drives, mmcblk#p# for SD-based and other eMMC-based drives (for Raspberry Pi, the single microSD reader)
• Lettered drives (* for drives, # for partitions): hd*# for HDDs, sd*# for SSDs and USB-based devices like flash drives and adapters

Please note that device designations may change after rebooting depending on where the drives are connected to when detected by the kernel.

The default drive layout for Redclaw consists of the following:

• GUID Partition Table (GPT)
• FAT32 at /boot/firmware with 512 MiB; partiton type of Microsoft basic data; contains contents of bootfs/ in the tarball
• EXT4 at / with the remaining space; partition type of Linux filesystem; contains contents of rootfs/ in the tarball

It is recommended to stay with EXT4, but you could use other supported filesystems like BTRFS, JFS, XFS, FAT, and NTFS.

Use fdisk to set up your chosen device. Make sure you use the right drive, or you may end up losing data and/or your current system.

Next, use mkfs to format each partition, making sure to use the right filesystem on the right partition.

Depending on what Linux distribution you use, the drives may automount when reinserted. If not, run mount /dev/<device> /<valid directory> to mount the partitions manually.

--- Keymaps

The system keymap is defined with the KEYMAP variable in /etc/vconsole.conf. Keymaps can be found in /usr/share/keymaps with the .map.gz extension, with commonly used ones in the i386 directory.

The default keymap is us. To change it, swap the keymap in the KEYMAP variable in the file with the keymap of your choice, leaving out the file extension.

You can also run localectl set-keymap <keymap> to change the keymap, following the same format.

Run "loadkeys <keymap>" or reboot the system to make changes go into effect.

--- Locales

The system locale is defined with the LANG variable in /etc/locale.conf, while user locales can be defined in .profile and .bash_profile depending on the shell used. Locales can be found in /usr/share/i18n/locales. The format for a locale is <language>_<COUNTRY>.<ENCODING>@<modifier>, with @<modifier> being optional as they are not commonly used.

Unicode-based locales are most commonly used as they are widely supported in most programs and on most websites. Legacy locales are available, like ISO-based ones, but it is recommended to use locales with UTF-8.

To view every available locale on the system, run "locale -a".

The default locale for Redclaw is en_US.UTF-8. To change it, swap the locale in the LANG variable in the mentioned files with the locale of your choice.

You can also run localectl set-locale LANG="<locale>" to set the locale, following the same format.

Reboot the system to make changes go into the effect.

--- Networking

Run "ip link" to view available network interfaces for the system. The wireless interface is usually named wlp#s# or wlo#, and the wired interface (Ethernet) is usually named end# or eth#. Ignore the loopback interface "lo" and any SIT interfaces "sit#".

To bring up an interface, run "ip link set <interface> up".

For wired interfaces, just connect an Ethernet cable to your machine and an active switch/router. systemd-networkd will take care of the rest.

For wireless interfaces:

• Retrieve your wireless network's SSID and password. You can scan for local networks after bringing up the wireless interface by running "iw <interface> scan | grep 'SSID: ' | sort -u". Running iw by itself will output every piece of information about every network it finds, so piping the output through grep clears things up. Piping the output through sort -u will sort the list and remove any duplicates, since some networks run on different signal bands (2.4 GHz and 5 GHz).
• Run "wpa_passphrase <SSID> <password> > /etc/wpa_supplicant/wpa_supplicant-<interface>.conf" to create the configuration file.
• If connecting to an open network, run the same command, then replace the psk lines with key_mgmt=NONE.
• If connecting to a hidden network, add scan_ssid=1 inside the network block.
• Enable the Systemd unit by running "systemctl enable wpa_supplicant@<interface>", and start the unit by replacing "enable" with "start"

Network interfaces have Systemd network units in /etc/systemd/network. These are read by systemd-networkd and systemd-resolved to manage the interfaces.

The first-boot.sh script included in the archive is supposed to set up one network interface, but for the time being, the script is not included in the installation process until it gets tested and released.

However, the installation provides one example unit file at /etc/systemd/network/00-interface.network.NOUSE. Remove .NOUSE from the name, change the numbers at the beginning, and change the value of Name to a valid network interface.

DHCP is used by default for automatic IP address assignment, managed by systemd-networkd. For a static configuration, make the following edits to the network unit file:

• Remove the [DHCPv4] section and everything under it.
• Remove the DHCP line in the [Network] section, but do not remove the section itself.
• Create the Address line in the [Network] section, using the manually assigned IP from your router configuration. For example: 192.168.1.2.
• Append the subnet mask in CIDR notation to the Address line. For example: Mask of 255.255.255.0 becomes /24 in CIDR, meaning the value of Address becomes: 192.160.1.2/24.
• Create the Gateway line in the [Network] section, using the IP address of the router, commonly 192.168.1.1.

systemd-resolved is the DNS resolver, which normally makes a file at /etc/systemd/resolve/stub-resolv.conf, making a symlink to /etc/resolv.conf if it does not exist.

Since we have /etc/resolv.conf included in the installation, systemd-resolved reads that file. /etc/resolv.conf contains the machine's domain name and nameserver entries of DNS servers as IPv4 addresses. These would normally be added to the network unit files, but having DNS server entries here centralizes it across multiple network interfaces.

This /etc/resolv.conf file does not include the domain entry, so add it before the nameserver entries. The file also include four nameserver entries, two Google Public DNS servers and two OpenDNS DNS servers. You can add or remove nameserver entries as you wish.

Run "systemctl restart systemd-networkd" and "systemctl restart systemd-resolved" to make changes go into effect.

Run "ping <web address> to test the connection. "ip link" shows the state of the interfaces, and "ip addr" shows each interfaces' assigned IP address.

Setting up networking helps with synchronizing the system clock, run by systemd-timesyncd.

--- Resetting Passwords

If at any time you lose the password to your local account, and you have another system handy, boot up the other system and mount the Redclaw drive.

Run the following commands to mount the following virtual filesystems. Let $LFS represent the path to your Redclaw drive:

• mount -v --bind /dev $LFS/dev
• mount -vt devpts devpts -o gid=5,mode=0620 $LFS/dev/pts
• mount -vt tmpfs tmpfs -o nosuid,nodev $LFS/dev/shm
• mount -vt proc proc $LFS/proc
• mount -vt sysfs sysfs $LFS/sys
• mount -vt tmpfs tmpfs $LFS/run

Use "chroot $LFS" to enter the Redclaw system, then use "passwd <user>" to change the user's password, or use "passwd -d <user>" to remove the user's password. Please note that once Linux-PAM is installed, every account will need a password to log in with.

Exit the chroot environment and use "umount -v $LFS/{dev/{pts,shm,},proc,sys,run,}" to unmount the virtual filesystems and the Redclaw drive.

--- Time and Timezones

systemd-timesyncd synchronizes the system clock with Internet NTP servers.

To set it manually, run either of the following commands: "hwclock -l --set --date 'YYYY-MM-DD HH:MM:SS'" or "timedatectl set-time 'YYYY-MM-DD HH:MM:SS'". This will set the system clock based on the inputted time matching the format.

The timezone is set a symlink at /etc/localtime, using a timezone file in /usr/share/zoneinfo. To change it, we will use the tzselect script included in Glibc. For script integration, the script prints out the last line of output, and we capture it with tail -1."

Run either of the following commands: "ln -sfv /usr/share/zoneinfo/$(tzselect | tail -1) /etc/localtime" or "timedatectl set-timezone $(tzselext | tail -1)" to change the timezone. Make sure to restart your machine to make changes go into effect.

Guide for V-branch rpi5-arm64

It is recommended to read this guide after booting into Redclaw.

--- Console Fonts

The system console font is defined with the FONT variable in /etc/sysconfig/console. Fonts can be found in /usr/share/consolefonts with the .psfu.gz for Unicode fonts, and the .psf.gz for legacy fonts.

The default font is Lat2-Terminus16, and it is recommended to keep it for its wide compatibility with many locales and keymaps. If you want a legacy font, change the UNICODE variable to 0 and swap the font in the FONT variable to a console font of your choice.

Reboot the system to make changes go into effect.

--- Disk Preparation

To manually set up a mass storage device to load Redclaw on, multiple tasks must happen.

Depending on the type of drive, /dev will report devices with the following common notations:

• Numbered drives (p# for partitions): nvme#p# for NVMe drives, mmcblk#p# for SD-based and other eMMC-based drives (for Raspberry Pi, the single microSD reader)
• Lettered drives (* for drives, # for partitions): hd*# for HDDs, sd*# for SSDs and USB-based devices like flash drives and adapters

Please note that device designations may change after rebooting depending on where the drives are connected to when detected by the kernel.

The default drive layout for Redclaw consists of the following:

• GUID Partition Table (GPT)
• FAT32 at /boot/firmware with 512 MiB; partiton type of Microsoft basic data; contains contents of bootfs/ in the tarball
• EXT4 at / with the remaining space; partition type of Linux filesystem; contains contents of rootfs/ in the tarball

It is recommended to stay with EXT4, but you could use other supported filesystems like BTRFS, JFS, XFS, FAT, and NTFS.

Use fdisk to set up your chosen device. Make sure you use the right drive, or you may end up losing data and/or your current system.

Next, use mkfs to format each partition, making sure to use the right filesystem on the right partition.

If using Raspberry Pi OS/Raspbian, the drives should automount when reinserted. If not, use mount /dev/<device> /<valid directory> to mount the partitions manually.

Then, copy over the files from rootfs/ and bootfs/ into the right partitions.

If not using the microSD reader on the Pi, change the device paths in /etc/fstab and /boot/firmware/cmdline.txt on the mounted partitions to ensure the bootloader and the kernel find the correct devices to read and mount on boot.

Safely eject and remove each storage device, and reboot with the Redclaw drive inserted. The bootloader will search for the first drive it finds, the microSD card reader first, then USB drives.

--- Keymaps

The system keymap is defined with the KEYMAP variable in /etc/sysconfig/console. Keymaps can be found in /usr/share/keymaps with the .map.gz extension, with commonly used ones in the i386 directory.

The default keymap is us. To change it, swap the keymap in the KEYMAP variable in the file with the keymap of your choice, leaving out the file extension.

Use "loadkeys <keymap>" or reboot the system to make changes go into effect.

--- Locales

The system locale is defined with the LANG variable in /etc/profile.d/i18n.sh, while user locales can be defined in .profile and .bash_profile depending on the shell used. Locales can be found in /usr/share/i18n/locales. The format for a locale is <language>_<COUNTRY>.<ENCODING>@<modifier>, with @<modifier> being optional as they are not commonly used.

Unicode-based locales are most commonly used as they are widely supported in most programs and on most websites. Legacy locales are available, like ISO-based ones, but it is recommended to use locales with UTF-8.

To view every available locale on the system, run "locale -a".

The default locale for Redclaw is en_US.UTF-8. To change it, swap the locale in the LANG variable in the mentioned files with the locale of your choice. Leave any entries with C.UTF-8 alone.

If you chose a non-Unicode locale, change the UNICODE variable in /etc/sysconfig/console to 0. Otherwise, leave it at 1.

Reboot the system to make changes go into the effect.

--- Networking

Use "ip link" to view available network interfaces for the system. The wireless interface is named wlan0, and the wired interface (Ethernet) is named end0 or eth0. Ignore the loopback interface named lo.

The Ethernet and wireless interfaces have ifconfig configuration files in /etc/sysconfig. These are read by ifup and ifdown to manage the interfaces. You may need to rename the configuration file for Ethernet depending on the interface name given by the kernel.

To bring up the Ethernet interface, make sure an Ethernet cable is connected to the Pi and an active switch/router, then use "ifup <interface>".

To bring up the wireless interface, be sure you know your wireless network's SSID and password. Use "wpa_passphrase <SSID> <password> > /etc/sysconfig/wpa_supplicant-wlan0.conf" to create the configuration file. If connecting to an unsecure network, run the same command, then replace the psk lines with key_mgmt=NONE. Then, use "ifup wlan0".

DHCP is used by default for automatic IP address assignment. For a static setup, edit the interface configuration files as below, the run the above commands for the interfaces:

• Replace dhcpcd with ipv4-static and remove every DHCP_* line.
• Create the IP line for the IP address given to the Pi.
• Create the GATEWAY line for the IP address of the gateway router.
• Create the PREFIX line for the number of masked bits in the subnet mask.
• Create the BROADCAST line for the broadcast IP address, usually with the last octet as 255.

Use "ping <web address> to test the connection. Using "ifconfig" will show active interfaces, and if the number of RX and TX bytes keep increasing with each iteration, then they are working properly.

Setting up networking helps with synchronizing the system clock.

--- Resetting Passwords

If at any time you lose the password to your local account, and you have another system handy, boot up the other system and mount the Redclaw drive.

Use the following commands to mount the following virtual filesystems. Let $LFS represent the path to your Redclaw drive:

• mount -v --bind /dev $LFS/dev
• mount -vt devpts devpts -o gid=5,mode=0620 $LFS/dev/pts
• mount -vt tmpfs tmpfs -o nosuid,nodev $LFS/dev/shm
• mount -vt proc proc $LFS/proc
• mount -vt sysfs sysfs $LFS/sys
• mount -vt tmpfs tmpfs $LFS/run

Use "chroot $LFS" to enter the Redclaw system, then use "passwd <user>" to change the user's password.

Exit the chroot environment and use "umount -v $LFS/{dev/{pts,shm,},proc,sys,run,}" to unmount the virtual filesystems and the Redclaw drive.

--- Time and Timezones

Unless the RTC battery is installed, the Raspberry Pi has no way to keep track of time while powered off. PiLFS provides a fake hardware clock script that mitigates this issue, but the data must be set first.

Synchronizing the system clock with NTP is the easiest way to do, assuming networking has been set up properly.

To do it manually, run the following commands: "hwclock -l --set --date 'YYYY-MM-DD HH:MM:SS'" and "hwclock -w". This will set the clock based on the inputted time matching the format, and save it to the RTC.

Before powering off, the fake clock script will save data to a file, and set an approximate time the next time Redclaw is booted again. NTP synchronization will take over anyways, if networking works.

The timezone is set a symlink at /etc/localtime, using a timezone file in /usr/share/zoneinfo. To change it, we will use the tzselect script included in Glibc. For script integration, the script prints out the last line of output, and we capture it with tail -1."

Run the following command: "ln -sfv /usr/share/zoneinfo/$(tzselect | tail -1) /etc/localtime" to change the timezone. Make sure to restart your machine to make changes go into effect.