Post-Install Setup

First boot is done and you are logged in. This page turns the fresh install into a daily-usable system: users/hostname, network, updates, writable data, shell basics, and backups. What to do after forinstall reports INSTALL OK and you have booted from the internal disk: log in, verify the install, set up users, bring up the network, and install updates.

Assumes you installed with forinstall and booted from the target disk (no install media attached). Run as root unless noted (su / sudo). Run these steps on the installed system, not the live USB.

Contents

1. First login and smoke test
2. Users & hostname
3. Network
4. Date and time
5. Package updates (pac + forupdate)
6. Writable-data setup
7. Shell basics
8. Backups
9. Issues and fixes

1. First login and smoke test

Log in as the user created during forinstall (or root), then confirm the root filesystem is the installed disk:

uname -a
df -hT          # root mounted, space free
ls /bin | head
mount
ls /

Expected: /dev/hd0p1 on / type ext2 (rw) (device name varies), /bin populated, df -hT shows free space. If /bin is empty or the root entry is missing, you booted the USB again — remove it and boot the internal disk. Snapshot now (QEMU savevm, VirtualBox/VMware snapshot) before making changes.

2. Users & hostname

The installer writes /etc/hostname, /etc/passwd, and /etc/shadow (default hostname forest). Change them live with hostname and passwd. Users/groups come from /etc/passwd, /etc/group, /etc/shadow; see Initrd Builder. Set hostname and check privileges before putting the machine on a network.

# who / what you are
hostname            # show current hostname
hostname -f         # fully qualified name
hostname -i         # IP addresses for this host
id                  # show uid/gid/groups for current user
cat /etc/passwd     # user database
cat /etc/hostname   # persistent hostname

# rename this machine (live + persistent)
hostname mybox
echo mybox > /etc/hostname
cat /etc/hostname

# set / change passwords (root first, then each user)
passwd              # change current user's password
passwd alice        # change alice's password (root only)

id                      # confirm uid/gid
hostname forest-node-01 # name this machine
su -                    # switch identity / test login shell
sudo -l                 # check privilege entries

# More identity and privilege checks:
hostname                # print hostname
id -un                  # print just the user name
sudo -v                 # validate credentials
su -c "ls /home/otheruser" otheruser  # run a command as another user
sudo -u postgres psql   # run a command as a different user

sudo caches credentials for 600 seconds and logs to /var/log/sudo.log (rules in /etc/sudoers). su authenticates against /etc/shadow.

Notes:

• hostname NAME takes effect immediately but is lost on reboot unless you also write /etc/hostname.
• On a live ISO / initrd root, /etc/passwd and /etc/shadow are RAM-only. Keep a copy on your data partition and restore it at startup (see writable-data setup), or use a full install where /etc is on disk.
• Verify after reboot: hostname; cat /etc/hostname; cat /etc/passwd.

3. Network

Bring an interface up (DHCP by default via rcS), inspect it, or fall back to a static address. DNS lives in /etc/resolv.conf.

# link + address state
ip addr                       # show all interfaces/addresses
ip link show                  # link state only
ip link set e1000 up          # bring NIC up
ip addr add 10.0.2.15/24 dev e1000
ip route show                 # routing table
ip route add default via 10.0.2.2 dev e1000
ping -c 4 10.0.2.2            # gateway / peer reachability
ping -c 4 127.0.0.1           # loopback sanity check
ethtool e1000                 # speed/duplex/link-detected
ethtool -i e1000              # driver name + version

# DNS
cat /etc/resolv.conf          # current resolvers
echo "nameserver 8.8.8.8" > /etc/resolv.conf
echo "nameserver 1.1.1.1" >> /etc/resolv.conf

DHCP (default, automatic at boot): rcS already runs DHCP. To re-run / confirm: ip addr (expect an address on e1000), ip route show (expect a default route), cat /etc/resolv.conf (expect a nameserver line).

# Static (use when there is no DHCP server):
ip addr add 192.168.1.10/24 dev e1000
ip link set e1000 up
ip route add default via 192.168.1.1 dev e1000
echo "nameserver 192.168.1.1" > /etc/resolv.conf
ip addr
ip route show
ping -c 4 192.168.1.1

Real-hardware NICs vary widely; if no interface appears, that is a missing driver, not a cable problem. See Networking. Recognized drivers: e1000 (Intel Gigabit, recommended for QEMU -net nic,model=e1000), RTL8139, NE2000, virtio-net (AArch64/RISC-V QEMU virt). Use ip link or ifconfig to see what was detected.

# Same setup with the traditional tools:
ifconfig                      # BSD-style summary of all interfaces
ifconfig e1000 10.0.2.15 netmask 255.255.255.0 up
ip route                      # show routes
route -n                      # traditional view

# DNS (userspace tools speak DNS wire format directly over UDP port 53):
dig @8.8.8.8 example.com
nslookup example.com
host example.com

There is no userspace DHCP client command — DHCP runs in the kernel at init only. For a fixed address, set it statically as above. pac speaks plain HTTP to the servers in /etc/pacservers, so it needs a working route (or a local mirror). Do not update over an untrusted network — no TLS in the client.

4. Date and time

date
date --iso-8601=seconds
date -s "2026-08-07 12:00:00"

Setting the clock requires root (settimeofday()). Use -u for UTC, -R for RFC 2822 output.

5. Package updates (pac + forupdate)

Two layers: pac for packages, forupdate for full system updates. Back up before either one.

pac list
pac update              # update everything installed
pac update <pkg>        # update one package
pac history             # audit what changed

pac search editor
pac info cool-tool
pac install cool-tool
pac list
pac update                 # update everything installed
pac update cool-tool       # update just one package
pac uninstall cool-tool
pac downgrade cool-tool 1.0.0     # install a specific older version
pac history                       # full change log
pac history cool-tool             # just this package's changes

Server list lives in /etc/pacservers — one hostname per line, first line is the default (pac.forestoperatingsystem.dev is always included). Local bookkeeping is under /var/pac (installed.db: name,version per line; history.db: timestamp,action,name,version per line).

# packages (pac) — full reference
pac list                      # what is installed
pac search editor             # find a package
pac info cool-tool            # package details
pac install cool-tool         # install one package
pac update                    # update everything installed
pac update cool-tool          # update just one package
pac history                   # full local change log (/var/pac/history.db)
pac history cool-tool         # this package's changes
pac downgrade cool-tool 1.0.0 # roll one package back
cat /var/pac/installed.db     # installed name,version ledger
cat /etc/pacservers           # server list (first line = default)

# system update (forupdate, run as root)
sudo forupdate                # guided: detect install -> manifest -> backup -> apply
cat /etc/forest-version       # current system version
ls /boot/backup/              # per-version backups

6. System updates with forupdate (offline)

forupdate is the interactive offline updater — no USB stick, disc, or network needed, as long as an update source is present at /media/forest-update/manifest.txt or a manifest was pre-staged at /tmp/forupdate-manifest.txt. Must run as root.

sudo forupdate

forupdate flow:

1. Must run as root (sudo forupdate).
2. Detects the install (/boot/forest-kernel, /boot/forest-initrd).
3. Loads the manifest from /media/forest-update/manifest.txt (update media) or /tmp/forupdate-manifest.txt (downloaded).
4. Backs up first to /boot/backup/v<version>/ (kernel, initrd, /etc/forest-version, /etc/forest-hostname, /etc/forest-network).
5. Applies the manifest, verifies, reports errors.

# pre-update backup check (do this before pac update / forupdate)
cat /etc/forest-version
ls /boot/backup/
df -hT                         # confirm /boot has room for another v<version>/ dir

# Rollback is manual and offline (no restore menu yet):
ls /boot/backup/              # e.g. v0.1.0  v0.1.1
cp /boot/backup/v0.1.0/forest-kernel /boot/forest-kernel
cp /boot/backup/v0.1.0/forest-initrd /boot/forest-initrd
cp /boot/backup/v0.1.0/forest-version /etc/forest-version
sync
reboot

Only the kernel copy is fatal during backup; initrd/config copies are best-effort. The newest 3 backups are kept. If the new system is broken, restore as above and reboot. Details: System Tools · Installer.

If an update breaks boot, copy the kernel/initrd back from the newest /boot/backup/v<version>/ directory. See Package Management (if present) and Updates.

7. Writable-data setup

Know this rule or lose data: the kernel ext2 driver is read-only and FAT12/16/32 is the only production read/write disk filesystem. An ext2 root boots fine but cannot save — configs, password changes, and pac installs outside a writable mount vanish on reboot. The fix: a FAT DATA partition mounted at /home or /data, wired in via fstab, plus a copy-to-writable workflow for anything on a read-only root.

# 1. Find the data partition and check it
lsblk
blkid
fdisk -l /dev/sda
fsck -n /dev/sda2

# 2. Create it if missing (example: second partition, FAT32)
mkfs -t fat32 -L FOREST-DATA /dev/sda2
blkid /dev/sda2

# 3. Mount it where daily data lives
mkdir -p /home /data
mount -t vfat /dev/sda2 /data
mount --bind /data/home /home     # or: mount -t vfat /dev/sda2 /home
df -hT                            # confirm /home or /data is vfat, not tmpfs
mount                             # list mounted filesystems

# 4. Copy-to-writable workflow (read-only root -> FAT store)
cp /etc/hostname /data/etc-hostname.bak
cp /etc/passwd /data/passwd.bak
cp /etc/resolv.conf /data/resolv.conf.bak
cp -r ~/notes /data/              # your files -> persistent store

# 5. Make it survive reboot: fstab entry
cat /etc/fstab

fstab fragment (adjust /dev/sda2 to your blkid result; prefer LABEL=/UUID= if your setup supports it so device renumbering does not break the mount):

# <device>   <mount>  <type>  <options>        <dump> <pass>
/dev/sda2    /data    vfat    defaults,noatime   0      2
proc         /proc    proc    defaults           0      0
sysfs        /sys     sysfs   defaults           0      0
tmpfs        /tmp     tmpfs   defaults           0      0

mount -a                          # apply fstab
df -hT                            # /data must show vfat on /dev/sda2
echo ok > /data/hello.txt && reboot
# after reboot:
cat /data/hello.txt               # still there = persistence works

Notes:

• On live/persistent boots /etc/fstab itself is RAM — keep the master copy on the data partition and restore it from rcS, or the wiring vanishes with the reboot you were trying to survive.
• There is no copy-up engine: only paths under the FAT mount persist. /tmp (tmpfs) and /proc /sys /dev (virtual) never persist by design.
• See Choosing a Filesystem and USB Persistence for the full FAT-vs-ext2 rationale and persistent-USB layouts.

8. Shell basics

forest-shell is the interactive shell. These are the daily commands for looking around and managing mounts.

# shell + navigation
echo $SHELL
pwd                               # where am I
ls                                # list here
ls -l /home                       # long listing
cat /etc/hostname                 # print a file
cat /etc/fstab                    # print mount table
cat /etc/resolv.conf              # print DNS config

# storage + mounts
df -hT                            # disk free, with fstype
du -sh /home                      # how much /home uses
mount                             # what is mounted where
mount -a                          # mount everything in /etc/fstab
umount /data                      # detach cleanly before pulling media

# processes + power
ps                                # running processes
uname -a                          # kernel / arch
shutdown                          # clean power-off (flushes FAT/ext2)
reboot                            # clean reboot

See Shell, Core Utilities, and Disk Tools.

9. Backups

FAT has no journal and flash wears — back up /home (and /data) to USB regularly with tar, and always unmount cleanly.

# 1. Plug in a backup USB, find it, mount it somewhere aside
lsblk
blkid
mkdir -p /mnt/usb
mount -t vfat /dev/sdb1 /mnt/usb
df -hT

# 2. Archive /home (and /data) to the stick
tar -cvf /mnt/usb/forest-home-$(date +%F).tar /home
tar -cvf /mnt/usb/forest-data-$(date +%F).tar /data

# 3. Verify, then detach cleanly
tar -tvf /mnt/usb/forest-home-$(date +%F).tar | head
ls -lh /mnt/usb/
umount /mnt/usb

# 4. Restore (when needed)
mount -t vfat /dev/sdb1 /mnt/usb
tar -xvf /mnt/usb/forest-home-<date>.tar -C /
umount /mnt/usb

What to back up, and when:

Also see Backup (pre-install backups) and Updates (system-update policy).

10. Issues and fixes

Still stuck? See Troubleshooting and FAQ.

Further reading

• First Boot — login and first checks (do this first)
• Updates — update policy and rollback
• Backup — pre-install data protection
• Choosing a Filesystem — FAT vs ext2, fstab
• Installation Overview — install methods at a glance
• Quick-Start — fastest path to an installed system
• Install on a VM — QEMU / VirtualBox / VMware via forinstall
• Install on Real Hardware — bare-metal USB install
• USB Persistence — live vs persistent vs full USB install
• Installer — forinstall + forupdate reference
• System Tools — hostname, id, sudo, date, forupdate
• Networking — stack, drivers, ip / ifconfig
• BIOS Boot — stage layout, sector map, error catalog
• UEFI Boot — ESP layout, forebo.cfg, chainloading

← Back to Wiki