path: root/bin/man/post-install.7

.Dd October 1, 2026
.Dt POST-INSTALL 7
.Os
.Sh NAME
.Nm post-install
.Nd from a freshly installed rawnix to a working desktop
.Sh DESCRIPTION
This page picks up where
.Xr installation 7
ends: the system boots, root has a password, and the ports tree is
synced.
What follows is the order that works, and the one place where the order
matters: the graphics driver is chosen before wlroots is built, because
wlroots and everything above it is built against it.
.Pp
Everything here uses
.Xr pkg 8 ,
which resolves dependencies and installs them.
Add
.Fl b
to fetch prebuilt packages instead of building, which is much faster and
needs no compiler:
.Dl # pkg add -b foot
.Sh FIRST STEPS
.Ss A user
root is for administration; log in as a user.
.Bd -literal -offset indent
# useradd -m -G wheel,audio,video,input,plugdev zorz
# passwd zorz
.Ed
.Pp
The groups are the ones a desktop needs:
.Li video
and
.Li input
for the compositor,
.Li audio
for sound,
.Li plugdev
for
.Xr stik 8 ,
and
.Li wheel
for
.Xr doas 1 .
.Ss doas
.Bd -literal -offset indent
# pkg add -b opendoas
# echo 'permit persist :wheel' > /etc/doas.conf
# chmod 640 /etc/doas.conf
.Ed
.Ss The clock and the network
Both are services; see
.Sx SERVICES
below.
.Bd -literal -offset indent
# pkg add -b openntpd dhcpcd
# ln -s /etc/sv/ntpd /service/ntpd
# ln -s /etc/sv/dhcpcd /service/dhcpcd
.Ed
.Pp
A server with a static address configures it in
.Pa /etc/dhcpcd.conf
rather than by hand, so one service owns the interface.
.Ss A firewall
On anything reachable from a network:
.Bd -literal -offset indent
# pkg add -b nftables
# vi /etc/nftables.conf
# ln -s /etc/sv/nftables /service/nftables
.Ed
.Pp
The shipped
.Pa /etc/nftables.conf
drops everything inbound except ssh; open what the machine serves.
With sshd reachable from the internet, add
.Li sshguard .
.Sh GRAPHICS
.Sy Choose the Mesa package before building wlroots.
wlroots, the compositors and everything that draws are built against the
Mesa that is installed, so installing the wrong one means building them
all again.
.Pp
There is one Mesa package per driver, and only one is installed at a
time:
.Bl -tag -width mesa-nouveau
.It Li mesa-amdgpu
AMD, from GCN onwards: Radeon, and the integrated graphics of Ryzen.
.It Li mesa-intel
Intel integrated graphics.
.It Li mesa-nouveau
NVIDIA, with the open driver.
The proprietary driver is not packaged.
.It Li mesa-virtio
A virtual machine: QEMU/KVM with virtio-gpu, and other hypervisors
through the same driver.
.El
.Pp
Which one, if you are not sure:
.Dl $ lspci | grep -i -E 'vga|3d|display'
.Pp
Then, for example:
.Dl # pkg add -b mesa-amdgpu
.Pp
The LLVM target matters here too.
Mesa's AMD driver compiles shaders with LLVM, so llvm has to be built
with
.Li AMDGPU
among its targets; the Intel driver does not, and nouveau uses
.Li NVPTX .
See
.Xr rawnix 7 ,
.Sx Clang and LLVM .
If llvm was built without the target your Mesa needs, rebuild llvm
first, then Mesa.
.Sh KERNEL MODULES
The kernel is monolithic: every driver a machine needs to boot, mount
its disks and reach the network is built in, so nothing has to be loaded
for the system to come up.
Two kinds of driver are the exception and are built as modules, because
which one a machine needs is not known in advance:
.Bl -bullet -compact
.It
wireless, and the firmware that goes with it
.It
graphics
.El
.Pp
These are loaded at boot from
.Pa /etc/rc.modules ,
a shell script run early in
.Pa /etc/runit/1 .
Create it with the modules this machine needs and make it executable:
.Bd -literal -offset indent
#!/bin/sh
modprobe jitterentropy_rng
modprobe iwlmvm
modprobe iwlwifi
modprobe amdgpu
.Ed
.Bd -literal -offset indent
# chmod 755 /etc/rc.modules
.Ed
.Pp
Line by line:
.Bl -tag -width jitterentropy_rng
.It Li jitterentropy_rng
An extra source of entropy for the kernel's random pool, from the timing
jitter of the CPU itself.
Not required, but worth having on a machine with no hardware random
generator, and on a virtual machine, where entropy is scarce early in
the boot.
.It Li iwlmvm , Li iwlwifi
Intel wireless.
Both are needed, and in this order:
.Li iwlwifi
is the driver and
.Li iwlmvm
the operating mode it hands the device to.
Other chips need their own:
.Li ath9k
or
.Li ath11k
for Atheros and Qualcomm,
.Li rtw88_8822be
and the like for Realtek,
.Li mt7921e
for MediaTek.
.It Li amdgpu
Graphics.
Use the one for the card in the machine:
.Li amdgpu
for AMD,
.Li i915
or
.Li xe
for Intel,
.Li nouveau
for NVIDIA,
.Li virtio_gpu
in a virtual machine.
.El
.Pp
What a machine actually has, and what claims it once loaded:
.Bd -literal -offset indent
$ lspci -k | grep -A3 -i -E 'network|vga|3d|display'
$ lsmod
$ dmesg | grep -i -E 'firmware|iwlwifi|amdgpu'
.Ed
.Pp
Wireless also needs its firmware, which is not in the kernel:
.Dl # pkg add -b linux-firmware
Without it the driver loads and the device stays silent, with a line in
.Ic dmesg
about firmware that could not be found.
.Pp
A server needs none of this: no wireless, no graphics.
.Li jitterentropy_rng
alone is still worth the one line.
.Sh A COMPOSITOR
With Mesa in place:
.Bd -literal -offset indent
# pkg add -b seatd
# ln -s /etc/sv/seatd /service/seatd
.Ed
.Pp
.Li seatd
hands the compositor the graphics and input devices, so it needs no
privileges of its own.
Its group is
.Li seatd ;
add the user to it if the compositor refuses to open the display.
.Pp
Then one of the two:
.Bl -tag -width labwc
.It Li sway
Tiling, i3-like, configured in
.Pa ~/.config/sway/config .
.It Li labwc
Stacking, openbox-like, configured in
.Pa ~/.config/labwc/ .
.El
.Pp
Both are wlroots compositors and can be installed side by side; pick one
at login.
.Bd -literal -offset indent
# pkg add -b labwc foot
$ labwc
.Ed
.Pp
.Li foot
is the terminal.
Without one, a compositor starts into an empty screen with no way to
type anything.
.Sh THE REST OF A DESKTOP
None of this is required; it is what most installs end up with.
.Bl -tag -width "wl-clipboard" -compact
.It Li foot
terminal
.It Li wmenu
application launcher
.It Li sfwbar
status bar
.It Li fnott
notifications
.It Li wl-clipboard
clipboard from the shell
.It Li grim , Li slurp
screenshots, with a region selector
.It Li imv
image viewer
.It Li mpv
video and audio
.It Li firefox , Li thunderbird
browser and mail
.It Li font-dejavu , Li font-jetbrains-mono
fonts; without one, everything falls back to something unreadable
.El
.Pp
Sound is
.Li alsa-utils ;
.Ic alsamixer
unmutes what is muted by default.
.Sh SERVICES
A service is enabled by linking it into
.Pa /service ,
and runit starts it within seconds.
.Bd -literal -offset indent
# ln -s /etc/sv/nginx /service/nginx    # enable, starts now
# rm /service/nginx                     # disable, stops now
# sv status /service/*                  # everything
# sv restart nginx                      # one
# sv down nginx ; sv up nginx           # stop, start
.Ed
.Pp
It is
.Pa /service ,
not
.Pa /var/service
and not
.Pa /run/runit/service ;
see
.Xr rawnix 7 .
Logs are under
.Pa /var/log/ Ns Ar service Ns /current ,
written by each service's own
.Pa log/run .
.Pp
A package that ships a service is linked in by
.Xr addpkg 8
at install time, so it is already running when the install finishes.
.Sh KEEPING IT UP TO DATE
.Bd -literal -offset indent
# ports -u                 # fetch the newest recipes
# pkg diff                 # what is older than its port
# pkg sysup -b             # update everything, from prebuilt packages
# revdep                   # anything broken afterwards
.Ed
.Pp
Without
.Fl b
everything is built from source, which needs llvm and the rest of the
development tools.
A server usually wants
.Fl b
and no compiler at all.
.Pp
The kernel is never updated by
.Ic pkg sysup :
it is installed by hand, so that a running machine does not get a new
kernel by surprise.
.Bd -literal -offset indent
# pkg add -b linux-6.12.111
# ls /boot/efi/limine.conf
.Ed
.Pp
Installing a kernel runs
.Ic limine-sync ,
which writes the boot menu from what is in
.Pa /boot .
The previous kernel stays in the menu; keep it until the new one has
booted.
See
.Xr bootloader 7 .
.Pp
.Lk https://audit.rawnix.org/
lists which ports are outdated and which have open CVEs, including the
kernel.
.Sh KEEPING A PORT WHERE IT IS
To stop a package being updated, lock it:
.Bd -literal -offset indent
# pkg lock rust
# pkg locked
.Ed
.Pp
A locked port keeps its own copy of the recipe, so
.Ic ports -u
cannot change it; see
.Xr pkg 8 .
.Sh FILES
.Bl -tag -width Ds -compact
.It Pa /etc/rc.modules
Modules loaded at boot; see
.Sx KERNEL MODULES .
.It Pa /service/
Enabled services, linked from
.Pa /etc/sv/ .
.It Pa /etc/doas.conf
Who may use
.Xr doas 1 .
.El
.Sh SEE ALSO
.Xr doas 1 ,
.Xr bootloader 7 ,
.Xr installation 7 ,
.Xr rawnix 7 ,
.Xr mkpkg 8 ,
.Xr pkg 8 ,
.Xr ports 8 ,
.Xr revdep 8 ,
.Xr stik 8