Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update BSD guide #1242

Merged
merged 3 commits into from
Dec 18, 2024
Merged

Update BSD guide #1242

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8009653
Update bsd.md
ivan-hc Dec 18, 2024
0c50a02
Update bsd.md
ivan-hc Dec 18, 2024
824b71f
Update bsd.md
ivan-hc Dec 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
185 changes: 117 additions & 68 deletions docs/guides-and-tutorials/bsd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,31 +6,56 @@ However, the compatibility of Linux programs on your BSD system must be done man

There are several guides on this subject, the one available on the FreeBSD site is an example https://docs.freebsd.org/en/books/handbook/linuxemu, but I will try to adapt [this one](https://unixdigest.com/tutorials/how-to-install-signal-desktop-on-freebsd-using-the-linux-binary-compatibility.html) as much as possible to the use of Debian in `debootstrap`, which is the most familiar distribution for me.

I will divide this quick guide highlighting the essential steps

------------------------------------------------------------------------
## Getting started
First we need to enable the Linux compatibility layer:
```
# sysrc linux_enable="YES"
```
Once enabled, it can be started without rebooting by executing the following command:
- [1. Enable Linux Compatibility Layout](#1-enable-linux-compatibility-layout)
- [2. Install Debian layout compatibiliti in BSD](#2-install-debian-layout-compatibiliti-in-bsd)
- [3. Configure and mount the Linux compatibility layout on BSD](#3-configure-and-mount-the-linux-compatibility-layout-on-bsd)
- [4. Configure Debian](#4-configure-debian)
- [5. Chroot Debian](#5-chroot-debian)
- [6. Update Debian](#6-update-debian)
- [7. Install needed packages in Debian](#7-install-needed-packages-in-debian)
- [8. Exit the chroot](#8-exit-the-chroot)
- [9. Fix ELF interpreter error](#9-fix-elf-interpreter-error)
- [10. Allow AppImages to use FUSE without root privileges](#10-allow-appimages-to-use-fuse-without-root-privileges)

- [Troubleshooting](#troubleshooting)
- [Chromium-based applications](#chromium-based-applications)
- [Missing libraries](#missing-libraries)

------------------------------------------------------------------------
## 1. Enable Linux Compatibility Layout
First we need to enable the Linux compatibility layer, to do so we need to run these commands **as root**, no reboot needed:
```
# service linux start
sysrc linux_enable="YES"
service linux start
```

------------------------------------------------------------------------
## 2. Install Debian layout compatibiliti in BSD
Then we need to install and use debootstrap, a program that can be used to install different Debian versions in a system without using an installation disk.

As I mentioned at the beginning, I will be using Debian, "Stable" branch

Using the PKG package manager, install "debootstrap"
```
# pkg install debootstrap
pkg install debootstrap
```
Then we need to setup the correct installation path for debootstrap. Use your favorite text editor and insert the following line in /etc/sysctl.conf:
...then we need to setup the correct installation path for debootstrap. Use your favorite text editor and insert the following line in /etc/sysctl.conf
```
compat.linux.emul_path="/compat/debian"
```
Then we use debootstrap to install the Debian base tools for the Debian Bookworm version:
...and finally, we use debootstrap to install the Debian base tools for the Debian Stable, **as root**
```
# debootstrap stable /compat/debian
debootstrap stable /compat/debian
```

------------------------------------------------------------------------
## 3. Configure and mount the Linux compatibility layout on BSD
In order for the contents of the home directory to be shared and in order to be able to run X11 applications, the directories /home and /tmp should be mounted in the Linux compat area using nullfs for loopback.

Edit /etc/fstab and insert the following:
In BSD, edit /etc/fstab and insert the following:
```
# Device Mountpoint FStype Options Dump Pass#
devfs /compat/debian/dev devfs rw,late 0 0
Expand All @@ -41,103 +66,127 @@ linsysfs /compat/debian/sys linsysfs rw,late
/tmp /compat/debian/tmp nullfs rw,late 0 0
/home /compat/debian/home nullfs rw,late 0 0
```
Then execute mount in order to mount everything:
```
# mount -al
```
Now we're ready to use chroot to access the Linux system:
```
# chroot /compat/debian /bin/bash
```
We can use the uname command to verify that we are located in a Linux environment:
Then execute mount in order to mount everything, **as root**:
```
# uname -b
Linux 6.1.119 x86_64
mount -al
```
Exit the chroot environment by typing exit
```
exit
```
...and edit and update the APT repositories located in /compat/debian/etc/apt/sources.list:

------------------------------------------------------------------------
## 4. Configure Debian
Edit and update the APT repositories located in /compat/debian/etc/apt/sources.list
```
deb https://deb.debian.org/debian stable contrib main
deb https://deb.debian.org/debian stable-updates contrib main
deb https://deb.debian.org/debian stable-backports contrib main
deb https://deb.debian.org/debian-security stable-security contrib main
```
I also prefer to disable recommended and suggested packages in /compat/debian/etc/apt/apt.conf:
I also prefer to disable recommended and suggested packages in /compat/debian/etc/apt/apt.conf
```
APT::Install-Recommends "false";
APT::AutoRemove::RecommendsImportant "false";
APT::AutoRemove::SuggestsImportant "false";
```
Then we go back into the chroot environment and update APT:

------------------------------------------------------------------------
## 5. Chroot Debian
Now we're ready to use chroot to access the Linux system. **As root**, do
```
# chroot /compat/debian /bin/bash
# apt update
chroot /compat/debian /bin/bash
```
If you get a lot of packages that need upgrading, you can do that before you continue with:
Now its time to setup Debian.

------------------------------------------------------------------------
## 6. Update Debian
Keep Debian updated via APT
```
# apt full-upgrade
apt update
```
Exit the chroot and run a program you have installed using "AM"/"AppMan" and check the error messages for missing libraries and packages.

If you have any doubts, install those packages that end with "-dev", so you can be sure you have all the libraries needed to run these programs.

To install them, enter the chroot again and install the missing dependencies with APT
If you get a lot of packages that need upgrading, you can do that before you continue with
```
# chroot /compat/debian /bin/bash
# apt install {package}
apt full-upgrade
```
The list of packages to add is still to be found. In the meantime I invite you to read what will be added gradually in the below section "[Troubleshooting](#troubleshooting)", with all the tips to made work the programs for Linux on BSD, including the packages installable via APT.

------------------------------------------------------------------------
## Troubleshooting
This section lists common problems that may arise. "AM" does not guarantee miracles.
## 7. Install needed packages in Debian
AppImages require FUSE to work. For older implementations (which are still the most popular) install with APT `libfuse2` or `libfuse2t64` (depending on the package made available in the repositories), while for all implementations, even the most recent ones, install `fuse3` and later (the latter brings with it `fusermount`).
```
apt install libfuse2 fuse3
```
Since they are written for Linux, they will surely require substantial dependencies. The safest way to get them is to install packages that end with "-dev".

**THIS LIST IS STILL BEING UPDATED!**
For example, "Brave AppImage" requires "`libnss3`", to be sure to use "`libnss3-dev`" instead
```
apt install libnss3-dev
```
...also, "`pulseaudio`" brings with it several core libraries that can be required in different programs
```
apt install pulseaudio
```
...not to mention that many programs, including the official versions of Firefox and Thunderbird, require some GTK3 or earlier libraries
```
apt install libgtk-3-dev libgtk2.0-dev
```
...I also suggest Xorg
```
apt install xorg
```
...if you want to use special fonts, you need to get at least the basic ones
```
apt install fonts-freefont-ttf
```
Is it too much? I know.

------------------------------------------------------------------------
- [Chromium-based applications](#chromium-based-applications)
- [ELF interpreter error](#elf-interpreter-error)
- [FUSE](#fuse)
- [GTK3](#gtk3)
The reason for this is that different programs require different libraries on the host, which are almost always present on Linux. This list will continue to be updated until we discover more common packages that may be needed to run the portable Linux programs managed by "AM" and "AppMan".

------------------------------------------------------------------------
### Chromium-based applications
Run Chromium-based apps with the `--no-sandbox` flag, for example
## 8. Exit the chroot
To exit the chroot and return to the main BSD shell, you can use the "`exit`" command
```
$ brave --no-sandbox
exit
```

------------------------------------------------------------------------
### ELF interpreter error
If you get the error:
## 9. Fix ELF interpreter error
To prevent errors like this one...
```
ELF interpreter /lib64/ld-linux-x86-64.so.2 not found, error 2
```
Then fix this by doing the following as root outside the chroot:
...do
```
# cd /compat/debian/lib64/
# rm ./ld-linux-x86-64.so.2
# ln -s ../lib/x86_64-linux-gnu/ld-linux-x86-64.so.2 ld-linux-x86-64.so.2
cd /compat/debian/lib64/
rm ./ld-linux-x86-64.so.2
ln -s ../lib/x86_64-linux-gnu/ld-linux-x86-64.so.2 ld-linux-x86-64.so.2
```
Then run again the program installed with "AM"/"AppMan" as the regular user.
This change requires a reboot (as does the next point, which is the most important one for AppImages, so... wait and keep read).

If the problem with ld-linux-x86-64.so.2 persists, then reboot FreeBSD before you continue.
------------------------------------------------------------------------
## 10. Allow AppImages to use FUSE without root privileges
Edit the file /etc/sysctl.conf by adding this line
```
vfs.usermount=1
```
This change requires a reboot.

------------------------------------------------------------------------
### FUSE
AppImages require FUSE to work.
## Troubleshooting
This section lists common problems that may arise. "AM" does not guarantee miracles.

For older implementations (which are still the most popular) install with APT `libfuse2` or `libfuse2t64` (depending on the package made available in the repositories), while for all implementations, even the most recent ones, install `fuse3` and later (the latter brings with it `fusermount`).
### Chromium-based applications
Run Chromium-based apps with the `--no-sandbox` flag, for example
```
# apt install libfuse2 fuse3
$ brave --no-sandbox
```

------------------------------------------------------------------------
### GTK3
Some programs, even those not in AppImage format, such as Firefox and Thunderbird, require the GTK3 libraries to run. Install the `libgtk-3-dev` package via APT.
### Missing libraries
Always check the terminal output, also using `LD_DEBUG=lib` if necessary, to see which libraries a program requires to run.

Search for such libraries in APT, also with `apt search {keyword}` or by searching on the internet, to locate the package to install.

Remember to always chroot to install packages via APT
```
chroot /compat/debian /bin/bash
apt install {package}
```

------------------------------------------------------------------------

Expand Down