diff options
Diffstat (limited to 'src/docs/install.txt')
| -rw-r--r-- | src/docs/install.txt | 697 |
1 files changed, 407 insertions, 290 deletions
diff --git a/src/docs/install.txt b/src/docs/install.txt index 50ad008..f7a6881 100644 --- a/src/docs/install.txt +++ b/src/docs/install.txt @@ -1,364 +1,481 @@ -1 Installation -************** + ________________________________ -These are the step-by-step instructions for installing Carbs Linux. + CARBS LINUX INSTALLATION GUIDE -1.1 Preparing Environment -========================= + Cem Keylan + ________________________________ -To install Carbs Linux, you will need a Live Linux ISO. For that -purpose, you can obtain a Gentoo or Void Linux live image. You can -follow their instructions to boot and setup your network. - You will need the following programs in order to install Carbs Linux: +Table of Contents +_________________ - * tar - * wget - * xz - * some form of base utilities (coreutils, sbase, busybox, etc.) +1. Preparing Environment +.. 1. Download +.. 2. Signature verification +.. 3. Extracting the tarball +.. 4. Obtain the chroot helper +2. Chroot +.. 1. Setting up repositories +..... 1. Obtaining from git +..... 2. Obtaining from rsync +..... 3. Making the package manager use the repositories +.. 2. Updating packages +.. 3. Installing packages +.. 4. Essential Software +.. 5. Obtaining the documentation +3. System Configuration +.. 1. Configuring hostname +.. 2. Hosts file +4. Kernel +.. 1. Obtaining the kernel sources +.. 2. Kernel dependencies +.. 3. Building the kernel +5. Making your system bootable +.. 1. Bootloader +..... 1. GRUB BIOS installation +..... 2. GRUB UEFI installation +.. 2. Init scripts +.. 3. Fstab +6. Post-installation +.. 1. KISS repositories - Rest of these instructions will assume that you have set all of these -up, and will continue on that point. -1.1.1 Download --------------- +These are the step-by-step instructions for installing Carbs Linux. It +can be acquired as plain-text to be viewed offline with a pager from +<https://carbslinux.org/docs/install.txt>. -First, we need to download the rootfs tarball. You can do the following -in order to obtain the rootfs. If you are using an i686 machine, -replace the 'x86_64' with 'i686'. We are setting this in a URL variable -so that we don't have to write it every time. - $ URL=https://dl.carbslinux.org/releases/x86_64 - $ wget $URL/carbs-rootfs.tar.xz +1 Preparing Environment +======================= - We can then check the integrity of the tarball and do a signature -verification. Even thought these are optional, they are highly -recommended. + To install Carbs Linux, you will need a Live Linux ISO. For that + purpose, you can obtain a Gentoo or Void Linux live image. You can + follow their instructions to boot and setup your network. -1.1.2 Check the integrity of the tarball (Recommended) ------------------------------------------------------- + You will need the following programs in order to install Carbs Linux: -All of the releases are saved in a single file named 'sha256sums.txt', -but the latest release is saved on 'carbs-rootfs.tar.xz.sha256'. You -can acquire and verify the tarball. + - tar + - wget + - xz + - some form of base utilities (coreutils, sbase, busybox, etc.) - $ wget $URL/carbs-rootfs.tar.xz.sha256 - $ sha256sum -c carbs-rootfs.tar.xz.sha256 + Rest of these instructions will assume that you have set all of these + up, and will continue on that point. -1.1.3 Verify the signature + +1.1 Download +~~~~~~~~~~~~ + + First, we need to download the rootfs tarball. You can do the + following in order to obtain the rootfs. If you are using an i686 + machine, replace the `x86_64' with `i686'. We are setting this in a + URL variable so that we don't have to write it every time. + + ,---- + | wget $URL/carbs-rootfs.tar.xz.sha256 + | sha256sum -c carbs-rootfs.tar.xz.sha256 + `---- + + +1.2 Signature verification +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + It is highly recommended to verify the signature of the tarball. You + will need GPG for this. + + ,---- + | wget $URL/carbs-rootfs.tar.xz.sig + | gpg --recv-keys FF484BDFEFCEF8FF + | gpg --verify carbs-rootfs.tar.xz.sig + `---- + + +1.3 Extracting the tarball +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + You will need to extract the tarball to your desired location. For + partitioning, you can follow [this guide]. This will assume that you + will be mounting your root partition to `/mnt'. + + ,---- + | mount /dev/sdx1 /mnt + | tar xf carbs-rootfs.tar.xz -C /mnt + `---- + + +[this guide] <https://wiki.archlinux.org/index.php/Partitioning> + + +1.4 Obtain the chroot helper +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + You can obtain the `cpt-chroot' script in order to do a simple chroot + into your new root filesystem. + + ,---- + | wget https://dl.carbslinux.org/distfiles/cpt-chroot + | chmod a+x cpt-chroot + `---- + + +2 Chroot +======== + + Chroot into Carbs Linux! + + ,---- + | ./cpt-chroot /mnt + `---- + + +2.1 Setting up repositories +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Newest tarballs do not come with repositories, so you will need to + manually obtain them, and set your `CPT_PATH' environment + variable. Carbs Linux repositories can either be obtained by `git' or + `rsync'. While rsync repositories are overall faster and smaller, git + offers the whole history of the repository and a means to manipulate + your repository as you like it. If you want to obtain the git + repository, you will need to install `git' itself. + + The following guide will assume that you put the repositories into + `~/repos/' directory, but you can put the repositories into any + directory you want. So go ahead and create that directory: + + ,---- + | mkdir -p $HOME/repos + `---- + + +2.1.1 Obtaining from git +------------------------ + + Carbs Linux git repositories can be found both from the main server + and GitHub (mirror). Here are both their repository links. You can + clone any of them. + + - git://git.carbslinux.org/repository + - <https://github.com/carbslinux/repository> + + ,---- + | git clone git://git.carbslinux.org/repository $HOME/repos/carbs + `---- + + +2.1.2 Obtaining from rsync -------------------------- -It is highly recommended to verify the signature of the tarball. You -will need GPG for this. + Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In + order to obtain it, run the following: - $ wget $URL/carbs-rootfs.tar.xz.sig - $ gpg --recv-keys FF484BDFEFCEF8FF - $ gpg --verify carbs-rootfs.tar.xz.sig + ,---- + | rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs + `---- -1.1.4 Extracting the tarball ----------------------------- -You will need to extract the tarball to your desired location. For -partitioning, you can follow this guide -(https://wiki.archlinux.org/index.php/Partitioning). This will assume -that you will be mounting your root partition to '/mnt'. +2.1.3 Making the package manager use the repositories +----------------------------------------------------- - $ mount /dev/sdx1 /mnt - $ tar xf carbs-rootfs.tar.xz -C /mnt + In your shell's configuration file, or in your `~/.profile' file, add + the following lines: -1.1.5 Obtain the chroot helper ------------------------------- + ,---- + | CPT_PATH=$HOME/repos/carbs/core + | CPT_PATH=$CPT_PATH:$HOME/repos/carbs/extra + | CPT_PATH=$CPT_PATH:$HOME/repos/carbs/xorg + | CPT_PATH=$CPT_PATH:$HOME/repos/carbs/community + | export CPT_PATH + `---- -You can obtain the 'cpt-chroot' script in order to do a simple chroot -into your new root filesystem. - $ wget https://dl.carbslinux.org/distfiles/cpt-chroot - $ chmod a+x cpt-chroot +2.2 Updating packages +~~~~~~~~~~~~~~~~~~~~~ -1.2 Chroot -========== + It is good practice to make sure your system is up to date, especially + before building new packages. If there is an update for the package + manager you will need to update twice. -Chroot into Carbs Linux! + ,---- + | cpt-update && cpt-update + `---- - $ ./cpt-chroot /mnt -1.2.1 Setting up repositories ------------------------------ +2.3 Installing packages +~~~~~~~~~~~~~~~~~~~~~~~ -Newest tarballs do not come with repositories, so you will need to -manually obtain them, and set your 'CPT_PATH' environment variable. -Carbs Linux repositories can either be obtained by 'git' or 'rsync'. -While rsync repositories are overall faster and smaller, git offers the -whole history of the repository and a means to manipulate your -repository as you like it. If you want to obtain the git repository, -you will need to install 'git' itself. + Since you are operating on a really small base, you might need to + build and install new programs to extend the functionality of your + system. In order to build and install packages new packages in Carbs, + you need to execute the following. "Package" is not actually a package + and is given as an example. - The following guide will assume that you put the repositories into -'~/repos/' directory, but you can put the repositories into any -directory you want. So go ahead and create that directory: + ,---- + | cpt-build package + | cpt-install package + `---- - $ mkdir -p $HOME/repos -1.2.1.1 Obtaining from rsync -............................ +2.4 Essential Software +~~~~~~~~~~~~~~~~~~~~~~ -Carbs Linux rsync repositories live in <rsync://carbslinux.org/repo>. -In order to obtain it, run the following: + Here is a list of software that you might want to have on your system. - $ rsync -avc rsync://carbslinux.org/repo $HOME/repos/carbs + *BOOTLOADERS* -1.2.1.2 Obtaining from git -.......................... + - efibootmgr + - grub -Carbs Linux git repositories can be found both from the main server and -GitHub (mirror). Here are both their repository links. You can clone -any of them. + *FILESYSTEMS* - * <git://git.carbslinux.org/repository> - * <https://github.com/carbslinux/repository> + - e2fsprogs + - dosfstools + - ntfs-3g - $ git clone git://git.carbslinux.org/repository $HOME/repos/carbs + *NETWORKING* -1.2.1.3 Making the package manager use the repositories -....................................................... + - dhcpcd + - wpa_supplicant -In your shell's configuration file, or in your '~/.profile' file, add -the following lines: + *TEXT EDITORS* - export CPT_PATH='' - CPT_PATH=$CPT_PATH:$HOME/repos/carbs/core - CPT_PATH=$CPT_PATH:$HOME/repos/carbs/extra - CPT_PATH=$CPT_PATH:$HOME/repos/carbs/xorg - CPT_PATH=$CPT_PATH:$HOME/repos/carbs/community - export CPT_PATH + - nano + - vim + - neatvi + - emacs + - emacs-nox (terminal-only version of emacs) -1.2.2 Updating packages ------------------------ + *USER SHELLS* -It is good practice to make sure your system is up to date, especially -before building new packages. If there is an update for the package -manager you will need to update twice. + - bash + - zsh + - oksh + - rc - $ cpt update + *POSIX BASE UTILITIES* -1.2.3 Installing packages -------------------------- + - busybox + - sbase + - coreutils -Since you are operating on a really small base, you might need to build -and install new programs to extend the functionality of your system. In -order to build and install packages new packages in Carbs, you need to -execute the following. "Package" is not actually a package and is given -as an example. + *DOCUMENTATION* - $ cpt build package - $ cpt install package + - carbs-docs + - man-pages + - man-pages-posix -1.2.4 Essential Software ------------------------- -Here is a list of software that you might want to have on your system. - - BOOTLOADERS - * efibootmgr - * grub - FILESYSTEMS - * e2fsprogs - * dosfstools - * ntfs-3g - NETWORKING - * dhcpcd - * wpa_supplicant - TEXT EDITORS - * nano - * vim - * neatvi - * nvi - * emacs - * emacs-nox (terminal-only version of emacs) - USER SHELLS - * bash - * zsh - * dash - * oksh - * rc - POSIX BASE UTILITIES - * busybox - * sbase - * coreutils - DOCUMENTATION - * carbs-docs - * man-pages - * man-pages-posix - -1.2.5 Obtaining the documentation (optional) --------------------------------------------- - -All the documentation for Carbs Linux can be found on a single info -manual to be viewed offline. You can obtain texinfo or the info -(standalone) package in order to view the documentation. - - Install the documentation. - $ cpt b carbs-docs && cpt i carbs-docs - - Install either texinfo or the info package. We will be installing standalone info - as it doesn't need perl. - $ cpt b info && cpt i info - - You can then run info and navigate through the documentation. - $ info carbslinux - -1.3 System Configuration -======================== - -After you have finished installing some extra packages, you can -configure your system to your liking. - -1.3.1 Configuring hostname (recommended) ----------------------------------------- - -You might want to add a hostname, especially in a networked environment. -Your hostname will default to 'carbslinux' unless you set this. - - $ echo your-hostname > /etc/hostname - -1.3.2 Setting up hosts file (optional) --------------------------------------- - -You can edit your /etc/hosts file, which is the static lookup table for -host names. By default, there are two entries for localhost which are -OKAY. You can replace the 'localhost' part of these entries to your -hostname. - - 127.0.0.1 localhost.localdomain localhost - ::1 localhost.localdomain localhost ip6-localhost - -1.4 Kernel -========== - -Kernel isn't managed under the main repositories, even though you could -package one for your personal use. Here is an example kernel package -(https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux), -which you will need to reconfigure for your specific setup if you want -to make use of it. - -1.4.1 Obtaining the kernel sources ----------------------------------- - -You can visit the https://kernel.org website to choose a kernel that you -want to install. Though only the latest stable and longterm (LTS) -versions are supported. - - Download the kernel and extract it - $ wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.7.6.tar.xz - $ tar xf linux-5.7.6.tar.xz - - Change directory into the kernel sources - $ cd linux-5.7.6 - -1.4.2 Installing dependencies ------------------------------ - -In order to compile the kernel you will need to install some -dependencies. You will need 'libelf' to compile the kernel. If you -want to configure using the menu interface you will also need 'ncurses'. - - The package manager asks to install if you are building more than one package, - so no need to run 'cpt i ...' - $ cpt b libelf ncurses - - In the vanilla kernel sources, you need perl to compile the kernel, -but it can be easily patched out. You will need to apply the following -patch. Patch was written by E5ten (https://github.com/E5ten). You will -need to obtain and apply the patch in the kernel source directory. - - $ wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch - $ patch -p1 < kernel-no-perl.patch +2.5 Obtaining the documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -1.4.3 Compiling the kernel --------------------------- + All the documentation for Carbs Linux can be found on a single info + manual to be viewed offline. You can obtain texinfo or the info + (standalone) package in order to view the documentation. -Next step is configuring and building the kernel. You can check -Gentoo's kernel configuration guide -(https://wiki.gentoo.org/wiki/Kernel/Configuration) to learn more about -the matter. Overall, Gentoo Wiki is a good place to learn about -configuration according to your hardware. The following will assume a -monolithic kernel. + ,---- + | # Install the documentation. + | cpt b carbs-docs && cpt i carbs-docs + | + | # Install either texinfo or the info package. We will be installing standalone info + | # as it doesn't need perl. + | cpt b info && cpt i info + | + | # You can then run info and navigate through the documentation. + | info carbslinux + `---- - $ make menuconfig - $ make - $ install -Dm755 $(make -s image_name) /boot/vmlinuz-linux -1.5 Making your system bootable -=============================== +3 System Configuration +====================== -In order to be able to boot your fresh system, wou will need an -init-daemon, init-scripts and a bootloader. The init daemon is already -provided by busybox, but you can optionally change it. + After you have finished installing some extra packages, you can + configure your system to your liking. -1.5.1 Installing a bootloader ------------------------------ -In the main repository, there is efibootmgr and grub to serve as -bootloaders. efibootmgr can be used as a standalone bootloader, or can -be used to install grub in a UEFI environment. efibootmgr is needed -unless you are using a device without UEFI support (or you really want -to use BIOS for a reason). +3.1 Configuring hostname +~~~~~~~~~~~~~~~~~~~~~~~~ - GRUB BIOS installation + You might want to add a hostname, especially in a networked + environment. Your hostname will default to 'carbslinux' unless you set + this. - $ cpt b grub && cpt i grub - $ grub-install --target=i386-pc /dev/sdX - $ grub-mkconfig -o /boot/grub/grub.cfg + ,---- + | echo your-hostname > /etc/hostname + `---- - GRUB UEFI installation - $ cpt b efibootmgr && cpt i efibootmgr - $ cpt b grub && cpt i grub +3.2 Hosts file +~~~~~~~~~~~~~~ + + You can edit your /etc/hosts file, which is the static lookup table + for host names. By default, there are two entries for localhost which + are OKAY. You can replace the 'localhost' part of these entries to + your hostname. + + ,---- + | 127.0.0.1 localhost.localdomain localhost + | ::1 localhost.localdomain localhost ip6-localhost + `---- + + +4 Kernel +======== + + Kernel isn't managed under the main repositories, even though you + could package one for your personal use. Here is an [example kernel + package], which you will need to reconfigure for your specific setup + if you want to make use of it. + + +[example kernel package] +<https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux> + +4.1 Obtaining the kernel sources +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + You can visit the <https://kernel.org> website to choose a kernel that + you want to install. Though only the latest stable and longterm (LTS) + versions are supported. + + ,---- + | # Download the kernel and extract it + | wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz + | tar xf linux-5.9.1.tar.xz + | + | # Change directory into the kernel sources + | cd linux-5.9.1 + `---- + + +4.2 Kernel dependencies +~~~~~~~~~~~~~~~~~~~~~~~ + + In order to compile the kernel you will need to install some + dependencies. You will need `libelf' to compile the kernel. If you + want to configure using the menu interface you will also need + `ncurses'. + + ,---- + | # The package manager asks to install if you are building more than one package, + | # so no need to run 'cpt i ...' + | cpt b libelf ncurses + `---- + + In the vanilla kernel sources, you need perl to compile the kernel, + but it can be easily patched out. You will need to apply the following + patch. Patch was written by [E5ten]. You will need to obtain and apply + the patch in the kernel source directory. + + ,---- + | wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch + | patch -p1 < kernel-no-perl.patch + `---- + + +[E5ten] <https://github.com/E5ten> + + +4.3 Building the kernel +~~~~~~~~~~~~~~~~~~~~~~~ + + Next step is configuring and building the kernel. You can check + Gentoo's [kernel configuration guide] to learn more about the + matter. Overall, Gentoo Wiki is a good place to learn about + configuration according to your hardware. The following will assume a + monolithic kernel. + + ,---- + | make menuconfig + | make + | install -Dm755 $(make -s image_name) /boot/vmlinuz-linux + `---- + + +[kernel configuration guide] +<https://wiki.gentoo.org/wiki/Kernel/Configuration> + + +5 Making your system bootable +============================= + + In order to be able to boot your fresh system, wou will need an + init-daemon, init-scripts and a bootloader. The init daemon is already + provided by busybox, but you can optionally change it. + + +5.1 Bootloader +~~~~~~~~~~~~~~ + + In the main repository, there is efibootmgr and grub to serve as + bootloaders. efibootmgr can be used as a standalone bootloader, or + can be used to install grub in a UEFI environment. efibootmgr is + needed unless you are using a device without UEFI support (or you + really want to use BIOS for a reason). + + +5.1.1 GRUB BIOS installation +---------------------------- + + ,---- + | cpt b grub && cpt i grub + | grub-install --target=i386-pc /dev/sdX + | grub-mkconfig -o /boot/grub/grub.cfg + `---- + + +5.1.2 GRUB UEFI installation +---------------------------- - $ grub-install --target=x86_64-efi \ - --efi-directory=esp \ - --bootloader-id=CarbsLinux + ,---- + | cpt b efibootmgr && cpt i efibootmgr + | cpt b grub && cpt i grub + | + | grub-install --target=x86_64-efi \ + | --efi-directory=esp \ + | --bootloader-id=CarbsLinux + | + | grub-mkconfig -o /boot/grub/grub.cfg + `---- - $ grub-mkconfig -o /boot/grub/grub.cfg -1.5.2 Installing init scripts ------------------------------ +5.2 Init scripts +~~~~~~~~~~~~~~~~ -Only thing left to do is installing the init-scripts, and now you are -almost ready to boot your system! + Only thing left to do is installing the init-scripts, and now you are + almost ready to boot your system! - $ cpt b carbs-init && cpt i carbs-init + ,---- + | cpt b carbs-init && cpt i carbs-init + `---- -1.5.3 Generating fstab ----------------------- -You can now manually edit your fstab entry, or you can use the genfstab -tool. If you want to use the tool, exit the chroot and run the -following: +5.3 Fstab +~~~~~~~~~ - $ wget https://github.com/cemkeylan/genfstab/raw/master/genfstab - $ chmod +x genfstab - $ ./genfstab -U /mnt >> /mnt/etc/fstab + You can now manually edit your fstab entry, or you can use the + genfstab tool. If you want to use the tool, exit the chroot and run + the following: -1.6 Post-installation -===================== + ,---- + | wget https://github.com/cemkeylan/genfstab/raw/master/genfstab + | chmod +x genfstab + | ./genfstab -U /mnt >> /mnt/etc/fstab + `---- -The base installation is now complete, you can now fine tune your system -according to your needs. Rest of these instructions are completely -optional. -1.6.1 Acquiring kiss repositories ---------------------------------- +6 Post-installation +=================== -While not 100% compatible with cpt, you can use kiss repositories in -your system the same way you are using the distribution repositories. -Here is an example for the KISS Linux Community repository. + The base installation is now complete, you can now fine tune your + system according to your needs. Rest of these instructions are + completely optional. You can check the rest of the documentation to + learn more about the system. - $ git clone https://github.com/kisslinux/community $HOME/repos/kiss-community - $ export CPT_PATH=$CPT_PATH:$HOME/repos/kiss-community/community - NOTE: There are lots of packages on the KISS community repository -that are also on Carbs Linux main repository. I would advise giving -lower priority to the KISS community repository as it may affect other -packages that you might install. +6.1 KISS repositories +~~~~~~~~~~~~~~~~~~~~~ + While not 100% compatible with cpt, you can use kiss repositories in + your system the same way you are using the distribution + repositories. Here is an example for the KISS Linux Community + repository. |