Using esOS

First steps

When esOS has started you are logged in as root on tty1. There is no password: esOS keeps nothing between boots, so there is no account to protect, and anyone at the keyboard already controls the machine. The welcome screen lists the commands you need first.

esOS:~# keyboard_setup
esOS:~# esx --help

Files you create are readable only by their owner (umask 077), and the shell keeps no command history, so passwords typed on a command line are not stored.

Keyboard layout

esOS starts with the US layout. keyboard_setup opens a menu with nine layouts and an automatic detection mode.

esOS:~# keyboard_setup            # menu: 0 = detect, 1-9 = layout, Esc = quit
esOS:~# keyboard_setup --detect   # detect directly
esOS:~# keyboard_setup trq       # apply Turkish Q without asking
esOS:~# keyboard_setup --list

Detection shows one character at a time; press the key that has that character printed on it, or Esc if your keyboard does not have it. Most layouts are identified in one to three questions. You then type a test line and confirm with Y; if you answer N the previous layout comes back.

Encrypting files with esx

Encryption Studio X encrypts a file with a password or with an RSA public key, and decrypts it with the same password or the matching private key.

# password
esOS:~# esx encrypt -i report.pdf -o report.pdf.enc -p 'correct horse battery staple'
esOS:~# esx decrypt -i report.pdf.enc -o report.pdf -p 'correct horse battery staple'

# RSA key pair (writes public.pem and private.pem)
esOS:~# esx keygen -s 4096 -o /mnt/keys
esOS:~# esx encrypt -i report.pdf -o report.pdf.enc -k /mnt/keys/public.pem
esOS:~# esx decrypt -i report.pdf.enc -o report.pdf -k /mnt/keys/private.pem

keygen never overwrites existing keys, and the private key is created readable by its owner only. Keep private.pem on separate storage from the files it protects.

To check that the esx program on your stick is the one that was released: sha256sum -c /etc/esos/apps.sha256

USB sticks and disks

Storage is never mounted automatically. List the devices, mount the one you need, and unmount it before you remove it.

esOS:~# lsblk -o NAME,SIZE,FSTYPE,LABEL
esOS:~# mount /dev/sdb1 /mnt
esOS:~# ls /mnt
esOS:~# umount /mnt

Supported file systems: ext4, FAT, exFAT, NTFS, ISO 9660, Btrfs and XFS. A USB stick needs about a second to appear after it is plugged in. Mount points /mnt and /media are available.

Encrypted containers (LUKS2)

For a whole set of files, a LUKS2 container is often more practical than encrypting files one by one. A container is a single file that holds an encrypted file system.

# create a 512 MB container on a mounted stick
esOS:~# dd if=/dev/zero of=/mnt/vault.img bs=1M count=512
esOS:~# loop=$(losetup -f --show /mnt/vault.img)
esOS:~# cryptsetup luksFormat --type luks2 "$loop"
esOS:~# cryptsetup open "$loop" vault
esOS:~# mkfs.ext4 /dev/mapper/vault
esOS:~# mkdir -p /media/vault && mount /dev/mapper/vault /media/vault

# close it
esOS:~# umount /media/vault && cryptsetup close vault && losetup -d "$loop"

LUKS2 derives its key with Argon2, which uses up to 1 GB of memory by default. On computers with little memory the format and open steps take longer; keep the defaults if you can.

Hardware report

hwreport prints one screen with the machine model, firmware type, Secure Boot state, processor features (including the x86-64-v3 check), memory, display, storage, and the security state of the running kernel.

Shutting down

esOS:~# poweroff
esOS:~# reboot

The init process stops all programs, writes pending data, and unmounts every mounted file system in reverse order before it turns the computer off, so mounted USB sticks are safe to remove afterwards. Ctrl+Alt+Del performs a clean reboot.

Troubleshooting

The screen stays black after the boot menu

Check that the processor supports x86-64-v3 (Intel Haswell, AMD Excavator/Zen or newer). If it does, choose safe mode in the boot menu; it turns off the IOMMU and kernel mode setting.

The computer refuses to boot the stick

Turn Secure Boot off in the firmware settings. On UEFI computers the boot menu has an entry that opens the firmware settings.

Letters appear as symbols after printing a file

Printing an encrypted or other binary file to the console (cat file.enc) sends control characters to the screen. esOS repairs the console at the next prompt. To look inside such a file, use less file.enc or od -c file.enc | less.

Automatic keyboard detection picks the wrong layout

Some punctuation keys are placed differently on Apple keyboards. Choose the layout from the keyboard_setup menu instead.