Documentation

Everything you need to know about installing, configuring, and using Zraxyl OS

Quick Navigation

Getting Started

This guide assumes you have basic knowledge of Linux systems and command-line usage.

Welcome to Zraxyl OS! This comprehensive documentation will guide you through installation, configuration, and usage of our custom Linux distribution.

🚀 Installation Guides

Complete guides for different installation types and desktop environments.

📦 Metapackages

Learn about our metapackage system and available desktop environments.

  • • Desktop Environments
  • • Fonts & Drivers
  • • Development Tools

🗃️ Repositories

Information about stable and staging repositories.

  • • Stable Repositories
  • • Staging Repositories
  • • Repository Configuration

System Requirements

Minimum Requirements

  • 2GB RAM (4GB for Desktop)
  • 20GB disk space (40GB recommended)
  • x86_64 or ARM64 processor
  • UEFI or BIOS boot support
  • Network connection for installation

Recommended

  • 8GB+ RAM (16GB for development)
  • 100GB+ SSD storage
  • Modern multi-core processor
  • UEFI with Secure Boot support
  • Dedicated graphics card (optional)

Supported Hardware

ComponentSupportedNotes
CPUIntel Core i3+, AMD Ryzen 3+, ARM Cortex-A72+64-bit required
GPUIntel HD, AMD Radeon, NVIDIA GeForceOpen source drivers preferred
NetworkEthernet, Wi-Fi 802.11n+, Bluetooth 4.0+Most chipsets supported
StorageSATA, NVMe, eMMC, USB 3.0+RAID 0/1/5/10 supported

Installation

Step 1: Download and Create Installation Media

Download ISO
Verify Checksum
Create Bootable USB
Boot from USB
curl -O https://releases.zraxyl.org/latest/zraxyl-server-x64.iso
sha256sum zraxyl-server-x64.iso
dd if=zraxyl-server-x64.iso of=/dev/sdX bs=4M status=progress
Replace /dev/sdX with your actual USB device path. This will erase all data on the USB drive!

Step 2: Boot and Install

  1. Boot from the USB drive
  2. Select "Install Zraxyl OS" from the boot menu
  3. Follow the graphical installer prompts
  4. Configure disk partitioning
  5. Set up user account and password
  6. Wait for installation to complete
  7. Reboot and remove installation media

Initial Configuration

First Boot Setup

After your first boot, run the initial configuration wizard:

sudo zraxyl-setup

This will guide you through:

  • Network configuration
  • Package manager setup
  • Security hardening options
  • Desktop environment selection (if applicable)

Base Installation (CLI)

This is a CLI-based installation similar to Arch Linux. LiveOS changes are only applied temporarily in RAM.

Default Credentials

Username: root    | Password: toor
Username: zraxyl  | Password: zraxyl

Step 1: Update System

bottle -Syu

Step 2: Partitioning

We'll use parted for partitioning. Example uses /dev/sdb (adjust for your drive):

parted /dev/sdb
print                                    # Check existing partitions
mklabel gpt                              # Set partition table to GPT
mkpart primary fat32 1MB 1024MB         # Create ESP partition (1GB)
set 1 esp on                            # Enable ESP flag
mkpart primary ext4 1024MB 100%         # Create root partition
quit                                     # Exit parted

Step 3: Formatting

mkfs -t vfat /dev/sdb1                   # Format ESP partition
mkfs -t ext4 /dev/sdb2                   # Format root partition
e2label /dev/sdb2 zraxyl                 # Label root partition

Step 4: Mounting

mount /dev/sdb2 /mnt                     # Mount root partition
mkdir -vp /mnt/boot                      # Create boot directory
mount /dev/sdb1 /mnt/boot                # Mount ESP partition

Step 5: Base System Installation

cd /
base-strap /mnt base-system              # Install base system
base-chroot /mnt                         # Enter chroot environment

Step 6: System Configuration

systemctl enable dhcpcd                  # Enable network on boot
systemctl enable getty@tty1              # Enable login TTY
systemctl enable getty@tty2              # Enable secondary TTY

Step 7: Bootloader Setup

dbus-uuidgen > /etc/machine-id           # Create machine ID
bootctl install                          # Install systemd-boot
passwd root                              # Set root password

Step 8: Boot Configuration

Install nano first, then configure the bootloader:

bottle -Sy nano
nano /boot/loader/loader.conf

Add this content to loader.conf:

default  zraxyl
timeout  4
console-mode max
editor   no

Create boot entry:

nano /boot/loader/entries/zraxyl.conf

Add this content (check /boot for kernel version):

title Zraxyl
linux /vmlinuz-zraxyl
initrd /initramfs-VERSION.img
options root=LABEL=zraxyl rw audit=0

Step 9: User Creation

bottle -Sy sudo                         # Install sudo
mkdir /home/user                        # Create home directory
useradd user --home /home/user/          # Add user
passwd user                              # Set user password

Step 10: Final Steps

exit                                     # Exit chroot
sync                                     # Sync changes to disk
umount -l /mnt/boot                      # Unmount boot partition
umount -l /mnt                          # Unmount root partition
reboot                                   # Reboot to installed system

Desktop Environments

Zraxyl OS supports multiple desktop environments. After completing the base installation, you can install any desktop environment using metapackages.

🖥️ KDE Plasma Desktop

Full Experience Available

Install the complete KDE Plasma desktop environment with all features:

# Full plasma desktop environment with extras
bottle -Sy base-desktop-plasma
# OR install minimal plasma variant
bottle -Sy base-desktop-plasma-clean

Post-Installation Setup:

# Install sudo for user management
bottle -Sy sudo
# Add new user with necessary groups
useradd zraxyl -m -G wheel,adm
# Set password for the new user
passwd zraxyl
You need to enable sudo for the wheel group by editing /etc/sudoers
# Edit sudoers file
nano /etc/sudoers
# Find and uncomment: %wheel ALL=(ALL) ALL
# Use Ctrl+W to search for "User privilege specification"
# Navigate and remove "# " from the wheel line
# Save with Ctrl+X, then Y, then Enter
reboot

🪟 XFCE4 Desktop

Lightweight & Fast

Install the XFCE4 desktop environment with custom theming and optimizations:

# Install XFCE4 desktop with extras
bottle -Sy base-desktop-xfce4 --disable-download-timeout
# Install display manager
bottle -Sy lightdm
# Install Xorg drivers (required for input devices)
bottle -Sy drivers-xorg

Enable Services:

# Enable LightDM display manager
systemctl enable lightdm
# Reboot to start the desktop environment
reboot

📦 Metapackages

Zraxyl uses metapackages to simplify installation of complete desktop environments and system components. These packages automatically install and configure all necessary components.

Available Desktop Metapackages:

PackageDescriptionVariant
base-desktop-plasmaComplete KDE Plasma environment with extra packagesFull Experience
base-desktop-plasma-cleanMinimal KDE Plasma with only core packagesMinimal
base-desktop-xfce4XFCE4 with custom theming and user-friendly extrasFull Experience
base-desktop-xfce4-cleanCore XFCE4 desktop with minimal packagesMinimal

System Components:

Xorg Drivers

Complete Xorg driver collection:

drivers-xorg
Included Drivers

Graphics: Intel, NVIDIA (Nouveau), AMD, QEMU, VirtualBox

Input: libinput, evdev, synaptics, wacom

Other: fbdev, vesa, vmware

Base Fonts

Essential font collection:

base-fonts
Included Fonts

DejaVu, Liberation, Droid, Hack, Noto, Cantarell, Bitstream Vera

🗃️ Package Repositories

Zraxyl OS uses multiple specialized repositories to organize packages by category and stability level.

🟢 Stable Repositories

Default for all users

These repositories are enabled by default and contain tested, stable packages.

core
extra
kde
xfce
gnome
games
python
perl
server
pentest
proprietary
cross_tools
Repository Configuration
[core]
Server = http://files.zraxyl.eu/repo/stable/amd64/$repo/packages/
SigLevel = Optional TrustAll

🟡 Staging Repositories

For developers & testers

These repositories contain newer, potentially unstable packages for testing purposes.

Not recommended for typical users - packages may be broken or unstable

Same repository structure as stable, but with development versions.

Staging Configuration
[core]
Server = http://files.zraxyl.eu/repo/staging/amd64/$repo/packages/
SigLevel = Optional TrustAll

Security Features

Zraxyl OS is designed with security as a top priority, featuring multiple layers of protection.

System Hardening

  • Kernel: Hardened kernel with KASLR, SMEP, SMAP
  • Memory: Stack canaries, DEP/NX bit, ASLR
  • Filesystem: Mandatory Access Control (MAC)
  • Network: Built-in firewall with sensible defaults

Encryption & Authentication

  • Disk: Full disk encryption with LUKS2
  • Boot: Secure Boot with custom keys
  • Auth: PAM with 2FA support
  • Network: WireGuard VPN integration

Security Tools

zraxyl-security-audit              # Run security audit
zraxyl-firewall-config             # Configure firewall
zraxyl-encrypt-home                # Encrypt home directory
zraxyl-vuln-scan                   # Vulnerability scanner

Package Management

Bottle Package Manager

Zraxyl OS uses bottle - a rebranded Pacman with custom makepkg scripts. Every package is written and compiled by the Zraxyl team.
CommandDescriptionExample
bottle -SyuUpdate system and upgrade packagesbottle -Syu
bottle -S <package>Install a packagebottle -S firefox
bottle -R <package>Remove a packagebottle -R firefox
bottle -Ss <term>Search for packagesbottle -Ss "text editor"
bottle -SySynchronize package databasebottle -Sy
bottle -Si <package>Show package informationbottle -Si firefox
bottle -QList installed packagesbottle -Q | grep dev
bottle -ScClean package cachebottle -Sc

Custom Package Development

🛠️ Built from Scratch

Every package in Zraxyl OS is:

  • Written by Zraxyl team: Custom build scripts and configurations
  • Compiled in-house: All packages built from source with optimizations
  • Quality assured: Tested and validated before repository inclusion
  • Pacman-compatible: Uses familiar Pacman syntax with bottle command
Unlike other distributions that repackage existing software, Zraxyl creates each package with custom makepkg scripts tailored for optimal performance.

Troubleshooting

System won't boot after installation

Check UEFI/BIOS settings and ensure Secure Boot is properly configured. Try booting in legacy mode if UEFI fails.

Network connectivity issues

Check network interface status with ip addr and configure using zraxyl-network-config.

Package installation fails

Run zpkg update first, then try installing again. Check available disk space and network connectivity.

Development Environment

Zraxyl OS comes with a comprehensive development environment. Install additional tools as needed:

zpkg install zraxyl-dev-tools      # Essential development tools
zpkg install docker kubernetes     # Container orchestration
zpkg install nodejs python rust   # Programming languages
zpkg install vscode sublime-text   # Code editors

Development Environment Setup

bottle -Sy base-devel                   # Install development tools
bottle -Sy git cmake ninja              # Version control and build tools
bottle -Sy gcc rust python              # Compilers and interpreters

🏗️ Custom Build System

  • Custom makepkg scripts for each package
  • Zraxyl-specific optimizations and patches
  • Integrated quality assurance testing
  • Automated dependency resolution

📦 Package Development

  • Source-based compilation for all packages
  • Custom configuration for Zraxyl compatibility
  • Performance tuning and security hardening
  • Comprehensive testing before release

Contributing to Zraxyl

We welcome contributions to package development and system improvements:

Join Community
Learn Build System
Submit Package
Code Review
Integration
# Contact the team via Telegram for contribution guidelines
# All packages must follow Zraxyl build standards
# Custom makepkg scripts ensure consistency and quality
Please read our Contributing Guidelines and Code of Conduct before submitting contributions.